Abstract
The OAuth protocol defines a mechanism for consumers to obtain credentials to access protected resources, but does not specify the lifetime of the credentials, nor does it define a mechanism for consumers to refresh their credentials after they expire. Service Providers may wish to issue session credentials to access protected resources that must be periodically refreshed when the session credentials expire, and also provide an interface for consumers to request additional priveleges after being authorized.
This extension depends on the Problem Reporting extension proposed by John Kristian to allow Service Providers to indicate why a request for a protected resource failed.
Authors
- Allen Tom (atom@yahoo-inc.com)
- George Fletcher
- Praveen Alavilli
Contributors
Several members of the community gave us feedback and suggestions. In particular we'd like to thank John Panzer, Eran Hammer-Lahav, Adam Rosien, Joseph Holsten, Brian Eaton
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.
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. |
| Access Token | A value used by the Consumer to gain access to the Protected Resources on behalf of the User, instead of using the User's Service Provider credentials. |
| Access Token Secret | A secret used by the Consumer to establish ownership of an Access Token. |
| Refresh Token Secret | A secret used by the Consumer to refresh an Access Token and Access Token secret. |
Service Provider Grants an Access Token and Refresh Secret
Consumers request an Access Token as specified in Section 6.3.1 of the OAuth 1.0 specification. If successful, the Service Provider generates an Access Token, an Access Token Secret, and an optional Refresh Secret. The Access Token and Access Token Secret are stored by the Consumer and used when signing Protected Resources requests. The optional Refresh Secret is used to sign requests to update the Access Token and Access Token Secret. The response contains the following parameters:
| oauth_token | The Access Token |
| oauth_token_secret | The Access Token Secret |
| oauth_refresh_secret | (optional) secret used to sign requests to refresh the credentials |
| oauth_token_lifetime | lifetime of the Access Token in seconds, OAUTH_PERSISTANT_TOKEN is returned if the token has no expiration. The token MAY be invalidated before the stated expiration time for reasons specific to the Service Provider. |
Problem Reporting when Accessing Protecting Resources
When a Service Provider rejects a consumer request for a protected resource, it SHOULD respond with HTTP 401 with additional response parameters in the HTTP response body, using the format defined in Section 5.3 of the OAuth 1.0 spec.
See The Problem Reporting Extension proposed by John Kristian.
Invalid Consumer Key
- HTTP 401 Unauthorized
- oauth_problem=consumer_key_rejected
Invalid Access Token
- HTTP 401 Unauthorized
- oauth_problem=token_revoked
Reauthorization Required (expired credentials, or user reauthorization required)
Temporary Error
- HTTP 401 Unauthorized
- oauth_problem=temporarily_unavailable
Rate Limit Exceeded
- HTTP 401 Unauthorized
- oauth_problem=rate_limit_exceeded
- Should we have a standard CAPTCHA challenge interface for Consumers to bypass rate limits
- return time interval to wait until retrying?
Updating Credentials
When an SP rejects a consumer request with the Reauthorization Required error, the consumer SHOULD attempt to update its credentials by making a request to the oauth_reauthorization_url with the following parameters:
| oauth_consumer_key | The Consumer Key |
| oauth_token | The Access Token that was obtained previously |
| oauth_signature_method | The signature method the Consumer used to sign the request. |
| oauth_signature | The Signature using the the Renewal Secret (instead of the Access Token secret) |
| oauth_timestamp | As defined in Nonce and Timestamp in Section 8. |
| oauth_version | 1.0 |
Auto renewal without user intervention
If no user intervention is required, the Service Provider returns a new Access Token, Access Token Secret, and optional Renewal Secret, as defined in Section 3 of this draft. The Consumer should discard the previously issued credentials and access the Service Provider's Protected Resources using the new credentials.
User intervention required
To be filled in by George and Praveen. The SP's Authentication server should return the url for the Consumer to direct the browser for the user to complete the re-authorization flow. We may also want to return a new Request Token and Request Token secret for the Consumer to exchange for the new credentials after the reauthorization process is completed. Alternatively, perhaps the existing Access Token and Access Token Secret can be used.
Comments (0)
You don't have permission to comment on this page.