| Internet-Draft | Txn Challenge | June 2026 |
| Rosomakho, et al. | Expires 27 December 2026 | [Page] |
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.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://yaroslavros.github.io/oauth-txn-challenge/draft-rosomakho-oauth-txn-challenge.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-rosomakho-oauth-txn-challenge/.¶
Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (mailto:oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Subscribe at https://www.ietf.org/mailman/listinfo/oauth/.¶
Source for this draft and an issue tracker can be found at https://github.com/yaroslavros/oauth-txn-challenge.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 27 December 2026.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
OAuth 2.0 ([OAUTH-FRAMEWORK]) 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 ([OAUTH-RAR]), 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 [OAUTH-STEP-UP]. 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.¶
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.¶
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.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This document uses the terms "client", "authorization server", "access token", "refresh token", and "protected resource" as defined by [OAUTH-FRAMEWORK].¶
This document uses the term "authorization details" as defined by [OAUTH-RAR].¶
This document defines the following additional terms:¶
The human user, resource owner, organizational authority, or policy authority whose approval is required before the challenged transaction can proceed.¶
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.¶
A challenge returned by a protected resource to indicate that a specific requested operation requires transaction-specific authorization before it can proceed.¶
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:¶
The flow is as follows:¶
The agent sends a request to the protected resource using its existing authorization context.¶
The protected resource determines that the request requires transaction-specific authorization.¶
The protected resource returns a transaction authorization challenge to the agent.¶
The agent relays the transaction authorization challenge to the client.¶
The client presents the transaction authorization challenge to the authorization server.¶
The authorization server validates the challenge, determines the approving party, and obtains any required approval.¶
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.¶
The client provides the access token to the agent.¶
The agent retries or continues the request and presents the access token to the protected resource.¶
The protected resource validates the access token, including its authorization details, and processes the request if the token authorizes the challenged operation.¶
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 [OAUTH-RAR], 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.¶
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 HTTP is used, the access token MUST be presented to the protected resource as defined by [OAUTH-FRAMEWORK]. Bearer access
tokens are presented using the Authorization request header field as specified in [BEARER]. Sender-constrained access
tokens are presented using the mechanism defined by the corresponding access token format, for example [DPOP] or
[MTLS].¶
For example:¶
POST /payments HTTP/1.1
Host: resource.example.com
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...
Content-Type: application/json
{
"amount": "5000.00",
"currency": "GBP",
"recipient": "Example Ltd"
}
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.¶
Before accepting the access token as authorization for a challenged operation, the protected resource MUST validate the access token according to [OAUTH-FRAMEWORK], 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;¶
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;¶
the access token has not previously been used, if the protected resource requires single-use access tokens 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 access token or 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.¶
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 SHOULD issue them as sender-constrained access tokens, for example using DPoP ([DPOP]) or mutual-TLS ([MTLS]), for high-impact operations. 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.¶
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.¶
This document registers the Accept-Txn-Challenge HTTP field name, one
OAuth error code, two OAuth parameters, two OAuth Protected Resource
Metadata parameters, one OAuth Authorization Server Metadata Parameter and two JWT claims.¶
IANA is requested to register the following field name in the "HTTP Field Name" registry [IANA.HTTP.FieldNames] as a structured Header Field:¶
IANA is requested to register the following error value in the "OAuth Extensions Error" registry [IANA.OAuth.Parameters]:¶
IANA is requested to register the following parameters in the "OAuth Parameters" registry [IANA.OAuth.Parameters]:¶
transaction_challenge¶
rs-client response, transaction authorization request¶
IETF¶
this document¶
transaction_authorization_id¶
transaction authorization request, transaction authorization response¶
IETF¶
this document¶
IANA is requested to register the following values in the "OAuth Protected Resource Metadata" registry [IANA.OAuth.Parameters].¶
txn_challenge_jwks_uri¶
URL of the protected resource's JSON Web Key Set containing public keys used to validate transaction authorization challenges.¶
IETF¶
this document¶
txn_challenge_signing_alg_values_supported¶
JSON array containing the JWS alg values supported by the protected resource for transaction authorization challenges.¶
IETF¶
this document¶
IANA is requested to register the following claims in the "JSON Web Token Claims" registry [IANA.JSON.Web.Token].¶
reason¶
Human-readable explanation of why authorization, confirmation, or other processing is required.¶
IETF¶
this document¶
reason_uri¶
URI identifying additional information about why authorization, confirmation, or other processing is required.¶
IETF¶
this document¶
TODO acknowledge.¶