# AuthZEN for HTTP Sideband Evaluations

## Abstract

This specification defines how OAuth 2.0 clients can request and receive authorization evaluations through HTTP headers alongside REST operations (POST, PUT, PATCH, DELETE). This enables clients to understand how authorization state may have changed as a result of the RESTful request, without requiring separate authorization API calls. The profile extends the AuthZEN specification to work within OAuth 2.0 environments while maintaining compliance with OAuth standards.

## 1 Introduction

As online digital experiences become more modular, a system understanding when to transiation from one user flow to another brings about a demand for continuous evaluation of state. For example, customer onboarding journeys for regulated industries such as Financial Services, Gambling and Gaming, Real Estate require the capture and maintenance of information to a particular standard, and services not provided unless the record is complete.

Fraud and scam prevention adds further complexity by introducing the need for probabilistic risk assessment — an approach that relies on calculating likelihoods or “risk scores” based on multiple signals rather than making purely binary, rule-based decisions. These signals may include user behavior analytics, geolocation data, device fingerprinting, transaction velocity, and other contextual factors. Defining a user journey design time is not possible or highly complex and a new set of techniques and patterns to drive user experience is required.

Attempting to develop user journies to ensure a customer record is in the correct state or mitigate all risk introduce “friction” for legitimate users, such as additional identity checks, one-time passwords, or manual reviews. While these measures protect against malicious activity, they may also negatively impact user satisfaction or lead to customer abandonment if the process feels overly intrusive. The continuous evaluation of authorization decisions in real time, which drives the user journey dynamically, offers a balanced way to address these concerns.

This standard enables real-time authorization evaluation through HTTP header sideband communications, running parallel to primary REST operations. By integrating state transition logic at the data layer rather than the experience layer, developers can seamlessly connect modular experiences while maintaining security and compliance requirements.

### 1.1 Conventions and Terminology

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 specification uses the terms "access token", "authorization server", "authorization endpoint", "authorization request", "client", "protected resource", and "resource server" defined by "The OAuth 2.0 Authorization Framework" [RFC6749].

## 2. Sideband Evaluation Flow

This specification borrows from the ideas introduced in RFC9470 (OAuth 2.0 Step-Up) and applies a sideband approach to AuthZEN evaluations. Specifically, the client:
1. Sends an AuthZEN evaluation in a RESTful mutation (e.g., POST, PUT, PATCH, or DELETE) via an `Authorization-Evaluation` header.
1. Receives an AuthZEN response using the`Authorization-Evaluation-Result` header within the same HTTP response, thus understanding any new or updated authorization state without needing a separate call.

## 2.1 Example: Todo Application

In this scenario, Bob is submitting a review on a todo item. The evaluation checks if reviewers are allowed to comment after a review is posted. On success, the result returns a true decision and a contextual reason.

**Request**

The OAuth client makes a request to the resource server, providing:
• A valid OAuth 2.0 access token in the Authorization header.
• An AuthZEN evaluation statement in the Authorization-Evaluation header.

POST /todos/1/reviews HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Content-Type: application/json
Authorization-Evaluation: {
  "subject": {
    "type": "user",
    "id": "[e-mail]"
  },
  "resource": {
    "type": "todo",
    "id": "1",
    "properties": {
      "status": "in_review",
      "assignee": "[e-mail]",
      "reviewer": "[e-mail]"
    }
  },
  "action": {
    "name": "can_comment"
  },
  "context": {
    "time": "1985-10-26T01:22-07:00"
  }
}

{
  "comment": "Changes look good!",
  "rating": 5,
  "review_type": "technical"
}

**Server-Side Processing**
1. The resource server processes the incoming POST request.
1. The Policy Enforcement Point (PEP) evaluates Bob’s request to post a review, respecting the OAuth token’s scopes and claims.
1. After successfully updating or creating the “review” resource, the PEP performs an AuthZEN evaluation of whether Bob (or any user) can now comment on the todo based on the new resource state.
1. The server prepares a response that includes both the newly created review resource and the AuthZEN evaluation result via a custom header.

Response

HTTP/1.1 201 Created
Content-Type: application/json
Authorization-Evaluation-Result: {
  "decision": true,
  "context": {
    "reason_user": {
      "message": "Technical review submitted - all reviewers can now comment on this todo"
    }
  }
}

{
  "id": "review_123",
  "todo_id": "1",
  "reviewer": "[e-mail]",
  "comment": "Changes look good!",
  "rating": 5,
  "review_type": "technical",
  "created_at": "1985-10-26T01:22-07:00"
}

**Note**: Authorization-Evaluation-Result is typically included in 200 OK or 201 Created responses, where a resource state change has occurred and an updated authorization decision is available.

## 3. Header Size Limit

Implementers SHOULD be aware that HTTP header size limits vary across servers and intermediaries, commonly ranging from 4 KB to 16 KB. While most AuthZEN evaluation statements are expected to be relatively small (subject, resource, and context data), implementers must consider these constraints in environments with additional or more complex data. If the data surpasses practical header limits, alternative approaches (e.g., chunked or body-based evaluation data) MAY be necessary.

## 4. Protected Resource Metadata

Protected resources that support AuthZEN sideband evaluations SHOULD include the following metadata in their resource metadata document (as per OAuth 2.0 Protected Resource Metadata):

{
  "authorization_evaluation_endpoint": "https://resource.example.com/evaluate",
  "authorization_evaluation_signing_alg_values_supported": ["RS256", "ES256"]
}

This metadata:
• Indicates the endpoint that supports direct AuthZEN evaluations if needed (e.g., for fallback scenarios where header-based evaluations are not sufficient).
• Lists supported signature algorithms for evaluation requests/responses, allowing implementers to verify requests or responses that are digitally signed.

## 5. Signing Responses

When a Resource Server returns sideband authorization evaluations through HTTP headers—especially if these evaluations contain hints, state transitions, or signals prompting the client to obtain a delegated entitlment from a resource owner, or perform some other activity, implementers MUST ensure that the client can verify the integrity and authenticity of the returned information.

If attackers can tamper with these hints or signals, they may cause the client to bypass necessary security checks or capture user credenatisl. To mitigate such risks, responses conveying critical authorization data SHOULD be digitally signed using a mechanism such as JSON Web Signature (JWS). This ensures that the client:
1. Authenticates the Source: The client can confirm that the response originated from the legitimate Resource Server, as opposed to a malicious intermediary.
1. Verifies Integrity: The response contents (e.g., “Resource Owner Consent required,” “risk score,” “approval to proceed”) have not been altered in transit.
1. Relies on Trusted Information: The client can safely act on the provided signals—such as initiating a step-up flow—knowing they were generated under the Resource Server’s authority.

Resource Servers that sign Authorization-Evaluation-Result headers or payloads MUST publish their public signing keys in a format discoverable by the client (e.g., via a JWK Set endpoint as described in [RFC7517]). Clients MUST retrieve and cache these keys using best practices for key rotation and revocation. This approach helps maintain system resilience and prevents reliance on stale or compromised keys.

When signature verification fails, clients SHOULD treat the response as invalid and either fall back to a secondary authorization check or request a fresh evaluation. The precise error handling behavior SHOULD be documented to ensure consistent client implementations across different deployments.

## 6. Security Considerations

Protected Identifiers: HTTP sideband need to conform to client contraints (scopes claims RAR Token).

1. **Transport Security**: All communication carrying Authorization-Evaluation and Authorization-Evaluation-Result headers MUST occur over TLS (HTTPS). This ensures confidentiality and integrity of both the OAuth token and the sideband evaluation data.
2. **Header Data Confidentiality**: Implementers SHOULD minimize sensitive data included in HTTP headers, since many components (e.g., proxies, load balancers) commonly log header data. Where necessary, encryption or tokenization techniques MAY be used.
3. **Alignment with OAuth Scopes and Claims**: The sideband evaluation MUST respect the privileges defined in the OAuth access token. PDPs SHOULD validate that the `Authorization_Evaluation_Result` with the Clients authorized scopes, claims, and rich token (RAR).
4. **Evaluation Signing and Verification**: If signing is used, implementers MUST verify signatures and SHOULD rely on secure algorithms (e.g., RS256, ES256). Key rotation SHOULD follow best practices, with public keys discoverable via JWK Sets.
5. **Optional Encryption**: For especially sensitive evaluations, the Authorization-Evaluation header MAY be encrypted using JSON Web Encryption (JWE) or a similar standard, ensuring only the Resource Server can decrypt it.
6. **Error Handling**: PEPs SHOULD NOT reveal overly detailed internal authorization error messages returned via Authorization-Evaluation-Result. Such detail can assist attackers in circumventing security.
7. **Logging and Audit Trails**: All authorization evaluations SHOULD be logged securely for auditing purposes. Logs MUST be protected according to applicable data privacy regulations and access control policies.

## 7. IANA Considerations

### 7.1. HTTP Header Fields

This specification registers two new HTTP header fields in the HTTP Fields registry, following the procedures in [RFC9110], Section 5.

#### 7.1.1. Registration Template

**Field Name**: Name of the HTTP header field (e.g., “Authorization-Evaluation”).

**Status**: Indicate whether the field is registered as “permanent” or “provisional” in the HTTP Fields registry.

**Specification Document(s)**: Reference(s) to the document(s) that define the header field, preferably including section numbers and/or URLs.

**Field Description**: A brief description of the purpose of the field (e.g., “Used by OAuth 2.0 clients to pass sideband authorization evaluation data.”).

Related Information: (Optional) Any additional information relevant to implementers.

#### 7.1.2. Initial Registry Contents

This document adds the following entries to the “HTTP Fields” registry:
1. **`Authorization-Evaluation`**
* **Field Name**: Authorization-Evaluation
* **Status**: Provisional (or Permanent, depending on community consensus)
* **Specification Document(s)**: Section 7.1.2 of [AUTHZEN-SIDEBAND]
* **Field Description**: Carries an AuthZEN statement (e.g., subject, resource, action, context) that the Resource Server (or a Policy Enforcement Point) will evaluate as part of an OAuth-protected REST request.
*** Related Information**: None
2. **`Authorization-Evaluation-Result`**
* **Field Name**: Authorization-Evaluation-Result
* **Status**: Provisional (or Permanent)
* **Specification Document(s)**:Section 7.1.2 of [AUTHZEN-SIDEBAND]
* **Field Description**: Provides the outcome of an AuthZEN evaluation (e.g., boolean decision, contextual data) in the HTTP response, informing the client of updated authorization state based on the new resource state.
* **Related Information**: None

### 7.2. Other IANA Registries

No other IANA actions are requested by this document.

## 8. References

### 8.1. Normative References

[BCP14] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, https://www.rfc-editor.org/info/rfc2119.

Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, RFC 8174, DOI 10.17487/RFC8174, May 2017, https://www.rfc-editor.org/info/rfc8174.

[RFC6749] Hardt, D., “The OAuth 2.0 Authorization Framework”, RFC 6749, DOI 10.17487/RFC6749, October 2012, https://www.rfc-editor.org/info/rfc6749.

[RFC9110] Fielding, R., et al., “HTTP Semantics”, RFC 9110, DOI 10.17487/RFC9110, June 2022, https://www.rfc-editor.org/info/rfc9110.

[RFC9396] Fett, D., “Rich Authorization Requests”, RFC 9396, DOI 10.17487/RFC9396, July 2023, https://www.rfc-editor.org/info/rfc9396.

[RFC9470] Campbell, B., et al., “OAuth 2.0 Step-up Authentication Challenge”, RFC 9470, DOI 10.17487/RFC9470, September 2023, https://www.rfc-editor.org/info/rfc9470.

[I-D.ietf-oauth-resource-metadata] Parecki, A., “OAuth 2.0 Protected Resource Metadata”, Work in Progress, https://datatracker.ietf.org/doc/draft-ietf-oauth-resource-metadata.

[AUTHZEN] Gazitt, O. (Aserto), Ed., Brossard, D. (Axiomatics), Ed., Tulshibagwale, A. (SGNL), Ed.,
“Authorization API 1.0 — The Access Evaluation API”, Workgroup: OpenID AuthZEN, OpenID Foundation, 6 September 2024, <https://openid.net/specs/authorization-api-1_0-01.html>.

[I-D.ietf-oauth-resource-metadata] Jones, M., Hunt, P., and A. Parecki, “OAuth 2.0 Protected Resource Metadata”,
Internet-Draft draft-ietf-oauth-resource-metadata-13, Work in Progress, 15 October 2024,
<https://datatracker.ietf.org/doc/draft-ietf-oauth-resource-metadata-13/>

[AUTHZEN-SIDEBAND] Hyland, D. “AuthZEN for HTTP Sideband Evaluations”, Internet-Draft draft-hyland-authzen-sideband-00,
Work in Progress, <Date>,

## 9. Acknowledgements

## Authors' Addresses

David Hyland
ID Partners
Email: