]> Alibaba

max.ldp@alibaba-inc.com

Security Web Authorization Protocol OAuth Authorization Rich Authorization Requests Fine-Grained Authorization Behavioral Authorization This specification defines a framework for constructing fine-grained authorization requests in OAuth 2.0 using domain-specific authorization schemas: structured definitions of behavioral boundaries for a particular application domain. Schema instances are carried in authorization requests via authorization_details; upon approval, the instance governs the authorization associated with the issued access token. Approved instances have a lifecycle: they become active upon approval and end, with defined protocol consequences for token issuance, refresh, and resource access. Resource servers verify client behaviors against the approved schema instance at runtime through deterministic constraint evaluation. Authorization servers review requested schema instances against server-side authorization policies. This specification also defines a negotiation pattern, reverse-guided authorization, allowing resource servers to reference a schema profile in error responses, guiding clients toward the authorization required for their next action.

Introduction When a client performs a delegated task such as "help me find and buy a laptop", the sequence of operations (product search, price checking, coupon search, cart management, payment, shipping selection) is determined at runtime. Scopes cannot express the constraints a deployment actually wants to approve for such work: an overly broad scope grants unchecked power (violating least privilege), while an overly narrow scope causes frequent authorization failures that interrupt task execution. This specification builds on OAuth 2.0 and Rich Authorization Requests (RAR) by defining a profile based on domain-specific authorization schemas. A domain-specific authorization schema is a structured description of behavioral boundaries for a particular application domain, such as transaction boundaries for e-commerce operations. A client requests authorization by submitting a schema instance in authorization_details; the Authorization Server reviews it against server-side authorization policies, and upon approval the instance governs the authorization associated with the issued access token. At runtime, the Resource Server verifies each client behavior directly against the approved schema instance through deterministic constraint evaluation; when a behavior exceeds the approved boundaries, the Resource Server returns structured schema requirements guiding the client toward the required authorization ().

Scope This specification defines the profile: how schema instances are constructed and discovered, requested, reviewed, bound to access tokens, given a lifecycle, verified at resource servers, and negotiated through structured error responses. The governance layer is out of scope: how an organization records authorization decisions as approval evidence is defined by complementary work. This specification defines the binding-layer state machine on which such governance decisions act; it does not define the decisions themselves. Guardrails () are type-scoped: a guardrail instance of one schema type constrains instances of that type only. The only cross-type apparatus available above specific schemas is the RAR common fields (actions, locations) of Section 2. This specification does not define a universal guardrail spanning multiple schema types. Out of scope: schema definitions for particular domains are expected in follow-up specifications, and the transaction_authority type () is a non-normative worked example; how a deployment determines work membership or plans task sequences is not specified; how the Authorization Server expresses its internal review policies is an implementation decision.

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 when, and only when, they appear in all capitals, as shown here.

Domain-Specific Authorization Schema:

A structured definition of task and authorization boundaries for a particular application domain, identified by an authorization details type (a short name or an HTTPS URI, ) and usable by clients to construct authorization requests. A schema defines constraint fields whose values are machine-verifiable at runtime through deterministic evaluation.

Schema Instance:

A concrete authorization details object conforming to a domain-specific authorization schema, carried in authorization_details. When approved by the Authorization Server, the schema instance is bound to the access token and verified by the Resource Server against each client behavior at runtime.

Bounded Work:

The overall objective for which a client requests authorization, such as "help me find and buy a laptop". The work_id assigned by the AS upon approval is the identity of the approved work. A work authorization is a schema instance approved for the overall work; task requests performed under the work are verified against its boundaries ().

Task:

A unit of activity performed by a client in pursuit of a bounded work. A task-level authorization request references the work it serves via the work_id field.

Task-in-Work Evaluation:

The deterministic verification, performed by the Resource Server, that a requested task is consistent with the boundary constraints of the approved work instance.

Guardrail Instance:

A schema instance used as an upper bound on other instances of the same type ().

Approver:

The party whose authorization decision establishes a governing authorization for requested work. The approver is authenticated, is entitled to approve the bounds in question, and is recorded on the approved instance as the party accountable for the decision.

Subject:

The user on whose behalf the work is performed. The subject and the approver are often the same person but need not be; for example, a manager can approve work performed on an employee's behalf.

AS Review Policy:

Server-side authorization policies used by the Authorization Server to review requested schema instances before approval. Review policies are managed by the Authorization Server.

Policy Enforcement Point (PEP):

The entity that enforces authorization decisions, allowing, denying, or adapting the client's request. In this specification, the Resource Server acts as the PEP, verifying each behavior against the approved schema instance.

Rich Authorization Requests (RAR):

A framework defined in for expressing fine-grained authorization requirements through the authorization_details parameter.

Domain-Specific Authorization Schema This specification defines a profile for domain-specific authorization schemas used with Rich Authorization Requests (RAR). Schema instances carried in authorization_details are structured data; when approved by the Authorization Server, the instance is bound to the access token and verified by the Resource Server at runtime through deterministic constraint evaluation. Schema instances are carried within the authorization_details parameter as the primary mechanism. This specification standardizes the binding of the approved instance to the access token, not the specific input channel by which the instance reaches the Authorization Server; schemas can accordingly be used with any authorization flow that supports authorization_details. Implementations MAY combine domain-specific authorization schemas with other RAR types in a single request. Resource servers MAY advertise the authorization details types they support via authorization_details_types_supported (); the relationship to per-type metadata is described in .

Type Identifiers The type field of a schema instance identifies the domain-specific authorization schema it instantiates. A type value is either: a short name: a lowercase ASCII string with optional underscore separators, no spaces, no leading or trailing whitespace; or an HTTPS URI: e.g., https://api.shop.example/schemas/transaction_v2. RFC 9396 imposes no syntax constraints on the type field, so URI-valued types are wire-compatible. The registry of is an optional endorsement channel for schemas intended for cross-vendor reuse, not an admission control (the hard gates are "known to the Authorization Server" on the AS side and deterministic resolvability on the Resource Server side). Type identity is exact string match: two instances have the same type if and only if their type values are byte-for-byte identical. Implementations MUST NOT normalize URI type values. A URI type value SHOULD be dereferenceable: an HTTP GET over TLS returns a JSON Schema document describing the structure of conforming instances. This aligns with the schema / schema_uri attributes served by the authorization details types metadata endpoint of . The document obtained by dereferencing is a descriptive input for instance construction, not an authorization and not authoritative for the AS's validation, which is performed against the schema known to the AS (fail-safe: an instance constructed from a drifted document fails validation). The same schema MUST NOT be simultaneously identified by both a short name and a URI; registered URI types MUST commit to semantic immutability: changed semantics require a new URI (see ).

Framework Requirements Authorization details types intended for use as domain-specific authorization schemas MUST satisfy the following requirements. These requirements apply to every schema used with this framework, whether or not its type is registered: Structured Constraints: The type MUST define its constraint fields with unambiguous data types and deterministic verification semantics, such that a Resource Server can verify a behavior against an approved instance without policy interpretation; Allowlist Semantics: The type MUST define constraint fields that express what is permitted: a behavior is permitted only when explicitly allowed by the present constraint fields of the approved instance; Common Fields: The type uses the common fields defined in (actions, locations, datatypes, identifier) to declare a declarative upper bound on the requested operations and resources; Subset Definition: The type SHOULD define what it means for one instance to be a subset of another, to support progressive narrowing in Token Exchange (). There is no standardized mechanism for comparing two arbitrary authorization details requests (); each schema type defines its own subset semantics under this requirement. Schema instances used with this specification MUST adhere to the following: Schema Conformance: Every instance MUST validate against the definition of the schema it instantiates. Unknown fields not defined by the schema MUST be rejected by the Authorization Server. Constraint Values: Constraint values MUST be within the ranges and formats defined by the schema (e.g., quantities with units such as a currency or a count, or timestamps per ). Deny by Default: An instance constrains behavior only through its present fields. Any behavior not consistent with every present constraint is denied; an empty or absent boundary grants no behavior (). Because instances are structured data rather than executable code, verification at the Resource Server is deterministic constraint evaluation; review logic is an Authorization Server implementation detail.

Framework Fields The following fields are defined by this framework and MAY appear in instances of any domain-specific authorization schema. Schema types MUST NOT redefine them.

work_id:

OPTIONAL. The AS-assigned identifier of an approved work instance. When approving a work instance, the AS assigns a unique work_id and makes it available to the client (e.g., in the enriched authorization_details of the issued access token or in the token response). Task-level requests include the AS-assigned work_id verbatim so that the Resource Server evaluates each task against the approved work boundaries (). Clients MUST NOT invent work_id values.

work_ref:

OPTIONAL. An AS-assigned reference to the approved work instance, embedded by the AS in the enriched authorization_details of a task token, from which the Resource Server resolves the work instance via local cache or token introspection (). It is not client-supplied.

evidence_ref:

OPTIONAL. A reference to an approval evidence record associated with the approval decision for this instance. This specification defines only the carriage of the field; the format of the reference and the resolution of the record are outside its scope (see ). The presence or successful verification of approval evidence does not establish current permission ().

Bounded Work and Task Requests An overall objective delegated to a client, such as "help me find and buy a laptop", is modeled as a bounded work. A client requests work authorization by submitting a schema instance that captures the proposed boundaries for the entire work, for example permitted operations, targeted resources, and a time window. When the Authorization Server approves the work instance, it assigns a work_id () and makes it available to the client, e.g., in the enriched authorization_details of the issued access token or in the token response. Subsequent authorization requests for individual tasks performed under the work include the same work_id and are verified against the work's approved boundaries: at runtime, the Resource Server evaluates each requested task against the work instance through deterministic constraint evaluation (), a task-in-work evaluation request. The approved schema instance represents the current authorized state of the work. Schemas MAY define cumulative constraints, whose values the Resource Server accumulates across the tasks performed under the work; derived authorizations can progressively narrow the work boundaries via Token Exchange subset semantics ().

Guardrail Instances A guardrail instance is a schema instance used as an upper bound on other instances of the same type. An instance is a hard constraint on behaviors; a guardrail is a hard constraint on instances. Guardrails introduce no new mechanism: they reuse the schema instance structure, the subset semantics of the type, and deny-by-default. The core rule is one sentence:

• Every schema instance approved under this framework MUST be a subset of every guardrail instance of the same type (byte-exact type identity, ) that is in effect for that approval.

Guardrail instances come from two sources: Administrative guardrails are configured by deployment administrators or organizational policy. They express hard ceilings, such as regulatory requirements, risk appetite, and organizational limits, and clients cannot propose instances beyond them. Proposed guardrails are submitted by clients and become effective upon AS approval. Typical uses are limits set by the resource owner ("at most 500 USD this month", in a payment schema), client self-limitation, and subject-level limits. A proposed guardrail that represents a user-set limit or a subject-level limit MUST obtain the resource owner's consent before the AS approves it; a proposed guardrail that purely self-limits the client MAY be approved according to AS policy. Two rules prevent the obvious implementation mistakes: The guardrail check is a necessary condition for approval, never a sufficient one. Approval of an instance is the conjunction of schema conformance, the AS's approval basis (), and the guardrail subset check. An implementation MUST NOT treat a subset relation between an instance and a guardrail as authorization to approve the instance: a wide guardrail, once approved, never exempts subsequent instances from the remaining checks. A proposed guardrail must itself respect the administrative ceiling. When administrative guardrails exist for a type, a proposed guardrail of that type MUST be a subset of every administrative guardrail of that type to be approvable. Clients may propose to tighten, never to exceed. When multiple guardrails are in effect, an instance must be a subset of each: their constraints compose by intersection. A guardrail that omits a constraint field defined by the schema does not constrain that field. This is distinct from deny-by-default, which bounds a behavior relative to the approved instance: the instance is the complete statement of what is permitted, while each guardrail bounds only the fields it mentions. Guardrail instances sit above work and task instances; the same schema and subset machinery is reused at every level. The lifecycle of guardrails follows the instance lifecycle () with two clarifications. Tightening a guardrail applies to subsequently approved instances immediately; the AS SHOULD revoke already-approved instances that exceed the tightened guardrail, reusing existing mechanisms (token revocation, token introspection reporting the tokens inactive, and RS deny-by-default); whether such revocation is enforced immediately is a deployment configuration. Removing a guardrail removes a ceiling and revokes nothing: ending a constraint is not ending an authorization, and implementations MUST NOT conflate the two. Relaxing a guardrail (e.g., raising a limit) is not a derivation and MUST NOT be performed via Token Exchange: it requires a new, independent authorization decision, with resource owner consent where required and revocation or supersession of the old guardrail, consistent with the monotonic narrowing principle, which constrains derivation chains, not new authorizations. Automatic widening is prohibited. An administrative guardrail limiting a transaction type to a total of 1000 USD and a fixed set of operations:

A client then requesting an instance of the same type with total_amount_limit of 1200 USD exceeds the guardrail and is rejected by the AS, whatever the approval basis would otherwise conclude. Security considerations specific to guardrails (probing, the descriptive nature of guardrail documents, and the closed-operator restriction) are described in . The type-scoped limitation of guardrails is recorded in .

schema_ref Claim The schema_ref claim is an OPTIONAL shorthand mechanism for referencing an approved schema instance in access tokens. When the AS uses Rich Authorization Requests (RAR), the enriched authorization_details array in the access token (per ) is the primary mechanism for carrying the approved schema instance. The schema_ref claim MAY be used as a lightweight alternative when: The inline instance content would make the access token exceed practical size limits (see ); The Resource Server already has a cached copy of the instance and only needs an identifier to look it up; The deployment uses opaque (non-JWT) access tokens where token introspection provides the instance content. When schema_ref is used, the AS performs instance registration as described in .

Claim Name:

schema_ref

Claim Type:

String

Usage:

JWT access tokens (the claim may also appear in introspection responses for opaque tokens per )

The schema_ref claim value is a string containing the unique instance identifier assigned by the Authorization Server during instance registration.

The Resource Server uses this identifier to look up the full approved instance from a local cache or via token introspection ().

Protocol Flow The end-to-end schema binding flow proceeds as follows. The client proposes a domain-specific schema instance in the authorization request; the Authorization Server reviews and approves it; and the Resource Server verifies each client behavior against the approved instance through deterministic constraint evaluation. Authorization Request: The authorization request includes authorization_details containing a schema instance (e.g., of type transaction_authority, , with the boundary constraints), using RAR () for structured authorization requests. Instance Validation: AS validates that the instance conforms to the definition of the declared schema (see ). Review and Approval: AS determines whether the proposed behavioral boundaries are appropriate for the specific client and resource owner, based on client registration metadata, organizational review policies, resource owner consent, token binding context, and any effective guardrails (see ). The AS does not perform per-behavior verification (which occurs at the Resource Server). Token Binding: AS issues an access token with enriched authorization_details array per , binding the approved schema instance to the token. The AS MAY include additional metadata in the authorization_details object (e.g., server-assigned identifiers such as work_id or work_ref, or normalized instance content) but MUST NOT alter the semantic meaning of the instance without client consent. Behavior Execution: The client presents the token to the Resource Server when performing a behavior. Instance Extraction: RS extracts the approved schema instance from the enriched authorization_details in the access token. Behavior Verification: The RS verifies the client's current behavior (action, target resource) against the boundary constraints of the approved instance through deterministic constraint evaluation. Enforcement: RS enforces the per-behavior decision, allowing or denying the client's action. Response: RS returns the result to the client.

Reverse-Guided Authorization Traditional OAuth error responses indicate authorization failure without providing guidance on how to obtain valid authorization. This specification defines a negotiation pattern in which the resource server guides the client toward the authorization required for its next action: when the client's next planned behavior falls outside the approved schema instance (behavioral drift), the client needs structured guidance to recover autonomously. Resource servers provide this guidance through structured error responses that enable clients to construct authorization requests with updated behavioral constraints.

Error Response Format When a client's request lacks sufficient authorization, the resource server returns an error response with a WWW-Authenticate header containing the insufficient_authorization error code, the error code defined and registered by , together with a schema_profile_uri parameter defined by this specification. The parameter is a URI referencing a schema profile document, a machine-readable JSON description of the required authorization conditions.

Per , the error response includes the WWW-Authenticate header with the error code and a JSON error body. The schema_profile_uri parameter carries a URI rather than an encoded payload: this keeps the header well within practical size limits and follows the precedent of the resource_metadata parameter in Protected Resource Metadata (). The client fetches the schema profile document referenced by the URI with an HTTP GET request over TLS. The fetched document has the following structure:

When the schema_type of a profile document is a URI type value (), the client MAY dereference it to obtain the type's JSON Schema description, which complements the profile's constraint descriptors with the structural definition of the schema.

Relationship to insufficient_scope defines the insufficient_scope error for cases where the access token lacks the scopes required by the resource server. The insufficient_authorization error used by this specification addresses a broader condition: the token may include adequate scopes but lack the schema-based authorization structure (e.g., boundary constraints or user confirmation) required by the resource server. For example, consider a client holding an access token with scope purchase that attempts to create a 500 USD purchase. The resource server requires a schema instance that limits transaction amounts and requires user confirmation for purchases above 200 USD. The scope is sufficient, but the token lacks the required schema binding. The insufficient_scope error cannot express this condition because the deficiency is structural (missing boundary constraints and confirmation signal), not scope-based. The insufficient_authorization error with a schema_profile_uri allows the resource server to convey both the missing boundary constraints (e.g., boundary.total_amount_limit) and the need for user confirmation (confirmation_required: true) in a machine-parseable form that the client can act on autonomously. Resource servers SHOULD use insufficient_scope when the deficiency is purely scope-based and insufficient_authorization when the deficiency involves boundary constraints that cannot be expressed as additional scopes.

Relationship to RAR Metadata and Error Remediation The error code and type-level metadata defined by address a related but different granularity than the reverse-guided mechanism defined here. That document registers the insufficient_authorization error code used above and defines the authorization_remediation error parameter, whose decoded contents carry actionable authorization details objects the client can request directly. This specification defines the schema_profile_uri parameter, which references a reusable profile document describing the shape of acceptable instances. The two remediation styles are complementary: an RS that knows the exact authorization details objects it needs (e.g., a specific direct debit mandate) returns them inline via authorization_remediation; an RS that publishes reusable behavioral requirements, as in multi-tenant or federated environments where many clients need the same shape of authorization, references a profile document via schema_profile_uri, which is cacheable (the URI MAY be used as a cache key) and additionally discoverable upfront via the schema_profiles attribute in Protected Resource Metadata. A resource server MAY combine both. Profile documents defined here use schema_type and JSON Schema descriptor vocabulary so they remain compatible with the type-level JSON Schema descriptions served by the metadata endpoint of that document.

Schema Profile Structure The schema profile document contains the following fields:

schema_type:

REQUIRED. The authorization details type identifier (a short name or URI, ; e.g., transaction_authority as defined in ) that the client MUST use in the constructed schema instance. Because the constraint descriptors below use the field names of this schema, the client can map a profile document to an instance mechanically.

required_scope:

OPTIONAL. Array of scope values that the access token MUST include.

required_claims:

OPTIONAL. Array of attribute names (e.g., agent_id, user_id) that MUST be present in the authorization context established by the access token. For JWT access tokens, these are claim names that MUST appear in the JWT. For opaque access tokens validated via introspection (), these are field names that MUST appear in the introspection response.

constraints:

OPTIONAL. Object defining boundary constraint descriptors that MUST be satisfied. Each key is a dotted path into the schema instance structure (e.g., boundary.total_amount_limit), using the field names of the schema identified by schema_type. Each value is a descriptor object using the JSON Schema vocabulary : type (data type), description (human-readable explanation), enum (allowed values), and required (boolean, whether a value for this path must be present in the instance).

confirmation_required:

OPTIONAL. Boolean indicating whether explicit user authorization is required for the requested behavioral boundaries. If true, the client MUST initiate an OAuth authorization flow to obtain the resource owner's explicit consent for the submitted schema instance. This does not mean local user confirmation (e.g., a modal dialog) is sufficient; the authorization must be obtained through the AS to produce a token with appropriate grants. The specific interaction mechanism depends on the OAuth flow in use (e.g., the interaction_required error with JWT Grant Interaction Response , or the prompt parameter in the authorization code flow).

auth_server:

REQUIRED. Identifier of the authorization server capable of issuing tokens that satisfy these requirements. The client can discover the token endpoint and other metadata via OAuth 2.0 Authorization Server Metadata () or OAuth 2.0 Protected Resource Metadata () using this identifier.

Profile-to-Instance Example Given the profile document above, a client constructs a transaction_authority instance that satisfies every constraint descriptor: the instance uses the type named by schema_type, the paths under constraints are populated with conforming values, and the request includes the scope named by required_scope:

The client submits this authorization request to the authorization server identified by auth_server. Because confirmation_required is true, the client initiates the user consent flow before the token is issued.

Client Adaptive Behavior Upon receiving a reverse-guided authorization response, the client SHOULD: Fetch the schema profile document referenced by schema_profile_uri over TLS and parse it to understand the authorization requirements. Verify that the specified auth_server is trusted before proceeding. Construct a new authorization request including the required scopes and a schema instance of the type named by schema_type that satisfies the constraints specified in the profile document, and any additional parameters required by the resource server. If confirmation_required is true, initiate user consent flow. Discover the token endpoint via the auth_server's metadata () and submit the authorization request. This allows clients to obtain authorization requirements dynamically instead of pre-programming them per resource server. During multi-step task execution, a client may encounter behavioral drift: situations where the next behavior in its plan falls outside the approved schema constraints. When this occurs, the client has three options: (1) request a new authorization with an updated schema instance that accommodates the new behavior (using the reverse-guided authorization mechanism described above); (2) degrade its behavior to stay within the approved constraints (e.g., selecting an alternative, less privileged action); or (3) request human confirmation to approve an expanded behavioral boundary. The choice among these options depends on the client's task context and the confirmation_required signal from the resource server.

Denial Semantics When the Resource Server denies a request under this framework, the reason falls into one of three classes, and the correct client response differs by class: The authorization has ended (withdrawn, terminated, expired, or completed, ): the operation is impermissible no matter how valid the credential appears, and the client MUST NOT retry it under the same or an equivalent authorization. Work under an ended authorization requires a fresh authorization decision. The operation is outside the approved bounds while the authorization is active: the client's options are a new authorization decision (potentially via reverse-guided guidance), behavioral degradation, or human confirmation for an expanded boundary (). Only the credential is invalid (e.g., the access token has expired while the authorization remains active): the client obtains a new credential for the same authorization (e.g., via the refresh token, ). The resource server signals class 3 with the invalid_token error of and classes 1 and 2 with insufficient_authorization (with a schema_profile_uri parameter when guidance is available); distinguishing class 1 from class 2 in the response is deployment policy, for example via error_description, and a client that cannot distinguish them MUST treat the denial as class 2 and attempt remediation at most once before stopping.

Authorization Server Processing

Instance Validation Upon receiving an authorization_details request containing a domain-specific schema instance, the AS MUST perform the following validation steps: Type Check: Verify that the type field identifies a domain-specific authorization schema known to the AS (e.g., transaction_authority, ), whether a registered short name or a URI the AS recognizes. Schema Conformance: Validate the instance against the definition of the declared schema, including required fields, value types, and formats. Unknown fields not defined by the schema MUST be rejected. Constraint Values: Verify that constraint values are within the ranges and formats defined by the schema (e.g., non-negative monetary amounts, well-formed timestamps with start earlier than end). Behavioral Boundary Check: Verify that the RAR common fields (actions, locations) do not exceed the client's registered permissions. The AS SHOULD also verify that the boundary constraints are consistent with the common fields (e.g., every operation listed in boundary.operations corresponds to a declared action). Because the request carries structured data rather than executable code, no syntax parsing, entry point resolution, or safety analysis of program code is required.

Instance Registration When the AS issues a schema_ref claim instead of embedding the full approved instance in authorization_details, the AS MUST register the instance: Assign a unique instance identifier; Store the approved instance content; Associate the instance with the authorization session, including its lifecycle state (); Optionally, pre-process the instance for faster verification. When the AS embeds the approved instance directly in the enriched authorization_details (the primary path), explicit registration is not required; the instance travels with the token. Instance registration in this specification is dynamic and on-demand. The Authorization Server does not need to maintain a pre-configured catalog of instances. When a schema instance is submitted for binding, the AS reviews it against pre-established approval principles (see ) and registers it only if approved.

Error Responses If instance validation or approval fails, the AS MUST return an error response per . The following table consolidates the error taxonomy for schema-instance-related conditions. The AS selects the error code based on the nature of the failure: Condition Error Code Rationale Unknown type (schema not known to the AS) invalid_request Schema identifier not recognized Missing required schema field (e.g., boundary) invalid_request Instance does not conform to the schema Unknown field not defined by the schema invalid_request Instance contains fields outside the schema Constraint value out of range or malformed invalid_request Constraint value violates the schema definition Instance exceeds an effective guardrail invalid_request Instance not a subset of every effective guardrail Instance references an ended authorization (work_id of an ended work) invalid_request Ended authorizations do not support new issuance RAR common fields exceed client's registered permissions invalid_scope Behavioral boundary exceeds pre-approved scope Other review failures (e.g., organizational review policy denies this pattern) invalid_request Approval basis not satisfied User consent required before binding interaction_required Per JWT Grant Interaction Response Example error response:

Approval Basis The Authorization Server's approval of a schema instance is not limited to conformance validation. The AS determines whether the proposed behavioral boundaries are appropriate for the specific client and resource owner based on the following factors: Client registration metadata: pre-registered client capabilities, allowed scopes, and trust level established during OAuth 2.0 Dynamic Client Registration or out-of-band provisioning. Organizational review policies: administrative rules defining which behavioral patterns are permitted for specific client types, user roles, or resource classes within the deployment. These rules are internal to the AS and are never carried in authorization requests or access tokens. Resource owner consent: explicit authorization from the approver () approving the submitted behavioral boundaries, obtained through the OAuth 2.0 authorization interaction (e.g., the consent screen in the authorization code flow, or the interaction_uri mechanism in JWT Grant Interaction Response). Token binding context: the authorization grant type, requested scopes, and other token request parameters that establish the context in which the schema instance is reviewed. Guardrail subset checks: for every guardrail instance in effect for the type (), the submitted instance MUST be a subset. The guardrail check is a necessary condition for approval, never a sufficient one: approval is the conjunction of schema conformance, the approval factors in this section, and the guardrail subset checks, and no conjunct may substitute for the others. For example, the AS MAY maintain a per-client allowlist of approved behavioral patterns (e.g., permitted actions, maximum transaction limits, allowed resource classes). When a new schema instance is submitted, the AS verifies that the declared RAR common fields (actions, locations) and the boundary constraints fall within the client's pre-approved boundaries. If the proposed instance exceeds these boundaries, the AS SHOULD return invalid_scope when the behavioral boundaries exceed the client's registered permissions, or invalid_request for other review violations (see the consolidated taxonomy in ). Alternatively, the AS MAY escalate to the resource owner for explicit consent before issuing the token. Because instances are structured data with schema-defined fields, this review is a comparison of constraint values against the AS's approval principles, rather than analysis of arbitrary program code. The schema instance carried in the access token is therefore backed by both schema conformance and the review policies governing the client and resource owner. The Resource Server can rely on this when enforcing the approved instance at runtime.

Refresh Token Handling When an access token carrying an approved schema instance expires and the client obtains a new access token via a refresh token, the AS re-binds the same approved instance to the new access token. The client does not resubmit the instance in the refresh request; the AS retrieves it from the authorization session state associated with the refresh token. Refresh is a token-renewal operation, not an authorization request. A refresh request MUST NOT modify the approved schema instance. If the client's task requires different behavioral boundaries, the client MUST either initiate a new authorization request (using the reverse-guided mechanism described in if applicable) or use Token Exchange () as described in . Both paths go through the full validation and approval process defined in this section. The refresh token lifetime SHOULD NOT exceed the validity period of the associated schema instance. If the instance has a natural expiration (e.g., a time-window constraint), the AS SHOULD align the refresh token lifetime accordingly.

Resource Server Enforcement The Resource Server acts as the Policy Enforcement Point (PEP) in this framework. When a behavior is presented with a token, the operative question is not merely "is this token valid?" It is the two-part question: Is the authorization bound to this token still active, and is this operation within its bounds? The two parts fail independently: the lifecycle part fails for a valid token whose authorization has ended (); the bounds part fails for a valid token on live work that reaches outside what was approved. The Resource Server extracts the approved schema instance from the access token, verifies each client behavior against the boundary constraints through deterministic constraint evaluation, and enforces the resulting decision (allow or deny). When the behavior is a task performed under an approved work (identified by work_id), this verification is a task-in-work evaluation: the task is checked against the work's approved boundaries ().

Instance Retrieval The RS obtains the approved instance from the access token. The primary mechanism is to extract the instance from the enriched authorization_details array included in the token per . The binding between the instance and the access token depends on the token type. For JWT access tokens, the instance content or schema_ref claim is integrity-protected by the token signature. For opaque tokens, the binding is established through token introspection or a shared back-channel between the AS and RS. When the token uses the schema_ref claim instead of inline instance content, the RS retrieves the instance using one of the following methods: Local Cache: Use a cached copy if available and not expired. Introspection: Retrieve the instance content via token introspection . Work Instances: When the task token's enriched authorization_details carries an AS-assigned work_ref, resolve the approved work instance from the local cache or via token introspection ().

Constraint Evaluation After extracting the approved instance from the token, the RS verifies each client behavior against every constraint present in the boundary object. Each constraint check is a deterministic comparison between the behavior's attributes and the constraint value, for example: The behavior's operation identifier is contained in boundary.operations; The cumulative transaction amount including the current behavior does not exceed boundary.total_amount_limit; The target merchant is contained in boundary.merchant; The current time is within boundary.time_window. When a behavior is performed under an approved work (see ), these checks constitute task-in-work evaluation: the RS verifies the task against the work instance's boundary constraints, including cumulative constraints, where defined by the schema, evaluated across all tasks performed under the work. Cumulative constraints are evaluated against state maintained by the Resource Server, which observes the underlying business activity (e.g., cart and order state in an e-commerce deployment). The Authorization Server approves the bound but does not track runtime usage.

Enforcement Decision Based on the constraint evaluation: If the behavior is consistent with every present constraint: Allow the behavior; If the behavior violates any present constraint, or if the behavior cannot be mapped to the approved instance: Deny with 403 Forbidden. When the denial results from behavioral drift, the RS MAY apply the reverse-guided mechanism () to guide the client toward a new authorization; If the instance cannot be retrieved or parsed, or if the authorization bound to the token has ended (): Deny with 403 Forbidden.

Instance Lifecycle An approved schema instance has a lifecycle. The lifecycle has two states and four ending reasons; the requested instance before approval is an object (a proposal), not a state: a rejected proposal never enters the lifecycle.

active:

The instance has been approved and bound. Tokens issued for it carry its authority; the AS accepts new task requests referencing its work_id, and refresh re-binds the same instance.

ended:

The instance no longer permits anything. Ended is terminal: an ended instance does not support new issuance, refresh, or derivation, and widening requires a fresh authorization through the AS (the monotonic narrowing principle, ).

An active instance ends in one of four ways, and the distinction among them matters for accountability: completed (the termination criterion is satisfied, e.g., the report is filed), withdrawn (the approver withdraws the work), terminated (an administrator or governance process ends it), or expired (the maximum lifetime elapses, e.g., a time_window constraint). The framework maps these concepts onto OAuth mechanisms as follows: Concept state Protocol observation and mechanisms active Instance approved and bound: inline enriched details (primary) or schema_ref + AS-side registration (lightweight); AS accepts new task requests referencing the work_id; refresh re-binds the same instance ended (withdrawn or terminated) AS marks the registered instance ended, revokes associated tokens (), and refuses new issuance, refresh, and derivation referencing it; token introspection () returns active: false; RS applies deny-by-default ended (expired) time_window or maximum lifetime: the RS determines expiry deterministically from the instance content, without AS-side state transition; the AS refuses refresh (token lifetime SHOULD NOT exceed instance lifetime, ) ended (completed) Termination criterion satisfied; which party reports completion is deployment-defined (a client's self-report is safe in this framework because ending only removes authority) inline instance (degenerate case) For an instance that governs a single request, ended is equivalent to token revocation or expiry: a bounded token lifetime gated on active authorization Guardrail instances follow the same lifecycle, with the tightening, removal, and relaxation semantics defined in . Because the ending of an authorization is a state change to one object with consequences for everything bound to it, the denial semantics of apply: a valid credential does not authorize further operations for work that has ended. Deployments MUST place a finite bound on how long a Resource Server continues to accept a token after the authorization it was issued for has ended; token lifetimes and introspection are the mechanisms this specification relies on, and the bound they define is the worst-case exposure window between an ending and its observation. The work_id and any evidence_ref of an ended instance remain meaningful as record locators: approval evidence records what was decided and remains available for accountability after the work is over, but its existence does not establish current permission (). Privacy considerations for authorization identifiers spanning multiple resource servers, including per-audience schema_ref variants, are discussed in .

Token Exchange (RFC 8693) When exchanging tokens , a new schema instance can be provided to refine or restrict the approved behavioral boundaries:

The resulting access token MUST include the new approved schema instance. Because schema instances are structured data, subset verification is decidable: each constraint in the new instance can be compared field-by-field against the corresponding constraint of the original instance (e.g., a lower total_amount_limit, a subset of operations, or a narrower time_window). The AS MUST verify that the derived instance is a subset of the original instance and reject the exchange otherwise; Token Exchange in this framework is narrowing-only, by construction. There is no standardized mechanism for comparing two arbitrary authorization details requests (); each schema type defines its own subset semantics under the framework requirements (). If the client requires broader behavioral boundaries, it MUST obtain a new authorization through the AS (for example, via the reverse-guided mechanism in , with resource owner consent where required), rather than widening an approved instance through exchange. Token Exchange is a common trigger for behavioral drift: when a client's next planned behavior falls outside the approved schema constraints, the Resource Server can return an insufficient_authorization error with a schema_profile_uri (as defined in ), guiding the client toward constructing an appropriate Token Exchange request with an updated schema instance.

Security Considerations

Trust Model The framework defined in this specification relies on the following trust assumptions, which deployments MUST evaluate before adoption: AS-to-RS trust: The Resource Server trusts the Authorization Server to validate, review, and bind approved schema instances to access tokens. The RS enforces the instance approved by the AS and does not re-evaluate the AS's approval decision at runtime. This trust relationship is consistent with the OAuth 2.0 trust model in which the RS trusts the AS's issuance of access tokens. Client-to-AS trust: The client trusts the AS to validate its submitted schema instance and issue a token reflecting the approved behavioral boundaries. The client MUST NOT trust instances or profiles received from other parties (including resource servers) without AS approval. AS/RS-to-client distrust: Neither the AS nor the RS trusts the client to act within its approved behavioral boundaries without verification. The AS performs validation and review; the RS performs per-behavior runtime verification. A compromised or malicious AS could embed an overly permissive instance in an access token, causing the RS to allow behaviors that the RS operator did not intend. To mitigate this risk, the RS MAY impose constraints on top of the token-bound instance, for example by deploying guardrail instances (), which are schema-native upper bounds the RS-side deployment can also enforce deterministically, or by: A hard deny list of dangerous or privileged actions that cannot be authorized by any token-bound instance; Rate limiting or transaction caps that apply regardless of the approved instance; Restriction of trusted ASes to a pre-registered allowlist, discoverable via Protected Resource Metadata (). The choice of which ASes to trust is a deployment decision. Resource Servers SHOULD restrict the set of trusted Authorization Servers and reject tokens issued by untrusted ASes. The authorization_servers field in Protected Resource Metadata () provides a mechanism for the RS to advertise its trusted ASes to clients.

No Executable Content Schema instances carried in authorization requests and access tokens are structured data conforming to schema definitions; they contain no executable code. This eliminates the class of attacks associated with client-submitted code, including non-terminating or resource-intensive evaluations, catastrophic regular-expression backtracking, and built-in functions with side effects (e.g., outbound HTTP requests performed during evaluation). Neither the AS nor the RS executes client-supplied content at any point in the flow. To preserve this property, the AS MUST reject instances containing fields not defined by the declared schema, and the RS MUST ignore or reject instances containing unknown fields.

Instance Integrity The schema_ref claim in access tokens MUST reference instances registered and stored securely by the AS. When the access token is opaque, the Resource Server retrieves the instance through token introspection (). The introspection response SHOULD include the approved schema instance using the same mechanisms as the access token: either the enriched authorization_details array containing the approved instance (the primary mechanism), or the schema_ref claim (the lightweight alternative). When a JWT access token is introspected, the introspection response SHOULD reflect the claims present in the JWT, including authorization_details and schema_ref, per . Resource Servers SHOULD invalidate cached instance content when the associated access token expires. If the AS revokes a registered instance before the token expires, because the work was withdrawn or terminated (), the AS SHOULD also revoke the associated access token, causing subsequent introspection calls to return active: false per . Resource servers that observe active: false (or that are otherwise notified of instance revocation through a deployment-specific mechanism) MUST treat subsequent verifications for the token as failed (deny-by-default).

Instance Size Limits Instances embedded inline within authorization_details increase the size of authorization requests and access tokens, and deployments commonly face size limits on HTTP headers carrying JWT access tokens. Deployments facing such constraints can use the schema_ref claim (), which binds a reference to the AS-registered instance instead of inline content.

Reverse-Guided Authorization Implementations of reverse-guided authorization () MUST consider the following security aspects: Auth Server Verification: Clients MUST verify that the auth_server specified in the schema profile document is trusted before submitting authorization requests. Verification SHOULD be performed by comparing the auth_server value against one of the following trust anchors: (1) the authorization_servers field in the Protected Resource Metadata () obtained from the resource server that returned the error; (2) a pre-registered allowlist of trusted authorization servers configured at client provisioning time; or (3) a deployment-specific trust registry. If none of these trust anchors are available, clients MUST NOT submit authorization requests to the specified auth_server. Clients MUST use only the token endpoint discovered from the auth_server's Authorization Server Metadata (). Blindly following redirects or trusting unverified auth_server values could lead to credential theft. Constraint Validation: Clients SHOULD validate that constraint values are reasonable before including them in authorization requests. Malicious resource servers might attempt to induce clients to request excessive permissions. Profile Document Retrieval: The schema_profile_uri is received from the resource server in the error response. Clients MUST fetch the profile document over TLS and SHOULD verify that the URI origin matches the resource server or a domain under its control. The profile document is guidance from the resource server; it does not constitute authorization, and only the Authorization Server can approve a schema instance. All communications in the reverse-guided flow MUST use TLS to prevent man-in-the-middle attacks on error responses.

Guardrails Implementations of guardrail instances () MUST consider the following: Guardrail probing: A client that submits proposed guardrails to discover the AS's ceilings learns no more than error responses to over-broad instances already reveal; the approval boundary is exposed either way. ASs MAY rate-limit proposed-guardrail submissions nonetheless. Descriptive inputs: Guardrail documents and metadata are descriptive inputs, like schema documents. The document a client dereferences may differ from the AS's known copy; validation failure is fail-safe, since the AS validates instances and proposed guardrails against its own knowledge. Closed operators only: Guardrail fields are limited to the closed constraint fields defined by the schema and closed comparison operators. Conditional logic MUST NOT be introduced through guardrails: a guardrail is an upper bound, not a policy decision point. Complex conditions belong to the AS's review policy, which is not carried on the wire.

Privacy Considerations Implementations of this specification MUST consider the following privacy aspects per BCP 188 : Instance Content Privacy: Schema instances embedded in authorization_details may carry identifying data (e.g., merchant and category values in the boundary). When instances are carried in JWT access tokens, this data is visible to any party that can decode the token. Implementations SHOULD avoid embedding personally identifiable information (PII) directly in instance content and instead use correlation identifiers (e.g., transaction_id) that the Resource Server or an audit service resolves when needed. Constraint Disclosure: The schema profile document returned via schema_profile_uri reveals the required boundary constraints to the requesting client. While this disclosure is necessary for the reverse-guided authorization flow, resource servers SHOULD limit the information to what is strictly needed for the client to construct a valid authorization request, and MUST NOT include internal implementation details, database schemas, or infrastructure information. Endpoint Exposure: The auth_server field in the schema profile document reveals the Authorization Server's identifier. Deployments SHOULD use well-known identifiers rather than exposing internal service URLs. Behavioral Profiling: The sequence of schema instances submitted by a client may reveal the client's intent, capabilities, or decision-making patterns. Authorization Servers SHOULD treat schema instances with the same confidentiality as other authorization request parameters and MUST NOT use them for purposes beyond authorization decision-making without explicit consent. Cross-Resource Correlation: Authorization identifiers such as work_id, schema_ref, and evidence_ref can correlate a user's activity across resource servers when the same value is observed by multiple RSs. Deployments for which this correlation is a concern MAY use audience-specific schema_ref and work_ref values per resource server, so that each RS observes a distinct identifier for the same authorization; the AS maintains the mapping. This is a deployment option and does not change the mechanisms defined in this specification.

IANA Considerations

Domain-Specific Authorization Schema Types Registry This specification establishes a new IANA registry titled "Domain-Specific Authorization Schema Types" for identifiers used in the type field of schema instances carried in authorization_details. The registry is an endorsement channel for schemas intended for cross-vendor reuse; schemas MAY be used with this framework without registration, subject to the "known to the Authorization Server" condition of . Registration requests MUST be sent to the oauth-ext-review@ietf.org mailing list for review and comment, using the "Specification Required" policy (). The Designated Expert for this registry SHOULD verify that each registration request satisfies the following criteria before approval: The proposed type identifier is syntactically valid: a lowercase ASCII string with optional underscore separators, no spaces, no leading or trailing whitespace, or an HTTPS URI; The referenced specification defines a complete schema: the full set of fields, their types and formats, which fields are required, deny-by-default semantics, and subset semantics for use in Token Exchange, consistent with the framework requirements defined in ; The schema carries structured data only and defines no executable content; The identifier does not conflict with or confusingly resemble existing registrations, and the same schema is not identified by both a short name and a URI. For URI identifiers, the URI's semantics are immutable: changed semantics require a new URI. Future registrations MUST include: Type identifier (lowercase ASCII string or HTTPS URI); Description of the schema and its intended domain; Reference to the specification defining the schema; Change controller. For URI identifiers, the registration SHOULD also include a hash of the schema document. The registry is initially empty. The transaction_authority example in is non-normative and is not registered.

JWT Access Token Claims Registration This specification registers the following claim in the "JWT Access Token JWT Claims" registry established by :

Claim Name:

schema_ref

Claim Description:

A reference to a registered, approved schema instance in JWT access tokens.

Change Controller:

IETF

Specification Document:

of this document

WWW-Authenticate Parameter Definition This specification defines a new parameter for use in the WWW-Authenticate header field with the Bearer authentication scheme, as defined in .

Parameter Name:

schema_profile_uri

Parameter Usage Location:

WWW-Authenticate response header field, used in resource server error responses that carry the insufficient_authorization error code defined by .

Parameter Description:

A URI referencing a schema profile document containing structured boundary constraint descriptors and authorization requirements that guide the client toward obtaining sufficient authorization. The document structure is defined in of this document.

Change Controller:

IETF

Specification Document:

of this document

RFC 6750 does not establish an IANA sub-registry for Bearer authentication scheme parameters. This section serves as the specification reference for the schema_profile_uri parameter.

OAuth Protected Resource Metadata Registration This specification registers the following attribute in the "OAuth Protected Resource Metadata" registry established by :

Metadata Name:

schema_profiles

Metadata Description:

Array of URIs referencing schema profile documents in the format defined in of this document, describing the authorization required by this resource server.

Change Controller:

IETF

Specification Document:

of this document

Error Code Usage This specification does not register a new error code. The reverse-guided mechanism uses the insufficient_authorization error code defined and registered by in the "OAuth 2.0 WWW-Authenticate Error Code Registry" established by that document.

&RFC9396; &RFC2119; &RFC8174; &RFC9728; &I-D.ietf-oauth-rar-metadata-remediation; &RFC3339; &RFC7662; &RFC6750; &RFC6749; &RFC8693; &RFC7009; &RFC6973; &RFC8126; &RFC9068; JSON Schema &I-D.liu-oauth-authorization-evidence; &I-D.parecki-oauth-jwt-grant-interaction-response; &RFC8414; &RFC7591; &I-D.zehavi-oauth-authority-metadata;

Contributors The following individuals contributed to the IETF 126 presentation and discussions from which this specification grew:

Jeff Lombardo

AWS

Karl McGuinness

Independent

Yaron Zehavi

Raiffeisen Bank International

Yaron Sheffer

Intuit

Suresh Krishnan

Cisco

Acknowledgments The author would like to thank Brian Campbell, Aaron Parecki, Hongru Zhu, and Hui Xue for their valuable input during the development of this specification; their contributions helped shape key design decisions.

Example: transaction_authority This appendix is non-normative. It defines transaction_authority, a worked example of a domain-specific authorization schema that illustrates the framework requirements of . It is not registered in the Domain-Specific Authorization Schema Types registry (); deployments that wish to standardize it or other schemas are expected to do so in follow-up specifications. Nothing in the framework is specific to payments: schemas for other domains, such as calendaring (time windows and attendee scope), document management (access and sharing scope), or service usage (quotas and rate windows), satisfy the same requirements. The transaction_authority authorization data type defines transaction boundaries within which the client is permitted to operate, carried within authorization_details. The example type name is local to this specification and is unrelated to the authority metadata concept discussed in .

Type Name:

transaction_authority

Data Type:

Object

Usage:

authorization_details ()

The following example shows the authorization_details request parameter containing a transaction_authority instance for an e-commerce transaction:

In addition to the common fields defined in (such as actions, locations, datatypes, and identifier) and the framework fields of , the transaction_authority example defines the following type-specific fields:

domain:

REQUIRED. A string identifying the application domain the schema instance applies to (e.g., "ecommerce").

transaction_id:

OPTIONAL. An identifier for the transaction the instance governs. When used together with the authorization evidence mechanism (), the transaction_id correlates the approved instance with the corresponding consent record.

boundary:

REQUIRED. An object containing the transaction boundary constraints. All fields are OPTIONAL; only behaviors consistent with every present constraint are permitted:

total_amount_limit:

An object with value (number) and currency (string) members. The aggregate amount of the client's transactions MUST NOT exceed value in the given currency.

operations:

An array of namespaced operation identifiers (e.g., "ecommerce.cart.add"). Only the listed operations are permitted.

category:

An array of product category identifiers the client is permitted to operate on.

merchant:

An array of merchant URIs the client is permitted to interact with.

time_window:

An object with start and end members, each a timestamp per . Only behaviors occurring within the window are permitted.

The common RAR fields and the boundary constraints serve different consumers at different stages of the authorization flow. The common fields (actions, locations) provide a declarative upper bound on the requested operations and resources, enabling the Authorization Server to approve or reject the request without interpreting the boundary constraints. The boundary constraints define the behavioral limits that the Resource Server verifies against each client behavior at runtime. This layered design allows Authorization Server implementations to review requests declaratively, while the Resource Server performs per-behavior verification through deterministic constraint evaluation. The AS SHOULD verify that the boundary constraints are consistent with the common fields (). The Resource Server bears responsibility for ensuring each verified behavior is consistent with the approved schema instance at runtime.

Open Issues This appendix is non-normative; it records questions on which working group guidance is sought.

Machine-Readable Constraint Semantics Beyond JSON Schema Clients require semantics such as deny-by-default, cross-field relationships, and cumulative-constraint evaluation in a machine-readable form to construct conforming instances autonomously. Candidate approaches include (a) a closed declarative constraint-operator vocabulary, (b) signed server-side policy attachments evaluated in trusted environments, and (c) policy languages such as Rego, used inside the Authorization Server to implement its review of submitted instances. Approach (c) must be reconciled with the No Executable Content principle of this specification (). Guardrail instances () cover the hard-constraint cases; policy languages offer increment only where approval policies need complex cross-field derivation. Whether policy languages can also be carried in reverse-guided responses () has been discussed, but no conclusion has been reached. Working group guidance is sought.

URI-Valued Type Identifiers This specification allows authorization details type values that are HTTPS URIs (). The RAR metadata mechanisms of key type metadata by type name; carrying URI values in those keys is structurally compatible with the JSON map, but the assumption that type names are simple strings is widespread in that document and its implementations. Coordination on the interoperability of URI-valued types is expected; see .

Per-Instance Subset Policy Switch This specification makes subset verification unconditional in Token Exchange (). Deployments requiring relaxation semantics may request guidance from the working group.