Internet Engineering Task Force P.G.M. van der Meulen Internet-Draft SURF Intended status: Informational M.B. de Jong Expires: 22 June 2025 Ponder Source 19 December 2024 OAuth Resource Helper draft-vandermeulen-oauth-resource-helper-00 Abstract 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. Status of This Memo 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 Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. van der Meulen & de Jong Expires 22 June 2025 [Page 1] Internet-Draft OAuth Resource Helper December 2024 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 2. Generic Flow . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Resource Helper Registry . . . . . . . . . . . . . . . . . . 5 4. Resource Helper Well-Known Endpoint . . . . . . . . . . . . . 5 5. Resource Helper Configuration . . . . . . . . . . . . . . . . 6 6. Resource Helper Pick Endpoint . . . . . . . . . . . . . . . . 6 7. Subject Info Lookup . . . . . . . . . . . . . . . . . . . . . 6 8. Picking Access Token Scopes . . . . . . . . . . . . . . . . . 7 9. Human-readable Label . . . . . . . . . . . . . . . . . . . . 7 10. Introspect and Token Payload Options . . . . . . . . . . . . 7 11. The Choice Endpoint . . . . . . . . . . . . . . . . . . . . . 7 12. Redirect Back to the Authorization Server . . . . . . . . . . 9 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 14. Security Considerations . . . . . . . . . . . . . . . . . . . 9 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 15.1. Normative References . . . . . . . . . . . . . . . . . . 10 15.2. Informative References . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 1. Introduction 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. van der Meulen & de Jong Expires 22 June 2025 [Page 2] Internet-Draft OAuth Resource Helper December 2024 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[RFC9396], 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 [UMA-Fed-Authz] and similarly in [I-D.ietf-gnap-resource-servers], 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. van der Meulen & de Jong Expires 22 June 2025 [Page 3] Internet-Draft OAuth Resource Helper December 2024 1.1. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 2. 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)-------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)-| | +--------+ +---------------+ Figure 1 * (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. van der Meulen & de Jong Expires 22 June 2025 [Page 4] Internet-Draft OAuth Resource Helper December 2024 * (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. 3. 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. 4. 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. van der Meulen & de Jong Expires 22 June 2025 [Page 5] Internet-Draft OAuth Resource Helper December 2024 5. 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 6. 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 7. 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: 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. van der Meulen & de Jong Expires 22 June 2025 [Page 6] Internet-Draft OAuth Resource Helper December 2024 8. 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. 9. 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. 10. 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. 11. 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) van der Meulen & de Jong Expires 22 June 2025 [Page 7] Internet-Draft OAuth Resource Helper December 2024 * 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 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" }, } van der Meulen & de Jong Expires 22 June 2025 [Page 8] Internet-Draft OAuth Resource Helper December 2024 12. 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. 13. IANA Considerations This memo includes no request to IANA. 14. 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[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. van der Meulen & de Jong Expires 22 June 2025 [Page 9] Internet-Draft OAuth Resource Helper December 2024 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". 15. References 15.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 15.2. Informative References [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . van der Meulen & de Jong Expires 22 June 2025 [Page 10] Internet-Draft OAuth Resource Helper December 2024 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, . [RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, May 2023, . [I-D.ietf-gnap-resource-servers] Richer, J. and F. Imbault, "Grant Negotiation and Authorization Protocol Resource Server Connections", Work in Progress, Internet-Draft, draft-ietf-gnap-resource- servers-05, 19 February 2024, . [UMA-Fed-Authz] Maler, E., "UMA Federated Authorization", 2018, . [FAPI-CIBA] Fernandez, G., "UMA Federated Authorization", 2021, . Authors' Addresses Pieter van der Meulen SURF Moreelsepark 48 3511 EP Utrecht Netherlands Email: pieter.vandermeulen@surf.nl Michiel de Jong Ponder Source Torenlaan 5A 1402 AT Bussum Netherlands Email: michiel@unhosted.org van der Meulen & de Jong Expires 22 June 2025 [Page 11]