OAuth 2.0 step-up authorization challenge proto

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 30 December 2025.¶

Copyright Notice

Copyright (c) 2025 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

In simple authorization scenarios, an authorization server will determine what claims to embed in the tokens to issue on the basis of aspects such as the scopes requested, the resource, the identity of the client, and other characteristics known a provisioning time. [RFC9470] helped improve the feedback a resource server can provide to a client in case the user authentication method, authentication class, or the freshness of the authentication event did not meet the requirements expexted by the resource server. Although those approaches are viable in many situations, it falls short in several important circumstances, for instance, in [FAPI2.0-Security-Profiles] or [hl7.fhir.uv.smart-app-launch] regulated APIs when they require peculiar client authentication mechanisms to be enforced or transaction specific details to be present in the token. These requirements may depend upon resource access rules or policies implemented at a policy decision point it relies on, using a logic that is opaque to the authorization server.¶

This document extends the collection of error codes defined by [RFC6750] and by [RFC9470] with a new error codes, failed_authorization and insufficient_authorization, which can be used by resource servers to signal to clients that the authorization delegation represented by the access token presented with the request does not meet the authorization requirements of the resource server. This document also introduces associated payload definitions. The resource server can use these payloads to explicitly communicate to the client its authorization requirements.¶

The client can then use this information to reach back to the authorization server with a new authorization request that specifies the additional authorization details required for issuing tokens useable at the resource. This document does not describe any new methods to perform this additional authorization request but will rely on OAuth 2.0 Rich Auhtorization Request [RFC9396], OAuth 2.0 Pushed Authorization Request [RFC9126], or OAuth 2.0 JWT-Secured Authorization Request [RFC9101] for this purpose. These extensions will make it possible to implement interoperable step up authorization flows with minimal work from resource servers, clients, and authorization servers.¶

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

This specification uses the terms "access token", "authorization server", "authorization endpoint", "authorization request", "client", "protected resource", and "resource server" defined by [RFC6749].¶

3. Protocol Overview

The following is an end-to-end sequence of a typical step up authorization scenario implemented according to this specification. The scenario assumes that the client obtained an access token for the protected resource before the sequence described below takes place.¶

+----------+                                          +--------------+
|          |                                          |              |
|          |-----------(1) request ------------------>|              |
|          |                                          |              |
|          |<---------(2) challenge ------------------|   Resource   |
|          |                                          |    Server    |
|  Client  |                                          |              |
|          |-----------(5) request ------------------>|              |
|          |                                          |              |
|          |<-----(6) protected resource -------------|              |
|          |                                          +--------------+
|          |
|          |
|          |  +-------+                              +---------------+
|          |->|       |                              |               |
|          |  |       |--(3) authorization request-->|               |
|          |  | User  |                              |               |
|          |  | Agent |<-----------[...]------------>| Authorization |
|          |  |       |                              |     Server    |
|          |<-|       |                              |               |
|          |  +-------+                              |               |
|          |                                         |               |
|          |<-------- (4) access token --------------|               |
|          |                                         |               |
+----------+                                         +---------------+

Figure 1: Abstract Protocol Flow¶

1. The client requests a protected resource, presenting an access token.¶

2. The resource server determines that the circumstances in which the presented access token was obtained offer insufficient authorization details, wrong grant flow, or inadequate client authentication mechanism; it therefore denies the request and returns a challenge describing (using a combination of error code and payload details) what authorization requirements must be met to allow the request. It is possible here for the resource server to rely on the responses from an external policy decision point.¶

3. The client redirects the user agent to the authorization server with an authorization request that includes the authorization details indicated by the resource server in the previous step.¶

4. A new and adequate authorization sequence takes place between the user agent, the client and the authorization server, resulting in the issuance of a new access token that encapsulates the authorization level, or ceremonies requested by the resource server. The authorization server uses the payload for the resource server's response forwarded by the client to initiate the right grant flow type or to ensure that the authorization details are met. The authorization server may here also contact an external policy decision point to request evaluation of complex business access policies. The newly minted access token contains or references information about the authorization elements required, including but not limited to the claims defined in [I-D.lombardo-oauth-client-extension-claims].¶

5. The client repeats the request from step 1, presenting the newly obtained access token.¶

6. The resource server finds that the authorization details, grant flow or client authentication mechanism used during the acquisition of the new access token complies with its requirements and returns the representation of the requested protected resource.¶

Such protocol flow is coherent with the expectations of [FAPI2.0-Security-Profiles] and section 2.1.10.2.1 of [hl7.fhir.uv.smart-app-launch].¶

The validation operations mentioned in steps 2 and 6 imply that the resource server has a way of evaluating the authorization requirements that occurred during the ceremonies that led to the issuance of the access token. In the context of this document, the assessment by the resource server of the specific authorization mechanisms used to obtain a token for the requested resource is called an "authorization state".¶

This document does not describe how the resource server performs this assessment of the authorization state, whether the access token is a JSON Web Token (JWT) [RFC9068] or is validated via introspection [RFC7662] or whether the resource provider is performing this assessment natively or by offloading the assessment to a policy decision point as defined in [D-OpenID-AuthZEN], [XACML] or NIST's ABAC [SP.800-162]. This document rather describes how the resource provider tells the client what type of authorization it needs to get from the authorization server for a request.¶

The terms "authorization state" and "step up" are metaphors in this specification. These metaphors do not suggest that there is an absolute hierarchy of authorization states expressed in interoperable fashion. The notion of a state emerges from the fact that the resource server may only want to accept certain authorization mechanisms. When presented with a token derived from particuliar authorization mechanisms (i.e., a given authorization state) that it does not want to accept (i.e., below the threshold it will accept), the resource server seeks to step up (i.e., renegotiate) from the current authorization state to one that it may accept. The "step up" metaphor is intended to convey a shift from the original authorization state to one that is acceptable to the resource server.¶

As for [RFC9470], although the case in which the new access token supersedes old tokens by virtue of a higher authorization state is common, in line with the connotation of the term "step up authorization", it is important to keep in mind that this might not necessarily hold true in the general case. For example, for a particular request, a resource server might require a higher authorization state and a shorter validity, resulting in a token suitable for one-off calls but leading to frequent prompts: hence, offering a suboptimal user experience if the token is reused for routine operations. In such a scenario, the client would be better served by keeping both the old tokens, which are associated with a lower authorization state, and the new one: selecting the appropriate token for each API call. This is not a new requirement for clients, as incremental consent and least-privilege principles will require similar algorithms for managing access tokens associated with different scopes and permission levels. This document does not recommend any specific token-caching strategy: that choice will be dependent on the characteristics of every particular scenario and remains application-dependent as in the core OAuth cases. Furthermore, OAuth 2.0 [RFC6749] assumes access tokens are treated as opaque by clients. The token format might thus be unreadable to the client or might change at any time to become unreadable. So, during the course of any token-caching strategy, a client must not attempt to inspect the content of the access token to determine the associated authentication information or other details (see Section 6 of [RFC9068] for a more detailed discussion).¶

4. Step-Up Authorization Challenge

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization", error_description="The authorization level is not met", resource_metadata_uri="https://www.example.com/.well-known/oauth-protected-resource", body_instructions=true

{
  "decision": false,
  "context": {
        "error_msg": "Missing expected access token scope",
        "details": [{
    "loc": "/scope",
    "method": "simple",
    "values": ["resource:read", "resource:write"]
    }]
  }
}

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization", error_description="The authorization level is not met",  body_instructions=true

{
    "decision": false,
    "context": {
        "error_msg": "Missing authorization_details",
        "details": [{
      "loc": "/authorization_details",
      "method": "simple",
      "value": [{
        "type": "payment_initiation",
          "actions": [
            "initiate",
            "status",
            "cancel"
          ],
          "locations": ["https://example.com/payments"],
          "instructedAmount": {
            "currency": "EUR",
            "amount": "123.50"
          },
          "creditorName": "Merchant A",
          "creditorAccount": {
            "iban": "DE02100100109307118603"
          },
          "remittanceInformationUnstructured": "Ref Number Merchant"
      }]
    }]
  }
}

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization", error_description="The authorization level is not met",  body_instructions=true

{
    "decision": false,
    "context": {
        "error_msg": "Missing expected access token scope",
        "details": [{
      "loc": "/email",
      "method": "exists"
    }]
  }
}

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization", error_description="The authorization level is not met",  body_instructions=true

{
    "decision": false,
    "context": {
        "error_msg": "Missing token claims - gty, ccr, cmr",
        "details": [{
    "loc": "/gty",
    "method": "exists"
    }, {
    "loc": "/ccr",
    "method": "exists"
    }, {
    "loc": "/cmr",
    "method": "exists"
    }]
  }
}

5. CLient Action Following A Setp-Up Auhtorization Challenge

This document does not define how the client should respond to a step-up authorization challenge. It is up to the logic of the client to decide what is the most appropriate grant type flow to start in order to try to obtain a new set of tokens from the authorization server.¶

6. Authorization Response

An authorization server complying with this specification will react to the presence of the presented parameters and react as defined by the associated specification being, without limitations to, the response described in [RFC6749].¶

7. Information conveyed via the Access Token

To evaluate whether an access token meets the protected resource's requirements, the resource server will enforce the conventional token-validation logic before analysing the content of the payload of the token as defined by [RFC7519], [RFC6749], and [RFC9068] as long as any specification that applies to IANA registered claims.¶

8. Deployment Considerations

This specification facilitates the communication of requirements from a resource server to a client, which, in turn, can enable a more granular and appropriate Authorization Request at the Authorization Server using either an OAuth 2.0 [RFC6749] defined grant flows, a Rich Authorization Request [RFC9396], a Push Authorization Request [RFC9126], or a JWT-Secured Authorization Request [RFC9101] as it sees fit. However, it is important to realize that the user experience achievable in every specific deployment is a function of the policies each resource server and authorization server pair establishes. Imposing constraints on those policies is out of scope for this document. It is therefore perfectly possible for resource servers and authorization servers to impose requirements that are impossible for subjects or clients to comply with or that lead to an undesirable user-experience outcome.¶

9. Resource Server Metadata

Resource servers can advertise their support of this specification by including in their OAuth protected resource metadata document, as defined in [RFC9728], the value step_up_authorization_supported. The presence of step_up_authorization_supported in the resource server metadata document signals that the resource server MAY honor the issuance of step-up authorization challenge if its sees fit.¶

10. Security Considerations

This specification adds to previously defined OAuth mechanisms. Their respective security considerations apply:¶

• OAuth 2.0 [RFC6749],¶

• JWT access tokens [RFC9068],¶

• Bearer WWW-Authenticate [RFC6750],¶

• Token introspection [RFC7662],¶

• OAuth2 Protected Resource Metadata [RFC9728],¶

• Rich Authorization Request [RFC9396],¶

• Push Authorization Request [RFC9126],¶

• JWT-Secured Authorization Request [RFC9101] and¶

• AuthZEN [D-OpenID-AuthZEN]¶

11. IANA Considerations

This document has no IANA actions.¶

12. References

Appendix A. Use Cases

+----------+
|          |                  +--------------+
|          |---(1) prompt --->|              |                                                                                      +--------------+
|          |                  |              |-----------------------------------(2) LLM request ---------------------------------->|              |
|          |                  |              |                                                                                      |              |
|          |                  |              |<-----------------------------------(3) Tool usage -----------------------------------|              |
|  User    |                  |              |                        +--------------+                                              |              |
|          |                  |              |---(4) tool request --->|              |                                              |              |
|          |                  |              |                        |              |                           +--------------+   |              |
|          |                  |              |                        |              |---(5) service request --->|              |   |              |
|          |                  |     LLM      |                        |   LLM Tool   |                           | Service APIs |   |      LLM     |
|          |                  |    Agent     |                        |              |<--(6) service response ---|              |   |              |
|          |                  |              |                        |              |                           +--------------+   |              |
|          |                  |              |<--(7) tool response ---|              |                                              |              |
|          |                  |              |                        +--------------+                                              |              |
|          |                  |              |                                                                                      |              |
|          |                  |              |-----------------------------------(8) LLM request ---------------------------------->|              |
|          |                  |              |                                                                                      |              |
|          |                  |              |<----------------------------------(9) LLM outcome -----------------------------------|              |
|          |                  |              |                                                                                      +--------------+
|          |<-(10) response --|              |
|          |                  +--------------+
+----------+

GET /.well-known/oauth-protected-resource
Host: api.saas.net
Accept: application/json

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "resource": "https://api.saas.net/",
  "authorization_servers": [ "https://authorization-server.saas.net" ],
  "bearer_methods_supported": [
    "header",
    "body"
  ],
  "scopes_supported": [
    "agent.tools.read",
    "agent.tools.write"
  ],
  "resource_documentation": "https://idp.saas.net/tools/resource_documentation.html"
}

GET /.well-known/oauth-authorization-server
Host: authorization-server.saas.net
Accept: application/json

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "issuer": "https://authorization-server.saas.net",
  "authorization_endpoint": "https://authorization-server.saas.net/oauth2/authorize",
  "token_endpoint": "https://authorization-server.saas.net/oauth2/token",
  "jwks_uri": "https://authorization-server.saas.net/oauth2/keys",
  "registration_endpoint": "authorization-server.saas.net/oauth2/register",
  "scopes_supported": [
    "agent.read", "agent.write"
  ],
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code", "refresh_token"
  ]
}

GET /oauth2/authorize?response_type=code
  &client_id=eb1e27d2df8b7
  &state=af0ifjsldkj
  &redirect_uri=https%3A%2F%2Ftool.example.com%2Fcb
  &code_challenge_method=S256
  &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U
  &authorization_details=%5B%7B%22type%22:%20%22payment_initiation
  %22,%22actions%22:%20%5B%22initiate%22,%22status%22,%22cancel%22
  %5D,%22locations%22:%20%5B%22https://example.com/payments%22%5D,
  %22instructedAmount%22:%20%7B%22currency%22:%20%22EUR%22,%22amount
  %22:%20%22123.50%22%7D,%22creditorName%22:%20%22Merchant%20A%22,
  %22creditorAccount%22:%20%7B%22iban%22:%20%22DE02100100109307118603
  %22%7D,%22remittanceInformationUnstructured%22:%20%22Ref%20Number
  %20Merchant%22%7D%5D
Host: authorization-server.saas.net

Acknowledgments

The authors wants to acknowledge the support and work of the following indivisuals: Grese Hyseni (Raiffeisen Bank International, grese.hyseni@rbinternational.com), Henrik Kroll (Raiffeisen Bank International, henrik.kroll@rbinternational.com).¶

The authors wants also to recognize the trail blazers and thought leaders that created the ecosystem without which this draft proposal would not be able to solve customer pain points and secure usage of digital services, especially without being limited to: Vittorio Bertocci†, Brian Campbell (Ping Identity), Justin Richer (MongoDB), Aaron Parecki (Okta), Pieter Kasselman (SPRL), Dr Mike Jones (Self-Issued Consulting, LLC), Dr Daniel Fett (Authlete).¶

Authors' Addresses