Abstract
This extension defines additional features common to many Service Providers that are missing in OAuth 1.0 protocol. Whenever possible, all features defined in this extension are backwards compatible with OAuth 1.0 and are not mandatory for any Service Provider that already implements OAuth 1.0.
The additional features are:
- The lifetime of the consumer's credentials are returned to the Consumer, as well as a interface for the consumer to auto refresh its credentials without user interaction.
- A mechanism for Service Providers to inform the Consumer that the user must complete a browser based reauthorization flow before accessing protected resources after the the Consumer was initially authorized.
- Additional error codes and problem reporting.
- An interface for Consumers to inform the Service Provider to invalidate its credentials.
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. If an oauth_refresh_secret was issued with the Access Token, the Refresh Secret should be used 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 Refresh Secret, as defined in an earlier section section 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.
Access Denied
If the Consumer cannot be reauthorized, the Service Provider SHOULD return HTTP 403, with oauth_reason=forbidden.
Consumer initiated credential cancellation
Consumers should provide "Logout" functionality in which the Consumer deletes its copy the user's OAuth credentials and also notifies the SP to invalidate the user's session. Service Providers SHOULD invalidate the Consumer's Access Token after receiving this request.
The request contains 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 |
| oauth_timestamp | As defined in Nonce and Timestamp in Section 8. |
| oauth_version | 1.0 |
Comments (0)
You don't have permission to comment on this page.