| Internet-Draft | OAuth Resource Helper | December 2024 |
| van der Meulen & de Jong | Expires 22 June 2025 | [Page] |
This Internet Draft introduces the concept of a Resource Helper in OAuth 2.0. A Resource Helper is a modular component that assists the Authorization Server in managing fine-grained authorization processes. The Resource Helper, associated with a specific Resource Server, handles scope selection and resource-specific details, providing the user-interface for the Resource Owner to approve or refine access requests. By offloading scope-related user interaction to the Resource Helper, the Authorization Server remains generic and stable while the Resource Helper evolves alongside the Resource Server's requirements. This specification defines the protocol, interfaces, and flow between the Authorization Server and the Resource Helper. Introducing a Resource Helper does not affect the OAuth client or the interaction between the OAuth client and the Resource Server.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 22 June 2025.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
In OAuth 2.0 [RFC6749] an authorization server is responsible for the authorization process. We introduce a resource helper, which is a separate component that can handle part of the OAuth Grant Flow of the authorization server, making the authorization server more modular. A Resouce Helper is associated with a specific resource server and provides the user interface for the resource owner to pick Access Token Scopes [RFC6749] (Section 3.3), and possibly other resource server specific information to put in the Access Token, or in an Introspection Response [RFC7662] (Section 2.2). This allows an authorization server to remain generic and stable, while the resource helper can be updated in lock-step with the functionality of the resource server. This document describes the protocol and interface between the authorization server and the resource helper.¶
During an OAuth 2.0 Authorization Grant Flow, the authorization server authenticates the resource owner (via the user agent) and establishes whether the resource owner (partially) grants or denies the client's request for a token. For the authorization server to meaningfully measure if the resource owner wants to grant or deny the request it needs to display, presumably via the user agent, the details of the authorization that the resource owner is about to give in a way that they will understand. These details can be very specific for the resource server's current functionality, especially when the resource owner wants to provide a more fine-grained authorization than just "yes" or "no". For example when the resource owner only wants to allow specific kinds of operations on specific resources, like "allow the client to view these three pictures, but not to delete them", or "allow the client write access to only this specific directory".¶
Several extension to OAuth 2.0 have been created to allow for more control over the authorization process outside of the authorization server.¶
authorization_details of the requested authorization in the Authorization Request to the authorization server.
This requires the client and the resource server to agree on the format and meaning of the authorization_details so that the client can create it
and the authorization server can interpret it and display it to the resource owner.¶
The role of the resource helper we propose is smaller and more interactive than these existing OAuth extensions. Displaying access token scope details via the user agent may involve describing specific resources and actions, in a human-viewable, probably locale-dependent, and possibly even persona-dependent way, using a combination of text, images, and layout. The resource helper executes this task entirely, leaving the authorization server more generic and stable.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The figure below shows the interaction between the authorization server and the resource helper when a client starts the authorization grant process.¶
+--------+ +---------------+ | |-(A)-------Authorization Grant----------->| | | | | | | | +----------+ | | | | | |<----------Pick--------(B)-| | | | | | | | | | | |-(C)----Get Subject------->| | | | | Resource | | Authorization | | Client | | Helper | Submit Scopes, | Server | | | | |-(D)--Token data, and ---->| | | | | | Introspection data | | | | | | | | | | | |-(E)------Return---------->| | | | +----------+ | | | | | | | |<--------------Access Token-----------(F)-| | +--------+ +---------------+
The authorization server SHOULD maintain a registry of trustworthy resource helpers, containing for each resource helper:¶
The authorization server SHOULD NOT redirect the end user to resource helpers other than the ones from this registry. It SHOULD also NOT accept choice submissions from resource helpers other than the ones from this registry.¶
At its `/.well-known/resource-helper` end point, the resource helper SHOULD serve a JSON document, containing an object with a member whose key is "pick" and whose value is the front channel URL for the pick endpoint to which the authorization server can redirect the user.¶
The resource helper needs to persist:¶
The authorization server can redirect the end user to the resource helper's Pick endpoint, with the following query parameters:¶
Example: https://resource-helper.example.com/pick?nonce=12345678&scope=read¶
The resource helper can optionally make a HTTP call to the Subject Info endpoint of the authorization server, with the nonce from the pick request in the query parameter to obtain more information about the end user. Apart from checking the value of the nonce query parameter, the authorization server SHOULD check the Authorization header to establish authentication of the resource helper before responding with any restricted information. Example request:¶
GET /subject-info?nonce=12345678 HTTP/1.1 Host: authorization-server.example.com Authorization: <...>¶
Example response:¶
{
"username": "polly123@example.com"
}
¶
Alternatively, the resource helper could skip this step and instead take its own end user authentication measures.¶
The resource helper will guide the end user in picking access scopes. Note that it is the responsibility of the resource helper to help the end user make the right decisions here. The choice will be opaque to the authorization server, to eventually be interpreted by the Resource Server during resource access.¶
Even though the detailed view of an access scope can only be provided by the resource helper, it is still useful if the authorization server can at least display a string label. In particular, when the authorization server displays the final confirmation dialog, to grant the selected scope to the client in question, it could display this label in much the same way as it will likely display some label for the client's identity there. Also, when displaying a list of currently valid tokens, with the option to revoke, displaying a list of one-line labels could be convenient there.¶
This label could be produced programmatically by the resource helper, or hand-picked by the resource owner.¶
To make it easier for existing resource servers to start accepting access tokens issued by the authorization server, some custom arrangements may be included in the resource helper's software, that interact well with the resource server's existing processes and policies. To facilitate this, the authorization server MUST allow the resource helper to specify opaque data to be included in the access token payload and in the token introspect response.¶
The resource helper might also share state with the resource server that helps the resource server to understand the scope of the access tokens issued by the authorization server, for instance through a database backend that is shared between the resource helper and the resource server.¶
After allowing the user to pick an access scope, the resulting choice submission would include:¶
Apart from the inclusion of the nonce which binds this back channel call to the initial front channel redirect (step B in Figure 1), the resource helper MUST also provide credentials that can identify it as a trusted member of the authorization server's resource helper Registry, for instance through an `Authorization` header as agreed between authorization server and resource helper, and this request MUST be made over TLS, to the choice endpoint of the authorization server.¶
Here is a non-normative example:¶
POST /choice
Content-Type: application/json
Authorization: <...>
{
"nonce": "12345678",
"action": "grant",
"label": {
"en-US": "John's picture number 4 (write access)"
},
"scope": "/home/john/pictures/4:write",
"payload": {
"user": "john"
},
"introspect": {
"path": "storage-5:~pictures/4",
"modes": "rwx"
},
}
¶
After the choice information has been successfully submitted to the authorization server, the end user can be
redirected back to the authorization server to continue the OAuth flow as usual. This redirect MUST contain
the nonce for this interaction in the query parameter, and result=ok if all steps were completed
successfully. Other values for the result query parameter SHOULD be used to indicate different types
of errors:¶
action: deny was passed in the choice call¶
Example: https://authorization-server.example.com/callback?nonce=12345678&result=ok.¶
This memo includes no request to IANA.¶
It is important to understand the value of the choice submission from resource helper to authorization server. It already contains an access grant as a half-product, for the authorization server to finalize by actually issuing it to a client.¶
This model differs from the Lodging Intent pattern used in[FAPI-CIBA], where the intent is only a description of some intended transaction, directly between client and resource server, and from Resource Registries as described in section 3.4 of [I-D.ietf-gnap-resource-servers], or as described in section 3.2 of [UMA-Fed-Authz], which only describe a resource.¶
The choice submission represents more than a description of a transaction scope or a resource registration. It additionally represents an assessment that this description was intentionally composed or approved by an authenticated resource owner, authorized to grant access to such resources, actually taking an active decision to grant such access.¶
What it does not include is the information to which particular client they will grant it. That remains the jurisdiction of the authorization server.¶
The resource helper MUST NOT display any information that the currently authenticated user is not allowed to see, even if it is instructed to display them through the scope parameter that comes from the authorization server.¶
The resource helper MUST only allow picking resources for which the currently authenticated user is a resource owner. The resulting access token scope MUST always be a subset (attenuation) of the resource owner's own access scope.¶
The scope coming back from the resource helper SHOULD be interpretable outside the context of a specific user.
For instance, a scope "my-billing-details:read" means different things for different resource owners.
To avoid confusion, especially if authentication was handled through the authorization server's user_info end point (see above),
use a globally unambiguous scope identifier such as "user-123:billing-detals:read".¶