error
Registry Context
The OAuth `error` parameter carries an error code in authorization endpoint and token endpoint error responses.
Technical Summary
RFC 6749 defines `error` as a REQUIRED single ASCII error code selected from a response-specific set. Authorization code errors are returned in the redirect URI query component, implicit grant errors in the fragment component, and token endpoint errors in a top-level JSON response member.
When Used
Authorization endpoint error responses and token endpoint error responses.
Normative Requirements
Authorization servers
RFC 6749 - Section 4.1.2.1
Automatically redirect the user-agent to the invalid redirection URI..
Condition: When an authorization code request fails because the redirection URI is missing, invalid, or mismatched, or because the client identifier is missing or invalid.
MUST NOT automatically redirect the user-agent to the invalid redirection URI
RFC 6749 - Section 4.1.2.1
Include characters outside %x20-21 / %x23-5B / %x5D-7E in the `error` value..
Condition: In an authorization code grant error response.
Values for the "error" parameter MUST NOT include characters outside the set
RFC 6749 - Section 4.2.2.1
Automatically redirect the user-agent to the invalid redirection URI..
Condition: When an implicit grant request fails because the redirection URI is missing, invalid, or mismatched, or because the client identifier is missing or invalid.
MUST NOT automatically redirect the user-agent to the invalid redirection URI
RFC 6749 - Section 4.2.2.1
Include characters outside %x20-21 / %x23-5B / %x5D-7E in the `error` value..
Condition: In an implicit grant error response.
Values for the "error" parameter MUST NOT include characters outside the set
RFC 6749 - Section 5.2
Include characters outside %x20-21 / %x23-5B / %x5D-7E in the `error` value..
Condition: In a token endpoint error response.
Values for the "error" parameter MUST NOT include characters outside the set
RFC 6749 - Section 5.2
Respond with HTTP 401 (Unauthorized) and include a `WWW-Authenticate` response header matching the authentication scheme used by the client..
Condition: When returning `invalid_client` after the client attempted authentication using the `Authorization` request header field.
the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field
RFC 6749 - Section 4.1.2.1
Include `error` as a single ASCII error code selected from `invalid_request`, `unauthorized_client`, `access_denied`, `unsupported_response_type`, `invalid_scope`, `server_error`, or `temporarily_unavailable`..
Condition: In an authorization code grant error response redirected to the client.
error REQUIRED. A single ASCII [USASCII] error code from the following
RFC 6749 - Section 4.2.2.1
Include `error` as a single ASCII error code selected from `invalid_request`, `unauthorized_client`, `access_denied`, `unsupported_response_type`, `invalid_scope`, `server_error`, or `temporarily_unavailable`..
Condition: In an implicit grant error response redirected to the client.
error REQUIRED. A single ASCII [USASCII] error code from the following
RFC 6749 - Section 5.2
Include `error` as a single ASCII error code selected from `invalid_request`, `invalid_client`, `invalid_grant`, `unauthorized_client`, `unsupported_grant_type`, or `invalid_scope`..
Condition: In a token endpoint error response.
error REQUIRED. A single ASCII [USASCII] error code from the following
RFC 6749 - Section 4.1.2.1
Inform the resource owner of the error..
Condition: When an authorization code request fails because the redirection URI is missing, invalid, or mismatched, or because the client identifier is missing or invalid.
the authorization server SHOULD inform the resource owner of the error
RFC 6749 - Section 4.2.2.1
Inform the resource owner of the error..
Condition: When an implicit grant request fails because the redirection URI is missing, invalid, or mismatched, or because the client identifier is missing or invalid.
the authorization server SHOULD inform the resource owner of the error
RFC 6749 - Section 5.2
Return HTTP 401 (Unauthorized) to indicate which HTTP authentication schemes are supported..
Condition: When returning the `invalid_client` error code.
The authorization server MAY return an HTTP 401 (Unauthorized) status code
Validation Guidance
Verify authorization code error responses sent to a valid redirect URI place `error` in the query component.
Do not expect an authorization code error redirect when the redirect URI or client identifier is missing or invalid; verify that an invalid redirect URI is never used automatically.
Verify authorization code error values are selected from the seven codes defined by RFC 6749 Section 4.1.2.1.
Verify implicit grant error responses sent to a valid redirect URI place `error` in the fragment component.
Do not expect an implicit grant error redirect when the redirect URI or client identifier is missing or invalid; verify that an invalid redirect URI is never used automatically.
Verify implicit grant error values are selected from the seven codes defined by RFC 6749 Section 4.2.2.1.
Verify token endpoint error values are selected from the six codes defined by RFC 6749 Section 5.2.
Reject any `error` value containing characters outside %x20-21 / %x23-5B / %x5D-7E.
Verify token endpoint error parameters are top-level members of an `application/json` response body.
Verify token endpoint errors normally use HTTP 400 unless another status code is specified.
For `invalid_client`, accept HTTP 401 as permitted; require HTTP 401 and a matching `WWW-Authenticate` header when the client used the `Authorization` request header.
Security Notes
RFC 9700 - Section 2.1.2
RFC 9700 advises clients not to use the implicit grant or other response types that issue access tokens in the authorization response unless access-token injection is prevented and token-leakage vectors are mitigated. Implementations should therefore treat RFC 6749 fragment-based implicit error handling as applicable primarily to legacy or specially mitigated deployments.
Reference
Details
- Entry Id
error- Name
error- Parameter Usage Location
authorization response, token response- Change Controller
IETF- Reference
RFC6749