OAuth 2.0 Authority Metadata

1.1. Publication Roles

The publication roles are distinct:¶

• A protected resource publishes the authority semantics it applies when enforcing access.¶

• An authorization server publishes its local understanding of the authority vocabulary it uses when making issuance decisions.¶

Protected resource metadata is resource-bound through the resource attribute defined by [RFC9728].¶

Authorization server metadata describes an issuer-local authority vocabulary. It does not establish how a resource enforces an issued authority.¶

Authorization server authority metadata enables clients, independently operated interfaces, policy services, and administrative tools to discover the issuer's declared interpretation of its scope values and authorization details types. It does not publish issuance policy or predict authorization decisions. An authorization server can maintain the same information privately without publishing this metadata.¶

1.2. Scope

This specification defines:¶

• an authority_metadata parameter for protected resource metadata;¶

• an authority_metadata parameter for authorization server metadata;¶

• a common authority description model for scopes and RAR types;¶

• reusable protected resource access requirement profiles;¶

• attenuation relationships;¶

• advisory authority ordering through family and rank.¶

This specification does not define:¶

• a universal authorization policy language;¶

• a universal vocabulary of application actions;¶

• a replacement for RAR type definitions or schemas;¶

• an authorization server policy decision algorithm;¶

• a new OAuth error or remediation protocol;¶

• an action approval protocol;¶

• a transaction or cross-resource outcome evidence protocol;¶

• a general-purpose translation between scopes and RAR objects.¶

1.3. Relationship to AuthZEN

The AuthZEN OAuth token issuance profile [AUTHZEN-ISSUANCE] and token exchange binding [AUTHZEN-EXCHANGE] drafts provide mechanisms for policy evaluation in authorization server issuance and exchange flows.¶

This document provides semantic information which can be used in those evaluations. For example, a deployment can resolve a requested scope into an authority description before consulting a policy decision point.¶

This specification does not change those profiles or define an additional AuthZEN request attribute. The transport of resolved metadata to a policy decision point is determined by the applicable profile or deployment.¶

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

The following terms are used:¶

Authority:

The operations and access a credential or authorization grant permits, including applicable resource and parameter restrictions.¶

Authority description:

Metadata describing the authority represented by an OAuth scope or authorization details type.¶

Authority publisher:

The authorization server or protected resource publishing an authority metadata document.¶

Authority consumer:

An authorization server, client, policy decision point, gateway, or other component that consumes authority metadata.¶

Access requirement profile:

A named set of properties a protected resource requires when accepting access carrying a described authority.¶

Attenuation:

Replacement or restriction of authority with authority that grants no greater access.¶

Authority family:

A publisher-defined grouping within which authority ranks have a common interpretation.¶

2.1. Protected Resource Metadata

In protected resource metadata, authority_metadata contains:¶

authorities:

REQUIRED. An array of authority entries.¶

access_requirement_profiles:

OPTIONAL. An object whose attribute names identify reusable access requirement profiles and whose attribute values describe those profiles.¶

The protected resource context is supplied by the enclosing document's resource attribute. Authority identifiers, profile names, families, and relationship targets are local to that metadata document.¶

2.2. Authorization Server Metadata

In authorization server metadata, authority_metadata contains:¶

authorities:

REQUIRED. An array of authorization server authority entries.¶

Authorization server authority entries describe the publisher's local authority vocabulary. They do not contain resource selectors, access requirement profile references, or attenuation relationships.¶

2.3. Common Requirements

Within either publication context:¶

• authorities MUST be a JSON array.¶

• Each authority entry MUST be a JSON object.¶

• A publisher MUST NOT publish more than one entry with the same combination of kind and value in the same metadata document.¶

• An empty authorities array describes no authorities.¶

• Omission of an authority entry MUST NOT be interpreted as a statement that the authority is unsupported or unrestricted.¶

This specification permits partial publication. An authority consumer cannot assume that the metadata enumerates every authority accepted or issued by the publisher.¶

2.4. Examples

The examples use illustrative application vocabularies. They are not standardized action, effect, or risk registries.¶

{
  "resource": "https://documents.example.com",
  "authorization_servers": [
    "https://as.example.com"
  ],
  "scopes_supported": [
    "documents.read",
    "documents.manage"
  ],
  "authorization_details_types_supported": ["document-access"],
  "authority_metadata": {
    "access_requirement_profiles": {
      "standard_access": {
        "token": {
          "max_lifetime": 3600
        }
      },
      "sensitive_access": {
        "token": {
          "max_age": 300,
          "max_lifetime": 600,
          "sender_constrained": true
        },
        "authentication": {
          "acr_values": [
            "phishing-resistant"
          ],
          "max_age": 300
        }
      }
    },
    "authorities": [
      {
        "id": "documents.read",
        "kind": "scope",
        "value": "documents.read",
        "description": "Read documents accessible to the subject.",
        "family": "document_access",
        "rank": 10,
        "authority": [
          {
            "resource_type": "document",
            "actions": [
              "document:read"
            ],
            "effects": [
              "data-disclosure"
            ],
            "risk": "low"
          }
        ],
        "access_requirement_profile": "standard_access"
      },
      {
        "id": "documents.manage",
        "kind": "scope",
        "value": "documents.manage",
        "description": "Read and update documents accessible to the subject.",
        "family": "document_access",
        "rank": 20,
        "authority": [
          {
            "resource_type": "document",
            "actions": [
              "document:read",
              "document:update"
            ],
            "effects": [
              "data-disclosure",
              "state-change"
            ],
            "risk": "medium"
          }
        ],
        "access_requirement_profile": "sensitive_access",
        "relationships": [
          {
            "relation": "can_be_attenuated_to",
            "target": "documents.read"
          }
        ]
      },
      {
        "id": "document_access.rar",
        "kind": "authorization_details_type",
        "value": "document-access",
        "description": "Access to specified documents under type-specific restrictions.",
        "family": "document_access",
        "authority": [
          {
            "resource_type": "document",
            "actions": [
              "document:read",
              "document:update"
            ],
            "effects": [
              "data-disclosure",
              "state-change"
            ]
          }
        ],
        "access_requirement_profile": "sensitive_access"
      }
    ]
  }
}

{
  "issuer": "https://as.example.com",
  "scopes_supported": [
    "profile.read",
    "profile.manage"
  ],
  "authorization_details_types_supported": ["document-access"],
  "authority_metadata": {
    "authorities": [
      {
        "kind": "scope",
        "value": "profile.read",
        "description": "Read profile information.",
        "family": "profile_access",
        "rank": 10,
        "authority": [
          {
            "resource_type": "profile",
            "actions": [
              "profile:read"
            ],
            "effects": [
              "data-disclosure"
            ],
            "risk": "low"
          }
        ]
      },
      {
        "kind": "scope",
        "value": "profile.manage",
        "description": "Read and update profile information.",
        "family": "profile_access",
        "rank": 20,
        "authority": [
          {
            "resource_type": "profile",
            "actions": [
              "profile:read",
              "profile:update"
            ],
            "effects": [
              "data-disclosure",
              "state-change"
            ],
            "risk": "medium"
          }
        ]
      },
      {
        "kind": "authorization_details_type",
        "value": "document-access",
        "description": "Access to specified documents under type-specific restrictions.",
        "family": "document_access",
        "authority": [
          {
            "resource_type": "document",
            "actions": [
              "document:read",
              "document:update"
            ],
            "effects": [
              "data-disclosure",
              "state-change"
            ]
          }
        ]
      }
    ]
  }
}

resource=https://documents.example.com
scope=documents.manage

3.1. Common attributes

Authority entries use the following common attributes.¶

3.2. Protected Resource attributes

Protected resource authority entries additionally use:¶

id:

REQUIRED. A non-empty string identifying the entry within this metadata document. Every id MUST be unique within the document.¶

access_requirement_profile:

OPTIONAL. A string naming one entry in access_requirement_profiles.¶

relationships:

OPTIONAL. An array of inline relationship objects as defined in Section 6.¶

A referenced access requirement profile MUST exist in the same authority_metadata object.¶

This specification defines one profile reference per authority entry. Profile inheritance and composition are not defined.¶

3.3. Authorization Server attributes

Authorization server authority entries are identified by their combination of kind and value.¶

An authorization server authority entry MUST NOT contain id, access_requirement_profile, or relationships.¶

Authorization server authority metadata MUST NOT contain access_requirement_profiles.¶

These restrictions distinguish the AS's local authority descriptions from a protected resource's access enforcement expectations.¶

4.1. Completeness and Interpretation

An authority description identifies the authority semantics known to its publisher. It does not independently establish a complete policy model.¶

In particular:¶

• resource_type does not identify every resource instance accessible under the authority.¶

• An action name does not, by itself, identify permitted parameter values.¶

• An effect describes consequences; it does not confer additional authority.¶

• A risk label does not establish an ordering of access rights.¶

A consumer performing semantic authorization evaluation needs the applicable vocabulary definitions, RAR type semantics, request values, and local policy.¶

4.2. RAR Interpretation

For a RAR entry, the authority description applies to the type identified by value.¶

The authority represented by a concrete RAR object depends on that object's parameters and the type-specific rules defined under [RFC9396].¶

The metadata does not replace those rules or duplicate the type's field schema.¶

For example, two objects of the same payment type may grant different authority because they identify different accounts, beneficiaries, amounts, or actions.¶

A consumer MUST NOT determine concrete RAR authority solely from its type-level authority metadata.¶

5.1. Profile Structure

access_requirement_profiles is a JSON object keyed by profile name.¶

Each profile can contain:¶

description:

OPTIONAL. Human-readable explanatory text.¶

token:

OPTIONAL. Token presentation requirements.¶

authentication:

OPTIONAL. End-user authentication requirements.¶

Profile names are local, case-sensitive identifiers. They do not imply standardized security levels.¶

For example:¶

{
  "access_requirement_profiles": {
    "sensitive_access": {
      "description": "Requirements for sensitive account access.",
      "token": {
        "max_age": 300,
        "max_lifetime": 600,
        "sender_constrained": true
      },
      "authentication": {
        "acr_values": [
          "phishing-resistant"
        ],
        "max_age": 300
      }
    }
  }
}

5.2. Token Requirements

The token object can contain:¶

max_age:

OPTIONAL. A positive integer expressing, in seconds, the maximum acceptable elapsed time since the access token was issued.¶

max_lifetime:

OPTIONAL. A positive integer expressing, in seconds, the maximum acceptable total lifetime of the access token, from issuance to expiration.¶

sender_constrained:

OPTIONAL. A boolean. If true, presentation must satisfy an applicable sender-constraining mechanism.¶

A boolean value of false means that this profile does not require the property. It does not prohibit the property or override stricter policy.¶

5.3. Authentication Requirements

The authentication object can contain:¶

acr_values:

OPTIONAL. A non-empty array of acceptable authentication context class reference values.¶

max_age:

OPTIONAL. A positive integer expressing, in seconds, the maximum acceptable elapsed time since the relevant end-user authentication event. The resource determines that event's time from validated authentication information associated with the access token, such as an auth_time claim in a validated JWT access token or a trusted token introspection response, as described in [RFC9470].¶

If both attributes are present, both requirements apply.¶

acr_values lists alternatives, not cumulative authentication requirements. The resource accepts an authentication context recognized as satisfying at least one listed value.¶

Authentication freshness is distinct from token freshness. Issuing a new token does not necessarily establish a new authentication event.¶

5.4. Default Resource Policy

If an authority entry has no access_requirement_profile, no additional profile is declared for that entry.¶

Resource-wide policy and other applicable requirements still apply.¶

A profile cannot weaken a requirement established by the resource's other enforcement policy.¶

5.5. Multiple Authorities in a Token

An access token may carry more than one authority.¶

This specification does not prescribe how an authorization server combines the associated profiles. It may satisfy a common set of requirements, or decline a request according to policy.¶

At enforcement time, the resource applies the requirements relevant to the authority used for the operation.¶

If an operation requires multiple authorities, all applicable requirements must be satisfied. A weaker profile cannot cancel a stronger requirement.¶

6.1. can_be_attenuated_to

The relationship:¶

{
  "relation": "can_be_attenuated_to",
  "target": "documents.read"
}

asserts that the target represents no greater authority than the source under the protected resource's authority semantics.¶

For relationships between scope entries, this relationship asserts that the target represents no greater authority than the source under the protected resource's applicable semantics and restrictions.¶

Where either entry describes a RAR type, the relationship identifies a candidate attenuation target. It does not establish containment between concrete authorization details objects or between a concrete object and a scope grant. A consumer MUST establish concrete containment using applicable type semantics, parameter restrictions, and policy before substitution.¶

For example, if documents.manage authorizes both reading and modifying documents, it can declare attenuation to a scope that authorizes reading the same documents.¶

Conversely, a payment execution authority does not automatically contain payment preparation or payment status access. Those are different operations. A relationship is valid only if the resource's actual semantics establish the asserted containment.¶

A publisher MUST NOT declare this relationship based solely on rank, risk, or perceived similarity. The relationship does not assert that the target satisfies the client's task, purpose, or Mission.¶

For parameterized authorities such as Rich Authorization Requests (RAR) types, the relationship identifies a potential attenuation target. It does not assert containment between arbitrary instances of the source and target types. Concrete containment requires the applicable type semantics and parameter restrictions.¶

6.2. RAR and Cross-Kind Relationships

Relationships can identify targets of a different kind.¶

However, identifying a target does not define a transformation of authorization request data.¶

For RAR types, authority comparison may depend on concrete object parameters. An asserted relationship does not authorize dropping, widening, or changing parameter restrictions.¶

A consumer needs applicable type semantics or configured policy to establish a safe concrete transformation. This specification does not define that transformation.¶

If containment cannot be established for the concrete request, the relationship alone is insufficient grounds for replacement.¶

6.3. Relationship Interpretation

Containment is transitive when the same resource context and compatible semantic restrictions apply. A consumer is not required to compute a transitive closure, select a target, or perform substitution. Unrecognized relationship names MUST NOT be interpreted as can_be_attenuated_to. Consumers traversing relationships SHOULD apply limits to traversal depth and visited entries to avoid unbounded processing.¶

8.1. Publication Is Not an Issuance Decision

An AS-published authority description does not imply that:¶

• every client can request that authority;¶

• every subject can grant it;¶

• the AS will issue it;¶

• any particular resource accepts it.¶

Similarly, a resource's published authority description does not authorize issuance by an AS.¶

Existing grant restrictions, client policy, subject authority, and applicable protocol rules remain in effect.¶

8.2. Metadata Sources and Conflicts

An authorization server may use local policy or configuration when protected resource metadata is unavailable.¶

AS authority metadata describes the AS's local interpretation of its authority vocabulary. Protected resource authority metadata describes the resource's enforcement semantics.¶

An authorization server MUST NOT use protected resource metadata, by itself, to relax its issuance restrictions or minimum security requirements. An omitted requirement, lower risk classification, lower rank, or narrower authority description does not override AS policy.¶

Where the authority descriptions differ, the AS determines their applicability through trusted configuration and local policy. The difference MUST NOT be resolved merely by selecting the interpretation that permits issuance.¶

This specification does not require an AS to issue a token when the descriptions or requirements cannot be reconciled.¶

8.3. Attenuation Options

Attenuation handling is determined by AS policy.¶

Possible behaviors include:¶

• issuing the originally requested authority;¶

• issuing lower authority where permitted by the applicable OAuth flow;¶

• declining the original request;¶

• suggesting a lower-authority request using an applicable remediation mechanism;¶

• requesting additional consent;¶

• requiring the client to submit a revised request.¶

This specification does not require an AS to search relationships, select the lowest rank, or issue an attenuated token.¶

Where an AS changes granted authority, it remains responsible for the applicable response requirements of [RFC6749], [RFC9396], and the relevant grant or exchange protocol, including [RFC8693] where applicable.¶

No new error code or remediation response is defined here.¶

9.1. Untrusted Resource Locations

An AS that fetches metadata in response to a client-supplied resource indicator can be exposed to server-side request forgery.¶

Implementations SHOULD validate destinations, constrain redirects, control access to internal addresses, and apply request size and timeout limits.¶

9.2. Semantic Misrepresentation

A publisher can incorrectly describe a scope, type, or containment relationship.¶

An authenticated document proves the document's source, not the correctness of its semantic claims.¶

Consumers should rely only on trusted publishers and understood vocabularies when using metadata for authorization decisions.¶

9.3. Stale Metadata

Authority semantics and access requirements may change.¶

Consumers SHOULD use bounded caching and an appropriate refresh strategy. An old description must not be assumed to remain valid indefinitely.¶

This specification does not define semantic version negotiation or bind a token to a metadata version.¶

9.4. Malicious Resource Metadata and Policy Downgrade

A malicious client can select an attacker-controlled resource whose metadata understates the authority represented by a scope or authorization details type, or declares weaker access requirements.¶

If an authorization server applies that metadata outside its resource context, the client might obtain a token usable at another resource under weaker policy.¶

An authorization server MUST bind protected resource authority metadata used in an issuance decision to the protected resource for which that metadata was validated. Protected resource authority metadata MUST be associated with the expected resource identity, not merely with the location from which the document was retrieved.¶

Scope values, authority identifiers, families, and ranks from one resource MUST NOT be used to establish authority semantics for another resource.¶

An authorization server MUST NOT treat resource metadata as authorization to weaken existing grant restrictions, client policy, subject authority, or AS-local minimum security requirements.¶

Omitted or weaker access requirements do not override those requirements.¶

When protected resource authority metadata informs token issuance, the authorization server MUST audience-restrict the resulting token to the resource or resources independently evaluated for that issuance decision, using the mechanisms described in [RFC8707].¶

A protected resource MUST reject an access token that is not intended for that resource.¶

An attacker-controlled resource MUST NOT be able to select an audience mapping that makes its tokens acceptable to another resource.¶

Publication of metadata, including an authorization_servers member naming an AS, does not establish that the publisher is trusted by that AS.¶

Token refresh or exchange that changes the target resource requires evaluation in the new resource context. A previous issuance decision based on another resource's metadata does not establish authority for the new target.¶

9.5. Requests Naming Multiple Resources

An OAuth request can identify more than one protected resource. Each resource's authority metadata and access requirements apply only within that resource's context.¶

An authorization server may issue a token intended for multiple resources, require a revised request, or reject an unsupported combination, subject to the applicable OAuth protocol and local policy.¶

If the authorization server issues one token intended to satisfy the requirements of multiple resources, that token MUST satisfy all applicable requirements. Requirements that cannot be jointly satisfied MUST NOT be resolved by selecting the weaker requirement.¶

This specification does not define a profile-merging algorithm.¶

9.6. Scope Combinations

The authority of several scopes may not equal a simple union of their individual descriptions.¶

A resource can apply combination-dependent semantics, and a token can also carry claims or authorization details that affect enforcement.¶

This specification does not define scope combination semantics. Consumers need applicable resource policy when evaluating combinations.¶

9.7. RAR Parameter Restrictions

Type-level metadata must not cause a consumer to ignore restrictions in a concrete authorization details object.¶

Unsafe transformations can widen document access, payment destinations, amounts, or other parameter-defined authority.¶

9.8. Requirements Are Not Enforcement

Publishing sender-constraining or freshness requirements does not implement them.¶

Resources remain responsible for enforcement. Issuing a short-lived token does not prove recent authentication.¶

9.9. Relationship Processing

Relationship graphs can contain cycles or excessive numbers of entries.¶

Consumers SHOULD bound graph processing. Rank must not be used as a shortcut for proving containment.¶

9.10. Consent Rendering

Human-readable descriptions can improve disclosure but do not prove comprehension.¶

Descriptions SHOULD be displayed as untrusted text. Consumers MUST NOT execute markup, scripts, or instructions embedded in descriptions.¶

11.1. OAuth Authorization Server Metadata Registration

This specification requests registration in the "OAuth Authorization Server Metadata" registry established by [RFC8414]:¶

• Metadata Name: authority_metadata¶

• Metadata Description: JSON object describing the authorization server's local authority vocabulary.¶

• Change Controller: IETF¶

• Specification Document: Section 2 of this document¶

11.2. OAuth Protected Resource Metadata Registration

This specification requests registration in the "OAuth Protected Resource Metadata" registry established by [RFC9728]:¶

• Metadata Name: authority_metadata¶

• Metadata Description: JSON object describing resource-bound authority, reusable access requirement profiles, and attenuation relationships.¶

• Change Controller: IETF¶

• Specification Document: Section 2 of this document¶

13.1. Normative References

[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/info/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/info/rfc8174>.

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/info/rfc6749>.

[RFC8414]

Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, <https://www.rfc-editor.org/info/rfc8414>.

[RFC8707]

Campbell, B., Bradley, J., and H. Tschofenig, "Resource Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, February 2020, <https://www.rfc-editor.org/info/rfc8707>.

[RFC9396]

Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, May 2023, <https://www.rfc-editor.org/info/rfc9396>.

[RFC9728]

Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", RFC 9728, DOI 10.17487/RFC9728, April 2025, <https://www.rfc-editor.org/info/rfc9728>.

13.2. Informative References

[RFC7662]

Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, <https://www.rfc-editor.org/info/rfc7662>.

[RFC8693]

Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, DOI 10.17487/RFC8693, January 2020, <https://www.rfc-editor.org/info/rfc8693>.

[RFC8705]

Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, February 2020, <https://www.rfc-editor.org/info/rfc8705>.

[RFC9068]

Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October 2021, <https://www.rfc-editor.org/info/rfc9068>.

[RFC9449]

Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, September 2023, <https://www.rfc-editor.org/info/rfc9449>.

[RFC9470]

Bertocci, V. and B. Campbell, "OAuth 2.0 Step Up Authentication Challenge Protocol", RFC 9470, DOI 10.17487/RFC9470, September 2023, <https://www.rfc-editor.org/info/rfc9470>.

[AUTHZEN-ISSUANCE]

OpenID Foundation, "AuthZEN Profile for OAuth 2.0 Token Issuance", 2026, <https://openid.github.io/authzen/authzen-oauth-token-issuance-1_0.html>.

[AUTHZEN-EXCHANGE]

OpenID Foundation, "AuthZEN Binding for OAuth 2.0 Token Exchange", 2026, <https://openid.github.io/authzen/authzen-oauth-token-exchange-1_0.html>.