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 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [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 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
    1.1.  Multiple Copies of One Client
    1.2.  Proxied Client Access
    1.3.  Dynamic, Anonymous, or Unregistered Clients
2.  Parameters
3.  IANA Considerations
4.  Security Considerations
5.  History
6.  Acknowledgements
7.  References
    7.1.  Normative References
    7.2.  Other References
§  Author's Address

1.  Introduction

This extension to the OAuth 2 (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.) [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 (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.) [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 (Security Considerations) section for more information.

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 (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.) [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.

5.  History

This extension is a continuation of the concepts proposed by the x_oauth_display_name (Google, “Google OAuth API Documentation,” .) [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 (Introduction), 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

7.2. Other References

Author's Address