| Note | ||
|---|---|---|
| ||
This is a proposal that puts UMA's core protocol on a WRAP/hostmeta footing (it also simplifies the metadata discovery model as discussed in late February). It currently assumes that the reader is intimately familiar with WRAP, but if we accept this as a basis for future protocol work, it will gain many more examples and more explanation/context. Throughout this proposal, notes such as this one will be used to highlight issues and points of discussion.. Although it currently calls out to the WRAP I-D, the intent is to work with the IETF group working on OAuth 2.0 to ensure that it will meet our needs, either by allowing our needed extension and profiling points, or by incorporating solutions we have invented out of that are of interest to others as well. |
| Table of Contents | ||||||||
|---|---|---|---|---|---|---|---|---|
|
...
- User registers host at an authorization manager (using [hostmeta], and profiling [WRAP] to define how a host accepts an authorizing user's chosen authorization manager as an access decision-maker)
- Requester gets access token from authorization manager (extending WRAP to define how the requester can satisfy user policy by providing additional information to the AM)
- Requester wields
- Requester gets access token from authorization manager
- Requester wields access token at host to gain access (extending WRAP to allow the host to validate the token at the authorization manager)
Notational Conventions
Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC2119].
...
Terms are capitalized here for clarity of definition, but are lowercase in the main body of the specification for readability. Note that in this specification, the word "profile" is used not only to refer to WRAP client [WRAP] (all WRAP references are temporary; OAuth 2.0 is the goal) profiles, but also for the result of choosing one out of several options in a referenced specification in order to increase interoperability.
...
Token Validation URL: The URL at an Authorization Manager that a Host uses to validate an access token.
Authorization Bootstrap URL: The URL at an Authorization Manager that a Requester uses to discover the Authorization Negotiation URL to use.
Authorization Negotiation URL: The URL at an Authorization Manager at which a Requester negotiates for authorization and receives refresh tokens and initial access tokens; an UMA-defined variant of the WRAP Access Token URL.
Protocol Steps
Step 1: User registers host at AM
...
Protocol Steps
Step 1: User registers host at AM
This step involves an embedded instance of WRAP within the main UMA flow. It profiles WRAP to define how a host comes to trust an authorization manager chosen by the authorizing user, and how it learns which access token formats are supported. The user introduces the host (as a WRAP Client) to the AM (as a WRAP Authorization Server) using any of the "user delegated" profiles. This step has the following substeps:
...
The AM MUST provide metadata at that location that offers a WRAP user authorization URL, documents the one or more access token formats that and claim formats that the AM generates, and provides an authorization bootstrap access token URL and token validation URL, in the following general pattern:
| Note | ||
|---|---|---|
| ||
This needs to be made more rigorous, and ideally we can ask the referenced specs (where they are still in process) to define suitable "rel" values to be used in hostmeta metadata. This example is for discussion. Define the UMA labeling URIs shown below somewhere in the spec. |
| Code Block | ||||
|---|---|---|---|---|
| ||||
<Link rel="http://tools.ietf.org/html/draft-hardt-oauth-01"
href="https://am.example.com/wrapuserauthz">
/> <Title>WRAP User Authorization URL</Title>
</Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/AccessTokenFormats"
href="http://docs.oasis-open.org/security/saml/v2.0/sstc-saml-approved-errata-2.0.pdf">
<Title>UMA Access Token Format produced />by this AM</Title>
</Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/AuthzBootstrapURLClaimFormats"
href="httpshttp://amwww.example.com/umaauthzbootstrap" />json.org">
<Title>UMA Claim Format produced by this AM</Title>
</Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/TokenValidationURLClaimFormats"
href="httpshttp://amdocs.example.com/umatokenvalidation" />
|
The user authorization URL, authorization bootstrap URL, and token validation URL MUST be HTTPS URLs.
| Note | ||
|---|---|---|
| ||
WRAP doesn't seem to say HTTPS is required for the user authorization URL; is this a bug in the WRAP spec? If not, is it a good idea for us to profile it in this way? Finally, is this the right place to say HTTPS is required for all these URLs? |
The host MUST follow one of the WRAP "user delegation" profiles in obtaining the user's authorization to use that AM to protect the resources it hosts on behalf of that user.
| Note | ||
|---|---|---|
| ||
If the host wants to give the user the option to protect some resources hosted there with one AM, and other resources hosted there with another AM, it can do this independently of the protocol. This will have UX implications on each host and each AM. (This is true of the existing UMA spec as well.) |
Step 2: Requester gets access token from AM
This step involves the AM and requester in the role of WRAP Authorization Server and Client respectively, using the "client account and password" profile with anonymous credentials. This step extends WRAP to allow for negotiation prior to authorization; specifically, the extensions allow the AM to specify claims it needs from the requester and for the requester to make the appropriate responses. It also profiles WRAP to specify how the requester must supply wrap_scope values in asking for authorization.
| Note | ||
|---|---|---|
| ||
We're not sure the "client account and password" profile with anonymous credentials is the correct approach. But note that this WRAP profile requires a refresh token, and we do intend to require a refresh token to be produced in any case. And we do want to allow "arbitrary" requesters to approach AMs for our Internet-scale ecosystem goals. What is the right way to achieve this? If this is roughly right, should WRAP/OAuth 2.0 dictate how anonymous credentials are provided, or do we have to? |
This step has the following substeps:
...
oasis-open.org/security/saml/v2.0/sstc-saml-approved-errata-2.0.pdf">
<Title> UMA Claim Format produced by this AM</Title>
</Link>
<Link rel="http://tools.ietf.org/html/draft-hardt-oauth-01"
href="https://am.example.com/wrapaccesstokenurl">
<Title>WRAP Access Token URL</Title>
</Link>
<Link rel="http://kantarainitiative.org/confluence/display/uma/TokenValidationURL"
href="https://am.example.com/umatokenvalidation">
<Title>WRAP User Authorization URL</Title>
</Link>
|
The user authorization URL and token validation URL MUST be HTTPS URLs.
| Note | ||
|---|---|---|
| ||
WRAP doesn't seem to say HTTPS is required for the user authorization URL; is this a bug in the WRAP spec? If not, is it a good idea for us to profile it in this way? Finally, is this the right place to say HTTPS is required for all these URLs? |
The host MUST follow one of the WRAP "user delegation" profiles in obtaining the user's authorization to use that AM to protect the resources it hosts on behalf of that user. If the host uses the token validation URL to offload token validation in step 3, it will use any access token acquired in this step to make an authorized call to that URL.
Step 2: Requester gets access token from AM
This step involves the AM and requester in the role of WRAP Authorization Server and Client respectively. If the requester is acting on behalf of a requesting party that is a corporation or other legal person, it MUST use one of the "autonomous client" profiles in this phase. If the requester is acting on behalf of a requesting party that is a human being, it MUST use one of the "user delegation" profiles in this phase.
This step extends WRAP to add a third possible response from the AM (WRAP Authorization Server) in addition to successful vs. unsuccessful access token responses: the third option is to ask for more information from the requesting party, in the form of claims. It also profiles WRAP (all of its relevant profiles) to specify how the requester must supply wrap_scope values in asking for authorization.
This step has the following substeps:
- (optional) Requester attempts to access resource at host and is given AM's access token URL
- Requester visits AM's access token URL, providing desired scope of access
- AM either provides access token (and refresh token), rejects authorization, or asks requester for claims
- Requester provides claims if as requested, until access token request either succeeds or fails definitively
...
If the requester knows, by whatever means, the authorization bootstrap access token URL for the AM that is protecting the desired resource without first approaching the host, it MAY proceed directly to that URL. Alternatively, it MAY attempt to access the resource directly at the host; if it does not present an access token, the host MUST respond with a WRAP challenge, using the "HTTP 401 Unauthorized" code and the HTTP header "WWW-Authenticate: WRAP" and providing the authorization bootstrap access token URL.
...
...
Provide examples – and explain exactly in what way the URL is provided.
The requester submits a GET request to the authorization bootstrap access token URL, providing the desired scope of access in the "wrap_scope" parameter. The value of this parameter is a URL-encoded JSON array of one or more objects, each consisting of at least two members: a "method" string with an HTTP access method value and a "uri" string with a resource URI value (which MAY have a "*" as the last path component in order to indicate all resources available in that directory on the host). If any additional members are present, they do not affect the interpretation of these two.
...
| Code Block |
|---|
[{"method": "GET", "uri": "http://example.com/foo"},
{"method": "POST", "uri": "http://example.com/bar"}]
|
| Note | ||
|---|---|---|
| ||
To be added: A simple wildcard mechanism to allow for encompassing the entire contents of some root path. Is it as simple as reserving the * character and allowing it to replace any single path component? |
The AM responds with an authorization negotiation URL for a short-lived resource created specifically for this attempt to get authorization to access this particular set of resources using these particular methods. The authorization negotiation URL MUST be an HTTPS URL. To manage security risks, the AM MAY delete the resource at any time, requiring the requester to start at the beginning even if the negotiation was not successfully concluded, but it is assumed that the negotiation will be conducted with alacrity.
| Note | ||
|---|---|---|
| ||
The bootstrap-to-negotiation URL mechanism exists to allow for extreme dynamicism and lightweightness of the requester's appearance authentication at the AM, while protecting the security of the interaction. Is it necessary? What are alternatives?": "http://example.com/*"}]
|
The requester performs a GET on the authorization negotiation access token URL, using the standard HTTP "Accept" header to express the acceptable media type(s) of any claims-required list. The AM responds in one of three ways:
...
| Note | ||
|---|---|---|
| ||
Need lots of examples for all of this. Also, note that WRAP forces clients to use POST on access token URLs and refresh token URLs; is it bad that we're using GET on a species of access token URL, or does its short-lived nature assuage the concern that this restriction was intended to addresscan we use GET in the way described here? |
On receiving a claims-required list, the requester performs a POST to the authorization negotiation URL supplying a claims document, specifying its type in the "Content-Type" header. The AM rejects the document if it does not recognize its type. If the AM accepts the document, it responds with a successful or unsuccessful access token response as detailed above, or with another claims-required response.
...
This step involves the requester and host in the role of WRAP Client and Protected Resource respectively. This step extends WRAP to allow the host to validate the token at the authorization manager. This step has the following substeps:
- Requester presents access token in attempting to access resource
- Host uses AM's token validation URL to ask for validation
- Host either allows access or generates an error
The substep detail is as follows.
The requester presents the access token to the host
- Requester presents access token in attempting to access
...
| title | Note |
|---|
...
- resource
- Host either uses AM's token validation URL to ask for validation or validates the token locally
- Host either allows access or generates an error
The substep detail is as follows.
The requester presents the access token to the host in attempting to access the desired resource, as defined in WRAP. The host either validates the token locally or performs a POST of the access token to the AM's token validation URL (wielding the access token it acquired in step 1 to show that the request is authorized), providing a description of the resource and method attempted.
The AM responds in one of two ways: the token is valid, or the token is invalid. Correspondingly, the host either allows access or rejects the requesters' attempt. The requester is free to seek authorization or to refresh its access token at the AM if it feels the rejection was in error.
| Note | ||
|---|---|---|
| ||
Obviously this is just the highest-level sketch of what needs to happen! This needs to be fleshed out. (E.g., the wrap_scope format could be reused here, without any wildcards.) |
References
| Anchor | ||||
|---|---|---|---|---|
|
http://www.ietf.org/rfc/rfc2119.txt
...
| Anchor | ||||
|---|---|---|---|---|
|
http://tools.ietf.org/html/draft-hammer-hostmeta
| Anchor | ||||
|---|---|---|---|---|
|
http://wiki.idcommons.net/Claim