Abstract
| This document is a work in progress |
This document defines an extension to add additional features required by many Service Providers that use a central OAuth enabled Identity Provider (IDP) that provides both user authentication and user authorization. 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:
- A way to let a consumer to request the Identity Provider to renew it's Access Token and Secret
- A way to let a consumer request the user for additional authorizations for accessing other protected resources provided by the same Service Provider (Progressive Authorization instead of making the Consumers request and manage multiple Access Tokens for different protected resources)
- A way to let a consumer request the Service Provider to invalidate the Access Token and Secret
- A new oauth_scope parameter added to the Request Token and Access Token Requests
- A new expiresIn attribute added to the Token Attributes extension
Though most of these features in this extension are to address the Service Providers using central IDP, the same can be used by the Service Providers that act as IDPs themselves.
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)
- Praveen Alavilli (AlavilliPraveen@aol.com)
- George Fletcher (gffletch@aol.com)
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 |
| OAuth enabled Identity Provider | An IDP that supports OAuth protocol |
| 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 Service Provider to verify the consumer when updating a previously issued Access Token and Access Token Secret. |
Additions to the Core Spec and Other Extensions
New OAuth Parameters
This extension adds the following additional parameters to the Core OAuth 1.0 protocol specification.
| oauth_scope | Url of the protected resource the Consumer is trying to access - this parameter SHOULD be passed by the Consumer in the Request Token and Access Token requests so the the OAuth enabled IDP can request the user for appropriate authorization |
| oauth_session_handle | A secret value returned by the OAuth enabled IDP to the Consumer |
New OAuth Problem Values
This extension uses the following new problem values to the OAuth Problem Reporting Extension
| additional_authorization_required | Mapped to same HTTP status code (401) as the "permission_unknown" problem - used to inform the Consumers that they can request for additional authorization using the token they have already got |
| token_expired | when returned by the Service Provider, the consumer can try to renew it's Access Token and Secret instead of re-initiating the OAuth protocol from the beginning |
| token_not_renewable | returned by the Service Provider or OAuth enabled IDP when it cannot renew the Access Token and Secret |
New Token Attributes
This extension adds a new attribute "expiresIn" to the Token Attributes Extension to allow a Consumer know before hand when the Access Token is going to expire and request for renewal even before it expires to provide better and optimal user experience.
Access Token Renewal
In the Access Token request as specified in Section 6.3.1 of the OAuth 1.0 specification, in case of a successful response with Access Token and Secret, the OAuth enabled IDP generates and returns the optional "oauth_session_handle" parameter (please see Step F in the flow diagram below). The "oauth_session_handle" MUST be safely stored by the Consumer along with the Access Token and Secret, and must never be exposed to the Service Provider.
The Consumer uses the Access Token and Secret to access the protected resources as defined in the OAuth 1.0 core specification. When the Service Provider returns "token_expired" problem in the response to a protected resource, the Consumer must send a new Access Token request to the OAuth enadled IDP using the current Access Token and Secret parameters as the Request Token and Secret parameters along with the "oauth_session_handle". The OAuth enabled IDP verifies the Token, Signature and oauth_session_handle before it renews the token. The OAuth enabled IDP MAY return the same Access Token and Secret or issue new Access Token and Secret to replace the old ones.
Note that the Consumer neither needs to request for new Request Token and Secret nor request for user authorization again. The Consumer can directly send the Access Token Request.
The OAuth enabled IDP can also return a new token attribute called "expiresIn" containing value as the number of seconds after which the Access token will expire, so the Consumers can renew the token before it expires.
If the OAuth enabled IDP cannot renew the Access Token and Secret, it MUST return "token_not_renewable" error.
Multiple Resource Authorization
When a Consumer tries to access multiple Resources (Service Providers) protected by the same OAuth enabled IDP, it can request for additional user authorizations using the same Access Token instead of requesting and managing multiple Access Tokens, Secrets and possibly multiple oauth_session_handle parameters.
In the protected resource request using a previously obtained Access Token and Secret, if the Service Provider finds that the user has not given the required authorization to the Consumer, the Service Provider SHOULD return an error with "oauth_problem" value as "additional_authorization_required" and HTTP status code 401. The Consumer uses the current Access Token and Secret as the Requst Token and Secret respectively to re-initiate the OAuth Authorization Request followed with the OAuth Access Token Request. The OAuth enabled IDP MAY return the same Access Token and Secret or issue new Access Token and Secret to replace the old ones.
Note that the Consumer doesn't need to request for new Request Token and Secret. The Consumer can directly send the Authorization Request (please see Step C in the flow diagram below).
The OAuth enabled IDP SHOULD only ask the user for the additional authorization required by the Consumer and MAY display the Authorizations that are already given by the user to the same Consumer bound to the same Access Token.
It is out of scope of this extension to define how the Service Provider passes the required Authorization (oauth_scope) to it's OAuth enabled IDP.
[ ?? Or should we allow oauth_scope to be passed to the Authorization url too ??]
Access Token Revocation
Consumers MAY provide a session termination or Sign Out functionality in which the Consumer requests the OAuth enabled IDP to invalidate the user's session, Access Token and Secret and deletes its local copies of the same. 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 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_nonce | As defined in Nonce and Timestamp in Section 8. |
| oauth_version | 1.0 |
The OAuth enabled IDP returns HTTP status code 200 after it successfully invalidates the user's session.
(TODO - should the IDP return a message to the consumer to display to the user ? useful when the user's session was based on a browser based session (SSO) to inform the user that the browser session and/or other consumers that they logged into are still valid and they must terminate them separately)
Flow Diagram with Transaction details
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.