]> Zscaler

yrosomakho@zscaler.com

Ping Identity

bcampbell@pingidentity.com

Independent

public@karlmcguinness.com

Defakto Security

pieter@defakto.security

Security Web Authorization Protocol Transaction Authorization Human-in-the-loop Human-on-the-loop Human-out-of-the-loop This document defines an OAuth mechanism for transaction-specific authorization challenges. A protected resource can require additional authorization for a particular operation by returning a transaction authorization challenge. This is useful when requests are mediated by agents, automated workflows, or delegated services and the protected resource requires confirmation from a human user, resource owner, or organizational authority. The client presents the challenge to an authorization server, which validates the challenge, obtains any required approval, and issues an OAuth 2.0 access token whose granted authorization details, expressed using Rich Authorization Requests, describe the approved operation. The access token is then presented to the protected resource as evidence that the challenged operation was authorized. 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 () access tokens authorize access to protected resources. In many deployments, however, a protected resource cannot determine whether a requested operation is acceptable based only on the access token that accompanies the request. The access token might establish that the caller is authorized to interact with the protected resource, but a particular operation can still require additional, transaction-specific authorization. This situation arises when the protected resource needs confirmation that a concrete transaction has been approved by an appropriate party. The approving party might be the human user on whose behalf the request is made, a different resource owner, or an organizational authority such as an administrator, manager, data owner, or policy decision point. This document defines a transaction authorization challenge. A protected resource uses this challenge to request additional authorization for a specific operation. The challenge is relayed to a client, which presents it to an authorization server. The authorization server validates the challenge, obtains any required approval, and issues an OAuth 2.0 access token whose granted authorization details, expressed using Rich Authorization Requests (), describe the approved operation and bind the access token to the challenged transaction. The access token is then presented to the protected resource as evidence that the challenged operation was authorized. Reusing the OAuth 2.0 access token abstraction avoids defining a new bearer artifact and allows existing access-token validation and protection mechanisms, including sender-constrained access tokens, to apply unchanged. This mechanism is complementary to OAuth step-up authentication defined in . Step-up authentication enables a protected resource to require stronger or fresher authentication of a user. A transaction authorization challenge instead requests authorization for a specific transaction. The approving party can be different from the subject associated with the access token used for the original request. Automated clients, including AI agents, are deployed with different levels of human oversight . With human-in-the-loop (HITL), a person approves an action before it is taken. With human-on-the-loop (HOTL), actions proceed and a person can intervene or stop them. With human-out-of-the-loop (HOOTL), no person is involved when the action is taken, and authorization is decided by policy that a person previously approved. This document supports all three modes by letting the authorization server obtain approval asynchronously from the appropriate party.

Human Approval for Agent-Mediated Actions Software agents, automated workflows, and delegated services can perform operations on behalf of users. Some operations are sufficiently sensitive that a protected resource might require explicit approval before processing them. Examples include sending a payment, publishing content, deleting data, modifying access policy, or disclosing sensitive information. Local confirmation mechanisms within an agent framework can reduce risk, but they are not always visible to the protected resource and do not necessarily produce authorization evidence that the protected resource can validate. A transaction authorization challenge allows the protected resource to require explicit authorization for the concrete operation and to receive an access token representing that authorization.

Authorization by a Different Resource Owner The party that initiated an operation is not always the party authorized to approve it. For example, an agent acting on behalf of one user might request access to a resource owned or controlled by another user. The protected resource can determine that approval from the resource owner, or from another party authorized to act for that resource owner, is required before the operation can proceed. In this case, the transaction authorization challenge allows the protected resource to describe the requested operation and the authorization server to determine the appropriate approving party. The resulting access token represents authorization of the challenged operation by the party selected according to authorization server policy.

Organizational Approval Some operations require approval by an organizational authority rather than by an individual end user. Examples include approving access to regulated data, authorizing a production deployment, granting elevated administrative access, or permitting data transfer to an external party. A transaction authorization challenge allows the protected resource to request authorization evidence from an authorization server or associated policy infrastructure. The authorization server validates the challenge, applies organizational policy, obtains any required approval, and issues an access token only when the required authorization has been obtained.

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 document uses the terms "client", "authorization server", "access token", "refresh token", and "protected resource" as defined by . This document uses the term "authorization details" as defined by . This document defines the following additional terms:

Approving Party:

The human user, resource owner, organizational authority, or policy authority whose approval is required before the challenged transaction can proceed.

Agent:

A software component, automated workflow, delegated service, or other intermediary that attempts an operation at a protected resource and relays a transaction authorization challenge to a client.

Transaction Authorization Challenge:

A challenge returned by a protected resource to indicate that a specific requested operation requires transaction-specific authorization before it can proceed.

Human-in-the-Loop (HITL):

A mode of operation in which a person approves an action before it is taken.

Human-on-the-Loop (HOTL):

A mode of operation in which actions proceed without prior approval and a person monitors them and can intervene or stop them.

Human-out-of-the-Loop (HOOTL):

A mode of operation in which no person is involved when an action is taken, and authorization is decided by policy that a person previously approved.

Architecture A transaction authorization challenge involves a protected resource, an agent, a client, an authorization server, and an approving party. The protected resource receives a request and determines whether the authorization currently presented with the request is sufficient. If the protected resource determines that the requested operation requires transaction-specific authorization, it returns a transaction authorization challenge. The agent is the component that attempted the operation at the protected resource. The agent relays the transaction authorization challenge to the client and later presents the resulting access token to the protected resource. The agent is not trusted to modify the contents of the challenge or the resulting access token. The client receives the transaction authorization challenge from the agent and presents it to the authorization server. The client is responsible for mediating the interaction between the agent-facing environment and the authorization server. The client does not need to interpret all application-specific details of the challenged transaction, but it MUST preserve the integrity of the challenge when presenting it to the authorization server. The authorization server validates the transaction authorization challenge, determines the approving party, obtains any required approval, and issues an access token whose granted authorization details describe the approved operation. The authorization server can use local policy, resource metadata, resource-owner information, organizational policy, or other authorization context to determine whether the requested operation can be approved. The approving party is the human user, resource owner, organizational authority, or policy authority whose approval is required. The approving party can be the same subject on whose behalf the agent is acting, but this is not required. The following figure shows the basic protocol flow:

Overall architecture of Transaction Authorization Challenge | Agent |<------>| Protected Resource | +----------+ +-------+ +--------------------+ | | transaction authorization challenge v +----------------------+ | Authorization Server | +----------------------+ | | approval interaction v +-----------------+ | Approving Party | +-----------------+ ]]>

The flow is as follows:

1. The agent sends a request to the protected resource using its existing authorization context.
2. The protected resource determines that the request requires transaction-specific authorization.
3. The protected resource returns a transaction authorization challenge to the agent.
4. The agent relays the transaction authorization challenge to the client.
5. The client presents the transaction authorization challenge to the authorization server.
6. The authorization server validates the challenge, determines the approving party, and obtains any required approval.
7. The authorization server issues an access token to the client. The access token's granted authorization details describe the approved operation, and the access token is bound to the challenged transaction.
8. The client provides the access token to the agent.
9. The agent retries or continues the request and presents the access token to the protected resource.
10. The protected resource validates the access token, including its authorization details, and processes the request if the token authorizes the challenged operation.

Transaction Authorization Challenge A transaction authorization challenge is a signed JWT () generated by a protected resource to request transaction-specific authorization for a particular operation. The challenge describes the operation to be authorized, identifies the authorization server expected to process the challenge, identifies the intended audience of the resulting access token, and contains freshness and integrity protection. It can also identify a key to which the resulting access token is bound (). The challenge is consumed by the authorization server and can also be validated by the client before the client presents it to the authorization server. The agent relays the challenge, but it is not trusted to modify the challenge or to describe the challenged transaction.

Challenge Capability Signal An agent indicates that it supports the transaction authorization challenge mechanism by sending the Accept-Txn-Challenge header field with a true value in requests to a protected resource. The Accept-Txn-Challenge header field is an Item Structured Field; see . Its value MUST be a Boolean. Any other value type MUST be handled by recipients as if the field were not present. For example, if this field is included multiple times, its type will become a List and the field will be ignored. This document does not define any parameters for the Accept-Txn-Challenge header field value, but future documents might define parameters. Receivers MUST ignore unknown parameters. The following example indicates support for transaction authorization challenges:

Agent indicating support for transaction authorization

An Accept-Txn-Challenge header field with a false value has the same semantics as when the header field is not present. An agent MUST NOT include the Accept-Txn-Challenge header field unless it has a client interaction path capable of relaying the challenge to a client that can validate the challenge and present it to an authorization server. A protected resource MUST NOT return a transaction authorization challenge, or a response requesting establishment of a binding key as defined in , unless the request includes an Accept-Txn-Challenge header field with a true value, or the protected resource has out-of-band knowledge that the client supports this specification.

Challenge Response When a protected resource requires transaction-specific authorization, it returns an HTTP error response indicating that transaction authorization is required. This document defines the OAuth error code transaction_authorization_required for this purpose. For example, in response to a request with a DPoP-bound access token:

Protected resource requesting transaction authorization

The challenge uses the authentication scheme of the access token in the request () or, if there is none, a scheme that the protected resource accepts. The transaction_challenge parameter contains a transaction authorization challenge encoded as a JWS Compact Serialization object as specified in . The challenge MUST be signed by the protected resource. The parameter is absent only when the operation requires a binding key that the request does not provide (). The error_description parameter MAY be included to provide a human-readable diagnostic description. The error_description parameter MUST NOT be used as the basis for an authorization decision. A protected resource SHOULD use status code 401 when the request was understood but requires additional transaction-specific authorization. Other status codes MAY be used when appropriate for the application protocol.

Challenge Representation A transaction authorization challenge is a JWT secured using JWS. The JOSE header typ value MUST be txn-authz-challenge+jwt. The alg value MUST identify an asymmetric digital signature algorithm. The alg value MUST NOT be none. The kid value in the JOSE header is used to identify the signing key in the protected resource's JWK Set. The challenge claims identify the protected resource, the authorization server expected to process the challenge, the transaction being authorized, and the intended audience of the resulting access token.

Challenge Claims A transaction authorization challenge MUST contain the following claims:

iss:

Issuer claim defined in . Identifier of the protected resource that generated the challenge. The access token issued in response to the challenge MUST use this value as its audience unless an application profile defines a different audience binding.

aud:

Audience claim defined in . Identifier of the authorization server expected to validate the challenge and issue an access token for the challenged operation. The value is selected by the protected resource and need not be the issuer of the access token presented with the original request. The protected resource MUST select an authorization server that it trusts to evaluate the challenge and issue access tokens for the requested operation.

iat:

Issued At claim defined in . Time at which the challenge was issued.

exp:

Expiration Time claim defined in . Time at which the challenge expires.

jti:

JWT ID claim defined in . Unique identifier for the challenge object.

txn:

Transaction Identifier claim defined in . Transaction identifier for the challenged operation. in response to the challenge MUST contain the same transaction identifier. The transaction identifier MUST be unique within the context of the protected resource for the lifetime of the challenge and any access token issued in response to it.

authorization_details:

Claim containing Authorization Details as defined in . Structured description of the operation for which transaction-specific authorization is requested. The granted authorization details carried by the access token issued in response to the challenge are derived from this value.

reason:

Human-readable explanation of why transaction-specific authorization is required. This value is intended for display to the client, the user, or the approving party. The value is integrity protected as part of the challenge.

A transaction authorization challenge MAY contain the following claims:

cnf:

Confirmation claim identifying the key to which the authorization server binds the issued access token (). Unlike cnf in a sender-constrained access token (, ), the party presenting the challenge need not hold the key; it is held by the party that sent the request that triggered the challenge, which can be the client itself. The claim contains exactly one confirmation method. As permits, an authorization server that does not support that method rejects the challenge instead of ignoring the member.

reason_uri:

URI identifying additional information about the transaction authorization request. The URI MUST be controlled by the protected resource or by a party trusted by the protected resource. The client and authorization server MAY dereference this URI to obtain additional information for display or policy evaluation.

act:

Actor claim defined in . Information about the actor or delegation context associated with the request that caused the challenge. The value identifies the party that attempted the challenged operation, or the delegated actor acting on behalf of another party.

The challenge MAY contain additional claims. The authorization server MUST ignore claims it does not understand unless local policy requires otherwise. Information obtained from reason_uri MUST NOT override the security-relevant contents of the signed challenge unless an application profile defines how that information is authenticated and bound to the challenge. Application profiles MAY define additional claims that bind the challenge to the original request or to selected security-relevant request components. The following example shows the claims of a transaction authorization challenge:

Example transaction authorization challenge

Challenge Signing and Key Discovery A protected resource that issues transaction authorization challenges MUST sign each challenge using an asymmetric signing key. The client and authorization server MUST validate the challenge signature before using any claim from the challenge for an authorization decision or for display to the user. A protected resource that issues transaction authorization challenges MUST make the public keys needed to validate those challenges available to clients and authorization servers. This document defines protected resource metadata parameters, using the OAuth 2.0 Protected Resource Metadata mechanism described in . Deployments MAY also use preconfigured trust relationships or other mechanisms to establish the same keying information. This document defines the following protected resource metadata parameters:

txn_challenge_jwks_uri:

URL of the protected resource's JSON Web Key Set containing public keys used to validate transaction authorization challenges.

txn_challenge_signing_alg_values_supported:

JSON array containing the JWS alg values supported by the protected resource for transaction authorization challenges.

If a protected resource uses the same JWK Set for transaction authorization challenges and for other protected resource signing keys, the value of txn_challenge_jwks_uri MAY be the same as another JWK Set URI published by the protected resource. When the challenge-signing key is published in the JWK Set identified by txn_challenge_jwks_uri, the kid value in the JOSE header of a transaction authorization challenge MUST identify the signing key in that JWK Set. If the challenge cannot be validated, the client or authorization server MUST NOT treat the challenge as authentic.

Access Token Key Binding A protected resource can request that the access token issued for a challenge be bound to a key by including in the challenge a cnf claim that identifies that key (the binding key). The binding key is a key that the sender of the triggering request demonstrated possession of when sending that request. The triggering request is the request to the protected resource that caused the challenge to be issued; it can be sent by an agent or by a client. The authorization server binds the issued access token to the binding key (). The binding key comes from a sender-constrained access token in the triggering request () or, otherwise, from a DPoP proof or client certificate sent with that request (). The protected resource MUST validate the access token, including any sender constraint, and if validation fails, returns the error response specified for that access token (, , ). A protected resource SHOULD include a binding key in the challenge whenever the access token in the triggering request is sender-constrained, and for high-impact or non-idempotent operations. It MUST NOT do so unless it knows, for example by configuration, that the authorization server supports binding keys in challenges with the confirmation method used.

Using an Existing Token Binding If the access token in the triggering request is sender-constrained, the cnf claim identifies its key, using the confirmation method and value verified when validating that access token. A DPoP proof sent with an access token bound using mutual-TLS is not used for cnf. The protected resource rejects a DPoP-bound access token sent with the Bearer scheme ().

Establishing a Binding Key If the triggering request does not contain a sender-constrained access token, the protected resource can take the binding key from a DPoP proof or a mutual-TLS client certificate sent with the access token, which is presented using the Bearer scheme. Whether an access token is sender-constrained is determined from the token itself, such as its cnf claim or introspection response, not from the authentication scheme. This document extends , which defines DPoP proofs at a protected resource only for DPoP-bound access tokens (). Such a proof only determines the binding key; it does not authenticate the request or authorize access. To include a binding key in the challenge, the protected resource processes a request that does not contain a sender-constrained access token as follows:

1. If the operation requires a binding key and the request contains no access token, the protected resource ignores any DPoP proof and responds as specified in , including a DPoP challenge if it accepts DPoP-bound access tokens.
2. If the request contains a DPoP proof, the protected resource MUST validate it as specified in , omitting the key comparison in item 12; the proof MUST contain an ath claim (). If the proof is not valid, it returns a 401 (Unauthorized) response with a Bearer challenge that contains algs and the invalid_dpop_proof error or, if a nonce that it requires () is missing or unacceptable, the use_dpop_nonce error with a DPoP-Nonce header field.
3. The key of the DPoP proof (jkt, ) or, if there is none, of the mutual-TLS client certificate (x5t#S256, ) shows only that the sender of the request holds it (). If the challenge would contain requester context derived from the access token, such as an act claim, the protected resource MUST NOT use that key unless it authenticates the key holder and verifies that the holder is authorized to act in that requester context.
4. If the protected resource can use that key and the authorization server supports its confirmation method (), the cnf claim of any transaction authorization challenge for the request identifies it. Otherwise, a challenge for the request has no cnf claim, and if the operation requires a binding key, the next step applies.
5. If the operation requires a binding key and the request does not establish a key that the protected resource can use, it returns a 401 (Unauthorized) response with:
   • if it can use the key of a DPoP proof for this operation and requester context and the authorization server supports jkt, a Bearer challenge with the binding_key_required error and algs; or
   • if it requires a sender-constrained access token, a Bearer challenge with the transaction_authorization_required error and no transaction_challenge, and, if it accepts DPoP-bound access tokens, a DPoP challenge with algs ().

The binding_key_required error indicates that the operation requires a binding key and that repeating the request with the same access token and a DPoP proof can provide it. This document defines algs as a Bearer authentication parameter () with the meaning given in . A DPoP challenge can accompany the Bearer challenge if the protected resource accepts DPoP-bound access tokens, but the retry does not need it. Without a transaction_challenge parameter, the transaction_authorization_required error indicates that the request needs to be repeated with a sender-constrained access token, such as a DPoP-bound or certificate-bound access token. To avoid the binding_key_required round trip, a request that contains the Accept-Txn-Challenge header field with a true value can include a DPoP proof from the start. For example, a protected resource requests a DPoP proof:

Protected resource requesting a DPoP proof for a binding key

The request is then repeated with the same access token and a DPoP proof:

Repeating a request with a DPoP proof for a binding key

The DPoP proof is formed as specified in , with ath computed over the bearer access token. The JWK SHA-256 thumbprint of its key is the jkt value in the cnf claim of the resulting challenge.

Agent Relay After receiving a transaction authorization challenge from a protected resource, the agent relays the challenge to the client using a deployment-specific client-agent protocol. The agent MUST relay the transaction authorization challenge without modifying it and MUST NOT replace it with an agent-generated description of the requested operation. The client MUST treat any agent-supplied description as advisory. Any authorization decision, user display, or disclosure decision MUST be based on the validated challenge or on protected resource state identified by the validated challenge. A client-agent protocol that carries transaction authorization challenges SHOULD distinguish a transaction authorization challenge from ordinary agent messages or natural-language content. For example, such a protocol can carry the challenge using a field named transaction_challenge whose value is the JWS Compact Serialization of the transaction authorization challenge. In deployments where one agent delegates work to another agent, a transaction authorization challenge MAY be relayed through one or more intermediate agents before reaching the client. Each agent that relays the challenge MUST relay it without modification. An intermediate agent MUST NOT replace the challenge with a new challenge unless it is itself acting as a protected resource for a distinct operation and generates a new signed transaction authorization challenge for that operation.

Client Processing Before presenting the challenge to the authorization server, the client MUST validate the challenge signature, issuer, audience, and expiration. The client MUST verify that the aud claim identifies the authorization server to which the client intends to present the challenge. The client MAY display the challenge contents to the user before sending the challenge to the authorization server. This allows the user to decide whether to continue and whether to disclose the challenged transaction to the authorization server. When displaying challenge information, the client MUST use information obtained from the validated challenge or from protected resource state identified by the validated challenge. The client MUST NOT rely on an unprotected description supplied by the agent. If the user declines to continue, or if the client cannot validate the challenge, the client MUST NOT present the challenge to the authorization server.

Authorization Server Processing The authorization server MUST validate the transaction authorization challenge before accepting it for processing or issuing an access token. At a minimum, the authorization server MUST verify that:

• the challenge signature is valid;
• the challenge was issued by a protected resource recognized by the authorization server;
• the challenge has not expired;
• no challenge with the same iss and jti values has previously been accepted for processing, unless the same client resubmits it, in which case the authorization server continues the original transaction authorization request; the authorization server retains this state until the challenge expires;
• the aud claim identifies the authorization server;
• the authorization server is willing to issue access tokens for the protected resource identified by the iss claim and for the requested operation;
• the access token issued in response to the challenge will use the protected resource identified by the iss claim as its audience, unless an application profile defines a different audience binding;
• the txn claim is present, is a string, and is acceptable;
• the requested operation is sufficiently described;
• the client is permitted to request transaction authorization for the challenged operation;
• if the challenge contains a cnf claim, that claim contains exactly one confirmation method, jkt or x5t#S256, with a well-formed value, and the authorization server supports it ().

When requester context, such as the act claim, is present in the challenge, the authorization server MUST consider that context when determining whether the challenged operation can be approved. The authorization server MUST NOT treat cnf as identifying or authenticating the requester. The authorization server determines the approving party according to local policy. The approving party can be the subject associated with the original request, a different resource owner, an administrator, an organizational approval workflow, or another policy authority. The authorization server MUST obtain any required approval before issuing an access token. The authorization server SHOULD present the approving party with sufficient information to understand the operation being authorized. The authorization server MUST NOT rely on an unprotected description supplied by the agent as the basis for the authorization decision. If the authorization server accepts the challenge for processing, the client obtains the result using the transaction authorization flow described in . If the authorization server rejects the challenge, cannot validate the challenge, or cannot obtain the required approval, it MUST NOT issue an access token for the challenged operation. When the challenge contains a cnf claim, the authorization server MUST bind the access token to the key identified by cnf as specified in or , with token_type DPoP for jkt () or Bearer for x5t#S256, and MUST NOT bind it to any other key. It MUST NOT issue a refresh token, because a refreshed access token would be bound to a key that the client proves (). The authorization server does not verify possession of the binding key and does not require the client to demonstrate it; it relies on the protected resource identified by the iss claim, which verified possession on the triggering request and asserts the key in the signed challenge (). Client authentication still applies. As an exception to , the authorization server does not require a DPoP proof on a transaction authorization request whose challenge contains a cnf claim, or on a poll for that request, even if the client's dpop_bound_access_tokens metadata is true.

Transaction Authorization Flow The client presents the transaction authorization challenge to the token endpoint () using the transaction authorization grant defined in this document. When the authorization server cannot issue a token response immediately, for example because satisfying the challenge requires approval from the resource owner, an administrator, or an organizational policy authority, it uses the OAuth Deferred Token Response mechanism , with the transaction authorization grant as the originating grant. A token response to the grant (returned immediately or, after deferral, on a polling request) authorizes the challenged operation. A deferred response is not a token response: it only indicates that the authorization server has accepted the challenge for processing. The level of human oversight is a deployment choice and does not change the protocol. The client uses the same grant and the same deferred token response flow whether the challenge is approved by a person before the operation proceeds (HITL), approved automatically subject to human monitoring and intervention (HOTL), or approved by policy a person established in advance (HOOTL). The following figure shows the transaction authorization flow when the request is deferred:

Transaction authorization flow using a deferred token response | | | | | | 400 authorization_pending | | | deferral_code, interval | | |<----------------------------------------| | | | Approval Request | | |------------------------>| | | | | POST /token grant: deferred | | | deferral_code | | |---------------------------------------->| | | 400 authorization_pending | | |<----------------------------------------| | | | Approval Result | | |<------------------------| | | | | POST /token grant: deferred | | | deferral_code | | |---------------------------------------->| | | 200 token response (access token) | | |<----------------------------------------| | | | | ]]>

Transaction Authorization Grant This document defines the grant type urn:ietf:params:oauth:grant-type:txn-authz-challenge. The client presents a validated challenge (relayed to it by the agent) by making a token request to the token endpoint with the following parameters in the application/x-www-form-urlencoded request body:

grant_type:

REQUIRED. MUST be urn:ietf:params:oauth:grant-type:txn-authz-challenge.

transaction_challenge:

REQUIRED. The transaction authorization challenge received from the protected resource.

completion_mode:

OPTIONAL. Including the value deferred, as defined by , signals that the client accepts a deferred token response. Because the approval that satisfies a challenge is typically asynchronous, a client SHOULD include deferred. An authorization server MUST NOT return a deferred response to a client that has not signaled deferred. If the authorization server cannot approve the operation synchronously for such a client, it MUST return the access_denied error (); the client can then repeat the request with deferred included in completion_mode.

client_id:

REQUIRED if the client is not authenticating with the authorization server as described in .

The client authentication requirements of apply, and requests MUST use TLS following the best practices of . The authorization server MUST validate the challenge as described in before accepting the request. If the challenge fails validation, the error code is invalid_grant () unless a more specific code applies, such as unauthorized_client for a client that is not permitted to request transaction authorization for the operation. For example, a public client, which requires to present a DPoP proof () on this request, sends the following request:

Transaction authorization grant request

Deferred Processing and Polling If the authorization server can approve the challenged operation without further interaction, it returns a token response as described in . Otherwise, if the client signaled completion_mode=deferred, the authorization server returns a deferred token response as defined in : an HTTP 400 response whose body carries the authorization_pending or interaction_required error code, a deferral_code, an expires_in, and an interval. The client then polls the token endpoint using the deferred grant of (grant_type=urn:ietf:params:oauth:grant-type:deferred with the deferral_code) until it receives a token response or a terminal error. The polling cadence, the interaction_required, slow_down, expired_token, and access_denied errors, optional completion-callback notifications, and cancellation via the revocation endpoint are all as defined in . When approval requires interaction that the client can facilitate, the authorization server returns interaction_required with an interaction_uri, on the deferred response or on a later polling response, as defined in . The client presents the interaction_uri to the user or other approving party, or opens it in a user agent, and continues polling. The deferral_code is sender-constrained as defined in ; this protects the polling credential. If the challenge contains a cnf claim, the access token issued on a polling request is bound to the key identified by cnf (), even if binds the deferral_code to the client's DPoP key. Otherwise, if the client presents a DPoP proof on the transaction authorization grant request, as requires of a public client, binds both the deferral_code and the access token later issued on a polling request to the client's DPoP key; if it does not, the format and binding of the issued access token are as described in . The txn value correlates the challenge, the issued token, and any re-evaluation.

• Editor's note: When the client presents a DPoP proof, binding the access token to the key identified by cnf conflicts with , which requires the access token to be bound to the client's DPoP key in both its sender-constraint requirements and its sender-constraining continuity guarantee. Resolving this requires to let the originating grant define how the issued access token is bound, separately from the binding of the deferral_code.

For example, the authorization server returns a deferred response, and the client then polls:

Deferred token response

Polling a deferred transaction authorization request

Discovery An authorization server indicates support for this mechanism by including urn:ietf:params:oauth:grant-type:txn-authz-challenge in the grant_types_supported value of its metadata , and by setting the deferred_token_response_supported metadata parameter defined in to true.

Successful Access Token Response If the transaction authorization request is approved, the authorization server returns an access token response. The response uses the access token response format defined in and the authorization_details response parameter defined in . The granted authorization_details value MUST describe the operation approved for the challenged transaction and MUST be derived from the authorization_details claim of the transaction authorization challenge. The authorization server MAY normalize, narrow, or otherwise constrain the granted authorization details relative to those requested by the challenge, but MUST NOT broaden them. The authorization_details parameter in the token response is returned by the authorization server as required by Section 7 of and conveys the authorization details as granted, which MAY differ from those requested in the challenge. This response parameter is informational for the client. The protected resource MUST determine authorization from the granted authorization details bound to the access token (see ), and MUST NOT rely on the token response parameter. The access token MUST contain the txn value from the transaction authorization challenge, MUST be bound to the granted authorization details, and MUST use the iss value from the transaction authorization challenge as its audience unless an application profile defines a different audience binding. The authorization server MAY issue this access token in any access token format negotiated with the protected resource; when JWT access tokens defined in are used, the txn and authorization_details claims are included as defined in and respectively. The access token issued in response to a transaction authorization challenge is scoped to the challenged operation and MUST NOT be accepted as authorization for any operation that is not described by its granted authorization details. For example:

Successful access token response

The access token MUST have a limited lifetime. The authorization server SHOULD issue the access token with a short lifetime because it represents authorization for a specific operation. When the challenge contains a cnf claim, the access token is sender-constrained to the key identified by cnf, using DPoP or mutual-TLS (). Otherwise, the authorization server MAY sender-constrain the access token to a key that the client proves; only the client can then present it. A client that relays the access token to an agent also relays its token_type. The client need not possess the binding key or generate DPoP proofs; the agent presents the access token using the indicated token type.

Access Token The access token issued in response to a transaction authorization challenge represents authorization for the challenged operation. It is an OAuth 2.0 access token whose granted authorization details, expressed using the authorization_details parameter and claim defined in , describe the operation that was approved. The access token is issued by the authorization server identified by the aud claim of the transaction authorization challenge and is presented to the protected resource that issued the challenge. The access token MUST contain sufficient information for the protected resource to determine that the token authorizes the challenged operation. At a minimum, the access token MUST be bound to the txn value from the challenge and MUST carry granted authorization details that describe the approved operation. The granted authorization details MAY be the value of the authorization_details claim from the challenge, a value derived from it, or a reference to protected resource state agreed between the protected resource and the authorization server. When requester context, such as the act claim, is present in the transaction authorization challenge, the authorization server MUST include equivalent requester context in the access token or otherwise bind the access token to that context. This access token is scoped to the challenged operation. Clients and protected resources MUST NOT assume that the access token issued in response to a transaction authorization challenge confers authorization beyond the operation described by its granted authorization details.

Token Presentation The client provides the access token to the agent. The agent presents the access token to the protected resource together with the request for the challenged operation. In deployments where one agent delegates work to another agent, the access token MAY be relayed through one or more intermediate agents before being presented to the protected resource. Each agent that relays the access token MUST relay it without modification. An agent MUST NOT use the access token for a different transaction, different protected resource, or different requester context. When the challenge contains a cnf claim, only the holder of the key identified by cnf can present the access token; an agent acting for another agent can obtain its own challenge. When HTTP is used, the access token MUST be presented to the protected resource as defined by . Bearer access tokens are presented using the Authorization request header field as specified in . Sender-constrained access tokens are presented using the mechanism defined by the corresponding access token format, for example or . For example:

Presenting the access token to a protected resource

The agent MUST NOT modify the access token. If the agent cannot present the access token to the protected resource, the challenged operation cannot be completed using this mechanism.

Protected Resource Validation Before accepting the access token as authorization for a challenged operation, the protected resource MUST validate the access token according to , the access token format in use, and the requirements of this document. At a minimum, the protected resource MUST verify that:

• the access token was issued by the authorization server identified by the aud claim of the transaction authorization challenge;
• the access token audience identifies the protected resource, unless an application profile defines a different audience binding;
• the access token has not expired;
• the access token is bound to the same txn value as the transaction authorization challenge;
• if the challenge, as recorded by the protected resource, contains a cnf claim, the access token is sender-constrained with the confirmation method and value in that claim, and the request satisfies that constraint (, );
• the granted authorization details associated with the access token authorize the requested operation and are consistent with the authorization_details claim of the transaction authorization challenge;
• any requester context required by the transaction authorization challenge is present and matches the challenged transaction;
• no access token for the same txn value has previously been accepted, if the protected resource requires single use for the challenged operation.

A protected resource MUST reject an access token that does not correspond to the transaction authorization challenge for the requested operation. A protected resource SHOULD treat access tokens issued in response to a transaction authorization challenge as single-use when the challenged operation is non-idempotent or high impact. If single-use semantics are required, the protected resource MUST maintain sufficient state to detect replay of the transaction identifier. The protected resource MUST NOT accept an access token issued in response to a transaction authorization challenge as general authorization for operations other than the challenged operation. In particular, the protected resource MUST NOT honour the granted authorization details of such an access token for any operation that is not the challenged operation described by those authorization details.

Security Considerations Transaction authorization challenges and the access tokens issued in response to them are security-sensitive artifacts. A transaction authorization challenge requests authorization for a specific operation, and the access token issued in response represents evidence that the challenged operation was authorized. Implementations need to ensure that these artifacts cannot be modified, replayed, substituted, or used for a different operation. A protected resource MUST sign each transaction authorization challenge using an asymmetric signing key. Clients and authorization servers MUST validate the challenge signature before using any claim from the challenge for display, policy evaluation, or authorization decisions. If a challenge cannot be validated, it MUST NOT be treated as authentic. The authorization server MUST verify that the aud claim identifies the authorization server and that the protected resource identified by the iss claim is trusted to request transaction authorization for the requested operation. An authorization server MUST NOT issue an access token for a challenge issued by an unrecognized or unauthorized protected resource. The transaction authorization challenge and the resulting access token MUST be bound to the same transaction identifier. The protected resource MUST verify that the txn value bound to the access token matches the txn value from the challenge. An access token issued in response to a transaction authorization challenge MUST NOT be accepted as authorization for any operation other than the challenged operation. Access tokens issued in response to a transaction authorization challenge can be replayed if they are not sufficiently constrained. Authorization servers MUST issue these access tokens with short lifetimes, and protected resources can require key binding (). Protected resources SHOULD treat these access tokens as single-use for non-idempotent or high-impact operations, and maintain sufficient state to detect replay where single-use semantics are required. A binding key protects the access token issued for a challenge. The cnf claim is part of the signed challenge, so a party that relays the challenge cannot remove or replace the binding key. A party that does not hold the binding key, such as an intermediate agent, cannot present the access token. If that party submits the challenge itself, the resulting access token is bound to the same key, so it cannot present that token either. The authorization server accepts a challenge only once, so such a party can at most prevent the transaction from completing. The strength of this protection depends on where the binding key comes from. If it is the key of a sender-constrained access token, a party that captured that token cannot substitute its own key. If it comes from a DPoP proof or a client certificate, it only shows that the sender of the triggering request holds the key. A party that obtained a bearer access token can then obtain a challenge with its own key as the binding key. Any requester context derived from that access token, such as an act claim (), still identifies the original requester to the approving party. For this reason, restricts this source of binding keys when the challenge would contain such requester context. Key binding does not replace single use (), because the holder of the key can present the access token more than once. Because the access token issued in response to a transaction authorization challenge carries granted authorization details that describe a specific operation, protected resources MUST evaluate those authorization details against the operation being requested. Accepting such an access token without evaluating its authorization details would allow a token issued for one operation to authorize a different operation. The agent is not trusted to modify or summarize the challenge. Clients and authorization servers MUST NOT rely on an unprotected description supplied by the agent as the basis for user display, policy evaluation, or authorization decisions. Information presented to the user or approving party SHOULD be derived from the validated challenge, from protected resource state identified by the challenge, or from information otherwise authenticated and bound to the challenge. When requester context is relevant to the authorization decision, the protected resource SHOULD include that context in the challenge, for example using the act claim. The authorization server MUST consider requester context when it is present. This helps prevent an approval obtained for one agent, client, user, or delegation context from being used to authorize a transaction initiated by another requester. The client can inspect the challenge before presenting it to the authorization server. This is important because the challenge can contain sensitive information about the requested operation, user intent, protected resources, or organizational policy. Clients SHOULD allow the user to decline before disclosing the challenge to the authorization server when the challenge contains privacy-sensitive transaction details. Challenges and the access tokens issued in response to them can reveal sensitive information if logged or exposed to unintended parties. In particular, the granted authorization details carried by the access token can describe the operation in detail. Implementations SHOULD minimize the information included in challenges and in the granted authorization details of the access token, avoid logging them unless necessary, and protect them in transit and at rest. Application profiles that define additional challenge claims, request binding mechanisms, or alternative audience bindings MUST describe how those extensions preserve challenge integrity, prevent replay and substitution, and avoid confused-deputy attacks.

IANA Considerations This document registers the Accept-Txn-Challenge HTTP field name, two OAuth error codes, one OAuth parameter, one OAuth grant type, two OAuth Protected Resource Metadata parameters, and two JWT claims. It relies on the deferred token response registrations (the completion_mode and interaction_uri parameters, the deferred grant type, the deferral-code type, and the token endpoint usage of the interaction_required error) defined by .

HTTP Field Name Registration IANA is requested to register the following field name in the "HTTP Field Name" registry as a structured Header Field:

Field Name:

Accept-Txn-Challenge

Status:

permanent

Structured Type:

Item

Reference:

this document

OAuth Extensions Error Registration IANA is requested to register the following error values in the "OAuth Extensions Error" registry :

Error name:

transaction_authorization_required

Usage location:

resource access error response

Protocol extension:

OAuth Transaction Authorization Challenge

Change controller:

IETF

Reference:

this document

Error name:

binding_key_required

Usage location:

resource access error response

Protocol extension:

OAuth Transaction Authorization Challenge

Change controller:

IETF

Reference:

of this document

OAuth Parameter Registration IANA is requested to register the following parameters in the "OAuth Parameters" registry :

Name:

transaction_challenge

Parameter Usage Location:

WWW-Authenticate response, token request

Change controller:

IETF

Reference:

this document

OAuth Protected Resource Metadata Registration IANA is requested to register the following values in the "OAuth Protected Resource Metadata" registry .

Metadata name:

txn_challenge_jwks_uri

Metadata description:

URL of the protected resource's JSON Web Key Set containing public keys used to validate transaction authorization challenges.

Change controller:

IETF

Reference:

this document

Metadata name:

txn_challenge_signing_alg_values_supported

Metadata description:

JSON array containing the JWS alg values supported by the protected resource for transaction authorization challenges.

Change controller:

IETF

Reference:

this document

OAuth URI Registration IANA is requested to register the following value in the "OAuth URI" registry , in accordance with .

URN:

urn:ietf:params:oauth:grant-type:txn-authz-challenge

Common Name:

Grant type URI for presenting an OAuth transaction authorization challenge to the token endpoint.

Change controller:

IETF

Reference:

this document

 JSON Web Token Claims Registration IANA is requested to register the following claims in the "JSON Web Token Claims" registry .

Claim Name:

reason

Claim Description:

Human-readable explanation of why authorization, confirmation, or other processing is required.

Change Controller:

IETF

Reference:

this document

Claim Name:

reason_uri

Claim Description:

URI identifying additional information about why authorization, confirmation, or other processing is required.

Change Controller:

IETF

Reference:

this document

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] This document specifies a new parameter authorization_details that is used to carry fine-grained authorization data in OAuth messages. 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. 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 document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields. This document obsoletes RFC 8941. JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) 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 an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification. This specification defines the Security Event Token (SET) data structure. A SET describes statements of fact from the perspective of an issuer about a subject. These statements of fact represent an event that occurred directly to or about a security subject, for example, a statement about the issuance or revocation of a token on behalf of a subject. This specification is intended to enable representing security- and identity-related events. A SET is a JSON Web Token (JWT), which can be optionally signed and/or encrypted. SETs can be distributed via protocols such as HTTP. This specification describes how to declare in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular proof-of- possession key and how the recipient can cryptographically confirm proof of possession of the key by the presenter. Being able to prove possession of a key is also sometimes described as the presenter being a holder-of-key. This specification defines a protocol for an HTTP- and JSON-based Security Token Service (STS) by defining how to request and obtain security tokens from OAuth 2.0 authorization servers, including security tokens employing impersonation and delegation. 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. Itaú Alibaba Group This document defines the Deferred Token Response (DTR) extension for OAuth 2.1. In existing OAuth grants, the token endpoint either issues an access token or returns an error. DTR establishes a generic asynchronous token request mechanism that any OAuth grant may plug into. In DTR-aware flows, the authorization server returns a deferral_code and a polling interval, indicating that the final token response will be available at a later time. The client retrieves the eventual response by polling the token endpoint, or by receiving a callback from the authorization server when one is configured. Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are widely used to protect data exchanged over application protocols such as HTTP, SMTP, IMAP, POP, SIP, and XMPP. Over the last few years, several serious attacks on TLS have emerged, including attacks on its most commonly used cipher suites and their modes of operation. This document provides recommendations for improving the security of deployed services that use TLS and DTLS. The recommendations are applicable to the majority of use cases. 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 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 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 document establishes an IETF URN Sub-namespace for use with OAuth-related specifications. This document is not an Internet Standards Track specification; it is published for informational purposes. Informative References n.d. n.d. n.d. Financial Stability Board 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. The OAuth 2.0 device authorization grant is designed for Internet- connected devices that either lack a browser to perform a user-agent- based authorization or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorization flow is impractical. It enables OAuth clients on such devices (like smart TVs, media consoles, digital picture frames, and printers) to obtain user authorization to access protected resources by using a user agent on a separate device. 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.

Acknowledgments TODO acknowledge.