Grant Management for OAuth 2.0

Introduction

is a technical specification that enables to manage privileges granted to client applications in a finer-grained way than pre-existing standard specifications.

A reason to pay attention to the specification is that it is positioned as a part of Financial-grade API 2.0, the successor of Financial-grade API 1.0 which is now the de facto standard for high API security and has been adopted by ecosystems such as , and . Grant Management is mentioned also in the of GAIN (Global Assured Identity Network), which is a project to build a global high-trust digital identity network over the Internet.

This article is a partial summary of a technical document () which is published on the website of . See the document directly for further details about the specification, related discussion and an “implementation”.

Concept of Grant

In OAuth 2.0, a user grants some privileges to a client application. As a result, an access token is issued from an authorization server to the client application.

The process of access token issuance may be repeated. Privileges requested by the client application through the second and subsequent processes may be different from the ones requested through the first process. In this way, privileges granted to the client application accumulate.

The Grant Management specification calls the set of accumulated privileges “grant” and defines means whereby to query about, merge and revoke a grant.

Request and Response Parameters

A grant ID is assigned to each grant in order to make grants manageable. A grant ID is issued together with an access token from the token endpoint. To request an authorization server to issue a grant ID, a client application includes a new authorization request parameter grant_management_action in an authorization request with a value create. The issued grant ID is included in the token response as the value of a new token response parameter grant_id.

To accumulate privileges, the client application includes grant_management_action=merge in the next authorization request with a new authorization request parameter grant_id whose value is a previously-issued grant ID.

The grant management action update was renamed to merge by . The change takes effect from the second Implementer's Draft of Grant Management for OAuth 2.0.

In addition to create and update, replace is defined as a value for the grant_management_action request parameter. The replace action replaces accumulated privileges tied to the specified grant ID with new ones that are granted only through the request including grant_management_action=replace. The previous privileges are revoked.

When the value of the grant_management_action request parameter is merge or replace, the grant_id request parameter is mandatory.

Grant Management Endpoint

The Grant Management specification defines a new endpoint called “grant management endpoint”. The endpoint enables to query about and revoke a grant. To access the endpoint, a pre-issued access token is necessary.

Query

  • HTTP Method — GET
  • URL — {endpoint}/{grant-id}
  • Protection — Access token having the grant_management_query scope
  • Status Code on Success — 200 OK
  • Response Content-Type — application/json
  • Response Format — See “

The following is an example response excerpted from “” of the Grant Management specification.

The JSON in the response body shows accumulated privileges of a grant. It has "scopes", "claims" and "authorization_details" as top-level properties.

scopes

The value of "scopes" is an array of combinations of scopes and resources (hereinafter referred to as “scope-resource clusters”). Each cluster consists of "scope" and "resource". The value of "scope" is a space-delimited scopes. The value of "resource" is an array of resources. Values of the scopes and resources are ones specified by the scope request parameter ( / ) and resource request parameters ( / ).

The structure of "scopes" makes implementers realize that scope-resource clusters should be managed separately even if privileges are accumulated through repeated merge operations. If contents of clusters were mixed through merge operations, scopes might be coupled with unintended resources. The right-bottom JSON in the figure below indicates that the change scope is combined with the https://payment.example.com resource if contents of clusters are mixed, which can cause a serious security incident such as theft of money.

claims

The value of "claims" is an array of “claims” that the user has consented for the client application to know. Put simply, “claims” here are user attributes. Some user attributes such as family_name and phone_number are defined as standard claims in of .

A client application can request claims by including special scopes (profile, email, address and phone) in the scope request parameter ( / ) and/or by using the claims request parameter ( / ).

authorization_details

The value of "authorization_details" is an array of pieces of detailed information about authorization. The pieces of information are ones specified by the authorization_details request parameter which is defined in “” (RAR).

Before RAR was developed, authorization server implementations had to introduce a nonstandard request parameter or use the scope request parameter in a nonstandard way in order to attach detailed information to an authorization request. The latter approach is called “parameterized scope” or “dynamic scope” which embeds a dynamic value in a scope string. For example, defines “Dynamic Consent Scope” () whose format is consent:{ConsentID} where consent: is a fixed-string prefix and {ConsentID} is the dynamic part (e.g. consent:urn:bancoex:C1DD33123).

The problem of the dynamic scope approach is that it is not standardized and interoperability among implementations is hopeless due to its intrinsically variant formats. RAR was developed to solve the problem and is positioned as a part of Financial-grade API 2.0.

Revoke

  • HTTP Method — DELETE
  • URL — {endpoint}/{grant-id}
  • Protection — Access token having the grant_management_revoke scope
  • Status Code on Success — 204 No Content

The Grant Management specification states that all refresh tokens associated with the revoked grant must be revoked and all access tokens associated with the revoked grant should be revoked.

NOTE: Implementations of access token and refresh token differ among authorization server implementations. Especially, it should be noted that self-contained access tokens, typically JWT access tokens, cannot be revoked unless the authorization server operates something equivalent to PKI’s (Certificate Revocation List) or (Online Certificate Status Protocol). See for details.

Server Metadata

The Grant Management specification adds the following server metadata.

  • grant_management_actions_supported — Grant management actions supported by the authorization server. Possible values are create, query replace, revoke and merge.
  • grant_management_endpoint — The URL of the grant management endpoint
  • grant_management_action_required — Boolean flag indicating whether the grant_management_action request parameter is always required.

Because “grant management is restricted to confidential only clients due to security reasons” (), if the discovery document () includes "grant_management_action_required":true, it implies that the authorization endpoint of the authorization server rejects any request from public clients.

Finally

Grant Management for OAuth 2.0 is supported from Authlete 2.3. The version is not deployed on the shared server (api.authlete.com) as of this writing. Please for early access to Authlete 2.3.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Takahiko Kawasaki

Co-founder and representative director of Authlete, Inc., working as a software engineer since 1997.