OAUTH WG G. Fletcher
Internet-Draft AOL
Intended status: Informational T. Lodderstedt
Expires: April 02, 2013 Deutsche Telekom AG
Z. Zeltsan
Alcatel-Lucent
October 2012

OAuth Use Cases
draft-ietf-oauth-use-cases-02

Abstract

This document lists the OAuth use cases. The provided list is based on the Internet Drafts of the OAUTH working group and discussions on the group's mailing list.

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 April 02, 2013.

Copyright Notice

Copyright (c) 2012 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

This document describes the use cases that have been discussed on the oauth WG mailing list and introduced by the Internet Drafts submitted to the group. The selected use cases illustrate the use of the OAuth flows by the clients of the various profiles and types. The document also includes those cases that are not directly supported by the OAuth 2.0 [I-D.ietf-oauth-v2], but were considered during its development. The document provides a list of the requirements derived from the use cases. The use cases supported by OAuth 2.0 are indicated.

The document's objective is to help with understanding of the OAuth 2.0 protocol design.

The following section provides the abbreviated descriptions of the use cases.

2. OAuth use cases

This section describes the use cases that have been discussed by the oauth WG.

2.1. Web server


Description:

Alice accesses an application running on a web server at www.printphotos.example.com and instructs it to print her photographs that are stored on a server www.storephotos.example.com. The application at www.printphotos.example.com receives Alice's authorization for accessing her photographs without learning her authentication credentials with www.storephotos.example.com.

Pre-conditions:

Post-conditions:

A successful procedure results in the application www.printphotos.example.com receiving an authorization code from www.storephotos.example.com. The code is bound to the application at www.printphotos.example.com and to the callback URL supplied by the application. The application at www.printphotos.example.com uses the authorization code for obtaining an access token from www.storephotos.example.com. The application at www.storephotos.example.com issues an access token after authenticating the application at www.printphotos.example.com and validating the authorization code that it has submitted. The application at www.printphotos.example.com uses the access token for getting access to Alice's photographs at www.storephotos.example.com.

Note: When an access token expires, the service at www.printphotos.example.com needs to repeat the OAuth procedure for getting Alice's authorization to access her photographs at www.storephotos.example.com. Alternatively, if Alice wants to grant the application a long lasting access to her resources at www.storephotos.example.com, the authorization server associated with www.storephotos.example.com may issue the long-living tokens. Those tokens can be exchanged for short-living access tokens required to access www.storephotos.example.com.

Requirements:

Note: OAuth 2.0 supports this use case

2.2. User-agent


Description:

Alice has on her computer a gaming application. She keeps her scores in a database of a social site at www.fun.example.com. In order to upload Alice's scores, the application gets access to the database with her authorization.

Pre-conditions:

Post-conditions:

A successful procedure results in Alice's browser receiving an access token. The access token is received from www.fun.example.com as a fragment of a redirection URL of an auxiliary web server www.help.example.com. Alice's browser follows the redirection, but retains the fragment. From the auxiliary web server at www.help.example.com Alice's browser downloads a script that extracts access token from the fragment and makes it available to the gaming application. The application uses the access token to gain access to Alice's data at www.fun.example.com.

Requirements:

Note: OAuth 2.0 supports this use case

2.3. Native Application


Description:

Alice wants to upload (or download) her photographs to (or from) storephotos.example.com using her smartphone. She downloads and installs a photo app on her smartphone. In order to enable the app to access her photographs, Alice needs to authorize the app to access the web site on her behalf. The authorization shall be valid for a prolonged duration (e.g. several months), so that Alice does not need to authenticate and authorize access on every execution of the app. It shall be possible to withdraw the app's authorization both on the smartphone as well as on the site storephotos.example.com.

Pre-conditions:

Post-conditions:

A successful procedure results in Alice's app receiving the access and refresh tokens. The app obtains the tokens by utilizing the Authorization Code flow. The application uses the access token to gain access to Alice's data at storephotos.example.com. The refresh tokens are persistently stored on the device for use in subsequent app executions. If a refresh token exists on app startup, the app directly uses the refresh token to obtain a new access token.

Requirements:

Note: OAuth 2.0 supports this use case

2.4. In-App-Payment (based on Native Application)


Description:

Alice has installed on her computer a gaming application (e.g., running as native code or as a widget). At some point she wants to play the next level of the game and needs to purchase an access to the advanced version of the game from her service provider at www.sp.example.com. With Alice's authorization the application accesses her account at www.sp.example.com and enables her to make the payment.

Pre-conditions:

Post-conditions:

A successful procedure results in the gaming application invoking the user browser and directing it to the authorization server of the service provider. The HTTP message includes information about the gaming application's request to access Alice's account. The authorization server presents to Alice the authentication and authorization interfaces. The authorization interface shows Alice the information about the application's request including the requested charge to her account. After Alice successfully authenticates and authorizes the request, the authorization server enables Alice to save the transaction details including the authorization code issued for the gaming application. Then the authorization server redirects Alice's browser to a custom scheme URI (registered with the operating system). This redirection request contains a one-time authorization code and invokes a special application that is able to extract the authorization code and present it to the gaming application. The gaming application presents the authorization code to the authorization server and exchanges it for a one-time access token. The gaming application then uses the access token to get access to Alice's account and post the charges at www.sp.example.com.

Requirements:

Note: The focus is on the requirements that are specific to this use case. The requirements that are common to the native applications are listed in the preceding use case.

Note: OAuth 2.0 does not directly support this use case

2.5. Device with an input method


Description:

Alice has a device, such as a gaming console, that does not support an easy data-entry method. She also has access to a computer with a browser. The application running on the Alice's device gets authorized access to a protected resource (e.g., photographs) stored on a server at www.storephotos.example.com

Pre-conditions:

Post-conditions:

Requirements:

Note: OAuth 2.0 supports this use case

2.6. Client password (shared secret) credentials


Description:

The company GoodPay prepares the employee payrolls for the company GoodWork. In order to do that the application at www.GoodPay.example.com gets authenticated access to the employees' attendance data stored at www.GoodWork.example.com.

Pre-conditions:

Post-conditions:

A successful procedure results in the application at www.GoodPay.example.com receiving an access token after authenticating to the application running at www.GoodWork.example.com.

Requirements:

Note: OAuth 2.0 supports this use case

2.7. Assertion


Description:

Company GoodPay prepares the employee payrolls for the company GoodWork. In order to do that the application at www.GoodPay.example.com gets authenticated access to the employees' attendance data stored at www.GoodWork.example.com.
This use case describes an alternative solution to the one described by the use case Client password credentials.

Pre-conditions:

Post-conditions:

A successful procedure results in the application at www.GoodPay.example.com receiving an access token after authenticating to the application running at www.GoodWork.example.com by presenting an assertion (e.g., SAML assertion).

Requirements:

Note: OAuth 2.0 supports this use case

2.8. Access token exchange


Description:

Alice uses an application running on www.printphotos.example.com for printing her photographs that are stored on a server at www.storephotos.example.com. The application running on www.storephotos.example.com, while serving the request of the application at www.printphotos.example.com, discovers that some of the requested photographs have been moved to www.storephotos1.example.com. The application at www.storephotos.example.com retrieves the missing photographs from www.storephotos1.example.com and provides access to all requested photographs to the application at www.printphotos.example.com. The application at www.printphotos.example.com carries out Alice's request.

Pre-conditions:

Post-conditions:

A successful procedure results in the application at www.printphotos.example.com receiving an access token that allows access to Alice's photographs. This access token is used for the following purposes:

As the result, there are two access token issued for two different applications. The tokens may have different properties (e.g., scope, permissions, and expiration dates).

Requirements:

Note: This use case is indirectly supported by Assertion frmamework for OAuth 2.0 [I-D.ietf-oauth-assertions] and its extensions SAML 2.0 Bearer Assertion Profiles for OAuth 2.0 [I-D.ietf-oauth-saml2-bearer] and JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0 [I-D.ietf-oauth-jwt-bearer]

2.9. Multiple access tokens


Description:

Alice uses a communicator application running on a web server at www.communicator.example.com to access her email service at www.email.example.com and her voice over IP service at www.voip.example.com. Email addresses and telephone numbers are obtained from Alice's address book at www.contacts.example.com. Those web sites all rely on the same authorization server, so the application at www.communicator.example.com can receive a single authorization from Alice for getting access to these three services on her behalf at once.
The authorization server needs to issue different access tokens for the involved services due to security and privacy policy. One typical reason is the use of the symmetric secrets for signing self-contained access tokens. In this use case, using a particular token for more than a single service introduces a security risk.

Note: This use case is especially useful for native applications since a web browser needs to be launched only once.

Pre-conditions:

Post-conditions:

A successful procedure results in the application at www.communicator.example.com receiving three different access tokens: one for accessing the email service at www.email.example.com, one for accessing the contacts at www.contacts.example.com, and one for accessing the VoIP service at www.voip.example.com.

Requirements:

Note: OAuth 2.0 does not support this use case

2.10. Gateway for browser-based VoIP applets


Description:

Alice accesses a social site on a web server at www.social.example.com. Her browser loads a VoIP applet that enables her to make a VoIP call using her SIP server at www.sipservice.example.com. The application at www.social.example.com gets Alice's authorization to use her account with www.sipservice.example.com without learning her authentication credentials with www.sipservice.example.com.

Pre-conditions:

Post-conditions:

A successful procedure results in the application at www.social.example.com receiving access token from www.sipservice.example.com with Alice's authorization.

Requirements:

Note: OAuth 2.0 does not support this use case

2.11. Signed Messages


Description:

Alice manages all her personal health records in her personal health data store at a server at www.myhealth.example.com, which manages authorization of access to Alice's participating health systems. Alice's Primary Care Physician (PCP), which has a Web site at www.pcp.example.com, recommends her to see a sleep specialist (www.sleepwell.example.com). Alice arrives at the sleep specialist's office and authorizes it to access her basic health data at her PCP's web site. The application at www.pcp.example.com verifies that Alice has authorized www.sleepwell.example.com to access her health data as well as enforces that www.sleepwell.example.com is the only application that can retrieve that data with that specific authorization.

Pre-conditions:

Post-conditions:

Requirements:

Note: OAuth 2.0 does not support this use case

2.12. Signature with asymmetric secret


Description:

Alice accesses an application running on a web server at www.printphotos.example.com and instructs it to print her photographs that are stored on a server www.storephotos.example.com. The application at www.printphotos.example.com, which does not have a shared secret with www.storephotos.example.com, receives Alice's authorization for accessing her photographs without learning her authentication credentials with www.storephotos.example.com.

Pre-conditions:

Post-conditions:

A successful procedure results in the application at www.printphotos.example.com receiving an access token from www.storephotos.example.com for accessing the Alice's photographs.

Requirements:

Note: OAuth 2.0 does not support this use case

3. Authors of the use cases

The major contributors of the use cases are as follows:

W. Beck, Deutsche Telekom AG
G. Brail, Sonoa Systems
B. de hOra
B. Eaton, Google
S. Farrell, NewBay Software
G. Fletcher, AOL
Y. Goland, Microsoft
B. Goldman, Facebook
E. Hammer-Lahav, Yahoo!
D. Hardt
R. Krikorian, Twitter
T. Lodderstedt, Deutsche Telekom
E. Maler, PayPal
D. Recordon, Facebook
L. Shepard, Facebook
A. Tom, Yahoo!
B. Vrancken, Alcatel-Lucent
Z. Zeltsan, Alcatel-Lucent

4. Security considerations

The OAuth 2.0 specification [I-D.ietf-oauth-v2] provides the implementers with security guidelines for all OAuth 2.0 client profiles. In addition, a comprehensive OAuth security model and background for the protocol design are provided by [I-D.ietf-oauth-v2-threatmodel].

5. IANA considerations

This Internet Draft includes no request to IANA.

6. Acknowledgements

The authors thank Igor Faynberg and Hui-Lan Lu for their invaluable help with preparing this document. Special thanks are to the draft reviewers Thomas Hardjono and Melinda Shore, whose suggestions have helped to improve the draft.

7. References

7.1. Normative References

[I-D.ietf-oauth-v2] Hammer-Lahav, E, Recordon, D and D Hardt, "The OAuth 2.0 Authorization Protocol", Internet-Draft draft-ietf-oauth-v2-25, March 2012.

7.2. Informative References

[I-D.ietf-oauth-v2-threatmodel] Lodderstedt, T, McGloin, M and P Hunt, "OAuth 2.0 Threat Model and Security Considerations", Internet-Draft draft-ietf-oauth-v2-threatmodel-07, August 2012.
[I-D.ietf-oauth-assertions] Campbell, B, Mortimore, C, Jones, M and Y Goland, "Assertion Framework for OAuth 2.0", Internet-Draft draft-ietf-oauth-assertions-05, September 2012.
[I-D.ietf-oauth-saml2-bearer] Campbell, B and C Mortimore, "SAML 2.0 Bearer Assertion Profiles for OAuth 2.0", Internet-Draft draft-ietf-oauth-saml2-bearer-14, September 2012.
[I-D.ietf-oauth-jwt-bearer] Jones, M, Campbell, B and C Mortimore, "JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0", Internet-Draft draft-ietf-oauth-jwt-bearer-02, September 2012.

Authors' Addresses

George Fletcher AOL EMail: gffletch@aol.com
Torsten Lodderstedt Deutsche Telekom AG EMail: torsten@lodderstedt.net
Zachary Zeltsan Alcatel-Lucent 600 Mountain Avenue Murray Hill, New Jersey USA Phone: +1 908 582 2359 EMail: Zachary.Zeltsan@alcatel-lucent.com