This wiki is no longer active and is left here for historical purposes. Please visit oauth.net for up-to-date information.
View
 

ScalableOAuth

This version was saved 9 years, 8 months ago View current version     Page history
Saved by atom
on May 21, 2008 at 7:04:17 pm
 


 

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.