...
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.
...
| Note | ||||||
|---|---|---|---|---|---|---|
| =
| }
* |||||
|
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)
...
| Note | ||||
|---|---|---|---|---|
| =TODOs}
* We might want to define that JRD can be used optionally, too.
{note}
The Property elements SHOULD be present in the hostmeta document:
{note:title=to be clarified later}
|| Property type || Cardinality || Meaning of Property element value ||
|
| |||
|
The Property elements SHOULD be present in the hostmeta document:
| Note | ||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||
|
Link relationships for the OAuth 2.0
...
endpoints
...
for
...
the
...
host:
...
Rel | Cardinality | HTTP Method(s) |
|---|
...
...
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. |
...
...
Required | As defined by OAuth | Supplies the OAuth token_uri |
...
endpoint |
...
hosts |
...
should |
...
use |
...
to |
...
ask |
...
for |
...
a |
...
host |
...
access |
...
token. |
...
...
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) |
|---|
...
...
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. |
...
...
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
| Code Block | ||||
|---|---|---|---|---|
| ||||
<!-- 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>
{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 {{ |
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. |
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
| Note |
|---|
It probably really should be a separate specification |
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:
- 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
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
| Note |
|---|
probably we need more information but most of it should be optional to increase interoperability |
An example client descriptor might look like follows:
| Code Block |
|---|
{
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.
...
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 Block |
|---|
{
client_id : 'AGSD)=bjchdb |