]> AWS

Canada jeffsec@amazon.com

IndyKite

Canada alex.babeanu@indykite.com

Raiffeisen Bank International

Austria yaron.zehavi@rbinternational.com

Practical Identity

United States of America george@practicalidentity.com

Web Authorization Protocol security trust It is not uncommon for resource servers to require additional information like details of delegation authorization, or assurance proof of the delegation of authorization mechanism used according to the characteristics of a request. This document introduces a mechanism that resource servers can use to signal to a client that the data and metadata associated with the access token of the current request does not meet its authorization requirements and, further, how to meet them. This document also codifies a taxonomy to guide the client into starting a new request towards the authorization server in order to get issued, if applicable, a new set of tokens matching the requirements. 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 mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

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. 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 expected by the resource server. Although those approaches are viable in many situations, it falls short in several important circumstances, for instance, in or 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 and by with one new error code, insufficient_authorization, which can be used by resource servers to signal to clients that the access token presented with the request does not meet the authorization requirements of the resource server. This document also introduces authorization step-up challenges and 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 Authorization Request , OAuth 2.0 Pushed Authorization Request , or OAuth 2.0 JWT-Secured Authorization Request 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.

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. This specification uses the terms "access token", "authorization server", "authorization endpoint", "authorization request", "client", "protected resource", and "resource server" defined by .

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. | | | | | | | |<---------(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 .
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 and section 2.1.10.2.1 of . 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) or is validated via introspection or whether the resource provider is performing this assessment natively or by offloading the assessment to a policy decision point as defined in , or NIST's ABAC . 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 particular 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 , 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 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 for a more detailed discussion).

Step-Up Authorization Challenge

HTTP Error Status Code The resource server responds with a 403 HTTP status code using the Bearer authentication scheme's error parameter (from ) when a request compliant with this specification does not meet its authorization state requirements.

WWW-Authenticate Header Error Code Following other standards like OAuth 2.0 Demonstrating Proof of Possession (DPoP) and in OAuth 2.0 Step Up Authentication Challenge Protocol, the error code of the WWW-Authenticate HTTP Header MUST be set to insufficient_authorization. This will signal that the authorization mechanisms used for the issuance of the access token presented with the request do not meet the authorization state requirements of the protected resource. The client is provided with a response that describes which new authorization mechanisms and details SHOULD be used in order to gain access to the requested resource. The client SHOULD then initiate a new ceremony with the authorization server, that comply with the stated resource requirements. Note: the logic through which the resource server determines that the current request does not meet the authorization state requirements of the protected resource, and associated functionality are out of scope for this document.

WWW-Authenticate Header Description The description field of the WWW-Authenticate HTTP Header MUST be set to The authorization level requires more details.

WWW-Authenticate Header Challenge This document specifies two types of challenge that MAY be used individually or conjointly.

resource_metadata_uri Challenge The resource server MAY return a challenge with the key resource_metadata_uri. When this challenge is present, its value MUST be set to the OAuth2 Protected Resource Metadata Endpoint URI for the resource server as defined in . The metadata endpoint MAY provide information on authorization details expected by the resource server. Note: the logic through which the client determines how to use any information on authorization details expected by the resource server from the metadata endpoint and how to map it to a viable authorization request for the authorization server is out of the scope of this document.

body_instructions Challenge The resource server MAY return a challenge with the key body_instructions When this challenge is present, its value MUST be set to false if no body is associated to the response from the resource server, or true if a body is associated to the response from the resource server.

Challenge Associated Body Content If a body is attached to the to the response from the resource server, it MUST be formatted as an AuthZEN response which MUST contain the following keys:

decision:

REQUIRED - MUST be set to false.

context:

REQUIRED - JSON structure as described below

The context MAY contain the following information

error_msg:

OPTIONAL - a human readable String that summarize the details required

details:

OPTIONAL - a JSON structure representing the expected parameters to be passed by the client to the authorization server if a new authorization request is attempted. This JSON structure MUST be formatted using the syntax defined by

Non Normative Examples Of Step-Up Authorization Challenge The following are non normative examples of some step-up authorization challenges:

resource_metadata_uri challenge and body_instructions challenge expressing a missing expected access token scope:

body_instructions challenge expressing missing authorization_details:

body_instructions challenge expressing missing email as an expected access token claim

body_instructions challenge expressing missing gty, ccr, and cmr as an expected access token claim

• Note: gty, ccr, and cmr are claims defined by

Client Action Following A Step-Up Authorization 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.

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 defined grant flows, a Rich Authorization Request , a Push Authorization Request , or a JWT-Secured Authorization Request 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.

Resource Server Metadata Resource servers can advertise their support of this specification by including in their OAuth protected resource metadata document, as defined in , 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.

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

• OAuth 2.0 ,
• JWT access tokens ,
• Bearer WWW-Authenticate ,
• Token introspection ,
• OAuth2 Protected Resource Metadata ,
• Rich Authorization Request ,
• Push Authorization Request ,
• JWT-Secured Authorization Request and
• AuthZEN

Scope This specification does not attempt to define the mechanics by which access control is made by the resource provider and how the result of such access control evaluation should be translated into one of the challenges defined in Section 4. This specification does not attempt to define the mechanics by which extended authorization requests are processed and validated by the authorization server.

Validation Of Token For this specification, the resource provider MUST examine the incoming access token and enforce the conventional token-validation logic - be it based on JWT validation, introspection, or any other method - before determining whether or not a challenge should be returned.

Step-Up Authorization Challenge Payload Following this document, response from the resource server to the client might unintentionally disclose information about the subject, the resource, the action to be performed, as long as context-specific data such as but not limited to authorization details that an attacker might use to gain knowledge about their target. Implementers should use care in determining what to disclose in the challenge and in what circumstances.

IANA Considerations This document has no IANA actions.

References Normative References 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. 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] This specification defines a profile for issuing OAuth 2.0 access tokens in JSON Web Token (JWT) format. Authorization servers and resource servers from different vendors can leverage this profile to issue and consume access tokens in an interoperable manner. It is not uncommon for resource servers to require different authentication strengths or recentness according to the characteristics of a request. This document introduces a mechanism that resource servers can use to signal to a client that the authentication event associated with the access token of the current request does not meet its authentication requirements and, further, how to meet them. This document also codifies a mechanism for a client to request that an authorization server achieve a specific authentication strength or recentness when processing an authorization request. Asserto Axiomatics SGNL JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification. This specification defines a metadata format that an OAuth 2.0 client or authorization server can use to obtain the information needed to interact with an OAuth 2.0 protected resource. Authlete n.d. 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. Informative References This document specifies a new parameter authorization_details that is used to carry fine-grained authorization data in OAuth messages. 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. The authorization request in OAuth 2.0 described in RFC 6749 utilizes query parameter serialization, which means that authorization request parameters are encoded in the URI of the request and sent through user agents such as web browsers. While it is easy to implement, it means that a) the communication through the user agents is not integrity protected and thus, the parameters can be tainted, b) the source of the communication is not authenticated, and c) the communication through the user agents can be monitored. Because of these weaknesses, several attacks to the protocol have now been put forward. This document introduces the ability to send request parameters in a JSON Web Token (JWT) instead, which allows the request to be signed with JSON Web Signature (JWS) and encrypted with JSON Web Encryption (JWE) so that the integrity, source authentication, and confidentiality properties of the authorization request are attained. The request can be sent by value or by reference. This specification defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token. OAuth 2.0 deployments can use this method to convey information about the authorization context of the token from the authorization server to the protected resource. 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. Hellō Okta SPRIND The OAuth 2.1 authorization framework enables an application to obtain limited access to a protected resource, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and an authorization service, or by allowing the application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 2.0 Authorization Framework described in RFC 6749 and the Bearer Token Usage in RFC 6750. AWS IndyKite This specification defines new claims for JWT profiled access tokens [RFC9068] so that resource providers can benefit from more granular information about the client: its authentication methods as long as the grant flow and the grant flow extensions used as part of the issuance of the associated tokens. Overxeer Entrust NIST NIST NIST BAH MITRE MITRE Scarfone Cybersecurity Authlete Moneyhub Financial Technology Authlete n.d. n.d. n.d.

Use Cases

LLM Agent accessing a service via an LLM Tool on behalf of a user LLM agents, including those based on large language models (LLMs), are designed to manage user context, memory, and interaction state across multi-turn conversations. To perform complex tasks, these agents often integrate with external systems such as SaaS applications, internal services, or enterprise data sources. When accessing these systems, the agent operates on behalf of the end user, and its actions are constrained by the user’s identity, role, and permissions as defined by the enterprise. This ensures that all data access and operations are properly scoped and compliant with organizational access controls. When using an LLM Tool, the LLM Agent is consuming an external API which has its own access control logic and policies on what conditions should be met for the access to the resources and the generation of the enriched information that the AI Agent can send return to the user who prompted it, with potential support of the LLM. Some access control conditions might require some authorization details as defined into, without being limited to, the examples of Rich Authorization Request . A non normative example of such interaction would be at the functional level: | | +--------------+ | | | |-----------------------------------(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 --| | | | +--------------+ +----------+ ]]> Figure 2: Abstract AI Agent Use Case Flow

Preconditions

• The LLM Agent has a registered OAuth 2.0 Client (com.example.llm-agent) with the Enterprise IdP (idp.example.com)
• The LLM Tool has a registered OAuth 2.0 Client (4960880b83dc9) with the Enterprise IdP (idp.example.com)
• The LLM Tool has a registered OAuth 2.0 Client (eb1e27d2df8b7) with External Service IdP (authorization-server.saas.net)
• The External Service APIs is protected by the Trust Domain controlled by the External Service IdP (authorization-server.saas.net)
• User already authenticated at the Enterprise IdP (idp.example.com) and delegated its authorization to the LLM Agent
• The LLM Agent is in possession of an Identity Token, an Access Token, and a Refresh Token issued by the Enterprise IdP (idp.example.com)
• We assume that the Access Token is valid for the duration of this example and possess the appropriate scopes and claims to be authorized to call the LLM Tool

LLM Agent receives a response from the LLM LLM Agent receives a directive to use the LLM Tool with a specific payload and it calls the external LLM Tool provided by an Enterprise internal IT with a valid access token. POST /Pay Host: tool.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K2p3dCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.S9QVKeqooCU7nRahQsPhnV7xOrkqsKB7YKQEReyaWT8 to=DE02100100109307118603& amount=123.50

LLM Tool receives the request LLM tool tries to call the service with the External Service APIs with the Access Token received using the JWT Bearer Authentication scheme (5) and is issued an authentication challenge. HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="new_authorization_needed", error_description="A new authorization request is needed" { "decision": false, "context": { "error_msg": "The user must be authorized to initiate payment for Merchant A ", "details": { "method": "urn:ietf:params:oauth:grant-ext:rar", "authorization_details": [ { "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" } ] } } }

• Note: How agents discover available tools is out of scope of this specification and this example

LLM Agent fetches the external tool resource's OAuth 2.0 Protected Resource Metadata per to dynamically discover an authorization server that can issue an access token for the resource. LLM Agent discovers the Authorization Server configuration per . LLM Agent has learned all necessary endpoints and supported capabilites to obtain an access token for the external tool.

LLM Tool obtains a set of token from Authorization Server protecting the API The LLM tool redirects the LLM Agent for an authorization request:

• We don't describe the way the user is authenticated as it follows Rich Authorization Request

The LLM Tool will receive an Authorization Code that it will be able to exchange for a set of JWTs issued by the Authorization Server protecting the API. The LLM Tool can then make a new request to the External Service APIs (5). If it can meet the APIs Access Control requirement, the flow will follow with a response (6).

Acknowledgments The authors wants to acknowledge the support and work of the following individuals: 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).