OAuth OIDC error handling

Authorize endpoint: Error responses

Authorization code flow examples

HTTP/1.1 400 Bad request - Redirect URL not whitelisted in the oauth / oidc client

<script type="text/javascript">error: {description: "The redirection URI provided does not match a pre-registered value.", message: "redirect_uri_mismatch"}</script>

HTTP/1.1 301 - Moved permanently invalid_request

    ?error_description=Missing parameter response_type&error=invalid_request

A request that is missing a required parameter is an invalid request. The description identifies what is missing.

HTTP/1.1 301 - Moved permanently unsupported_response_type

    ?error_description=Response type is not supported&error=unsupported_response_type

When a response_type is requested that is not supported, this error is returned. Usually it is because of a typing error.

HTTP/1.1 301 - Moved permanently invalid scope

    ?error_description=No scope requested and no default scope configured&error=Invalid_Scope

When the scope parameter has no value, then this error is returned.

HTTP/1.1 301 - Moved permanently unauthorized_client

    ?error_description=No scope requested and no default scope configured&error=unauthorized_client

HTTP/1.1 400 - Bad request invalid_request

    <script type="text/javascript"> {error: {description: "Missing parameter: redirect_uri", message: "invalid_request} </script>

An error message resulting from a missing or invalid redirect_url in the request should, according to RFC 6749, be sent to the user’s UI. This is not mandatory according to the RFC. However, a redirect_url is always checked during the first call to the authorization server for both the authorization code flow and the implicit flow, for both OAUTH and OIDC protocols. No other flows are implicated here.

HTTP/1.1 301 - Moved permanently interaction_required

    ?error_description=The request requires some interaction that is not allowed&error=interaction_required

This happens, for example, when the request was executed with the Prompt=None parameter and no session was available. This parameter suppresses the authentication and consent page, so the user is not allowed to log in and so a valid session was required, but was not available.

HTTP/1.1 301 - Moved permanently access_denied

    ?error_description=Resource Owner did not authorize the request&error=access_denied

This happens for example when the request was executed, but the user, or resource owner, did not give their consent.

HTTP/1.1 301 - Moved permanently consent_required

    ?error_description=The request requires consent&error=consent_required

This happens, for example, when the request was executed with the [ prompt=none ] parameter with a valid session, but the request did ask for one or more extra scopes than was previously consented or approved by the user, or resource owner.

    {"error":"redirect_uri_mismatch","error_description":"The redirection URI provided does not match a pre-registered value."}

HTTP/1.1 301 - Redirect URI mismatch

    ?error_description=The redirection URI provided does not match a pre-registered value&error=redirect_uri_mismatch

This happens when a request for an authorization code was made while the request contained a redirect URL that was not configured on the allow-list for the OAUTH/OIDC client.

Implicit flow

Parameters that are not wanted with this type of flow, are ignored. All invalid parameters that are not part of the protocol standard are ignored.

HTTP/1.1 301 - Moved Permanently

    #error_description=Missing required parameter nonce from request&error=invalid_request

For the implicit flow, a nonce is, per RFC 6749, always required to be sent with the request, such as nonce=12346463467736251337290, which is a random number used only once per request and included for security reasons.

The error and the result of a valid request are always added after the fragment sign #.

HTTP/1.1 400 - Bad request invalid_request

    <script type="text/javascript">error: {description: "The redirection URI provided does not match a pre-registered value.", message: "redirect_uri_mismatch"}</script>

An HTML error page is served to the user indicating the problem with the redirect_url not being valid or allow-listed for the client in this case. Anything that has to do with missing or invalid redirects normally are, as specified by RFC 6749 as 'SHOULD' (so not mandatory), sent to the user UI.

HTTP/1.1 301 - Moved Permanently access_denied

    #error_description=Resource Owner did not authorize the request&error=access_denied

This happens when a response_type was included in the request that was not supported (for example, not part of the OAUTH 2.0 RFC).

HTTP/1.1 301 - Moved Permanently invalid_scope

    ?error_description=Unknown invalid scope mobilephone&error=invalid_scope

This happens when a scope (mobilephone in this case) was requested that was not configured on the client.

HTTP/1.1 301 - Moved Permanently server_error

    #error_description=The authorization server encountered an unexpected condition that prevented it from fulfilling the request&error=server_error

HTTP/1.1 301 - Moved Permanently temporary_unavailable

    #error_description=The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server&error=temporary_unavailable

Token endpoint

The token endpoint receives requests for access tokens. These can be access token request messages or refresh requests.

Access tokens are bearer tokens as indicated in RFC6750 Bearer tokens. For example, any party in possession of a bearer token (a bearer) can use it to get access to the associated resources (without demonstrating possession of a cryptographic key).

The OAuth specifications doesn't stipulate any type of token, such as JWT or SAML tokens. The OneWelcome Identity Platform token endpoint produces access tokens that can be considered as randomly generated strings.

The value is opaque to both OAuth clients and OAuth resource servers. Resource servers can obtain more information about the access token from the Introspect or TokenInfo endpoint.

When a refresh request is sent to the token endpoint, clients can optionally include requested scopes. These can only be a subset (or the same set) of the scopes that were requested previously.

If the client requests a smaller set of scopes, this will reduce the set of attributes that are returned by the TokenInfo endpoint accordingly.

Error response examples

HTTP/1.1 400 - Bad request - redirect_uri_mismatch

    {"error_description":"The redirection URI provided does not match a pre-registered value.","error":"redirect_uri_mismatch”}

This happens when a wrong (not configured or allow-listed on the client) or no redirect_uri is supplied.

HTTP/1.1 400 - Bad request - invalid grant

    {"error_description": "The provided access grant is invalid, expired, or revoked.","error": "invalid_grant"}

This happens when, for example, an expired or invalid authorization code is used on the token endpoint to get an access token.

HTTP/1.1 400 - Bad request - invalid grant

    {"error_description": "Resource owner authentication failed", "error": "invalid_grant"}

This happens when the credentials supplied for the resource owner, such as password credential flow, were wrong.

HTTP/1.1 400 - Bad request - invalid_client

    {"error_description": "Client authentication failed", "error": "invalid_client"}

This happens when an incorrect client_id is provided.

HTTP/1.1 400 - Bad request - server_error

    {"error_description": "User must be authenticated to issue ID tokens.","error": "server_error"}

This happens whenever a scope, which does not exist in the configuration of that client, is requested via the authorize endpoint. With that authorization code, an access_code is then requested on the token endpoint. This request cannot then be fulfilled, because that particular scope is not configured for that client, and finally this error appears.

HTTP/1.1 400 - Bad request - invalid_request

    {"error_description": "Client authentication failed", "error": "invalid_request"}

This happens when a wrong authentication method is used on the token endpoint, such as when the client is configured for basic authentication. The basic authentication header was provided, but the Client_Secret and Client_ID were sent in the body as well.

HTTP/1.1 400 - Bad request - invalid_client

    {"error_description":"Invalid authentication method for accessing this endpoint.","error":"invalid_client"}

This happens when an incorrect authentication method is used on the token endpoint. For example, the client is configured for basic authentication, but the Client_Id and Client_Secret were provided in the body of the request and NO basic authentication header was provided.

HTTP/1.1 400 - Bad request - unsupported_grant_type

    {"error_description":"Grant type is not supported","error":"unsupported_grant_type"}

This error is returned when the grant_type parameter has an unsupported value in the request.

HTTP/1.1 400 - Bad request - unauthorized_client

    {"error_description":"The authenticated client is not authorized to use this authorization grant type.","error":"unauthorized_client"}

HTTP/1.1 400 - Bad request - invalid_scope

    {"error_description": "Unknown/invalid scope(s): [phone, email]", "error": "invalid_scope"}

Scopes, which were not configured on the client, were requested when executing a resource owner password credential flow. In this case, the phone and email scopes were requested, but these were not configured on the client.

Introspect endpoint

This endpoint is meant to verify whether a given access_token or refresh_token is still valid.

Error message examples

Any parameters that are invalid are ignored. When the token_type parameter is used and contains an invalid value, the {active: false} message is returned. Any tokens that are invalid, such as a false value, give a general {active: false} message. So, invalid tokens are not treated as errors, to avoid disclosing unneeded sensitive information.

HTTP/1.1 400 - Bad request - invalid_client

    {"error_description": "Client authentication failed", "error": "invalid_client"}

This error is returned when, for example, the client_id is omitted when sending the request to the endpoint, if the client is of type Public, or if the client is of type Confidential and the basic authentication header is not sent or is incorrect.

Revoke endpoint

This endpoint is meant to revoke an access_token and a refresh_token. When a token is successfully revoked, HTTP1.1/200 and an empty "{}" JSON message is returned. When a refresh_token is revoked, the associated access_tokens are also revoked. When an access_token is revoked, the refresh_token, if any, is also revoked.

Error message examples

HTTP/1.1 400 - Bad request - invalid_request

    {"error_description": "Missing parameter: token","error": "invalid_request"}

HTTP/1.1 400 - Bad request - invalid_client

    {"error_description": "Client authentication failed", "error": "invalid_client"}

This error is returned when, for example, the client_id is omitted when sending the request to the endpoint if the client is of type Public, or if the client is of type Confidential and the basic authentication header is not sent or is incorrect.

HTTP/1.1 400 - Bad request - server_error

    {"error_description":"Unrecognised token type","error":"server_error"}

This error is returned when, for example, the token submitted to the revoke endpoint was an ID_Token, instead of an access or refresh token.

Token info endpoint

This is a proprietary endpoint offered by the OneWelcome Identity Platform. It is not specified by any of the IETF specifications.

The purpose of this endpoint is to provide the resource server with the following functionality in a single protocol (in other words, request and response):

• Validation of the access token and refresh token, similar to OAuth's introspect endpoint.
• Obtain information about the user.

Token info on TokenInfo endpoint

The following table lists the attributes that are directly related to the token as such and which are always included in a TokenInfo response.

User information on the TokenInfo endpoint

OAuth is an authorization protocol and not an authentication protocol. It tells the resource server which access rights (scopes) are given to the client that presents the access token. It does not tell the OAuth client or resource server who the current authenticated user is. However, by including attributes from the user's profile as scopes, the resource server can limit access to protected resources that are associated with that user. Typically, that would be the same user as the user that logged in.

The OneWelcome Identity Platform returns user attributes on the TokenInfo endpoint based on two mechanisms:

Scope-based

Some user attributes are configured as identifiers for that user. These are attributes that are unique for that user and that can also be used for logging in. Typical examples of such identifiers are username and private email address. When such an identifier is included in the authorization request or token request (depending on the grant flow) as a scope, the OneWelcome Identity Platform returns the value for that attribute in the TokenInfo response.

Typically, one would expect this endpoint to return the same attributes, regardless of how the access token was achieved: through a refresh grant or another grant. In order to achieve this, the client should include the same scopes in the refresh request as were used in a previous access token request or authorization request.

Configuration-based

Additionally, the TokenInfo endpoint can also return other attributes from the user's profile. This is dependent on the customer-specific configuration and the set of such attributes is the same for all OAuth clients. Examples of such attributes are nickname, first name, last name, and primary phone number.

The OneWelcome Identity Platform's ability to include an user's profile attributes in the TokenInfo response has a few limitations:

• Attributes where values have a more dynamic character such as formatted name and LastLogin date cannot be returned.
• Multi-valued attributes (other than primary email and primary phone number) cannot be returned.
• An attribute's metadata cannot be provided through the UserInfo endpoint.

The names for the attributes as they appear in the TokenInfo response can be configured.

Example request

Given an access token, a resource server can perform an HTTP GET on the TokenInfo endpoint.

    curl -X GET 'https://<domainURI>/auth/oauth2.0/v1/token-info?access_token=723320a5-a2c6-459b-ba05-8dd05aa8d24e'

Example response

The following example shows a TokenResponse message for a setup where:

• A mobile application known as MyMobileApp uses the authorization code grant to obtain access rights to download the user's photos through an API that is provided by a resource server (AuthorisationToDownloadPhotos)
• To identify the user that is logged in and whose photos will be downloaded, the scopes SCIMuserid, externalid, and primaryEmail are included.
• The user's current value for nickName was configured as an attribute, so any resource server can use that in dialogue with the user.

    {
        "access_token": "723320a5-a2c6-459b-ba05-8dd05aa8d24e",
        "grant_type": "authorization_code",
        "token_type": "Bearer",
        "expires_in": 2965,
        "client_id": "MyMobileApp",
        "scope": ["SCIMuserid", "externalid", "primaryEmail", "AuthorisationToDownloadPhotos"],
        "SCIMuserid": "05303a84b6ff41e18aa5bb17605b5b25",
        "externalid": ["11111111-6666-8888-5555-100000012300"],
        "primaryEmail" : "JohnSmith1980@gmail.com",
        "nickName" : "Jimmy"
    }