draft-hardjono-dyn-reg-v1.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc PUBLIC "-//IETF//DTD RFC 2629//EN"
"http://xml.resource.org/authoring/rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
]>
<rfc category="std" docName="draft-hardjono-oauth-dyn-reg-v1-02"
     ipr="trust200902">
  <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

  <?rfc toc='yes' ?>

  <?rfc tocdepth='3' ?>

  <?rfc symrefs='yes' ?>

  <?rfc sortrefs='yes' ?>

  <?rfc compact='yes' ?>

  <?rfc subcompact='no' ?>

  <?rfc strict='yes' ?>

  <?rfc notedraftinprogress='yes' ?>

  <front>
    <title abbrev="OAuth Dynamic Client Registration">OAuth Dynamic Client
    Registration Protocol</title>

    <author fullname="Thomas Hardjono" initials="T" role="editor"
            surname="Hardjono">
      <organization>MIT Kerberos Consortium</organization>

      <address>
        <postal>
          <street></street>

          <city></city>

          <region></region>

          <code></code>

          <country></country>
        </postal>

        <phone></phone>

        <facsimile></facsimile>

        <email>hardjono@mit.edu</email>

        <uri></uri>
      </address>
    </author>

    <author fullname="Maciej Machulak" initials="M" surname="Machulak">
      <organization>Newcastle University</organization>

      <address>
        <email>m.p.machulak@ncl.ac.uk</email>

        <uri>http://ncl.ac.uk/</uri>
      </address>
    </author>

    <author fullname="Eve Maler" initials="E" surname="Maler">
      <organization>XMLgrrl.com</organization>

      <address>
        <email>eve@xmlgrrl.com</email>

        <uri>http://www.xmlgrrl.com</uri>
      </address>
    </author>

    <author fullname="Christian Scholz" initials="C" surname="Scholz">
      <organization>COM.lounge GmbH</organization>

      <address>
        <postal>
          <street></street>

          <city></city>

          <region></region>

          <code></code>

          <country></country>
        </postal>

        <phone></phone>

        <facsimile></facsimile>

        <email></email>

        <uri></uri>
      </address>
    </author>

    <date day="1" month="May" year="2011" />

    <abstract>
      <t>This specification proposes an OAuth Dynamic Client Registration
      protocol.</t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <t>This informal draft discusses a number of requirements for and
      approaches to automatic registration of clients with an OAuth
      authorization server, with special emphasis on the needs of the
      OAuth-based User-Managed Access protocol <xref
      target="UMA-Core"></xref>.</t>

      <t>In some use-case scenarios it is desirable or necessary to allow
      OAuth clients to obtain authorization from an OAuth authorization server
      without the two parties having previously interacted. Nevertheless, in
      order for the authorization server to accurately represent to end-users
      which client is seeking authorization to access the end-user's
      resources, a method for automatic and unique registration of clients is
      needed.</t>

      <t>The goal of this proposed registration protocol is for an
      authorization server to provide a client with a client identifier and
      optionally a client secret in a dynamic fashion. To accomplish this, the
      authorization server must first be provided with information about the
      client, with the client-name being the minimal information provided. In
      practice, additional information will need to be furnished to the
      authorization server, such as the client's homepage, icon, description,
      and so on.</t>

      <t>The dynamic registration protocol proposed here is envisioned to be
      an additional task to be performed by the OAuth authorization server,
      namely registration of a new client identifier and optional secret and
      the issuance of this information to the client. This task would occur
      prior to the point at which the client wields its identifier and secret
      at the authorization server in order to obtain an access token in normal
      OAuth fashion.</t>

      <section title="Notational Conventions">
        <t>The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
        'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
        document are to be interpreted as described in <xref
        target="RFC2119"></xref>.</t>

        <t>Unless otherwise noted, all the protocol parameter names and values
        are case sensitive.</t>
      </section>

      <section title="Terminology">
        <t><list hangIndent="6" style="hanging">
            <t hangText="resource server"><vspace /> A server capable of
            accepting and responding to protected resource requests.</t>

            <t hangText="resource owner"><vspace /> An entity capable of
            granting access to a protected resource.</t>

            <t hangText="client"><vspace /> An application obtaining
            authorization and making protected resource requests.</t>

            <t hangText="authorization server"><vspace /> A server capable of
            issuing tokens after successfully authenticating the resource
            owner and obtaining authorization. The authorization server may be
            the same server as the resource server, or a separate entity.</t>

            <t hangText="authorization manager"><vspace /> An UMA-defined
            variant of an authorization server that carries out an authorizing
            user's policies governing access to a protected resource.</t>

            <t hangText="end-user authorization endpoint"><vspace /> The
            authorization server's HTTP endpoint capable of authenticating the
            end-user and obtaining authorization.</t>

            <t hangText="token endpoint"><vspace /> The authorization server's
            HTTP endpoint capable of issuing tokens and refreshing expired
            tokens.</t>

            <t hangText="client identifier"><vspace /> An unique identifier
            issued to the client to identify itself to the authorization
            server. Client identifiers may have a matching secret.</t>

            <t hangText="client registration endpoint">The authorization
            server's HTTP endpoint capable of issuing client identifiers and
            optional client secrets.</t>
          </list></t>
      </section>
    </section>

    <section title="Use Cases">
      <t>The UMA protocol involves two instances of OAuth flows. In the first,
      an end-user introduces a host (essentially an enhanced OAuth resource
      server) to an authorization manager (an enhanced OAuth authorization
      server) as a client of it, possibly without that host having obtained
      client identification information from that server previously. In the
      second, a requester (an enhanced OAuth client) approaches a host and
      authorization manager to get and use an access token in approximately
      the normal OAuth fashion, again possibly without that client having
      obtained client identification information from that server previously.
      Both the host-as-client and the requester-as-client thus may need
      dynamic client registration in order for the UMA protocol flow to
      proceed.</t>

      <t>The needs for inter-party trust vary in different UMA use cases. In
      lightweight Web circumstances such as person-to-person calendar sharing,
      dynamic registration is entirely appropriate. In cases where
      high-sensitivity information is being protected or where a regulatory
      environment puts constraints on the building of trust relationships,
      such as sharing health records with medical professionals or giving
      access to tax records to outsourced bookkeeping staff, static means of
      provisioning client identifiers may be imposed.</t>

      <t>More information about UMA use cases is available at <xref
      target="UMA-UC"></xref>.</t>
    </section>

    <section title="Requirements">
      <t>Following are proposed requirements for dynamic client
      registration.</t>

      <section title="The client needs to be uniquely identifiable by the authorization server">
        <t>In order for an authorization server to do proper user-delegated
        authorization and prevent unauthorized access it must be able to
        identify clients uniquely. As is done today in OAuth, the client
        identifier (and optional secret) should thus be issued by the
        authorization server and not simply accepted as proposed by the
        client.</t>
      </section>

      <section title="The authorization server must collect metadata about a client for later user interaction">
        <t>In order for the authorization server to describe a client to an
        end-user in an authorization step it needs information about the
        client. This can be the client name at a minimum, but today servers
        usually request at least a description, a homepage URL, and an icon
        when doing manual registration.</t>
      </section>

      <section title="The authorization server must have the option of strongly authenticating the client and its metadata">
        <t>In order to prevent spoofing of clients and enable dynamic building
        of strong trust relationships, the authorization server should have
        the option to verify the provided information. This might be solved
        using message signature verification; relatively weaker authentication
        might be achieved in a simpler way by pulling metadata from a trusted
        client URL.</t>
      </section>

      <section title="Dynamic client registration must be possible from both web-server applications and applications with other capabilities and limitations, such as native applications">
        <t>In the UMA context, alternative types of applications might serve
        as both hosts (for example, as a device-based personal data store) and
        requesters (for example, to subscribe to a calendar or view a photo).
        Such applications, particularly native applications, may have special
        limitations, so new solutions to meeting the set of requirements
        presented here may be needed. We anticipate that each instance of a
        native application (that is, the specific instance running on each
        device) that is installed and run by the same user may need the option
        of getting a unique client identifier. In this case, there are
        implications around gathering and displaying enough information to
        ensure that the end-user is delegating authorization to the intended
        application.</t>
      </section>

      <section title="Transaction integrity must be ensured in large deployments where data propagation can be an issue">
        <t>When a client sends information to a server endpoint, it might take
        time for this data to propagate through big server installations that
        spread across various data centers. Care needs to be taken that
        subsequent interactions with the user after the registration process,
        such as an authorization request, show the correct data.</t>

        <t>In the UMA context, dynamic registration of a host at an AM is
        almost certain to take place in the middle of an introduction and
        authorization process mediated by the end-user; even though the host
        needs a client identifier from the AM no matter which end-user caused
        the registration process to take place, the end-user may need to wait
        for the registration sub-process to finish in order to continue with
        the overall process. It may be necessary to ensure that the host
        interacts with the same AM server throughout.</t>
      </section>

      <section title="UMA design principles and requirements">
        <t>In addition to general requirements for dynamic client
        registration, UMA seeks to optimize for the design principles and
        requirements found in the UMA Requirements document <xref
        target="UMA-Reqs"></xref>, most particularly: <list style="symbols">
            <t>DP1: Simple to understand, implement in an interoperable
            fashion, and deploy on an Internet-wide scale</t>

            <t>DP6: Able to be combined and extended to support a variety of
            use cases and emerging application functionality</t>

            <t>DP8: Avoid adding crypto requirements beyond what existing web
            app implementations do today</t>

            <t>DP10: Complexity should be borne by the authorization endpoint
            vs. other endpoints</t>
          </list></t>
      </section>
    </section>

    <section title="Analysis of Registration Flow Options">
      <t>This section analyzes some options for exchanging client metadata for
      a client identifier and optional secret.</t>

      <t>It currently seems impossible to specify a single registration flow
      that will satisfy all requirements, deployment needs, and client types.
      This document, therefore, presents as small a variety of options as
      possible. If it is possible to construct a single unified flow in the
      ultimate design, all other things being equal this would be
      preferred.</t>

      <t><list hangIndent="6" style="hanging">
          <t hangText="Client provides metadata on every request"><vspace />
          In this approach, the client passes all necessary metadata such as
          its name and icon on every request to the authorization server, and
          the client doesn't wield a client identifier as such. This option
          makes it more difficult (though not impossible) to meet the first
          and second requirements since different clients could theoretically
          represent themselves to an authorization server with the same
          metadata and the same client could represent itself on subsequent
          visits with different metadata. Also, today's OAuth protocol
          requires the use of a client identifier. Because of the UMA
          simplicity principle we do not recommend this flow option and and
          have not provided a candidate solution.</t>

          <t hangText="Client pushes metadata"><vspace /> In this approach,
          the client discovers the registration endpoint of the authorization
          server and sends its metadata directly to that endpoint in a
          standard format. The authorization server answers with a client
          identifier and optional secret in the response. This approach may be
          necessary in cases where the client is behind a firewall, but strong
          authentication of the client metadata may be more difficult or
          costly with this approach than with a "pull" approach, discussed
          just below. Further, this approach is problematic in the case of
          applications that can't function as POST-capable web servers. A
          proposal for "push" is presented in this document.</t>

          <t
          hangText="Client pushes URL, server pulls metadata from it"><vspace />
          In this approach, the client sends only a URL to the authorization
          server, which then uses that URL to pull metadata about the client
          in some standard format, returning identification information in the
          response to the initial request. This approach more easily allows
          for strong authentication of clients because the metadata can be
          statically signed. (The message containing the URL could be signed
          as well.) However, caution should be exercised around the
          propagation issue if the initial URL push is made to a server
          different from the one the end-user is interacting with. Further,
          this approach is problematic in the case of applications that cannot
          themselves serve as "pull-able" metadata repositories. A proposal
          for "pull" is presented in this document.</t>

          <t
          hangText="Native-app client collaborates with home-base web app to provide metadata"><vspace />
          An instance of a native application (for example, on a mobile
          device) may have difficulty directly conveying trustworthy metadata
          but may also have difficulty providing a trustworthy third-party
          source from which a server can pull metadata. This document explores
          one option for meeting the requirements, but does not present a
          full-fledged proposal.</t>
        </list></t>
    </section>

    <section title="Discovery of Server's Client Registration Endpoint">
      <t>Regardless of flow option, the client needs to discover the
      authorization server's client registration endpoint.</t>

      <t>The client MUST use the <xref target="RFC5785"></xref> and <xref
      target="hostmeta"></xref> discovery mechanisms to learn the URI of the
      client registration endpoint at the authorization server. The
      authorization server MUST provide a host-meta document containing a Link
      element with a rel value of: <spanx style="verb">http://oauth.net/as/registration</spanx></t>

      <figure>
        <preamble>For example:</preamble>

        <artwork><![CDATA[
      
      <XRD>
        <Host>http://server.example.com</Host>
        <Link rel="http://oauth.net/as/registration" 
              href="https://server.example.com/register">
            <Title>Client Registration Endpoint</Title>
        </Link>
      </XRD>
      
       ]]></artwork>
      </figure>
    </section>

    <section title="Client Registration with Pushed Metadata">
      <t>This registration flow works as follows:</t>

      <t><list style="numbers">
          <t>The client sends its metadata in JSON form to the client
          registration endpoint. The client MUST send its name, description,
          and redirection URI and MAY send a URI for its icon. The client MAY
          sign the metadata as a JSON Token issuer, using the mechanisms
          defined in <xref target="OAuth-Sig"></xref>.</t>

          <t>The authorization server checks the data, verifying the signature
          as necessary, and returns a client identifier and an optional client
          secret.</t>
        </list></t>

      <figure anchor="Figure-1"
              title="Client Registration Flow with Pushed Metadata">
        <artwork><![CDATA[
            
  +--------+                                  +---------------+
  | Client |--(A)--- Registration Request --->| Authorization |
  |        |         with Metadata            |     Server    |
  |        |                                  |               |
  |        |<-(B)----Registration Response ---|               |
  |        |         with Client ID Info      |               |
  +--------+                                  +---------------+

          ]]></artwork>
      </figure>

      <section title="Client Registration Request">
        <t>The client sends a JSON formatted document to the client
        registration endpoint. The client includes the following parameters in
        the request:</t>

        <t><list hangIndent="6" style="hanging">
            <t hangText="type"><vspace /> REQUIRED. This parameter must be set
            to "push".</t>

            <t hangText="client_name"><vspace /> REQUIRED. This field contains
            a human-readable name of the client.</t>

            <t hangText="client_url"><vspace /> REQUIRED. This field contains
            the URL of the homepage of the client.</t>

            <t hangText="client_description"><vspace /> REQUIRED. This field
            contains a text description of the client.</t>

            <t hangText="client_icon"><vspace /> OPTIONAL. This field contains
            a URL for an icon for the client.</t>

            <t hangText="redirect_url"><vspace /> REQUIRED. This field
            contains the URL to which the authorization server should send its
            response.</t>
          </list></t>

        <t>The client MAY include additional metadata in the request and the
        authorization server MAY ignore this additional information.</t>

        <figure>
          <preamble>For example, the client might send the following
          request:</preamble>

          <artwork><![CDATA[
        
    POST /register HTTP/1.1
    Host: server.example.com
    Content-Type: application/json

    {
      type: "push",
      client_name: "Online Photo Gallery",
      client_url:  "http://onlinephotogallery.com",
      client_description: "Uploading and also editing capabilities!",
      client_icon: "http://onlinephotogallery.com/icon.png",
      redirect_url: "https://onlinephotogallery.com/client_reg"
    }
        
         ]]></artwork>
        </figure>

        <t>The parameters are included in the entity body of the HTTP request
        using the "application/json" media type as defined by <xref
        target="JSON"></xref>. The parameters are serialized into a JSON
        structure by adding each parameter at the highest structure level.
        Parameter names and string values are included as JSON strings.</t>
      </section>

      <!-- client push request -->

      <section title="Client Registration Response">
        <t>After receiving and verifying information received from the client,
        the authorization server issues a client identifier and an optional
        client secret, and constructs the response by adding the following
        parameters to the entity body of the HTTP response with a 200 status
        code (OK): <list hangIndent="6" style="hanging">
            <t hangText="client_id"><vspace /> REQUIRED.</t>

            <t hangText="client_secret"><vspace /> OPTIONAL.</t>

            <t hangText="issued_at"><vspace /> OPTIONAL. Specifies the
            timestamp when the identifier was issued. The timestamp value MUST
            be a positive integer. The value is expressed in the number of
            seconds since January 1, 1970 00:00:00 GMT.</t>

            <t hangText="expires_in"><vspace /> OPTIONAL; if supplied, the
            <spanx style="verb">issued_at</spanx> parameter is REQUIRED.
            Specifies the valid lifetime, in seconds, of the identifier. The
            value is represented in base 10 ASCII.</t>
          </list></t>

        <t>The parameters are included in the entity body of the HTTP response
        using the "application/json" media type as defined by <xref
        target="JSON"></xref>. The parameters are serialized into a JSON
        structure by adding each parameter at the highest structure level.
        Parameter names and string values are included as JSON strings.</t>

        <t>The authorization server MUST include the HTTP <spanx style="verb">Cache-Control</spanx>
        response header field with a value of <spanx style="verb">no-store</spanx>
        in any response containing <spanx style="verb">client_secret</spanx>.</t>

        <figure>
          <preamble>For example, the authorization server might return the
          following response:</preamble>

          <artwork><![CDATA[
            
    HTTP/1.1 200 OK
    Content-Type: application/json
    Cache-Control: no-store

    {
      client_id: "5UO9XcL4TQTa",
      client_secret: "WdRKN3zeTc20"
    }

             ]]></artwork>
        </figure>
      </section>

      <!-- client registration response -->

      <section title="Error Response">
        <t>If the request for registration is invalid or unauthorized, the
        authorization server constructs the response by adding the following
        parameters to the entity body of the HTTP response with a 400 status
        code (Bad Request) using the &ldquo;application/json&rdquo; media
        type: <list style="symbols">
            <t><spanx style="verb">error</spanx> (REQUIRED).</t>

            <t><spanx style="verb">error_description</spanx> (OPTIONAL).
            Human-readable text providing additional information, used to
            assist in the understanding and resolution of the error
            occurred.</t>

            <t><spanx style="verb">error_uri</spanx> (OPTIONAL). A URI
            identifying a human-readable web page with information about the
            error, used to provide the end-user with additional information
            about the error.</t>
          </list></t>

        <figure>
          <preamble>An example error response (with line breaks for
          readability):</preamble>

          <artwork><![CDATA[
        
    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    Cache-Control: no-store

    {
    "error": "unauthorized_client",
    "description": "This client is not on the 
      white list of this Authorization Server."
    }
        
         ]]></artwork>
        </figure>
      </section>

      <!-- error message -->
    </section>

    <!-- push client registration -->

    <section title="Client Registration with Pushed URL and Pulled Metadata">
      <t>This registration flow works as follows:</t>

      <t><list style="numbers">
          <t>The client sends its metadata URI to the client registration
          endpoint. The client MAY sign the metadata as a JSON Token issuer,
          using the mechanisms defined in <xref
          target="OAuth-Sig"></xref>.</t>

          <t>The authorization server verifies the signature as necessary, and
          uses the <xref target="RFC5785"></xref> and <xref
          target="hostmeta"></xref> discovery mechanisms on this URI to
          retrieve the host-meta document describing the client. The host-meta
          document MUST contain the client name, description, and redirection
          URI, and MAY contain a URI for the client icon.</t>
        </list></t>

      <figure anchor="Figure-2"
              title="Client Registration Flow with Pushed URL and Pulled Metadata">
        <artwork><![CDATA[

  +--------+                                  +---------------+
  | Client |--(A)--- Registration Request --->| Authorization |
  |        |         with URL                 |     Server    |
  |        |                                  |               |
  |        |<-(B)--- Client Discovery --------|               |
  |        |                                  |               |
  |        |--(C)---- Host-Meta Document ---->|               |
  |        |                                  |               |
  |        |<-(D)--- Registration Response ---|               |
  |        |         with Client ID Info      |               |
  +--------+                                  +---------------+

          ]]></artwork>
      </figure>

      <section title="Client Registration Request">
        <t>The client sends a JSON formatted document to the client
        registration endpoint. The client includes the following parameters in
        the request:</t>

        <t><list hangIndent="6" style="hanging">
            <t hangText="type"><vspace /> REQUIRED. This parameter must be set
            to "pull".</t>

            <t hangText="client_url"><vspace /> REQUIRED. This field contains
            the URL of the homepage of the client.</t>
          </list></t>

        <t>The client MUST NOT include other metadata parameters, such as
        those defined in the pushed-metadata scenario.</t>

        <figure>
          <preamble>For example, the client might send the following
          request:</preamble>

          <artwork><![CDATA[
        
    POST /register HTTP/1.1
    Host: server.example.com
    Content-Type: application/json

    {
      type: "pull",
      url: "http://onlinephotogallery.com"
    }

        
         ]]></artwork>
        </figure>

        <t>The parameters are included in the entity body of the HTTP request
        using the "application/json" media type as defined by <xref
        target="JSON"></xref>. The parameters are serialized into a JSON
        structure by adding each parameter at the highest structure level.
        Parameter names and string values are included as JSON strings.</t>
      </section>

      <section title="Client Discovery">
        <t>The authorization server evaluates this request and MAY perform a
        <xref target="RFC5785"></xref> and <xref target="hostmeta"></xref>
        discovery mechanism on the provided URL to the host-meta document for
        the client.</t>

        <figure>
          <preamble>For example:</preamble>

          <artwork><![CDATA[
        
GET /.well-known/host-meta HTTP/1.1
Host: onlinephotogallery.com        
         ]]></artwork>
        </figure>

        <t>The authorization server retrieves the host-meta document, which
        MUST contain:</t>

        <t><list style="symbols">
            <t>A <spanx style="verb">Property</spanx> element with a <spanx
            style="verb">type</spanx> value of <spanx style="verb">http://oauth.net/client/name</spanx>
            containing the human-readable client name. (REQUIRED)</t>

            <t>A <spanx style="verb">Property</spanx> element with a <spanx
            style="verb">type</spanx> value of <spanx style="verb">http://oauth.net/client/description</spanx>
            containing the human readable description of the client.
            (REQUIRED)</t>

            <t>A <spanx style="verb">Link</spanx> element with a <spanx
            style="verb">rel</spanx> value of <spanx style="verb">http://oauth.net/client/redirect_uri</spanx>
            (REQUIRED).</t>

            <t>A <spanx style="verb">Link</spanx> element with a <spanx
            style="verb">rel</spanx> value of <spanx style="verb">http://oauth.net/client/uri</spanx>
            (REQUIRED).</t>

            <t>A <spanx style="verb">Link</spanx> element with a <spanx
            style="verb">rel</spanx> value of <spanx style="verb">http://oauth.net/client/icon</spanx>
            (OPTIONAL).</t>
          </list></t>

        <figure>
          <preamble>For example:</preamble>

          <artwork><![CDATA[
        
    <XRD>
      <Host>http://onlinephotogallery.com</Host>
      <Property type="http://oauth.net/client/name">
        Online Photo Gallery
      </Property>
      <Property type="http://oauth.net/client/description">
        Really nice Online Photo Gallery!
      </Property>
      <Link rel="http://oauth.net/client/uri" 
            href="http://onlinephotogallery.com">
        <Title>Client URI</Title>
      </Link>
      <Link rel="http://oauth.net/client/redirect_uri" 
            href="https://onlinephotogallery.com/client_reg">
        <Title>Client Redirect URI</Title>
      </Link>
      <Link rel="http://oauth.net/client/icon" 
            href="http://onlinephotogallery.com/icon.png">
        <Title>Client Icon</Title>
      </Link>
    </XRD>
        
         ]]></artwork>
        </figure>
      </section>

      <!-- client discovery -->

      <section title="Client Registration Response">
        <t>After receiving and verifying information retrieved from the
        client, the authorization server issues the client identifier and an
        optional client secret, and constructs the response by adding the
        following parameters to the entity body of the HTTP response with a
        200 status code (OK):</t>

        <t><list style="symbols">
            <t><spanx style="verb">client_id</spanx> (REQUIRED)</t>

            <t><spanx style="verb">client_secret</spanx> (OPTIONAL)</t>
          </list></t>

        <t>The parameters are included in the entity body of the HTTP response
        using the "application/json" media type as defined by <xref
        target="JSON"></xref>. The parameters are serialized into a JSON
        structure by adding each parameter at the highest structure level.
        Parameter names and string values are included as JSON strings.</t>

        <t>The authorization server MUST include the HTTP <spanx style="verb">Cache-Control</spanx>
        response header field with a value of <spanx style="verb">no-store</spanx>
        in any response containing the <spanx style="verb">client_secret</spanx>.</t>

        <figure>
          <preamble>For example the authorization server might return the
          following response:</preamble>

          <artwork><![CDATA[
        
    HTTP/1.1 200 OK
    Content-Type: application/json
    Cache-Control: no-store

    {
      "client_id":"5UO9XcL4TQTa",
      "client_secret":"WdRKN3zeTc20"
    }
        
         ]]></artwork>
        </figure>
      </section>

      <section title="Error Response">
        <t>If the request for registration is invalid or unauthorized, the
        authorization server constructs the response by adding the following
        parameters to the entity body of the HTTP response with a 400 status
        code (Bad Request) using the &ldquo;application/json&rdquo; media
        type:</t>

        <t><list style="symbols">
            <t><spanx style="verb">error</spanx> (REQUIRED). A single error
            code.</t>

            <t><spanx style="verb">error_description</spanx> (OPTIONAL).
            Human-readable text providing additional information, used to
            assist in the understanding and resolution of the error
            occurred.</t>

            <t><spanx style="verb">error_uri</spanx> (OPTIONAL). A URI
            identifying a human-readable web page with information about the
            error, used to provide the end-user with additional information
            about the error.</t>
          </list></t>

        <figure>
          <preamble>An example error response (with line breaks for
          readability):</preamble>

          <artwork><![CDATA[
        
    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    Cache-Control: no-store

    {
    "error": "unauthorized_client",
    "description": "This client is not on the 
      white list of this Authorization Server."
    }
        
         ]]></artwork>
        </figure>

        <t>If the host-meta discovery was not successful, the authorization
        server MUST use the error code <spanx style="verb">hostmeta_error</spanx>.</t>

        <figure>
          <preamble>An example error response (with line breaks for
          readability):</preamble>

          <artwork><![CDATA[
        
    HTTP/1.1 404 Not Found
    Content-Type: application/json
    Cache-Control: no-store

    {
    "error": "hostmeta_error",
    "description": "The hostmeta document could 
      not be retrieved from the URL."
    }
        
         ]]></artwork>
        </figure>
      </section>

      <!-- error message -->
    </section>

    <!-- pull client registration -->

    <section title="Native Application Client Registration">
      <t>For a native application serving as an UMA host, we anticipate that
      the need for dynamic client registration to introduce this app to an UMA
      authorization manager may typically happen only once (or very
      infrequently), likely to a single authorization manager, and
      registration could usefully take place at the time the app is
      provisioned onto a device. By contrast, for a native app serving as an
      UMA requester, it may need to register at multiple authorization
      managers over time when seeking access tokens, at moments much later
      than the original provisioning of the app onto the device.</t>

      <t>When a native application is provisioned on a device, such as through
      an app store model, often it has an associated "home base" web server
      application component with which it registers (outside of any
      UMA-related or OAuth-related interactions). This pairwise relationship
      can be exploited in a number of ways to allow trustable, unique metadata
      to be conveyed to an OAuth server and for this instance of the app to
      receive a client identifier and optional secret. We have discussed
      "device-initiated" and "home base-initiated" pattern options for OAuth
      dynamic client registration in these circumstances. Device-initiated
      flows seem more generically applicable (for example, for both UMA host
      and UMA requester needs). However, a home base-initiated flow may be
      preferable in case it is necessary to pre-determine a trust level
      towards an OAuth server. In this case, the home base server could
      initiate the registration process if and only if there exists a trust
      relationship between the two parties.</t>

      <t>Following is one option for a device-initiated flow: <list
          style="numbers">
          <t>User provisions native app on device and registers with and
          authenticates to app's home-base web application.</t>

          <t>Home base provisions native app with home base-signed
          metadata.</t>

          <t>Whenever user tries to use native app to access a protected
          resource, native app provides home base-provided metadata to
          server.</t>

          <t>Server verifies home base signature by pulling public key from
          home base URL and generates client identifier and secret for native
          app.</t>

          <t>Server returns client identifier and secret to native app.</t>
        </list></t>
    </section>

    <section title="Security Considerations">
      <t>Following are some security considerations: <list style="symbols">
          <t>No client authentication: The server should treat unsigned pushed
          client metadata as self-asserted.</t>

          <t>Weak client authentication: The server should treat unsigned
          pulled client metadata as self-asserted unless the the domain of the
          client matches the client metadata URL and the URL is well-known and
          trusted.</t>

          <t>Strong client authentication: The server should treat signed
          client metadata (pushed or pulled) and a signed metadata URL as
          self-asserted unless it can verify the signature as being from a
          trusted source.</t>
        </list></t>
    </section>

    <section title="Acknowledgments">
      <t>The authors thank the User-Managed Access Work Group participants,
      particularly the following, for their input to this document: <list
          style="symbols">
          <t>Domenico Catalano</t>

          <t>George Fletcher</t>

          <t>Nat Sakimura</t>
        </list></t>
    </section>

    <section title="Document History">
      <t></t>

      <t>[[ to be removed by RFC editor before publication as an RFC ]]</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <reference anchor="OAuth-Sig"
                 target="http://www.ietf.org/mail-archive/web/oauth/current/msg03893.html">
        <front>
          <title>OAuth Signature proposals</title>

          <author initials="D." surname="Balfanz">
            <organization>IETF</organization>
          </author>

          <date year="2010" />
        </front>
      </reference>

      <reference anchor="hostmeta"
                 target="http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hammer-hostmeta-13.xml">
        <front>
          <title>Web Host Metadata</title>

          <author initials="E." surname="Hammer-Lahav">
            <organization>Yahoo!</organization>
          </author>

          <date year="2010" />
        </front>
      </reference>

      <reference anchor="JSON" target="http://tools.ietf.org/html/rfc4627">
        <front>
          <title>The application/json Media Type for JavaScript Object
          Notation (JSON)</title>

          <author initials="D." surname="Crockford">
            <organization>JSON.org</organization>
          </author>

          <date year="2006" />
        </front>
      </reference>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2617.xml' ?>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5785.xml' ?>
    </references>

    <references title="Non-Normative References">
      <reference anchor="UMA-Core"
                 target="http://kantarainitiative.org/confluence/display/uma/Working+Drafts">
        <front>
          <title>UMA Requirements</title>

          <author initials="C." surname="Scholz">
            <organization>Kantara Initiative</organization>
          </author>

          <date year="2010" />
        </front>
      </reference>

      <reference anchor="UMA-UC"
                 target="http://kantarainitiative.org/confluence/display/uma/UMA+Scenarios+and+Use+Cases">
        <front>
          <title>UMA Explained</title>

          <author initials="H." surname="Akram">
            <organization>Kantara Initiative</organization>
          </author>

          <date year="2010" />
        </front>
      </reference>

      <reference anchor="UMA-Reqs"
                 target="http://kantarainitiative.org/confluence/display/uma/UMA+Requirements">
        <front>
          <title>UMA Requirements</title>

          <author initials="E." surname="Maler">
            <organization>Kantara Initiative</organization>
          </author>

          <date year="2010" />
        </front>
      </reference>
    </references>
  </back>
</rfc>