identity 1.0 documentation

JSON Metadata for OAuth Responses

«  OAuth Token Introspection   ::   Contents   ::   OAuth 2.0 Resource Set Registration  »

JSON Metadata for OAuth Responses

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.

( http://tools.ietf.org/html/draft-sakimura-oauth-meta-01 )

( draft 01 )

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.

(draft 01)

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].

(draft 01)

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 relationships (“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.)

{
  "_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}",
        "method":"GET",
        "Authorize":"{token_type} {access_token}"
      },
      {
        "href":"https://example.com/user/{user_id}",
        "method":"POST",
        "Authorize":"{token_type} {access_token}",
        "params":[
          "name","birthday"
        ]
      }
  },
  "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.

Note

  • 上のJSONの例では2つのリレーションシップを含んでいます
    • self
    • Connect UserInfo
  • リレーションシップは、
    • リレーションシップオブジェクト
    • リレーションシップオブジェクトの配列

(draft 01)

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.

(draft 01)

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 specification.

(draft 01)

4.1.1. self

An object with the following members.

href
REQUIRED. The URI that resulted in this response.

( draft 01 )

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.2). 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).
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.5). 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.

(draft 01)

4.2. Error Responses

In the case of the Error Response described in section 5.2. of [RFC6749], the folloing member SHOULD be present.

( draft 01 )

4.2.1. self

An object with the following members.

href
REQUIRED. The URI that resulted in this response.

(draft 01)

4.2.2. describedby

An object with the following members.
href
REQUIRED. The value is “http://tools.ietf.org/html/rfc6749#section-5.2”.

( draft 01 )

5. IANA Considerations

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.

(draft 01)

7. Acknowledgements

This specification borrows heavily from [HAL]. The Link type registration is taken from [oauth-lrdd].

[todo]

(draft 01)

8. References

8.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.

(draft 01)

8.2. Informational References

[HAL]
Kelly, M., “JSON Hypermedia API Language”, 07 2012.
[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.

(draft 01)

«  OAuth Token Introspection   ::   Contents   ::   OAuth 2.0 Resource Set Registration  »