[Wg-uma] XRD for resource discovery & description

Paul C. Bryan email at pbryan.net
Wed Oct 21 19:02:02 EDT 2009


Hi all:

On tomorrow's conference call, I'd like to discuss using XRD to support
resource discovery and metadata. By way of example,
early-super-pre-drafty host registration flow description follows.

Paul


________________________________________________________________________

n. Host registration [excerpt]

Host registration is the act of an authorizing user introducing a host
to an authorization manager. Once registered, a host can request access
control decisions from the authorization manager for resources being
accessed by requesting services.


n.1 User introduction

A host is explicitly introduced to an authorization manager by an
authorizing user via an identifier that can be resolved via LRDD to an
XRD descriptor. The XRD descriptor is obtained by the host via HTTP, and
contains a link to the authorization manager host container resource.
Example (namespaces supressed for simplicity): 

  <XRD>
    <Subject>http://copmonkey.com/</Subject>
    <Expires>2009-10-23T23:59:59Z</Expires>
    <Type>http://uma-wg.net/core/1.0/am</Type>
    <Link>
      <Rel>http://uma-wg.net/core/1.0/am/host</Rel>
      <URI>http://copmonkey.com/host/</URI>
    </Link>
    ...
  </XRD>


n.2 Access token issuance
The host resolves the URI of the host container resource, and sends an
HTTP POST request to that resource, to request the creation of a new
host resource. Example request:


  POST http://copmoney.com/host/ HTTP/1.1
  ...


Without any OAuth headers included in the request, an OAuth challenge is
returned. Example response:


  HTTP/1.1 401 Unauthorized
  WWW-Authenticate: OAuth realm="copmonkey", provider="https://copmonkey.com/oauth/"
  ...


The "provider" challenge (per OAuth discovery "sneak-peek") parameter
provides the URI of the OAuth provider used to authorize access to the
host container. The host performs LRDD discovery on this resource to
resolve its XRD descriptor, and its descriptor is obtained. Example
descriptor:


  <XRD>
    <Subject>https://copmonkey.com/oauth/</Subject>
    <Expires>2009-10-23T23:59:59Z</Expires>
    <Type>http://oauth.net/core/1.0/signature/HMAC-SHA1</Type>
    <Link>
      <Rel>http://oauth.net/discovery/1.0/consumer-identity/static</Rel>
      <LocalID>53032297b44847ed</LocalID>
    <Link>
      <Rel>http://oauth.net/core/1.0/endpoint/initiate</Rel>
      <URI>https://copmonkey.com/oauth/initiate/</URI>
    </Link>
    <Link>
      <Rel>http://oauth.net/core/1.0/endpoint/authorize</Rel>
      <URI>https://copmonkey.com/oauth/authorize/</URI>
    </Link>
    <Link>
      <Rel>http://oauth.net/core/1.0/endpoint/token</Rel>
      <URI>https://copmonkey.com/oauth/token/</URI>
    </Link>
  </XRD>


In this example, the consumer identity is statically allocated (no
consumer identity is needed), and endpoints are established for OAuth
protocol initiation, user request authorization and access token
issuance. How OAuth is negotiated is out-of-scope for UMA protocol,
except that OAuth service discovery is expected to be supported.

The host proceeds to negotiate the issuance of an access token by
initating OAuth protocol flow (issuance of request token), user request
authorization (via authorization manager user interface to user), and
access token request.


n.3 Request host resource creation (w. signature)

Now that the host has an access token it can use to sign requests, it
re-issues the original POST request from n.2 above to create a host
resource in the authorization manager, signed. Example request:


  POST http://copmoney.com/host/ HTTP/1.1
  Authorization: OAuth realm="copmonkey", oauth_consumer_key="53032297b44847ed",
   oauth_token="2f5fa6f0613942d9", oauth_signature_method="HMAC-SHA1",
   oauth_signature="...", oauth_timestamp="...", oauth_nonce="...",
   oauth_version="1.0"
  ...


The authorization manager indicates the resource has been successfully
created, with a new identifier:


    HTTP/1.1 201 Created
    Location: https://copmonkey.com/host/cbab2239-7528-4056-8aac-717d154e3972/
    ...


n.4 Retrieve host resource metadata

The host can now perform discovery on this new host resource (via LRDD
and GET request signed with OAuth) to get an XRD descriptor. Example
descriptor:


    <XRD>
      <Subject>https://copmonkey.com/host/cbab2239-7528-4056-8aac-717d154e3972/</Subject>
      <Expires>2009-11-22T23:59:59Z</Expires>
      <Type>http://uma-wg.net/core/1.0/am/host/instance</Type>
      <Link>
        <Rel>http://uma-wg.net/core/1.0/am/host/handle</Rel>
        <LocalID>cbab2239-7528-4056-8aac-717d154e3972</LocalID>
      <Link>
      <Link>
        <Rel>http://uma-wg.net/core/1.0/am/host/decision</Type>
        <URI>https://copmonkey.com/host/decision/</URI>
      </Link>
    </XRD>


This descriptor contains the handle that the host should advertise to
requesting services as well as the resource to which the host should
direct requests for access control policy decisions. The host can report
to the authorizing user that host registration was successful.


n. References [excerpt]


[LRDD] 
Hammer-Lahav: "Link-based Resource Descriptor Discovery 03", March 2009.
http://tools.ietf.org/html/draft-hammer-discovery-03

[XRD]
Hammer-Lahav, Noris: "Extensible Resource Descriptor (XRD) Version 1.0",
October 2009
http://www.oasis-open.org/committees/download.php/34724/xrd-1.0-wd09.html

[HTTP]
Fielding, Gettys, Mogul, Frystyk, Masinter, Leach, Berners-Lee:
"Hypertext Transfer Protocol — HTTP/1.1", RFC 2616, June 1999.
http://tools.ietf.org/html/rfc2616


________________________________________________________________________
Discussion points:

1. XRD (really, any description/discovery mechanism) adds overhead to
the protocol. If we hard-coded resource taxonomy and schema into the
protocol, it would be simpler, yet far less flexible or extensible. On
balance, I'm definitely inclined to accept the added complexity given
the benefits.

2. LRDD is handy in that it can allow any practically any understood
identifier to be used for service resource discovery, including such
identifiers as email address and unqualified domain name. This could
legitimately ease user providing the location of authorization manager
without having to memorize or copy-paste a complex URL.

3. I find myself tempted to "abuse" XRD by using <Link> tags to specify
arbitrary name-value pairs. It seems ripe for this kind of "abuse". It's
certainly handy because I don't need to invent a schema to represent a
couple of entities when all I can do is include it in the XRD.
Rel=name=type, is actually handy.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://kantarainitiative.org/pipermail/wg-uma/attachments/20091021/12fc6177/attachment.html 


More information about the Wg-uma mailing list