The IETF I-D submission is closed at the moment, so I'm attaching a draft extension to this email for now. It is my intention for this to become a working group item, and am looking forward to discussing this at IIW.
-- Justin PS: This and the XML draft are my first time using the RFC formats, so I'll gladly take advice and help in getting these correct.Title: OAuth Client Instance Extension
| TOC |
|
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 April 10, 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.
References
6.1.
Normative References
6.2.
Other References
§
Author's Address
| TOC |
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].
| TOC |
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.
| TOC |
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.
| TOC |
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 generally 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 for more information.
| TOC |
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 [MAY?] 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.
| TOC |
3. IANA Considerations
This document makes no request of IANA.
| TOC |
4. Security Considerations
The instance_name and instance_description parameters MUST be treated as self-asserted information 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.
| TOC |
5. History
This extension is a continuation of the concepts proposed by the x_oauth_display_name (, “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.
| TOC |
6. References
| TOC |
6.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 (TXT). |
| [RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
| TOC |
6.2. Other References
| [google_oauth] | “Google OAuth API Documentation.” |
| TOC |
Author's Address
| Justin Richer (editor) | |
| The MITRE Corporation |
Network Working Group J. Richer, Ed.
Internet-Draft The MITRE Corporation
Intended status: Experimental October 7, 2010
Expires: April 10, 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 April 10, 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 April 10, 2011 [Page 1]
Internet-Draft oauth-instance October 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. References . . . . . . . . . . . . . . . . . . . . . . . . . . 5
6.1. Normative References . . . . . . . . . . . . . . . . . . . 5
6.2. Other References . . . . . . . . . . . . . . . . . . . . . 5
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 5
Richer Expires April 10, 2011 [Page 2]
Internet-Draft oauth-instance October 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 generally 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 for more information.
Richer Expires April 10, 2011 [Page 3]
Internet-Draft oauth-instance October 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 [MAY?] 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 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 April 10, 2011 [Page 4]
Internet-Draft oauth-instance October 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. References
6.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.
6.2. Other References
[google_oauth]
"Google OAuth API Documentation",
<http://code.google.com/apis/accounts/docs/
OAuth_ref.html>.
Author's Address
Justin Richer (editor)
The MITRE Corporation
Richer Expires April 10, 2011 [Page 5]
draft-richer-oauth-instance-01.xml
Description: XML document
_______________________________________________ OAuth mailing list OAuth@ietf.org https://www.ietf.org/mailman/listinfo/oauth
