Due to the pre-meeting cutoff date for submitting new drafts, I cannot submit it to the IETF site now. Since I don't want to lose weeks, I attached the document to this mail. I will upload the document to the IETF site after 2010-07-26.
I would appreciate any feedback on the I-D. regards, Torsten. Am 11.06.2010 01:02, schrieb Eran Hammer-Lahav:
Title: Multiple access tokensI strongly believe that it should be first presented as an I-D. This is true in general for most proposed changes of this size. It is hard to tell how big of an impact a change like this will have without some actual text. Once proposed, the WG can decide if this is of interest as a WG item. If it is, we discuss the technical details. Then, we can have a chat about editorial work and how to best fit it within the OAuth specifications framework. Hope this helps. EHL
| TOC |
|
Multiple access tokens
draft-lodderstedt-oauth-multiple-access-tokens-00
Abstract
This document proposes changes to the OAuth v2 specification in order to support the issuance of access tokens, which are valid for particular resource servers and the exchange of a single access grant (end-user authorization code, credentials, assertion, refresh token e.t.c) into multiple resource server-specific access tokens.
Status of this Memo
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”
This Internet-Draft will expire on January 11, 2011.
Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Table of Contents
1.
Introduction
2.
Service-specific tokens
2.1.
Definitions
2.2.
Requesting a service-specific token
2.3.
Access token response
3.
Multiple-tokens mode
3.1.
Requesting tokens for multiple services
3.2.
Access token response
3.3.
Service usage
3.4.
Refresh token
4.
Proposed changes
4.1.
Changes to section 3.
4.2.
Changes to section 3.1.
4.3.
Changes to section 4.
4.4.
Changes to section 4.2.
4.5.
Changes to section 5.
5.
Acknowledgements
6.
IANA Considerations
7.
Security Considerations
8.
Informative References
§
Author's Address
| TOC |
1. Introduction
OAuth v2 [draft‑ietf‑oauth‑v2‑09] (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol draft-ietf-oauth-v2-09,” June 2010.) distinguishes the role of resource server and authorization server and that way also enables deployments where a single authorization server is responsible for authorizing access to multiple, independent resource servers.
It may be expected that more and more clients will integrate (or mash-up) several of such services. As an example, one might imagine a communication client integrating e-Mail via IMAP, Voice over IP using the SIP protocol, contacts via SyncML over HTTP, and webstorage access (e.g. for e-Mail attachments) using HTTP/WebDAV. For a particular end-user, the client may discover that all of the end-user's services rely on the same OAuth2-based authorization server because they are provided by the same organization (e.g. an isp or a telco). For reasons of simplicity and user experience, the client may want to acquire access authorization to all services in a single authorization flow or for a single access grant. Another example of multi-service clients are OpenId Connect [openid‑connect] (Recordon, D. and E. Hammer-Lahav, Ed., “OpenId Connect,” May 2010.) clients. They will very likely require access to identity data (user data service) and other user resources as well.
There is currently no way to distinguish resource servers on the protocol level. Clients could use the "scope" parameter to indicate the desired resource server in an authorization request. Theoretically, it is also possible for a client to request authorization for multiple resource servers in a single authorization request. Unfortunately, the current protocol design only allows to issue a single access token per end-user authorization flow. Both restrictions force deployments to issue tokens valid for multiple resources servers, which significantly limits applicability of the OAuth2 protocol and imposes a security threats as well.
- The need to issue multi-audience tokens imposes a major security threat on end-users. Every resource server receiving such a token can use it to invoke requests on behalf of the end-user on other resource servers this particular token is valid for. The token may even be accidentially exposed to an adversary by way of HTTP referers or log files. The impact of such an incident may be significant (e.g. disclosure of health care data, financial looses) since such tokens are powerful like passwords.
- For reasons of operational security, authorization servers should use different secrets for signing and encrypting self-contained tokens for different servers. This especially holds, if the resource servers are operated at different locations and by partner organisations. An archetype of this approach is the Kerberos protocol.
- Different services may, for the same end-user, require different identities attested by an access token. Examples range from network identities, such as fixed-line port, radius session, IMSI, to user identities, product booking instances (e-mail box, MSISDN), customer identities, contract numbers or federated identities. Such identities should be asserted by different tokens.
- Different services may require different if not disjunct attributes and permissions associated with the attested identities. Keeping this data separated in different tokens promotes data privacy (cf. [laws‑of‑identity] (Cameron, K., “The Laws of Identity,” May 2005.) , Law 2). Moreover, it is good practice in identity management to issue service-specific identities.
- Different services may require different token formats (e.g. SWT vs. SAML assertions vs. session handles)
Approaches have been proposed in the working group to overcome the limitation by issuing a single token and acquire service-specific tokens afterwards by using this single token with the refresh or assertion flow. But instead of solving the problem it just transfers it and endangers interoperability.
This internet draft proposes to
- Explicitly support the identification of resource servers accepting the same token by a service id,
- To allow for the issuance of service-specific tokens, and
- To allow multiple service-specific tokens to be issued at once in a single authorization flow or based on a single access grant.
Every token is valid for exactly one service id. So the relation between resource servers and tokens is transparent to clients.
First, an extension is defined to support different tokens for different services in a multi-service deployment. Second, a further extension is defined in order to allow for the issuance of multiple service-specific access tokens at once. The necessary changes to the OAuth v2 draft are identified afterwards.
| TOC |
2. Service-specific tokens
| TOC |
2.1. Definitions
The OAuth core shall support deployments with one authorization server and multiple resource servers, where different servers use different tokens (format, content, signatures/ encryption algorithms, keys).
Resource servers are identified by a services id, that is unique within a particular deployment. Every access token is associated with exactly one service id.
A service id may be any string, e.g. "mail" or "http://mail.example.com". The service id designates a logical service, which may be equivalent to a endpoint URL. It is also possible that the service can be accessed over different channels, e.g. HTTPS, FTP, and IMAP.
[[Note: The relation between service id and sites/endpoints should be worked out when merging this draft with the sites proposal. ]]
The service id of a particular resource server can be obtained by the client either from the server's documentation or by the way of discovery. The following example shows the usage of an additional "service_id" attribute of the WWW-Authenticate header:
GET /users/meier/inbox/ HTTP/1.1 Host: email.example.com HTTP/1.1 401 Unauthorized WWW-Authenticate: Token realm='Example Service' service_id='myservice'
[[Alternative: use the realm value as service id.]]
| TOC |
2.2. Requesting a service-specific token
In order to request service-specific tokens, a new parameter "service_id" is introduced. It is used in the context of the end-user authorization flow as well as the access token request. The parameter specifies the service id the authorization shall be acquired for.
Note: This parameter is mandatory in multi-service environments.
| TOC |
2.3. Access token response
The access token issued is valid for the service id specified by the respective request parameter. No further response parameter is needed in order to represent this relation.
| TOC |
3. Multiple-tokens mode
As an optional feature, authorization servers may support the acquisition of multiple service-specific access tokens from a single access grant.
It is the decision of the client to request multiple tokens at once. The following pre-requistes must be fulfilled:
- The client must seek authorization for multiple resource servers,
- At least two of this resource servers must trust the same authorization server [[authz server equivalence should be defined as part of OAuth Discovery]],
- At least two of these resource servers must have different service ids (Note: multiple-services == multiple-tokens), and
- The respective authorization server must support the multiple-tokens feature.
Support can be announced by the authorization server using [[OAuth Discovery]]. If an authorization server does not support this feature and a client tries to obtain multiple tokens the request shall be answered with an error response.
| TOC |
3.1. Requesting tokens for multiple services
It is not sufficient to request tokens for different services just by using the new "service_id" parameter since there might be the need to request server-specific scopes, too. Since scopes are assumed to be resource server specific, there is a need to create a namespace per resource server scope. The service id is used for that purpose.
The service ids and their corresponding scopes are encoded within the request's scope parameter as follows: Scope values are constructed from the service id and the desired resource/permission values by using the service id as prefix and the resource-specific scope enclosed by braces.
<serviceId>(<scope on resource server>)[, <more resource server scopes>]
So opening and closing braces become delimiters and reserved symbols, which must not be used in the scope (or must be escaped). Empty resource-specific scopes are indicated by ommiting the braces.
To give an example. Assumed there is the scope
read write delete
for the "email" service, the scope
read copy
for the "webdav" service and no scope for the "voip" service. The resulting scope parameter would be:
email(read write delete),webdav(read copy),voip
A client indicates a request for multiple service-specific tokens by setting the parameter service_id to the predefined value 'multiple-services'. If this value is set, the authorization server parses the scope according to the rules given above.
An example request is give below
GET /authorize?response_type=code&client_id=s6BhdRkqt3&
redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&
scope=email(read+write+delete)%2Cwebdav(read+copy)%2Cvoip HTTP/1.1
Host: server.example.com
[[Alternative I: generally use a JSON document with an appropriate structure to pass in the required servers, resources and permissions to the authz server]]
[[Alternative II: use the technique proposed by [request‑by‑reference] (Sakimura, N., “Request by Reference ver.1.0 for OAuth 2.0 draft-sakimura-oauth-requrl-00,” June 2010.) , where the request document contains the structure as described in Alternative I.]]
| TOC |
3.2. Access token response
In multiple-tokens mode, the access token response contains an array of access tokens in the new parameter "access_tokens". The response parameters "access_token", "expires_in", and "scope" are not not used in that case. An example is as follows
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"refresh_token":"8xLOxBtZp8",
"access_tokens":[
{
"access_token":"SlAV32hkKG2",
"expires_in":3600,
"service_id":"email"
},
{
"access_token":"SlAV32hkKG3",
"expires_in":3600,
"service_id":"webdav"
},
{
"access_token":"SlAV32hkKG4",
"expires_in":3600,
"scope":"voip"
}
]
}
[[Alternative: use the mulitple-tokens response for single token responses, too]]
| TOC |
3.3. Service usage
Clients select the token for a particular request based on the service id.
| TOC |
3.4. Refresh token
Refresh tokens issued in multiple-tokens mode represent the access grant on all respective servers (and scopes). Such a refresh token can be used to obtain all access tokens corresponding to the access grant or subsets thereof, which can be specified using the parameters server_id and scope.
| TOC |
4. Proposed changes
This section list the changes to the protocol specification.
| TOC |
4.1. Changes to section 3.
Add a new parameter "service_id" and extend definition of the parameter "scope" as follows.
- service_id
- REQUIRED (for multi-service deployments). Defines the resource server the client seeks access authorization for. A value of "multiple-services" indicates that the client wants to obtain multiple access tokens at once (multiple-tokens mode). In this mode, interpretation of the parameter "scope" differs from single server mode.
- scope
- OPTIONAL.
Single-token mode: The scope of the access request expressed as a list of space-delimited strings. The value of the "scope" parameter with regard to a certain resource server is defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope.
Multiple-tokens mode: A comma-separated list of service-specific scopes. Every entry starts with the server id followed by braces, which enclose the actual scope. For every scope, the definition of the single-token mode holds.
| TOC |
4.2. Changes to section 3.1.
In multiple-tokens mode, the authorization response shall be returned as JSON document according to the definition of the access token response. The parameter access_token, expires_in, and scope are omited.
If the response type is "token" or "code-and-token", the authorization server applies a URL-safe base64 encoding to the JSON document and adds the resulting string as the redirection URI fragment. This is illustrated in the following example:
HTTP/1.1 302 Found
Location: http://example.com/rd#IHsNCiAgICAgICAiYWNjZXNzX3RvaiU2...
| TOC |
4.3. Changes to section 4.
Add a new parameter "service_id" and extend definition of the parameter "scope" as given in Section 4.1 (Changes to section 3.).
| TOC |
4.4. Changes to section 4.2.
The definition shall be extended as follows:
- access_token
- REQUIRED (used in single-token mode only). The access token issued by the authorization server.
- expires_in
- OPTIONAL (used in single-token mode only). The duration in seconds of the access token lifetime. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated by the authorization server.
- scope
- OPTIONAL (used in single-token mode only). The scope of the access token as a list of space- delimited strings. The value of the "scope" parameter is defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope.
- access_tokens
- REQUIRED (used in multiple-tokens mode only). List of access tokens issued by the authorization server along with their respective service id, expiration and scope.
- refresh_token
- OPTIONAL. The refresh token used to obtain new access tokens using the same end-user access grant as described in Section 4.1.4.
| TOC |
4.5. Changes to section 5.
Add attribute "service_id" to WWW-Authenticate header definition.
| TOC |
5. Acknowledgements
I would like to thank Stefanie Dronia, Sebastian Ebling, James H. Manger, Axel Nennker, and Nat Sakimura for their valuable feedback.
| TOC |
6. IANA Considerations
This memo includes no request to IANA.
| TOC |
7. Security Considerations
Implementors of JavScript-based clients must not use the "eval" function to instantiate the access token response JSON document. Instead, JSON libraries or native JSON support should be used. This is to prevent code injection into the client by an adversary.
| TOC |
8. Informative References
| [draft-ietf-oauth-v2-09] | Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol draft-ietf-oauth-v2-09,” June 2010. |
| [laws-of-identity] | Cameron, K., “The Laws of Identity,” May 2005. |
| [openid-ax-1.0] | sp...@openid.net, “OpenID Attribute Exchange 1.0 - Final,” December 2007. |
| [openid-connect] | Recordon, D. and E. Hammer-Lahav, Ed., “OpenId Connect,” May 2010. |
| [request-by-reference] | Sakimura, N., “Request by Reference ver.1.0 for OAuth 2.0 draft-sakimura-oauth-requrl-00,” June 2010. |
| TOC |
Author's Address
| Dr.-Ing. Torsten Lodderstedt | |
| Deutsche Telekom AG | |
| Email: | tors...@lodderstedt.net |
_______________________________________________ OAuth mailing list OAuth@ietf.org https://www.ietf.org/mailman/listinfo/oauth
