OAuth Consumer Request 1.0 Draft 1

Abstract

This memo describes a method for using the OAuth flow to sign a request made between a Consumer and Service Provider where no User is involved. This enables OAuth to be used as a replacement to HTTP Basic authentication, which is not as complex as HTTP Digest authentication, and extends the capabilities of the OAuth Consumer credentials.

OAuth Core 1.0 defines a protocol for delegating user access to Consumer applications without sharing the user's private credentials. The protocol centers on a three-legged scenario, delegating User access to a Consumer for resources held by a Service Provider. In some cases, a two-legged scenario is needed, in which the Consumer is acting on behalf of itself, without a User involvement.

OAuth was created to solve the problem of sharing two-legged credentials in three-legged situations. However, within the OAuth context, Consumers might still need to communicate with the Service Provider using requests that are Consumer-specific. Since the Consumers already established a Consumer Key and Consumer Secret, there is value in being able to use them for requests where the Consumer identity is verified.

Table of Contents

1.  Notation and Conventions
2.  Definitions
3.  Consumer Identity
4.  Consumer Request
    4.1.  Consumer Sends Request
    4.2.  Service Provider Replies
5.  Security Considerations
Appendix A.  Appendix A - Example
Appendix B.  Appendix B - Discovery
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,” .).

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

2.  Definitions

Service Provider:

A web application that allows access via OAuth.

Consumer:

A website or application that uses OAuth to access resources controlled by the Service Provider.

Protected Resource(s):

Data controlled by the Service Provider, which the Consumer can access through authentication.

Consumer Key:

A value used by the Consumer to identify itself to the Service Provider.

Consumer Secret:

A secret used by the Consumer to establish ownership of the Consumer Key.

3.  Consumer Identity

This memo defines a method in which the Consumer Key and Consumer Secret, established by means left unspecified, are used to authenticate a Consumer against credentials stored by the Service Provider. For the purpose of this memo, it is assumed the Consumer already established a Consumer Key and Consumer Secret with the Service Provider.

While the method described in this memo can be used with an empty Consumer Secret, it does not provide any security or protection in such a scenario, unless other means of identification are used, such as a Public Key.

4.  Consumer Request

The Consumer requests the Protected Resource by making an HTTP request to the Service Provider. The request HTTP method and URL are provided by the Service Provider by means not specified in this memo. This workflow has been designed to imitate the flow used to obtain a Request Token in a three-legged OAuth flow as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) section 6.1.

4.1.  Consumer Sends Request

To access a Protected Resource, the Consumer sends an HTTP request to the Service Provider's resource endpoint URL. The request MUST be signed as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) section 9 with an empty Token Secret. The request contains the following REQUIRED parameters, unless otherwise noted:

oauth_consumer_key:

The Consumer Key.

oauth_signature_method:

The signature method the Consumer used to sign the request.

oauth_signature:

The signature as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) section 9: Signing Requests.

oauth_timestamp:

As defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) section 8: Nonce and Timestamp.

oauth_nonce:

As defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) section 8: Nonce and Timestamp.

oauth_version:

OPTIONAL. If present, value MUST be 1.0. Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present. Service Providers' response to non-1.0 value is left undefined.

Additional parameters:

OPTIONAL. Any additional parameters, as defined by the Service Provider.

4.2.  Service Provider Replies

The Service Provider verifies the signature and Consumer identity as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) section 9. If successful, it replies with the appropriate response to the Consumer request. The format of the reply is left unspecified by this memo.

If the request fails verification or is rejected for other reasons, the Service Provider SHOULD respond with the appropriate response code as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) section 10: HTTP Response Codes. The Service Provider MAY include some further details about why the request was rejected in the HTTP response body as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) section 5.3: Service Provider Response Parameters.

5.  Security Considerations

This memo abides by the security considerations specified in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .).

Appendix A.  Appendix A - Example

In this example, the Service Provider provider.example.net is an OAuth-enabled website, and the Consumer consumer.example.com uses resource offered by the Service Provider on behalf of its Users. The Service Provider allows Consumers to manage their Consumer profile which includes their name and description using an API call, in addition to a manual HTML page. The Consumer profile is used by the Service Provider when asking Users to grant Consumer access.

The Service Provider allows Consumers to see their profile at the following endpoint URL:

Profile Request URL:

http://provider.example.net/profile, using HTTP GET

The Service Provider supports the HMAC-SHA1 signature method and the OAuth Authorization Header. No additional parameters are defined for the profile request.

The Consumer already has an established identity with the Service Provider:

Consumer Key:

dpf43f3p2l4k3l03

Consumer Secret:

kd94hf93k423kf44

The consumer needs to sign the request before sending it to the Service Provider. To generate the signature, it first needs to generate the Signature Base String. The request contains the following parameters (oauth_signature excluded) which are ordered and concatenated into a normalized string:

oauth_consumer_key:

dpf43f3p2l4k3l03

oauth_signature_method:

HMAC-SHA1

oauth_timestamp:

1191242096

oauth_nonce:

kllo9940pd9333jh

oauth_version:

1.0

The following inputs are used to generate the Signature Base String:

1. GET
2. http://provider.example.net/profile
3. oauth_consumer_key=dpf43f3p2l4k3l03&oauth_nonce=kllo9940pd9333jh&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1191242096&oauth_version=1.0

The Signature Base String is:

    GET&http%3A%2F%2Fprovider.example.net%2Fprofile&oauth_consumer_key%3Ddpf43f3p2l4k3l03%26oauth_nonce%3Dkllo9940pd9333jh%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1191242096%26oauth_version%3D1.0

HMAC-SHA1 produces the following digest value as a base64-encoded string, using the Signature Base String as text and kd94hf93k423kf44& as key (empty Token Secret):

    SGtGiOrgTGF5Dd4RUMguopweOSU=

All together, the Consumer request for its profile is:

    http://provider.example.net/profile

    Authorization: OAuth realm="http://provider.example.net/",
                    oauth_consumer_key="dpf43f3p2l4k3l03",
                    oauth_signature_method="HMAC-SHA1",
                    oauth_signature="SGtGiOrgTGF5Dd4RUMguopweOSU%3D",
                    oauth_timestamp="1191242096",
                    oauth_nonce="kllo9940pd9333jh",
                    oauth_version="1.0"

provider.example.net checks the signature and responds with the requested profile.

Appendix B.  Appendix B - Discovery

When using OAuth Discovery as defined in [OAuth Discovery 1.0] (Hammer-Lahav, E., “OAuth Discovery 1.0,” .), the Consumer Request 1.0 extension service type URI is: http://oauth.net/ext/consumer_request/1.0. It follows the same rules and workflow as the http://oauth.net/core/1.0/endpoint/resource service type.

6. References

Author's Address