Step 1: User registers host at AM
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.
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.
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)
TODOs
- We might want to define that JRD can be used optionally, too.
The Property elements SHOULD be present in the hostmeta document:
to be clarified later
Property type |
Cardinality |
Meaning of Property element value |
|---|---|---|
| http://kantarainitiative.org/confluence/display/uma/token_formats | One or more |
Access token format produced by this AM. Options are (@@TBS). |
| http://kantarainitiative.org/confluence/display/uma/claim_formats | Zero or more |
Claim format supported by this AM. Options are (@@TBS). |
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. |
Example XRD document
<!-- Applies to both hosts and requesters -->
<Property
type="http://kantarainitiative.org/confluence/display/uma/token_formats">
saml
</Property>
<Property
type="http://kantarainitiative.org/confluence/display/uma/claim_formats">
json
</Property>
<!-- Host "authorization API" -->
<Link rel="http://kantarainitiative.org/confluence/display/uma/host_token_uri"
href="https://am.example.com/host/token_uri"></Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/host_user_uri"
href="https://am.example.com/host/user_uri"></Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/host_token_validation_uri"
href="https://am.example.com/host/token_validation_uri"></Link>
<!-- Requester token-getting endpoints -->
<Link rel="http://kantarainitiative.org/confluence/display/uma/req_token_uri"
href="https://am.example.com/requester/token_uri"></Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/req_user_uri"
href="https://am.example.com/requester/user_uri"></Link>
Host obtains authorizing user's consent to trust AM for access decisions
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.