OAuth Session 1.0 Draft 1

Abstract

This specification defines the concept of an Authorization Session which represents the authorization granted to the Consumer to access Protected Resources on behalf of the User. OAuth Core 1.0 assumes that the Authorization Session lifetime and the Access Token lifetime are equal. This specification defines a mechanism for Service Providers to issue Access Tokens with shorter lifetimes than the Authorization Session, along with a way for Consumers to refresh their Access Tokens while the Authorization Session is valid.

This specification also defines a mechanism for Consumers to request additional privileges to be added to their Authorization Session after being initially authorized by the User, without having to manage multiple sets of Access Tokens for the same Service Provider.

Finally, this specification defines an interface for Consumers to terminate their Authorization Session with the Service Provider when the Consumer no longer needs to access Protected Resources.

Table of Contents

1.  Acknowledgements
2.  Definitions
3.  Notation and Conventions
4.  Overview
5.  Access Token Renewal
    5.1.  Consumer Obtains an Access Token and Session Handle
    5.2.  Accessing Protected Resources
    5.3.  Consumer Requests to Update Access Token
    5.4.  Service Provider Updates Access Token
6.  Multiple Resource Authorization
    6.1.  Additional Authorization Required
    6.2.  Consumer Requests User Authorization
7.  Authorization Revocation
8.  Security Considerations
Appendix A.  Workflow Diagram
Appendix B.  Example
9.  References
§  Authors' Addresses

1.  Acknowledgements

Several members of the community contributed valuable feedback and suggestions, including Naveen Agarwal, Dirk Balfanz, Blaine Cook, Shreyas Doshi, Brian Eaton, Eran Hammer-Lahav, Joseph Holsten, Hugo Haas, John Panzer, Scott Renfro, Adam Rosien, Eric Sachs, and Gregg Stefancik.

This extension depends on the [OAuth Problem Reporting Extension] (Kristian, J., “OAuth Problem Reporting Extension,” .) by John Kristian.

2.  Definitions

Authorization Session:

The period during which a Consumer has authenticated with the Service Provider, and has been authorized to access Protected Resources on behalf of the User.

Authorization Session Handle:

Information used by the Consumer to identify its Authorization Session with the Service Provider.

OAuth Enabled Identity Provider:

A Service Provider's identity and authorization service, which is separate from the other Protected Resources offered by a Service Provider.

3.  Notation and Conventions

The keywords 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.

4.  Overview

The features defined in this extension are:

1. A method for Consumers to request the Service Provider to renew its Access Token and Secret, provided that the Consumer still has a valid Authorization Session with the Service Provider.
2. A method for Consumers that have already been authorized by the User to request additional authorization from the User to access additional Protected Resources provided by the same Service Provider without requiring Consumers to manage multiple Access Tokens
3. A method for consumers to request the Service Provider to invalidate its credentials
4. A new oauth_expires_in response parameter to describe the lifetime of an Access Token

Consumers request access to Protected Resources as specified in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Sections 6.1, 6.2, and 6.3. Consumers obtain an Access Token, as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Section 6.3.2 and also an optional Authentication Session Handle that can be used to refresh the Access Token if it expires, or to update the Access Token if the Consumer needs to request additional priveleges.

Consumers access Protected Resources as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Section 7. Consumers accessing a Protected Resource using an expired access token are informed using the Problem Reporting Extension that they should refresh their Access Token, provided that they still have a valid Authorization Session with the Service Provider.

5.  Access Token Renewal

Service Providers MAY wish to grant Authorization Sessions to Consumers with longer lifetimes than the lifetime of the Access Token. This section defines a workflow for Consumers to update their Access Token without user intervention while the Consumer has a valid Authorization Session with the Service Provider.

Service Providers SHOULD NOT implement the Access Token Renewal workflow if the lifetime of their Access Tokens is equal to the lifetime of the Authorization Session.

5.1.  Consumer Obtains an Access Token and Session Handle

Consumers obtain an Access Token and Access Token Secret as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Section 6. In addition to the oauth_token and oauth_token_secret parameters, the Service Provider MAY return three additional parameters:

oauth_session_handle:

REQUIRED. Used to identify the instance of the Consumer after it has been authorized by the User.

oauth_authorization_expires_in:

OPTIONAL. The duration that the Consumer is authorized to access Protected Resources on behalf of the user in seconds. The Service Provider MAY revoke access to the Consumer prior to the expected expiration time as deemed necessary for reasons specific to the Service Provider.

oauth_expires_in:

OPTIONAL. The lifetime of the Access Token in seconds. If the Access Token lifetime is shorter than the lifetime of the authorization (oauth_authorization_expires_in), then the Consumer SHOULD proactively refresh its Access Token before it expires. The Access Token could be invalidated before the expected expiration time due to reasons specific to the Service Provider.

5.2.  Accessing Protected Resources

Consumers access Protected Resources as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Section 7. If the Service Provider denies the request because the Access Token has expired the Service Provider MUST respond with HTTP 401 and use the [OAuth Problem Reporting Extension] (Kristian, J., “OAuth Problem Reporting Extension,” .) to inform the Consumer to go through the Reauthorization workflow.

	    HTTP/1.1 401 Unauthorized
	    WWW-Authenticate: OAuth oauth_problem=access_token_expired
	    Content-type: application/x-www-form-urlencoded

            oauth_problem=access_token_expired

5.3.  Consumer Requests to Update Access Token

Consumers SHOULD attempt to update their Access Token proactively before the token expires, or when denied a protected resource due to the access_token_expired problem. To update an Access Token, the Consumer makes an HTTP request to the Service Provider's Access Token URL, with the following parameters:

oauth_consumer_key:

The Consumer Key.

oauth_token:

The Access Token obtained previously.

oauth_signature_method:

The signature method the Consumer used to sign the request

oauth_signature:

The signature as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Section 9: Signing Requests.

oauth_timestamp:

As defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Section 8: Nonce and Timestamp.

oauth_nonce:

As defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Section 8: Nonce and Timestamp.

oauth_session_handle:

REQUIRED. The Authentication Session Handle obtained previously.

5.4.  Service Provider Updates Access Token

The Service Provider MUST verify that the the Consumer is still authorized to access the Protected Resources, and if so, the format of the response is identical to the response defined in Section 5.1 (Consumer Obtains an Access Token and Session Handle). The Consumer MUST replace its previous copy of the Access Token, Access Token Secret, and Authentication Session Handle with the new values.

After obtaining the new Access Token, the Consumer can access Protected Resources using the new Access Token.

If the Consumer is no longer authorized to access the Protected Resources, the Service Provider should return the HTTP 401 and the "permission_denied" problem to the Consumer.

	    HTTP/1.1 401 Unauthorized
	    WWW-Authenticate: OAuth oauth_problem=permission_denied
	    Content-type: application/x-www-form-urlencoded

            oauth_problem=permission_denied

6.  Multiple Resource Authorization

Service Providers may offer multiple Protected Resources that are protected by the same OAuth enabled Identity Provider. Over time, Consumers may want to access additional Protected Resources than what was originally authorized by the User. This section defines a workflow for Consumers to upgrade their credentials to access additional Protected Resources without having to manage multiple sets of credentials.

This workflow assumes that the Consumer has obtained an Access Token, Access Token Secret, and an Authentication Session Handle as defined in Section 5.1 (Consumer Obtains an Access Token and Session Handle).

6.1.  Additional Authorization Required

Service Providers SHOULD return HTTP 401 with the additional_authorization_required problem to Consumers that access a Protected Resource using an Access Token without sufficient credentials.

	    HTTP/1.1 401 Unauthorized
	    WWW-Authenticate: OAuth oauth_problem=additional_authorization_required
	    Content-type: application/x-www-form-urlencoded

            oauth_problem=additional_authorization_required

6.2.  Consumer Requests User Authorization

The OAuth enabled Identity Provider SHOULD only ask the user for the additional authorization required by the Consumer and MAY display the Authorizations that have already given by the user to the same Consumer.

It is out of scope of this specification to define how the Service Provider passes the required Authorization (oauth_scope) to it's OAuth enabled IDP.

In order for the Consumer to obtain additional authorization, the Consumer repeats [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Sections 6.1 and 6.2. The Consumer obtains an unauthorized Request Token and directs the User to the Service Provider to authorize the Request Token. However, when exchanging the Request Token for the Access Token, the Consumer submits the Authentication Session Handle that was obtained previously in addition to the Request Token. The Service Provider responds with an Access Token that is authorized for the new set of privileges, as well as the Access Token Secret, and Authentication Session Handle. The previously issued Access Token, Access Token Secret, and Authentication Session Handle MUST be discarded.

Service Providers MAY choose to re-issue the same Access Token, Access Token Secret, and Authentication Session Handle as long as the new set of credentials are authorized to access the new set of protected resources that were authorized by the User.

7.  Authorization Revocation

Consumers MAY provide a session termination or Sign Out functionality in which the Consumer requests the OAuth enabled IDP to terminate the Consumer's Authentication Session, and to invalidate the Access Token and Secret. Service Providers MUST invalidate the Consumer's Access Token after receiving this request. The Access Token Invalidation end point is defined in the OAuth Discovery Information as "http://oauth.net/oauth_token_invalidation_request" (TODO - correct the namespace). The request contains the following parameters:

oauth_consumer_key:

The Consumer Key.

oauth_token:

The Access Token obtained previously.

oauth_signature_method:

The signature method the Consumer used to sign the request

oauth_signature:

The signature as defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Section 9: Signing Requests.

oauth_timestamp:

As defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Section 8: Nonce and Timestamp.

oauth_nonce:

As defined in [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) Section 8: Nonce and Timestamp.

oauth_session_handle:

REQUIRED IF the Service Provider returned an oauth_session_handle value with the previous Access Token.

8.  Security Considerations

Service Providers may want to issue Access Tokens with relatively short lifetimes for a variety of reasons. Issuing permanent credentials can be risky if the credentials are stolen due to a compromised Protected Resource or Consumer. The Authentication Session Handle that is shared by the Consumer and the Service Provider's Identity Provider, but not with the Protected Resource helps defend against the scenario where the Protected Resource is compromised.

Allowing Access Tokens to be revoked before they expire requires Service Providers to perform a database lookup before serving a Protected Resource. For performance reasons, Service Providers may want to issue Access Tokens that can be validated without a database lookup, provided that the Access Token lifetime is less than then the Service Provider's allowable latency for Access Token revocation.

Over time, new versions of Consumers may be released which require additional privileges than what their users originally granted. Users SHOULD have the opportunity to either approve or deny additional privileges for a Consumer after the initial authorization.

All secrets and the Authentication Session Handle SHOULD only be transmitted using HTTPS.

Appendix A.  Workflow Diagram

Workflow Diagram

Appendix B.  Example

Example goes here

9. References

Authors' Addresses