OAuth OIDC endpoint error handling details

Authorise Endpoint - Error Responses

Authorisation Code Flow

(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 tells 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 according to the RFC not mandatory. However a redirect_url is always checked during the first call to the authorisation server for both authorisation code flow and for 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 login 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 end-user/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 then was previously consented/ approved by the end-user/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 authorisation code was made while the request contained a Redirect URL which was not configured on the white list for the OAUTH/OIDC client.

Implicit Flow

Note 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 send with the request. Like nonce=12346463467736251337290, a random number only used once per request and is included for security reasons.

Note The error and also the result of a valid request is 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/ whitelisted oil the client in this case. Anything that has to do with missing or invalid redirects normally are, as specified by the RFC 6749 as 'SHOULD', so not mandatory, send 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 (e.g. not part of the RFC OAUTH 2.0).

(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 requests' 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. OneWelcome's 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 Introspection or TokenInfo endpoint described on this page.

When a 'refresh request' is sent to the OneWelcome 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 Messages Overview

Error response (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/ whitelisted on the client) or no redirect_uri is supplied.

Error response (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 when an expired or invalid authorisation code is used on the Token end-point to get an access_token.

Error response (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.

Error response (HTTP/1.1 400 - Bad request - invalid_client)

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

This happens when a wrong client_id is provided.

Error response (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 is requested via the Authorize endpoint which does not exist in the configuration of that client. With that authorisation code an access_code is then requested on the Token endpoint. This request cannot then be fulfilled as that particular scope is not configured for that client and finally this error appears.

Error response (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. For example, when the client is configured for basic authentication. The basic authentication header was provided, but the Client_Secret and Client_ID was send in the body as well.

Error response (HTTP/1.1 400 - Bad request - invalid_client)

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

This happens when a wrong authentication method is used on the Token endpoint. For example, the client is configured for basic authentication, but Client_Id and Client_Secret were provided in the body of the request and NO Basic Authentication header was provided.

Error response (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.

Error response (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"}

Error response (HTTP/1.1 400 - Bad request - invalid_scope)

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

Scopes were requested when executing a resource owner password credential flow, which were not configured on the client. In this case scopes phone and email 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 Messages Overview

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

Error response (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 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 Messages Overview

Error response (HTTP/1.1 400 - Bad request - invalid_request)

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

Error response (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.

Error response (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 OneWelcome, it is not specified by any of the IETF specifications.

Warning: OneWelcome may deprecate this endpoint in the future in favour of using the introspective endpoint.

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

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

Token Info on TokenInfo Endpoint

⚠️OneWelcome will stop support for TokenInfo endpoint by Q4 2020, thus it should not be used for new projects. It will be replaced with TokenIntrospect & UserInfo endpoints.

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 TokenInfo Endpoint

OAuth is an authorisation protocol and not an authentication protocol. It tells the Resource Server what access rights (scopes) are given to the client that presents the access token. It does not tell the OAuth client or the Resource Server who the current authenticated user is. However, by including attributes from the enduser'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.

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

Scope-based

Some attributes of a user 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 e-mail address. When such an identifier was included in the authorisation request or token request (depending on the grant flow) as a scope, OneWelcome 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 authorisation request.

Configuration based

Additionally, the TokenInfo endpoint may also return other attributes from the enduser'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 and last name, and primary phone number.

OneWelcome's ability to include an enduser'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.

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'

Response

The following example shows a TokenResponse message for a set up where:

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

{

    "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"

}