OAuth Resource Helper

Introduction In OAuth 2.0 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 , and possibly other resource server specific information to put in the Access Token, or in an Introspection Response . 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.

In OAuth 2.0 Rich Authorization Requests, the client includes a JSON description with the 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.
In Resource Set Registration as proposed in and similarly in , an API is defined on the authorization server to allow a resource server to register Resource Sets at the authorization server. A resource set consists of scopes, a description and an icon to allow the authorization server to display the available resource sets to the resource owner in a meaningful way.

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.

Requirements Language 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 when, and only when, they appear in all capitals, as shown here.

Generic Flow The figure below shows the interaction between the authorization server and the resource helper when a client starts the authorization grant process.

(A): The OAuth client initiates the authorization grant process by sending a request to the authorization server.
(B): The authorization server authenticates the user and then redirects the user (via their user agent) to the "Pick" endpoint of the Resource Helper that is registered for the resource server. This redirection includes a unique nonce and, optionally, the scope parameter specified by the client, to initiate the scope selection process.
(C): The Resource Helper may call the authorization server's "Subject Info" to retrieve additional user-specific information (e.g., a username or other identifiers). This call uses the nonce from step B and the resource helper's credentials to authenticate this request.
(D): Once the user has selected their desired scope and permissions, the Resource Helper submits this choice to the authorization server. This submission includes the scope, optional token payload, optional introspection details, and a label with a description of the access that was granted. This call uses the nonce from step B and the resource helper's credentials to authenticate this request.
(E): The authorization server processes the Resource Helper's submission. It finalizes the scope and token details and prepares the access token for the client.
(F): The authorization server issues the access token to the client, completing the flow.

Resource Helper Registry The authorization server SHOULD maintain a registry of trustworthy resource helpers, containing for each resource helper:

a fully qualified domain name (for `/.well-known/resource-helper` lookup, see below)
client credentials
which scope-picking tasks it can be used for

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.

Resource Helper Well-Known Endpoint 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.

Resource Helper Configuration The resource helper needs to persist:

the `choice` back channel endpoint URL of the authorization server
(optional) the subject_info back channel endpoint URL of the authorization server
the front channel callback URL of the authorization server
its client credentials for use in backchannel calls to the authorization server

Resource Helper Pick Endpoint The authorization server can redirect the end user to the resource helper's Pick endpoint, with the following query parameters:

a nonce for this interaction
(optional) the scope parameter as specified by the client (if any)

Example: https://resource-helper.example.com/pick?nonce=12345678&scope=read

Subject Info Lookup 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: Example response: Alternatively, the resource helper could skip this step and instead take its own end user authentication measures.

Picking Access Token Scopes 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.

Human-readable Label 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.

Introspect and Token Payload Options 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.

The Choice Endpoint After allowing the user to pick an access scope, the resulting choice submission would include:

nonce (the nonce from the previous steps)
action (must contain the string "grant" or the string "deny" as appropriate)
label (a human-readable string for display in for instance the authorization server's token revokation interface)
(optional) a scope field, if different from the one that was requested (to be passed back to the client)
(optional) an opaque payload object (to be included in the access token payload)
(optional) an opaque introspect object (to be included in the introspection response for the access token, if applicable)

Apart from the inclusion of the nonce which binds this back channel call to the initial front channel redirect (step B in ), 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:

Redirect Back to the Authorization Server 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:

ok: all steps completed successfully
deny: if action: deny was passed in the choice call
unauth: if no end user could be authenticated
cancel: if the end user chose to abort the process
error: if the back channel call to the choice end point resulted in no response or in an error response
invalid: if the resource helper could not unambiguously interpret its task
fail: if the resource helper was unable to perform it tasks for other reasons

Example: https://authorization-server.example.com/callback?nonce=12345678&result=ok.

IANA Considerations This memo includes no request to IANA.

Security Considerations 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, 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 , or as described in section 3.2 of , 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".