OAuth Client Challenge Protocol

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 20 November 2026.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

The OAuth 2.0 Authorization Framework [RFC6749] 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.¶

2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3. 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 [RFC6749], 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.¶

4. 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 [RFC6749].¶

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 Section 5.¶

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 [RFC6749]. 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.¶

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store

{
  "error": "insufficient_client_authorization",
  "authorization_requirement": {
    "type": "verifiable_presentation",
    "challenge_session": "7f3d9e2a-4c1b-4f8e-b5a0-1e6c8d2f0a9b",
    "presentation_definition": { ... }
  }
}

5. 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.¶

6. 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 [RFC6749], see also Section 4.¶

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 [RFC9126], 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.¶

7. Client Metadata

Clients that communicate their client metadata, for example via dynamic client registration [RFC7591] or client ID metadata document [I-D.ietf-oauth-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.¶

8. Security Considerations

9. IANA Considerations

10. References

Appendix A. Example with Authorization Details

The following is an example that illustrates a token request using authorization_details as defined in [RFC9396]. The authorization details indicate that the client aims to operate in an open banking ecosystem that has certain requirements.¶

POST /token HTTP/1.1
Host: authorization-server.example
Content-Type: application/x-www-form-urlencoded
OAuth-Client-Attestation: eyJ0eXAiOiJvYX...
DPoP: eyJ0eXAiOiJkcG9...

grant_type=client_credentials&
resource=https://api.openbanking.example&
authorization_details=%5B%7B%22type%22%3A%22payment_initiation%22%2C%22actions%22%3A%5B%22initiate%22%2C%22status%22%2C%22cancel%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fapi.openbanking.example%2Fpayments%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%3A%22EUR%22%2C%22amount%22%3A%22123.50%22%7D%2C%22creditorName%22%3A%22Merchant%20A%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22DE02100100109307118603%22%7D%2C%22remittanceInformationUnstructured%22%3A%22Ref%20Number%20Merchant%22%7D%5D

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 [Mastercard.VI].¶

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store

{
  "error": "insufficient_client_authorization",
  "authorization_requirement": {
    "type": "verifiable_presentation",
    "challenge_session": "7f3d9e2a-4c1b-4f8e-b5a0-1e6c8d2f0a9b",
    "presentation_definition": { ... }
  }
}

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¶

Author's Address