Grant Management for OAuth 2.0
Introduction
Grant Management for OAuth 2.0 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 UK Open Banking, Australian Consumer Data Right and Open Banking Brasil. Grant Management is mentioned also in the whitepaper 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 (“Grant Management for OAuth 2.0”) which is published on the website of Authlete. 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 FAPI PR 344. 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_queryscope - Status Code on Success — 200 OK
- Response Content-Type —
application/json - Response Format — See “6.4. Query Status of a Grant”
The following is an example response excerpted from “6.4. Query Status of a Grant” 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 (RFC 6749 / Section 3.3) and resource request parameters (RFC 8707 / Section 2).
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 Section 5.1 of OpenID Connect Core 1.0.
A client application can request claims by including special scopes (profile, email, address and phone) in the scope request parameter (OIDC Core / Section 5.4) and/or by using the claims request parameter (OIDC Core / Section 5.5).
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 “OAuth 2.0 Rich Authorization Requests” (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, Open Banking Brasil Financial-grade API Security Profile 1.0 defines “Dynamic Consent Scope” (Section 7.1.2) 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_revokescope - 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 CRL (Certificate Revocation List) or OCSP (Online Certificate Status Protocol). See “OAuth Access Token Implementation” 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 arecreate,queryreplace,revokeandmerge.grant_management_endpoint— The URL of the grant management endpointgrant_management_action_required— Boolean flag indicating whether thegrant_management_actionrequest parameter is always required.
Because “grant management is restricted to confidential only clients due to security reasons” (Section 5.1), if the discovery document (OIDC Discovery) 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 contact us for early access to Authlete 2.3.
