This specification draft expired and marked as obsolete by its author. Implementers are discouraged from implementing products using the methods described in this specification. No update is expected. This draft will be replace by the OAuth 2.0 effort in the IETF.

March 31, 2008
Eran Hammer-Lahav


OAuth Discovery 1.0 Draft 2

Abstract

OAuth Core 1.0 defines a protocol for delegating user access to Consumer applications without sharing the user’s private credentials. The protocol specifies a set of configuration values that enable Consumers to find and communicate with Service Providers. However, OAuth Core leaves the process of communicating that information undefined.

The discovery protocol provides a way for Consumers to receive the required configuration data from Service Providers in a machine-readable format. It creates an extendable framework for communicating current and future services.

The protocol has been designed to keep the workflow as simple as possible, use existing discovery practices, and maintaining strong flexibility, allowing Service Providers to structure their configuration as needed.



Table of Contents

1.  Notation and Conventions
2.  Definitions
3.  Scope and Limitations
4.  Discovery Workflow
5.  Configuration Retrieval
6.  Descriptor Structure
    6.1.  OAuth Endpoints
    6.2.  Consumer Identity
    6.3.  Request Parameter Methods
    6.4.  Request Signature Methods
7.  Establish Consumer Identity
    7.1.  Static Allocation
    7.2.  Out-of-band Allocation
Appendix A.  Appendix A - Example
8.  References
§  Author’s Address




1.  Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119] (Bradner, B., “Key words for use in RFCs to Indicate Requirement Levels,” .). Domain name examples use [RFC2606] (Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” .).

Unless otherwise noted, this specification is written as a direct continuation of [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .), inheriting the definitions and guidelines set by it.



2.  Definitions

OAuth Discovery:
A general name for the workflow described in this specification.
OAuth Configuration:
The information needed by Consumers to perform the workflow defined in [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) successfully and access Protected Resources.
OAuth Descriptor
The XRDS-Simple XRD element containing the OAuth Configuration, located by performing discovery on the Protected Resource URI.
Consumer Identity:
The Consumer Key, Consumer Secret, and any other information used to establish an identity for the Consumer such as public key.



3.  Scope and Limitations

While a fully automated discovery process of authentication, authorization, and service utilization is a highly desirable, OAuth Discovery is inheritably limited. OAuth does not address the methods in which Protected Resources are accessed. Without clear standards of the Protected Resources methods, any discovery protocol will eventually require some form of manual interaction.

In many cases, Consumer Key allocation requires human interaction. This is done for legal, compliance, or other reasons, which hinder automated discovery without prior manual registration.

However, combined with other specifications, the entire process can be fully automated from authentication, through authorization, to service utilization. While OAuth Discovery alone cannot provide a fully automated workflow, it strongly enables it.

OAuth Discovery is designed to address two workflows:

Service Providers MUST support automatic initiation, and MAY support out-of-band initiation by providing the information needed through documentation or other means.



4.  Discovery Workflow

The OAuth Discovery workflow follows the process defined in [XRDS‑Simple 1.0] (Hammer-Lahav, E., “XRDS-Simple 1.0,” .) to locate and parse the machine-readable information containing the necessary OAuth Configuration. Each Protected Resource supporting OAuth Discovery MUST identify the location of its OAuth Configuration contained within a Resource Description Document (Hammer-Lahav, E., “XRDS-Simple 1.0,” .) [XRDS‑Simple 1.0].

Unless provided by the Service Provider out-of-band, the Consumer uses the Protected Resource URI to retrieve the resource’s description which in turn points to the location of the associated OAuth Configuration. The OAuth Configuration MAY reside in the same document or in a separate document. While both Service Providers and Consumers play a role in the workflow, it is focused on actions performed by Consumers. The workflow includes the following steps:

  1. Retrieve OAuth Configuration.
  2. Parse OAuth Descriptor.
  3. Establish Consumer Identity.

Once all steps have been performed, the Consumers have the required information needed to obtain an Access Token as defined in [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) sections 6 and access the Protected Resource following the workflow defined in [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) sections 7.



5.  Configuration Retrieval

The Consumer retrieves the Resource Description Document using the Protected Resource URI by following the retrieval protocol defined in [XRDS‑Simple 1.0] (Hammer-Lahav, E., “XRDS-Simple 1.0,” .) section 5. If the retrieval protocol is successful, the Consumer retrieves the Resource Description Document. If the retrieval protocol fails, it SHALL be assumed that the Service Provider does not support OAuth Discovery.

Using the selection protocol defined in [XRDS‑Simple 1.0] (Hammer-Lahav, E., “XRDS-Simple 1.0,” .) section 7.2, the Consumer finds the location of the OAuth Configuration, identified by the service type http://oauth.net/discovery/1.0, and specified by the URI element. The URI element MUST include an absolute HTTP(S) URI or a URI fragment only. If the URI includes only a fragment, it indicated an internal reference to an XRD element within the same document.

If the OAuth Configuration location is in another document, the Consumer retrieves the OAuth Configuration XRDS-Simple document following the workflow defined in [XRDS‑Simple 1.0] (Hammer-Lahav, E., “XRDS-Simple 1.0,” .) section 5.2. Once the OAuth Configuration document has been obtained, the Consumer locates the referenced XRD element using the workflow defined in [XRDS‑Simple 1.0] (Hammer-Lahav, E., “XRDS-Simple 1.0,” .) section 7.1. The selected XRD element is referred to as the OAuth Descriptor.



6.  Descriptor Structure

The OAuth Descriptor - a valid XRDS-Simple XRD element - contains the OAuth Configuration indentifying the OAuth endpoints and their attributes. The OAuth Descriptor define services which provide the necessary information needed to interact with an OAuth-enabled Service Provider.

Each OAuth endpoint and property is assigned a type identifier used by Service Providers to document their OAuth implementation, and by Consumers to lookup endpoints and their properties. XRDS-Simple provide a simple mechanism for specifying the type and characteristics of resources, which in this case are the OAuth endpoints.

The OAuth Descriptor MUST include at least one Service element for each of the OAuth Endpoints (OAuth Endpoints). The OAuth Descriptor MUST include at least one of the two types defined in Section 6.2 (Consumer Identity), unless another method of obtaining a Consumer Identity is specified using and extension type. The types defined in Section 6.1 (OAuth Endpoints) and Section 6.2 (Consumer Identity) are all mutually exclusive, and Service elements MUST NOT include more than one of these types. Other types MAY be combined with the types defined in the two sections.

Service elements for each of the OAuth Endpoints (OAuth Endpoints) MUST include at least one type from Section 6.3 (Request Parameter Methods) and one type from Section 6.4 (Request Signature Methods), unless otherwise specific, or other request parameter methods and request signature methods are specified using an extension type.



6.1.  OAuth Endpoints

To identify the OAuth endpoints, each is given a unique type identifier:

Request Token:
http://oauth.net/core/1.0/endpoint/request - [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 6.1.1. Service elements of this type MUST include at least one URI child element, and their HTTP method defaults to POST unless a simple:httpMethod attribute provided.
User Authorization:
http://oauth.net/core/1.0/endpoint/authorize - [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 6.2.1. Service elements of this type MUST include at least one URI child element, and use HTTP GET even if no simple:httpMethod attribute provided. MUST NOT specify other HTTP methods. The User Authorization endpoint does not support signature methods and types from Section 6.4 (Request Signature Methods) SHOULD be omitted or ignored.
Access Token:
http://oauth.net/core/1.0/endpoint/access - [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 6.3.1. Service elements of this type MUST include at least one URI child element, and their HTTP method defaults to POST unless a simple:httpMethod attribute provided.
Protected Resource:
http://oauth.net/core/1.0/endpoint/resource - [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 7. If a Service element of this type contains any URI child elements, they SHALL be ignored for the purpose of OAuth Discovery.



6.2.  Consumer Identity

OAuth requires a pre-arranged Consumer Identity in order to obtain access. OAuth Discovery defines two service types for documenting the methods in which Consumer Identity can be obtained:

Static allocation:
http://oauth.net/discovery/1.0/consumer-identity/static - Includes the Consumer Identity within the OAuth Descriptor, as defined in Section 7.1 (Static Allocation).
Out-of-band allocation:
http://oauth.net/discovery/1.0/consumer-identity/oob - Documents a human-accessible endpoint through which a Consumer Identity MAY be obtained as defined in Section 7.2 (Out-of-band Allocation).



6.3.  Request Parameter Methods

These types are used to document the request parameters methods supported by the Service Provider as defined in [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 5.2:

Authentication Header:
http://oauth.net/core/1.0/parameters/auth-header.
HTTP POST Body:
http://oauth.net/core/1.0/parameters/post-body.
URI Query Parameters:
http://oauth.net/core/1.0/parameters/uri-query.



6.4.  Request Signature Methods

These types are used to document the signature methods supported by the Service Provider:

HMAC-SHA1:
http://oauth.net/core/1.0/signature/HMAC-SHA1 - [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 9.2.
RSA-SHA1:
http://oauth.net/core/1.0/signature/RSA-SHA1 - [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 9.3.
PLAINTEXT:
http://oauth.net/core/1.0/signature/PLAINTEXT - [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 9.4.



7.  Establish Consumer Identity

[OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) requires Consumers to establish an Consumer Identity prior to making OAuth requests, and leaves the methods of establishing the Consumer Identity unspecified. The process of establishing a Consumer Key and Consumer Secret can be complex and can also require manual human interaction for legal, compliance, and other reasons. However, there are some cases in which a simple Consumer Identity is sufficient or not needed at all.

OAuth Discovery defines two Consumer Identity allocation scenarios: a statically allocated Consumer Identity or an endpoint through-which a Consumer Identity MAY be established out-of-band. If a Consumer Identity has been established using the out-of-band method, the Consumer SHOULD note the URI used, and check in future requests if other Protected Resources point to the same URI for obtaining a Consumer Identity. If the same URI used to obtain a Consumer Identity is referenced by another Protected Resource, the Consumer MAY use that identity to obtain an Access Token for the other resource.



7.1.  Static Allocation

Static Consumer Identity allocation is used when no Consumer Identity is needed. In this case the Service Provider does not desire tracking individual Consumers, or might provide limited accessibility to unidentified Consumers. In this scenario, the Service Provider assigns a default Consumer Identity in the OAuth Descriptor.

Static allocation is identified using the service type: http://oauth.net/discovery/1.0/consumer-identity/static. The Service element MUST include at least one LocalID element with the Consumer Key encoded per [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 5.1. Any URI element included SHALL be ignored. Static allocation does not include a Consumer Secret which is defined as an empty string. For example:

      <Service>
        <Type>http://oauth.net/discovery/1.0/consumer-identity/static</Type>
        <LocalID>0685bd9184jfhq22</LocalID>
      </Service>



7.2.  Out-of-band Allocation

Out-of-band Consumer Identity allocation is used when the Service Provider requires a Consumer registration process that cannot be performed automatically or has unique requirements the Consumer Developer must comply with. OAuth Discovery does not address this scenario expect for enabling the Service Provider to provide a human-readable endpoint, and associating Consumer Identities obtained via that endpoint to its URI, enabling Consumer Identity reusability. This allows Consumer to use OAuth Discovery with manually pre-established Consumer Identities.

Out-of-band allocation is identified using the service type: http://oauth.net/discovery/1.0/consumer-identity/oob. The Service element MUST include at least one URI element. If no HTTP method is specified, the URI method defaults to GET. The result value of the request is undefined. For example:

      <Service>
        <Type>http://oauth.net/discovery/1.0/consumer-identity/oob</Type>
        <URI>http://sp.example.com/consumer_apply</Type>
      </Service>



Appendix A.  Appendix A - Example

This example demonstrate a simple Resource Description Document in which the Protected Resource’s descriptor points to the OAuth Configuration contained within the same document, and Consumer Identity allocation is provided statically. Each of the OAuth HTTP endpoints support the HMAC-SHA1 signature method, while HTTPS endpoints use the PLAINTEXT signature method. The Service Provider in this example supports sending request parameters via URI query and the Authorization header, except for requesting User authorization which only supports the URI query method. The Service Provider does not support parameters in the HTTP body.

  <?xml version="1.0" encoding="UTF-8"?>
  <XRDS xmlns="xri://$xrds">
    <XRD xml:id="oauth" xmlns:simple="http://xrds-simple.net/core/1.0" xmlns="xri://$XRD*($v*2.0)" version="2.0">
      <Type>xri://$xrds*simple</Type>
      <Expires>2008-12-31T23:59:59Z</Expires>
      <Service priority="10">
        <Type>http://oauth.net/core/1.0/endpoint/request</Type>
        <Type>http://oauth.net/core/1.0/parameters/auth-header</Type>
        <Type>http://oauth.net/core/1.0/parameters/uri-query</Type>
        <Type>http://oauth.net/core/1.0/signature/PLAINTEXT</Type>
        <URI>https://api.example.com/session/request</URI>
      </Service>
      <Service priority="10">
        <Type>http://oauth.net/core/1.0/endpoint/authorize</Type>
        <Type>http://oauth.net/core/1.0/parameters/uri-query</Type>
        <URI>https://api.example.com/session/login</URI>
      </Service>
      <Service priority="10">
        <Type>http://oauth.net/core/1.0/endpoint/access</Type>
        <Type>http://oauth.net/core/1.0/parameters/auth-header</Type>
        <Type>http://oauth.net/core/1.0/parameters/uri-query</Type>
        <Type>http://oauth.net/core/1.0/signature/PLAINTEXT</Type>
        <URI>https://api.example.com/session/activate</URI>
      </Service>
      <Service priority="10">
        <Type>http://oauth.net/core/1.0/endpoint/resource</Type>
        <Type>http://oauth.net/core/1.0/parameters/auth-header</Type>
        <Type>http://oauth.net/core/1.0/parameters/uri-query</Type>
        <Type>http://oauth.net/core/1.0/signature/HMAC-SHA1</Type>
      </Service>
      <Service priority="10">
        <Type>http://oauth.net/discovery/1.0/consumer-identity/static</Type>
        <LocalID>0685bd9184jfhq22</LocalID>
      </Service>
    </XRD>
    <XRD xmlns="xri://$XRD*($v*2.0)" version="2.0">
      <Type>xri://$xrds*simple</Type>
      <Service priority="10">
        <Type>http://oauth.net/discovery/1.0</Type>
        <URI>#oauth</URI>
      </Service>
    </XRD>
  </XRDS>



8. References

[OAuth Core 1.0] OAuth, OCW., “OAuth Core 1.0.”
[RFC2119] Bradner, B., “Key words for use in RFCs to Indicate Requirement Levels,” RFC 2119.
[RFC2606] Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” RFC 2606.
[XRDS-Simple 1.0] Hammer-Lahav, E., “XRDS-Simple 1.0.”



Author’s Address

  Eran Hammer-Lahav
  Hueniverse
Email:  eran@hueniverse.com