Errors from Secured Resources

  • Article

 

This section describes the errors that a secured resource, such as a web API returns when the web API implements RFC 6750. In addition, it includes information to help your web application authenticate to a service that is secured by Azure Active Directory (Azure AD). For more information, see the RFC 6750 specification, The OAuth 2.0 Authorization Framework: Bearer Token Usage.

Secured resources that implement RFC 6750 issue HTTP status codes. If the request does not include authentication credentials or is missing the token, the response includes an "WWW-Authenticate" header. When a request fails, the resource server responds with the an HTTP status code and an error code.

Here is an example of an unsuccessful request and response. In this case, the client request does not have the required bearer token.

GET /resource HTTP/1.1 
   Host: service.contoso.com 
   Authorization: Bearer

In the response from the resource, the HTTP 401 status code indicates the authorization failed. The invalid_token error code and error description explain the specific problem.

HTTP/1.1 401 Unauthorized 
WWW-Authenticate: Bearer authorization_uri="https://login.window.net/contoso.com/oauth2/authorize",  error="invalid_token",  error_description="The access token is missing.",

HTTP Status Codes

The following status codes are used in responses to requests for secured resources.

HTTP Code

Description

400

Default HTTP code. Used in most cases.

401

Authentication failed. For example, the request the request contains an expired access token.

403

Authorization failed. For example, the user does not have permission to access the resource.

500

An internal error has occurred at the service. Retry the request.

Error Parameters

The following table shows the parameters in the error response.

Parameter

Description

authorization_uri

The URI (physical endpoint) of the authorization server. This value is also used as a lookup key to get more information about the server from a discovery endpoint.

The client must validate that the authorization server is trusted. When the resource is protected by Azure AD, it is sufficient to verify that the URL begins with https://login.windows.net or another hostname that Azure AD supports. A tenant-specific resource should always return a tenant-specific authorization URI.

error

An error code value defined in Section 5.2 of the OAuth 2.0 Authorization Framework. The next table describes the error codes that Azure AD returns.

error_description

A more detailed description of the error. This message is not intended to be end-user friendly.

resource_id

Returns the unique identifier of the resource. The client application can use this identifier as the value of the resource parameter when it requests a token for the resource.

Important

The client application must verify the value. Otherwise, a malicious service might be able to induce an elevation-of-privileges attack.

The recommended strategy for preventing an attack is to verify that the resource_id matches the base of the web API URL that being accessed. For example, if https://service.contoso.com/data is being accessed, the resource_id can be htttps://service.contoso.com/. The client application must reject a resource_id that does not begin with the base URL unless there is a reliable alternate way to verify the id.

Bearer Scheme Error Codes

The RFC 6750 specification defines the following errors for resources that use using the WWW-Authenticate header and Bearer scheme in the response. The following table lists the HTTP status code and error codes that can appear in the response.

HTTP Code: Error_Code

Description

Client Action

400: invalid_request

The request is not well-formed. For example, it might be missing a parameter or using the same parameter twice.

Fix the error and retry the request. This type of error should occur only during development and be detected in initial testing.

401: invalid_token

The access token is missing, invalid, or is revoked. The value of the error_description parameter provides additional detail. 

Request a new token from the authorization server. If the new token fails, an unexpected error has occurred. Send an error message to the user and retry after random delays.

403: insufficient_scope

The access token does not contain the impersonation permissions required to access the resource.

Send a new authorization request to the authorization endpoint. If the response contains the scope parameter, use the scope value in the request to the resource.

403: insufficient_access

The subject of the token does not have the permissions that are required to access the resource.

Prompt the user to use a different account or to request permissions to the specified resource.

Here is another example of a problematic request and its error response. In this case, the client application has an access token, but it is expired.

GET /resource HTTP/1.1 
    Host: server.example.com 
    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ

The response uses the HTTP 401 status code and error and error_description parameters to describe the error.

HTTP/1.1 401 Unauthorized 
     WWW-Authenticate: Bearer authorization_uri="https://login.window.net/contoso.com/oauth2/authorize", 
                       error="invalid_token", error_description="The access token is expired."

See Also

Error Handling in OAuth 2.0
Authorization Endpoint Errors
Token Issuance Endpoint Errors
OAuth 2.0 in Azure AD
Best Practices for OAuth 2.0 in Azure AD