Authorization Evidence and Audit Trail for OAuth 2.0 Access Tokens

1.1. Requirements Language

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

1.2. Relationship to Rich Authorization Requests

This specification builds on the Rich Authorization Requests (RAR) framework [RFC9396]. In RAR, clients include authorization_details in authorization requests to convey fine-grained authorization data. RAR Section 7.1 defines an "Enriched Response" mechanism where the Authorization Server dynamically populates fields in the authorization_details based on user consent decisions or policy rules.¶

The authorization_evidence type defined in this specification follows this enriched response pattern:¶

1. The client includes an authorization_evidence authorization details object in its request, typically with minimal or placeholder fields indicating that evidence is requested.¶
2. During the consent interaction, the AS presents the requested operation to the user and captures the user's confirmation action.¶
3. The AS enriches the authorization_evidence object with the complete evidence record, including user_confirmation details and the AS's cryptographic signature.¶
4. The enriched authorization details is included in the token response and bound to the issued access token.¶

This approach ensures that authorization evidence is structured as a first-class authorization detail rather than a standalone JWT claim, enabling consistent handling across OAuth flows and composability with other authorization details types.¶

3.1. Type Definition

Type Identifier:

authorization_evidence¶

Usage:

authorization_details in authorization requests and token responses¶

3.2. Client Request

A client requests authorization evidence by including an authorization_evidence authorization details object in its authorization request. The client typically includes minimal fields, indicating that evidence is requested:¶

{
  "authorization_details": [
    {
      "type": "authorization_evidence"
    }
  ]
}

The client MAY include optional fields to indicate preferences, such as specific audit trail requirements. However, the AS has final authority over the evidence content based on the actual consent interaction.¶

3.3. Enriched Response

After the user completes the consent interaction, the AS enriches the authorization_evidence object with the complete evidence record. The enriched authorization details is included in the token response:¶

{
  "authorization_details": [
    {
      "type": "authorization_evidence",
      "evidence": {
        "id": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
        "user_confirmation": {
          "displayed_content": "Add items under $50 to cart",
          "user_action": "confirmed_via_button_click",
          "timestamp": 1731320595
        },
        "content_hash": "uU0nuZNNPgilLlLX2YNrNmHQoFu66dKfLq3Ln4AXCR0",
        "as_signature": "eyJhbGciOiJFUzI1NiJ9..MEUCIQDx...",
        "audit_trail": {
          "semantic_expansion_level": "medium",
          "proposal_ref": "urn:uuid:proposal-xyz"
        }
      }
    }
  ]
}

3.4. Evidence Object Structure

The evidence object within the authorization_evidence authorization details type contains the following fields:¶

{
  "evidence": {
    "id": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
    "user_confirmation": {
      "displayed_content": "Add items under $50 to cart",
      "user_action": "confirmed_via_button_click",
      "timestamp": 1731320595
    },
    "content_hash": "uU0nuZNNPgilLlLX2YNrNmHQoFu66dKfLq3Ln4AXCR0",
    "as_signature": "eyJhbGciOiJFUzI1NiJ9..MEUCIQDx..."
  }
}

3.5. Field Definitions

3.6. AS Signature

The as_signature field contains a cryptographic signature from the Authorization Server over the evidence record. This signature:¶

• Proves the AS witnessed the user's consent;¶
• Ensures the evidence has not been tampered with;¶
• Provides strong evidence of user consent for dispute resolution (subject to trust in the AS, as discussed in Section 9).¶

The signature MUST be computed over the following fields of the evidence object:¶

• id¶
• user_confirmation (entire object)¶

The as_signature field itself MUST be excluded from the signature computation. The signature format MUST be a detached JWS [RFC7515] in Compact Serialization using the AS's signing key. In detached Compact Serialization (see RFC 7515 Appendix F), the payload portion is omitted, resulting in the format "header..signature".¶

The signature input is constructed using the following deterministic algorithm:¶

1. Create a new JSON object containing only the id and user_confirmation fields copied from the evidence object. No other fields from the evidence object are included.¶
2. Apply the JSON Canonicalization Scheme (JCS) as defined in [RFC8785] to the JSON object from the previous step, producing a deterministic byte string.¶
3. Compute the SHA-256 digest of the JCS output from Step 2, encode it in base64url, and store the result in the content_hash field of the evidence object. The content_hash field itself is not part of the signature input.¶
4. Compute a detached JWS (Compact Serialization) over the JCS output from Step 2 using the AS's private signing key. The resulting value (header..signature) is stored in the as_signature field of the evidence object.¶

To verify an as_signature, the verifier reconstructs the JCS input by performing Steps 1 and 2 above on the received evidence object (excluding the as_signature field), then verifies the detached JWS using the AS's public key. The content_hash can be verified in the same pass: the verifier recomputes the digest over the reconstructed JCS output and compares it with the received content_hash. Hash verification requires no key material and therefore provides integrity checking that is independent of trust in the AS. Any extension fields present in the evidence object beyond id, user_confirmation, content_hash, and as_signature MUST NOT be included in the JCS input and therefore are not covered by the signature. In particular, the OPTIONAL revocation member defined in Section 7.3 is not covered by the as_signature; in signed JWT access tokens its integrity is provided by the token signature.¶

Note: In examples throughout this document, the as_signature value is shown in abbreviated form for readability. Actual values MUST use the detached JWS Compact Serialization format described above.¶

The key used to sign the evidence record MAY be the same key used to sign the access token, or it MAY be a separate dedicated key. When a separate key is used, implementations MUST ensure that the evidence signing key is associated with the AS through a verifiable mechanism (e.g., published in the AS's JWKS endpoint as defined in [RFC7517]). Using a dedicated evidence signing key enables independent key rotation without affecting token validation.¶

4.1. Structure

{
  "audit_trail": {
    "semantic_expansion_level": "medium",
    "proposal_ref": "urn:uuid:proposal-xyz"
  }
}

4.2. Field Definitions

4.3. Semantic Expansion Levels

The semantic_expansion_level field indicates how much the system interpreted or expanded the user's original intent. The following four values form a closed set; implementations MUST NOT use values outside this set:¶

none:

No interpretation; user specified exact parameters. Example: User explicitly sets "transfer $100 to account X".¶

low:

Minor defaults applied. Example: User says "add to cart" and the system defaults quantity to 1 and selects the user's saved shipping address.¶

medium:

Significant interpretation of qualitative terms. Example: User says "buy cheap headphones" and the system maps "cheap" to a price ceiling of $50 and selects a specific product category.¶

high:

Substantial expansion from a high-level goal into a multi-step plan. Example: User says "plan my trip to Tokyo" and the agent derives flight search, hotel booking, and itinerary creation as separate authorized operations.¶

6.2. Evidence Generation

When issuing an access token with evidence, the AS MUST:¶

1. Record the exact content displayed to the user during consent;¶
2. Capture the user's confirmation action and timestamp;¶
3. Generate a unique evidence identifier;¶
4. Compute the content_hash (Step 3 of the AS Signature algorithm in Section 3);¶
5. Sign the evidence fields (id and user_confirmation) with the AS's private key using JCS canonicalization;¶
6. Include the authorization_evidence authorization details in the access token.¶

8.1. Evidence Verification

Resource Servers MAY verify the evidence object by:¶

1. Extracting the as_signature from the evidence;¶
2. Verifying the signature using the AS's public key;¶
3. Recomputing the SHA-256 digest of the JCS-canonicalized signing input and comparing it with the content_hash, which detects corruption or tampering without requiring the AS's public key;¶
4. Confirming that the evidence id and timestamp are consistent with the token's iat claim (i.e., the user confirmation occurred before or at token issuance);¶

Note: The displayed_content field records what was shown to the user during consent. The RS typically does not have direct knowledge of the consent interaction and therefore cannot independently verify this field. Instead, the RS relies on the AS signature as proof that the AS witnessed the user's consent to the described operation.¶

8.2. Audit Logging

Resource Servers SHOULD log evidence information for audit purposes, including:¶

• Evidence ID;¶
• User confirmation timestamp;¶
• Displayed content summary;¶
• Operation performed;¶
• Outcome (success/failure).¶

9.1. Signature Verification

The AS signature over the evidence fields (id and user_confirmation) is critical for evidence integrity. Implementations MUST:¶

• Use strong cryptographic algorithms (e.g., RS256, ES256);¶
• Protect AS signing keys appropriately;¶
• Rotate keys periodically with proper key management.¶

9.2. Content Hash

The content_hash provides tamper detection that is independent of the as_signature: any party holding an evidence record can recompute the digest without key material or trust in the AS, which is useful when evidence records are archived, replicated, or exchanged between audit systems after tokens have expired. Because identical records yield identical digests, the content_hash also enables deduplication in audit stores and allows two parties to confirm they hold the same record by comparing digests. References to evidence records from other artifacts (e.g., evidence_ref in Section 4, or delegation chains) SHOULD include the content_hash of the referenced record so that the reference is bound to its content.¶

Since the digest is deterministic, evidence records with low-entropy content could in principle serve as correlatable identifiers if the candidate content can be enumerated. Evidence records in this specification include a unique id and a user-confirmation timestamp, which provides sufficient entropy in practice; implementations publishing digests to public stores SHOULD nonetheless consider whether correlation of digests across stores raises privacy concerns for their deployment.¶

9.3. Evidence Tampering and Trust in the AS

The evidence object is protected by the access token's signature. However, the as_signature field provides an additional layer of protection specifically for the user confirmation record.¶

It is important to understand the trust boundary of the evidence mechanism: the as_signature provides cryptographic proof that the AS recorded a user confirmation. It does not independently prove that the user actually consented. The AS controls both the consent interaction and the signing key, so a compromised or malicious AS could fabricate evidence records. Trust in the evidence record therefore depends on trust in the AS and its operational security. Deployments requiring stronger non-repudiation guarantees SHOULD supplement this mechanism with user-side signatures or independent consent auditing.¶

9.4. Replay Attacks

Evidence records are bound to specific access tokens. The evidence ID and timestamp help detect attempts to reuse evidence across different authorization contexts.¶

9.5. Token-Evidence Binding

The evidence object is embedded in a signed access token ([RFC9068]), which provides integrity protection at the token level. The inner as_signature provides a second, independent integrity layer specifically over the user confirmation record. This dual-signature design ensures that:¶

• Evidence cannot be moved from one token to another without detection (the token signature would not cover the new evidence);¶
• Evidence fields cannot be modified within a valid token (the inner AS signature would be invalidated);¶
• Evidence can be independently verified even when extracted from the token (e.g., via introspection) using the as_signature.¶

Implementations MUST NOT copy an evidence object from one access token into another without re-validating the as_signature and confirming that the evidence id and timestamp are consistent with the new token's context.¶

The dual-signature design described above applies to signed JWT access tokens ([RFC9068]). When opaque (reference) tokens are used, the evidence object is not embedded in the token itself and MUST be retrieved by the RS via token introspection ([RFC7662]) or a dedicated evidence retrieval endpoint. In this case, the as_signature provides the sole integrity protection for the evidence record, and implementations MUST ensure that the transport between the RS and the introspection or retrieval endpoint is protected with TLS.¶

9.6. Cross-Domain Evidence Verification

In cross-domain scenarios where the RS is in a different trust domain than the AS, the RS must be able to verify the as_signature using the AS's public key. Implementations SHOULD:¶

• Publish the AS's evidence signing keys at a well-known JWKS endpoint ([RFC7517]) accessible to the RS;¶
• Include a kid (Key ID) in the JWS header of the as_signature to enable key selection;¶
• Support key caching at the RS with appropriate cache invalidation to balance performance and key freshness.¶

When the AS and RS belong to different administrative domains, trust establishment for the evidence signing key MAY be facilitated through a trust framework, federation agreement, or explicit key distribution mechanism.¶

9.7. Revocation Handle Security

A revocation handle grants no authority: it is a lookup key for a consent record, not a credential. Nevertheless, implementations MUST protect against the following threats:¶

• Enumeration: handles MUST contain at least 128 bits of entropy so that an attacker cannot discover consent records by guessing handle values;¶
• Insecure direct object reference: possession of a handle MUST NOT be sufficient to revoke the associated consent record. The AS MUST authenticate the principal and verify that the authenticated principal owns the consent record before executing any revocation (Section 7.4);¶
• Cross-site request forgery: a GET request to the revocation endpoint MUST only render the confirmation interface and MUST NOT trigger revocation. Revocation MUST be executed through a POST (or equivalent non-idempotent method) protected against cross-site request forgery.¶

When a revocation handle is delivered through a token response (in addition to, or instead of, the front channel), clients MUST treat it as sensitive data and MUST NOT expose it in URLs, logs, or user agents beyond what is necessary to present the revocation option to the user.¶

9.8. Revocation Enforcement Boundary

Revocation under this specification is enforced by the AS and by downstream token revocation and status mechanisms; it is not purely cryptographic. A token issued before revocation remains cryptographically valid until it expires, is revoked via the token revocation mechanisms of the host protocol (e.g., [RFC7009]), or is rejected based on status information such as token status lists ([RFC9727]) or shared signals ([I-D.ietf-secevent-caep]). Deployments with short-lived tokens reduce the window during which a revoked consent is not yet enforced; deployments requiring timely propagation of revocation SHOULD combine token revocation with status lists or event-based propagation.¶

This specification does not require resource servers to consult consent state. Whether an RS enforces consent revocation directly, or relies on the AS to revoke the associated tokens, is a deployment decision.¶

9.9. Privacy Considerations

Evidence records contain information about user consent interactions, including what was displayed to the user and how they responded. Implementations should consider applicable data protection requirements when storing and processing evidence records.¶

Consent records and revocation state (Section 7.1) extend these considerations: the revocation timestamp and method are part of the user's consent history. Access to the revocation endpoint MUST require principal authentication so that the consent history of one user cannot be inspected by another, and retention of consent records after revocation SHOULD follow the same data protection policies that apply to the evidence records themselves.¶

10.1. OAuth Authorization Details Type Registration

This specification registers the following authorization details type in the "OAuth Authorization Details Types" registry established by [RFC9396]:¶

Type:

authorization_evidence¶

Description:

Authorization evidence and audit trail information using the enriched response pattern, providing cryptographic proof of user consent for authorization proof and audit purposes.¶

Change Controller:

IETF¶

Specification Document:

Section 3 of this document¶