OAuth Resource Helper

Introduction The Authorization Server may redirect the Resource Owner to the Resource Helper's View or Pick endpoint, as part of the authorization flow. Optionally, the Resource Helper may submit the selected access scope to a resource registration endpoint, and refer to it by an identifier rather than by a self-contained description. From the Revokation interface, the Authorization Server may also redirect the Resource Owner to the Resource Helper's View endpoint, to allow them to view the details of previously granted access, and help the Resource Owner decide whether a given token should be revoked or not. During the Authorization Code Flow as described in , the authorization server authenticates the resource owner (via the user agent) and establishes whether the resource owner grants or denies the client's access request. 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 access token scope in a way that the resource owner will understand. Displaying access token scope details via the user agent may involve describing specific resources and actions, in a human-readable, probably locale-dependent, and possibly even persona-dependent way. When the API of the Resource Server changes, the method of displaying access token scope details may also need to change. For instance, if a feature is added that allows the end user to add a photo to an event in a calendar, then the description of an "events:654234:write" access token scope may need to change from "edit the date and title of 'Birthday Bash'" to "upload photos and edit details of 'Birthday Bash'", and it may make sense to display the event's primary photo, so the resource owner can better understand the access token scope they are granting, leading to a more informed decision and thus better security.

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.

Viewing Access Token Scopes During the Authorization Code Flow, the Authorization Server can redirect the user to the Resource Helper to view the access token scope before continuing. | Resource | | | | '-------(4)-- User picks scope ----->| Helper | | | | .------(6)-- Redirect back to AS --<| | | | | | | +---------------+ | | | | | | | | | | | (5) Submit | | | | | | Choice | | | | | v | | | | | +---------------+ | | | '---------------------------------->| | | | | | | | | | '---------(3)-- Redirect to RH -------<| | | | | | | | | | Client Identifier | | | .-+--------------(1)-- & Redirect URI ------->| | | | | | | | | | '--------------(2)-- User authenticates --->| | | | User- | | Authorization | | | Agent | | Server | | | | | | | | .--------(7)-- Authorization Code ---<| | +-|-- --|---+ +---------------+ | | ^ v | | | | ^ v | | +---------+ | | | |>---(8)-- Authorization Code ---------' | | Client | & Redirect URI | | | | | |<---(9)----- Access Token -------------------' +---------+ (w/ Optional Refresh Token) ]]> The view endpoint of the resource helper is a web page the authorization server can link to, which is specialized in displaying an access token scope for the resource owner to understand, and recording a user choice in its context. It SHOULD take 'actions', 'redirect_uri', 'state' and optionally 'scope' as its parameters. The 'action' parameter SHOULD be a space-delimited list of valid actions, as agreed between Authorization Server and Resource Helper, for instance 'grant reject' for use from an authorization endpoint, or 'revoke cancel' for use in a revokation interface. The state parameter here SHOULD be a nonce that is bound to the resource helper. Example: https://view.example.org/?scope=events:654234:write&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fcontinue&state=xyz The view endpoint will allow the resource owner to grant/reject, and this answer is submitted to the authorization server through the back channel. POST /choice Content-Type: application/json { "action": "grant", "state": "xyz" } After this back channel call completes the user will be redirected back in the front channel. The authorization should check that the state parameter matches the nonce it had included in the initial redirect, and that an answer was received through the back channel. https://example.org/continue&state=xyz

Picking Access Token Scopes The authorization server may grant an access token scope which is different from the one requested by the client, based on the authorization server policy or the resource owner's instructions. To allow the resource owner to instruct the authorization server to grant a smaller, larger, or different access token scope than what the client requested, especially in the case where the client only specified the requested scope in generic terms, or not at all, the requirements for viewing access token scopes need to be augmented with a requirement to allow the user to select, deselect, and browse specific aspects of it. In some use cases, a client may generically ask for access to "a photo" or "a folder", without specifying a specific one, and the resource owner may have a chance to browse through a photo collection or a folder tree to select a specific one. Here too, each time the functionalities of the resource server change, the resource browser interface may also need to change. The redirect to the pick endpoint can be embedded in the authorization code flow similarly to the view endpoint. The Authorization Server can redirect the user to the Resource Helper to pick the access token scope before continuing. The pick endpoint of the resource helper takes the same parameters as the view endpoint, but SHOULD allow the user to influence the details of the scope. Example: https://pick.example.org/?scope=webdav-folder&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fcontinue&state=xyz After allowing the user to pick a fine-grained access scope, the resulting choice submission would include a scope field: POST /choice Content-Type: application/json { "action": "grant", "state": "xyz", "scope": "/home/john/pictures/4:write" }

Resource registration endpoint and scope templates With a Resource Helper in play, there are four places where a scope parameter might be specified: from client to Authorization Server, from Authorization Server to Resource Helper, from Resource Helper to the Authorization Server's choice endpoint, and from Authorization Server back to client. The scopes that exist between client and Authorization Server may (partially) match those that exist between Authorization Server and Resource Helper, but they don't have to. After all, the scopes used between client and Authorization Server may be hard-coded into the software, and cumbersome to evolve. In the previous section the scope '/home/john/pictures/4:write' was used as an example of a scope that may be picked. This scope may fit into a template, for instance "<file_path>:<read | write>". In simple cases the scope MAY come from a finite list which both the Authorization Server and the Resource Helper are configured with. The string could also be parseable as JSON or some other syntax. When more flexibility is required, the "scope" parameter of the Choice endpoint could also refer to a dynamically registered resource set, and in some situations a resource helper may first call the resource registration endpoint, as described in section 3.4 of , or as described in section 3.2 of , and then refer to the freshly minted resource set by using its resource_reference in the "scope" parameter of its subsequent call to the Choice endpoint.

Interaction between Resource Helper and Resource Server When a scope is approved or minted in the resource helper, some interaction may be necessary to later make the resource server correctly understand the access scope of the access token, at the time of API access. For instance, the resource helper may insert an entry in the policy registry of the resource server, and ask the authorization server to insert a reference to that into the token, or into the introspect response.

Additional information in the call to the Choice endpoint The authorization server MAY receive additional types of information from the resource helper through the Choice endpoint. Here is a non-normative example: POST /choice Content-Type: application/json { "action": "grant", "state": "xyz", "scope": "/home/john/pictures/4:write", "label": { "en-US": "John's picture number 4 (write access)" }, "payload": { "user": "john" }, "introspect": { "path": "storage-5:~pictures/4", "modes": "rwx" }, }

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 authorisation server can at least display a string label. In particular, when the authorisation server displays the final confirmation dialog, to grant the viewed or picked 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 option to revoke, it would be cumbersome for the user to click 'view' on each of them, and displaying a list of one-line labels would be more 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 interacts well with the resource server's existing processes and policies. To facilitate this, the authorization server MAY 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 authorisation server.

Decoupled authentication Before redirecting to the resource helper, the authorization server may already have taken some measures to authenticate the user in the current user agent session. The resource helper is, however, responsible for its own authentication measures. In many cases this can however rely on the same sign-in mechanisms, and not require any additional clicks from the user. The resource helper is responsible for making sure the authenticated user is allowed to delegate the scope they select. The response coming back from the resource helper should thus be interpreted as a decision made by the resource owner as identified by the resource helper, which may be different from the one authenticated to the main authorization server. This decoupling is by design, and will allow for scenarios where the resource helper refers to a different set of user identifiers than the authorization server. For instance, the resource server may be self-hosted by the resource owner, with the resource owner authenticating as 'admin', whereas the authorization server may be hosted by a university, with the resource owner authenticating with their student number. The authorization server is trusting the resource helper to select the access token scope to be granted, and the resource helper is subsequently trusting the authorization server to select the client that will receive this access. In a way, the resource helper is granting access to the resource, and the authorization server is delegating, or forwarding this grant, binding it to a particular client.

IANA Considerations This memo includes no request to IANA.

Security Considerations It is important to understand the value of the redirect back 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, which does not imply that it was composed by an authenticated resource owner. It's up to the Authorization Server and the Resource Helper to share their understanding of the various values of 'action'. The Authorization Server should be careful not to redirect the user to the wrong URL, put a nonce in the state parameter and check that when accepting the callback redirect, and to always use https. The Resource Helper should 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 should only grant access to resources for which the currently authenticated user is a resource owner. The resulting access token scope should always be a subset (attenuation) of the Resource Owner's own access scope. The scope coming back from the Resource Helper should not need to be interpreted in 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 in the light of decoupled authentication (see above), use a globally unambiguous scope identifier such as 'user-123:billing-detals:read'.