Abstract
This extension defines features common to many Service Providers that are missing in OAuth 1.0 protocol. All features defined in this extension are additions to the OAuth 1.0 protocol and are backwards compatible with existing OAuth 1.0 implementations.
The features defined in this extension are:
- The Access Token lifetime is returned to the Consumer,
- An interface for the Consumer to auto refresh its credentials without user interaction after the Access Token has expired.
- 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 following extensions:
- Problem Reporting - to allow Service Providers to indicate why a request for a protected resource failed
- Token Attributes - to return additional information about the token to the Consumer, including the token lifetime, and additional information.
- Discovery - to describe the SP's endpoints to update the consumer's credentials
Authors
- Allen Tom (atom@yahoo-inc.com)
| George Fletcher, Praveen Alavilli - would be great if you could sign on as authors |
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, Eric Sachs
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. (This is not actually a secret for generating signatures - this secret is known only by the Consumer and the IdP, and not by the service endpoints |
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_expires_in | 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. |
| oauth_refresh_secret and oauth_token_expires_in can be returned at Token Attributes using the oauth_token_attribute parameter. The oauth_refresh_secret can defined as a more generic "fixup_state" or "reauth_state" parameter that Consumers pass to to the Auth server. |
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.
Reauthorization Required (expired credentials, or user reauthorization required)
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 Access Token and Access Token secret |
| oauth_timestamp | As defined in Nonce and Timestamp in Section 8. |
| oauth_relay_state | Value returned by the Service Endpoint |
| oauth_refresh_secret | (or fixup_state) - extra token attribute that was passed to the Consumer when the Access Token was issued |
| 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 revocation
Consumers should provide "Logout" functionality in which the Consumer deletes its copy of 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 |
Appendix: Security Considerations
Rationale for Renewable Access Tokens (Sessions)
Many Service Providers have the concept of a Session credential with a finite lifetime. Consumers authenticate with the Service Provider's Authentication Service to obtain a Session credential to access the Service Provider's protected resources. When the Session credential expires, the consumer is able to obtain a new Session credential by re-authenticating with the Authentication service. The primary benefit to this architecture is that Session credentials do not need to be revocable if they expire quickly, and that protected resources can be returned without a database lookup to verify that the consumer is still authorized.
Service Providers that use Sessions
Comments (0)
You don't have permission to comment on this page.