OAuth 2.0 Client Intermediary Metadata
draft-parecki-oauth-client-intermediary-metadata-00

Document Type Active Internet-Draft (individual)
Last updated 2019-08-29
Stream (None)
Intended RFC status (None)
Formats plain text xml pdf htmlized bibtex
Stream Stream state (No stream defined)
Consensus Boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date
Responsible AD (None)
Send notices to (None)
Open Authentication Protocol                                  A. Parecki
Internet-Draft                                                      Okta
Intended status: Standards Track                         August 29, 2019
Expires: March 1, 2020

                 OAuth 2.0 Client Intermediary Metadata
          draft-parecki-oauth-client-intermediary-metadata-00

Abstract

   This specification defines a mechanism for including information
   about additional parties involved in an OAuth transaction by adding a
   new section to the OAuth 2.0 Dynamic Client Registration request, as
   well as requires that authorization servers surface this information
   to users during an OAuth transaction.

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 March 1, 2020.

Copyright Notice

   Copyright (c) 2019 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 Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Parecki                   Expires March 1, 2020                 [Page 1]
Internet-Draft   OAuth 2.0 Client Intermediary Metadata      August 2019

1.  Introduction

   In some applications of OAuth, an OAuth client is acting on behalf of
   one or more intermediary or user-facing applications, and is not the
   entity that the user has an established relationship with.  In the
   traditional OAuth model, a client_id represents only one application,
   and so the consent screen lists just one third party: the OAuth
   client.  In these cases, it is not appropriate to list only the
   actual OAuth client or only the user-facing application.  Listing
   only the actual OAuth client would be confusing to the user, since
   the user does not have a relationship with this entity.  Listing only
   the user-facing application would be inaccurate and misrepresent the
   situation, since the user would be unaware that their data is
   actually being handled by additional parties.

   This specification extends [RFC7591] and [RFC7592] to define a
   mechanism for including information about the additional parties
   involved in an OAuth transaction by including information about the
   additional intermediaries as well as the user-facing application into
   the Dynamic Client Registration request.  This specification also
   defines requirements of the OAuth authorization server to present
   this information about the additional parties in the OAuth consent
   screen during an OAuth transaction.

2.  Notational Conventions

   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
   [RFC2119].

   Unless otherwise noted, all the protocol parameter names and values
   are case sensitive.

3.  Terminology

   In addition to the terms defined in referenced specifications, this
   document uses the following terms:

   "OAuth":  In this document, "OAuth" refers to OAuth 2.0, [RFC6749].

   "End User Application (EUA)":  The software that the end user
      interacts with and has a relationship with, which is not the same
      as the OAuth client interacting with the Resource Server.

   "Intermediary":  One or more entities that the user's data will pass
      through or be shared with by using the OAuth client.  This
      information is voluntarily provided by the OAuth client, and is

Parecki                   Expires March 1, 2020                 [Page 2]
Internet-Draft   OAuth 2.0 Client Intermediary Metadata      August 2019

      typically enforced by a business relationship between the
      organization providing the Client and the organization providing
      the Resource Server.

   "Client":  "Client" has the same definition as in OAuth 2.0, but is
      worth pointing out explicitly here that the client in this case is
      requesting and obtaining permission from the user to access their
      resources while acting on behalf of the End User Application.

4.  End User Application and Intermediary Metadata

   Registered end user applications, as well as intermediaries, have a
   set of metadata values associated with the client identifier of the
   client that represents them in the OAuth transaction, such as a user-
   visible name, logo, and URL.

   Like the OAuth client metadata defined in [RFC7591] and [RFC7592],
   these metadata values are used in the following ways:

   o  as input values to registration and update requests, and

   o  as output values in registration responses.

   These values are used by the authorization server when displaying the
   OAuth consent screen to the end user, to inform them of all the
   additional parties that will be handling the user's data upon
   approval.

   The following metadata fields are defined by this specification.  The
   implementation and use of the fields is OPTIONAL unless stated
   otherwise.  All data member types (strings, arrays, numbers) are
   defined in terms of their JSON ([RFC7159]) representations.

   Some fields are expected to be displayed in the OAuth consent UI and
   are designated accordingly.

   "name"

   REQUIRED.  A human-readable name of the end user application or
   intermediary.  Authorization servers MUST display this field to the
   end user on the OAuth consent screen.

   "description"

   REQUIRED.  A human-readable description of the end user application
   or intermediary.  This is not intended to be displayed in the OAuth
   consent screen.

Parecki                   Expires March 1, 2020                 [Page 3]
Internet-Draft   OAuth 2.0 Client Intermediary Metadata      August 2019

   "uri"

   A URL string of a web page providing information about the end user
   application or intermediary.  If present, the authorization server
   SHOULD display this URL to the end user in a clickable fashion.  It
   is RECOMMENDED that clients always send this field.  The value of
   this field MUST point to a valid web page.

   "logo_uri"

   A URL string that references a logo for this end user application or
   intermediary.  If present, the authorization server SHOULD display
   this image to the end user in the OAuth consent screen.  The value of
   this field MUST be a valid image file.

   "contacts"

   Array of strings representing ways to contact people responsible for
   this end user application or intermediary, typically email addresses
   or phone numbers.  The authorization server MAY display these to the
   end user in the OAuth consent screen.  See Section 6 of [RFC7591] for
   information on Privacy Considerations.

5.  Client Registration Endpoint

   The client registration endpoint is described in Section 3 of
   [RFC7591].

   Since this specification provides a mechanism for a client to assert
   user information about additional parties other than itself, the
   registration endpoint MUST be protected by an OAuth 2.0 access token
   obtained by the client.  The method by which the initial access token
   is obtained by the client or developer is out of scope of this
   specification, but is likely to be obtained using the client
   credentials grant.

5.1.  Client Registration Request

   This specification extends the client registration request defined in
   [RFC7591].

   This operation registers a combination of client, end user
   application, and optionally one or more intermediaries with an
   authorization server.  The authorization server assigns a unique
   client identifier (and optionally a client secret) that represents
   the combination of all the entities described in the registration
   request.

Parecki                   Expires March 1, 2020                 [Page 4]
Internet-Draft   OAuth 2.0 Client Intermediary Metadata      August 2019

   To register, the client or developer sends an HTTP POST as described
   in Section 3.1 of [RFC7591], with an additional property named
   "end_user_application" containing a JSON object with the end user
   application registration information, and optionally a property named
   "intermediaries" with a JSON array of objects of each intermediary's
   registration information.

   For example, the client could send the following registration request
   to the client registration endpoint using its OAuth 2.0 access token
   it has previously obtained using the client credentials grant.

   The following is a non-normative example request:

       POST /register HTTP/1.1
       Content-Type: application/json
       Accept: application/json
       Host: server.example.com
       Authorization: Bearer 8IGFGXKXZBV5LL38Y3X1

       {
         "client_name": "My Example Client",
         "redirect_uris": [
           "https://client.example.org/callback"
         ],
         "logo_uri": "https://client.example.org/logo.png",
         "end_user_application": {
           "name": "User-Recognizable App Name",
           "description": "This application is what the user
             is interacting with in their browser",
           "uri": "https://example.net/",
           "logo_uri": "https://example.net/logo.png",
           "contacts": [
             "support@example.net"
           ]
         },
         "intermediaries": [
           {
             "name": "Partner App Name",
             "description": "An application that may also receive
               this user's data when the user authorizes the client",
             "uri": "https://partner.example/",
             "logo_uri": "https://partner.example/logo.png",
             "contacts": [
               "support@partner.example"
             ]
           }
         ]
       }

Parecki                   Expires March 1, 2020                 [Page 5]
Internet-Draft   OAuth 2.0 Client Intermediary Metadata      August 2019

5.2.  Client Registration Response

   This specification extends the client information response defined in
   [RFC7591] and [RFC7592].

   Upon a successful registration request, the authorization server
   returns a client identifier for the combination of the client, end
   user application, and any intermediaries specified in the request.

   In addition to the response fields defined in Section 3.2 of
   [RFC7591] and Section 3 of [RFC7592], the response MUST also contain
   all registered metadata about the end user application and any
   intermediaries.  The authorization server MAY reject or replace any
   of the requested metadata values submitted during the registration
   and substitute them with suitable values.

   The following is a non-normative example response of a successful
   registration:

Parecki                   Expires March 1, 2020                 [Page 6]
Internet-Draft   OAuth 2.0 Client Intermediary Metadata      August 2019

    HTTP/1.1 201 Created
    Content-Type: application/json
    Cache-Control: no-store
    Pragma: no-cache

    {
      "client_id": "V8tvEkZWhDAdxSaKGUJZ",
      "client_secret": "SpsuwZIxnp8bBEhp5sk1EKiIKTZ4X4DKU",
      "grant_types": ["authorization_code", "refresh_token"],
      "token_endpoint_auth_method": "client_secret_basic",
      "registration_client_uri": "https://server.example.com/client/tmzaAMkyWlH3",
      "registration_access_token": "MphaAqDaZT86C93ENWRZcf3dfU2dW6POASo8dFXa",
      "client_name": "My Example Client",
      "redirect_uris": [
        "https://client.example.org/callback"
      ],
      "logo_uri": "https://client.example.org/logo.png",
      "end_user_application": {
        "name": "User-Recognizable App Name",
        "description": "This application is what the user is interacting
          with in their browser",
        "uri": "https://example.net/",
        "logo_uri": "https://example.net/logo.png",
        "contacts": [
          "support@example.net"
        ]
      },
      "intermediaries": [
        {
          "name": "Partner App Name",
          "description": "An application that may also receive
            this user's data when the user authorizes the client",
          "uri": "https://partner.example/",
          "logo_uri": "https://partner.example/logo.png",
          "contacts": [
            "support@partner.example"
          ]
        }
      ]
    }

   The "registration_client_uri" and "registration_access_token"
   properties are required in order to support updating and deleting
   this client as described in [RFC7592].

Parecki                   Expires March 1, 2020                 [Page 7]
Internet-Draft   OAuth 2.0 Client Intermediary Metadata      August 2019

5.3.  Client Read Request

   This specification extends the client read request defined in
   [RFC7592] to include the additional metadata properties in the
   response that describe the end user application and intermediaries.
   No additional behavior is prescribed by this specification.

5.4.  Client Update Request

   This specification extends the client update request defined in
   [RFC7592] to be able to update the additional metadata properties
   that describe the end user application and intermediaries.

   The additional properties are provided in the update request in the
   same format as in the initial registration request.

   Since these values were asserted by the client in the initial
   registration, there is no need to prescribe any additional security
   model around the ability to update them, even though these represent
   additional parties.

5.5.  Client Delete Request

   No new behavior is prescribed for delete requests beyond that defined
   in [RFC7592].

6.  Providing End-User Application Details in the Authorization Request

   When the authorization server begins a request from an OAuth client
   identifier that has been registered with additional end user
   application or intermediary information, it MUST display the
   additional parties in the consent UI visible to the end user.

   The authorization server MAY choose to emphasize or make the end user
   application information the primary information displayed in the
   consent screen.  This is because the end user application is likely
   the most recognizable entity to the end user, and the end user may
   not be aware that it is actually a different organization's OAuth
   client that is the one making requests for the user's data.

   The authorization server chooses how best to display the additional
   information, but it MUST include at least the name of the end user
   application, intermediaries, and client, and SHOULD include the logo
   of each as well.

   Once an access token has been issued to this client, the client uses
   the access token to make requests at the resource server on behalf of
   the specific end user application on behalf of the end user.

Parecki                   Expires March 1, 2020                 [Page 8]
Internet-Draft   OAuth 2.0 Client Intermediary Metadata      August 2019

7.  Acknowledgements

   The authors would like to thank Ryan Christiansen and Preston
   McFarland for their initial contributions of the concepts behind this
   specification.  The authors would also like to thank the OAuth
   Working Group for their work on the referenced and related
   specifications that this specification builds upon.

8.  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>.

   [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>.

   [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <https://www.rfc-editor.org/info/rfc7159>.

   [RFC7591]  Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and
              P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
              RFC 7591, DOI 10.17487/RFC7591, July 2015,
              <https://www.rfc-editor.org/info/rfc7591>.

   [RFC7592]  Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak,
              "OAuth 2.0 Dynamic Client Registration Management
              Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015,
              <https://www.rfc-editor.org/info/rfc7592>.

Author's Address

   Aaron Parecki
   Okta

   Email: aaron@parecki.com
   URI:   https://aaronparecki.com

Parecki                   Expires March 1, 2020                 [Page 9]