]> Google, LLC

nwatson@google.com

Security Web Authorization Protocol oauth error Define an error-handling protocol extension for the OAuth 2.0 token endpoint that allows the authorization server or resource server to specify an extra parameter on error responses that should be passed through to follow-up authorization requests. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction OAuth 2.0 and define several different error codes that authorization servers and resource servers may return. On token endpoint calls, most most runtime errors are lumped into invalid_grant, with the rest of the errors indicating a coding or configuration error by the client. Similarly, invalid_token covers most runtime errors on resource server calls. Given the changing security, privacy, and regulatory landscapes since OAuth 2.0 was released, many authorization servers have new types of error conditions, which may be too complex to adequately describe in a JSON response. This specification extends OAuth to allow for authorization servers and resource servers to return an extra parameter which can be passed back to the authorization server when the user is present in order to provide a richer error experience which may even allow for recovery by the user.

Motivating Use Cases Some errors which may require a richer experience include:

• User account types which have reduced capabilities (e.g. underage or enterprise accounts)
• Applications which can be disabled or restricted
• Custom authentication strength requirements not covered by an existing spec
• TODO more?

In the common case, errors requiring user attention are likely to appear at authorization time, when the user is present to see and/or address them. However, in circumstances where data used for access control is changed out of band, these errors could result in failures at refresh token exchange or access token usage. In this situation, the error codes defined by the original OAuth 2.0 spec are insufficiently expressive to address these different error scenarios. The error_description parameter also cannot cover errors that:

• Need to display richer detail (e.g. explain to user why account is blocked)
• Contain sensitive data (e.g. account has been flagged as underage)

Because the user is not always be present when the client receives an error from the authorization or resource server, there needs to be some way to preserve error state until the user is present again. Simply returning invalid_grant so that the client reattempts the authorization flow has a few downsides:

• Some clients may not automatically restart authorization and instead render a button to do so. In this case the user has no explanation for why they're suddenly signed out of the client.
• It may result in unnecessary work for the user if they need to complete some preliminary auth steps in order to reach the error state (e.g. sign in or account selection for authorization servers that support multiple login).
• invalid_grant is semantically the wrong error code for many error conditions.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Error Responses

Token endpoint When returning an error response from the token endpoint, the authorization server MAY return an additional parameter with any error code. In this case, error_state is a private contract wholly within the authorization server, so its format requires no specification (though see considerations below).

Bearer authentication scheme This specification defines the following WWW-Authenticate auth-param value, which may be presented alongside any error code. If access tokens are validated by the authorization server, the error response body is a private contract wholly within the authorization server and requires no specification (though see considerations below). If access tokens are validated directly on the resource server (e.g. using an authorization server public key), then the authorization server will need to understand the error_state generated by the resource server. It is RECOMMENDED to represent error_state as a JWT , and use JSON Web Encryption to encrypt it.

Resource server error_state JWT If using a JWT to represent error_state, the standard JWT claims MUST be set as follows:

• typ: "error+jwt"
• iss: Endpoint URL of the resource server endpoint returning the error
• aud: Authorization server issuer as defined by its metadata endpoint
• sub: Identifier of the user whose access token triggered the error
• iat: Issue time
• nbf: Not before
• exp: Expiration time, but see considerations below

The JWT will contain other custom claims that can be understood by the authorization server to display the error, but due to the diverse nature of potential errors, it's not possible to enumerate them in a spec. Authorization servers MUST ignore unknown claims.

error_state considerations It is RECOMMENDED that error_state be opaque to the client, though clients MUST NOT introspect the parameter regardless. If error_state contains any user data, it MUST be encrypted. It is RECOMMENDED that error_state contains a timestamp and the authorization server defines a reasonable timeframe in which it must be used. Given that there may be some human-introduced delay before error_state is sent to the authorization endpoint and the expected lack of sensitivity of the error_state parameter, it is RECOMMENDED that the expiration timestamp be at least 1 day. The authorization server and resource server MAY use error_state to represent both recoverable and non-recoverable errors. Examples of recoverable errors could include step-up auth or re-acknowledgment of updated terms of service. Examples of non-recoverable errors could include account or API disables where the authorization server needs to communicate some information to the user. It is NOT RECOMMENDED to distinguish between recoverable and non-recoverable errors to the client, as it potentially leaks sensitive information to the client. (Signals that should be shared for security and abuse reasons should use the protocols defined in [OpenID SSF].)

New error codes This specification additionally defines the access_denied error code for the token endpoint and resource servers, as an error code that may be more appropriate in some cases where error_state is returned.

Authorization Grant Request If the client is not running in a context where it can initiate an authorization grant flow (e.g. a workflow running on some cloud VM), it MAY transmit the error_state parameter to the system that can. Authorization servers that support error_state MUST support at least one of the following to avoid sending long encrypted parameters in the URL:

• HTTP POST requests to the authorization grant flow
• Pushed authorization requests

The authorization server MUST ignore an expired error_state parameter (though it is entirely possible that the same error will be re-encountered during a fresh authorization grant flow).

Security Considerations The resource server could in theory return an entire authorization URL that the client should follow, but doing so could allow a compromised resource server to direct the user to a malicious authorization server that would phish or steal user credentials. Returning just the error_state parameter prevents this as clients are responsible for targeting the correct authorization endpoint. TODO Risk of attaching error_state to URL for different user. TODO Guidance on background-running clients that need to notify the user. Don't want to train users to click on authz links.

Privacy Considerations Encrypting the error_state parameter allows the authorization and resource servers to embed additional user data into the parameter that should not be visible to clients. For example, unencrypted, a server couldn't reveal in the error that access was denied because the user is underage. However, encrypted (and salted), there's no problem plumbing an under_age flag to the authorization server.

IANA Considerations

OAuth Parameters Registration This specification registers the following OAuth parameter definitions in the IANA OAuth Parameters registry.

Registry Contents

• Name: error_state
  • Parameter Usage Location: authorization request, token response
  • Change Controller: IETF
  • Reference: This document

Normative References The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. 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). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries defined by that specification. Related digital signature and Message Authentication Code (MAC) capabilities are described in the separate JSON Web Signature (JWS) specification. JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. This document defines the pushed authorization request (PAR) endpoint, which allows clients to push the payload of an OAuth 2.0 authorization request to the authorization server via a direct request and provides them with a request URI that is used as reference to the data in a subsequent call to the authorization endpoint. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.

Acknowledgments TODO acknowledge.