One document matched: draft-sakimura-oauth-meta-00.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-sakimura-oauth-meta-00" ipr="trust200902">
<front>
<title abbrev="Abbreviated-Title">JSON Metadata for OAuth
Responses</title>
<author fullname="Nat Sakimura" initials="N." role="editor"
surname="Sakimura">
<organization>Nomura Research Institute</organization>
<address>
<email>sakimura@gmail.com</email>
</address>
</author>
<date day="12" month="December" year="2012" />
<abstract>
<t>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.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>Although <xref target="RFC6749">OAuth 2.0</xref> 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 "<spanx style="verb">_links</spanx>" that represents various link
relationships and other metadata.</t>
</section>
<section title="Requirements">
<t>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 <xref
target="RFC2119">RFC 2119</xref>.</t>
</section>
<section anchor="metaobjects" title="JSON Meta Object">
<t>A JSON Meta Object uses the format described in <xref
target="RFC4627"></xref> and is intended to be inserted into a JSON
document to express some of the metadata associated with it as <spanx
style="verb">_links</spanx> member.</t>
<t>The value of the <spanx style="verb">_links</spanx> member is a JSON
object that expresses link relationships (<spanx style="verb">rel</spanx>),
which in turn holds an object with <spanx style="verb">href</spanx> and
other members or an array of such objects.</t>
<t>Following non-normative schematic example should help envisage what
it would look like the following. (Note: line-wraps are for display
purpose only.)</t>
<figure>
<artwork><![CDATA[ {
"_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"
}]]></artwork>
</figure>
<t></t>
<t>Here, we have <spanx style="verb">_links</spanx> member that
expresses various "relations" such as <spanx style="verb">self</spanx>
and <spanx style="verb">http://openid.net/specs/connect/1.0/#userinfo_ep</spanx>.
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 <spanx style="verb">href</spanx>. They are
explained in the next section.</t>
<t></t>
<section anchor="_links" title="_links Member">
<t><spanx style="verb">_links</spanx> member holds exactly one object
that contains the following members with relation as the <spanx
style="verb">string</spanx> defined in <xref target="RFC4627"></xref>.
The <spanx style="verb">string</spanx> SHOULD be a link relation type
that is either defined in the IANA registry defined in <xref
format="title" target="RFC5988">Web Linking</xref> or a URI that
describes the relation.</t>
<t>Each relation member holds exactly one object or one array, whose
items are objects. Each object has following members, which are all
optional.</t>
<section anchor="href" title="href">
<t>The value of the <spanx style="verb">href</spanx> member is a
<xref target="RFC6570">URI Template</xref> 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
<spanx style="verb">string</spanx> matches the template variable
name.</t>
</section>
<section anchor="method" title="method">
<t>The value of the <spanx style="verb">method</spanx> member is the
HTTP method defined in <xref target="RFC2616">Hypertext Transfer
Protocol -- HTTP/1.1</xref>[RFC2616] that can be used to the URL
described in the <spanx style="verb">href</spanx>. e.g., GET, POST,
PUT, DELETE.</t>
</section>
<section anchor="params" title="params">
<t>The <spanx style="verb">params</spanx> member describes the
parameters to be sent to the URL expressed in <spanx style="verb">href</spanx>.
The <spanx style="verb">value</spanx> is an array of <spanx
style="verb">pairs</spanx> whose string corresponds to the parameter
names of the parameters that are to be sent to the URL. The <spanx
style="verb">value</spanx> of the <spanx style="verb">pair</spanx>
is an <spanx style="verb">object</spanx> with following <spanx
style="verb">members</spanx> . All <spanx style="verb">members</spanx>
are optional.</t>
<t><list style="hanging">
<t hangText="required">Boolean. true of false. Indicates whether
this parameter is required to be sent with the request.</t>
<t hangText="description">Human readable description of the
variable.</t>
</list></t>
</section>
<section anchor="ctype" title="content-type">
<t>The content-type to be used when the parameters are sent to the
URL.</t>
<t>e.g., <spanx style="verb">application/x-www-form-urlencoded</spanx>,
<spanx style="verb">multipart/form-data</spanx>, <spanx
style="verb">application/json</spanx>.</t>
</section>
<section anchor="authz" title="Authorize">
<t>The HTTP Authorize header defined in <xref
target="RFC2616">Hypertext Transfer Protocol -- HTTP/1.1</xref> to
be used when accessing the resource identified by href. It is
templated in exactly the same syntax as in <xref
target="RFC6570">URI Template</xref> except that it is applied to
the Authorization request header than the URI.</t>
</section>
</section>
</section>
<section anchor="applications"
title="Application to the OAuth 2.0 Token Endpoint References">
<t>To create the <xref target="metaobjects"></xref> should be used in
the token endpoint responses of <xref target="RFC6749">the OAuth 2.0
Authorization Framework</xref>, following relations SHOULD be
included.</t>
<section anchor="sucess" title="Successful Responses">
<t>In the case of the Successful Response described in section 5.1. of
<xref target="RFC6749"></xref>, the following member SHOULD be present
in the value of the <xref target="_links"></xref>.</t>
<section title="self">
<t>An object with the following members.</t>
<t><list style="hanging">
<t hangText="href">REQUIRED. The URI that resulted in this
response.</t>
</list></t>
</section>
<section title="describedby">
<t>An object with the following members.</t>
<t><list style="hanging">
<t hangText="href">REQUIRED. The value is one of the following
URIs: <spanx style="verb">http://tools.ietf.org/html/rfc6749#section-4.1.4</spanx>,
<spanx style="verb">http://tools.ietf.org/html/rfc6749#section-4.3.3</spanx>,
<spanx style="verb">http://tools.ietf.org/html/rfc6749#section-4.4.3</spanx>.</t>
</list></t>
</section>
<section title="Protected Resources">
<t>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.</t>
<t><list style="hanging">
<t hangText="href">REQUIRED. The URI template that describes the
request to the resource as described in <xref
target="href">section 3.1.1. </xref>.</t>
<t hangText="method">OPTIONAL. HTTP request method to be used as
described in <xref target="method">section 3.1.2.</xref>.
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 <spanx style="verb">params</spanx> 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.</t>
<t hangText="params">OPTIONAL. Parameters to be sent as
described in <xref target="params">section 3.1.3.</xref>.</t>
<t hangText="content-type">OPTIONAL. As described in <xref
target="ctype">section 3.1.4.</xref>.</t>
<t hangText="Authorize">OPTIONAL. HTTP Authorization header to
be sent when accessing the resource. This is described in <xref
target="authz">section 3.1.5.</xref>. If this member is not
available, then the client SHOULD access the expanded <spanx
style="verb">href</spanx> value to obtain the Authorization
header response to learn what authorization scheme it should
use.</t>
</list></t>
</section>
</section>
<section anchor="error" title="Error Responses">
<t>In the case of the Error Response described in section 5.2. of
<xref target="RFC6749"></xref>, the folloing member SHOULD be
present.</t>
<section title="self">
<t>An object with the following members.</t>
<t><list style="hanging">
<t hangText="href">REQUIRED. The URI that resulted in this
response.</t>
</list></t>
</section>
<section title="describedby">
<t>An object with the following members.</t>
<t><list style="hanging">
<t hangText="href">REQUIRED. The value is
"http://tools.ietf.org/html/rfc6749#section-5.2".</t>
</list></t>
</section>
</section>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>This document makes no request of IANA.</t>
<t>Note to RFC Editor: this section may be removed on publication as an
RFC.</t>
<section title="Link Type Registration">
<t>Pursuant to <xref target="RFC5988"></xref>, the following link type
registrations [[will be]] registered by mail to
link-relations@ietf.org.</t>
<section title="OAuth 2 Registrations">
<t>The secition 3 of <xref target="RFC6749">the OAuth 2.0
Authorization Framework</xref> defines two endpoints that may be
discovered through this specification. These are the user
Authorization Endpoint and the Token Endpoint.</t>
<section title="Authorization Endpoint">
<t><list style="symbols">
<t>Relation Name: oauth2-authorize</t>
<t>Descritpion: An OAuth 2.0 Authorization Endpoint specified
in section 3.1 of <xref target="RFC6749"></xref></t>
<t>Reference: <xref target="RFC6749"></xref></t>
</list></t>
</section>
<section title="Token Endpoint">
<t><list style="symbols">
<t>Relation Name: oauth2-token</t>
<t>Description: An OAuth 2.0 Token Endpoint specified in
section 3.2 of <xref target="RFC6749"></xref>.</t>
<t>Refeence: <xref target="RFC6749"></xref></t>
</list></t>
</section>
</section>
</section>
</section>
<section anchor="Security" title="Security Considerations">
<t></t>
<section title="href tampering">
<t>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.</t>
</section>
</section>
<section anchor="Acknowledgements" title="Acknowledgements">
<t>This specification borrows heavily from <xref target="HAL"></xref>.
The Link type registration is taken from <xref
target="oauth-lrdd"></xref>.</t>
<t>[todo]</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119"?>
<?rfc include='reference.RFC.2616'?>
<?rfc include='reference.RFC.4627'?>
<?rfc include='reference.RFC.5988'?>
<?rfc include='reference.RFC.6570'?>
<?rfc include='reference.RFC.6749'?>
<?rfc include='reference.RFC.6750'?>
</references>
<references title="Informational References">
<reference anchor="HAL">
<front>
<title>JSON Hypermedia API Language</title>
<author fullname="Mike Kelly" initials="M." surname="Kelly">
<address>
<email>mike@stateless.co</email>
</address>
</author>
<date day="01" month="07" year="2012" />
</front>
</reference>
<reference anchor="oauth-lrdd">
<front>
<title>Link Type Registrations for OAuth 2</title>
<author fullname="William J. Mills" initials="W. J. "
surname="Mills">
<address>
<email>wmills_92105@yahoo.com</email>
</address>
</author>
<date day="10" month="October" year="2012" />
</front>
</reference>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 01:19:58 |