From: http://www.ietf.org/internet-drafts/draft-richer-oauth-instance-00.txt Title: OAuth Client Instance Extension Reference: draft-richer-oauth-instance-00 Date: November 7, 2010 HTML: http://tools.ietf.org/id/draft-richer-oauth-instance-00.html Data Tracker: https://datatracker.ietf.org/doc/draft-richer-oauth-instance/ Tracker Listing: http://ietfreport.isoc.org/idref/draft-richer-oauth-instance/ Tools: http://tools.ietf.org/html/draft-richer-oauth-instance-00 (HTML) Announced: http://www.ietf.org/mail-archive/web/i-d-announce/current/msg34560.html See also: IETF Open Authentication Protocol (OAuth) Working Group http://www.ietf.org/html.charters/oauth-charter.html IETF OAuth Working Group Status Pages http://tools.ietf.org/wg/oauth/ IETF OAuth Working Group Discussion List Archives http://www.ietf.org/mail-archive/web/oauth/current/maillist.html https://www.ietf.org/mailman/listinfo/oauth Bringing OAuth to the IETF (IETF Journal 5/1) http://xml.coverpages.org/newsletter/news2009-07-06.html#cite3 The OAuth Protocol: Authentication http://tools.ietf.org/html/draft-ietf-oauth-authentication The OAuth Protocol: Web Delegation http://tools.ietf.org/html/draft-ietf-oauth-web-delegation Evaluating OAUTH's Suitability for SIP Authentication http://tools.ietf.org/html/draft-beck-oauth-sip-eval Auth Access Tokens Using Credentials http://tools.ietf.org/html/draft-dehora-farrell-oauth-accesstoken-creds The OAuth 1.0 Protocol http://tools.ietf.org/html/draft-hammer-oauth OAuth Web Resource Authorization Profiles http://tools.ietf.org/html/draft-hardt-oauth Using OAuth for Recursive Delegation http://tools.ietf.org/html/draft-vrancken-oauth-redelegation =============================================================================== Network Working Group J. Richer, Ed. Internet-Draft The MITRE Corporation Intended status: Experimental November 7, 2010 Expires: May 11, 2011 OAuth Client Instance Extension draft-richer-oauth-instance-00 Abstract This specification defines two client instance extension parameters for OAuth 2.0 user authorization requests. Requirements Language 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 RFC 2119 [RFC2119]. 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 May 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 Richer Expires May 11, 2011 [Page 1] Internet-Draft oauth-instance November 2010 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Multiple Copies of One Client . . . . . . . . . . . . . . . 3 1.2. Proxied Client Access . . . . . . . . . . . . . . . . . . . 3 1.3. Dynamic, Anonymous, or Unregistered Clients . . . . . . . . 3 2. Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 4 5. History . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 5 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 5 7.1. Normative References . . . . . . . . . . . . . . . . . . . 5 7.2. Other References . . . . . . . . . . . . . . . . . . . . . 5 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 5 Richer Expires May 11, 2011 [Page 2] Internet-Draft oauth-instance November 2010 1. Introduction This extension to the OAuth 2 [I-D.ietf-oauth-v2] protocol defines two additional parameters that a client can include in requests to the user authorization endpoint which can be used to identify an instance of a given client and distinguish it from other instances of the same client that a user may authorize. These are intended to aid in the user experience and to be used in addition to the client identifier as defined in OAuth 2 [I-D.ietf-oauth-v2]. 1.1. Multiple Copies of One Client A given client identifier may represent more than one access grant for a given user within a system protected by OAuth. For example, a user may authorize the same installed client on both a laptop and a desktop computer. Each of these would have the same client identifier but be issued different tokens and will have been granted access separately. This extension is intended to allow the two client instances to identify themselves to the authorization server in a way that the user could later differentiate which tokens belonged to which copy of the client. 1.2. Proxied Client Access An OAuth client capable of using the web-server flow could allow the user to interact with it through another means such as email or SMS. In this case, the OAuth client is a single entity with a single client ID which in turn could have multiple distinct grants per user. For example, in an email-proxied system, a user could grant access to the email proxy using multiple separate email addresses. In each of these, the client is the proxy itself, but the grant is being made on behalf of a particular email account. This extension is intended to allow the proxy client to identify to the authorization server which address is being requested. 1.3. Dynamic, Anonymous, or Unregistered Clients An authorization server can allow unregistered or anonymous clients to access its protected resources. In these cases, the client credentials could act as a user-agent string, providing a machine- identifiable string claimed by the client itself. This extension is intended to allow such clients to present identifying information to the end-user through the authorization endpoint. See the security considerations (Section 4) section for more information. Richer Expires May 11, 2011 [Page 3] Internet-Draft oauth-instance November 2010 2. Parameters instance_name OPTIONAL A short, human-readable name that the server SHOULD display to the end-user along with the client name. instance_description OPTIONAL A longer, human-readable description that the server MAY display to the end-user along with the client name. If a client presents the instance_description, it MUST also present an instance_name. The server MUST NOT assume any format or structure to either of the parameters. If present, the authorization server SHOULD store this information along with its associated access grant in order to present it to the user at a future time. The authorization server MAY allow the end- user to edit or augment the client-presented information prior to storage. The authorization server MAY impose size limitations on either or both parameters, and such limitations SHOULD be documented as part of the the authorization server's API. 3. IANA Considerations This document makes no request of IANA. 4. Security Considerations The instance_name and instance_description parameters MUST be treated as self-asserted information from the client and MUST NOT be treated as a replacement for a client credential as defined in OAuth 2 [I-D.ietf-oauth-v2]. Instead, the instance parameters MUST be treated with a level of trust appropriate to the end client. When this information is displayed to the user, the authorization server MUST present it in such a way as to make clear to the end user that the instance information is self-asserted by the client and has not been validated. The authorization server MUST NOT display the instance information in lieu of a pre-registered display name, if available, but SHOULD display the instance information in addition to a pre-registered display name, if available. Richer Expires May 11, 2011 [Page 4] Internet-Draft oauth-instance November 2010 5. History This extension is a continuation of the concepts proposed by the x_oauth_display_name [google_oauth] parameter as deployed by Google. Google has used this extension parameter to allow for unregistered clients using the consumer key and secret of anonymous/anonymous to identify themselves to the system. In this deployment, as far as the Authorization Server is concerned, all unregistered apps are different instances of the anonymous/anonymous client. As dicussed above (Section 1), this extension seeks to standardize use for unregistered, proxied, and multi-instance clients alike. 6. Acknowledgements Thanks to Marius Scurtescu and the OAuth Working Group for feedback. 7. References 7.1. Normative References [I-D.ietf-oauth-v2] Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 2.0 Protocol", draft-ietf-oauth-v2-10 (work in progress), July 2010. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 7.2. Other References [google_oauth] Google, "Google OAuth API Documentation", . Author's Address Justin Richer (editor) The MITRE Corporation Email: jricher@mitre.org Richer Expires May 11, 2011 [Page 5]