UAS api Endpoints
Authorization/Authentication
The authorization endpoint can be used to request either access tokens or authorization codes (implicit and authorization code flow). You either use a web browser or a web view to start the process.
• client_id (required)
Identifier of the client
• scope (required)
One or more registered scopes
• redirect_uri (required)
must match exactly one of the allowed redirect URIs for that client
• response_type (required)
code requests an authorization codetoken requests an access token (only resource scopes are allowed)id_token token requests an identity token and an access token (both resource and identity scopes are allowed)• response_mode (optional)
form_post sends the token response as a form post instead of a fragment encoded redirect
• state (recommended)
Unified Authentication Service will echo back the state value on the token response, this is for correlating request and response.
• nonce (required for identity tokens using implicit flow)
Unified Authentication Service will echo back the nonce value in the identity token, this is for correlating the token to the request).
• prompt (optional)
none no UI will be shown during the request. If this is not possible (e.g. because the user has to sign in or consent) an error is returnedlogin the login UI will be shown, even if the user is already signed-in and has a valid session• code_challenge (required when using proof keys)
Sends the code challenge for proof key flows.
• code_challenge_method (optional - default to plain when using proof key )
plain indicates that the challenge is using plain text (not recommended)S256 indicates the challenge is hashed with SHA256• login_hint (optional)
Can be used to pre-fill the username field on the login page.
• ui_locales (optional)
Gives a hint about the desired display language of the login UI
• max_age (optional)
If the user's logon session exceeds the max age (in seconds), the login UI will be shown
acr_values (optional)Allows to pass additional authentication related information to the user service - there are also values with special meaning:
idp:name_of_idp bypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration)tenant:name_of_tenant can be used to pass a tenant name to the user serviceExample (URL encoding removed for readability)
GET /connect/authorize?client_id=client1&scope=openid email api1&response_type=id_token token
Token
The token endpoint can be used to programmatically request or refresh tokens (resource owner password credential flow, authorization code flow, client credentials flow and custom grant types).
• grant_type (required)
authorization_code client_credentialsPasswordrefresh_token custom• scope (required for all grant types besides refresh_token and code)
• redirect_uri (required for code grant type)
• code (required for code grant)
• code_verifier (required when using proof keys - added in v2.5)
• username (required for password grant type)
• password (required for password grant_type)
• acr_values (allowed for password grant type to pass additional information to user service)
Values with special meaning:
idp:name_of_idp bypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration)tenant:name_of_tenant can be used to pass extra information to the user service• refresh_token (required for refresh token grant)
• client_id (either in the post body, or as a basic authentication header)
• client_secret (either in the post body, or as a basic authentication header)
Authentication
All requests to the token endpoint must be authenticated - either pass client id and secret via Basic Authentication or add client_id and client_secret fields to the POST body.
Example: (Form-encoding removed and line breaks added for readability)
POST /connect/token
Authorization: Basic abcxyz
grant_type=authorization_code&code=hdh922&redirect_uri=https://myapp.com/callback
UserInfo
The UserInfo endpoint can be used to retrieve identity information about a subject. It requires a valid access token with at least the “openid” scope.
Example:
GET /connect/userinfo
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/json
{
"sub": "248289761001",
"name": "Bob Smith",
"given_name": "Bob",
"family_name": "Smith",
"role": [
"user",
"admin"
]
}
Discovery Endpoint
The discovery endpoint can be used to retrieve metadata about Unified Authentication Service - it returns information like the issuer name, key material, supported scopes etc.
Example:
GET /.well-known/openid-configuration
Logout Endpoint
Redirecting to the logout endpoint clears the authentication session and cookie.
You can pass the following optional parameters to the endpoint:
• id_token_hint
The id_token that the client retrieved during authentication. This allows bypassing the logout confirmation screen as well as providing a post logout redirect URL
• post_logout_redirect_uri
A URI that Unified Authentication Service can redirect to after logout (by default a link is displayed). The URI must be in the list of allowed post logout URIs for the client.
/connect/endsession?id_token_hint=...&post_logout_redirect_uri=https://myapp.com
See the Authentication options section to configure the behavior of logout endpoint and logout page.
Token Revocation
This endpoint allows revoking access tokens (reference tokens only) and refresh token. It implements the token revocation specification.
Supported parameters:
• token (required)
The token to revoke
client_id (required)
client_secret (required)
• token_type_hint
Either access_token or refresh_token
Introspection Endpoint
The introspection endpoint is an implementation of RFC 7662.
It can be used to validate reference tokens (or JWTs if the consumer does not have support for appropriate JWT or cryptographic libraries).
The introspection endpoint requires authentication using a scope credential (only scopes that are contained in the access token are allowed to introspect the token).
Example:
POST /connect/introspect
Authorization: Basic xxxyyy
token=<token>
A successful response returns a status code of 200 and either an active or inactive token:
{
"active": true,
"sub": "123"
}
Unknown or expired tokens are marked as inactive:
{
"active": false,
}
An invalid request returns a 400 or a 401 if the scope is not authorized.
Note:
The introspection endpoint replaces the old access token validation endpoint. Since the introspection endpoint requires authentication, it adds privacy features to reference tokens, which were not available previously. The access token validation endpoint still exists, but it is recommended to disable it and use the introspection endpoint instead.
Access token validation endpoint
The access token validation endpoint can be used to validate reference tokens. It can be also used to validate self-contained JWTs if the consumer does not have support for appropriate JWT or cryptographic libraries.
You can either GET or POST to the validation endpoint. Due to query string size restrictions, POST is recommended.
Example:
POST /connect/accesstokenvalidation
token=<token>
or
GET /connect/accesstokenvalidation?token=<token>
A successful response returns a status code of 200 and the associated claims for the token.
An unsuccessful response returns a 400 with an error message.
It is also possible to pass a scope that is expected to be inside the token:
POST /connect/accesstokenvalidation
token=<token>&expectedScope=calendar
Note:
The access token validation endpoint does not enforce client authentication.
Do not use reference tokens for confidentiality purposes.
Identity Token Validation Endpoint
The identity token validation endpoint can be used to validate identity tokens. This is useful for clients that do not have access to the appropriate JWT or crypto libraries (e.g. JavaScript).
You can either GET or POST to the validation endpoint. Due to query string size restrictions, POST is recommended.
Example:
POST /connect/identitytokenvalidation
token=<token>&client_id=<expected_client_id>
GET /connect/identitytokenvalidation?token=<token>&client_id=<expected_client_id>
A successful response returns a status code of 200 and the associated claims for the token.
{
"nonce": "nonce",
"iat": "1413203421",
"sub": "88421113",
"amr": "password",
"auth_time": "1413203419",
"idp": "idsrv",
"iss": "https://idsrv3.com",
"aud": "implicitclient",
"exp": "1413203781",
"nbf": "1413203421"
}
An unsuccessful response will return a 400 with an error message.
CSP Endpoint
Unified Authentication Service provides an endpoint to record CSP errors that the browser reports. These CSP errors are raised as events in the system event