fapi-grant-management | February 2021 | |
Lodderstedt, et al. | Standards Track | [Page] |
This specification defines an extension of OAuth 2.0 [RFC6749] to allow clients to explicitly manage their grants with the authorization server.¶
OAuth authorization servers issue access and refresh tokens based on privileges granted by a resource owner to a particular client in the course of an authorization process or based on pre-configured policies. The concept representing these privileges and their assignment to a particular client is sometimes referred to a the "underlying grant".¶
Although this concept is fundamental to OAuth, there is no explicit representation of the grant in the OAuth protocol. This leads to the situation that clients cannot explicitly manage grants, e.g. query the status or revoke a grant that is no longer needed. The status is implicitly communicated if an access token refresh succeeds or fails or if an API call using an access token fails with HTTP status codes 401 (token is invalid) or 403 (token lacks privileges).¶
It also means the client cannot explicitly ask the authorization server to update a certain grant that is bound to a certain user. Instead the authorization server, typically, will determine a pre-existing grant using the client id from the authorization request and the user id of the authenticated resource owner.¶
If a client wants the authorization server to update a pre-existing grant, it needs to obtain identity data about the user and utilize it in a login hint kind of parameter to refer to the "same user as last time", exposing more identity data to the client than neccessary.¶
Another pattern that was proposed is to use refresh tokens to refer to grants. This would require to send the refresh token as part of the authorization request through the front channel, which posses security issues since the refresh token is a credential and could leak and be injected that way.¶
There are also use cases in highly regulated sectors, e.g. Open Data, where the client might be forced to maintain concurrent, independent grants to represent the privileges delegated by the resource owner to this client in the context of a distinct service offered by the client to this user and using different client_ids is not appropriate.¶
In order to support the before mentioned use cases, this specification introduces a grant_id
clients can use to identify a particular grant along with additional authorization request parameters to request creation and use of such grant ids. This specification also defines a new grant management API provided by the authorization server that clients can use to query the status of a grant and to revoke it.¶
An authorization server supporting this extension allows a client to explicitly manage its grants. The basic design principle is that creation and update of grants is always requested using an OAuth authorization request while querying the status of a grant and revoking it is performed using the new Grant Management API.¶
The underlying assumption is that creation and updates of grants almost always require interaction with the resource owner. Moreover, the client is supposed to manage the grant ids along with the respective tokens on its own without support from the authorization server.¶
This specification introduces the token response parameter grant_id
:¶
grant_id
: URL safe string value identifying an individual grant managed by a particular authorization server for a certain client and a certain resource owner. The grant_id
value MUST be unique in the context of a certain authorization server and SHOULD have enough entropy to make it impractical to guess it.¶
HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-cache, no-store { "access_token": "2YotnFZFEjr1zCsicMWpAA", "token_type": "example", "expires_in": 3600, "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", "grant_id":"TSdqirmAxDa0_-DB_1bASQ" }¶
The Grant Management API allows clients to perform various actions on a grant whose grant_id
the client previously obtained from the authorization server.¶
Currently supported actions are:¶
The Grant Management API does not provide bulk access to all grants of a certain client for functional and privacy reasons. Every grant is associated with a certain resource owner, so just getting the status is useless for the client as long as there is not indication of the user the client can use this grant for. Adding user identity data to the status data would weaken the privacy protection OAuth offers for users towards a client.¶
The Grant Management API will not expose any tokens associated with a certain grant in order to prevent token leakage. The client is supposed to manage its grants along with the respective tokens and ensure its usage in the correct user context.¶
The grant management API is provided by a new endpoint provided by the authorization server. The client MAY utilize the server metadata parameter grant_management_endpoint
(see Section 5.1) to obtain the endpoint URL.¶
The resource URL for a certain grant is built by concatenating the grant management endpoint URL, a slash, and the the grant_id
. For example, if the grant management endpoint is defined as¶
https://as.example.com/grants¶
and the grant_id
is¶
TSdqirmAxDa0_-DB_1bASQ¶
the resulting resource URL would be¶
https://as.example.com/grants/TSdqirmAxDa0_-DB_1bASQ¶
The status of a grant is queried by sending a HTTP GET request to the grant's resource URL as shown by the following example.¶
GET /grants/TSdqirmAxDa0_-DB_1bASQ Host: as.example.com Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA¶
The authorization server will respond with a JSON-formated response as shown in the folling example:¶
HTTP/1.1 200 OK Cache-Control: no-cache, no-store Content-Type: application/json { "scopes":[ { "scope":"contacts read write", "resources":[ "https://rs.example.com/api" ] }, { "scope":"openid" } ], "claims":[ "given_name", "nickname", "email", "email_verified" ], "authorization_details":[ { "type":"account_information", "actions":[ "list_accounts", "read_balances", "read_transactions" ], "locations":[ "https://example.com/accounts" ] } ] }¶
The privileges associated with the grant will be provided as a JSON array containing objects with the following structure:¶
scopes
: JSON array where every entry contains the scope
parameter value and (optionally) any resource
parameter value as defined in [RFC8707] passed in the same authorization request. The AS MUST maintain the scope and resource values passed in different authorization requests in separate objects of the JSON structure in order to preserve their relationship.¶
claims
: JSON array containing the names of all OpenID Connect claims (see [OpenID]) as requested and consented in one or more authorization requests associated with the respective grant.¶
authorization_details
: JSON Object as defined in [I-D.ietf-oauth-rar] containing all authorization details as requested and consented in one or more authorization requests associated with the respective grant.¶
The response structure MAY also include further elements defined by extensions.¶
To revoke a grant, the client sends a HTTP DELETE request to the grant's resource URL. The authorization server responds with a HTTP status code 204 and an empty response body.¶
This is illustrated by the following example.¶
DELETE /grants/TSdqirmAxDa0_-DB_1bASQ Host: as.example.com Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA HTTP/1.1 204 No Content¶
The AS MUST revoke the grant and all refresh tokens issued based on that particular grant, it SHOULD revoke all access tokens issued based on that particular grant.¶
Note: Token revocation as defined in [RFC7009] differentiates from grant revocation as defined in this specification in that token revocation is not required to cause the revocation of the underlying grant. It is at the discretion of the AS to retain a grant in case of token revocation and allow the client to re-connect to this grant through a subsequent authorization request. This decoupling may improve user experience in case the client just wanted to discard the token as a credential.¶
If the resource URL is unknown, the authorization server responds with HTTP status code 400.¶
If the client is not authorized to perform a call, the authorization server responds with HTTP status code 403.¶
If the request lacks a valid access token, the authorization server responds with HTTP status code 401.¶
grant_id_supported
OPTIONAL. JSON string indicating support for provision of grant ids in token responses and use of such grant ids in authorization requests. Allowed values are none
, optional
, always
.¶
none
: the AS does not support grant ids.¶
optional
: the AS supports grant ids, the client determines whether grant ids are issued.¶
always
: the AS will provide grant ids in every token response.¶
If omitted, the default value is none
.¶
grant_update_supported
OPTIONAL. JSON boolean indicating whether the authorization server supports grant updates. If omitted, the default value is false
.¶
grant_management_actions_supported
OPTIONAL. JSON array containing a list of Grant Management actions which are supported. Allowed values are query
and revoke
. If omitted, the default value is no supported actions.¶
grant_management_endpoint
OPTIONAL. URL of the authorization server's Grant Management Administration Endpoint.¶
grant_id_required
OPTIONAL. JSON boolean requesting the AS to provide grant ids in the token response. If omitted, the default value is no grant ids required.¶
Implementations may wish to consider solutions to allow for addressibility of individual components within a grant. Trust ecosystems should consider their requirements during implementation and consider either;
- Including a unique identifier within the authorization object (ie. id
within the RAR) or;
- Defining a comparison algorithm for the grant to allow for derivation of update and append actions¶
grant_id
is issued by the authorization server for each established grant between a client and a user. This should prevent correlation between different clients.¶
grant_id
MUST NOT be derived from PII that can make possible to identify the user.¶
grant_id
potentially could be shared by different client_id belonging to the same entity.¶
A grant id is considered a public identifier, it is not a secret. Implementations MUST assume grant ids leak to attackers, e.g. through authorization requests. For example, access to the sensitive data associated with a certain grant MUST NOT be made accessible without suitable security measures, e.g. an authentication and authorization of the respective client.¶
grant_id
¶
grant_management_mode
¶
grant_management_modes_supported
¶
grant_management_actions_supported
¶
grant_management_endpoint
¶
invalid_grant_id
¶
We would like to thank Vladimir Dzhuvinov, Takahiko Kawasaki, Roland Hedberg, Filip Skokan, Dave Tonge, and Brian Campbell for their valuable feedback and contributions that helped to evolve this specification.¶
Copyright (c) 2020 The OpenID Foundation.¶
The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.¶
The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.¶
[[ To be removed from the final specification ]]¶
-01¶
simplified authorization requests¶
added metadata control grant management behavior of AS and client¶
extended grant resource data model¶
-00¶
initial revision¶