OAuth Discovery 1.0 Draft 1

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 the Service Provider. However, OAuth Core leaves the process of communicating that information undefined.

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

The protocol has been designed to keep the workflow as simple as possible, use existing discovery practices, and maintain 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.  Realms
5.  Discovery Workflow
    5.1.  Identify the Resource Realm
        5.1.1.  Service Providers
        5.1.2.  Consumers
    5.2.  Retrieve the Discovery Definition Document
    5.3.  Parse the Discovery Definition Document
        5.3.1.  Document Structure
        5.3.2.  Realm Definition Element
        5.3.3.  Service Types
        5.3.4.  Service Element
        5.3.5.  oauth:CustomParameters Element
        5.3.6.  oauth:RequestParameterMethods Element
        5.3.7.  oauth:RequestSignature Element
        5.3.8.  Append Attribute
        5.3.9.  Service Extensions
        5.3.10.  Parsing Process
    5.4.  Establish Consumer Identity
        5.4.1.  Static Allocation
        5.4.2.  Dynamic Allocation
        5.4.3.  Manual Allocation
        5.4.4.  Complex Consumer Realm
    5.5.  Establish User Access
Appendix A.  Appendix A - Examples
Appendix A.1.  Simple Discovery Definition Document
6.  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,” .) and OAuth extension examples use the URI prefix http://oauth.net/example/.

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.

Consumer Identity:

The Consumer Key, Consumer Secret, and any other information used to establish an identity for the Consumer such as public key.

Realm:

An absolute HTTP(S) URL used to group Protected Resources together by associating them to the URL. Realms allow sharing information across multiple Protected Resources.

Resource Realm:

Realm for sharing OAuth configuration across multiple Protected Resources.

User Realm:

Realm for sharing an Access Token across multiple Protected Resources.

Consumer Realm:

Realm for sharing a Consumer Identity across multiple Protected Resources.

Realm Definition:

An XRD element containing the Service Provider OAuth configuration, in a machine-readable format.

Discovery Definition Document:

An XRDS document which binds together Realm Definitions and other services, in a machine-readable format.

OAuth Endpoints:

The group of four request endpoints defined by [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) (Request Token, User authorization, Access Token, and Protected Resource).

3.  Scope and Limitations

While a fully automated discovery process of authentication, authorization, and services is a highly desired objective, OAuth Discovery is inheritably limited. 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.

OAuth Discovery does not address the methods in which Protected Resources are accessed. Without clear standards of the Protected Resources space, any discovery protocol will eventually require some form of external handling of the Protected Resources. However, combines with other specifications, the entire process can be fully automated from authentication, through authorization, to services.

OAuth Discovery is designed to accommodate two scenarios:

• Automated Initiation - If the requested Protected Resource endpoint is known, the Consumer attempts accessing it without the any authorization credentials, causing the request to fail. The failure reply contains the information needed to perform discovery. This scenario is similar to the HTTP Basic Authentication (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” .) [RFC2617] flow.
• Manual Initiation - The information needed to perform discovery is provided by the Service Provider in ways not specified by this specification. This information allows the Consumer to configure its OAuth resources automatically instead of hard-coding the OAuth endpoints and properties.

Service Providers MUST support Automated Initiation, and MAY support Manual Initiation by providing the information needed in documentation or other means.

4.  Realms

OAuth Discovery uses Realms to associate Protected Resources to a common configuration used for OAuth authentication. A Realm MUST be a valid endpoint URL pointing to an accessible resource using HTTP requests. Service Providers MAY put access restrictions on the Realm URL. In order for the Consumer to perform the OAuth Discovery workflow, the Consumer requests the resource at the Realm URL.

Each Protected Resource MUST be associated with a Resource Realm, which in turn identifies the resource's User Realm and a Consumer Realm. In order to enable complex configuration of Realms without complicating the workflow, a Protected Resource may omit an explicit User Realm or Consumer Realm association, allowing them to implicitly default to the value of the Resource Realm.

The User Realm and Consumer Realm inform the Consumer when established credentials MAY be reused between Protected Resources. Realms are valid values of the realm parameter as defined in [RFC2617] (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” .) section 1.2, but are more restrictive in their requirements and syntax.

5.  Discovery Workflow

The OAuth Discovery workflow centers around the retrieval and parsing of the Discovery Definition Document which is the machine-readable format of the [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) configuration. While both the Service Provider and Consumer play a role in the workflow, it is focused on actions performed by the Consumer. The workflow includes the following steps:

1. Identify the Resource Realm.
2. Retrieve the Discovery Definition Document.
3. Parse the Discovery Definition Document.
4. Establish Consumer Identity.
5. Establish User Access.

Once all steps have been performed, the Consumer has the required OAuth credentials to access the Protected Resource following the [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 7 workflow.

5.1.  Identify the Resource Realm

Service Providers are likely to offer multiple Protected Resources, and MAY choose to partition access to them. Partitioning is done by associating Protected Resources to a Resource Realm, a common unique URL. Each Resource Realm has its own Realm Definition contained within a Discovery Definition Document.

Service Providers identify the Resource Realm of each Protected Resource, which is used by the Consumers locate the Discovery Definition Document for that Realm.

5.1.1.  Service Providers

Service Providers MUST identify the Resource Realm of each Protected Resource when denying Consumer access due to lack of OAuth credentials. Service Providers MAY document Realm information via other means to enable Manual Initiation.

The Resource Realm is provided by at least one of the following methods in decreasing preference:

1. In the OAuth HTTP WWW-Authenticate header as defined in [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 5.4.2, using the xoauth_realm parameter.
2. In the OAuth HTTP WWW-Authenticate header realm parameter as defined in [RFC2617] (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” .).
3. In the xoauth_realm parameter sent as part of the HTTP response body as defined in [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 5.3.
4. In the HTTP response body contained within a <link> element as follow: <link rel="auth" type="application/xrds+xml" href="http://sp.example.com/" />, where the href attributes is the Resource Realm.

In case the Service Provider supports the OAuth HTTP Authorization Scheme, but does not support OAuth Discovery, the Consumer will fail to locate a valid Discovery Definition Document by requesting the resource at the Resource Realm URL.

5.1.2.  Consumers

When attempting to access a Protected Resource using OAuth, the Consumer MUST first identify the Resource Realm. This allows the Consumer to check if it has already performed OAuth Discovery on that Realm and can reused that configuration. Consumers MUST NOT use configuration obtained for one Resource Realm with another.

To obtain the Resource Realm, if it has not been provided as part of a Manual Initiation process, the Consumer attempts to access the Protected Resource by making a request to the Protected Resource endpoint without any OAuth credentials. The request will fail with the Service Provider indicating the Resource Realm in its response.

To identify the Realm, the Consumer MUST analyze the Service Provider response by searching in order the list of supported Realm containers (Service Providers) for a Realm value, and MUST stop as soon as the first Resource Realm is found.

5.2.  Retrieve the Discovery Definition Document

The Consumer retrieves the Discovery Definition Document from the Realm using the Yadis protocol as defined in [XRI Resolution 2.0] (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0 - Committee Draft 02,” .) section 6. If the Yadis protocol is successful, the Consumer obtains the Discovery Definition Document. If the Yadis protocol fails, it SHALL be assumed that the Service Provider does not support OAuth Discovery.

5.3.  Parse the Discovery Definition Document

The Discovery Definition Document is an XRDS-formatted document providing a machine-readable representation of the OAuth configuration needed to allow Consumers access using [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .). The XRDS format provides a simple and extendable framework and is defined in [XRI Resolution 2.0] (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0 - Committee Draft 02,” .) section 4.

OAuth Discovery uses a subset of the elements defined in [XRI Resolution 2.0] (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0 - Committee Draft 02,” .). Service Providers MAY use XRDS tags and attributes not listed in this specification but such elements MUST NOT change the meaning or behavior of the Discovery Definition Document from an OAuth Discovery standpoint. Consumers MAY ignore XRDS tags and attributes not listed in this specification. All elements not beginning with "oauth:" are defined in [XRI Resolution 2.0] (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0 - Committee Draft 02,” .) section 4. If a conflict exists between this specification and [XRI Resolution 2.0] (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0 - Committee Draft 02,” .), the definitions in this specification are to be used.

Unless otherwise noted, all tags, attributes, values, and XML namespaces are case sensitive.

5.3.1.  Document Structure

The Discovery Definition Document is a valid XRDS document. It contains a single XRDS root element. For example:

                <XRDS xmlns="xri://$xrds">

The XRDS element MUST include at least one Realm Definition and MAY include any number of other XRD elements which are ignored in OAuth Discovery. Realm Definitions MUST include the xmlns:oauth attribute with a value of http://oauth.net/discovery/1.0. For example:

                <XRD xmlns:oauth="http://oauth.net/discovery/1.0" xmlns="xri://$XRD*($v*2.0)">

Each Realm Definition describes a Resource Realm, a User Realm, a Consumer Realm, or any combination, and contains Service elements describing OAuth endpoints or other services. The document MUST NOT include more than one Realm Definition per Realm, and MAY include one and only one Realm Definition unbound to a specific Realm, which serves as a catch-all element. The order in which XRD elements appear in the document MUST NOT affect its meaning.

5.3.2.  Realm Definition Element

The Realm Definition is an XRD element which contains the xmlns:oauth attribute and the following elements:

<Query>

0 or 1 per Realm Definition with type xs:anyURI. Value identifies which Realm the definition covers, MUST contain a valid Realm, and MUST NOT be empty. A Discovery Definition Document MUST NOT contain more than one Realm Definition with a missing Query element.

<Expires>

0 or 1 per Realm Definition with type xs:dateTime. Consumers MUST NOT use the Realm Definition after the given expiration. If a newly retrieved document contains expired Realm Definitions, they MUST be ignore. If a cached document contains expired Realm Definitions, the Consumer MUST discard the document and obtain a newer copy. If the HTTP transport caching semantics specify a different expiration time, the Consumer MUST use the earlier of the two.

<Service>

0 or more per Realm Definition as defined in Section 5.3.4 (Service Element).

<oauth:Realm>

0 or more per Realm Definition with type xs:anyURI. Value MUST contain a valid Realm and MUST NOT be empty. Element MUST contain a type attribute set to either user or consumer based on the Realm type. The element supports an OPTIONAL priority attribute as defined in [XRI Resolution 2.0] (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0 - Committee Draft 02,” .) section 4.3.3.

<oauth:RequestParameterMethods>

0 or 1 per Realm Definition as defined in Section 5.3.6 (oauth:RequestParameterMethods Element).

<oauth:RequestSignature>

0 or 1 per Realm Definition as defined in Section 5.3.7 (oauth:RequestSignature Element).

<oauth:Reference>

0 or 1 per Realm Definition with type xs:anyURI. Value MUST be a valid discoverable Realm. The element is used to reference another Realm while retaining the Protected Resource Realm association. When a oauth:Reference element is used, is MUST be the only element contained in the Realm Definition with the exception of Expires and Query. The referenced Realm MUST NOT contain another oauth:Reference element.

5.3.3.  Service Types

Realm Definitions use Service elements to document the endpoints and services associated with the OAuth workflow. The Service element contains a child element Type which is used to indicate the type of service described.

To identify the OAuth Endpoints, each is given a unique URI, listed with their [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section reference:

Request Token:

http://oauth.net/core/1.0/endpoint/request - section 6.1.1.

User Authorization:

http://oauth.net/core/1.0/endpoint/authorize - section 6.2.1.

Access Token:

http://oauth.net/core/1.0/endpoint/access - section 6.3.1.

Protected Resource:

http://oauth.net/core/1.0/endpoint/resource - section 7.

Service elements MAY contain multiple Type elements and as follows:

• Each Service element MAY contain one, but MUST NOT contain more than one Type element with an OAuth Endpoint URI.
• Realm Definitions used for User Realms MUST contain a Service element for each of the OAuth Endpoints with the exception of http://oauth.net/core/1.0/endpoint/resource, which MAY be omitted if the Realm Definition contains both oauth:RequestParameterMethods and oauth:RequestSignature elements.
• If multiple Service elements are present for the same endpoint type, they SHOULD contain the OPTIONAL priority attribute and differ in their priority value.
• To speed up discovery, if more than one Type element is defined for that service, Service Providers SHOULD list the Type element for the OAuth Endpoints URI first.

5.3.4.  Service Element

The Service element contains the OPTIONAL priority attribute and the following elements:

<Type>

1 or more per Service element with type xs:anyURI as defined in Section 5.3.3 (Service Types). The Type element supports an OPTIONAL oauth:required attribute with type xs:boolean and default value false if omitted. The oauth:required attribute MUST NOT be used with service types defined in this specification and is provided for discovery extensions (Service Extensions).

<URI>

0 or 1 per Service element with type xs:anyURI. The value is the URL the Consumer uses in the [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) protocol. Service elements for the OAuth Endpoints MUST include a URI element expect for http://oauth.net/core/1.0/endpoint/resource which MUST NOT.

<oauth:HttpMethod>

0 or 1 per Service element with type xs:string. oauth:HttpMethod elements MUST be present and have a non-empty value when, and only when, the URI element is non-empty, except for http://oauth.net/core/1.0/endpoint/authorize which MUST NOT have an oauth:HttpMethod element. The value is the HTTP method used to request the URL provided in the URI element. The oauth:HttpMethod element supports an OPTIONAL source attribute with type xs:anyURI which indicates the source of the HTTP method definition. If omitted, the source attribute defaults to http://www.ietf.org/rfc/rfc2616 which enables using the methods defined in [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” .) as values for the oauth:HttpMethod element: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, and CONNECT.

<oauth:CustomParameters>

0 or 1 per Service element as defined in Section 5.3.5 (oauth:CustomParameters Element). MUST NOT appear with services of type http://oauth.net/core/1.0/endpoint/access.

<oauth:RequestParameterMethods>

0 or 1 per Service element as defined in Section 5.3.6 (oauth:RequestParameterMethods Element). MUST be included in Service elements for the OAuth Endpoints, if the parent Realm Definition does not contain an oauth:RequestParameterMethods element.

<oauth:RequestSignature>

0 or 1 per Service element as defined in Section 5.3.7 (oauth:RequestSignature Element). REQUIRED if the parent Realm Definition does not contain an oauth:RequestSignature element and the service type is http://oauth.net/core/1.0/endpoint/request, http://oauth.net/core/1.0/endpoint/access, or http://oauth.net/core/1.0/endpoint/resource.

5.3.5.  oauth:CustomParameters Element

The oauth:CustomParameters element is used to document Service Provider specific request parameters. Since [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) allows Service Providers to extent the list of parameters, the element provides the ability to list the parameters added. The element MUST NOT include OAuth Protocol Parameters or parameters implicitly defined by the inclusion of a service extension via a Type element as defined in Section 5.3.9 (Service Extensions).

The oauth:CustomParameters element contains 1 or more oauth:Parameter elements with type xs:string. The element MUST contain a source attribute with type xs:anyURI which indicates the source of the parameter definition.

5.3.6.  oauth:RequestParameterMethods Element

The oauth:RequestParameterMethods element is 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. Since [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) allows Service Providers to extent the list of supported methods, the element provides the ability to add methods that were not listed in the specification.

The oauth:RequestParameterMethods element contains 1 or more oauth:Method elements with type xs:string listed in decreasing preference. While [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) declares an order of preference, Service Providers MAY choose to override it, for example when adding new methods.

The oauth:Method element supports an OPTIONAL source attribute with type xs:anyURI which indicates the source of the method definition. If omitted, the source attribute defaults to http://oauth.net/core/1.0 which enables using the methods defined in [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) as values for the oauth:Method element: AUTH-HEADER, POST-BODY, and URL-QUERY.

The oauth:RequestParameterMethods element MAY be used in both the Realm Definition and Service elements. If present in both, the values of the child element are applied to the values of the parent element based on the OPTIONAL append attribute of the child's oauth:RequestParameterMethods element as defined in Section 5.3.8 (Append Attribute).

5.3.7.  oauth:RequestSignature Element

The oauth:RequestSignature element is used to document the signature methods supported by the Service Provider as defined in [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 9. Since [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) allows Service Providers to extent the list of supported methods, the element provides the ability to add methods that were not listed in the specification.

The oauth:RequestSignature element contains 1 or more oauth:Method elements with type xs:string listed in decreasing preference.

The oauth:Method element supports an OPTIONAL source attribute with type xs:anyURI which indicates the source of the signature method definition. If omitted, the source attribute defaults to http://oauth.net/core/1.0 which enables using the methods defined in [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) as values for the oauth:Method element: HMAC-SHA1, RSA-SHA1, and PLAINTEXT.

The oauth:RequestSignature element MAY be used in both the Realm Definition and Service elements. If present in both, the values of the child element are applied to the values of the parent element based on the OPTIONAL append attribute of the child's oauth:RequestSignature element as defined in Section 5.3.8 (Append Attribute).

5.3.8.  Append Attribute

The append attribute with type xs:string defines how two configuration lists are merged together into a single list in decreasing preference order. If the attribute is supported but omitted, it defaults to override. The attribute values are:

override

Only the child's values are used. The parent's values are ignored.

head

The values of the child and parent are merged with any duplicates removed from the parent's list. Preference is given to the child's values in their order and then to the remaining parent's values in their order. Child's values MAY be prefixed with an '!' character (ASCII code 33) indicating the value MUST be removed from both parent and child lists.

tail

The values of the child and parent are merged with any duplicates removed from the child's list. Preference is given to the parent's values in their order and then to the remaining child's values in their order. Child's values MAY be prefixed with an '!' character (ASCII code 33) indicating the value MUST be removed from both parent and child lists.

5.3.9.  Service Extensions

OAuth extensions MAY define additional service type URIs used to indicate support or property of an existing service type, or as a standalone service. The following example demonstrate using the http://oauth.net/example/language/1.0 URI to indicate the authorization endpoint supports a language parameter extension:

      <Service>
        <Type>http://oauth.net/core/1.0/endpoint/authorize</Type>
        <Type>http://oauth.net/example/language/1.0</Type>
        <URI>https://api.example.com/session/login</URI>
      </Service>

Extensions to an OAuth Endpoint are OPTIONAL and MAY be used by the Consumer if supported. If an extension to an OAuth Endpoint is REQUIRED by the Service Provider, it MUST be identified using the oauth:required attribute. for example:

      <Service>
        <Type>http://oauth.net/core/1.0/endpoint/authorize</Type>
        <Type oauth:required="true">http://oauth.net/example/language/1.0</Type>
        <URI>https://api.example.com/session/login</URI>
      </Service>

In the following example, a new service is defined which provides the Service Provider's terms of service:

      <Service>
        <Type>http://oauth.net/example/tos/1.0</Type>
        <URI>https://api.example.com/tos</URI>
        <oauth:HttpMethod>GET</oauth:HttpMethod>
      </Service>

The oauth:Method and oauth:HttpMethod elements provide extendibility through the source attribute which also uses URIs to identify the type of extension used. If the Consumer is unfamiliar with the value of the source attribute, it SHOULD look for other familiar methods listed. In order to use existing specifications that do not define a namespace URI, the official specification URL SHOULD be used when possible. For RFCs, the URI is the RFC number prefixed by http://www.ietf.org/rfc/rfc.

In this example, the Service Provider's terms of service are available using the WebDAV HTTP method PROPFIND:

      <Service>
        <Type>http://oauth.net/example/tos/1.0</Type>
        <URI>https://api.example.com/tos</URI>
        <oauth:HttpMethod source="http://www.ietf.org/rfc/rfc4918">PROPFIND</oauth:HttpMethod>
      </Service>

5.3.10.  Parsing Process

Parsing the Discovery Definition Document includes the following steps:

1. Find the Realm Definition for the Resource Realm - When parsing a Discovery Definition Document, the Consumer MUST find a Realm Definition with an exact match to the Resource Realm by comparing it to the value of the Query element. If no match is found, the Consumer looks for a Realm Definition without a Query element. If none found, or if the Realm Definition is incomplete, invalid, or expired, discovery fails.
2. Follow one level of references - If the Realm Definition contains an oauth:Reference element, the Consumer MUST perform discovery on the referenced Realm value per Section 5.2 (Retrieve the Discovery Definition Document), retrieve the Discovery Definition Document, and locate the referenced Realm by looking for an exact match. The referenced Realm MUST NOT contain another oauth:Reference element, and if it does, the Consumer MUST NOT retrieve it and discovery fails. Catch-all Realm Definitions do not match against a referenced Realm. Using a reference does not change the Protected Resource Realm association.
3. Identify the User Realm and Consumer Realm - If the Realm Definition does not include oauth:Realm elements for User Realm or Consumer Realm, they default to the value of the Resource Realm. Otherwise, the Consumer MUST use the oauth:Realm element with highest priority for each Realm type. If using the highest priority Realm ends in failed discovery, the Consumer SHOULD attempt to use the next Realm in priority order, and repeat until successful or tried all Realms.
4. Retrieve the Realm Definition for the User Realm and Consumer Realm - If the Realms are not identical to the Resource Realm, the Consumer MUST perform discovery on the identified Realms following the same workflow as the Resource Realm discovery. If the Realm Definition referenced contains other oauth:Realm elements, they MUST be ignored.
5. Find the endpoints configuration - Using the Realm Definition the Consumer locates the Service element with the highest priority for each endpoint. If for any reason the Consumer cannot use the discovered configuration (for example in case of an unknown signature method) or fails to use it, it SHOULD look for the Service element with the next highest priority for that service type. Consumers SHOULD repeat this process until successful or all Service elements have been tried.

5.4.  Establish Consumer Identity

The Consumer SHOULD check to see if it already has a valid Consumer Identity for the discovered Consumer Realm of the Protected Resource. If true, the Consumer MAY use that identity. In this case, the Consumer does not need to discover or parse the Realm Definition of the Consumer Realm.

If the Consumer does not have a valid Consumer Identity, it MUST use the discovered information contained in the Realm Definition of the Consumer Realm to obtain an 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 three Consumer Identity allocation scenarios: static, dynamic, and manual.

5.4.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 Realm Definition of the Consumer Realm.

Static allocation is identified using the service type URI: http://oauth.net/discovery/1.0/consumer-identity/static. The Realm Definition MUST include a Service element with the type URI and an oauth:ConsumerKey element with the Consumer Key encoded per [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 5.1. Static allocation does not include a Consumer Secret which is an empty string. For example:

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

5.4.2.  Dynamic Allocation

Dynamic Consumer Identity allocation is used when a basic Consumer profile is needed. The Service Provider allows Consumer to automatically apply and receive a Consumer Identity by providing some information. In this scenario, the Service Provider provides an endpoint the Consumer uses to request a Consumer Identity with a simple set of parameters to establish identity.

Dynamic allocation is identified using the service type URI: http://oauth.net/discovery/1.0/consumer-identity/dynamic. The Realm Definition MUST include a Service element with the type URI, URI element, and oauth:HttpMethod element. The Service element MAY include the OPTIONAL oauth:RequestParameterMethods and oauth:CustomParameters elements. The HTTP response of the request uses [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) section 5.3 and include the oauth_consumer_key and xoauth_consumer_secret parameters. For example:

      <Service>
        <Type>http://oauth.net/discovery/1.0/consumer-identity/dynamic</Type>
        <URI>http://sp.example.com/register</Type>
        <oauth:HttpMethod>GET</oauth:HttpMethod>
        <oauth:RequestParameter>
          <oauth:Method>URL-QUERY</oauth:Method>
        </oauth:RequestParameter>
        <oauth:CustomParameters>
          <oauth:Parameter source="http://oauth.net/example/consumer_identity>name</oauth:Parameter>
          <oauth:Parameter source="http://oauth.net/example/consumer_identity>description</oauth:Parameter>
          <oauth:Parameter source="http://oauth.net/example/consumer_identity>url</oauth:Parameter>
        </oauth:CustomParameters>
      </Service>

5.4.3.  Manual Allocation

Manual 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 needs to address. 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 a Consumer Realm. This allows Consumer to use OAuth Discovery with manually pre-established Consumer Identities. Type:

Manual allocation is identified using the service type URI: http://oauth.net/discovery/1.0/consumer-identity/manual. The Realm Definition MUST include a Service element with the type URI, URI element, and oauth:HttpMethod element. The result value of the request is undefined. For example:

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

5.4.4.  Complex Consumer Realm

In cases where a Service Provider offers multiple Consumer Realms, and allows access to its Protected Resources using different combinations of those Realms, the Service Provider MAY include multiple Consumer Realms per Resource Realm. The Service Provider MAY also include multiple Consumer Identity services for a single Consumer Realm, allowing Consumers to use one of multiple methods to obtain a Consumer Identity.

5.5.  Establish User Access

The Consumer SHOULD check to see if it already has a valid Access Token for the discovered User Realm of the Protected Resource. If true, the Consumer MAY use that Token together with the Consumer Identity established in the previous step to access the Protected Resource. In this case, the Consumer does not need to discover or parse the Realm Definition of the User Realm.

If the Consumer does not have a valid Access Token, it MUST use the discovered information contained in the Realm Definition of the User Realm to perform the OAuth protocol and obtain access. The Realm Definition contains all the documentation required to successfully complete the Oauth workflow.

Appendix A.  Appendix A - Examples

The examples in this section demonstrate some of the capabilities of the OAuth Discovery and try to provide a usable template for both simple and complex scenarios.

Appendix A.1.  Simple Discovery Definition Document

This example demonstrate a Discovery Definition Document where the Resource Realm contains the services configuration for both the User Realm and Consumer Realm. The Service Provider also support static Consumer Identity allocation.

  <?xml version="1.0" encoding="UTF-8"?>
  <XRDS xmlns="xri://$xrds">
    <XRD xmlns:oauth="http://oauth.net/discovery/1.0" xmlns="xri://$xrd*($v*2.0)">
      <Query>http://api.example.com/</Query>
      <Expires>2007-12-31T23:59:59Z</Expires>
      <oauth:RequestParameterMethods>
        <oauth:Method>AUTH-HEADER</oauth:Method>
        <oauth:Method>POST-BODY</oauth:Method>
        <oauth:Method>URL-QUERY</oauth:Method>
      </oauth:RequestParameterMethods>
      <oauth:RequestSignature>
        <oauth:Method>HMAC-SHA1</oauth:Method>
      </oauth:RequestSignature>
      <Service>
        <Type>http://oauth.net/core/1.0/endpoint/request</Type>
        <URI>https://api.example.com/session/request</URI>
        <oauth:HttpMethod>POST</oauth:HttpMethod>
        <oauth:RequestSignature append="head">
          <oauth:Method>PLAINTEXT</oauth:Method>
        </oauth:RequestSignature>
      </Service>
      <Service>
        <Type>http://oauth.net/core/1.0/endpoint/authorize</Type>
        <URI>https://api.example.com/session/login</URI>
        <oauth:RequestParameterMethods append="override">
          <oauth:Method>URL-QUERY</oauth:Method>
        </oauth:RequestParameterMethods>
      </Service>
      <Service>
        <Type>http://oauth.net/core/1.0/endpoint/access</Type>
        <oauth:HttpMethod>POST</oauth:HttpMethod>
        <URI>https://api.example.com/session/activate</URI>
        <oauth:RequestSignature append="head">
          <oauth:Method>PLAINTEXT</oauth:Method>
        </oauth:RequestSignature>
      </Service>
      <Service>
        <Type>http://oauth.net/discovery/1.0/consumer-identity/static</Type>
        <oauth:ConsumerKey>0685bd9184jfhq22</oauth:ConsumerKey>
      </Service>
    </XRD>
  </XRDS>

6. References

Author's Address