Complexity of Access Token Privileges Introduced by Grant Management

Introduction

RFC 8707 Resource Indicators for OAuth 2.0 (published in February, 2021) introduced the resource parameter in order to tie “resources” to an access token as audience.

Grant Management for OAuth 2.0 (whose first implementer’s draft was published in July, 2021) assumes that “scopes” and “resources” are managed combinedly.

These specifications have made internal and external representations of access token privileges complex. Consequently, logic of access token validation has become complex, too.

This article explains the complexity and the need to extend the format of introspection response so that privileges of access token can be expressed properly.

Combinedly or Independently?

An access token generated by an authorization request including scope=readand resource=https://rs.example.com/r1 will hold information as shown below.

"scope": "read",
"aud": [ "https://rs.example.com/r1" ],

It is not necessarily obvious whether “scopes” and “resources” (audience) should be treated combinedly (scopes && resources) or independently (scopes || resources). For example, it is obvious that API access to https://rs.example.com/r1 with read operation is allowed, but it is not necessarily obvious whether (a) API access to https://rs.example.com/r1 with arbitrary operations and (b) API access to arbitrary resources with read operation are allowed or not.

However, the example of grant management query response shown in “6.4. Query Status of a Grant” of “Grant Management for OAuth 2.0” makes it clear that scopes and resources should be treated combinedly.

(You may find "resources" in the published specification, but it’s a typo. The correct claim name is "resource". See FAPI Issue 444.)

Introspection Response Format

The following is an example of series of authorization requests with grant management.

1. Input (authorization request): grant_management_action=create & scope=s1 & resource=https://rs.example.com/r1 / Output (token response): grant_id=g1 & access_token=a1
2. Input (authorization request): grant_management_action=update & scope=s2 & resource=https://rs.example.com/r2 & grant_id=g1 / Output (token response): grant_id=g1 & access_token=a2

The first request generates a new grant ID (g1), and the second request uses the grant ID with grant_management_action=update. After these requests, a grant management query about g1 will receive a response shown below.

{
  "scopes": [
    { "scope":"s1", "resource":["https://rs.example.com/r1"] },
    { "scope":"s2", "resource":["https://rs.example.com/r2"] }
  ]
}

It is expected that the access token (a2) created by the second request has the same privileges as the grant (g1) does. If so, how should the privileges of the access token be described in an introspection response (RFC 7662)?

If we have to describe the privileges with existing standard claims (i.e. scope and aud) only, an introspection response will have to look like below.

"scope": "s1 s2",
"aud": [
  "https://rs.example.com/r1",
  "https://rs.example.com/r2"
]

However, the representation breaks relations between scopes and resources by merging them flatly and thus makes it impossible for a resource server to perform access token validation properly.

Therefore, a new means needs to be invented whereby to describe the privileges without breaking relations between scopes and resources.

Below is an example of new means which uses a newly-introduced grant claim.

"scope": "s2",
"aud": [ "https://rs.example.com/r2" ],
"grant": [
  { "scope":"s1", "resource":["https://rs.example.com/r1"] }
]

The name of the new claim (grant) is not so important. What is more important is the structure whereby to describe the privileges. In any case, a consensus on claim name and structure has to be reached for interoperability.

Note: In the example above, scope and aud represent the scopes and resources that were directly specified in the authorization request through which the access token (a2) was issued. The content of grant represents the privileges inherited from the grant (g1), which was the snapshot of the privileges that the grant held at the timing of issuance of the access token.

Token Response Format

The token response format will encounter a similar problem because privileges accumulated by grant_management_action=update cannot be expressed by the scope response parameter.

Possible solutions would be:

1. Introduce a new claim such as grant.
2. Give up embedding information about the inherited privileges in a token response and recommend use of the grant management API.

JWT Access Token Format

The format of JWT Access Token (draft-ietf-oauth-access-token-jwt) also will have to deal with the same issue to support Grant Management.

Discussion

This topic is discussed in the Financial-grade API Working Group of the OpenID Foundation as an issue of Grant Management. Visit “FAPI Issue 455: Impact of grant_management_action=update on AT implementation and introspection” if you are interested.