OAuth Authorization Grant Catalog

1.1. 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 (Figure 2). 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.¶

Appendix B 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 (Section 9.1, Section 9.2).¶

1.2. Relationship to Other Metadata

Each source of information used to issue a grant answers a different question:¶

Section 5.2, Section 5.3, and Section 5.6 define how a Grant Issuer combines these sources.¶

1.3. 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 [RFC7523] 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 (Section 4) has an Authorization Envelope (Section 4.6) and processing rules (Section 5) stated in terms of the inputs a grant conveys.¶

• Each Grant Profile Definition specifies how grants of its Grant Profile convey those inputs (Section 8.1). This specification provides one only for ID-JAG (Section 7).¶

• A retrieval protocol authenticates the relationship and delivers the catalog (Section 6). 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 (Section 5.4.1).¶

• Constraints on the values within an authorization details object (Section 4.5.3).¶

• Paging, change notification, delta retrieval, and push delivery of catalogs.¶

• Automatic reconciliation of Grant Issuer policy with a changed entry (Section 5.5).¶

• A mechanism by which a client discovers whether a grant from a particular Grant Issuer would be accepted (Section 9.7 of [ID-JAG]), which is an open issue (Appendix "Open Issues").¶

• Establishment of an Onboarding Arrangement (Section 6.2).¶

4.1. Common Conventions

Every object defined in this section is a JSON object [RFC8259]. A document that carries these objects MUST conform to I-JSON [RFC7493]. A Grant Issuer MUST ignore members it does not understand (Section 8).¶

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 (Section 6.2.1 of [RFC3986]). The length limit bounds the Grant Catalog and entry identifiers that a Grant Issuer retains with each approval (Section 5.5). 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 (Section 6.2.1 of [RFC3986]).¶

4.2. Relationship View

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

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 (Section 6.1).¶

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 (Section 5.1) 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.¶

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

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 (Section 7.1).¶

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 (Section 4.6, Section 5.4).¶

Several Tenant Objects can reference the same Grant Catalog. Tenant Objects for tenants that differ in any input that an entry governs (Section 4.6) reference different Grant Catalogs. A Tenant Object has no default Grant Catalog, and Grant Catalogs have no inheritance, partial overrides, or merge rules.¶

Section 5.5 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:¶

{
  "tenant_id": "customer-acme",
  "display": "Acme",
  "grant_catalog": "read-only"
}

4.4. Grant Catalog

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

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

4.5. Entry

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

The value of resource is an absolute URI [RFC3986] and MUST NOT contain a fragment component.¶

Section 4.6 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 [RFC7523].¶

A Grant Catalog can contain entries for several resources, and several entries can name the same resource when they describe different grants (Section 4.6). A client that needs access to several resources obtains a separate grant for each.¶

4.6. 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 Table 14. Grant Issuer policy and the runtime request narrow the Authorization Envelope (Section 5.3).¶

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:¶

1. The grant conveys, as its only audience, the authorization_server of the Relationship View that contains the Grant Catalog.¶

2. If the Tenant Object contains tenant_id, the grant conveys that value as its target tenant. Otherwise, the grant conveys no target tenant.¶

3. The grant conveys the entry's resource as its only protected resource.¶

4. For each input in Table 14:¶

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

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 (Appendix B). 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.¶

4.7. 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 (Section 8).¶

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 (Section 5.1). Grant Catalog identifiers are unique only within a Relationship View (Section 4.1), 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 (Section 5.5). The retrieval protocol handles caching of representations.¶

5.1. Validating a Relationship View

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

1. 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 (Section 6.2.1 of [RFC3986]).¶

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

3. Every document conforms to I-JSON [RFC7493]. 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 Section 4.1.¶

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

5. At most one Tenant Object omits tenant_id, and no two Tenant Objects have the same tenant_id.¶

6. 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 (Section 4.7).¶

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 (Section 5.5).¶

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:¶

1. The Grant Issuer does not implement a Grant Profile Definition for the Grant Profile identified by profile.¶

2. A member of the entry other than its id, or a member of an object within the entry, does not satisfy its definition in Section 4.5 or Section 4.1: 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.¶

3. The entry contains a member for an input (Section 4.6) that its Grant Profile Definition states the Grant Profile cannot convey (Section 8.1).¶

4. The entry conflicts with public metadata (Section 5.2).¶

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

5.2. 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:¶

1. Retrieve and validate the Resource Authorization Server's Authorization Server Metadata (Section 3.3 of [RFC8414]), and verify that its issuer identifier is identical to the authorization_server of the Relationship View.¶

2. If the entry's resource is a URL that uses the https scheme (Section 1.2 of [RFC9728]), request its Protected Resource Metadata using the oauth-protected-resource well-known URI suffix (Section 3 of [RFC9728]); otherwise, this step has no effect. If the response has HTTP status code 200 (OK), validate the metadata as specified in Section 3.3 of [RFC9728]. Any other response, or no response, leaves this step without effect, because publishing Protected Resource Metadata is optional.¶

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

4. Perform the checks that the Grant Profile Definition specifies, such as checks of grant_types_supported (Section 7.3).¶

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 (Section 4.6), 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 (Section 2 of [RFC8414], Section 2 of [RFC9728]), and an authorization_servers member of Protected Resource Metadata that omits the Resource Authorization Server's issuer identifier is not a conflict (Section 2 of [RFC9728]).¶

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

5.3. 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 Section 5.4 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:¶

Publicly advertised scopes:  messages.read, messages.write,
                             messages.admin
Catalog entry:               messages.read, messages.write
Approved by policy:          messages.read
Requested by the client:     messages.read, messages.write
Issued in the grant:         messages.read

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

5.4. 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 (Section 5.3). 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 (Section 8.1). 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 (Section 4.6).¶

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 (Section 8.1).¶

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:¶

1. The Relationship View that contains them is installed (Section 5.5).¶

2. The entry is usable for issuance (Section 5.1).¶

3. If the Tenant Object contains tenant_id, the entry's Grant Profile can convey a target tenant (Section 4.3).¶

4. An approval for the entry and the Tenant Object applies (Section 5.5).¶

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

5.5. 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 (Section 5.1), or in which the retrieval protocol confirms the installed one (Section 6.8).¶

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 Table 16 after each retrieval.¶

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 (Section 9.8). Whether to relax these rules is an open issue (Appendix "Open Issues").¶

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 (Section 9.7).¶

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

5.6. Optional Supporting Metadata

A Grant Issuer can use other metadata to help administrators understand entries: authorization details types metadata [RAR-METADATA] describes the structure of an authorization details type, and authority metadata [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 ([RAR-METADATA]), documentation_uri, or definition_uri.¶

6.1. Relationship Identity

An Issuer Relationship is identified by the Grant Issuer's issuer identifier [RFC8414] and, when that issuer is multi-tenant, an issuer tenant identifier. An issuer tenant identifier is a tenant identifier (Section 2) 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 [OpenID.Enterprise], the value is the stable, issuer-unique form of that claim. The values personal and organization, which Section 2.2 of [OpenID.Enterprise] 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.¶

6.2. Relationship Authorization

An Onboarding Arrangement (Section 2) 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.¶

6.3. Authorization Server Metadata

This specification defines the following Authorization Server Metadata [RFC8414] member for the OAuth retrieval protocol:¶

authorization_grant_catalog_endpoint:

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

• uses the https scheme;¶

• contains no fragment component; and¶

• is the resource indicator (Section 2 of [RFC8707]) 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:¶

{
  "issuer": "https://ras.example/",
  "token_endpoint": "https://ras.example/oauth2/token",
  "jwks_uri": "https://ras.example/oauth2/jwks",
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "urn:ietf:params:oauth:grant-type:jwt-dpop"
  ],
  "authorization_grant_profiles_supported": [
    "urn:ietf:params:oauth:grant-profile:id-jag"
  ],
  "token_endpoint_auth_methods_supported": ["private_key_jwt"],
  "dpop_signing_alg_values_supported": ["ES256"],
  "authorization_grant_catalog_endpoint":
    "https://ras.example/oauth2/grant-catalog"
}

6.4. 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 [RFC7523] to obtain a catalog access token. The assertion is not a grant in the sense of this specification (Section 2).¶

A catalog access assertion is a JWS [RFC7515] with the following JOSE header parameters:¶

typ:

REQUIRED. The value oauth-grant-catalog-access+jwt (Section 3.11 of [RFC8725]).¶

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 (Section 6.1).¶

sub:

REQUIRED. The same value as iss. Section 3 of [RFC7523] 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 Section 3 of [RFC7523], 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 (Section 6.1), conveyed in the tenant claim [OpenID.Enterprise].¶

iat:

REQUIRED. The time at which the assertion was issued (Section 4.1.6 of [RFC7519]).¶

exp:

REQUIRED. The expiration time of the assertion (Section 4.1.4 of [RFC7519]). The value MUST NOT be more than 300 seconds after the value of iat.¶

jti:

REQUIRED. A unique identifier for the assertion (Section 4.1.7 of [RFC7519]).¶

cnf:

OPTIONAL. A confirmation claim that binds the assertion to a DPoP key that the Grant Issuer controls, as specified in Section 3 of [JWT-DPOP]. 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:¶

{
  "typ": "oauth-grant-catalog-access+jwt",
  "alg": "ES256",
  "kid": "issuer-key-1"
}

{
  "iss": "https://idp.example/",
  "sub": "https://idp.example/",
  "aud": "https://ras.example/",
  "tenant": "acme-workforce",
  "iat": 1788897600,
  "exp": 1788897720,
  "jti": "catalog-request-123"
}

6.5. Catalog Access Token Request

The Grant Issuer requests a catalog access token by sending a token request (Section 2.1 of [RFC7523]) 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 (Section 4.1 of [JWT-DPOP]).¶

assertion:

REQUIRED. The catalog access assertion.¶

resource:

REQUIRED. The value of the authorization_grant_catalog_endpoint metadata member (Section 2 of [RFC8707]).¶

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 (Section 3.1 of [RFC7523]), 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 (Section 2.2 of [RFC7523]). 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 ([RFC7523BIS]).¶

• 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 (Section 3.12 of [RFC8725]).¶

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):¶

POST /oauth2/token HTTP/1.1
Host: ras.example
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJ0eXAiOiJvYXV0aC1ncmFudC1jYXRhbG9nLWFjY2Vzcytqd3Qi...
&resource=https%3A%2F%2Fras.example%2Foauth2%2Fgrant-catalog
&scope=authorization_grant_catalog.read
&client_id=https%3A%2F%2Fidp.example%2F
&client_assertion_type=
 urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImNsaWVudC1rZXktMSJ9...

The Resource Authorization Server processes the request as follows:¶

1. If the grant type is urn:ietf:params:oauth:grant-type:jwt-dpop, it validates the DPoP proof (Section 5 of [JWT-DPOP]) before validating the assertion, so that a request rejected for its proof or nonce does not consume the assertion's jti (Section 5.1 of [JWT-DPOP]).¶

2. It validates the catalog access assertion (Section 6.4.1).¶

3. 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 (Section 5 of [JWT-DPOP]) 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 (Section 7.1 of [JWT-DPOP]), and that the Onboarding Arrangement does not require DPoP-bound catalog access assertions.¶

4. It verifies that the resource parameter is identical to its authorization_grant_catalog_endpoint metadata value.¶

5. It verifies that the scope parameter is authorization_grant_catalog.read.¶

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

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

6.6. Catalog Access Token Response

If the request is valid, the Resource Authorization Server responds as specified in Section 5.1 of [RFC6749]. 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 Section 6.5.¶

The following is an example of a catalog access token response:¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "authorization_grant_catalog.read"
}

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 (Section 6 of [JWT-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 ([RFC9449]) or a certificate-bound catalog access token ([RFC8705]) when the Grant Issuer uses those mechanisms.¶

6.7. 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 Section 2.1 of [RFC6750] or, for a DPoP-bound token, Section 7.1 of [RFC9449]. The Resource Authorization Server verifies the DPoP proof for a DPoP-bound token and rejects a DPoP-bound token presented as a bearer token (Section 7.2 of [RFC9449]).¶

The Grant Issuer MUST send a catalog access token only to the authorization_grant_catalog_endpoint URL from Authorization Server Metadata it has validated (Section 3.3 of [RFC8414]), 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 (Section 5.5).¶

The Resource Authorization Server determines the Relationship View from the Issuer Relationship associated with the catalog access token (Section 6.2). It responds with HTTP status code 200 (OK) and a Relationship View document of media type application/oauth-grant-catalog+json (Section 11.2), whose content is the Relationship View (Section 4.2). 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 Section 5.1, and treats a response of any other media type as an incomplete retrieval (Section 5.5).¶

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; Appendix A shows the Grant Catalog standard in full:¶

GET /oauth2/grant-catalog HTTP/1.1
Host: ras.example
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
If-None-Match: "view-91b6c4"
Accept-Encoding: gzip, br

HTTP/1.1 200 OK
Content-Type: application/oauth-grant-catalog+json
Cache-Control: no-store
ETag: "view-a24f91"

{
  "authorization_server": "https://ras.example/",
  "grant_issuer": {
    "issuer": "https://idp.example/",
    "tenant": "acme-workforce"
  },
  "tenants": [
    {
      "tenant_id": "customer-acme",
      "display": "Acme",
      "grant_catalog": "read-only"
    },
    {
      "tenant_id": "customer-acme-eu",
      "display": "Acme Europe",
      "grant_catalog": "standard"
    }
  ],
  "grant_catalogs": [
    {
      "id": "read-only",
      "entries": [ ... ]
    },
    {
      "id": "standard",
      "display": "Standard API access",
      "entries": [ ... ]
    }
  ]
}

6.8. Caching and Refresh

The Resource Authorization Server SHOULD include a strong entity tag (Section 8.8.3 of [RFC9110]) in each Relationship View document response, and SHOULD support conditional requests using If-None-Match (Section 13.1.2 of [RFC9110]).¶

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 (Section 15.4.5 of [RFC9110]) confirms the installed Relationship View and is a complete retrieval (Section 5.5).¶

A Relationship View document is specific to an Issuer Relationship. The Resource Authorization Server MUST include Cache-Control: no-store (Section 5.2.2.5 of [RFC9111]) 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 (Section 12.5.3 of [RFC9110]), and the Resource Authorization Server SHOULD compress responses when the Grant Issuer supports a content coding.¶

6.9. Error Responses

The token endpoint returns errors as specified in Section 5.2 of [RFC6749] and, for the urn:ietf:params:oauth:grant-type:jwt-dpop grant type, Section 5 of [JWT-DPOP]. 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 (Section 2 of [RFC8707]), 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 Section 3 of [RFC6750], or Section 7.1 of [RFC9449] 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 (Section 3.1 of [RFC6750]).¶

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

7.1. Representation of Inputs

An ID-JAG conveys its issuer, its issuer tenant (Section 5.4), and the values that Section 4.6 constrains as follows.¶

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 (Section 6.1 of [RFC9449]), as specified in Section 3 of [JWT-DPOP].¶

mtls:

The x5t#S256 confirmation member, containing the SHA-256 thumbprint of the client's X.509 certificate (Section 3.1 of [RFC8705]).¶

7.2. 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 (Section 4.3 of [RFC8693]), and act (Section 4.1 of [RFC8693]). The Grant Profile, not an entry, determines whether a grant conveys a client identifier or an actor. The other claims that Section 3.1 of [ID-JAG] defines (auth_time, acr, amr, aud_sub, and email) are Catalog-Governed Claims.¶

An ID-JAG has the typ value oauth-id-jag+jwt (Section 3.1 of [ID-JAG]); see Section 9.11.¶

7.3. 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 (Section 7.2 of [ID-JAG]). For each such entry, the Grant Issuer performs the following checks in step 4 of Section 5.2, interpreting grant_types_supported with the default value defined in Section 2 of [RFC8414]:¶

• 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 (Section 4.1 of [JWT-DPOP]).¶

8.1. Grant Profile Definitions

A Grant Profile Definition specifies the following:¶

1. The Grant Profile identifier used in the profile member of an entry.¶

2. How a grant of the profile conveys each input in Section 4.6. 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.¶

3. How a grant of the profile identifies its issuer and, for a multi-tenant issuer, its issuer tenant (Section 5.4).¶

4. The reserved claim names of the profile, including the claims the profile requires in every grant (Section 4.5.4), and the namespace of the claim member.¶

5. 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 (Section 5.4).¶

6. The composition checks against public metadata that apply to the profile, such as checks of the grant types used to redeem its grants (Section 5.2).¶

7. 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 (Section 5.4).¶

8. Any rule of the Grant Profile that catalog use narrows, such as making an OPTIONAL element required.¶

9. For a profile whose grants identify the client by its client identifier at the Resource Authorization Server, how the Grant Issuer obtains that identifier (Section 5.4.1).¶

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

9.1. Catalog Is Not an Authorization Decision

A catalog neither authorizes a request (Section 1) 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.¶

9.2. 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 (Section 5.6) but does not bind the protected resource.¶

9.3. 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 (Section 6.2).¶

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 (Section 2), the new tenant would receive the catalog content of the old one.¶

9.4. 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 Section 9.7 of [ID-JAG], which requires client authentication. Whether to define that mechanism is an open issue (Appendix "Open Issues").¶

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 (Section 6.2, Section 6.5).¶

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 (Section 6.4.1) 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 (Section 6.5). 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.¶

9.5. 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 (Section 6.7) limit its disclosure. The token's restriction to the catalog resource and scope (Section 6.6) prevents its use at other protected resources of the Resource Authorization Server.¶

9.6. 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 (Section 3.3 of [RFC8414]).¶

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

9.7. 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 (Section 6.2), 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 (Section 5.5).¶

9.8. 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 (Section 5.1).¶

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 (Section 5.5) 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.¶

9.9. 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 (Section 5.4).¶

An entry obtained for one Issuer Relationship is used only for grants whose issuer and issuer tenant identify that relationship (Section 5.4), so that a catalog disclosed to one issuer tenant does not determine the grants issued for subjects of another.¶

9.10. 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 (Section 4.1).¶

9.11. 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 (Section 6.4.1, Section 8.1). 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 (Section 3 of [RFC7523]). 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.¶

Section 6.5 forbids using a catalog access assertion as a client assertion and recommends a separate key for client assertions. Section 2.8 of [RFC8725] describes this class of attack. For the same reason, an entry is used only for grants of its own Grant Profile (Section 5.4), even when the grants of another profile carry similar claims.¶

9.12. 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 (Section 5.2). A Resource Authorization Server, or an attacker that can alter catalog responses, chooses these URIs (Section 7.7 of [RFC9728]).¶

A Grant Issuer that dereferences these URIs:¶

• sends no credential obtained through a retrieval protocol (Section 5.6, Section 6.7);¶

• 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 (Section 4.7), so an approval does not cover later changes to them.¶

9.13. 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 (Section 5.5). 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.¶

11.1. OAuth Authorization Server Metadata Registry

This specification requests registration of the following value in the "OAuth Authorization Server Metadata" registry established by [RFC8414].¶

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):

Section 6.3 of this specification¶

11.2. Media Types Registry

This specification requests registration of the following media types in the "Media Types" registry, in the manner described in [RFC6838].¶

11.3. OAuth Scope Value

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

12.1. Normative References

[ID-JAG]

Parecki, A., McGuinness, K., and B. Campbell, "Identity Assertion JWT Authorization Grant", Work in Progress, Internet-Draft, draft-ietf-oauth-identity-assertion-authz-grant-06, 30 October 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-identity-assertion-authz-grant-06>.

[JWT-DPOP]

Parecki, A., "OAuth 2.0 JWT Authorization Grant with DPoP Binding", Work in Progress, Internet-Draft, draft-parecki-oauth-jwt-dpop-grant-02, 30 October 2026, <https://datatracker.ietf.org/doc/html/draft-parecki-oauth-jwt-dpop-grant-02>.

[OpenID.Enterprise]

Hardt, D. and K. McGuinness, "OpenID Connect Enterprise Extensions 1.0 - draft 01", September 2025, <https://openid.net/specs/openid-connect-enterprise-extensions-1_0-01.html>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/rfc/rfc3986>.

[RFC6749]

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

[RFC6750]

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, <https://www.rfc-editor.org/rfc/rfc6750>.

[RFC7493]

Bray, T., Ed., "The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015, <https://www.rfc-editor.org/rfc/rfc7493>.

[RFC7515]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, <https://www.rfc-editor.org/rfc/rfc7515>.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/rfc/rfc7519>.

[RFC7521]

Campbell, B., Mortimore, C., Jones, M., and Y. Goland, "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, May 2015, <https://www.rfc-editor.org/rfc/rfc7521>.

[RFC7523]

Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 2015, <https://www.rfc-editor.org/rfc/rfc7523>.

[RFC7523BIS]

Jones, M. B., Campbell, B., Mortimore, C., and F. Skokan, "Updates to OAuth 2.0 JSON Web Token (JWT) Client Authentication and Assertion-Based Authorization Grants", Work in Progress, Internet-Draft, draft-ietf-oauth-rfc7523bis-11, 28 April 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rfc7523bis-11>.

[RFC7800]

Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)", RFC 7800, DOI 10.17487/RFC7800, April 2016, <https://www.rfc-editor.org/rfc/rfc7800>.

[RFC8174]

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

[RFC8259]

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

[RFC8414]

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

[RFC8693]

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

[RFC8705]

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

[RFC8707]

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

[RFC8725]

Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, February 2020, <https://www.rfc-editor.org/rfc/rfc8725>.

[RFC9110]

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

[RFC9111]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, June 2022, <https://www.rfc-editor.org/rfc/rfc9111>.

[RFC9396]

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

[RFC9449]

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

[RFC9493]

Backman, A., Ed., Scurtescu, M., and P. Jain, "Subject Identifiers for Security Event Tokens", RFC 9493, DOI 10.17487/RFC9493, December 2023, <https://www.rfc-editor.org/rfc/rfc9493>.

[RFC9700]

Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "Best Current Practice for OAuth 2.0 Security", BCP 240, RFC 9700, DOI 10.17487/RFC9700, January 2025, <https://www.rfc-editor.org/rfc/rfc9700>.

[RFC9728]

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

12.2. Informative References

[AUTHORITY-METADATA]

Zehavi, Y., "OAuth 2.0 Authority Metadata", Work in Progress, Internet-Draft, draft-zehavi-oauth-authority-metadata-00, 11 October 2026, <https://datatracker.ietf.org/doc/html/draft-zehavi-oauth-authority-metadata-00>.

[CIMD]

Parecki, A. and E. Smith, "OAuth Client ID Metadata Document", Work in Progress, Internet-Draft, draft-ietf-oauth-client-id-metadata-document-03, 2 November 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-03>.

[RAR-METADATA]

Zehavi, Y., "OAuth 2.0 RAR Metadata and Error Remediation", Work in Progress, Internet-Draft, draft-ietf-oauth-rar-metadata-remediation-00, 23 August 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar-metadata-remediation-00>.

[RFC6838]

Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, <https://www.rfc-editor.org/rfc/rfc6838>.

[RFC6839]

Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", RFC 6839, DOI 10.17487/RFC6839, January 2013, <https://www.rfc-editor.org/rfc/rfc6839>.