OAuth Authorization Grant Catalog

OAuth Authorization Grant Catalog Independent

public@karlmcguinness.com

Security Web Authorization Protocol OAuth authorization grant JWT authorization grant cross-domain metadata This specification defines the OAuth Authorization Grant Catalog: an authenticated, relationship-specific description of the authorization grants that a Resource Authorization Server is prepared to accept from a Grant Issuer. A Grant Issuer is an authorization server, such as an identity provider, that issues grants for redemption at the Resource Authorization Server. For each eligible target tenant, a catalog describes the protected resources, scope values, authorization details types, claims, subject identifier formats, and grant binding methods that the Resource Authorization Server accepts. The Grant Issuer uses the catalog as input to the policy under which it issues grants; the catalog is not an authorization decision. The data model is independent of grant encoding and retrieval protocol. This specification applies it only to the Identity Assertion JWT Authorization Grant (ID-JAG), and defines an OAuth retrieval protocol that delivers the complete catalog in one response. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction Several OAuth specifications define authorization grants that one authorization server issues for a client to present to another authorization server, typically in another trust domain. The Identity Assertion JWT Authorization Grant (ID-JAG) , which an identity provider issues, is one example. In this specification, the issuing authorization server is called the Grant Issuer, and the receiving authorization server is called the Resource Authorization Server. The Grant Issuer has to know which tenants, protected resources, scope values, authorization details types , claims, subject identifiers, and grant bindings the Resource Authorization Server accepts from it. Public metadata does not convey this information. OAuth 2.0 Authorization Server Metadata and OAuth 2.0 Protected Resource Metadata :

are retrieved without authentication;
are generally not specific to a tenant; and
describe what a server implements, not what it accepts from a particular Grant Issuer.

Publishing this information would advertise issuer-specific trust relationships, which warns can disclose deployment-sensitive information. That section also prohibits using the authorization_grant_profiles_supported metadata member to disclose issuer allow lists. Deployments therefore communicate these values through documentation or implementation-specific configuration, and administrators of a Grant Issuer copy them into local configuration by hand. This specification defines a common, authenticated representation of that configuration, called the catalog. A Resource Authorization Server publishes the catalog, and a Grant Issuer uses it to configure issuance and to detect changes. The Resource Authorization Server publishes entries that describe the grants it accepts from one Grant Issuer. An administrator of the Grant Issuer approves a subset of each entry that the Grant Issuer uses, and the Grant Issuer issues grants within that subset. A revision on each entry lets the Grant Issuer detect changes that need review. The catalog supports configuration and grant construction. It does not establish trust between the servers or register clients. It is input to policy authoring, not an authorization decision: the Resource Authorization Server applies its current policy to every grant it processes, whether or not the grant was issued using a catalog. A grant constructed from an entry can still be rejected, for example because of the client, the subject, the contents of authorization details objects, or the Resource Authorization Server's current policy. The catalog states how to construct a grant that avoids preventable failures, not whether a particular request will succeed.

Motivating Example An enterprise uses its identity provider for single sign-on to a software-as-a-service application. It wants an AI assistant, a client registered at the application, to use ID-JAG to read messages through the application's Messages API on behalf of employees. Today, an administrator of the identity provider reads the application's documentation and enters the following by hand:

the application's issuer identifier;
the enterprise's tenant identifier at the application;
the resource identifier of the Messages API;
the scope value messages.read; and
the requirement that each ID-JAG be bound to a DPoP key.

A mistake surfaces only when the application rejects an ID-JAG, after the ID-JAG has disclosed its claims to the client. With a catalog, the identity provider retrieves a Relationship View under its relationship with the application. The Relationship View lists the enterprise's tenant and one entry stating these values (). The administrator approves the entry instead of typing its values. When the application later changes the entry, the identity provider detects the new revision and stops issuing under the old approval until an administrator reviews the change. When the application removes the tenant, the identity provider stops issuing for it. Copied values would instead go on being used after they no longer match. shows a richer case, with scope values that cannot be combined in one grant. The catalog replaces copied grant configuration. The rest of the integration is unchanged:

establishing the relationship (the Onboarding Arrangement);
registering the client at the application and mapping its client identifier;
mapping subjects;
learning any restrictions the application applies to that particular client;
deciding which employees and clients may use the integration; and
making the application's runtime authorization decisions.

Approving an entry constrains what grants contain. What a scope value permits, and whether a request is allowed, remain decisions of the application (, ).

Relationship to Other Metadata Each source of information used to issue a grant answers a different question: Sources of Information Used to Issue a Grant

Source	Question It Answers
Authorization Server Metadata	Where are the Resource Authorization Server's endpoints, and which protocol features does it support?
Protected Resource Metadata	Which authorization servers and capabilities does a protected resource advertise?
Authorization details types metadata	What structure does an authorization details object of a given type have?
Authority metadata	What does a scope value or authorization details type authorize?
Relationship View	Which grants does the Resource Authorization Server offer to this Issuer Relationship?
Grant Issuer approval	Which of those grants may the Grant Issuer issue?
Runtime authorization	Is this request allowed now?

, , and define how a Grant Issuer combines these sources.

Applicability This specification applies to authorization grants whose content a Grant Issuer determines and that a Resource Authorization Server validates at redemption. JWT authorization grants and their profiles have this form. This specification does not apply to grants that an authorization server issues for redemption at itself, such as authorization codes, device codes, and refresh tokens, because no other party determines what such a grant contains. This specification defines a catalog data model and keeps it separate from grant encoding and from retrieval:

The data model () has an Authorization Envelope () and processing rules () stated in terms of the inputs a grant conveys.
Each Grant Profile Definition specifies how grants of its Grant Profile convey those inputs (). This specification provides one only for ID-JAG ().
A retrieval protocol authenticates the relationship and delivers the catalog (). This specification defines an OAuth retrieval protocol.

The following are outside the scope of this specification:

Enumeration or registration of application clients, and establishment of client identifier mappings ().
Constraints on the values within an authorization details object ().
Paging, change notification, delta retrieval, and push delivery of catalogs.
Automatic reconciliation of Grant Issuer policy with a changed entry ().
A mechanism by which a client discovers whether a grant from a particular Grant Issuer would be accepted (), which is an open issue ().
Establishment of an Onboarding Arrangement ().

Conventions and Definitions 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. This specification uses the following terms:

"access token", "authorization grant", "authorization server", "client", "resource server", and "scope" defined by OAuth 2.0 ;
"JSON Web Token (JWT)" and "claim" defined by ;
"authorization details" and "authorization details type" defined by ;
"resource indicator" as used by ;
"protected resource" as used by ; and
"trust domain" as defined in .

In this specification, "grant" means an authorization grant that a Grant Issuer issues for a client to present to a Resource Authorization Server, and "client" means that client, the application client. Where the Grant Issuer itself acts as a client of the Resource Authorization Server (), the text says so. The issuer tenant of a grant is the tenant of the Grant Issuer that issues it, and its target tenant is the Resource Authorization Server tenant for which it is issued. This specification defines the following terms:

tenant:: An administrative boundary within an issuer, such as a customer organization, that scopes subjects, clients, and policy (). An issuer is multi-tenant when one issuer identifier hosts several tenants ().
tenant identifier:: A string that, together with an issuer identifier, identifies exactly one tenant of that issuer. A tenant identifier is not reassigned by the issuer to a different tenant and is compared using simple string comparison ().
Grant Issuer:: An authorization server that consumes a Relationship View and issues grants.
Resource Authorization Server:: An authorization server that accepts grants issued by a Grant Issuer and publishes Relationship Views. This specification uses the term as does, for any Grant Profile.
Grant Profile:: A profile of an authorization grant, identified by a URI as used in the authorization_grant_profiles_supported metadata member (), such as urn:ietf:params:oauth:grant-profile:id-jag.
Grant Profile Definition:: A specification that defines how catalog entries apply to a Grant Profile ().
Issuer Relationship:: The relationship under which a Resource Authorization Server discloses catalog content to a Grant Issuer, identified by the Grant Issuer's issuer identifier and, when that issuer is multi-tenant, an issuer tenant identifier ().
Onboarding Arrangement:: The agreement, established outside this protocol, under which a Resource Authorization Server discloses catalog content to an Issuer Relationship and determines the Resource Authorization Server tenants eligible for it ().
Relationship View:: The complete set of Tenant Objects, and the Grant Catalogs they reference, that a Resource Authorization Server makes available to one Issuer Relationship at a point in time ().
Tenant Object:: An object that binds one Resource Authorization Server tenant eligible for an Issuer Relationship to exactly one Grant Catalog ().
Grant Catalog:: A complete set of entries identified by a stable identifier ().
Entry:: A member of a Grant Catalog that describes the grants of one Grant Profile that the Resource Authorization Server accepts for one protected resource ().
Authorization Envelope:: The set of grants that an entry, or an approved subset of an entry, permits ().

Protocol Overview shows the protocol flow.

Protocol Overview | | | | | Resource | | |---(B) Authenticate relationship ->| Authorization | | | | Server | | |<--(C) Relationship View ----------| | | Grant | +---------------+ | Issuer | ^ | | (D) Validate, compose, and install | | | (E) Administrator approves a subset | | | | | | +--------+ | | |---(F) Grant ---->| Client |---(G) Grant -+ +---------+ +--------+ ]]>

(A): The Grant Issuer retrieves the Resource Authorization Server's public metadata, which includes the location of the catalog for a retrieval protocol.
(B): The Grant Issuer authenticates an Issuer Relationship to the Resource Authorization Server using a retrieval protocol. The Resource Authorization Server verifies that an Onboarding Arrangement authorizes that relationship ().
(C): The Resource Authorization Server returns the Relationship View for that Issuer Relationship.
(D): The Grant Issuer validates the Relationship View, composes each entry with public metadata, and installs the result ().
(E): An administrator of the Grant Issuer approves a subset of one or more entries for use by its clients and subjects ().
(F): When a client requests a grant, the Grant Issuer authenticates the client and the subject, applies its policy, and issues a grant within the approved subset of one entry ().
(G): The client presents the grant to the Resource Authorization Server, which validates it and applies its current policy as specified by the Grant Profile.

Steps (A) through (E) occur when the Grant Issuer is configured and when it refreshes the catalog, not for each grant. With the OAuth retrieval protocol (), the Grant Issuer:

signs a catalog access assertion;
exchanges the assertion at the Resource Authorization Server's token endpoint for a catalog access token; and
uses that token to retrieve one complete Relationship View.

This exchange is separate from the grants that clients later request in step (F). The design rests on the following principles, each stated normatively in the sections cited:

The Resource Authorization Server determines a Relationship View solely from the authenticated Issuer Relationship ().
The Grant Issuer installs all of a Relationship View or none of it ().
A grant is issued using one Tenant Object and one entry. The grant conveys an input that the entry governs only as the entry permits. Every claim in the grant is either reserved by the Grant Profile or listed in the entry (, , ).
Approval and runtime policy only narrow an entry. A new or changed entry, public metadata, and authority metadata never broaden an approval. An entry cannot enable a value that public metadata excludes (, , , ).
When the revision of an entry or the grant_catalog of a Tenant Object changes, issuance under approvals made for the previous value stops. Issuance resumes only under an approval made for the new value ().
A Grant Issuer ignores members it does not understand. A specification that defines a restrictive member also defines a mechanism that prevents Grant Issuers that do not implement that member from using the entry ().

Catalog Data Model The objects in this section describe what a Resource Authorization Server accepts in grants from one Issuer Relationship. The Tenant Objects of a Relationship View identify the Resource Authorization Server tenants eligible for that relationship, and the Grant Catalogs of the Relationship View contain the entries. Several Tenant Objects can reference one Grant Catalog, so tenants that are offered the same grants share entries. Each approval remains specific to one Tenant Object (). shows a complete Relationship View with one Tenant Object and one Grant Catalog. The Tenant Object references the Grant Catalog read-only, whose single entry permits ID-JAGs for the Messages API. Grants issued using this entry contain the scope value messages.read and are bound to a DPoP key. An administrator of the Grant Issuer still approves a subset before the entry is used ().

Example Relationship View shows the object structure, without the display and description members. provides a fuller example of the inputs that an entry can govern.

Structure of a Relationship View

Common Conventions Every object defined in this section is a JSON object . A document that carries these objects MUST conform to I-JSON . A Grant Issuer MUST ignore members it does not understand (). Each object is defined by a table of its members. In these tables, "string", "object", and "array" denote JSON types, and the JSON value null has none of these types. The following members are used by several objects:

id:: A stable identifier for the object. The value is a non-empty JSON string of at most 255 octets when encoded in UTF-8. Identifiers are opaque and case-sensitive, and are compared using simple string comparison (). The length limit bounds the Grant Catalog and entry identifiers that a Grant Issuer retains with each approval (). Grant Catalog identifiers are unique within a Relationship View, and entry identifiers are unique within a Grant Catalog.
display:: OPTIONAL. A JSON string containing a short, human-readable name for the object, intended for presentation to an administrator.
description:: OPTIONAL. A JSON string containing a human-readable explanation of the object, such as what a scope value permits, intended for an administrator deciding what to approve.

The values of display and description have no effect on processing. Language negotiation for these values is outside the scope of this specification. Where this specification describes a member as an array of unique values, the array MUST NOT contain the same value twice. Within an entry, each of the following values is unique and identifies an item:

a scope value within a values array;
a type value within a types array; and
a claim value within a claims array.

Members that carry protocol values, such as authorization_server, tenant_id, profile, resource, scope, type, claim, and the names in formats and methods, are compared using simple string comparison ().

Relationship View A Relationship View is a JSON object with the following members: Relationship View Members

Member	Status	Description
`authorization_server`	REQUIRED	String; the issuer identifier of the Resource Authorization Server
`grant_issuer`	REQUIRED	Object; identifies the Issuer Relationship that the Relationship View serves
`tenants`	REQUIRED	Array containing every Tenant Object () eligible for the Issuer Relationship
`grant_catalogs`	REQUIRED	Array containing each Grant Catalog () that a Tenant Object references, each exactly once

The issuer member of grant_issuer is REQUIRED and contains the issuer identifier of the Grant Issuer. The tenant member of grant_issuer contains the issuer tenant identifier, and is present if and only if the Issuer Relationship has one (). The Resource Authorization Server derives grant_issuer from the Issuer Relationship that it used to select the Relationship View. Comparing grant_issuer with the Issuer Relationship for which the Grant Issuer retrieved the Relationship View () detects errors in routing, caching, or the association of responses with requests. The comparison does not show that the Resource Authorization Server selected the content of the Relationship View correctly. A Relationship View is complete and is not paged. If the Issuer Relationship has no eligible tenants, both arrays are empty.

Tenant Object A Tenant Object binds one Resource Authorization Server tenant that is eligible for an Issuer Relationship to the Grant Catalog that applies to that tenant. Tenant Object Members

Member	Status	Description
`tenant_id`	OPTIONAL	String; the exact tenant identifier () of the Resource Authorization Server tenant, which a grant issued for this tenant conveys as its target tenant ()
`display`, `description`	OPTIONAL	See
`grant_catalog`	REQUIRED	String; the `id` of the Grant Catalog that applies to this tenant

A Tenant Object is identified by its tenant_id or, if it has none, by that absence. An ID-JAG conveys tenant_id in the aud_tenant claim (). The following requirements apply to tenant_id:

The Resource Authorization Server MUST include tenant_id unless its issuer identifier alone identifies the target tenant.
A Relationship View MUST NOT contain more than one Tenant Object without tenant_id, or two Tenant Objects with the same value of tenant_id.

A Tenant Object that contains tenant_id is usable only with entries whose Grant Profile can convey a target tenant (, ). Several Tenant Objects can reference the same Grant Catalog. Tenant Objects for tenants that differ in any input that an entry governs () reference different Grant Catalogs. A Tenant Object has no default Grant Catalog, and Grant Catalogs have no inheritance, partial overrides, or merge rules. specifies how a change to grant_catalog affects approvals. A Tenant Object with a different tenant_id is a different Tenant Object. The following is an example of a Tenant Object:

Grant Catalog A Grant Catalog is a complete set of entries and is never paged or assembled from parts. Grant Catalog Members

Member	Status	Description
`id`	REQUIRED	Identifier ()
`display`, `description`	OPTIONAL	See
`entries`	REQUIRED	Array of entries ()

An empty entries array indicates that the Resource Authorization Server offers no grants for the tenants whose Tenant Objects reference this Grant Catalog. A Grant Catalog can contain entries for several Grant Profiles.

Entry An entry describes the grants of one Grant Profile that the Resource Authorization Server accepts for one protected resource. Entry Members

Member	Status	Description
`id`	REQUIRED	Identifier ()
`revision`	REQUIRED	String of at most 255 octets in UTF-8; the version of the entry's normative semantics ()
`display`, `description`	OPTIONAL	See
`profile`	REQUIRED	String; the identifier of the Grant Profile of the grants the entry describes
`resource`	REQUIRED	String; the resource indicator () of the protected resource
`scope`	OPTIONAL	Object; permitted scope values ()
`authorization_details`	OPTIONAL	Object; permitted authorization details types ()
`claims`	OPTIONAL	Non-empty array of claim objects ()
`sub_id`	OPTIONAL	Object; permitted subject identifier formats ()
`grant_binding`	OPTIONAL	Object; permitted grant binding methods ()

The value of resource is an absolute URI and MUST NOT contain a fragment component. specifies the grants that the scope, authorization_details, claims, sub_id, and grant_binding members permit, including when they are absent. The profile member identifies the Grant Profile, not the grant type used to redeem the grant, because several Grant Profiles share the JWT bearer grant type urn:ietf:params:oauth:grant-type:jwt-bearer . A Grant Catalog can contain entries for several resources, and several entries can name the same resource when they describe different grants (). A client that needs access to several resources obtains a separate grant for each.

Requirement Levels The scope, authorization_details, sub_id, and grant_binding members of an entry each contain a requirement member, called the presence requirement, that states whether a grant conveys the input at all. Scope value objects, authorization details type objects, and claim objects each contain an OPTIONAL requirement member, called the item requirement, that states whether a grant conveys that item. The value of a requirement member is the JSON string required or optional. An absent item requirement is treated as optional. For a member with items A and B, the two levels permit the following selections: Selections Permitted by the Two Levels

Presence	Item Requirements	Permitted Selections
`optional`	A and B `optional`	None, A, B, or both
`required`	A and B `optional`	A, B, or both
`required`	A `required`, B `optional`	A, or both

A member whose presence requirement is optional MUST NOT contain an item whose item requirement is required. The formats of the sub_id member and the methods of the grant_binding member are alternatives and have no item requirement. For these members, a presence requirement of required means that a grant uses one of them ().

Scope The scope member of an entry is a JSON object with the following members: Members of the scope Member

Member	Status	Description
`requirement`	REQUIRED	The presence requirement ()
`values`	REQUIRED	Non-empty array of scope value objects

A scope value object has the following members: Scope Value Object Members

Member	Status	Description
`scope`	REQUIRED	String; one scope token ()
`requirement`	OPTIONAL	The item requirement ()
`display`, `description`	OPTIONAL	See

Authorization Details Types The authorization_details member of an entry is a JSON object with the following members: Members of the authorization_details Member

Member	Status	Description
`requirement`	REQUIRED	The presence requirement ()
`types`	REQUIRED	Non-empty array of authorization details type objects

An authorization details type object has the following members: Authorization Details Type Object Members

Member	Status	Description
`type`	REQUIRED	String; an authorization details type ()
`requirement`	OPTIONAL	The item requirement ()
`documentation_uri`	OPTIONAL	String; an absolute `https` URI of human-readable documentation for the type
`display`, `description`	OPTIONAL	See

An entry constrains the type values of the authorization details objects that a grant conveys, not the other members of those objects. A grant can convey more than one authorization details object of a permitted type. The Grant Issuer applies its policy to complete authorization details objects, and the Resource Authorization Server validates their contents at redemption. The catalog does not carry schemas for authorization details types ().

Claims An entry distinguishes two kinds of claims that a grant conveys:

Reserved claims:: Claims whose presence and values the Grant Profile or other members of the catalog determine, such as the issuer, audience, or target tenant of a grant, and claims that the Grant Profile requires in every grant. The Grant Profile Definition lists them.
Catalog-Governed Claims:: All other claims, including claims that the Grant Profile defines but does not require, such as an authentication context claim or an email address, and claims such as a department or group membership. A grant issued using an entry conveys a Catalog-Governed Claim only if the entry lists that claim.

Every claim that a grant issued using an entry conveys is either a reserved claim of its Grant Profile or a claim that the entry lists. A claim object has the following members: Claim Object Members

Member	Status	Description
`claim`	REQUIRED	String; a claim name in the namespace that the Grant Profile Definition specifies, which for JWT authorization grants is a JWT claim name ()
`requirement`	OPTIONAL	The item requirement ()
`definition_uri`	OPTIONAL	String; an absolute `https` URI of the definition of the claim
`display`, `description`	OPTIONAL	See

The claim member of a claim object MUST NOT be a reserved claim name of the entry's Grant Profile. A claim object has the following limits:

Listing a claim does not change the syntax or semantics that the Grant Profile or the claim's definition specifies for it.
Claim objects carry no constraints on claim values. An entry that lists an authentication context claim as required requires the claim to be present, not a particular value.
The definition_uri member is descriptive and does not establish the truth or provenance of a claim.

Subject Identifier The sub_id member of an entry is a JSON object with the following members: Members of the sub_id Member

Member	Status	Description
`requirement`	REQUIRED	The presence requirement ()
`formats`	REQUIRED	Non-empty array of unique format names from the "Security Event Identifier Formats" registry (), such as `email` or `saml-nameid` ()

This member describes a subject identifier conveyed in addition to the subject of the grant; for an ID-JAG, it is the sub_id claim ().

Grant Binding The grant_binding member of an entry is a JSON object with the following members: Members of the grant_binding Member

Member	Status	Description
`requirement`	REQUIRED	The presence requirement ()
`methods`	REQUIRED	Non-empty array of unique grant binding method names, defined below or by other specifications ()

This specification defines the following grant binding methods:

dpop:: The grant is bound to a DPoP key , and the client demonstrates possession of that key when presenting the grant.
mtls:: The grant is bound to an X.509 certificate , and the client presents that certificate when presenting the grant.

The catalog does not describe client authentication to the Resource Authorization Server or sender-constraining of the access token that server issues. Both are separate from grant binding.

Authorization Envelope An entry defines an Authorization Envelope: the set of grants that the Resource Authorization Server is prepared to accept for one protected resource from the Issuer Relationship. The inputs that an entry governs are the protected resource and the inputs listed in . Grant Issuer policy and the runtime request narrow the Authorization Envelope (). A grant is within the Authorization Envelope of an entry, for a Tenant Object that references the Grant Catalog containing the entry, when all of the following are true:

The grant conveys, as its only audience, the authorization_server of the Relationship View that contains the Grant Catalog.
If the Tenant Object contains tenant_id, the grant conveys that value as its target tenant. Otherwise, the grant conveys no target tenant.
The grant conveys the entry's resource as its only protected resource.
For each input in :
- If the entry has no member for the input, the grant conveys none of that input.
- Otherwise, every item of the input that the grant conveys is listed in the member, and the grant conveys every listed item whose item requirement is required.
- If the member's presence requirement is required, the grant conveys at least one item. The claims member has no presence requirement.
For grant binding, a bound grant uses exactly one method.

Inputs Governed by Members of an Entry

Input (Member)	Item	Conveyed When the Grant
Scope values (`scope`, )	The `scope` of each scope value object	Conveys that scope value
Authorization details (`authorization_details`, )	The `type` of each authorization details type object	Conveys at least one authorization details object of that type
Catalog-Governed Claims (`claims`, )	The `claim` of each claim object	Conveys that claim
Subject identifier in addition to the subject (`sub_id`, )	Each name in `formats`	Conveys a subject identifier in that format
Grant binding (`grant_binding`, )	Each name in `methods`	Is bound using that method

The inputs are independent: any selection of items that one member permits is permitted together with any selection that each other member permits. The catalog expresses no alternatives between sets of items, no exclusions, and no conditions, either within a member or between members. When the Resource Authorization Server accepts only some combinations, it publishes separate entries whose Authorization Envelopes each contain only accepted combinations (). For example, it might accept one scope value or another but not both, or a scope value only together with a particular claim. A Grant Issuer does not infer a rule that an entry does not state.

Entry Revision The revision member is an opaque version identifier controlled by the Resource Authorization Server. The normative semantics of an entry comprise:

the profile and resource members;
the scope member, including its requirement and the scope and requirement of each scope value object;
the authorization_details member, including its requirement and the type and requirement of each authorization details type object;
the claims member, including the claim and requirement of each claim object;
the sub_id and grant_binding members; and
any member that the specification defining it declares part of the normative semantics of an entry ().

The Resource Authorization Server:

MUST change the revision of an entry whenever it changes the normative semantics of the entry; and
MUST NOT use, in Relationship Views for the same Issuer Relationship, a revision value it has previously used for that entry with different normative semantics.

A counter that increases with each change, or a digest of the normative semantics, meets both requirements. When normative semantics are compared:

the order of elements in the values, types, claims, formats, and methods arrays is not significant;
an absent item requirement is equivalent to the value optional; and
a Grant Issuer compares only the members it understands.

A change limited to other members, such as display, description, documentation_uri, or definition_uri, does not require a new revision. The combination of the Resource Authorization Server issuer identifier, the Issuer Relationship, the Grant Catalog id, the entry id, and the revision identifies one set of normative semantics (). Grant Catalog identifiers are unique only within a Relationship View (), so the Grant Catalogs offered to two Issuer Relationships can share an identifier and differ in content. The revision member provides no integrity guarantee. It lets the Grant Issuer determine whether an approval made for an earlier copy of an entry still applies (). The retrieval protocol handles caching of representations.

Using a Catalog

Validating a Relationship View Before installing any part of a Relationship View, the Grant Issuer MUST verify the following:

The authorization_server of the Relationship View, and any other issuer identifier that the retrieval protocol conveys, are identical to the issuer identifier of the Resource Authorization Server with which the Grant Issuer associates the Issuer Relationship, using simple string comparison ().
The grant_issuer of the Relationship View identifies the Issuer Relationship for which the Grant Issuer retrieved the Relationship View: the issuer of grant_issuer is identical to that relationship's issuer identifier, and the tenant of grant_issuer and that relationship's issuer tenant identifier are either identical or both absent.
Every document conforms to I-JSON . The Relationship View, the structures that the retrieval protocol defines, every Tenant Object, and every Grant Catalog other than the contents of its entries satisfy their definitions: every REQUIRED member is present, and every member defined by this specification has the specified JSON type and meets the constraints stated for it. Grant Catalog and entry identifiers satisfy .
The grant_catalog of every Tenant Object identifies a Grant Catalog in the Relationship View, and every Grant Catalog in the Relationship View is referenced by at least one Tenant Object.
At most one Tenant Object omits tenant_id, and no two Tenant Objects have the same tenant_id.
No entry has a Resource Authorization Server issuer identifier, Grant Catalog id, entry id, and revision that the Grant Issuer has currently installed, for the same Issuer Relationship, with different normative semantics ().

If any of these checks fails, the retrieval is incomplete, and the Grant Issuer MUST NOT install any part of the Relationship View obtained in it (). In addition, the Grant Issuer MUST NOT use an entry for issuance if any of the following is true. Each of these conditions affects only that entry:

The Grant Issuer does not implement a Grant Profile Definition for the Grant Profile identified by profile.
A member of the entry other than its id, or a member of an object within the entry, does not satisfy its definition in or : a REQUIRED member is absent, a member has a JSON type other than the one specified, or a constraint stated for the member is not met.
The entry contains a member for an input () that its Grant Profile Definition states the Grant Profile cannot convey ().
The entry conflicts with public metadata ().

An entry that requires an item the Grant Issuer cannot produce, such as a subject identifier format or a grant binding method that the Grant Issuer does not implement, is valid but cannot be used by that Grant Issuer. A Grant Issuer SHOULD make available to its administrators the reason that a Relationship View was not installed or that an entry cannot be used for issuance.

Composition with Public Metadata Public metadata remains authoritative for what it describes, and an entry cannot enable a value that public metadata excludes. When it installs a Relationship View, the Grant Issuer composes each entry with public metadata as follows:

Retrieve and validate the Resource Authorization Server's Authorization Server Metadata (), and verify that its issuer identifier is identical to the authorization_server of the Relationship View.
If the entry's resource is a URL that uses the https scheme (), request its Protected Resource Metadata using the oauth-protected-resource well-known URI suffix (); otherwise, this step has no effect. If the response has HTTP status code 200 (OK), validate the metadata as specified in . Any other response, or no response, leaves this step without effect, because publishing Protected Resource Metadata is optional.
For each member in the following table that the Authorization Server Metadata or the validated Protected Resource Metadata contains, verify that the member's values include every corresponding value of the entry.
Perform the checks that the Grant Profile Definition specifies, such as checks of grant_types_supported ().

Public Metadata Members Checked in Composition

Member	Metadata	Entry Values Checked
`authorization_grant_profiles_supported` ()	Authorization Server	`profile`
`authorization_details_types_supported` ()	Authorization Server	Each authorization details `type`
`authorization_details_types_supported` ()	Protected Resource	Each authorization details `type`

A Resource Authorization Server that publishes authorization_grant_profiles_supported MUST include in it the Grant Profile of every entry it publishes. A specification that defines another metadata member listing the values supported for a Grant Profile, or for an input that an entry governs (), can specify that the member is checked in the same way. A member is not checked if its defining specification permits a server to omit supported values from it: the scope values of an entry need not appear in scopes_supported (, ), and an authorization_servers member of Protected Resource Metadata that omits the Resource Authorization Server's issuer identifier is not a conflict (). If a step fails, the entry conflicts with public metadata, and the Grant Issuer MUST NOT use the entry for issuance. Step 2 fails if Protected Resource Metadata is retrieved and fails validation. The Grant Issuer does not resolve a conflict by preferring catalog values over public metadata or by combining values from both.

Approval and Runtime Narrowing An administrator of the Grant Issuer approves a subset of an entry for use with a Tenant Object that references the entry's Grant Catalog. An approved subset is an Authorization Envelope contained in the entry's Authorization Envelope. It retains every requirement of the entry and can add requirements of its own. An administrator can:

remove optional items;
remove subject identifier formats and binding methods; and
make an optional member or item required.

For example, for an entry whose grant_binding member has the requirement optional and the methods dpop and mtls, an administrator can approve a subset in which binding is required and dpop is the only method. How a Grant Issuer records approval, and whether it approves entries for particular clients or subjects, is a matter of Grant Issuer policy. The rules in that refer to what an entry requires or permits apply to the approved subset. At runtime, the Grant Issuer applies subject, client, consent, and other local policy, and the client's request, to narrow the approved subset further. For an item that the approved subset requires:

if local policy excludes the item, the Grant Issuer MUST NOT issue a grant using that entry; and
if the client's request omits the item, the Grant Issuer either adds it, when its policy permits issuing values that the client did not request, or does not issue a grant using that entry.

For example:

Narrowing of Scope Values The Grant Issuer cannot issue messages.admin merely because public metadata advertises it, and cannot issue messages.write merely because the catalog permits it.

Issuing a Grant When a Grant Issuer issues a grant using an entry, the Grant Issuer MUST ensure that the grant is within the Authorization Envelope of the subset of that entry approved for the Tenant Object for which the grant is issued (). The Grant Issuer issues each grant using exactly one entry, and MUST NOT combine inputs permitted by different entries in one grant. After authenticating the client and the subject and applying its policy, the Grant Issuer issues a grant as specified by the Grant Profile, using one approved Tenant Object and one approved entry. The Grant Issuer selects the Tenant Object from the client's request and its own configuration for the Issuer Relationship; the catalog defines no parameter of the client's grant request for selecting a target tenant (). The Grant Issuer selects an entry whose Grant Profile matches the kind of grant the client requested and whose resource is the requested protected resource. When more than one approved Tenant Object or entry could satisfy a request, Grant Issuer policy selects one. The Grant Issuer issues a grant for a request that names several resources only if its policy reduces the request to one of them. It issues a grant for a request that names no resource only if its policy determines one (). The Grant Issuer MUST NOT issue a grant using an entry obtained for an Issuer Relationship unless the grant identifies its issuer by the issuer identifier of that relationship and, when the relationship has an issuer tenant, identifies that issuer tenant, as the Grant Profile Definition specifies (). The Grant Issuer MUST NOT derive a target tenant identifier from the number of Tenant Objects in a Relationship View or from the form of an issuer identifier. The Grant Issuer decides whether it releases a claim value. If an entry requires a claim that the Grant Issuer's policy does not permit it to release for a subject, the Grant Issuer MUST NOT issue a grant using that entry for that subject. An entry does not create a binding. The Grant Issuer binds a grant only to a key or certificate whose possession the client has demonstrated, and selects the binding as the Grant Profile Definition specifies. Where the Grant Profile allows a choice of method, the Grant Issuer chooses a method that the entry permits. The Grant Issuer MUST NOT issue a grant using an entry in either of the following cases:

the entry requires binding and the client has not demonstrated possession using any listed method; or
the Grant Profile requires the Grant Issuer to bind the grant, and the entry permits none of the methods that would satisfy that requirement.

The Grant Issuer uses an entry with a Tenant Object only when all of the following hold:

The Relationship View that contains them is installed ().
The entry is usable for issuance ().
If the Tenant Object contains tenant_id, the entry's Grant Profile can convey a target tenant ().
An approval for the entry and the Tenant Object applies ().

When the Grant Issuer does not issue a grant because no approved entry permits the request, it responds to the client as the Grant Profile Definition specifies.

Clients The catalog does not enumerate or register application clients, or establish client identifier mappings. A Relationship View is relationship-wide and does not establish eligibility for a particular application client: a Resource Authorization Server can permit a grant configuration for one application client and reject an otherwise equivalent configuration for another. When the grants of a Grant Profile identify the client by its client identifier at the Resource Authorization Server, its Grant Profile Definition specifies how the Grant Issuer obtains that identifier, as does for ID-JAG. Such an identifier can be shared across trust domains .

Installation and Reconciliation The following terms describe a retrieval:

Complete retrieval:: A retrieval in which the Grant Issuer obtains and validates a complete Relationship View (), or in which the retrieval protocol confirms the installed one ().
Incomplete retrieval:: A retrieval in which a transport failure occurs, a response is interrupted or fails validation, or the Resource Authorization Server rejects the Grant Issuer's credentials.

After a complete retrieval, the Grant Issuer replaces the installed state for the Issuer Relationship with the new Relationship View. A Tenant Object, Grant Catalog, or entry that the new Relationship View omits, or contains with a different grant_catalog or revision, is withdrawn. A Grant Issuer retains the following with each approval:

the Resource Authorization Server issuer identifier;
the Issuer Relationship;
the Tenant Object's tenant_id, if any;
the Grant Catalog id;
the entry id and revision;
the approved subset; and
any client identifier mapping that the Grant Profile requires.

The items of the approved subset are identified by their protocol values. State that is specific to a retrieval protocol, such as a URI or an HTTP entity tag, is retained separately and is not part of an approval. An approval applies while the installed Relationship View contains a Tenant Object that has the approved tenant_id (or no tenant_id, if the approved Tenant Object had none) and the approved grant_catalog, and that Grant Catalog contains an entry with the approved id and revision. The Grant Issuer applies the rules in after each retrieval. Effects of a Retrieval on Installed State and Approvals

Event	Rule
A retrieval is incomplete	The Grant Issuer MUST NOT install any state from that retrieval, and does not treat it as a withdrawal. State installed from an earlier retrieval remains in force, subject to the maximum age below.
A Tenant Object or entry appears	The appearance of a new Tenant Object or entry MUST NOT, by itself, cause the Grant Issuer to issue grants using it.
An entry changes	A change to an entry MUST NOT, by itself, expand an existing approval.
Only members outside the normative semantics of an entry change (), and every approved identifier, `grant_catalog`, and `revision` is unchanged	Approvals that depend on the changed objects continue to apply.
A Tenant Object, Grant Catalog, or entry is withdrawn	The Grant Issuer MUST stop issuing grants that depend on it in its previous form, and suspends issuance under the approvals that depend on it.
The `grant_catalog` of a Tenant Object, or the `revision` of an entry, changes	The Grant Issuer MUST NOT issue grants under an approval made for the previous value. Issuance resumes only under an approval made for the new value.
A later complete retrieval contains a withdrawn object again with the approved identifiers, `grant_catalog`, and `revision`	The approval applies again without new approval.

A change of grant_catalog or revision also withdraws the previous form of the object, so the withdrawal row applies to it as well. These rules apply to every change of revision, including a change that only narrows an entry, such as the removal of a scope value (). Whether to relax these rules is an open issue (). The Grant Issuer SHOULD retrieve the Relationship View periodically and after administrative changes to the Issuer Relationship. The Grant Issuer SHOULD stop issuing grants that depend on installed state it has not been able to refresh within a maximum age that it configures for the Issuer Relationship, such as one day. The maximum age is measured from the most recent complete retrieval. An incomplete retrieval, including one that results from the end of the Issuer Relationship, does not extend the maximum age (). A Resource Authorization Server that needs issuance to stop sooner removes every eligible tenant from the relationship before ending it. The Grant Issuer observes that removal at its next refresh as a withdrawal.

Optional Supporting Metadata A Grant Issuer can use other metadata to help administrators understand entries: authorization details types metadata describes the structure of an authorization details type, and authority metadata describes what a scope value or authorization details type authorizes. Such metadata is advisory:

it cannot broaden an entry or an approval;
it does not cause an entry to conflict with public metadata; and
its absence, or a failure to retrieve it, does not affect the validity of an entry.

This specification does not define how a Grant Issuer uses schemas or authority descriptions to enforce or narrow policy. The Grant Issuer MUST NOT send a credential obtained through a retrieval protocol when dereferencing a schema_uri (), documentation_uri, or definition_uri.

Retrieving a Catalog Before disclosing catalog content to a Grant Issuer, the Resource Authorization Server establishes, through a retrieval protocol (), which Issuer Relationship the disclosure serves. and apply to every retrieval protocol. The remaining subsections define the OAuth retrieval protocol, which requires only public metadata and an Onboarding Arrangement and is the same for every Grant Profile.

Relationship Identity An Issuer Relationship is identified by the Grant Issuer's issuer identifier and, when that issuer is multi-tenant, an issuer tenant identifier. An issuer tenant identifier is a tenant identifier () of the Grant Issuer. Grants issued by the Grant Issuer identify their issuer and issuer tenant by these values. Where a grant or a catalog access assertion conveys the issuer tenant identifier in the tenant claim , the value is the stable, issuer-unique form of that claim. The values personal and organization, which Section 2.2 of reserves for categories of accounts, do not identify an issuer tenant. An issuer tenant identifier is scoped by the issuer identifier. The Resource Authorization Server:

MUST treat the pair of issuer identifier and issuer tenant identifier as one exact identifier; and
MUST NOT interpret, normalize, or derive an issuer tenant identifier, or compare issuer tenant identifiers across issuers.

Relationship Authorization An Onboarding Arrangement () records:

whether the Grant Issuer uses a multi-tenant issuer;
which Resource Authorization Server tenants are eligible for the Issuer Relationship;
which keys and algorithms the Grant Issuer uses; and
for the OAuth retrieval protocol, whether client authentication or DPoP-bound catalog access assertions are required.

The Resource Authorization Server:

MUST NOT disclose catalog content to an Issuer Relationship that no Onboarding Arrangement authorizes;
MUST determine the Relationship View solely from the authenticated Issuer Relationship; and
MUST verify that the Issuer Relationship is authorized each time it discloses catalog content.

Ending an Issuer Relationship stops disclosure, even under a credential issued before the relationship ended.

Authorization Server Metadata This specification defines the following Authorization Server Metadata member for the OAuth retrieval protocol:

authorization_grant_catalog_endpoint:

URL of the catalog endpoint, from which the Grant Issuer retrieves its Relationship View (). The URL:

uses the https scheme;
contains no fragment component; and
is the resource indicator () of a protected resource called the catalog resource.

A Resource Authorization Server that supports the OAuth retrieval protocol MUST publish this member. A Grant Issuer MUST NOT use the OAuth retrieval protocol with a Resource Authorization Server whose metadata omits this member. The following is an example of Authorization Server Metadata for a Resource Authorization Server that supports ID-JAG and the OAuth retrieval protocol:

Catalog Access Assertion A catalog access assertion is a JWT that the Grant Issuer signs on its own behalf, not on behalf of an end user or a client. The Grant Issuer presents it as an authorization grant to obtain a catalog access token. The assertion is not a grant in the sense of this specification (). A catalog access assertion is a JWS with the following JOSE header parameters:

typ:: REQUIRED. The value oauth-grant-catalog-access+jwt ().
alg:: REQUIRED. An asymmetric digital signature algorithm. The value MUST NOT be none or a MAC-based algorithm.
kid:: OPTIONAL. The key identifier of the Grant Issuer's signing key.

The catalog access assertion contains the following claims:

iss:: REQUIRED. The issuer identifier of the Grant Issuer ().
sub:: REQUIRED. The same value as iss. requires a sub claim; for this assertion, the claim has no other meaning.
aud:: REQUIRED. The issuer identifier of the Resource Authorization Server, as a JSON string. This narrows , which also permits the token endpoint URL.
tenant:: REQUIRED if the Grant Issuer uses a multi-tenant issuer; otherwise, it MUST be omitted. The issuer tenant identifier of the Issuer Relationship (), conveyed in the tenant claim .
iat:: REQUIRED. The time at which the assertion was issued ().
exp:: REQUIRED. The expiration time of the assertion (). The value MUST NOT be more than 300 seconds after the value of iat.
jti:: REQUIRED. A unique identifier for the assertion ().
cnf:: OPTIONAL. A confirmation claim that binds the assertion to a DPoP key that the Grant Issuer controls, as specified in . A catalog access assertion that contains this claim is DPoP-bound. The Grant Issuer MUST NOT include this claim unless the grant_types_supported member of the Resource Authorization Server's metadata includes urn:ietf:params:oauth:grant-type:jwt-dpop.

The catalog access assertion identifies only the Issuer Relationship and, when the assertion is DPoP-bound, the Grant Issuer's DPoP key. It does not contain the aud_tenant claim or identify a Grant Profile, target tenant, End-User, client, resource, scope, or authorization details. Other claims MAY be present and are ignored unless understood. The following is an example of the JOSE header and claims of a catalog access assertion:

Validating the Catalog Access Assertion The Resource Authorization Server validates the catalog access assertion as specified in , and in addition MUST ensure the following:

The typ JOSE header parameter is oauth-grant-catalog-access+jwt.
The iss claim identifies a Grant Issuer for which an Onboarding Arrangement exists. The signature verifies using a key of that issuer obtained from the jwks_uri in the issuer's Authorization Server Metadata () or provisioned under the Onboarding Arrangement. The signature algorithm is an asymmetric algorithm that the Resource Authorization Server allows for that issuer ().
The sub claim is identical to the iss claim.
The aud claim is a JSON string identical to the issuer identifier of the Resource Authorization Server.
The iat claim is present and, subject to the Resource Authorization Server's allowance for clock skew, is not later than the current time, and exp is not more than 300 seconds after iat.
The jti claim is present and has not been used in a previously accepted catalog access assertion from the same issuer. An assertion is accepted when the Resource Authorization Server issues a catalog access token in response to it. The Resource Authorization Server retains each accepted jti value, across every instance of its token endpoint, until the assertion's exp time plus the allowance for clock skew has passed.
The pair of iss and, when present, tenant identifies an Issuer Relationship that an Onboarding Arrangement currently authorizes (). An assertion identifies no Issuer Relationship if:
- the issuer is multi-tenant and the assertion has no tenant claim;
- the issuer is multi-tenant and the assertion has a tenant claim with the value personal or organization; or
- the issuer is single-tenant and the assertion has a tenant claim.

The Resource Authorization Server:

MUST NOT accept a JWT with a typ other than oauth-grant-catalog-access+jwt as a catalog access assertion; and
MUST NOT accept a catalog access assertion as a grant of any Grant Profile or as a client assertion.

These rules apply whether or not a Grant Profile specifies a typ value for its grants ().

Catalog Access Token Request The Grant Issuer requests a catalog access token by sending a token request () to the token endpoint of the Resource Authorization Server with the following parameters:

grant_type:: REQUIRED. The value urn:ietf:params:oauth:grant-type:jwt-bearer or, for a DPoP-bound catalog access assertion, the value urn:ietf:params:oauth:grant-type:jwt-dpop ().
assertion:: REQUIRED. The catalog access assertion.
resource:: REQUIRED. The value of the authorization_grant_catalog_endpoint metadata member ().
scope:: REQUIRED. The value authorization_grant_catalog.read, the scope value this specification defines for read access to the catalog.

A Resource Authorization Server that supports the OAuth retrieval protocol and includes urn:ietf:params:oauth:grant-type:jwt-dpop in grant_types_supported MUST accept DPoP-bound catalog access assertions. When the Onboarding Arrangement requires client authentication at the token endpoint (), the Grant Issuer is a registered client of the Resource Authorization Server. The Grant Issuer authenticates using the method that the Onboarding Arrangement fixes, such as a JWT client assertion signed with a key of the Grant Issuer (). The following rules apply to client assertions:

A Grant Issuer that authenticates with a JWT client assertion MUST use the issuer identifier of the Resource Authorization Server as the sole value of the client assertion's aud claim.
The Resource Authorization Server MUST reject a catalog access token request whose client assertion does not contain its issuer identifier as the sole audience value ().
The Grant Issuer MUST NOT use a catalog access assertion as a client assertion.
The Grant Issuer SHOULD sign client assertions with a key that it does not use to sign catalog access assertions or grants ().

When client authentication is not required, the request contains no client_id parameter. The following is an example of a catalog access token request that uses client authentication, with both assertions abbreviated (line breaks for display purposes only): The Resource Authorization Server processes the request as follows:

If the grant type is urn:ietf:params:oauth:grant-type:jwt-dpop, it validates the DPoP proof () before validating the assertion, so that a request rejected for its proof or nonce does not consume the assertion's jti ().
It validates the catalog access assertion ().
It checks the assertion according to the grant type:
- If the grant type is urn:ietf:params:oauth:grant-type:jwt-dpop, it verifies that the assertion is bound to the key of the DPoP proof () and that its cnf claim contains only the jkt member.
- If the grant type is urn:ietf:params:oauth:grant-type:jwt-bearer, it verifies that the assertion contains no cnf claim, whether or not it supports the urn:ietf:params:oauth:grant-type:jwt-dpop grant type (), and that the Onboarding Arrangement does not require DPoP-bound catalog access assertions.
It verifies that the resource parameter is identical to its authorization_grant_catalog_endpoint metadata value.
It verifies that the scope parameter is authorization_grant_catalog.read.
If the Onboarding Arrangement requires client authentication, it authenticates the client and verifies that the Onboarding Arrangement associates the authenticated client with the iss claim of the catalog access assertion. It does not accept as a client assertion any JWT whose typ is oauth-grant-catalog-access+jwt.
It records the assertion's jti value as accepted and issues the catalog access token. It checks that the value is still unused and records it in one atomic operation, so that two concurrent requests that carry the same assertion cannot both obtain a catalog access token, and a request rejected by an earlier step does not consume the value.

When the Onboarding Arrangement requires client authentication, the Resource Authorization Server MUST NOT issue a catalog access token on the strength of the catalog access assertion alone. Because the catalog is disclosed to the Issuer Relationship identified by the catalog access assertion, not to the authenticated client, a Grant Issuer that uses a multi-tenant issuer needs at most one client registration at each Resource Authorization Server. The Grant Issuer's client identifier can then equal its issuer identifier, as in the example above.

Catalog Access Token Response If the request is valid, the Resource Authorization Server responds as specified in . The Resource Authorization Server:

MUST restrict the catalog access token to the catalog resource and the authorization_grant_catalog.read scope; and
MUST associate the token with the Issuer Relationship identified by the catalog access assertion.

The Resource Authorization Server SHOULD issue catalog access tokens with a lifetime of a few minutes, and MUST NOT issue a refresh token; the Grant Issuer obtains a new catalog access token with a new catalog access assertion. The Resource Authorization Server MUST NOT issue an access token for the catalog resource, or with the authorization_grant_catalog.read scope, in response to any token request other than one specified in . The following is an example of a catalog access token response: When the catalog access assertion is DPoP-bound, the Resource Authorization Server MUST issue a catalog access token bound to the same key, with the token_type value DPoP (). The catalog resource is a protected resource of the Resource Authorization Server, so the exception in that section for protected resources that do not support DPoP does not apply. When the catalog access assertion is not DPoP-bound, the Resource Authorization Server MAY issue a DPoP-bound catalog access token () or a certificate-bound catalog access token () when the Grant Issuer uses those mechanisms.

Relationship View Document The Grant Issuer retrieves its Relationship View by sending an HTTP GET request to the authorization_grant_catalog_endpoint URL, presenting the catalog access token as specified in or, for a DPoP-bound token, . The Resource Authorization Server verifies the DPoP proof for a DPoP-bound token and rejects a DPoP-bound token presented as a bearer token (). The Grant Issuer MUST send a catalog access token only to the authorization_grant_catalog_endpoint URL from Authorization Server Metadata it has validated (), without further resolution or normalization of that URL. The Grant Issuer MUST NOT follow redirections in response to a request that carries a catalog access token, and treats a redirection as an incomplete retrieval (). The Resource Authorization Server determines the Relationship View from the Issuer Relationship associated with the catalog access token (). It responds with HTTP status code 200 (OK) and a Relationship View document of media type application/oauth-grant-catalog+json (), whose content is the Relationship View (). The Resource Authorization Server MUST construct the document from one consistent state of the Issuer Relationship. The Grant Issuer validates the document as specified in , and treats a response of any other media type as an incomplete retrieval (). The following is an example of a Relationship View document request and response for another Issuer Relationship, with the issuer tenant acme-workforce and two eligible tenants. The entries of each Grant Catalog are abbreviated; shows the Grant Catalog standard in full:

Caching and Refresh The Resource Authorization Server SHOULD include a strong entity tag () in each Relationship View document response, and SHOULD support conditional requests using If-None-Match (). When the Grant Issuer holds an entity tag, it sends a conditional request, and sends If-None-Match only with the entity tag of a representation it has installed. A 304 (Not Modified) response () confirms the installed Relationship View and is a complete retrieval (). A Relationship View document is specific to an Issuer Relationship. The Resource Authorization Server MUST include Cache-Control: no-store () in these responses. The Grant Issuer retains the document and its entity tag as application state, keyed by the Resource Authorization Server's issuer identifier and the Issuer Relationship. This retrieval protocol is designed for Relationship Views of up to several thousand Tenant Objects in one response, not for unbounded collections. The Grant Issuer SHOULD indicate support for content codings using Accept-Encoding (), and the Resource Authorization Server SHOULD compress responses when the Grant Issuer supports a content coding.

Error Responses The token endpoint returns errors as specified in and, for the urn:ietf:params:oauth:grant-type:jwt-dpop grant type, . The Resource Authorization Server returns:

invalid_grant, if:
- the catalog access assertion is invalid, expired, or replayed, or identifies no authorized Issuer Relationship;
- a DPoP-bound assertion is presented with the urn:ietf:params:oauth:grant-type:jwt-bearer grant type;
- an assertion that is not DPoP-bound is presented when the Onboarding Arrangement requires one; or
- the client that the Grant Issuer authenticated as is not associated with the assertion's issuer.
invalid_target (), if the resource parameter is missing or is not the catalog resource.
invalid_scope, if the scope parameter is missing or is not authorization_grant_catalog.read.

The catalog endpoint returns errors as specified in , or for a DPoP-bound token. The Resource Authorization Server responds with:

HTTP status code 401 (Unauthorized) and invalid_token, if the Issuer Relationship associated with the catalog access token is no longer authorized.
HTTP status code 403 (Forbidden) and insufficient_scope, if the access token does not include the authorization_grant_catalog.read scope ().

An error response MUST NOT disclose whether another issuer, issuer tenant, Resource Authorization Server tenant, Grant Catalog, or entry exists.

Identity Assertion JWT Authorization Grant Profile In this Grant Profile Definition for , the Grant Issuer is the IdP Authorization Server and grants are ID-JAGs. A Grant Profile Definition for another profile of the JWT authorization grant can reuse the representation of inputs in .

Grant Profile identifier:

urn:ietf:params:oauth:grant-profile:id-jag ().

Grant binding:

The IdP Authorization Server selects the binding as described in . When the client presents a valid DPoP proof, ID-JAG requires the IdP Authorization Server to bind the ID-JAG to the DPoP key or a client certificate (). Either method satisfies that requirement if the approved subset permits it ().

When the approved subset permits neither method, the IdP Authorization Server does not issue an ID-JAG using the entry for a request with a valid DPoP proof (), so a Resource Authorization Server that verifies DPoP-bound ID-JAGs lists dpop in its entries.

Resource selection:

ID-JAG does not require the resource parameter of the Token Exchange request (); specifies how the IdP Authorization Server selects an entry when that parameter is absent.

Tenant selection:

The IdP Authorization Server selects the Tenant Object as it determines the aud_tenant claim ().

Error responses:

When the IdP Authorization Server does not issue an ID-JAG because no approved entry permits the request, it responds to the Token Exchange request with the access_denied error code ().

Narrowed rules:

Catalog use narrows the following rules of :

An ID-JAG issued using an entry always contains the resource claim with exactly one resource identifier. makes the claim OPTIONAL and permits several resource identifiers.
An ID-JAG issued using an entry contains a Catalog-Governed Claim only if the entry lists it (). allows any claim valid in an ID Token and recommends the email and aud_sub claims for subject resolution. A Resource Authorization Server that uses those claims lists them in its entries.
Requiring tenant_id in a Tenant Object () is stricter than , which also lets a Resource Authorization Server identify the target tenant from its trust relationship with the issuer.

Clients:

The client_id claim carries the client's identifier at the Resource Authorization Server. The IdP Authorization Server obtains this value as described in ; the catalog does not provide it ().

The following is an example of the claims of an ID-JAG issued for the Tenant Object customer-acme-eu in , using the entry in :

Representation of Inputs An ID-JAG conveys its issuer, its issuer tenant (), and the values that constrains as follows. Representation of Inputs in an ID-JAG

Input	JWT Representation
Issuer	`iss` claim ()
Issuer tenant	`tenant` claim ()
Audience	`aud` claim, as a string or an array of one string
Target tenant	`aud_tenant` claim ()
Protected resource	`resource` claim (), as a string or an array of one string
Scope values	`scope` claim ()
Authorization details	`authorization_details` claim ()
Catalog-Governed Claims	Claims named by the `claim` member of claim objects
Subject identifier	`sub_id` claim ()
Grant binding	`cnf` claim ()

A cnf claim that represents a binding contains only the confirmation member of one method:

dpop:: The jkt confirmation member, containing the JWK SHA-256 Thumbprint of the client's DPoP key (), as specified in .
mtls:: The x5t#S256 confirmation member, containing the SHA-256 thumbprint of the client's X.509 certificate ().

Reserved Claims The reserved claim names of this Grant Profile are iss, sub, aud, jti, exp, iat, nbf, tenant, aud_tenant, resource, scope, authorization_details, sub_id, cnf, client_id (), and act (). The Grant Profile, not an entry, determines whether a grant conveys a client identifier or an actor. The other claims that defines (auth_time, acr, amr, aud_sub, and email) are Catalog-Governed Claims. An ID-JAG has the typ value oauth-id-jag+jwt (); see .

Composition Checks A Resource Authorization Server that publishes entries for this Grant Profile MUST include grant_types_supported in its Authorization Server Metadata; if it lists this Grant Profile in authorization_grant_profiles_supported, it also includes urn:ietf:params:oauth:grant-type:jwt-bearer in grant_types_supported (). For each such entry, the Grant Issuer performs the following checks in step 4 of , interpreting grant_types_supported with the default value defined in :

Unless the entry requires binding and lists dpop as its only method, grant_types_supported includes urn:ietf:params:oauth:grant-type:jwt-bearer.
If the entry lists dpop, grant_types_supported includes urn:ietf:params:oauth:grant-type:jwt-dpop ().

Extensibility The extension points below are designed to preserve the principles in .

Grant Profiles:

A specification can apply the catalog to another Grant Profile by providing a Grant Profile Definition (). A Grant Issuer that does not implement that Grant Profile Definition does not use that profile's entries ().

Members:

A specification can define additional members of the objects defined in this specification. A Grant Issuer ignores members it does not understand (). If the value of a member of an entry, or of an object within an entry, affects what an administrator approves or which grants the entry permits, the specification that defines the member declares that member part of the entry's normative semantics ().

An extension member is either advisory or restrictive:

An advisory member informs approval, for example by grouping entries for presentation to administrators. A Grant Issuer that ignores an advisory member still issues only grants within the entry's Authorization Envelope as this specification defines it.
A restrictive member narrows the grants that the Resource Authorization Server accepts below the entry's Authorization Envelope, for example by constraining the values in authorization details objects. A Grant Issuer that ignores a restrictive member issues grants that the Resource Authorization Server rejects, after their claims have been disclosed to the client.

A specification MUST NOT define a restrictive member unless it also defines a mechanism that prevents Grant Issuers that do not implement the member from using the entry, such as a distinct Grant Profile identifier. This specification defines no such mechanism ().

Grant binding methods:

A specification can define additional grant binding methods. It states how the Grant Issuer binds a grant, how the Resource Authorization Server verifies the binding, and how a grant represents it.

Retrieval protocols:

A specification can define another retrieval protocol. That protocol:

defines error responses;
defines how the Grant Issuer locates the catalog;
authenticates the Issuer Relationship () to the Resource Authorization Server;
authenticates the Resource Authorization Server to the Grant Issuer; and
delivers, unchanged, a complete Relationship View () that reflects one consistent state of the Issuer Relationship.

A Grant Issuer does not combine objects obtained through different retrieval protocols.

Grant Profile Definitions A Grant Profile Definition specifies the following:

The Grant Profile identifier used in the profile member of an entry.
How a grant of the profile conveys each input in . A Grant Profile to which the catalog applies conveys the audience and the protected resource. Where the profile cannot convey another input, the Grant Profile Definition says so; an entry for that profile then does not contain the corresponding member.
How a grant of the profile identifies its issuer and, for a multi-tenant issuer, its issuer tenant ().
The reserved claim names of the profile, including the claims the profile requires in every grant (), and the namespace of the claim member.
For each grant binding method the profile supports, how the binding is represented in a grant, when the profile requires the Grant Issuer to bind a grant, and how the Grant Issuer selects among methods ().
The composition checks against public metadata that apply to the profile, such as checks of the grant types used to redeem its grants ().
How the Grant Issuer selects a Tenant Object for a request, and how it responds when it does not issue a grant because no approved entry permits the request ().
Any rule of the Grant Profile that catalog use narrows, such as making an OPTIONAL element required.
For a profile whose grants identify the client by its client identifier at the Resource Authorization Server, how the Grant Issuer obtains that identifier ().

A Grant Profile Definition for a JWT authorization grant SHOULD specify a typ value for the grants of the profile (), so that a Resource Authorization Server that accepts them at the same token endpoint as catalog access assertions can distinguish the two ().

Security Considerations The security considerations of , , , and , and of the Grant Profile of each entry, such as , apply to this specification.

Catalog Is Not an Authorization Decision A catalog neither authorizes a request () nor lists every grant that the Resource Authorization Server accepts: the Resource Authorization Server can accept grants issued under other arrangements, or under an entry that it has since withdrawn, as its policy determines. The Authorization Envelope protects the Resource Authorization Server only as far as the Grant Issuer observes it, so a Resource Authorization Server that requires a property of every grant it accepts enforces that property at redemption.

Changes in Scope Meaning An entry does not state the authority that its scope values and authorization details types represent at the protected resource, so an approval bounds the grants that the Grant Issuer constructs, not what those grants authorize. For example, if the protected resource changes messages.write so that it also permits deleting messages, the entry and its revision do not change, and approvals that include messages.write continue to apply. A Resource Authorization Server that changes the authority of an existing scope value can instead publish a new scope value, so that the change requires new approval. Authority metadata can reveal such a change () but does not bind the protected resource.

Relationship Authorization and Assertion Trust Trust in a Grant Issuer's signing keys establishes that the Grant Issuer can issue grants, not that it is entitled to learn the Resource Authorization Server's configuration for every issuer tenant identifier it can name. An Onboarding Arrangement authorizes each Issuer Relationship separately (). When a Resource Authorization Server accepts one signing key for several Issuer Relationships, as it can for a multi-tenant issuer, a compromise of that key or of the signing service that uses it discloses the catalogs of all those Issuer Relationships. This specification requires no particular arrangement of keys across tenants. An Onboarding Arrangement authorizes an issuer tenant identifier, not the organization behind it. If an issuer reassigned a tenant identifier to another tenant, contrary to its definition (), the new tenant would receive the catalog content of the old one.

Protected Discovery and Client Authentication A Relationship View is disclosed to an Issuer Relationship, not to a client, so its retrieval is not the protected discovery mechanism of , which requires client authentication. Whether to define that mechanism is an open issue (). The Grant Issuer's signature on the catalog access assertion binds a response to the relationship, so client authentication at the token endpoint is required only when the Onboarding Arrangement requires it (, ). When the Onboarding Arrangement does not require client authentication, the catalog access assertion is the only credential the Grant Issuer presents. An assertion that is not DPoP-bound is then a bearer credential until the Resource Authorization Server accepts it. The replay check () prevents reuse of the assertion but not its first use by a party that obtains it, and binding only the catalog access token does not prevent that use. A DPoP-bound catalog access assertion cannot be used without the private key that its cnf claim identifies (). DPoP binding demonstrates possession of a key that the Grant Issuer names under its own signature; it is not client authentication. The assertion's short lifetime, its audience restriction, and TLS further limit the exposure. A Resource Authorization Server weighs the confidentiality of its catalog content when deciding whether its Onboarding Arrangements require client authentication or DPoP-bound catalog access assertions.

Catalog Access Token Disclosure A disclosed catalog access token permits retrieval of the Relationship View until it expires or the relationship ends. The rules for where the Grant Issuer sends the token () limit its disclosure. The token's restriction to the catalog resource and scope () prevents its use at other protected resources of the Resource Authorization Server.

Response Authenticity Relationship View documents are not signed. Their authenticity and integrity rest on TLS server authentication of the catalog resource and on validation of the Resource Authorization Server's metadata (). An attacker able to alter catalog responses can cause an administrator of the Grant Issuer to approve grants that the Resource Authorization Server did not offer, or to deny approval of grants that it did offer. The attacker cannot cause the Resource Authorization Server to accept a grant that its current policy rejects.

Stale Catalogs and Relationship Termination When the Resource Authorization Server narrows what it accepts, a Grant Issuer that has not refreshed issues grants that the Resource Authorization Server rejects after their claims have been disclosed to the client. Such grants affect availability and disclosure, not authorization. After a relationship ends and disclosure stops (), the Grant Issuer can no longer refresh its installed state. The maximum age that it configures bounds how long it continues to issue grants under that state, but the Resource Authorization Server cannot enforce that bound. To stop issuance at a known time, the Resource Authorization Server ends the relationship only after the Grant Issuer has observed the removal of every eligible tenant ().

Revision Integrity and Approval A Resource Authorization Server that changes the normative semantics of an entry without changing its revision causes the Grant Issuer to continue issuing grants under an approval that no longer matches the entry. The Grant Issuer detects such a change only when it holds an earlier copy of the entry with the same revision (). A revision does not bind the Resource Authorization Server to the meaning that the Grant Issuer approved, and a grant issued before a change can be redeemed after it. Requiring an approval for the installed revision () avoids relying on a Grant Issuer's comparison of two revisions to decide that a change only narrows an entry. An incorrect comparison would expand the approved subset.

Tenant Confusion If a Grant Issuer derived a grant's target tenant from the number of Tenant Objects in a Relationship View or the form of an issuer identifier, a grant intended for one tenant could be accepted for another (). An entry obtained for one Issuer Relationship is used only for grants whose issuer and issuer tenant identify that relationship (), so that a catalog disclosed to one issuer tenant does not determine the grants issued for subjects of another.

Tenant Eligibility If a Resource Authorization Server makes a tenant eligible for an Issuer Relationship because an administrator of that tenant configured trust in the Grant Issuer, anyone who controls a tenant at the Resource Authorization Server can add a Tenant Object, with a display of their choosing, to the Grant Issuer's Relationship View. If an administrator of the Grant Issuer approves an entry for that Tenant Object, clients obtain grants that disclose claims to that tenant. A Resource Authorization Server SHOULD make a tenant eligible for an Issuer Relationship only when the Onboarding Arrangement records agreement on the Grant Issuer side, for example by an administrator of the issuer tenant. An administrator of the Grant Issuer identifies a Tenant Object by its tenant_id, not by its display ().

Cross-JWT Confusion A Resource Authorization Server that accepts JWT authorization grants and catalog access assertions at the same token endpoint relies on the typ JOSE header parameter to distinguish them (, ). Without that check, a grant could be presented as a catalog access assertion, or a catalog access assertion as a grant; their claims overlap, and the sub claim of a catalog access assertion is an issuer identifier. When the client identifier assigned to a Grant Issuer equals its issuer identifier, a catalog access assertion also has the iss, sub, and aud values of a client assertion (). One intercepted JWT could then serve as both the grant and the client authentication of a request, and a validator of client assertions that ignores typ does not prevent this. forbids using a catalog access assertion as a client assertion and recommends a separate key for client assertions. describes this class of attack. For the same reason, an entry is used only for grants of its own Grant Profile (), even when the grants of another profile carry similar claims.

External References Entries and authorization details types metadata contain URIs that refer to other servers: the documentation_uri, definition_uri, and schema_uri members, and the resource of each entry, whose Protected Resource Metadata the Grant Issuer requests during composition (). A Resource Authorization Server, or an attacker that can alter catalog responses, chooses these URIs (). A Grant Issuer that dereferences these URIs:

sends no credential obtained through a retrieval protocol (, );
applies the protections against server-side request forgery that it applies to other URLs obtained from external parties; and
treats content retrieved from these URIs, which the retrieval protocol does not authenticate, as untrusted input, not as catalog content.

A Grant Issuer can cache Protected Resource Metadata and limit how many such requests one refresh makes. A Grant Issuer presents display, description, documentation_uri, and definition_uri to administrators as untrusted text. These members can change without a new revision (), so an approval does not cover later changes to them.

Resource Consumption A Relationship View can be large. A Grant Issuer SHOULD limit the size of the responses it accepts, and treats a response that exceeds its limits as an incomplete retrieval (). A Resource Authorization Server can limit the rate at which it accepts catalog access assertions and requests to the catalog endpoint from an Issuer Relationship.

Privacy Considerations The privacy considerations of the Grant Profile of each entry, such as , apply to this specification. A catalog discloses business relationships: which Resource Authorization Server tenants are associated with an issuer tenant, and the names those tenants use. This specification:

limits that disclosure to an authenticated and authorized Issuer Relationship ();
requires that caches not store Relationship View documents (); and
prohibits error responses that reveal other issuers, tenants, or catalogs ().

Because an entry states the claims and subject identifier formats that the Resource Authorization Server requires or accepts (, ), an administrator of the Grant Issuer decides before issuance which claims the Grant Issuer releases and to which Resource Authorization Server tenants. An entry that requires a claim does not cause the Grant Issuer to release it without approval (). The Grant Issuer stores catalog content as configuration, protects it like other relationship-specific configuration, and makes it accessible only to administrators who manage the corresponding Issuer Relationship. Dereferencing a URI contained in a catalog, such as a documentation_uri or definition_uri, can reveal to the server hosting it that the Grant Issuer has a relationship with the Resource Authorization Server. A Grant Issuer can avoid such retrieval or perform it through an intermediary.

IANA Considerations

OAuth Authorization Server Metadata Registry This specification requests registration of the following value in the "OAuth Authorization Server Metadata" registry established by .

Metadata Name:: authorization_grant_catalog_endpoint
Metadata Description:: URL of the OAuth Authorization Grant Catalog endpoint, which is also the resource indicator for requesting a catalog access token
Change Controller:: IETF
Specification Document(s):: of this specification

Media Types Registry This specification requests registration of the following media types in the "Media Types" registry, in the manner described in .

application/oauth-grant-catalog+json

Type name:: application
Subtype name:: oauth-grant-catalog+json
Required parameters:: N/A
Optional parameters:: N/A
Encoding considerations:: binary; a document of this type is a JSON object encoded in UTF-8.
Security considerations:: See of this specification.
Interoperability considerations:: N/A
Published specification:: and of this specification
Applications that use this media type:: Authorization servers that publish an OAuth Authorization Grant Catalog, and authorization servers that retrieve one to issue grants.
Fragment identifier considerations:: The syntax and semantics of fragment identifiers specified for +json in apply.
Additional information:: Deprecated alias names for this type: N/A
: Magic number(s): N/A
: File extension(s): N/A
: Macintosh file type code(s): N/A
Person & email address to contact for further information:: Karl McGuinness, public@karlmcguinness.com
Intended usage:: COMMON
Restrictions on usage:: none
Author:: Karl McGuinness, public@karlmcguinness.com
Change controller:: IETF

application/oauth-grant-catalog-access+jwt

Type name:: application
Subtype name:: oauth-grant-catalog-access+jwt
Required parameters:: N/A
Optional parameters:: N/A
Encoding considerations:: binary; a catalog access assertion is a JWT, which is a sequence of base64url-encoded values separated by period (".") characters.
Security considerations:: See of this specification.
Interoperability considerations:: N/A
Published specification:: of this specification
Applications that use this media type:: Authorization servers that request a catalog access token for an OAuth Authorization Grant Catalog, and authorization servers that issue one.
Fragment identifier considerations:: N/A
Additional information:: Deprecated alias names for this type: N/A
: Magic number(s): N/A
: File extension(s): N/A
: Macintosh file type code(s): N/A
Person & email address to contact for further information:: Karl McGuinness, public@karlmcguinness.com
Intended usage:: COMMON
Restrictions on usage:: none
Author:: Karl McGuinness, public@karlmcguinness.com
Change controller:: IETF

The registration of application/oauth-grant-catalog-access+jwt establishes the typ JOSE header parameter value oauth-grant-catalog-access+jwt used by catalog access assertions ().

OAuth Scope Value No IANA registry exists for OAuth scope values, and this specification requests no registration for authorization_grant_catalog.read ().

References Normative References Identity Assertion JWT Authorization Grant Okta Independent Ping Identity This specification provides a mechanism for an application to use an identity assertion to obtain an access token for a third-party API by coordinating through an identity provider that the downstream Resource Authorization Server already trusts for single sign-on (SSO), using OAuth 2.0 Token Exchange (RFC 8693) and the JWT Profile for OAuth 2.0 Authorization Grants (RFC 7523). This pattern is informally referred to as Cross-App Access (XAA). OAuth 2.0 JWT Authorization Grant with DPoP Binding Okta This specification defines a new OAuth 2.0 authorization grant type for exchanging a JSON Web Token (JWT) assertion that is bound to a key for an access token. To use the assertion, the client must prove possession of that key using the Demonstrating Proof of Possession (DPoP) mechanism. Unlike the JWT bearer grant, a stolen assertion cannot be used by a party that does not hold the private key. Uniform Resource Identifier (URI): Generic Syntax A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] The OAuth 2.0 Authorization Framework The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] The OAuth 2.0 Authorization Framework: Bearer Token Usage This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] The I-JSON Message Format I-JSON (short for "Internet JSON") is a restricted profile of JSON designed to maximize interoperability and increase confidence that software can process it successfully with predictable results. JSON Web Signature (JWS) JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification. JSON Web Token (JWT) JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants This specification provides a framework for the use of assertions with OAuth 2.0 in the form of a new client authentication mechanism and a new authorization grant type. Mechanisms are specified for transporting assertions during interactions with a token endpoint; general processing rules are also specified. The intent of this specification is to provide a common framework for OAuth 2.0 to interwork with other identity systems using assertions and to provide alternative client authentication mechanisms. Note that this specification only defines abstract message flows and processing rules. In order to be implementable, companion specifications are necessary to provide the corresponding concrete instantiations. JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants This specification defines the use of a JSON Web Token (JWT) Bearer Token as a means for requesting an OAuth 2.0 access token as well as for client authentication. Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs) This specification describes how to declare in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular proof-of- possession key and how the recipient can cryptographically confirm proof of possession of the key by the presenter. Being able to prove possession of a key is also sometimes described as the presenter being a holder-of-key. The JavaScript Object Notation (JSON) Data Interchange Format JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. OAuth 2.0 Authorization Server Metadata This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. OAuth 2.0 Token Exchange This specification defines a protocol for an HTTP- and JSON-based Security Token Service (STS) by defining how to request and obtain security tokens from OAuth 2.0 authorization servers, including security tokens employing impersonation and delegation. OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens This document describes OAuth client authentication and certificate-bound access and refresh tokens using mutual Transport Layer Security (TLS) authentication with X.509 certificates. OAuth clients are provided a mechanism for authentication to the authorization server using mutual TLS, based on either self-signed certificates or public key infrastructure (PKI). OAuth authorization servers are provided a mechanism for binding access tokens to a client's mutual-TLS certificate, and OAuth protected resources are provided a method for ensuring that such an access token presented to it was issued to the client presenting the token. Resource Indicators for OAuth 2.0 This document specifies an extension to the OAuth 2.0 Authorization Framework defining request parameters that enable a client to explicitly signal to an authorization server about the identity of the protected resource(s) to which it is requesting access. JSON Web Token Best Current Practices JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security tokens that contain a set of claims that can be signed and/or encrypted. JWTs are being widely used and deployed as a simple security token format in numerous protocols and applications, both in the area of digital identity and in other application areas. This Best Current Practices document updates RFC 7519 to provide actionable guidance leading to secure implementation and deployment of JWTs. HTTP Semantics The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. HTTP Caching The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. This document obsoletes RFC 7234. OAuth 2.0 Rich Authorization Requests This document specifies a new parameter authorization_details that is used to carry fine-grained authorization data in OAuth messages. OAuth 2.0 Demonstrating Proof of Possession (DPoP) This document describes a mechanism for sender-constraining OAuth 2.0 tokens via a proof-of-possession mechanism on the application level. This mechanism allows for the detection of replay attacks with access and refresh tokens. Subject Identifiers for Security Event Tokens Security events communicated within Security Event Tokens may support a variety of identifiers to identify subjects related to the event. This specification formalizes the notion of Subject Identifiers as structured information that describes a subject and named formats that define the syntax and semantics for encoding Subject Identifiers as JSON objects. It also establishes a registry for defining and allocating names for such formats as well as the JSON Web Token (JWT) "sub_id" Claim. Best Current Practice for OAuth 2.0 Security This document describes best current security practice for OAuth 2.0. It updates and extends the threat model and security advice given in RFCs 6749, 6750, and 6819 to incorporate practical experiences gathered since OAuth 2.0 was published and covers new threats relevant due to the broader application of OAuth 2.0. Further, it deprecates some modes of operation that are deemed less secure or even insecure. OAuth 2.0 Protected Resource Metadata This specification defines a metadata format that an OAuth 2.0 client or authorization server can use to obtain the information needed to interact with an OAuth 2.0 protected resource. Updates to OAuth 2.0 JSON Web Token (JWT) Client Authentication and Assertion-Based Authorization Grants Self-Issued Consulting Ping Identity Disney Okta This document updates RFC7521, RFC7522, RFC7523 and RFC9126 with respect to the treatment of audience values in OAuth 2.0 Client Assertion Authentication and Assertion-based Authorization Grants to address a security vulnerability identified in the previous requirements for those audience values in multiple OAuth 2.0 specifications. OpenID Connect Enterprise Extensions 1.0 - draft 01 Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References Media Type Specifications and Registration Procedures This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. Additional Media Type Structured Syntax Suffixes A content media type name sometimes includes partitioned meta- information distinguished by a structured syntax to permit noting an attribute of the media as a suffix to the name. This document defines several structured syntax suffixes for use with media type registrations. In particular, it defines and registers the "+json", "+ber", "+der", "+fastinfoset", "+wbxml" and "+zip" structured syntax suffixes, and provides a media type structured syntax suffix registration form for the "+xml" structured syntax suffix. This document is not an Internet Standards Track specification; it is published for informational purposes. OAuth 2.0 RAR Metadata and Error Remediation Raiffeisen Bank International OAuth 2.0 Rich Authorization Requests (RAR) [RFC9396] standardizes the exchange and processing of authorization details but does not define metadata for describing authorization details types. In addition, no interoperable guidance is offered to clients, to remediate failures by resource servers due to insufficient authorization details. This document addresses this interoperability challenge, allowing clients to dynamically discover metadata instead of relying on out- of-band agreements, as well as standardizes failure signaling including interoperable remediation when insufficient authorization details are the cause of failure. OAuth 2.0 Authority Metadata Raiffeisen Bank International OAuth metadata advertises supported scopes and authorization details types, but advertised scope values and RAR type identifiers do not themselves describe the *authority* associated with them. This specification defines authority metadata extensions for OAuth 2.0 Protected Resource Metadata and OAuth 2.0 Authorization Server Metadata. A protected resource can describe the authority it associates with scopes and Rich Authorization Requests (RAR) types, reusable access requirement profiles, and relationships identifying lower-authority alternatives. An authorization server can publish a simpler description of its local authority vocabulary. This metadata can inform authentication and authorization decisions before token issuance and exchange, as well as support authority attenuation. OAuth Client ID Metadata Document Okta independent This specification defines a mechanism through which an OAuth client can identify itself to authorization servers, without prior dynamic client registration or other existing registration. This is through the usage of a URL as a client_id in an OAuth flow, where the URL refers to a document containing the necessary client metadata, enabling the authorization server to fetch the metadata about the client as needed.

Example Grant Catalog The following Grant Catalog, from a Relationship View whose authorization_server is https://ras.example/, has one entry for the ID-JAG profile (). Every ID-JAG issued using the entry:

is bound to a DPoP key;
contains the scope value messages.read, the email claim, and a sub_id claim in the saml-nameid format; and
can also contain the scope value messages.write and authorization details objects of type message_channel.

Example of Alternative Entries The Resource Authorization Server https://ras.example/ accepts ID-JAGs for the protected resource https://api.example/reports that carry either the scope value reports.read or reports.export, but not both, and requires the department claim only with reports.export. A single entry cannot express either rule (), so the Resource Authorization Server publishes two entries: An administrator of the Grant Issuer approves each entry separately for each Tenant Object, for example reports-read for two Tenant Objects and reports-export for only one of them. An ID-JAG issued using reports-read does not contain the department claim, which that entry does not list (). No ID-JAG contains both scope values, because each grant is issued using exactly one entry ().

Example Approval Lifecycle An approval of the entry in for the Tenant Object customer-acme-eu changes as the Relationship View changes:

The Grant Issuer installs a Relationship View in which customer-acme-eu references the Grant Catalog standard, whose entry messages-api-id-jag has the revision 5. An administrator approves the scope value messages.read for that entry, and the Grant Issuer issues ID-JAGs with that scope value.
A refresh fails with a transport error. The Grant Issuer installs nothing and continues to issue ID-JAGs under the installed state, within the maximum age it has configured ().
The Resource Authorization Server removes customer-acme-eu from the Issuer Relationship. The next refresh retrieves a Relationship View without it, and the Grant Issuer suspends issuance for customer-acme-eu ().
The Resource Authorization Server restores customer-acme-eu with the same grant_catalog, and the Grant Catalog still contains revision 5 of the entry. The approval applies again without new approval ().
The Resource Authorization Server adds the optional scope value messages.archive to the entry and changes its revision to 6. The Grant Issuer stops issuing ID-JAGs under the approval for revision 5, even though the change does not affect messages.read ().
An administrator reviews revision 6 and approves messages.read again. The Grant Issuer resumes issuing ID-JAGs with that scope value.

Design Rationale

Data model separate from retrieval:

Deployments differ in the administrative relationship that already exists between a Grant Issuer and a Resource Authorization Server. Objects defined independently of retrieval let any retrieval protocol deliver identical objects to the same Grant Issuer policy.

Complete documents and no merge rules:

Because each Tenant Object references one Grant Catalog that is neither paged nor merged (, ), a Grant Issuer determines what a tenant is offered from one object and cannot mistake a partial retrieval for a complete one.

One response per Relationship View:

One complete response gives the Grant Issuer one consistent state without a manifest of versions, and makes a withdrawal the absence of an object from a validated response. Compression and conditional requests () offset the cost of retransmitting the whole view until deployments show a need for incremental retrieval.

Authority in public metadata, eligibility in the catalog:

What a scope value or authorization details type authorizes is the same for every Issuer Relationship, so it belongs in public metadata, such as authority metadata . Which scope values and authorization details types a relationship may use is specific to the relationship, so it belongs in the catalog. Entries identify items by the protocol values that authority metadata uses, so the two compose without a mapping.

Envelope without alternatives:

An Authorization Envelope that is a product of independent selections () can be evaluated without a rule language, and a Grant Issuer cannot misread a rule that does not exist.

Opaque revision identifiers:

The format prescribes no canonicalization and leaves the generation of revision values to the Resource Authorization Server, which can use a counter or a digest of the normative semantics. Because a revision is tied to the normative semantics (), the Grant Issuer retains approvals across changes to presentation text.

Optional claims listed explicitly:

Exempting some optional claims, such as an email address, from listing () would leave their release outside the administrator's approval, with no principled line between them and related claims, such as one that states whether that email address is verified.

One resource per grant:

Limiting a grant to one protected resource () avoids rules for how scope values and authorization details apply across resources, and keeps each approval about one resource.

Signed relationship assertion:

Stating the Issuer Relationship under the signature of the keys that sign the Grant Issuer's grants ():

gives every Resource Authorization Server the same provenance for the relationship;
reuses the trust that each Resource Authorization Server already places in the issuer; and
binds catalog access to the identity that issues the grants the catalog describes.

Authorizing a tenant selector against the relationships permitted to a Grant Issuer authenticated as a client would instead leave each Resource Authorization Server to define its own selector and mapping, and a client credential authorized for many issuer tenants would carry the same broad authority as a shared signing key ().

No client inventory:

Client identifiers can be shared across trust domains () or established by registration, and a client inventory () would require additional disclosure policy and synchronization of client registration state. A view for one identified client that the Issuer Relationship is authorized to inspect would disclose no inventory, and could be defined later.

Open Issues RFC Editor: please remove this appendix before publication.

Reapproval: whether issuance can continue under an existing approval when an entry changes to a revision whose Authorization Envelope still contains the approved subset, and what a Resource Authorization Server would publish to make that safe (, ). Tracked as issue #12.
Client-facing discovery: whether to define the protected discovery mechanism that permits, through which an application client retrieves the entries that apply to it. A view of whole entries cannot express a restriction for one client that is narrower than an entry. Tracked as issue #15.
Freshness and termination: whether to require a maximum age, or let the Resource Authorization Server publish one, so that it has a deadline after which a Grant Issuer stops issuing under state it cannot refresh (, ). Tracked as issue #16.
Must-understand extensions: a mechanism, to be added before the format stabilizes, by which an entry marks extension members that a Grant Issuer must implement, so that restrictive extensions need no distinct Grant Profile identifier (); and whether every extension is to preserve the principles in . Tracked as issue #19.

Acknowledgments This specification builds on the Identity Assertion JWT Authorization Grant and on the JWT authorization grant .

Document History RFC Editor: please remove this appendix before publication. -01

Editorial restructuring; no normative changes.

-00

Initial version.