Abstract
| This document is a work in progress |
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 a Consumer to update its credentials after the Access Token has been issued.
- 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 information about the token, including the token lifetime, scopes for the token, and additional information needed to update the token
- Discovery - to describe the SP's endpoints
Authors
- Allen Tom (atom@yahoo-inc.com)
| George Fletcher, Praveen Alavilli - would be great if you could sign on as authors |
Acknowledgments
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, Dirk Balfanz
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. |
| Auth Session Handle | Session information used by the Consumer to update an Access Token and Access Token secret. The Auth Session Handle is only used by the Consumer when updating its credentials. |
Service Provider Grants an Access Token and Auth Session
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 token attributes. The Access Token and Access Token Secret are stored by the Consumer and are used to access Protected Resources.
The optional oauth_auth_session token attribute is used by the Service Provider to verify the Consumer when updating the Access Token and Access Token Secret.
The optional oauth_token_expires_in token attribute can be used by the Consumer to pro actively refresh its credentials. The value of the oauth_token_expires_in attribute is the duration that the token is valid in seconds. Expressing the value as a duration rather than a UTC timestamp helps reduce issues with clock skew.
The response contains the following parameters:
| oauth_token | The Access Token |
| oauth_token_secret | The Access Token Secret |
| oauth_token_attributes | (optional) Attributes about the Access Token, including the token expiration time in seconds (oauth_token_expires_in) and session information to automatically refresh the Access Token when it expires (oauth_session_handle) |
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)
- HTTP 401 Unauthorized
- oauth_problem=reauthorization_required
- oauth_scope=description_of_resource_to_be_authorized
| Note: The oauth_scope is an optional parameter describing the resource that is being accessed. Instead of returning the scope as a separate parameter, the oauth_scope could be potentially be described using the Token Attributes extension instead of being returned as a separate parameter. We should decide on a single interface before finalizing this document. |
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 Access Token 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 Consumer Secret and Access Token secret |
| oauth_timestamp | As defined in Nonce and Timestamp in Section 8. |
| oauth_scope | Value returned by the Service Endpoint |
| oauth_auth_session | An 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 Auth Session, 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. Alternatively, the Consumer could have discovered the URL.
After the user completes the manual re-authorization flow, the Consumer updates its credentials using the interface defined in Section 6.3.1 of the OAuth 1.0 spec, except that the Request Token and Request Token Secret are substituted with the Access Token and Access Token Secret.
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 using the Consumer Secret and Access Token secret |
| oauth_timestamp | As defined in Nonce and Timestamp in Section 8. |
| oauth_version | 1.0 |
| Note: it is probably not necessary to require that the oauth_session_handle be passed in , however the oauth_token must be valid and not expired |
Appendix
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.
Rationale for Auth Session (aka Refresh Secret)
Service Providers often run their Authentication Service separately from other protected resources. The Authentication Service is usually strictly monitored and controlled, while other Protected Resources may be running relatively new and unproven code.
In the event that a Protected Resource is compromised (the SP gets hacked), it is desirable to prevent the intruder from being able to continue to compromise the system after the vulnerability has been fixed. Issuing credentials with a finite lifetime limits the duration that the intruder can continue to use compromised credentials. Issuing a credential to a Consumer that is not known by the Protected Resource but is known by the Authentication Service can enable an Service Provider to revoke access to an intruder without requiring consumers to be reauthorized.
Rationale for additional authorization flow
Consumers may implement new features and access new protected resources after an older version of the consumer was authorized by the user. New versions of a Consumer should be able to request additional scopes to be added to their existing set of credentials rather than having to request a new Access Token or to use new Consumer Key.
See Also
Comments (0)
You don't have permission to comment on this page.