Before authenticating users, make sure that you have the following information :
- OpenID Provider Metadata (autodiscovery URL) : Your admin can provide you with the URL which lives in
https://${realm.url}/oauth/${realm.name}/.well-known/openid-configuration - Your client credentials : client_id & client_secret (optional)
To initiate an authentication request, you must redirect the user browser to the OpenID Provider authorization_endpoint
The parameters available are :
| Parameter | Required | Description |
|---|
| response_type | Yes | A response_type which has been whitelisted to your client. If the response_type has not been assigned to the client, an error will be returned |
| client_id | Yes | The client_id which was provided by your admin |
| redirect_uri | Yes | One of the URLs registered by the client. It must be an exact match. If you use a redirect_uri which has not been registered, an error will be returned |
| scope | No | A space separated list of scopes required for this authentication request. If this parameter is ommited, the default scopes assigned to the client will be used. If a scope is requested and has not been assigned to the client, an error will be returned |
| state | No | A string that your app creates which the OpenID Provider will return in the response. It's highly recommended to use a state parameter to protect your application against CSRF attacks |
| code_challenge | No | Required if PKCE enforced is checked on the client. Specifies the SHA256 hash value of the code_verifier value in the token request. Set this parameter to help prevent authorization code interception attacks |
| code_challenge_method | No | Required only if you use a code_challenge. CYM-Identity only supports S256 |
| nonce | No | Required only if the response_type includes id_token. A random value which will returned as part of the id_token. It helps to detect replay attacks |
| response_mode | No | Specify how you expect the Authorization Server to send the response to the redirect_uri. Possible values are query & fragment |
| prompt | No | Specify how the Authorization Server prompts the user for reauthentication and reapproval. Possible values are login, consent, login consent & none |
| resource | No | Specify the resource which will be access by the access_tokens from this authentication request. It must equal the URI of a Protected Resource available in the Realm |
| max_age | No | Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated. If the elapsed time is greater than this value, the user will be asked to re-authenticate |
| ui_locales | No | A space separated list of languages. Specifies the requested language for the authentication UI. Your login pages must support this parameter or ignore it |
| acr_values | No | A space separated list of acr_values. Specifes the authentication levels acceptable to the client. Using this parameters maps to a voluntary OpenID claim |
Example request :
It may be unusual, but we recommend that you first manage Authentication errors, then authentication success.
There are two types of errors which can occur on the authentication request
These errors will mainly happen during your development :
- invalid_client_id : The client_id supplied does not match a client from the Realm or the client does not exist
- invalid_redirect_uri : The redirect_uri supplied does not match any of the pre-registered redirect_uris
In case of an error during the authentication, the user will be redirected to your application's redirect_uri as follows :
| Parameter | Required | Description |
|---|
| error | Yes | An error code which can be used by your app to determine the reason of the error |
| error_description | No | A description which can be used by the developer to fix the error |
| state | No | If a state parameter is present in the request, it'll be echoed in the response |
The possible errors are summarized below :
| Error | Source |
|---|
| invalid_response_type | The response_type requested is not whitelisted for the app |
| invalid_scope | The scope requested does not exist or has not been assigned to the client |
| invalid_response_mode | The response_mode requested is not whitelisted for the app or does not exist |
| invalid_code_challenge | The code_challenge is missing from the request |
| invalid_code_challenge_method | The code_challenge_method is missing from the request |
| nonce_required | In case an id_token will be directly passed to the redirect_uri, a nonce is required in the request |
| access_denied | The user did not consent to the scopes requested by the App |
| login_required | In case of a request with prompt=none, this error will be returned if the user is not logged in, or if the max_age has ellapsed |
| invalid_request | The resource requested does not exist or the scopes requested are not sufficient for the resource |
In case of a successful authentication, the user will be redirected to the specified redirect_uri as follows :
| Parameter | Required | Description |
|---|
| code | No | Will be present if the requested responsetype included _code |
| access_token | No | Will be present if the requested responsetype included _token |
| id_token | No | Will be present if the requested responsetype included _id_token |
| state | No | If a state parameter is present in the request, it'll be echoed in the response |
| scope | No | A scope will be returned if the requested response_type included token |
| expires_in | No | Will be returned if the requested response_type included token. Represents the number of seconds the access_token is valid for. |
| session_state | No | A string which must be used to listen to session change events Session. |
| token_type | No | Will be returned if the requested response_type included token. Represents the type of access token returned. Only Bearer access_tokens are supported |
In case you requested a code, you need to exchange this code for the actual tokens. You'll call the Authorization Server token_endpoint
POST /token_endpoint HTTP/1.1
grant_type=authorization_code
&code=A_RANDOMLY_GENERATED_CODE
&redirect_uri=https%3A%2F%2Fyour.awesome.app%2Fcallback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
| Parameter | Required | Description |
|---|
| grant_type | Yes | The value must be authorization_code |
| code | Yes | the code received in your redirect_uri |
| redirect_uri | Yes | The redirect_uri which your app received the code on |
| client_id | No | Only required if the client authenticates through client_secret_post or does not authenticate (for native clients) |
| client_secret | No | Only required if the client authenticates through client_secret_post |
| client_assertion | No | Only required if the client authenticated through client_secret_jwt or private_key_jwt |
| client_assertion_type | No | Only required if a clientassertion is used. The value must be _urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
| code_verifier | No | Only required if a code_challenge was used during the authentication request |
| resource | No | The URI of a resource which has been declared in the Realm |
HTTP/1.1 400 Bad Request
{
"error": "AN_ERROR_CODE",
"error_description": "AN_ERROR_DESCRIPTION"
}
HTTP/1.1 200 OK
{
"access_token": "AN_ACCESS_TOKEN_VALUE",
"id_token" : "AN_ID_TOKEN",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token" : "A_REFRESH_TOKEN"
}