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.

Requesting an access token using the Implicit Grant

GET /{tenant}/oauth2/v1/auth/

The request

Request parameters

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

Example request

GET /{tenant}/oauth2/v1/auth/?
    response_type=token
    &client_id=[YOUR_CLIENT_ID]
    &redirect_uri=https://[YOUR_APP_REDIRECT_URI]/
    &scope=[SCOPES]
    &state=[STATE]

The 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.

Response parameters

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 <Base64UrlEncodedHeader>.<Base64UrlEndcodedPayload>.<Base64UrlEncodedSignature> See http://openid.net/specs/openid-connect-core-1_0.html

Example response

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.

Error parameters

Name Value 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.

Example error response

Example
https://[YOUR_APP_REDIRECT_URI]/#error=access_denied

Requesting an authorization code using the Authorization Code Grant

GET /{tenant}/oauth2/v1/auth/

The request

Request parameters

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

Example request

GET /{tenant}/oauth2/v1/auth/?
    response_type=token
    &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]

The 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.

Response parameters

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.

Example response

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.

Error parameters

Name Value 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.

Example error response

Example
https://[YOUR_APP_REDIRECT_URI]/#error=access_denied

Related sections

How To: Perform OAuth Implicit Grant

How To: Perform OAuth Authorization Code Grant