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: &lt;...&gt;

   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: &lt;...&gt;

   {
     "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,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

15.2.  Informative References

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,
              <https://www.rfc-editor.org/info/rfc6749>.




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,
              <https://www.rfc-editor.org/info/rfc7662>.

   [RFC9396]  Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0
              Rich Authorization Requests", RFC 9396,
              DOI 10.17487/RFC9396, May 2023,
              <https://www.rfc-editor.org/info/rfc9396>.

   [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,
              <https://datatracker.ietf.org/doc/html/draft-ietf-gnap-
              resource-servers-05>.

   [UMA-Fed-Authz]
              Maler, E., "UMA Federated Authorization", 2018,
              <https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-
              federated-authz-2.0.html>.

   [FAPI-CIBA]
              Fernandez, G., "UMA Federated Authorization", 2021,
              <https://openid.net/specs/openid-client-initiated-
              backchannel-authentication-core-1_0.html>.

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]