Page Comparison

In order for a host to be able to delegate authorization to an authorization manager the authorizing user must introduce the host to the AM. The result of this step is the following:

 

# The host received metadata of the AM like OAuth 2.0 endpoints

# The host received an OAuth access token in order to verify requester access tokens in step 3 and as a representation of the user's decision to

 
# The AM received a list of protected resources on the host it is supposed to authorize on behalf of the user.

The following sub steps are performed in order to fulfill these requirements:

# The host looks up the authorization manager metadata and learns about API endpoints and formats supported by the AM

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

# The host obtains an access token from the authorization manager by following the OAuth 2.0 web server flow.

# The host registers the authorization user's resources with the AM by using the resource registration API.

{note

:title

=TODOs/Issues

}
* Host and AM can both decide if they work with the other side

* AM can refuse client id/secret. Needs error conditions

* How can the Host trust the AM? There are trust frameworks around for that these days

* no big difference between RRAPI to be in hostmeta or provisioned in step 2. Needs more input to get decision

* step 2 might be a separate specification.

* maybe in this specification the server can put in additional data specific to some namespace. Example:

{note}

h2. host looks up the authorization manager metadata

The very first step for the host is to lookup the metadata of the authorization manager. There are many possible ways for the authorizing user to provide the location of the authorization manager or it might be discovered by the host. The exact process is beyond the scope of this specification and it is up to the host to choose a method. For example it could simply ask for the URL of the AM or it could be contained on a physical magnetic-stripe card.

From the data provided or discovered the host then has to retrieve the hostmeta document as described in section 2 of \[[hostmeta|#hostmeta]. 

For example if the user gave "am.example.com" as the authorization manager's domain then the host would create the URL "https://am.example.com/.well-known/host-meta" and perform a GET request on it.

The authorization manager MUST provide a XRD 1.0 formatted document at the hostmeta location where it has to document the the following:

* One set of OAuth 2.0 URI endpoints for the host to use

* One set of OAuth 2.0 URI endpoints for any requester to use

* The location of the token verification API for the host to verify access tokens received from a requester in step 3.

 
* (The format of the access tokens to use)

* (The format of the claims formats the AM can generate)

{note

:title

• We might want to define that JRD can be used optionally, too.

 |

{note}


Link relationships for the OAuth 2.0 endpoints for the host:

|| Rel || Cardinality || HTTP Method(s)

 || Description |||
| http://kantarainitiative.org/confluence/display/uma/host_user_uri

 | Required | As defined by OAuth | Supplies the OAuth user_uri endpoint hosts should use to gather the consent of the authorizing user for a host-AM relationship.

 |
| http://kantarainitiative.org/confluence/display/uma/host_token_uri

 | Required | As defined by OAuth | Supplies the OAuth token_uri endpoint hosts should use to ask for a host access token.

 |
| http://kantarainitiative.org/confluence/display/uma/host_token_validation_uri

 | Optional | POST (with host access token)

 |Supplies the UMA endpoint hosts should use to request validation of access tokens presented to them by requesters in Step 3. MUST use HTTPS.

 |

Link relationships for the OAuth 2.0 endpoints for the requester:

|| Rel || Cardinality || HTTP Method(s)

 || Description |||
| http://kantarainitiative.org/confluence/display/uma/req_user_uri

 | Required | As defined by OAuth | Supplies the OAuth user_uri endpoint requesters should use to gather the consent of the authorizing user for user delegation flows in synchronous person-to-service sharing scenarios.

 |
| http://kantarainitiative.org/confluence/display/uma/req_token_uri

 | Required | As defined by OAuth | Supplies the OAuth token_uri endpoint requesters should use to ask for an access token in Step 2.

{code}


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


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. 

{note}
Should we really use a different name for the AM vs. AS? It can be confusing as we see here.
{note} 

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.

h3. Dynamic binding of OAuth clients


{note}
It probably really should be a separate specification
{note}


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

h4. 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}}}.


h4. Overview

The dynamic client registration process works as follows:

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


h4. The client registration flow

h5. 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}}}

{note}
probably we need more information but most of it should be optional to increase interoperability
{note}

An example client descriptor might look like follows:

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

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.

h5. 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:

{code}
{
    client_id : 'AGSD)=bjchdb