OAuth Working Group M. Kelly
Internet-Draft Stateless
Intended status: Standards Track N. Sakimura, Ed.
Expires: August 16, 2013 Nomura Research Institute
February 12, 2013
JSON Metadata for OAuth Responses 1.0
draft-sakimura-oauth-meta-02
Abstract
This specification defines an extensible metadata member that may be
inserted into the OAuth 2.0 responses to assist the clients to
process those responses. It is expressed as a member called "_links"
that is inserted as the top level member in the responses. It will
allow the client to learn where the members in the response could be
used and how, etc. Since it is just a member, any client that does
not understand this extension should not break and work normally
while supporting clients can utilize the metadata to its advantage.
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 August 16, 2013.
Copyright Notice
Copyright (c) 2013 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
Kelly & Sakimura Expires August 16, 2013 [Page 1]
Internet-Draft OAuth-Meta February 2013
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 . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. JSON Meta Object . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. _links Member . . . . . . . . . . . . . . . . . . . . . . 4
3.1.1. href . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1.2. Authorize . . . . . . . . . . . . . . . . . . . . . . 5
3.1.3. operations . . . . . . . . . . . . . . . . . . . . . . 5
3.1.4. content-type . . . . . . . . . . . . . . . . . . . . . 5
4. Application to the OAuth 2.0 Token Endpoint Responses . . . . 5
4.1. Successful Responses . . . . . . . . . . . . . . . . . . . 5
4.1.1. self . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.1.2. describedby . . . . . . . . . . . . . . . . . . . . . 6
4.1.3. Protected Resources . . . . . . . . . . . . . . . . . 6
4.2. Error Responses . . . . . . . . . . . . . . . . . . . . . 7
4.2.1. self . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.2. describedby . . . . . . . . . . . . . . . . . . . . . 7
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
5.1. Link Type Registration . . . . . . . . . . . . . . . . . . 7
5.1.1. OAuth 2 Registrations . . . . . . . . . . . . . . . . 7
6. Security Considerations . . . . . . . . . . . . . . . . . . . 8
6.1. href tampering . . . . . . . . . . . . . . . . . . . . . . 8
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 8
8. Document History . . . . . . . . . . . . . . . . . . . . . . . 8
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
9.1. Normative References . . . . . . . . . . . . . . . . . . . 9
9.2. Informational References . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
Kelly & Sakimura Expires August 16, 2013 [Page 2]
Internet-Draft OAuth-Meta February 2013
1. Introduction
Although OAuth 2.0 [RFC6749] has been known for its REST
friendliness, OAuth itself is not RESTful, as it heavily relies on
out-of-band information to drive the interactions. This situation
can be eased by hypertext-enabling the JSON responses through the
introduction of a member that represents such hypertext and other
metadata. To achieve this, this specification introduces a top level
member "_links" that represents various link relationships and other
metadata.
2. Requirements
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].
3. JSON Meta Object
A JSON Meta Object uses the format described in [RFC4627] and is
intended to be inserted into a JSON document to express some of the
metadata associated with it as "_links" member.
The value of the "_links" member is a JSON object that expresses link
relations ("rel"), which in turn holds an object with "href" and
other members or an array of such objects.
Following non-normative schematic example should help envisage what
it would look like. (Note: line-wraps are for display purpose only.)
Kelly & Sakimura Expires August 16, 2013 [Page 3]
Internet-Draft OAuth-Meta February 2013
{
"_links":{
"self":{"href":"https://example.com/token?code=123"},
"http://openid.net/specs/connect/1.0/#userinfo_ep":
{
"href":"https://example.com/user/{user_id}",
"Authorize":"{token_type} {access_token}",
"operations":[
{ "method":"GET"},
{
"method":"POST",
"params":["name","birthday"],
"content-type":"application/x-www-form-urlencoded"
}
]
}
},
"token_type":"Bearer",
"access_token":"aCeSsToKen"
}
Here, we have "_links" member that expresses various "relations" such
as "self" and "http://openid.net/specs/connect/1.0/#userinfo_ep".
Each relationships has either a link relations object or an array of
link relations objects as its value. The link relations objects
holds various members such as "href". They are explained in the next
section.
3.1. _links Member
"_links" member holds exactly one object that contains the following
members with relation as the "string" defined in [RFC4627]. The
"string" SHOULD be a link relation type that is either defined in the
IANA registry defined in Web Linking [RFC5988] or a URI that
describes the relation.
Each relation member holds exactly one object or one array, whose
elements are objects. Each object has following members, which are
all optional.
3.1.1. href
The value of the "href" member is a URI Template [RFC6570] that the
relation points to. The values for template parameters SHOULD be
taken from the value of the top-level members in the including JSON
object whose "string" matches the template variable name.
Kelly & Sakimura Expires August 16, 2013 [Page 4]
Internet-Draft OAuth-Meta February 2013
3.1.2. Authorize
The HTTP Authorize header defined in Hypertext Transfer Protocol --
HTTP/1.1 [RFC2616] to be used when accessing the resource identified
by href. It is templated in exactly the same syntax as in URI
Template [RFC6570] except that it is applied to the Authorization
request header than the URI.
3.1.3. operations
An array of possible operations on the URI value of the
Section 3.1.1, whose elements are objects that describes the method
and the parameters.
3.1.3.1. method
The value of the "method" member is the HTTP method defined in
Hypertext Transfer Protocol -- HTTP/1.1 [RFC2616] that can be used to
the URL described in the "href". e.g., GET, POST, PUT, DELETE.
3.1.3.2. params
The "params" member describes the parameters to be sent to the URL
expressed in "href". The "value" is an array whose elements
represents the name of the parameters to be sent to the URI.
3.1.4. content-type
The content-type to be used when the parameters are sent to the URL.
[todo] Locate the proper reference and name for content transfer
encodings.
e.g., "application/x-www-form-urlencoded", "multipart/form-data",
"application/json".
4. Application to the OAuth 2.0 Token Endpoint Responses
To create the Section 3 should be used in the token endpoint
responses of the OAuth 2.0 Authorization Framework [RFC6749],
following relations SHOULD be included.
4.1. Successful Responses
In the case of the Successful Response described in section 5.1. of
[RFC6749], the following member SHOULD be present in the value of the
"_links" member described in _links Member (Section 3.1) of this
Kelly & Sakimura Expires August 16, 2013 [Page 5]
Internet-Draft OAuth-Meta February 2013
specification.
4.1.1. self
An object with the following members.
href REQUIRED. The URI that resulted in this response.
4.1.2. describedby
An object with the following members.
href REQUIRED. The value is one of the following URIs:
"http://tools.ietf.org/html/rfc6749#section-4.1.4" (Access Token
Response of Authorization Code Grant),
"http://tools.ietf.org/html/rfc6749#section-4.3.3" (Access Token
Response of Resource Owner Password Credentials Grant),
"http://tools.ietf.org/html/rfc6749#section-4.4.3" (Access Token
Response of Client Credentials Grant ). [[editor's note. Add
Assertion Flows as well.]]
4.1.3. Protected Resources
Each protected resources MUST provide a unique Relation Name by
either registering to the Link Relation Type Registry defined in
section 6.2 of [RFC5988]or providing an absolute URI that provides a
collision registant name. The value is an array of objects that has
the following members.
href REQUIRED. The URI template that describes the request to the
resource as described in href (Section 3.1.1).
method OPTIONAL. HTTP request method to be used as described in
method (Section 3.1.3.1). Defaults to "GET". Semantics of the
HTTP methods in this case SHOULD map as follows: "GET" means
reading the resource. "POST" means creating or updating the
resource with supplied parameters in "params" member below.
"DELETE" means deleting the corresponding resource. "PUT" means
the complete replacement of the resource by the body of the
request. The resource MUST support "GET" method. The support of
other methods are OPTIONAL.
params OPTIONAL. Parameters to be sent as described in params
(Section 3.1.3.2).
Kelly & Sakimura Expires August 16, 2013 [Page 6]
Internet-Draft OAuth-Meta February 2013
content-type OPTIONAL. As described in content-type
(Section 3.1.4).
Authorize OPTIONAL. HTTP Authorization header to be sent when
accessing the resource. This is described in Authorize
(Section 3.1.2). If this member is not available, then the client
SHOULD access the expanded "href" value to obtain the
Authorization header response to learn what authorization scheme
it should use.
4.2. Error Responses
In the case of the Error Response described in section 5.2. of
[RFC6749], the folloing member SHOULD be present.
4.2.1. self
An object with the following members.
href REQUIRED. The URI that resulted in this response.
4.2.2. describedby
An object with the following members.
href REQUIRED. The value is
"http://tools.ietf.org/html/rfc6749#section-5.2".
5. IANA Considerations
5.1. Link Type Registration
Pursuant to [RFC5988], the following link type registrations [[will
be]] registered by mail to link-relations@ietf.org.
5.1.1. OAuth 2 Registrations
The secition 3 of the OAuth 2.0 Authorization Framework [RFC6749]
defines two endpoints that may be discovered through this
specification. These are the user Authorization Endpoint and the
Token Endpoint.
5.1.1.1. Authorization Endpoint
o Relation Name: oauth2-authorize
Kelly & Sakimura Expires August 16, 2013 [Page 7]
Internet-Draft OAuth-Meta February 2013
o Descritpion: An OAuth 2.0 Authorization Endpoint specified in
section 3.1 of [RFC6749]
o Reference: [RFC6749]
5.1.1.2. Token Endpoint
o Relation Name: oauth2-token
o Description: An OAuth 2.0 Token Endpoint specified in section 3.2
of [RFC6749].
o Refeence: [RFC6749]
6. Security Considerations
6.1. href tampering
Unless integrity protected channel is used, an attacker may be able
to tamper the value of the href thereby causing the receiver of the
JSON response to send a request to the URL under the attacker's
control with potentially confidential information contained in the
parameters. To mitigate this risk, an integrity protected channel
such as TLS protected channel should be used.
7. Acknowledgements
This specification borrows heavily from [HAL]. The Link type
registration is taken from [oauth-lrdd].
[todo]
8. Document History
-02
o Added Mike Kelly as an author.
o xref fix.
o Introduced "operations" as in draft-ietf-scim-api-00#section-3.5.
o Updated the informative reference to HAL.
Kelly & Sakimura Expires August 16, 2013 [Page 8]
Internet-Draft OAuth-Meta February 2013
o Added description to OAuth Token Endpoint hrefs.
o Added content-type to the example.
o Added Area and Working Group.
-01
o Some format changes, reference fix, and typo fixes.
o Changed 'items' to 'elements' to match the JSON terminology.
-00
o Initial Draft
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, March 2012.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework",
RFC 6749, October 2012.
9.2. Informational References
[HAL] Kelly, M., "JSON Hypermedia API Language", February 2013.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[oauth-lrdd]
Mills, W., "Link Type Registrations for OAuth 2",
October 2012.
Kelly & Sakimura Expires August 16, 2013 [Page 9]
Internet-Draft OAuth-Meta February 2013
Authors' Addresses
Mike Kelly
Stateless
Email: mike@stateless.co
Nat Sakimura (editor)
Nomura Research Institute
Email: sakimura@gmail.com
Kelly & Sakimura Expires August 16, 2013 [Page 10]