One document matched: draft-richer-oauth-instance-00.txt

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",
              <http://code.google.com/apis/accounts/docs/
              OAuth_ref.html>.


Author's Address

   Justin Richer (editor)
   The MITRE Corporation

   Email: jricher@mitre.org







Richer                    Expires May 11, 2011                  [Page 5]