Page Comparison

...

1. The host looks up the authorization manager metadata and learns about API endpoints and formats supported by the AM
2. The host obtains OAuth client credentials and a the location of the resource registration API from the authorization manager.
3. The host obtains an access token from the authorization manager by following the OAuth 2.0 web server flow.
4. The host registers the authorization user's resources with the AM by using the resource registration API.

host looks up the authorization manager metadata

...

The host obtains OAuth client credentials and the location of the resource registration API from the authorization manager

The goal of this sub step is to provide the host with a client id, optionally a client secret and the URL of the resource registration API of the AM.

There are two ways to provide this:

1. The host has to pre-register with the AM in order to use it. In this case all of this information is provided in a way which is beyond the scope of this specification. The most widespread method with OAuth is to enter it manually.
2. The host is not pre-registered and a dynamic association needs to be created between host and AM. In this case the information is obtained with the process described below.

It is up to the AM to decide whether it allows only pre-registered hosts, only dynamic associated ones or both.

If the association needs to be done dynamically, the following process is used which is similar to the one used in OpenIDConnect (http://openidconnect.com/#associations).

If the client does not have a valid client identifier and secret, it shall make the following HTTPS "POST" request to the server's host token endpoint URL (see metadata lookup) with the following REQUIRED parameters:

type - "client_associate"
redirect_uri - The URI the host wishes to register with the server for receiving OpenID responses.

• • • from here the same, still needs work ***

The host gets a host access token from the AM that represents the approval of the authorizing user for the host to trust this AM for protecting the resources it manages for this user.

NOTE: The host is free to offer the option to protect any subset of the user's resources using different AMs or other means entirely; any such partitioning is outside the scope of this specification.

The host MUST use the [OAuth20] web server flow (@@TBS: subsequently profile it to use UMA recursively for claims-getting purposes?), utilizing the host_user_uri and host_token_uri endpoints. The host acts in the role of an OAuth client; the authorizing user acts in the role of an OAuth end-user resource owner; and the AM acts in the role of an OAuth authorization server.

If the host has not already received client credentials from the AM prior to entering the web server flow, it MUST wield the client_id "uma_host_anonymous_client" and no client_secret (@@TBS: Explain how to do dynamic association to get unique client credentials).

Host supplies resource details to AM

Once the host has received an access token, it MAY, immediately or at any time until user authorization is revoked, wield the token at the AM's host_resource_details_uri endpoint to POST an XRD (@@TBS: JRD eventually?) structure to the AM describing the authorizing user's resources currently managed at that host in order to assist the AM in letting the authorizing user configure policies specific to those resources.In order for the host to initiate an OAuth flow to retrieve an access token for the resource registration API and the token verification API, it needs to have a client identifier and optionally a client secret. How this is transferred is beyond the scope of the OAuth specification and usually a manual process of preregistration and transferring this information is used.

In this step the host is the OAuth client and the authorization manager is the OAuth authorization server. For User Managed access the authorization server MUST provide the client identifier, an OPTIONAL client secret and the URI of the resource registration API which can be individual for each client.

In order to also allow for dynamic binding of a host and authorization manager, this specification also defines a protocol for dynamic and automatic client registration for OAuth.

Dynamic binding of OAuth clients

Terminology

Dynamic binding will be explained in OAuth terminology, using client and authorization server as the parties involved in the process.

Moreover the following terminology is used:

client registration endpoint: This is the URI defining the location of the client registration API. This is used by the client to send the required data for obtaining a client identifier and additional information

Discovery of client registration endpoint

In order for the client to obtain the URI of the client registration endpoint the authorization server MUST provide a hostmeta document containing a Link element with rel-value http://kantarainitiative.org/uma/client_registration_uri.

Overview

The dynamic client registration process works as follows:

1. The client send it's name and description as well as an optional image to the client registration endpoint
2. the authorization server checks the data and returns a JSON formatted document containing a client identifier, optional client secret and optionally additional information

The client registration flow

The client sends a client descriptor to the authorization server

The client creates a JSON document with the following keys/value pairs:

• the name of the client in the key name
• the URL to the service in the key name
• a short description of the client in the key description
• OPTIONAL: the URI to an icon representing the client in the key icon

An example client descriptor might look like follows:

{
    name : 'A wonderful image hoster',
    url: 'http://wonderfulimagehoster.com',
    description : 'as the name implies',
    icon: 'http://wonderfulimagehoster.com/logo.png'
}

The client then performs a POST request to the client registration endpoint using application/json as content type and sending the client descriptor in the body of the message.

The authorization server sends a response containing the client credentials

The authorization server can check the client descriptor as it requires and will then send either a success or an error response.

The success response is a JSON document consisting of a REQUIRED client identifier in the field client_id and an optional matching secret in the field client_secret.

An example response might look like this:

{
    client_id : 'AGSD)=bjchdb