One document matched: draft-sakimura-oauth-meta-02.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-02" ipr="trust200902">
<front>
<title abbrev="OAuth-Meta">JSON Metadata for OAuth Responses 1.0</title>
<author fullname="Mike Kelly" initials="M." surname="Kelly">
<organization>Stateless</organization>
<address>
<email>mike@stateless.co</email>
</address>
</author>
<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="February" year="2013" />
<area>Security</area>
<workgroup>OAuth Working Group</workgroup>
<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 relations (<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. (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}",
"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"
}]]></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
elements 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="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 title="operations">
<t>An array of possible operations on the URI value of the <xref
target="href"></xref>, whose elements are objects that describes the
method and the parameters. </t>
<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> 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 whose elements
represents the name of the parameters to be sent to the URI. </t>
</section>
</section>
<section anchor="ctype" title="content-type">
<t>The content-type to be used when the parameters are sent to the
URL.</t>
<t>[todo] Locate the proper reference and name for content transfer
encodings.</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>
</section>
<section anchor="applications"
title="Application to the OAuth 2.0 Token Endpoint Responses">
<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 <spanx style="verb">_links</spanx> member
described in <xref target="_links">_links Member</xref> of this
specification.</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>
(Access Token Response of Authorization Code Grant), <spanx
style="verb">http://tools.ietf.org/html/rfc6749#section-4.3.3</spanx>
(Access Token Response of Resource Owner Password Credentials
Grant), <spanx style="verb">http://tools.ietf.org/html/rfc6749#section-4.4.3</spanx>
(Access Token Response of Client Credentials Grant ). [[editor's
note. Add Assertion Flows as well.]]</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 <xref target="RFC5988"></xref>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">href
</xref>.</t>
<t hangText="method">OPTIONAL. HTTP request method to be used as
described in <xref target="method">method</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">params</xref>.</t>
<t hangText="content-type">OPTIONAL. As described in <xref
target="ctype">content-type</xref>.</t>
<t hangText="Authorize">OPTIONAL. HTTP Authorization header to
be sent when accessing the resource. This is described in <xref
target="authz">Authorize</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></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>
<section title="Document History">
<t>-02</t>
<t><list style="symbols">
<t>Added Mike Kelly as an author. </t>
<t>xref fix. </t>
<t>Introduced "operations" as in draft-ietf-scim-api-00#section-3.5.
</t>
<t>Updated the informative reference to HAL. </t>
<t>Added description to OAuth Token Endpoint hrefs. </t>
<t>Added content-type to the example. </t>
<t>Added Area and Working Group. </t>
</list></t>
<t>-01</t>
<t><list style="symbols">
<t>Some format changes, reference fix, and typo fixes. </t>
<t>Changed 'items' to 'elements' to match the JSON terminology. </t>
</list></t>
<t>-00</t>
<t><list style="symbols">
<t>Initial Draft</t>
</list></t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119"?>
<?rfc include='reference.RFC.2616'?>
<?rfc include='reference.RFC.5988'?>
<?rfc include='reference.RFC.6570'?>
<?rfc include='reference.RFC.6749'?>
</references>
<references title="Informational References">
<?rfc include='reference.RFC.4627'?>
<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="12" month="February" year="2013" />
</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:32 |