]> CrowdStrike

atul.tulshibagwale@crowdstrike.com

Practical Identity LLC

george@practicalidentity.com

Defakto Security

pieter@defakto.security

sec oauth Workloads OAuth JWT token exchange Transaction Tokens (Txn-Tokens) are designed to maintain and propagate user identity, workload identity and authorization context throughout the Call Chain within a trusted domain during the processing of external requests (e.g. such as API calls) or requests initiated internally within the Trust Domain. Txn-Tokens ensure that this context is preserved throughout the Call Chain thereby enhancing security and consistency in complex, multi-service architectures. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction Modern computing architectures often consist of multiple independently running components, referred to in this document as workloads. In many deployments, an external invocation through an interface such as an API results in the invocation of multiple internal workloads in order to process the request. These workloads often execute in virtually or physically isolated networks. Such networks, and the workloads operating within them, can be compromised through software supply chain attacks, privileged user compromise, malicious insiders, software defects, or other attacks. Such compromise can enable unauthorized actions, including

• Invocation of workloads in the absence of a valid transaction.
• Arbitrary user or workload impersonation.
• Parameter modification or augmentation.
• Theft of tokens used to convey authorization context (e.g. OAuth 2.0 access tokens).

Transaction Tokens (Txn-Tokens) are intended to reduce these risks by carrying user or workload identity, along with authorization and request context, in short-lived, signed JWTs that are bound to specific transactions and propagated throughout the Call Chain within a Trust Domain. The authorization and request context include parameters of the original call, environmental attributes such as the IP address of the original caller, user and workload identity information and other information that is expected to remain consistent across subsequent workload invocations, including information added within the Trust Domain after the initial request. Downstream workloads use Txn-tokens to apply authorization decisions based on this context within a specific transaction. Txn-Tokens are cryptographically protected, enabling downstream workloads to detect unauthorized modification of this information. Txn-Tokens reduce risk by making it harder for an attacker to invoke workloads outside an authorized transaction, impersonate users or workloads within a transaction, modify request context for a transaction, or rely on stolen access tokens alone. Txn-Tokens apply both to transactions initiated by an external event, such as an Internet-facing API invocation, and to transactions initiated from within the Trust Domain.

Notational Conventions 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.

Terminology

Workload:

A running instance of software executing for a specific purpose. Examples of workloads include containerized microservices, monolithic services and infrastructure services such as managed databases.

Trust Domain:

A logical grouping of systems that share a common set of security controls and policies. In practice this may include a virtually or physically separated network, which contains two or more workloads. The workloads within a Trust Domain may be invoked only through published interfaces.

External Endpoint:

A published interface to a Trust Domain that results in the invocation of a workload within the Trust Domain. In practice, the external endpoint may be accessed through a gateway service as described in the WIMSE architecture .

Call Chain:

The set of invocations across all workloads invoked to complete the requested transaction.

Transaction Token (Txn-Token):

A signed JWT with a short lifetime, providing immutable information about the user or workload, certain parameters of the call, and specific contextual attributes of the call. The Txn-Token is used to authorize subsequent calls in the Call Chain.

Transaction Token Service (TTS):

A special service within the Trust Domain that issues Txn-Tokens to requesting workloads. Each Trust Domain using Txn-Tokens MUST have exactly one logical TTS.

What are Transaction Tokens? Txn-Tokens are short-lived, signed JWTs that assert the identity of a user or a workload and an authorization context. The authorization context provides information expected to remain constant during the execution of the transaction as it passes through the Call Chain.

Authorization Context Authorization context includes information used for authorization, accounting and auditing purposes and often contains information about the request being made. A key aspect of the authorization context is the intent or purpose of the transaction, which should be as narrowly defined as possible for the given deployment. A narrowly scoped, short-lived, transaction token reduces the attack surface of captured and replayed transaction tokens.

Creating Txn-Tokens

Creation Txn-Tokens are typically created when a workload is invoked using an endpoint that is externally visible, and is authorized using a separate mechanism, such as an OAuth access token. The externally visible endpoint exchanges the external authorization token for a transaction token before sending it to the workload. The transaction token may be obtained through a local interface, or it may be requested from a remote server. If the transaction token request is made via HTTP to a remote server, it MUST use as described in this specification. To do this, it invokes a special Token Service (the Transaction Token Service (TTS)) and provides context that is sufficient for the TTS to generate a Txn-Token. The context information provided to the TTS MUST include:

• The identification of the Trust Domain in which the issued Txn-Token is valid.
• A token which identifies the subject of the Txn-Token (e.g. an OAuth access token, a self-issued JWT, etc).
• The desired authorization scope for the issued Txn-Token.

Additional contextual information MAY be provided such as:

• Parameters that are required to be integrity protected for the duration of this call.
• Additional context, such as the incoming IP address, User Agent information, or other context that can help the TTS to issue the Txn-Token.

The TTS responds to a successful invocation by generating a Txn-Token. The calling workload then uses the Txn-Token to authorize its calls to subsequent workloads. If the requesting service does not have an inbound token that it can use in its request to the TTS, it MAY generate a self-signed JWT and present that in the request in place of the external authorization token. This can be the case when the external authentication does not use an access token or when the requesting service is initiating a scheduled internal request for itself or on behalf of a user of the system.

Txn-Token Lifetime Txn-Tokens are expected to be short-lived (on the order of minutes or less), and as a result MUST be used only for the expected duration of an external or internal invocation. If the token or other credential (e.g. self-signed JWT) presented to the TTS when requesting a Txn-Token has an expiration time, then the TTS MUST NOT issue a Txn-Token if the expiration time has passed. The lifetime of the Txn-Token itself MAY exceed the expiration time of the presented token, subject to the policy of the TTS. The TTS SHOULD assess whether the Txn-Token’s assigned lifetime and transaction binding adequately mitigate the risks of a Txn-Token lifetime that exceeds the presented subject token’s expiration time. If a long-running process such as a batch or offline task is involved, the mechanism used to perform the external or internal invocation still results in a short-lived Txn-Token (see ).

Benefits of Txn-Tokens Txn-Tokens prevent unauthorized invocations by allowing a workload to independently verify the identity of the user or workload that initiated an external call, as well as any contextual information relevant to processing that call. This results in the following benefits:

• Short-lived, Txn-Tokens, bound to a single transaction, reduce replay risk.
• Narrowly scoped Txn-Tokens limit lateral movement and blast radius.
• Signed Txn-Tokens protect the original call context and identity from modification along the Call Chain.
• Independent verification at each workload helps prevent unauthorized invocation.
• Restricting which workloads can obtain Txn-Tokens limits exposure from compromised or untrusted services, including some SBOM-related attack paths.

Txn-Token Issuance and Usage Flows

Basic Flow shows the basic flow of how Txn-Tokens are used in a multi-workload environment.

Basic Transaction Tokens Architecture │ │---------->│ │ │ External │ │ Txn-Token │ 8 │ Endpoint │ 3 │ Service │ <---------│ │<----------│ │ +--------------+ +--------------+ │ ^ 4 v │ 7 +--------------+ │ │ │ Internal │ │ Workload │ │ │ +--------------+ │ ^ v │ o 5 o 6 o │ ^ v │ +--------------+ │ │ │ Internal │ │ Workload │ │ │ +--------------+ ]]>

1. External endpoint is invoked using conventional authorization mechanism such as an OAuth 2.0 Access token.
2. External endpoint provides context and incoming authorization (e.g., access token) to the TTS.
3. TTS mints a Txn-Token that provides immutable context for the transaction and returns it to the requester.
4. The external endpoint initiates a call to an internal workload and provides the Txn-Token as authorization.
5. Subsequent calls to other internal workloads use the same Txn-Token to authorize calls.
6. Responses are provided to calling workloads based on successful authorization by the invoked workloads.
7. Response provided to external endpoint based on successful authorization by the invoked workload.
8. External client is provided a response to the external invocation.

Internally Initiated Txn-Token Flow An internal workload may need to initiate a transaction not on the basis of a current external request, but as part of a scheduled task or in reaction to a specific condition. The transaction may be requested on behalf of the identity of the requesting workload or as an impersonation on behalf of a specific user chosen based on information accessible to the workload.

Internally Initiated Txn-Token Flow

In the diagram above, steps 5-7 are the same as in .

1. A workload determines that it needs to initiate a request on behalf of a user in response to a scheduled timer or other trigger.
2. The internal workload authenticates to the token service and makes a request for a Txn-Token. The request contains information about the transaction along with optional additional authorization credentials.
3. TTS authorizes the requester and then mints a Txn-Token that provides immutable context for the transaction and returns it to the requester.
4. The originating workload then contacts another internal workload and provides the Txn-Token as authorization.

Txn-Token Format A Txn-Token is a JSON Web Token protected by a JSON Web Signature . The following describes the required values in a Txn-Token:

JWT Header In the JWT Header:

• The typ Header Parameter MUST be present and MUST have the value txntoken+jwt.
• Key rotation of the signing key SHOULD be supported through the use of a kid Header Parameter.

is a non-normative example of the JWT Header of a Txn-Token

Example: Txn-Token Header

JWT Body Claims The body of a Txn-Token is a JWT . It contains a combination of existing JWT claims and new claims defined in this specification as described below. A Txn-Token MAY contain additional claims not defined in this specification. Recipients of a Txn-Token MUST ignore any claims they do not understand.

iss:

OPTIONAL The iss claim as defined in is not required as Txn-Tokens are bound to a single Trust Domain as defined by the aud claim and often the signing keys are known.

iat:

REQUIRED The issued at time of the Txn-Token as defined in .

aud:

REQUIRED This claim, defined in , MUST identify the Trust Domain in which the Txn-Token is valid. A Txn-Token MUST NOT be accepted outside the Trust Domain identified by the aud claim.

exp:

REQUIRED Expiry time of the Txn-Token as defined in .

txn:

REQUIRED A unique transaction identifier as defined in Section 2.2 of .

sub:

REQUIRED This claim represents the principal of the transaction as defined by Section 4.1.2 of . The value MUST be unique within the context of the aud Trust Domain. Note: Unlike OpenID Connect, the sub claim is NOT associated with the iss claim.

scope:

REQUIRED The scope claim is defined in . Note that the value of this claim is determined by the TTS and is not required to match the requested scope nor the scope in any supplied external token. For additional context please refer to

tctx:

RECOMMENDED A JSON object that contains values that remain immutable throughout the Call Chain. For additional context please refer to

rctx:

RECOMMENDED A JSON object that describes the environmental context of the requested transaction. For additional context please refer to

req_wl:

REQUIRED. A string value that identifies the workload that requested the Txn-Token.

Scope claim The scope claim captures, as narrowly as possible, the purpose of this particular transaction. The values used for this claim are defined by the TTS as representative of the authorization model defined by the Trust Domain. The value may be literately and semantically different from, and represent an intent narrower, than a scope value issued to an external client. How a given deployment represents the authorization model within the Trust Domain is at its discretion and not prescribed by this specification.

Request Context The Txn-Token SHOULD contain an rctx claim. The JSON value of the rctx claim MAY include any values the TTS determines are relevant to downstream services that rely on the Txn-Token. For example, this may include the IP address information of the originating request, information about the computational entity that requested the Txn-Token and contextual attributes of the originating request itself. The following is a non-normative example of an rctx claim initiated by an external call:

Transaction Context The Txn-Token SHOULD contain an tctx claim. The value of this claim is a JSON object that contains fields (wherein the value could itself be an object), which together assert the details that remain immutable through the Call Chain where this Txn-Token is used. Txn-Tokens are primarily used to assure identity and context for a transaction, and the content of this field is a critical part of that context. Whereas the rctx field contains environmental values related to the request, the tctx field contains the actual authorizaton details that are determined by the TTS. These values are used by services using the Txn-Token to reliably obtain specific parameters needed to perform their work. The content of the tctx field is determined by the TTS and the claims may be computed internally or from parameters it receives from the service that requests the Txn-Token. The following is a non-normative example of an tctx claim initiated by an external call:

Example The figure below shows a non-normative example of the JWT body of a Txn-Token initiated by an external call:

Example: Txn-Token Body

A Txn-Token from an internal request would look much the same except the rctx and tctx field claims would be populated with information from the initiating workloads request.

Txn-Token Service (TTS) A Txn-Token Service (TTS) uses as described in this specification to issue transaction tokens in response to HTTP requests. The unique properties of the Txn-Token requests and responses are described below. The TTS MAY optionally support other OAuth 2.0 endpoints and features, but that is not a requirement for it to be a TTS. Each Trust Domain that uses Txn-Tokens MUST have exactly one logical TTS.

Requesting Txn-Tokens A workload requests a Txn-Token from a TTS. If the transaction token request is made via HTTP to a remote server, it MUST use as described in this specification. Txn-Tokens may be requested for both externally originating or internally originating requests. This profile describes how required and optional context can be provided to the TTS in order for the Txn-Token to be issued. The request to obtain a Txn-Token using this method is called a Txn-Token Request, and a successful response is called a Txn-Token Response. The Txn-Token profile of the OAuth 2.0 Token Exchange is described below.

Txn-Token Request A workload requesting a Txn-Token provides the TTS with proof of its identity (client authentication), the purpose of the Txn-Token and optionally any additional context relating to the transaction being performed. Most of these elements are provided by the OAuth 2.0 Token Exchange specification and the rest are defined as new parameters. Additionally, this profile defines a new token type URN urn:ietf:params:oauth:token-type:txn_token which is used by the requesting workload to identify that it is requesting the Txn-Token Response to contain a Txn-Token. To request a Txn-Token the workload invokes the OAuth 2.0 token endpoint with the following parameters:

• grant_type REQUIRED. The value MUST be set to urn:ietf:params:oauth:grant-type:token-exchange.
• audience REQUIRED. The value MUST be set to the Trust Domain name.
• scope REQUIRED. A space-delimited list of case-sensitive strings where the value(s) MUST represent the specific purpose or intent of the transaction.
• requested_token_type REQUIRED. The value MUST be urn:ietf:params:oauth:token-type:txn_token.
• subject_token REQUIRED. The value MUST contain a token that represent the subject of the transaction. The manner in which the subject is represented in the subject_token depends on the subject_token_type. The subject_token MAY be:
  • An inbound token received by an external endpoint (e.g. an API Gateway).
  • A self-signed JWT constructed by a workload initiating a transaction.
  • An unsigned JSON object constructed by a workload initiating a transaction.
  • Any other format that is understood by the TTS.
  The type of the subject_token field is identified by subject_token_type.
• subject_token_type REQUIRED. The value MUST indicate the type of the token or value present in the subject_token parameter.

The following additional parameters are defined for the Txn-Token Request:

• request_context RECOMMENDED. This parameter contains a JSON object which represents the context of this transaction.
• request_details RECOMMENDED. This parameter contains a JSON object which contains additional details about the request. This could include API parameters, authorization criteria or other details the requester would like to pass to the TTS. The TTS uses this data along with other information at its disposal to construct the tctx JSON object (if required).

All parameters are encoded using the "application/x-www-form-urlencoded" format per Appendix B of . The figure below shows a non-normative example of a Txn-Token Request. Line breaks added for readability.

Example: Txn-Token Request

Subject Token Types The subject_token_type parameter value MUST be a URI . It MAY be:

• Any one of the subject token types described in Section 3 of OAuth 2.0 Token Exchange except the Refresh Token type (i.e., urn:ietf:params:oauth:token-type:refresh_token).
• A URN type name when the subject token is a self-signed JWT, as described below.
• A URN type name when the subject token is an unsigned JSON object, as described below.
• A custom URN agreed to between requesters and the TTS. The TTS MAY support other token formats, which MAY be specified in the subject_token_type parameter.

Self-Signed Subject Token Type A requester MAY use a self-signed JWT as a subject_token value. In that case, the requester MUST set the subject_token_type value to: urn:ietf:params:oauth:token-type:self_signed. This self-signed JWT MUST contain the following claims:

• iss: The unique identifier of the requesting workload.
• sub: The subject for whom the Txn-Token is being requested. The TTS SHALL use this value in determining the sub value in the Txn-Token issued in the response to this request.
• aud: The unique identifier of the TTS. The TTS SHALL verify that this value matches its own unique identifier.
• iat: The time at which the self-signed JWT was created. Note that the TTS may reject self-signed tokens with an iat value that is unreasonably far in the past or future.
• exp: The expiration time for the JWT. provides guidance on setting the expiry of a Txn-Token.

The self-signed JWT MAY contain other claims.

Unsigned JSON Object Subject Token Type A requester MAY use an unsigned JSON object as a subject_token value. In that case, the requester MUST set the subject_token_type value to: urn:ietf:params:oauth:token-type:unsigned_json. The JSON object in the subject token MUST contain the following fields:

• sub: The subject for whom the Txn-Token is being requested. The TTS SHALL use this value in determining the sub value in the Txn-Token issued in the response to this request.

The unsigned JSON object MAY contain other fields, and the TTS MAY consider them when generating the Txn-Token.

Txn-Token Request Processing When the TTS receives a Txn-Token Request it:

• MUST validate the requesting workload client authentication and determine if that workload is authorized to obtain the Txn-Tokens with the requested value(s) (see ). The authorization policy for determining such issuance is out of scope for this specification.
• The TTS MUST validate the subject_token, including verifying the signature, if it is signed.
• The TTS determines the value to specify as the sub of the Txn-Token and MUST ensure the sub value is unique within the Trust Domain defined by the aud claim.
• The TTS MUST set the iat claim to the time of issuance of the Txn-Token.
• The TTS MUST set the aud claim to an identifier representing the Trust Domain of the TTS. If the TTS supports multiple Trust Domains, then it MUST determine the correct aud value for this request.
• The TTS MUST set the exp claim to the expiry time of the Txn-Token. The TTS MAY consider any exp value present in the subject_token parameter of the Txn-Token Request in determining the exp value of the resulting Txn-Token.
• The TTS MUST set the txn claim to a unique ID specific to this transaction.
• The TTS MAY set the iss claim of the Txn-Token to a value defining the entity that signed the Txn-Token.
• The TTS MUST evaluate the value specified in the scope parameter of the request to determine the scope claim of the issued Txn-Token.
• If a request_context parameter is present in the Txn-Token Request, the TTS SHOULD evaluate the content of the request_context parameter and may include claims in the rctx claim of the issued Txn-Token based on the request_context parameter. The TTS is authoritative for the set of claims made available in the rctx claim. The claims included in the rctx claim of the issued Txn-Token may be an exact match of those on the request_context, may be derived from the request_context, or independently asserted by the TTS.
• If a request_details parameter is present in the Txn-Token Request, the TTS SHOULD evaluate the content of the request_details parameter and may include claims in the tctx claim of the issued Txn-token based on the request_details parameter. The claims included in the tctx claim of the issued Txn-Token may be an exact match of those on the request_details, or may be derived from the request_details. The TTS is authoritative for the set of claims made available in the tctx claim and MAY include additional claims unrelated to the request_details.

The TTS MAY provide additional processing and verification that is outside the scope of this specification.

Txn-Token Response A successful response to a Txn-Token Request MUST include the following values defined in :

• The token_type value MUST be set to N_A per guidance in OAuth 2.0 Token Exchange .
• The access_token value MUST be the Txn-Token JWT.
• The issued_token_type value MUST bet set to urn:ietf:params:oauth:token-type:txn_token.

The Txn-Token Response MUST NOT include the refresh_token value. If the TTS responds with an error, the error response is as described in Section 5.2 of . shows a non-normative example of a Txn-Token Response.

Example: Txn-Token Response

Mutual Authentication of the Txn-Token Request A TTS and requesting workload MUST authenticate each other (mutual authentication). Workloads MUST authenticate the TTS to ensure that they do not disclose sensitive information, such as OAuth access tokens, to a rogue TTS. A TTS MUST authenticate a workload to ensure the workload is authorized to request a transaction token. Workloads SHOULD use the https scheme to secure the communication channel and authenticate the TTS. When using https, TLS certificates MUST be checked according to . At the time of this writing, TLS version 1.3 is the most recent version. Workloads SHOULD authenticate to a Transaction Token Server using asymmetric (public-key based) methods or signed client authentication JWTs in accordance with , which MAY be provisioned using mechanisms such as or other provisioning protocols. Examples of public-key based authentication include those defined in OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens , Workload Authentication Using Mutual TLS , WIMSE Workload-to-Workload Authentication with HTTP Signatures and WIMSE Workload Proof Token .

Using Txn-Tokens Txn-Tokens need to be communicated between workloads that depend upon them to authorize the request. Such workloads will often present HTTP interfaces for being invoked by other workloads. This section specifies the HTTP header the invoking workload MUST use to communicate the Txn-Token to the invoked workload, when the invoked workload presents an HTTP interface. Note that the standard HTTP Authorization header MUST NOT be used because that may be used by the workloads for other purposes.

"Txn-Token" HTTP Header A workload that invokes another workload using HTTP and needs to present a Txn-Token to the invoked workload MUST use the HTTP Header "Txn-Token" to communicate the Txn-Token in the HTTP Request. The value of this header MUST be exactly one Txn-Token.

Txn-Token Validation A workload that receives a Txn-Token MUST evaluate the token for validity before authorizing it for activities supported by the workload. To validate the Txn-Token, the workload MUST:

• Validate the Txn-Token JWS signature.
• Verify the aud claim identifies the Trust Domain of the workload.
• Verify the Txn-Token is not expired.

In addition, any outbound calls made by this workload MUST include the Txn-Token as it was received so that it is passed unmodified to any downstream workloads. Once the Txn-Token is determined to be valid, the workload MAY use any of the data contained in the Txn-Token to determine if the Txn-Token authorizes the requested activity. How the workload determines this authorization is out of scope for this specification.

Security Considerations

Txn-Token Replay Risks A Txn-Token is not resistant to replay attacks. A long-lived Txn-Token therefore represents a risk if it is discovered by an attacker (e.g. if it is stored in a file), and then replayed. For this reason, a Txn-Token lifetime MUST be kept short and follow the guidance given in . The use of a unique transaction identifier (txn claim) allows for discovery of Txn-Token replay as described in .

Unique Transaction Identifier A Txn-Token conveys user identity and authorization context across workloads in a Call Chain. The txn claim is a unique identifier that, when logged by the TTS and workloads, enables discovery and auditing of successful and failed transactions. The txn value SHOULD be unique within the Trust Domain. A workload receiving a Txn-Token can store the txn value of each Txn-Token for the time window in which the Txn-Token would be accepted to prevent multiple uses of the same Txn-Token. Requests to the same workload for which the txn value has been seen before would be declined. When strictly enforced, such a single-use check provides a very strong protection against Txn-Token replay, but it may not always be feasible in practice, e.g., when multiple instances of the same workload receiving a Txn-Token have no shared state.

Refresh Tokens OAuth refresh tokens are used to obtain access tokens as defined in and MUST NOT be used to request transaction tokens (see . Since Txn-Tokens are short-lived (), the Txn-Token response from the TTS MUST NOT include a refresh token (see ).

Access Tokens When creating Txn-Tokens, the Txn-Token MUST NOT contain the access token presented to the external endpoint. If an access token is included in a Txn-Token, an attacker may extract the access token from the Txn-Token, and replay it to any Resource Server that can accept that access token. Txn-Token expiry does not protect against this attack since the access token may remain valid even after the Txn-Token has expired. Access tokens are typically short-lived but they can be invalidated before their expiration due to security or policy changes. In addition to standard access token validation, a TTS MAY, based on the risk profile of the deployment or transaction, verify whether the presented access token was invalidated. Where appropriate, implementations can use OAuth 2.0 Token Introspection or similar mechanisms to obtain up-to-date token status from the authorization server.

Subject Token Types Identifies the token type of the subject_token which is generally a token the requesting workload received (e.g. an OAuth token or a SAML assertion). In the absence of an appropriate incoming token, the requesting service MAY use a self-signed JWT, an unsigned JSON object or any other format to represent the details of the requester and the transaction to the TTS.

Scope Processing The authorization model within a Trust Domain boundary may be quite different from the authorization model (e.g. OAuth scopes) used with clients external to the Trust Domain. This makes managing unintentional scope increase a critical aspect of the TTS. The TTS MUST ensure that the requested scope of the Txn-Token is equal or less than the scope(s) associated with the original subject_token.

TTS Discovery A workload may use various mechanisms to determine the correct instance of a TTS with which to interact. Workloads MUST retrieve configuration information from a trusted source to minimize the risk of a threat actor providing malicious configuration data that points to an instance of a TTS under it's control which could be used to collect access tokens sent as part of the Transaction Token Request message. To mitigate this risk, workloads SHOULD authenticate the service providing the configuration information and verify the integrity of the configuration information. This ensures that no unauthorized entity can insert or alter configuration data. The workload SHOULD use Transport Layer Security (TLS) to authenticate the endpoint and secure the communication channel. Additionally, application-layer signatures or message authentication codes MAY be used to detect any tampering with the configuration information.

Workload Configuration Protection A deployment may include multiple instances of a TTS to improve resiliency, reduce latency and enhance scalability. A workload may be configured to access more than one instance of a TTS to ensure reliability or reduce latency for transaction token requests. The workload configuration should be protected against unauthorized addition or removal of TTS instances. An attacker may perform a denial of service attack or degrade the performance of a system by removing an instance of a TTS from the workload configuration.

TTS Authentication A workload may accidently send a transaction token request to a service that is not a TTS, or an attacker may attempt to impersonate a TTS in order to gain access to transaction token requests which includes sensitive information like access tokens. To minimise the risk of leaking sensitive information like access tokens that are included in the transaction token request, the workload MUST ensure that it authenticates the TTS and only contacts instances of the TTS that is authorized to issue transaction tokens.

TTS Issuance Policies A TTS should be selective in which workloads can successfully request a Txn-Token. A TTS does not need to issue a Txn-Token to every workload that requests one. TTS token issuance decisions, including whether to issue a Txn-Token and the claims it contains, are typically subject to deployment-specific issuance policies and business logic. For example, an API gateway handling a user-initiated request might be permitted to obtain a Txn-Token carrying request context such as a transaction amount, while a downstream service in the same Call Chain might not. Such policies may vary based on system architecture, workload identity, transaction context, or risk, and may result in different Txn-Token contents or denial of issuance. The definition and management of these policies are deployment-specific and out of scope for this specification.

TTS Key Rotation The TTS may need to rotate signing keys. When doing so, it MAY adopt the key rotation practices in Section 10.1.1 of .

Transaction Tokens Are Not Authentication Credentials A workload MUST NOT use a transaction token to authenticate itself to another workload, service or the TTS. Transaction tokens represents information relevant to authorization decisions and are not workload identity credentials. Authentication between the workload and the TTS is described in .

Transaction Tokens Are Not OAuth 2.0 Access Tokens A workload MUST NOT use a transaction token as an OAuth 2.0 Access Token. An OAuth 2.0 Access Token represents a grant of authority to a client, a transaction token represents the context of a specific transaction. The separation of the transaction token from the OAuth 2.0 Access Token is a deliberate design choice as described in . Transaction tokens support the principle of least privilege since they are narrowly scoped to a single transaction and have short lifetimes. This makes them less susceptible to broad replay attacks than the longer-lived access tokens. By maintaining a distinct token type, the protocol ensures that context propagation while minimizing the risk of lateral access if a transaction token is intercepted within the Trust Domain. This separation also reduces the need for including transaction context in the access token, reducing token size. Using a dedicated HTTP header from the Authorization: Bearer header for transaction tokens allows services to distinguish between an access token, which carries authorization delegation information, and the transaction token, which carries transaction context.

Unknown subject_token scope If the scope associated with a subject_token cannot be determined from the token or another trusted source, the TTS cannot ensure that the requested scope does not expand the authorization represented by that token. The TTS MUST reject the Txn-Token Request and MUST NOT treat an unknown scope as unconstrained.

Txn-Token as a subject_token A TTS MUST exercise caution when receiving a Txn-token as a subject_token. Any Txn-Token issued in response to such a request is effectively a replacement Txn-Token. Replacing Txn-Tokens potentially negates the primary purpose of having Txn-Tokens. When issuing replacement Txn-Tokens, a TTS:

• MAY enable modifications to asserted values that reduce the scope of permitted actions.
• MAY enable additional asserted values.
• MUST NOT enable modification to asserted values that expand the scope of permitted actions.
• MUST NOT modify txn, sub, and aud values of the Txn-Token in the request.
• MUST NOT issue a new Txn-Token when the Txn-Token being replaced has expired.
• MAY issue a replacement Txn-Token with a lifetime exceeding the lifetime of the input Txn-Token, subject to the policy of the TTS.
• SHOULD limit the number of times a Txn-Token is replaced if it allows extending the lifetime beyond that of the input Txn-Token to reduce replay risks.
• MUST maintain the Call Chain of workloads that requested the Txn-Token being replaced in the subsequently issued Txn-Token. The mechanism for maintaining this Call Chain is out of scope for this specification.

Determining signing keys The iss claim may be used to identify the signer of the Txn-Token in cases where the signing keys are not predetermined.

Preserving transaction context across Trust Domains Txn-Tokens are only valid within the Trust Domain identified by the aud claim as defined in . When a workload needs to access a resource in a different Trust Domain to complete a transaction, and the identity and authorization context from the Txn-Token needs to be preserved, it SHOULD use OAuth Identity and Authorization Chaining Across Domains .

Privacy Considerations

Handling of Personal Information Claims contained within transaction tokens may be considered personal information (PI) or personally identifying information (PII) in some jurisdictions and if so their values should be protected accordingly. For example, requester IP address (req_ip) is often considered personal information and therefore must be handled according to jurisdictional requirements.

Logging Complete Txn-Tokens MUST NOT be logged verbatim. This is in order to prevent replay of tokens or leakage of PII or other sensitive information via log files. A hash of the Txn-Token may be logged to allow for correlation with the log files of the TTS that records issued tokens. Alternatively the JWS payload of a Txn-Token may be logged after the signature has been removed. If the Txn-Token contains PII, then care should be taken in logging the content of the Txn-Token so that the PII does not get logged.

IANA Considerations This specification registers the following token type identifiers to the "OAuth URI" subregistry of the "OAuth Parameters" registry. It also registers the following claims defined in Section in the IANA JSON Web Token Claims Registry defined in . It also registers the Media Type "txntoken+jwt" as defined in the section .

OAuth URI Subregistry Contents

• URN: urn:ietf:params:oauth:token-type:txn_token
  • Common Name: Transaction Token
  • Change Controller: IETF
  • Specification Document Section of this specification
• URN: urn:ietf:params:oauth:token-type:self_signed
  • Common Name: Token type for Self-signed JWT
  • Change Controller: IETF
  • Specification Document: Section of this specification
• URN: urn:ietf:params:oauth:token-type:unsigned_json
  • Common Name: Token type for Unsigned JSON Object
  • Change Controller: IETF
  • Specification Document: Section of this specification

JWT Claims Registry Contents

• Claim Name: tctx
  • Claim Description: The transaction authorization details
  • Change Controller: IETF
  • Specification Document: Section of this specification
• Claim Name: rctx
  • Claim Description: The requester context
  • Change Controller: IETF
  • Specification Document: Section of this specification

IANA Media Type Registration Contents The following entry will be proposed using the IANA Media Type registration form.

• Type Name: application
• Subtype Name: txntoken+jwt
• Change Controller: IETF
• Required Parameters: N/A.
• Optional Parameters: N/A.
• Encoding Considerations: 7-bit text
• Security Considerations:
  1. The media type is used to identify JWTs that may be used as Transaction Tokens. It is a piece of data, and may not contain executable content.
  2. Transaction Tokens are short-lived tokens used within a trusted environment, so there are no privacy considerations. Transaction Tokens are unmodifiable tokens, which need integrity protection.
  3. The JWTs representing Transaction Tokens are signed, and therefore are integrity protected. A recipient of a Transaction Token must verify the signature on the Transaction Token before using it.
  4. There are no additional security considerations specific to the use of JWTs as Transaction Tokens.
  5. The Transaction Tokens format does not require the use of links within the token. If links are used by specific instances of Transaction Tokens, then their interpretation is usage specific.
• Interoperability Considerations: Transaction Tokens inherit all interoperability properties of JWTs.
• Published Specification: this document (when published).
• Application Usage: Any application supporting the use of JWTs.
• Fragment Identifier Consideration: N/A.
• Restrictions on Usage: Any application supporting the use of JWTs.
• Intended Usage: Common
• Contact Person: Atul Tulshibagwale

HTTP Header The header name Txn-Token is proposed to be added to the HTTP Field Name Registry as an unstructured Header Field. This header is defined in the section . The following entry will be proposed in the HTTP Field Name Registry. Note that this is an unstructured field, therefore the value of the Type field is left empty as shown below:

• Field Name: Txn-Token
• Type:
• Status: permanent
• Specification Document: Section of this document
• Comment: The Authorization header cannot be used for Txn-tokens because that header may be used for service-to-service authorization, and the services may simultaneously require the use of Txn-tokens to convey detailed immutable information such as user identity and details of fine-grained authorization that are included in the Txn-token.

References Normative References 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. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations. 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] 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. 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 use of a JSON Web Token (JWT) Bearer Token as a means for requesting an OAuth 2.0 access token as well as for client authentication. 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. 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. 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 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 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 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. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. This document obsoletes RFC 7234. 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. Defakto Security Defakto Security MITRE NSA-CCSS Ping Identity Okta This specification describes a mechanism for preserving identity and authorization information across trust domains that use the OAuth 2.0 Framework. A JSON Web Token (JWT) authorization grant, obtained through an intra-domain OAuth 2.0 Token Exchange, facilitates the cross-domain acquisition of an access token. The relevant identity and authorization information is chained throughout the flow by being conveyed in the respective artifacts exchanged at each step of the process. Chaining across multiple domains is achieved by using the same protocol every time a trust domain boundary is crossed. n.d. n.d. n.d. NRI Ping Identity Microsoft Google Salesforce Informative References The "amr" (Authentication Methods References) claim is defined and registered in the IANA "JSON Web Token Claims" registry, but no standard Authentication Method Reference values are currently defined. This specification establishes a registry for Authentication Method Reference values and defines an initial set of Authentication Method Reference values. Cloud Native Computing Foundation n.d. Palo Alto Networks Zscaler University of the Bundeswehr Munich The increasing prevalence of cloud computing and micro service architectures has led to the rise of complex software functions being built and deployed as workloads, where a workload is defined as software executing for a specific purpose, potentially comprising one or more running instances. This document discusses an architecture for designing and standardizing protocols and payloads for conveying workload identity and security context information. Palo Alto Networks Zscaler The WIMSE architecture defines authentication and authorization for software workloads in a variety of runtime environments, from the most basic ones to complex multi-service, multi-cloud, multi-tenant deployments. This document profiles a workload authentication based on X.509 workload identity certificates using mutual TLS (mTLS). Palo Alto Networks Intuit The WIMSE architecture defines authentication and authorization for software workloads in a variety of runtime environments, from the most basic ones to complex multi-service, multi-cloud, multi-tenant deployments. This document defines one of the mechanisms to provide workload authentication, using HTTP Signatures. While only applicable to HTTP traffic, the protocol provides end-to-end protection of requests (and optionally, responses), even when service traffic is not end-to-end encrypted, that is, when TLS proxies and load balancers are used. Authentication is based on the Workload Identity Token (WIT). Ping Identity Defakto Security The WIMSE architecture defines authentication and authorization for software workloads in a variety of runtime environments, from basic deployments to complex multi-service, multi-cloud, multi-tenant systems. This document specifies the Workload Proof Token (WPT), a mechanism for workloads to prove possession of the private key associated with a Workload Identity Token (WIT). The WPT is a signed JWT that binds the workload's authentication to a specific HTTP request, providing application-level proof of possession for workload-to-workload communication. This specification is designed to work alongside the WIT credential format defined in draft-ietf- wimse-workload-creds and can be combined with other WIMSE protocols in multi-hop call chains.

Acknowledgements The authors would like to thank John Bradley, Kelley Burgin, Brian Campbell, Naveen CM, Andrii Deinega, Apoorva Deshpande, Daniel Fett, Evan Gilman, Joseph Heenan, Watson Ladd, Kai Lehmann, Jeff Lombardo, Dan Moore, Steinar Noem, Ashay Raut, Justin Richer, Joe Salowey, Dean Saxe, Arndt Schwenkschuster, Dag Sneeggen, Yaron Scheffer, Orie Steele, Dmitry Telegin, and Hannes Tschofenig for supporting, commenting, contributing and providing feedback on this specification.

Document History [[ To be removed from final specification ]]

Since Draft 10

• Fixed typo in document history

Since Draft 09

• Editorial text describing claims

Since Draft 08

• Added document history for changes from 07 to 08
• Added TTS Issuance Guidance policies (see issue https://github.com/oauth-wg/oauth-transaction-tokens/issues/321)
• Provide guidance on cross-domain access (see https://github.com/oauth-wg/oauth-transaction-tokens/issues/326)
• Added security consideration for invalidated tokens (see issue https://github.com/oauth-wg/oauth-transaction-tokens/issues/321)
• Added doublequotes around the "Txn-Token" header name to distinguish it from the usage of Txn-Token as a name for Transaction Tokens.
• Added Brian Campbell as a contributor.
• Renamed Requester-Context section to Request Context and removed specification of rctx specific claims (see issue https://github.com/oauth-wg/oauth-transaction-tokens/issues/323)
• Clarified how multiple workloads are represented in the req_wl claim (see issue https://github.com/oauth-wg/oauth-transaction-tokens/issues/331)
• Clarify transaction tokens vs OAuth 2.0 access tokens
• Merged Overview and Introduction sections (see https://github.com/oauth-wg/oauth-transaction-tokens/issues/327)
• Changed additionally defined request parameters from OPTIONAL to RECOMMENDED see https://github.com/oauth-wg/oauth-transaction-tokens/issues/332)
• Consistent cappitalisation of trust domain and call chain (see https://github.com/oauth-wg/oauth-transaction-tokens/issues)
• Updated JWT body claims from OPTIONAL to RECOMMENDED (see https://github.com/oauth-wg/oauth-transaction-tokens/issues/330)
• Clarified TTS behaviour wrt txtx and rctx, fixed examples (see https://github.com/oauth-wg/oauth-transaction-tokens/issues/349)

Since Draft 07

• Fixed author affiliation (https://github.com/oauth-wg/oauth-transaction-tokens/pull/318)
• Added details to the benefits section (https://github.com/oauth-wg/oauth-transaction-tokens/pull/316)
• Updated the definition of the req_wl claim (https://github.com/oauth-wg/oauth-transaction-tokens/pull/315)
• Editorial changes for grammar and clarity (https://github.com/oauth-wg/oauth-transaction-tokens/pull/307, https://github.com/oauth-wg/oauth-transaction-tokens/pull/308)
• Standardized terminology throughout the document (https://github.com/oauth-wg/oauth-transaction-tokens/pull/304)
• Revised handling of personal information in Privacy section (hhttps://github.com/oauth-wg/oauth-transaction-tokens/pull/306/)
• Clarified token replay risks (https://github.com/oauth-wg/oauth-transaction-tokens/pull/305)
• Fixed section numbering issue (https://github.com/oauth-wg/oauth-transaction-tokens/issues/352)
• Made iss optional in all circumstances, and added Seurity Consideration that provides guideance on using it when signing keys are not predetmined.

Since Draft 06

• Remove contradiction in "request_details" description and simplify normative langugage Clarify claim usage.
• Consistency in terms of expectations of input token (https://github.com/oauth-wg/oauth-transaction-tokens/issues/224)
• Replace StringOrURI with string Replace StringOrURI with String
• Include token theft as a threat to be mitigated Consider information disclosure as a benefit
• Remove definition of Authorization Context Be more specific on Authorization Context
• Clarify text on use of empty parameter: https://github.com/oauth-wg/oauth-transaction-tokens/issues/235
• Clarify that workloads should ensure it is communicating with a legitimate instance of a transaction token service (https://github.com/oauth-wg/oauth-transaction-tokens/issues/233)
• Clarify need to validate signature on subject_token if it is signed.
• Clarify role of transaction tokens in call chain (https://github.com/oauth-wg/oauth-transaction-tokens/issues/203)
• Revise normative langugage for enforcement of token expiry (https://github.com/oauth-wg/oauth-transaction-tokens/issues/210)
• Remove exp field from unsigned token (https://github.com/oauth-wg/oauth-transaction-tokens/issues/201)
• Change document category from informational to standards track (https://github.com/oauth-wg/oauth-transaction-tokens/issues/169)
• Clarify that txnshould remain unchanged when included in a replacement transaction token.
• Editorial updates (https://github.com/oauth-wg/oauth-transaction-tokens/issues/204)
• Removed the requirement to encode parameters in based64url format
• Rename the purpose claim to scope
• Enhanced the description of the sub claim addressing issue #225
• Removed references to replacing transaction tokens, and added a note in the Security Considerations to clarify replacement concerns.
• Editorial updates identified by Dan Moore (https://github.com/oauth-wg/oauth-transaction-tokens/issues/236)
• Editorial comments from Joe Saloway (https://github.com/oauth-wg/oauth-transaction-tokens/issues/219)
• Clarify request_details (https://github.com/oauth-wg/oauth-transaction-tokens/issues/197)
• Add normative language for processing Txn-Tokens (https://github.com/oauth-wg/oauth-transaction-tokens/issues/270)
• Strengthen normative language for Txn-Token Requests (https://github.com/oauth-wg/oauth-transaction-tokens/issues/209)
• Aligned with WIMSE terminology (https://github.com/oauth-wg/oauth-transaction-tokens/issues/213)
• Updated Acknowledgement section (https://github.com/oauth-wg/oauth-transaction-tokens/issues/260)
• Rewrote the 'Handling of Personal Information' section of Privacy Considerations (https://github.com/oauth-wg/oauth-transaction-tokens/issues/290)
• Removed text related to replacement transaction tokens
• Updated references to call chain to be capitalized and fixed some definitions (https://github.com/oauth-wg/oauth-transaction-tokens/issues/284)
• Update definition of req_wl claim (https://github.com/oauth-wg/oauth-transaction-tokens/issues/311)

Since Draft 05

• Strengthened prohibition on expanding TraT scope
• Clarified that TraTs can exceed request token lifetime, but cannot use expired tokens in request
• Improved abstract for clarity
• Clarified that the HTTP header Txn-Token is unstructured
• Scope Processing: behavior undefined when subject_token has no scope claim

Since Draft 04

• Clarified Transaction Token Service discovery
• Language improvements
• Renamed azd claim to tctx claim
• Fixed terminology captialization
• Added key rotation guidance
• Clarified text around external vs internal invocation

Contributors Ping Identity

bcampbell@pingidentity.com