Internet DRAFT - draft-hunt-oauth-chain
draft-hunt-oauth-chain
INTERNET-DRAFT Phil Hunt
Intended Status: Standards Track Oracle Corporation
Expires: June 1, 2013 November 28, 2012
Chain Grant Type for OAuth2
draft-hunt-oauth-chain-01.txt
Abstract
This specification defines a method by which an OAuth protected
service, can use a received oauth token from its client, to in turn,
act as a client and access another OAuth protected service in a
'chained' profile.
Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
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 September 2, 2011.
Copyright and License 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
Phil Hunt Expires June 1, 2013 [Page 1]
INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012
described in the Simplified BSD License.
Phil Hunt Expires June 1, 2013 [Page 2]
INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1 Notational Conventions . . . . . . . . . . . . . . . . . . 5
2. Chained OAuth token Request . . . . . . . . . . . . . . . . . 5
2.1 Client Requests OAuth token . . . . . . . . . . . . . . . . 6
2.2 Processing Requirements . . . . . . . . . . . . . . . . . . 7
2.3 Error Response . . . . . . . . . . . . . . . . . . . . . . 7
2.4 Example (non-normative) . . . . . . . . . . . . . . . . . . 8
3. Security Considerations . . . . . . . . . . . . . . . . . . . 8
3.1 Single Domain . . . . . . . . . . . . . . . . . . . . . . . 8
3.2 Multi-Domain . . . . . . . . . . . . . . . . . . . . . . . 8
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.1 Normative References . . . . . . . . . . . . . . . . . . . 9
5.2 Informative References . . . . . . . . . . . . . . . . . . 9
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . . 9
Appendix B. Document History . . . . . . . . . . . . . . . . . . . 9
Author's Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
Phil Hunt Expires June 1, 2013 [Page 3]
INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012
1. Introduction
OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2] provides a
method for making authenticated HTTP requests to a resource or
service using an OAuth token issued to third-party clients. OAuth
tokens are issued through a number of grant types defined in the
specification.
OAuth supports the ability to support new grant types via definition
of new extension grant types. This specification defines an extension
grant type that enables "chained" authorization between separate
OAuth infrastructures or "domains".
Figure 1, shows a "chained authorization" where by an OAuth protected
resource provider (Server A) to in turn, act as an OAuth client to
another OAuth resource provider (Server B).
Server A (OAuth Domain A) requests an OAuth token from Server B by
presenting its own client credential to Server B's token service
along with the OAuth token used by the "Originating Client" to access
Server A. In response, Server B's token service provides Server A an
OAuth token for Server B.
+-----------+ +------------------+ +-----------------+
|Originating| | OAuth Protected | | OAuth Protected |
| Client |--------->| Server A |-------->| Server B |
| | | (Domain A) | | (Domain B) |
+-----------+ +------------------+ +-----------------+
Figure 1: Typical Chain Scenario
While this scenario could be solved through the use of bearer tokens
or other similar technologies, "Chained Authorization" enables pair-
wise trust and client credential validation when transactions are
happening in a series of connected steps (similar in nature to a
message bus).
When exchanging tokens between separate OAuth "domains", each domain
is able to use different token types and set different client
credential requirements for each pair-wise relationship.
This specification uses the terminology defined in [I-D.ietf-oauth-
v2].
Please discuss this draft on the oauth@ietf.org mailing list.
Phil Hunt Expires June 1, 2013 [Page 4]
INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012
1.1 Notational Conventions
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].
Unless otherwise noted, all protocol parameter names and values are
case sensitive.
2. Chained OAuth token Request
An OAuth protected service (the chain requestor), wishes to in turn
act as a client to another OAuth protected service. In doing so, the
chain requestor is utilizing the existing authorization relationship
with the originating client to access another service on the
originating client's behalf along with its own client credential.
For the purpose of this specification, an OAuth "domain" is defined
as a set of one or more resource servers whose authorization is
managed by a common OAuth token server. Chained OAuth token requests
MAY occur between OAuth domains, OR MAY occur with in a single domain
with a common OAuth token service.
The process by which the originating client obtains an OAuth token is
defined by the OAuth 2.0 Authorization Protocol [I-D.ietf.oauth-v2].
+-----------+ +------------------+ +---------------+
|Originating| | OAuth Protected |--(B)-AT1-->| OAuth Token |
| Client |-(A)AT1-->| Service & Client | | Server |
| | | (Domain A) |<-(C)-AT2---| (Domain B) |
+-----------+ +------------------+ +---------------+
|
| +---------------+
+------(D)-AT2-->|OAuth Protected|
| Server |
| (Domain B) |
+---------------+
Figure 2: Chain OAuth Token Request
The request/response flow illustrated in Figure 2 includes:
(A) The originating client requests a resource from the OAuth
Protected Service (Domain A). In doing so, it presents OAuth
token AT1 (previously issued) as per the normal OAuth resource
access request [I-D.ietf.oauth-v2].
Phil Hunt Expires June 1, 2013 [Page 5]
INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012
(B) The OAuth Protected Service & Client (the chain requestor)
requests an OAuth token that includes the received OAuth token
AT1 and a grant_type of "http://oauth.net/grant_type/chain".
(C) The target Token Server (Domain B) validates the client
credentials of the chain requestor and the token AT1 provided
per the processing rules defined in this specification and
issues a new OAuth token (AT2) valid the current domain (Domain
B).
(D) The chain requestor accesses the "chained" OAuth Protected
Server in Domain B with the new OAuth token (AT2).
Note that in a single domain scenario, the Token Server (Domain
B) MAY be the same token server for the OAuth Protected Server
(Domain A).
2.1 Client Requests OAuth token
The client (the chain requestor) makes a request to a token endpoint
and includes the received OAuth token. The core details of which are
defined in OAuth [I-D.ietf.oauth-v2], by specifying
"http://oauth.net/grant_type/chain" as the absolute URI value of the
"grant_type" parameter and by adding the following parameter:
oauth_token
REQUIED. The value of the oauth_token parameter MUST contain a
single OAuth token previously issued by an OAuth server. The
token server MAY choose to interpret scope encoded within the
provided OAuth token.
The format of the oauth_token value is corresponds to the value
used in an HTTP "Authorization" header when accessing a resource
as defined in section 7 of the OAuth specification [I-
D.ietf.oauth-v2].
scope
OPTIONAL. The scope of the access request expressed as a list of
space-delimited strings. The value is defined by the token
server. If the value contains multiple space- delimited strings,
their order does not matter, and each string adds an additional
access range to the requested scope.
Where scope is available in both the provided oauth_token and
the scope parameter, the token endpoint MAY choose to interpret
and prioritize scope values from either the parameter or the
OAuth token in any way it deems appropriate to its domain.
Phil Hunt Expires June 1, 2013 [Page 6]
INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012
Token servers SHOULD issue OAuth tokens with a limited lifetime and
require clients to refresh them by requesting a new OAuth token using
the same originating oauth_token, if it is still valid, or with a new
originating oauth_token. The token server SHOULD NOT issue refresh
tokens.
2.2 Processing Requirements
Prior to issuing an OAuth token response as described in [I-
D.ietf.oauth-v2], the token server MUST validate the provided
oauth_token according to the following criteria. If present, the
token server MUST also validate the client credentials of the
requesting client. Application of additional restrictions and policy
are at the discretion of the token server.
o If the oauth_token denotes an identifier used to retrieve
authorization information, the authorizing server MUST be able
query the issuing server for the purpose of validation and to
retrieve authorization information. The method for which this is
done are beyond the scope of this specification and is defined by
companion OAuth token specifications.
o If the oauth_token can be parsed and self-contains authorization
information, then the authorizing server MUST validate the token
and obtain necessary authorizing information. The method by which
this is done is beyond the scope of this specification and is
defined by companion OAuth token specifications.
o The token server MUST validate that received oauth_token is still
valid either by parsing the token itself, or by confirming
validity with the token server (which is out of the scope of this
specification).
2.3 Error Response
If the oauth_token is not valid, or authorization information
requirements cannot be met, the token server MUST construct an error
response as defined in [I-D.ietf.oauth-v2]. The value of the error
parameter MUST be the "invalid_grant" error code. The token server
MAY include additional information regarding the reasons the OAuth
token was considered invalid using the error_description or error_uri
parameters.
Phil Hunt Expires June 1, 2013 [Page 7]
INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012
Example error:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error":"invalid_grant",
"error_description":"Audience validation failed"
}
2.4 Example (non-normative)
Though non-normative, the following examples illustrate what a
conforming token request would look like. Note: Line breaks are for
readability purposes only.
POST /token.oauth2 HTTP/1.1
Host: authz.example.net
Content-Type: application/x-www-form-urlencoded
grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fchain
oauth_token=MAC+token%3D%22h480djs93hd8%22
%2Ctimestamp%3D%22137131200%22%2Cnonce%3D%22dj83hs9s%22
%2Csignature%3D%22kDZvddkndxvhGRXZhvuDjEWhGeE%3D%22
3. Security Considerations
The specification builds on considerations described within the OAuth
2.0 Authorization Protocol [I-D.ietf.oauth-v2].
[[Other considerations TBD]]
3.1 Single Domain
OAuth protected servers within the same domain, using the same Token
server, MAY request new OAuth tokens for the purpose of binding the
original user context with the new client credential.
3.2 Multi-Domain
When issuing tokens between OAuth domains, the token server MUST be
able to determine the submitted oauth_token's issuer.
The token server SHOULD have a method of establishing trust with the
issuer of the received OAuth token.
Phil Hunt Expires June 1, 2013 [Page 8]
INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012
The token server MUST define a method of mapping received credentials
received via the received OAuth token.
4. IANA Considerations
The following is a parameter registration request, as defined in The
OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol [I-
D.ietf.oauth-v2], for the "oauth_token" parameter:
o Parameter name: oauth_token
o Parameter usage: token request
o Change controller: IETF
o Specification document(s): draft-hunt-oauth-chain
5. References
5.1 Normative References
[I-D.ietf.oauth-v2]
Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The
OAuth 2.0 Authorization Protocol", ID draft-ietf-oauth-
v2-13 (work in progress), Feb 2011.
[RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
5.2 Informative References
[I-D.ietf.oauth.saml2.bearer]
Campbell, B., and Mortimore, C., "SAML 2.0 Bearer
Assertion Grant Type Profile for OAuth 2.0", ID draft-
ietf-oauth-saml2-bearer-03 (work in progress), Feb 2011.
Appendix A. Contributors
The current draft was based in part on the SAML 2.0 Bearer Assertion
Grant Type profile [I-D.ietf.oauth.saml2.bearer], by B. Campbell and
C. Mortimore.
Appendix B. Document History
[[ to be removed by RFC editor before publication as an RFC ]]
Phil Hunt Expires June 1, 2013 [Page 9]
INTERNET DRAFT Chain Grant Type for OAuth 2 November 28, 2012
draft-hunt-oauth-chain-00
o Initial draft
draft-hunt-oauth-chain-01
o Document refreshed for OAuth WG discussion
Author's Addresses
Phil Hunt (editor)
Oracle Corporation
EMail: phil.hunt@yahoo.com
Phil Hunt Expires June 1, 2013 [Page 10]
