COAZ: A Framework for Mapping Information Models to AuthZEN Authorization Requests - Draft 1

1.1. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.2. Terminology

This specification uses the following terms:¶

COAZ:

Compatible with OpenID AuthZEN (pronounced "cozy"). The framework defined by this specification for mapping an information model into an AuthZEN Authorization API request.¶

Binding:

A specification that binds this framework to a specific protocol or interface by fulfilling the conformance requirements of Section 4. A binding is designated COAZ-<PROTOCOL>: for example, COAZ-MCP for the Model Context Protocol. Bindings for HTTP APIs and OpenAPI are anticipated.¶

Operation:

A unit of work in the specific protocol or interface that requires an independent authorization decision from the AuthZEN PDP.¶

Information Model:

The set of data associated with an operation that a binding makes available to a mapping, such as request fields, message parameters, and security tokens.¶

Input Variable:

A named element of the information model, exposed to expressions by a binding (for example, a variable holding a request's parameters or a variable holding decoded token claims).¶

Mapping:

A declarative description of how to construct an AuthZEN Authorization API request from an operation's input variables, consisting of an envelope that names the AuthZEN API to call and a template for that API's request body. Each value in a mapping is either a literal or an expression.¶

Envelope:

The single top-level member of a mapping. Its key names the AuthZEN API (evaluation or evaluations) to which the constructed request is sent, and its value is the template for that API's request body. See Section 2.3.¶

Literal:

A value in a mapping that is used verbatim, as a constant, without reference to any input variable.¶

Expression:

A value in a mapping that is computed by evaluating it, in the binding's expression language (Section 2.6), against the operation's input variables.¶

PDP:

Policy Decision Point, as defined in [AUTHZEN]. A service that evaluates authorization requests and returns access decisions.¶

PEP:

Policy Enforcement Point, as defined in [AUTHZEN]. The component that constructs the AuthZEN request from a mapping, calls the PDP, and enforces the decision.¶

Default Mapping:

A mapping defined by a binding that applies to an operation when no other mapping has been supplied for it. OPTIONAL; see Section 2.8.¶

Declared Mapping:

A mapping supplied by an authority that describes an operation (for example, a server advertising a mapping for a specific operation). OPTIONAL; see Section 2.8.¶

2.1. Overview

A COAZ mapping is a template, corresponding to a distinct operation, for an AuthZEN Authorization API request, in which any value MAY be replaced by an expression over the operation's input variables. To authorize an operation, a PEP:¶

1. Populates the input variables defined by the applicable binding from the incoming operation (see Section 2.2).¶

2. Selects the mapping that applies to the operation (see Section 2.8).¶

3. Resolves every value in the mapping: literals are taken verbatim; expressions are evaluated against the input variables (see Section 2.5 and Section 2.6).¶

4. Constructs the AuthZEN request from the resolved values and sends it to the API named by the mapping's envelope (see Section 2.7).¶

5. Enforces the returned decisions.¶

2.2. Information Model and Input Variables

A binding MUST define the information model it exposes to mappings as a set of named input variables. Expressions reference these variables by name. The framework does not mandate any particular variables; naming and contents are entirely binding-defined. For example, a binding for a request/response protocol might expose a variable for the request and a variable for the caller's authorization token.¶

A binding MUST specify, for each input variable, its name, the source from which the PEP populates it, and its structure, so that a mapping author knows exactly which fields an expression can reference and what they will contain.¶

2.3. The Mapping

A COAZ mapping is a JSON [RFC8259] object with exactly one top-level member, its envelope. The envelope's key names the AuthZEN Authorization API to which the constructed request is sent, and its value is a template shaped exactly as that API's request body. This framework defines two envelope keys:¶

evaluation:

The value is a template for an Access Evaluation request as defined in Section 6 of [AUTHZEN]: a single authorization decision, expressed with subject, action, and resource fields and an OPTIONAL context field.¶

evaluations:

The value is a template for an Access Evaluations request as defined in Section 7 of [AUTHZEN]: one or more authorization decisions, expressed with OPTIONAL top-level subject, action, resource, and context defaults and an evaluations array whose entries MAY each contain their own subject, action, resource, and context fields.¶

A mapping with no top-level member, more than one top-level member, or an envelope key not defined by this framework or by the applicable binding is malformed, and a PEP MUST treat it as a mapping error (Section 3). Future versions of this framework, and individual bindings, MAY define additional envelope keys corresponding to other AuthZEN APIs; a PEP MUST treat an envelope key it does not support as a mapping error rather than ignore it.¶

The framework does not redefine the request structures or their semantics. The meaning of each field and — for the evaluations envelope — the rules by which per-entry fields override top-level defaults are exactly as defined in Sections 6 and 7 of [AUTHZEN]. In particular, custom attributes of a subject, resource, or action MUST be nested under that object's properties key as defined by [AUTHZEN], rather than added as sibling keys; context is a free-form object and is the exception. COAZ's primary addition to these structures is that any leaf value MAY be an expression rather than a literal (a binding MAY also designate trust-anchored fields; see Section 2.9).¶

2.4. Example Mappings

This section is non-normative. The examples use an illustrative binding that exposes two input variables — request, holding the operation's parameters, and token, holding the caller's validated token claims — and the framework's defaults: CEL as the expression language and the leading-$ discriminator of Section 2.5.¶

An operation requiring a single decision is mapped with the evaluation envelope. Literals (here identity, read, and document) and expressions appear side by side:¶

{
  "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "action": { "name": "read" },
    "resource": { "type": "document", "id": "$request.document_id" }
  }
}

An expression can also embed literal text, using the expression language's own operators rather than any additional mapping syntax. In CEL this is string concatenation: the value "$'urn:doc:' + request.document_id" resolves to the literal prefix urn:doc: followed by the value of request.document_id. The leading $ marks the whole value as an expression; the embedded literal uses ordinary CEL single-quoted string syntax.¶

An operation requiring several decisions — here, a move that must be authorized as a read of the source and a write of the destination — is mapped with the evaluations envelope. The two decisions are entries in the evaluations array, and the shared subject sits at the top level of the request body, applying to both per the default semantics of [AUTHZEN]:¶

{
  "evaluations": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "evaluations": [
      { "action": { "name": "read" },
        "resource": { "type": "folder", "id": "$request.source" } },
      { "action": { "name": "write" },
        "resource": { "type": "folder", "id": "$request.destination" } }
    ]
  }
}

2.5. Literals and Expressions

Every leaf value in a mapping is either a literal or an expression:¶

• A literal is used verbatim as a constant in the constructed request.¶

• An expression is evaluated, in the binding's expression language, against the operation's input variables, and its result is used in the constructed request.¶

The default discriminator, which a binding SHOULD use, is the $ prefix:¶

• A string value whose first character is $ is an expression; the text following the $ is the expression itself.¶

• Any other value — a string not beginning with $, or any number, boolean, null, list, or map — is a literal.¶

• A string value beginning with $$ is a literal whose text begins with $: the leading $$ denotes a single literal $. Doubling applies only to a leading $; a $ anywhere else in a string has no special meaning and does not mark an expression.¶

A binding MAY define a different discriminator where the default conflicts with its environment. Any discriminator MUST distinguish a literal from an expression unambiguously for every leaf value, and MUST include an escape mechanism such that any literal value — including one whose text resembles an expression — can be represented. The distinction MUST be lossless.¶

This framework does not use the terms "static" or "dynamic" to describe values. A field reference such as "the request's path" is an expression, not a literal, because it is computed from an input variable. Only constants are literals.¶

2.6. The Expression Contract

The default expression language for COAZ is Common Expression Language [CEL], and a binding SHOULD use it, so that mappings look and behave the same across protocols. A binding MAY designate a different expression language where CEL is a poor fit for its environment; a binding that does so MUST name the language it uses. Regardless of the language, every COAZ expression MUST satisfy the following contract, which is what allows the rest of this framework to remain language-neutral:¶

1. An expression is evaluated against the input variables defined by the binding, and only those variables.¶

2. An expression MUST evaluate to a single JSON value — a scalar (string, number, boolean, or null), a list, or a map — or to the distinguished value absent. A value is used as the value of the field in which the expression appears; absent causes that field to be omitted from the constructed request entirely.¶

A binding MUST specify how an expression yields absent, so that mapping authors can distinguish "field deliberately omitted" from "field present with a null value." When the expression language is CEL, the default is CEL optional selection: the .? operator yields absent when the selected key is missing, while plain field selection on a missing key is an evaluation error.¶

The framework relies on [AUTHZEN] for which fields are required: subject, action, and resource are required for every evaluation, and context is optional. If an expression yields absent or null for a required field, the PEP cannot construct a valid request; this is a mapping error (see Section 3).¶

A value that an expression returns is always a single field value, including when it is a list or a map. Returning a list SHALL NOT cause the request to fan out into multiple evaluations. The number of decisions requested MUST be determined solely by the mapping's envelope — one for evaluation, and the number of entries in the evaluations array for evaluations (see Section 2.7) — not by the type of a value an expression returns.¶

2.7. Constructing the AuthZEN Request

A PEP MUST construct, from the resolved mapping, the AuthZEN request named by the mapping's envelope, as defined in [AUTHZEN], and send it to the corresponding API: the Access Evaluation API for an evaluation envelope, or the Access Evaluations API for an evaluations envelope.¶

A PDP used with COAZ MUST support the Access Evaluation API. Support for the Access Evaluations API is additionally required wherever mappings use the evaluations envelope. A PEP whose PDP does not support the Access Evaluations API MAY instead satisfy an evaluations mapping by issuing one Access Evaluation request per entry of the constructed request — applying the top-level defaults to each entry exactly as [AUTHZEN] defines for the Access Evaluations request — and permitting the operation only if every decision is a permit.¶

For an evaluations envelope, the top-level and per-entry fields of the constructed request carry exactly the default and override semantics defined by [AUTHZEN]. COAZ does not define any additional merge behavior.¶

A binding MUST state which envelope keys it permits (Section 4).¶

2.8. Default and Declared Mappings

A binding MAY support either or both of the following sources of mappings. This capability is OPTIONAL; a binding that supports neither requires every operation to carry its own mapping by some binding-defined means.¶

• Default mappings. A binding MAY define one or more mappings that apply to operations when no declared mapping has been supplied. A binding that defines default mappings MUST enumerate the operations in scope and MUST explicitly identify any operations that are not authorized by COAZ (pass-through operations), so that the absence of a mapping is never interpreted as an implicit deny.¶

• Declared mappings. A binding MAY allow an authority that describes an operation to supply a mapping for it. A binding that supports declared mappings MUST define who may author them, where they are carried, and how a declared mapping relates to any default mapping for the same operation (for example, whether it overrides the default).¶

As a non-normative illustration, using the same illustrative binding as Section 2.4: a binding for an HTTP API might define a default mapping that authorizes any request from its method and path,¶

{
  "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "action": { "name": "$request.method" },
    "resource": { "type": "http_route", "id": "$request.path" }
  }
}

while allowing the authority that describes a specific route (for example, its OpenAPI definition) to declare a mapping that overrides the default for that route with domain-specific semantics:¶

{
  "evaluation": {
    "subject": { "type": "identity", "id": "$token.sub" },
    "action": { "name": "approve" },
    "resource": { "type": "expense_report", "id": "$request.path_params.report_id" }
  }
}

2.9. Trust-Anchored Fields

Inputs to a COAZ mapping are considered to be untrusted, because they may be provided by the same entity whose operation is being authorized. Allowing such a mapping to set the fields that establish identity would let the authorized party assert who the subject is, inverting the trust model.¶

To prevent this, and to prevent mapping developers from accidentally trusting inputs to the mapping, a binding MAY designate certain request fields as trust-anchored: their value MUST be derived from the PEP's trusted inputs (such as an independently verifiable authorization token), not asserted by a mapping. A trust-anchored field MAY be as specific as a single identifying attribute — for example, the subject's identifier — leaving the remaining attributes of the same object available to a declared mapping. A binding that admits declared mappings from a party other than the PEP MUST specify which fields are trust-anchored.¶

A binding MUST require the PEP to enforce each trust-anchored field by one of:¶

• Verification. The mapping sets the field, and the PEP verifies that its resolved value matches the corresponding trusted input, treating a mismatch as a mapping error. This keeps the field's provenance visible in the mapping.¶

• Substitution. The PEP sets the field from its trusted inputs, ignoring any value a declared mapping supplied.¶

Sibling fields that are not trust-anchored remain available to the mapping. An attribute does not become trustworthy merely by appearing in the constructed request: a binding and its deployments MUST treat any attribute that originates from a declared mapping — including non-trust-anchored attributes of an object whose identifier is trust-anchored — as untrusted input, and policy MUST NOT rely on such an attribute as authoritative for identity or privilege.¶

2.10. Discoverability

A binding MAY define a mechanism by which a caller can obtain, in advance of invoking an operation, the mapping that will be applied to it. This enables a caller to understand how authorization will be performed and to shape its request accordingly. Discoverability is OPTIONAL and is not always achievable: some protocols provide no channel through which a mapping can be advertised. Bindings MUST NOT assume discoverability unless they define a mechanism for it.¶

5.1. Externalized Authorization

This framework moves authorization logic out of the implementation of the protected operation. Decisions are delegated to an AuthZEN PDP, so security logic lives apart from business logic, policy is managed in one place, and enforcement is consistent across operations and protocols.¶

5.2. Fail-Closed Enforcement

As required by Section 3, a PEP MUST fail closed. A mapping error, a denial, or a PDP communication failure all result in the operation being refused. Bindings and deployments MUST NOT define fallbacks that permit an operation in the absence of an explicit permit decision.¶

5.3. Mapping Integrity

A mapping determines how an operation is authorized; tampering with it can weaken or bypass authorization. A PEP SHOULD validate that a mapping is well-formed and that its expressions reference only defined input variables before relying on it. Where mappings are supplied by a party other than the PEP (for example, declared mappings), the trust placed in that party MUST be considered in the threat model.¶

5.4. Transport Security

All communication between the PEP and the PDP MUST use TLS, as specified in the transport requirements of [AUTHZEN].¶

5.5. Deployment Coverage

If no PEP in an operation's path evaluates the applicable mapping, no AuthZEN authorization occurs and access control falls back to whatever other mechanisms are in place. Deployments SHOULD be validated to confirm that COAZ mappings are consumed by an appropriate enforcement point for every in-scope operation.¶

7.1. Normative References

[AUTHZEN]

Gazitt, O., Brossard, D., and A. Tulshibagwale, "Authorization API 1.0", 2026, <https://openid.net/specs/authorization-api-1_0.html>.

[CEL]

Google, "Common Expression Language", 2024, <https://cel.dev/>.

[RFC2119]

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/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

7.2. Informative References

[COAZMCP]

"COAZ-MCP: COAZ Binding for the Model Context Protocol", 2026, <https://openid.net/specs/authzen-mcp-profile-1_0.html>.

[MCP]

"Model Context Protocol", 25 November 2025, <https://modelcontextprotocol.io/specification/2025-11-25>.

[OPENAPI]

"OpenAPI Specification", 2024, <https://spec.openapis.org/oas/latest.html>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

[RFC9110]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/rfc/rfc9110>.

A.1. OpenID AuthZEN Authorization API

This framework is built directly on the OpenID AuthZEN Authorization API [AUTHZEN]. A COAZ mapping is a template for an Access Evaluation or Access Evaluations request, selected by its envelope, and COAZ defers entirely to [AUTHZEN] for the structure of that request, the semantics of its defaults and overrides, and the form of the decision response. COAZ adds only the projection from an arbitrary information model into that request.¶

A.2. COAZ Bindings

This specification is the common foundation for a family of bindings, each of which binds the framework to a specific protocol or interface by fulfilling the conformance requirements of Section 4. COAZ-MCP [COAZMCP] is the reference binding. Bindings for HTTP APIs [RFC9110] and for OpenAPI-described routes [OPENAPI] are anticipated.¶

B.1. The Request Envelope

A mapping names the AuthZEN API it targets through a single outer key rather than assuming one API for all mappings. The Access Evaluation API is the baseline capability of every AuthZEN PDP, so the common case — one operation, one decision — asks no more of the PDP than [AUTHZEN] itself requires. The Access Evaluations API is engaged only by mappings that genuinely need several decisions for a single operation. The envelope also leaves room for growth: future versions of this framework, or individual bindings, can bind additional keys to other AuthZEN APIs without changing the shape of existing mappings, and a PEP treats an envelope key it does not support as a mapping error, so unknown request types fail closed.¶

B.2. One Output, Many Inputs

The central design choice of COAZ is to fix the output and vary the input. The AuthZEN request is the same regardless of the source protocol, so PDPs, policy authors, and tooling work identically across protocols. Only the projection from each protocol's information model differs, and that projection is exactly what a binding specifies.¶

B.3. Literals and Expressions, Not Static and Dynamic

COAZ describes values as either literals or expressions. It avoids the "static/dynamic" framing because a field reference — which appears to be a simple mapping — is in fact computed from an input variable and is therefore an expression. Reserving "literal" for true constants keeps the model precise and avoids the contradiction of a "static" mapping that is full of computed values.¶

B.4. A Default Language, an Overridable Contract

The framework names CEL as its default expression language so that mappings look the same across bindings and a mapping author carries one skill between them. Alongside the default it fixes an expression contract, so that a binding whose environment genuinely cannot host a CEL evaluator can substitute another language without destabilizing the rest of the model: the contract in Section 2.6 defines exactly what any replacement must guarantee. The same reasoning applies to the default $ discriminator and $$ escape of Section 2.5: one default syntax across bindings, overridable only where a protocol's environment forces it.¶