OAuth 2.0 Authorization Endpoint
This OAuth 2.0 endpoint is to request an access token using the implicit grant, or an authorization code using the authorization code grant.
GET /{tenant}/oauth2/v1/auth/
Requesting an access token using the Implicit Grant
Request
| Name | Values | Description | Required |
|---|---|---|---|
| response_type | token | Instructs The Identity Hub to return an access token in the url fragment of the response. | Yes |
| client_id | The client Id you obtained from the Apps admin page | The client Id uniquely identifies your App. | Yes |
| redirect_uri | One of the redirect uri's you configured for your app in the Apps admin page | This parameter determines where the response is sent. This must exactly match one of the values listed for your App in the Apps admin page | Yes |
| scope | A space delimited list of scopes | The list of scopes available for the App. See the Apps admin page | No, but for OpenID connect "openid" scope is required. |
| state | Any string | The Identity Hub includes this parameter and its value in the response, so your application receives the same value it sent. You can then use this value to redirect the user to the correct resource in your app. | No (but recommended) |
| nonce | Any string | The Identity Hub includes this parameter and its value in the ID Token, so your application receives the same value it sent. The value is used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values. See http://openid.net/specs/openid-connect-core-1_0.html | No (but recommended) Appplies only to OpenID Connect |
GET /{tenant}/oauth2/v1/auth/?
response_type=token
&client_id=[YOUR_CLIENT_ID]
&redirect_uri=https://[YOUR_APP_REDIRECT_URI]/
&scope=[SCOPES]
&state=[STATE]
Response
If the user succesfully authenticates and grants access if needed, The Identity Hub returns an access token to your application. The response parameters are returned to your application in the fragment. Since a uri fragment is not returned to the server, client-side script must parse the fragment and extract the value of the access_token parameter.
| Name | Values | Description |
|---|---|---|
| access_token | The access token | This parameter holds the access token issued by The Identity Hub. |
| token_type | bearer | This value will always be bearer to indicate this is a bearer token. |
| expires_in | A number | The number of seconds the access token is valid from the time it was issued. |
| state | Any string | This value is roundtripped by The Identity Hub. |
| scope | A space delimited set of scopes | The list of scopes that are returned, can be different from the list of scoped your App asked in the initial request. This can be the result of a user not granting the App access to certain scopes or the rights of the user prevent the user from having the scopes. |
| id_token | The OpenID Connect ID Token | Only when openid scope was specified in authorization request. The ID token is in the format |
https://[YOUR_APP_REDIRECT_URI]/#
access_token=X5678IYHI690UJJJ000
&token_type=bearer
&expires_in=960
&scope=[SCOPES]
&state=[STATE]
&id_token=[IDTOKEN]
Handling errors
If the specified parameters of the request are invalid, The Identity Hub will respond with an error When the specified client_id or redirect_uri parameter in the access token request is invalid, the user agent is not redirected to the specified redirect_uri. Instead a message is displayed by The Identity Hub to the user.
| Name | Values | Description |
|---|---|---|
| error | access_denied | The user denied the request |
| unsupported_response_type | The value of the response_type parameter is not supported by The Identity Hub | |
| server_error | The value of the response_type parameter is not supported by The Identity Hub | |
| invalid_scope | One of the requested scopes is invalid. | |
| unauthorized_client | The client is not authorized to request a token or code using this method. | |
| state | Any string | The value of the state parameter that was sent in the request. |
https://[YOUR_APP_REDIRECT_URI]/#error=access_denied
Requesting an authorization code using the Authorization Code Grant
Request
| Name | Values | Description | Required |
|---|---|---|---|
| response_type | code | Instructs The Identity Hub to return an authorization in the query string of the response. | Yes |
| client_id | The client Id you obtained from the Apps admin page | The client Id uniquely identifies your App. | Yes |
| redirect_uri | One of the redirect uri's you configured for your app in the Apps admin page | This parameter determines where the response is sent. This must exactly match one of the values listed for your App in the Apps admin page | Yes |
| scope | A space delimited list of scopes | The list of scopes available for the App. See the Apps admin page | No, but for OpenID connect "openid" scope is required. |
| state | Any string | The Identity Hub includes this parameter and its value in the response, so your application receives the same value it sent. You can then use this value to redirect the user to the correct resource in your app. | No (but recommended) |
| nonce | Any string | The Identity Hub includes this parameter and its value in the ID Token, so your application receives the same value it sent. The value is used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values. See http://openid.net/specs/openid-connect-core-1_0.html | No (but recommended) Appplies only to OpenID Connect |
| code_challenge | Any string | Proof Key for Code Exchange parameter. The Identity Hub will link this value to requested authorization code. See https://tools.ietf.org/html/rfc7636. | No |
| code_challenge_method | Only values : plain or S256 | Proof Key for Code Exchange parameter. The Identity Hub will link this value to requested authorization code. See https://tools.ietf.org/html/rfc7636. | No |
GET /{tenant}/oauth2/v1/auth/?
response_type=code
&client_id=[YOUR_CLIENT_ID]
&redirect_uri=https://[YOUR_APP_REDIRECT_URI]/
&scope=[SCOPES]
&state=[STATE]
&code_challenge=[CODE_CHALLENGE]
&code_challenge_method=[CODE_CHALLENGE_METHOD]
Response
If the user succesfully authenticates and grants access if needed, The Identity Hub returns an authorization code to your application. The response parameters are returned to your application in the query string of the redirect uri, so they can be read by the web server.
| Name | Values | Description |
|---|---|---|
| authorization_code | The authorization code as string | This parameter holds the authorization code issued by The Identity Hub. |
| state | Any string | This value is roundtripped by The Identity Hub. |
https://[YOUR_APP_REDIRECT_URI]/?code=X5678IYHI690UJJJ000&state=[STATE]
Handling errors
If the specified parameters of the request are invalid, The Identity Hub will respond with an error When the specified client_id or redirect_uri parameter in the access token request is invalid, the user agent is not redirected to the specified redirect_uri. Instead a message is displayed by The Identity Hub to the user.
| Name | Values | Description |
|---|---|---|
| error | access_denied | The user denied the request |
| unsupported_response_type | The value of the response_type parameter is not supported by The Identity Hub | |
| server_error | The value of the response_type parameter is not supported by The Identity Hub | |
| invalid_scope | One of the requested scopes is invalid. | |
| unauthorized_client | The client is not authorized to request a token or code using this method. | |
| state | Any string | The value of the state parameter that was sent in the request. |
https://[YOUR_APP_REDIRECT_URI]/#error=access_denied