Errors from Secured Resources
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