]> Curity

judith.kahrer@curity.io

Security TBD oauth client client challenge additional input This document extends the OAuth 2.0 token endpoint error response (RFC 6749) with a new error code that indicates to the client that it must provide additional input for the authorization server to authorize it and accept its request. This mechanism enables just-in-time authorization flows in which the authorization server dynamically challenges the client during a request and the client tries to satisfy it. For example, the authorization server can ask the client mid-flow to provide an assertion, a verifiable presentation, or other proof-of-possession material. About This Document Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction The OAuth 2.0 Authorization Framework assumes that a single grant signaled through the grant_type parameter is sufficient for the authorization server to authorize the client. It does not define how the authorization server signals to the client to provide additional input for it to make a decision - like an additional grant from the Resource Owner or an attestation artifact to prove the client's provenance. Real-world deployments increasingly require the authorization server to apply dynamic, contextual authorization policies — for example:

• Demanding a freshly signed client attestation when risk signals indicate an elevated threat level.
• Requiring the client to prove its mandate before a high-value token is issued.

This document introduces a way for the authorization server to start a challenge session where it defines requirements that it expects from the client. It extends the OAuth 2.0 Authorization Framework by introducing the following parameters:

1. A new error code insufficient_client_authorization for token error responses that the authorization server returns when it cannot proceed without additional client-supplied material.
2. A companion response parameter authorization_requirement — a typed JSON object that describes what the authorization server requires.
3. Processing rules for both parties, including the requirement to return unauthorized_client when subsequently provided input fails validation.

Motivation and Use Cases

Just-in-Time Authorization Whether and in which form an authorization server may return an access token to a client depends not only on the presented grant and requested access but also on the capabilities of the client, e.g., whether it is a public client or a confidential client, whether it is a first-party client or a third-party client. Just-in-time authorization means that the authorization server can, dynamically and on demand, evaluate necessary data from different sources to understand the context of a request and use that information to accept or deny a token request from a client. In a just-in-time flow, the authorization server defers its final authorization decision, challenges the client for supplemental proof material, and only then either grants or denies the request.

Client Authentication Step-Up An authorization server may accept client authentication for low-assurance tokens but require an attestation for tokens granting elevated privileges (see ()). The insufficient_client_authorization mechanism allows the authorization server to escalate the authentication requirement without the client needing to speculatively include high-assurance credentials on every request. It allows, for example, public clients to increase their trust profile.

Continuos Authorization The security state of a system can change at any time. Systems may communicate via signals about certain security-relevant events that they observed for other systems to adopt. In such an environment the authorization server may receive signals that constitute the need for additional input for authorization to e.g., mitigate attacks and prevent misuse.

Comparison with OAuth 2.0 First-Party Applications OAuth 2.0 First-Party Applications defines an API for user authentication where the authorization server challenges the OAuth 2.0 client to provide data from the user. The proposed API is similar to the mechanism defined in this document. However, there is a subtle difference: OAuth 2.0 First-Party Applications defines a new error code for the client to provide more data from the end-user (Resource Owner). Its main purpose is to enable clients to control the user experience. For that it makes two important assumptions:

• The client can interact with an end-user.
• The client is trusted to handle sensitive data like the end-user's credentials, i.e., the client is a first-party application.

The extension in this document is different because it assumes that the client can satisfy the challenge from the Authorization Requirement itself. It is applicable for both first- and third-party use cases where the authorization server challenges the client to provide additional input for the authorization grant. The client does not have to handle end-user credentials. What's more, it does not require an additional endpoint but extends the token response.

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.

Terminology This document uses the terms "access token", "authorization server", "client", "client authentication", "token response", "token request" and "token endpoint" as defined by the OAuth 2.0 Authorization Framework , unless otherwise specified by this document. In addition, the document uses the following terms:

Insufficient Client Authorization Response:

A token error response from the OAuth 2.0 token endpoint that indicates to the client that the authorization server requires additional input for it to authorize the client.

Authorization Requirement:

A typed JSON object returned by the authorization server in an Insufficient Client Authorization Response that specifies the additional material the client must supply.

Challenge Session:

A string managed by the authorization server that serves as the nonce in the challenge-response pattern. It associates an Insufficient Client Authorization Response with the subsequent request that satisfies it.

Insufficient Client Authorization Response This document registers the error code insufficient_client_authorization for use in OAuth 2.0 token endpoint error responses as defined in Section 5.2 of . The following content applies to the Insufficient Client Authorization Response.

error:

REQUIRED. The error parameter MUST be insufficient_client_authorization.

authorization_requirement:

REQUIRED. The authorization_requirement parameter is a typed JSON object as defined in .

challenge_session:

REQUIRED. An opaque identifier generated by the authorization server that binds this authorization challenge to the follow-up request. The client MUST include this value in the subsequent request to the authorization server if it receives one along with the insufficient_client_authorization error response.

expires_in:

OPTIONAL. A JSON number that defines the number of seconds from the time of the Insufficient Client Authorization Response until the challenge_session expires. The client MUST NOT submit a response after this time.

The authorization server MUST comply with Section 5.2 of . The authorization server SHOULD respond with HTTP status code 403 (Forbidden). It MAY include other parameters in the response. The client MUST ignore any parameters it does not understand. If the client does not understand or cannot satisfy the Authorization Requirement, it MUST treat the Insufficient Client Authorization Response as if the authorization server returned an unauthorized_client error. The Insufficient Client Authorization Response indicates the following:

1. The authorization server has determined that it cannot yet authorize the client or issue an access token.
2. The condition is resolvable: the authorization server knows what additional input would allow it to proceed.
3. The authorization server wishes to challenge the client to supply that input.

The following represents a non-normative example of an Insufficient Client Authorization Response.

The authorization_requirement Object The authorization_requirement parameter holds a JSON object that indicates what type of input the authorization server requires for the client to satisfy the insufficient client authorization. The following member is defined for all authorization_requirement types:

type:

REQUIRED. An absolute URI or a string identifying the authorization requirement type. The value determines the semantics of other members in the object.

Providing Authorization Requirement Each profile of this document that specifies a type of Authorization Requirement also MUST define how the client can fulfill the challenge and provide the required input to the authorization server. If the client does not understand the type of the authorization_requirement of an Insufficient Client Authorization Response or if it cannot satisfy the requirement, the client MUST treat the Insufficient Client Authorization Response as if the authorization server returned an unauthorized_client error as defined in Section 5.2 in , see also . The client MUST include the challenge_session parameter with the same value as it received in the Insufficient Client Authorization Response in its subsequent request and attempt to resolve the challenge. Some extensions to OAuth 2.0, notably Pushed Authorization Requests , make use of the token endpoint response outside a token endpoint request. A profile that defines an Authorization Requirement type SHOULD define mechanisms to fulfill the requirements that are applicable to authorization and token requests alike. If the authorization server deems the supplied input from the client in response to an Authorization Requirement challenge as invalid and if there is no other way for the client to resolve the insufficient_authorization error, the authorization server MUST respond with an unauthorized_client error.

Client Metadata Clients that communicate their client metadata, for example via dynamic client registration or client ID metadata document can signal support for this specification. To do so, they MUST include the following property in their client metadata:

insufficient_client_authorization_supported:

OPTIONAL. JSON boolean value specifying whether the client supports this specification.

This enables authorization servers to apply this specification without breaking integrations.

Security Considerations

Sender-Constrained Tokens The authorization server SHOULD issue sender-constrained tokens as a result of a successfully resolved client authorization challenge. In this way, the authorization server can mitigate the risk of token theft and replay. The idea is that the authorization server binds the token to a public key that the client controls. For the token to be valid, the client MUST provide a proof-of-possession that satisfies that key binding. The exact methods on how the authorization server binds the token to the client's key and how the client provides a proof-of-possession are out of scope of this document. Demonstrating Proof-of-Possession (DPoP) and certificate-bound access tokens are two examples, and there may be others.

Challenge Session The challenge_session parameter associates a Insufficient Client Authorization Response with follow-up resolution attempts. To mitigate session hijacking and replay, the authorization server SHOULD bind the challenge_session to the device requesting tokens, for example via DPoP. Similar to sender-constrained tokens, the binding prevents other devices from replaying a captured challenge_session and thus prevents other devices from taking over sessions (session hijacking).

IANA Considerations

OAuth Parameters Registration This document defines the following values for the IANA "OAuth Parameters" registry of established by . Parameter Name: challenge_session Parameter Usage Location: token response, token request Change Controller: IETF Specification Document: of [draft-kahrer-oauth-client-challenge-protocol-00]

OAuth Error Codes This document defines the following values for the IANA "OAuth Extensions Error" registry of . Error Name: insufficient_client_authorization Error Usage Location: token endpoint Related Protocol Extension: n/a Change Controller: IETF Specification Document: of [draft-kahrer-oauth-client-challenge-protocol-00]

OAuth Client Metadata Registration This document defines the following values for the IANA "OAuth Dynamic Client Registration Metadata" registry of established by . Client Metadata Name: insufficient_client_authorization_supported Client Metadata Description: JSON boolean value that specifies whether the OAuth client supports insufficient client authorization error in token error responses. Change Controller: IESG Specification Document: of [draft-kahrer-oauth-client-challenge-protocol-00]

References 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] 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. IANA This specification defines mechanisms for dynamically registering OAuth 2.0 clients with authorization servers. Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol. This specification also defines a set of common client metadata fields and values for clients to use during registration. Informative References MATTR Bundesdruckerei SPRIND This specification defines an extension to the OAuth 2.0 protocol [RFC6749] that enables a client instance to include a key-bound attestation when interacting with an Authorization Server or Resource Server. This mechanism allows a client instance to prove its authenticity verified by a client attester without revealing its target audience to that attester. It may also serve as a mechanism for client authentication as per OAuth 2.0. Okta Practical Identity LLC Defakto Security This document defines the Authorization Challenge Endpoint, which supports clients that want to control the process of obtaining authorization from the user using a native experience. In many cases, this can provide an entirely browserless OAuth 2.0 experience suited for native applications, only delegating to the browser in unexpected, high risk, or error conditions. 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. Okta This specification defines a mechanism through which an OAuth client can identify itself to authorization servers, without prior dynamic client registration or other existing registration. This is through the usage of a URL as a client_id in an OAuth flow, where the URL refers to a document containing the necessary client metadata, enabling the authorization server to fetch the metadata about the client as needed. This document describes a mechanism for sender-constraining OAuth 2.0 tokens via a proof-of-possession mechanism on the application level. This mechanism allows for the detection of replay attacks with access and refresh tokens. This document describes OAuth client authentication and certificate-bound access and refresh tokens using mutual Transport Layer Security (TLS) authentication with X.509 certificates. OAuth clients are provided a mechanism for authentication to the authorization server using mutual TLS, based on either self-signed certificates or public key infrastructure (PKI). OAuth authorization servers are provided a mechanism for binding access tokens to a client's mutual-TLS certificate, and OAuth protected resources are provided a method for ensuring that such an access token presented to it was issued to the client presenting the token. This document specifies a new parameter authorization_details that is used to carry fine-grained authorization data in OAuth messages.

Example with Authorization Details The following is an example that illustrates a token request using authorization_details as defined in . The authorization details indicate that the client aims to operate in an open banking ecosystem that has certain requirements. While the client authentication already provides some information about the provenance of the running software, the client also needs to prove that it complies with the requirements. Therefore, the authorization server challenges the client and responds with a Insufficient Client Authorization Response. The authorization server requests from the client the presentation of a verifiable credentials, e.g., a verifiable intent .

Acknowledgments The author wants to thank the following people for their feedback, input and contributions to this document: Jacob Ideskog, Michał Trojanowski

Document History -00

• Initial draft