rfc9635xml2.original.xml   rfc9635.xml 
<?xml version="1.0" encoding="UTF-8"?> <?xml version='1.0' encoding='utf-8'?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?> <!DOCTYPE rfc [
<!-- generated by https://github.com/cabo/kramdown-rfc version 1.7.5 (Ruby 3.1
.2) -->
<!DOCTYPE rfc [
<!ENTITY nbsp "&#160;"> <!ENTITY nbsp "&#160;">
<!ENTITY zwsp "&#8203;"> <!ENTITY zwsp "&#8203;">
<!ENTITY nbhy "&#8209;"> <!ENTITY nbhy "&#8209;">
<!ENTITY wj "&#8288;"> <!ENTITY wj "&#8288;">
<!ENTITY SELF "RFC nnnn">
]> ]>
<?rfc tocindent="yes"?> <rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="trust200902" docName="draft
<?rfc strict="yes"?> -ietf-gnap-core-protocol-19" number="9635" obsoletes="" updates="" submissionTyp
<?rfc compact="yes"?> e="IETF" category="std" consensus="true" tocInclude="true" sortRefs="true" symRe
<?rfc comments="yes"?> fs="true" version="3" xml:lang="en" >
<?rfc inline="yes"?>
<?rfc docmapping="yes"?>
<rfc ipr="trust200902" docName="draft-ietf-gnap-core-protocol-19" category="std" consensus="true" tocInclude="true" sortRefs="true" symRefs="true">
<front> <front>
<title>Grant Negotiation and Authorization Protocol</title> <title>Grant Negotiation and Authorization Protocol (GNAP)</title>
<seriesInfo name="RFC" value="9635"/>
<author initials="J." surname="Richer" fullname="Justin Richer" role="editor "> <author initials="J." surname="Richer" fullname="Justin Richer" role="editor ">
<organization>Bespoke Engineering</organization> <organization>Bespoke Engineering</organization>
<address> <address>
<email>ietf@justin.richer.org</email> <email>ietf@justin.richer.org</email>
<uri>https://bspk.io/</uri> <uri>https://bspk.io/</uri>
</address> </address>
</author> </author>
<author initials="F." surname="Imbault" fullname="Fabien Imbault"> <author initials="F." surname="Imbault" fullname="Fabien Imbault">
<organization>acert.io</organization> <organization>acert.io</organization>
<address> <address>
<email>fabien.imbault@acert.io</email> <email>fabien.imbault@acert.io</email>
<uri>https://acert.io/</uri> <uri>https://acert.io/</uri>
</address> </address>
</author> </author>
<date year="2024" month="March" day="09"/> <date year="2024" month="October"/>
<area>Security</area> <area>SEC</area>
<workgroup>GNAP</workgroup> <workgroup>gnap</workgroup>
<keyword>Internet-Draft</keyword>
<abstract> <abstract>
<t>The Grant Negotiation and Authorization Protocol (GNAP) defines a mecha
<?line 158?> nism for delegating authorization to a piece of
software and conveying the results and artifacts of that delegation to
<t>GNAP defines a mechanism for delegating authorization to a the software. This delegation can include access to a set of APIs as
piece of software, and conveying the results and artifacts of that delegation to well as subject information passed directly to the software.</t>
the software. This
delegation can include access to a set of APIs as well as subject information
passed directly to the software.</t>
</abstract> </abstract>
</front> </front>
<middle> <middle>
<?line 165?> <section anchor="introduction">
<name>Introduction</name>
<section anchor="introduction"><name>Introduction</name> <t>GNAP allows a piece of software, the client instance, to request delega
ted
<t>This protocol allows a piece of software, the client instance, to request del
egated
authorization to resource servers and subject information. The delegated access to authorization to resource servers and subject information. The delegated access to
the resource server can be used by the client instance to access resources and A PIs the resource server can be used by the client instance to access resources and A PIs
on behalf a resource owner, and delegated access to on behalf a resource owner, and delegated access to
subject information can in turn be used by the client instance to make authentic ation decisions. subject information can in turn be used by the client instance to make authentic ation decisions.
This delegation is facilitated by an authorization server usually on This delegation is facilitated by an authorization server, usually on
behalf of a resource owner. The end user operating the software can interact behalf of a resource owner. The end user operating the software can interact
with the authorization server to authenticate, provide consent, and with the authorization server to authenticate, provide consent, and
authorize the request as a resource owner.</t> authorize the request as a resource owner.</t>
<t>The process by which the delegation happens is known as a grant, and
<t>The process by which the delegation happens is known as a grant, and
GNAP allows for the negotiation of the grant process GNAP allows for the negotiation of the grant process
over time by multiple parties acting in distinct roles.</t> over time by multiple parties acting in distinct roles.</t>
<t>This specification focuses on the portions of the delegation process facing t he client instance. <t>This specification focuses on the portions of the delegation process facing t he client instance.
In particular, this specification defines interoperable methods for a client ins tance to request, negotiate, In particular, this specification defines interoperable methods for a client ins tance to request, negotiate,
and receive access to information facilitated by the authorization server. and receive access to information facilitated by the authorization server.
This specification additionally defines methods for the client instance to acces s This specification additionally defines methods for the client instance to acces s
protected resources at a resource server. protected resources at a resource server.
This specification also discusses discovery mechanisms for the client instance t o This specification also discusses discovery mechanisms that enable the client in stance to
configure itself dynamically. configure itself dynamically.
The means for an authorization server and resource server to interoperate are The means for an authorization server and resource server to interoperate are
discussed in the companion document, <xref target="I-D.ietf-gnap-resource-server discussed in <xref target="I-D.ietf-gnap-resource-servers"/>.</t>
s"/>.</t> <t>The focus of this protocol is to provide interoperability between the d
ifferent
<t>The focus of this protocol is to provide interoperability between the differe parties acting in each role, not to specify implementation details of each.
nt
parties acting in each role, and is not to specify implementation details of eac
h.
Where appropriate, GNAP may make recommendations about internal implementation Where appropriate, GNAP may make recommendations about internal implementation
details, but these recommendations are to ensure the security of the overall details, but these recommendations are to ensure the security of the overall
deployment rather than to be prescriptive in the implementation.</t> deployment rather than to be prescriptive in the implementation.</t>
<t>This protocol solves many of the same use cases as OAuth 2.0 <xref targ
<t>This protocol solves many of the same use cases as OAuth 2.0 <xref target="RF et="RFC6749"/>,
C6749"/>,
OpenID Connect <xref target="OIDC"/>, and the family of protocols that have grow n up OpenID Connect <xref target="OIDC"/>, and the family of protocols that have grow n up
around that ecosystem. However, GNAP is not an extension of OAuth 2.0 around that ecosystem. However, GNAP is not an extension of OAuth 2.0
and is not intended to be directly compatible with OAuth 2.0. GNAP seeks to and is not intended to be directly compatible with OAuth 2.0. GNAP seeks to
provide functionality and solve use cases that OAuth 2.0 cannot easily provide functionality and solve use cases that OAuth 2.0 cannot easily
or cleanly address. <xref target="vs-oauth2"/> further details the protocol rati onale compared to OAuth 2.0. or cleanly address. <xref target="vs-oauth2"/> further details the protocol rati onale compared to OAuth 2.0.
GNAP and OAuth 2.0 will likely exist in parallel GNAP and OAuth 2.0 will likely exist in parallel
for many deployments, and considerations have been taken to facilitate for many deployments, and considerations have been taken to facilitate
the mapping and transition from existing OAuth 2.0 systems to GNAP. Some example s the mapping and transition from existing OAuth 2.0 systems to GNAP. Some example s
of these can be found in <xref target="example-oauth2"/>.</t> of these can be found in <xref target="example-oauth2"/>.</t>
<section anchor="terminology">
<name>Terminology</name>
<section anchor="terminology"><name>Terminology</name> <t>
The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
<t>The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUI "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>
RED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL ",
NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECO "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
MMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to be i "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to
nterpreted as be
described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and interpreted as described in BCP&nbsp;14 <xref target="RFC2119"/> <xref
only when, they target="RFC8174"/> when, and only when, they appear in all capitals, as
appear in all capitals, as shown here.</t> shown here.
</t>
<?line -18?>
<t>This document contains non-normative examples of partial and complete HTTP me
ssages, JSON structures, URIs, query components, keys, and other elements. Whene
ver possible, the document uses URI as a generic term, since it aligns with <xre
f target="RFC3986"/> recommendations and matches better with the intent that the
identifier may be reachable through various/generic means (compared to URLs). S
ome examples use a single trailing backslash <spanx style="verb">\</spanx> to in
dicate line wrapping for long values, as per <xref target="RFC8792"/>. The <span
x style="verb">\</spanx> character and leading spaces on wrapped lines are not p
art of the value.</t>
<t>This document uses the term "mutual TLS" as defined by <xref target="RFC8705"
/>. The shortened form "MTLS" is used to mean the same thing.</t>
<t>For brevity, the term "signature" on its own is used in this document to refe
r to both digital signatures (which use asymmetric cryptography) and keyed MACs
(which use symmetric cryptography). Similarly, the verb "sign" refers to the gen
eration of either a digital signature or keyed MAC over a given signature base.
The qualified term "digital signature" refers specifically to the output of an a
symmetric cryptographic signing operation.</t>
</section>
<section anchor="roles"><name>Roles</name>
<t>The parties in GNAP perform actions under different roles. <t>This document contains non-normative examples of partial and complete HTTP me
ssages, JSON structures, URIs, query components, keys, and other elements. Whene
ver possible, the document uses URI as a generic term, since it aligns with the
recommendations in <xref target="RFC3986"/> and better matches the intent that t
he identifier may be reachable through various/generic means (compared to URLs).
Some examples use a single trailing backslash (<tt>\</tt>) to indicate line wra
pping for long values, as per <xref target="RFC8792"/>. The <tt>\</tt> character
and leading spaces on wrapped lines are not part of the value.</t>
<t>This document uses the term "mutual TLS" as defined by <xref target="
RFC8705"/>. The shortened form "MTLS" is used to mean the same thing.</t>
<t>For brevity, the term "signature" on its own is used in this document
to refer to both digital signatures (which use asymmetric cryptography) and key
ed Message Authentication Codes (MACs) (which use symmetric cryptography). Simil
arly, the verb "sign" refers to the generation of either a digital signature or
a keyed MAC over a given signature base. The qualified term "digital signature"
refers specifically to the output of an asymmetric cryptographic signing operati
on.</t>
</section>
<section anchor="roles">
<name>Roles</name>
<t>The parties in GNAP perform actions under different roles.
Roles are defined by the actions taken and the expectations leveraged Roles are defined by the actions taken and the expectations leveraged
on the role by the overall protocol.</t> on the role by the overall protocol.</t>
<figure title="Figure 1: Roles in GNAP"><artset><artwork type="svg"><svg xmlns= <figure>
"http://www.w3.org/2000/svg" version="1.1" height="432" width="472" viewBox="0 0 <name>Roles in GNAP</name>
472 432" class="diagram" text-anchor="middle" font-family="monospace" font-size <artset>
="13px" stroke-linecap="round"> <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" version=
<path d="M 8,32 L 8,112" fill="none" stroke="black"/> "1.1" height="432" width="472" viewBox="0 0 472 432" class="diagram" text-anchor
<path d="M 8,240 L 8,288" fill="none" stroke="black"/> ="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 58,112 L 58,224" fill="none" stroke="black"/><path d="M 54,112 L 54,2 <path d="M 8,32 L 8,112" fill="none" stroke="black"/>
24" fill="none" stroke="black"/> <path d="M 8,240 L 8,288" fill="none" stroke="black"/>
<path d="M 104,240 L 104,288" fill="none" stroke="black"/> <path d="M 58,112 L 58,224" fill="none" stroke="black"/>
<path d="M 120,32 L 120,112" fill="none" stroke="black"/> <path d="M 54,112 L 54,224" fill="none" stroke="black"/>
<path d="M 128,144 L 128,192" fill="none" stroke="black"/> <path d="M 104,240 L 104,288" fill="none" stroke="black"/>
<path d="M 152,96 L 152,144" fill="none" stroke="black"/> <path d="M 120,32 L 120,112" fill="none" stroke="black"/>
<path d="M 170,192 L 170,240" fill="none" stroke="black"/><path d="M 166,192 L 1 <path d="M 128,144 L 128,192" fill="none" stroke="black"/>
66,240" fill="none" stroke="black"/> <path d="M 152,96 L 152,144" fill="none" stroke="black"/>
<path d="M 184,96 L 184,144" fill="none" stroke="black"/> <path d="M 170,192 L 170,240" fill="none" stroke="black"/>
<path d="M 216,144 L 216,192" fill="none" stroke="black"/> <path d="M 166,192 L 166,240" fill="none" stroke="black"/>
<path d="M 216,240 L 216,288" fill="none" stroke="black"/> <path d="M 184,96 L 184,144" fill="none" stroke="black"/>
<path d="M 224,32 L 224,112" fill="none" stroke="black"/> <path d="M 216,144 L 216,192" fill="none" stroke="black"/>
<path d="M 320,240 L 320,288" fill="none" stroke="black"/> <path d="M 216,240 L 216,288" fill="none" stroke="black"/>
<path d="M 328,32 L 328,112" fill="none" stroke="black"/> <path d="M 224,32 L 224,112" fill="none" stroke="black"/>
<path d="M 8,32 L 120,32" fill="none" stroke="black"/> <path d="M 320,240 L 320,288" fill="none" stroke="black"/>
<path d="M 224,32 L 328,32" fill="none" stroke="black"/> <path d="M 328,32 L 328,112" fill="none" stroke="black"/>
<path d="M 128,96 L 152,96" fill="none" stroke="black"/> <path d="M 8,32 L 120,32" fill="none" stroke="black"/>
<path d="M 184,96 L 216,96" fill="none" stroke="black"/> <path d="M 224,32 L 328,32" fill="none" stroke="black"/>
<path d="M 8,112 L 120,112" fill="none" stroke="black"/> <path d="M 128,96 L 152,96" fill="none" stroke="black"/>
<path d="M 224,112 L 328,112" fill="none" stroke="black"/> <path d="M 184,96 L 216,96" fill="none" stroke="black"/>
<path d="M 128,144 L 216,144" fill="none" stroke="black"/> <path d="M 8,112 L 120,112" fill="none" stroke="black"/>
<path d="M 128,192 L 216,192" fill="none" stroke="black"/> <path d="M 224,112 L 328,112" fill="none" stroke="black"/>
<path d="M 24,224 L 88,224" fill="none" stroke="black"/> <path d="M 128,144 L 216,144" fill="none" stroke="black"/>
<path d="M 232,224 L 304,224" fill="none" stroke="black"/> <path d="M 128,192 L 216,192" fill="none" stroke="black"/>
<path d="M 168,238 L 216,238" fill="none" stroke="black"/><path d="M 168,242 L 2 <path d="M 24,224 L 88,224" fill="none" stroke="black"/>
16,242" fill="none" stroke="black"/> <path d="M 232,224 L 304,224" fill="none" stroke="black"/>
<path d="M 24,304 L 88,304" fill="none" stroke="black"/> <path d="M 168,238 L 216,238" fill="none" stroke="black"/>
<path d="M 232,304 L 304,304" fill="none" stroke="black"/> <path d="M 168,242 L 216,242" fill="none" stroke="black"/>
<path d="M 8,366 L 40,366" fill="none" stroke="black"/><path d="M 8,370 L 40,370 <path d="M 24,304 L 88,304" fill="none" stroke="black"/>
" fill="none" stroke="black"/> <path d="M 232,304 L 304,304" fill="none" stroke="black"/>
<path d="M 8,384 L 40,384" fill="none" stroke="black"/> <path d="M 8,366 L 40,366" fill="none" stroke="black"/>
<path d="M 24,224 C 15.16936,224 8,231.16936 8,240" fill="none" stroke="black"/> <path d="M 8,370 L 40,370" fill="none" stroke="black"/>
<path d="M 88,224 C 96.83064,224 104,231.16936 104,240" fill="none" stroke="blac <path d="M 8,384 L 40,384" fill="none" stroke="black"/>
k"/> <path d="M 24,224 C 15.16936,224 8,231.16936 8,240" fill="none"
<path d="M 232,224 C 223.16936,224 216,231.16936 216,240" fill="none" stroke="bl stroke="black"/>
ack"/> <path d="M 88,224 C 96.83064,224 104,231.16936 104,240" fill="no
<path d="M 304,224 C 312.83064,224 320,231.16936 320,240" fill="none" stroke="bl ne" stroke="black"/>
ack"/> <path d="M 232,224 C 223.16936,224 216,231.16936 216,240" fill="
<path d="M 24,304 C 15.16936,304 8,296.83064 8,288" fill="none" stroke="black"/> none" stroke="black"/>
<path d="M 88,304 C 96.83064,304 104,296.83064 104,288" fill="none" stroke="blac <path d="M 304,224 C 312.83064,224 320,231.16936 320,240" fill="
k"/> none" stroke="black"/>
<path d="M 232,304 C 223.16936,304 216,296.83064 216,288" fill="none" stroke="bl <path d="M 24,304 C 15.16936,304 8,296.83064 8,288" fill="none"
ack"/> stroke="black"/>
<path d="M 304,304 C 312.83064,304 320,296.83064 320,288" fill="none" stroke="bl <path d="M 88,304 C 96.83064,304 104,296.83064 104,288" fill="no
ack"/> ne" stroke="black"/>
<polygon class="arrowhead" points="224,96 212,90.4 212,101.6" fill="black" trans <path d="M 232,304 C 223.16936,304 216,296.83064 216,288" fill="
form="rotate(0,216,96)"/> none" stroke="black"/>
<polygon class="arrowhead" points="136,96 124,90.4 124,101.6" fill="black" trans <path d="M 304,304 C 312.83064,304 320,296.83064 320,288" fill="
form="rotate(180,128,96)"/> none" stroke="black"/>
<g class="text"> <polygon class="arrowhead" points="224,96 212,90.4 212,101.6" fi
<text x="64" y="68">Authorization</text> ll="black" transform="rotate(0,216,96)"/>
<text x="276" y="68">Resource</text> <polygon class="arrowhead" points="136,96 124,90.4 124,101.6" fi
<text x="60" y="84">Server</text> ll="black" transform="rotate(180,128,96)"/>
<text x="276" y="84">Server</text> <g class="text">
<text x="172" y="164">Client</text> <text x="64" y="68">Authorization</text>
<text x="172" y="180">Instance</text> <text x="276" y="68">Resource</text>
<text x="60" y="260">Resource</text> <text x="60" y="84">Server</text>
<text x="264" y="260">End</text> <text x="276" y="84">Server</text>
<text x="56" y="276">Owner</text> <text x="172" y="164">Client</text>
<text x="120" y="276">~</text> <text x="172" y="180">Instance</text>
<text x="136" y="276">~</text> <text x="60" y="260">Resource</text>
<text x="152" y="276">~</text> <text x="264" y="260">End</text>
<text x="168" y="276">~</text> <text x="56" y="276">Owner</text>
<text x="184" y="276">~</text> <text x="120" y="276">~</text>
<text x="200" y="276">~</text> <text x="136" y="276">~</text>
<text x="268" y="276">User</text> <text x="152" y="276">~</text>
<text x="28" y="340">Legend</text> <text x="168" y="276">~</text>
<text x="88" y="372">indicates</text> <text x="184" y="276">~</text>
<text x="176" y="372">interaction</text> <text x="200" y="276">~</text>
<text x="256" y="372">between</text> <text x="268" y="276">User</text>
<text x="296" y="372">a</text> <text x="28" y="340">Legend:</text>
<text x="328" y="372">human</text> <text x="88" y="372">indicates</text>
<text x="368" y="372">and</text> <text x="176" y="372">interaction</text>
<text x="420" y="372">computer</text> <text x="256" y="372">between</text>
<text x="88" y="388">indicates</text> <text x="296" y="372">a</text>
<text x="176" y="388">interaction</text> <text x="328" y="372">human</text>
<text x="256" y="388">between</text> <text x="368" y="372">and</text>
<text x="304" y="388">two</text> <text x="420" y="372">computer</text>
<text x="348" y="388">pieces</text> <text x="88" y="388">indicates</text>
<text x="388" y="388">of</text> <text x="176" y="388">interaction</text>
<text x="436" y="388">software</text> <text x="256" y="388">between</text>
<text x="8" y="404">~</text> <text x="304" y="388">two</text>
<text x="24" y="404">~</text> <text x="348" y="388">pieces</text>
<text x="40" y="404">~</text> <text x="388" y="388">of</text>
<text x="88" y="404">indicates</text> <text x="436" y="388">software</text>
<text x="136" y="404">a</text> <text x="8" y="404">~</text>
<text x="184" y="404">potential</text> <text x="24" y="404">~</text>
<text x="272" y="404">equivalence</text> <text x="40" y="404">~</text>
<text x="332" y="404">or</text> <text x="88" y="404">indicates</text>
<text x="392" y="404">out-of-band</text> <text x="136" y="404">a</text>
<text x="136" y="420">communication</text> <text x="184" y="404">potential</text>
<text x="224" y="420">between</text> <text x="272" y="404">equivalence</text>
<text x="280" y="420">roles</text> <text x="332" y="404">or</text>
</g> <text x="392" y="404">out-of-band</text>
</svg> <text x="136" y="420">communication</text>
</artwork><artwork type="ascii-art"><![CDATA[ <text x="224" y="420">between</text>
<text x="280" y="420">roles</text>
</g>
</svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
+-------------+ +------------+ +-------------+ +------------+
| | | | | | | |
|Authorization| | Resource | |Authorization| | Resource |
| Server | | Server | | Server | | Server |
| |<--+ +--->| | | |<--+ +--->| |
+-----+-------+ | | +------------+ +-----+-------+ | | +------------+
║ | | ║ | |
║ +--+---+---+ ║ +--+---+---+
║ | Client | ║ | Client |
║ | Instance | ║ | Instance |
║ +----+-----+ ║ +----+-----+
║ ║ ║ ║
.----+----. ║ .----------. .----+----. ║ .----------.
| | +=====+ | | | +=====+ |
| Resource | | End | | Resource | | End |
| Owner | ~ ~ ~ ~ ~ ~ | User | | Owner | ~ ~ ~ ~ ~ ~ | User |
| | | | | | | |
`---------` `----------` `---------` `----------`
Legend Legend:
===== indicates interaction between a human and computer ===== indicates interaction between a human and computer
----- indicates interaction between two pieces of software ----- indicates interaction between two pieces of software
~ ~ ~ indicates a potential equivalence or out-of-band ~ ~ ~ indicates a potential equivalence or out-of-band
communication between roles communication between roles
]]></artwork></artset></figure> ]]></artwork>
</artset>
<dl> </figure>
<dt>Authorization Server (AS):</dt> <dl>
<dd> <dt>Authorization Server (AS):</dt>
<t>server that grants delegated privileges to a particular instance of clien <dd>
t software in the form of access tokens or other information (such as subject in <t>Server that grants delegated privileges to a particular instance
formation). The AS is uniquely defined by the <em>grant endpoint URI</em>, which of client software in the form of access tokens or other information (such as su
is the absolute URI where grant requests are started by clients.</t> bject information). The AS is uniquely defined by the grant endpoint URI, which
</dd> is the absolute URI where grant requests are started by clients.</t>
<dt>Client:</dt> </dd>
<dd> <dt>Client:</dt>
<t>application that consumes resources from one or several RSs, possibly req <dd>
uiring access privileges from one or several ASs. The client is operated by the <t>Application that consumes resources from one or several resource
end user or it runs autonomously on behalf of a resource owner. servers, possibly requiring access privileges from one or several ASes. The clie
nt is operated by the end user, or it runs autonomously on behalf of a resource
owner.
</t> </t>
<t>For example, a client can be a mobile application, a web applicat
<t>Example: a client can be a mobile application, a web application, a back- ion, a backend data processor, etc.</t>
end data processor, etc.</t> <t>Note: This specification differentiates between a specific instan
ce (the client instance, identified by its unique key) and the software running
<t>Note: this specification differentiates between a specific instance (the the instance (the client software). For some kinds of client software, there cou
client instance, identified by its unique key) and the software running the inst ld be many instances of that software, each instance with a different key.</t>
ance (the client software). For some kinds of client software, there could be ma </dd>
ny instances of that software, each instance with a different key.</t> <dt>Resource Server (RS):</dt>
</dd> <dd>
<dt>Resource Server (RS):</dt> <t>Server that provides an API on protected resources, where operati
<dd> ons on the API require a valid access token issued by a trusted AS.</t>
<t>server that provides an API on protected resources, where operations on t </dd>
he API require a valid access token issued by a trusted AS.</t> <dt>Resource Owner (RO):</dt>
</dd> <dd>
<dt>Resource Owner (RO):</dt> <t>Subject entity that may grant or deny operations on resources it
<dd> has authority upon.
<t>subject entity that may grant or deny operations on resources it has auth
ority upon.
</t> </t>
<t>Note: The act of granting or denying an operation may be manual (
<t>Note: the act of granting or denying an operation may be manual (i.e. thr i.e., through an interaction with a physical person) or automatic (i.e., through
ough an interaction with a physical person) or automatic (i.e. through predefine predefined organizational rules).</t>
d organizational rules).</t> </dd>
</dd> <dt>End user:</dt>
<dt>End user:</dt> <dd>
<dd> <t>Natural person that operates a client instance.
<t>natural person that operates a client instance.
</t> </t>
<t>Note: That natural person may or may not be the same entity as th
<t>Note: that natural person may or may not be the same entity as the RO.</t e RO.</t>
> </dd>
</dd> </dl>
</dl> <t>The design of GNAP does not assume any one deployment architecture
<t>The design of GNAP does not assume any one deployment architecture,
but instead attempts to define roles that can be fulfilled in a number but instead attempts to define roles that can be fulfilled in a number
of different ways for different use cases. As long as a given role fulfills of different ways for different use cases. As long as a given role fulfills
all of its obligations and behaviors as defined by the protocol, GNAP does all of its obligations and behaviors as defined by the protocol, GNAP does
not make additional requirements on its structure or setup.</t> not make additional requirements on its structure or setup.</t>
<t>Multiple roles can be fulfilled by the same party, and a given party
<t>Multiple roles can be fulfilled by the same party, and a given party can switch roles in different instances of the protocol. For example, in many in
can switch roles in different instances of the protocol. For example, stances,
the RO and end user in many instances are the same person, where a user is the RO and end user are the same person, where a user
authorizing the client instance to act on their own behalf at the RS. In this ca authorizes the client instance to act on their own behalf at the RS. In this cas
se, e,
one party fulfills both of the RO and end-user roles, but the roles themselves one party fulfills the roles of both RO and end user, but the roles themselves
are still defined separately from each other to allow for other are still defined separately from each other to allow for other
use cases where they are fulfilled by different parties.</t> use cases where they are fulfilled by different parties.</t>
<t>As another example,
<t>For another example,
in some complex scenarios, an RS receiving requests from one client instance can act as in some complex scenarios, an RS receiving requests from one client instance can act as
a client instance for a downstream secondary RS in order to fulfill the a client instance for a downstream secondary RS in order to fulfill the
original request. In this case, one piece of software is both an original request. In this case, one piece of software is both an
RS and a client instance from different perspectives, and it fulfills these RS and a client instance from different perspectives, and it fulfills these
roles separately as far as the overall protocol is concerned.</t> roles separately as far as the overall protocol is concerned.</t>
<t>A single role need not be deployed as a monolithic service. For examp
<t>A single role need not be deployed as a monolithic service. For example, le,
a client instance could have front-end components that are installed on the end a client instance could have frontend components that are installed on the end u
user's device as ser's device as
well as a back-end system that the front-end communicates with. If both of these well as a backend system that the frontend communicates with. If both of these
components participate in the delegation protocol, they are both considered components participate in the delegation protocol, they are both considered
part of the client instance. If there are several copies of the client software part of the client instance. If there are several copies of the client software
that run separately but all share the same key material, such as a that run separately but all share the same key material, such as a
deployed cluster, then this cluster is considered a single client instance. deployed cluster, then this cluster is considered a single client instance.
In these cases, the distinct components of what is considered a GNAP client inst ance In these cases, the distinct components of what is considered a GNAP client inst ance
may use any number of different communication mechanisms between them, all of wh ich may use any number of different communication mechanisms between them, all of wh ich
would be considered an implementation detail of the client instances and out of scope of GNAP.</t> would be considered an implementation detail of the client instances and out of scope of GNAP.</t>
<t>As another example, an AS could likewise be built out of many constit
<t>For another example, an AS could likewise be built out of many constituent uent
components in a distributed architecture. The component that the client instance components in a distributed architecture. The component that the client instance
calls directly could be different from the component that the calls directly could be different from the component that the
RO interacts with to drive consent, since API calls and user interaction RO interacts with to drive consent, since API calls and user interaction
have different security considerations in many environments. Furthermore, have different security considerations in many environments. Furthermore,
the AS could need to collect identity claims about the RO from one system the AS could need to collect identity claims about the RO from one system
that deals with user attributes while generating access tokens at that deals with user attributes while generating access tokens at
another system that deals with security rights. From the perspective of another system that deals with security rights. From the perspective of
GNAP, all of these are pieces of the AS and together fulfill the GNAP, all of these are pieces of the AS and together fulfill the
role of the AS as defined by the protocol. These pieces may have their own inter nal role of the AS as defined by the protocol. These pieces may have their own inter nal
communications mechanisms which are considered out of scope of GNAP.</t> communications mechanisms, which are considered out of scope of GNAP.</t>
</section>
</section> <section anchor="elements">
<section anchor="elements"><name>Elements</name> <name>Elements</name>
<t>In addition to the roles above, the protocol also involves several
<t>In addition to the roles above, the protocol also involves several
elements that are acted upon by the roles throughout the process.</t> elements that are acted upon by the roles throughout the process.</t>
<dl>
<dl> <dt>Access Token:</dt>
<dt>Access Token:</dt> <dd>
<dd> <t>A data artifact representing a set of rights and/or attributes.
<t>a data artifact representing a set of rights and/or attributes.
</t> </t>
<t>Note: An access token can be first issued to a client instance (r
equiring authorization by the RO) and subsequently rotated.</t>
</dd>
<t>Note: an access token can be first issued to a client instance (requiring <dt>Grant:</dt>
authorization by the RO) and subsequently rotated.</t> <dd>
</dd> <t>(verb): To permit an instance of client software to receive some
<dt>Grant:</dt> attributes at a specific time and with a specific duration of validity and/or to
<dd> exercise some set of delegated rights to access a protected resource.</t>
<t>(verb): to permit an instance of client software to receive some attribut </dd>
es at a specific time and valid for a specific duration and/or to exercise some <dt/>
set of delegated rights to access a protected resource;</t> <dd>
</dd> <t>(noun): The act of granting permission to a client instance.</t>
<dt/> </dd>
<dd> <dt>Privilege:</dt>
<t>(noun): the act of granting permission to a client instance.</t> <dd>
</dd> <t>Right or attribute associated with a subject.
<dt>Privilege:</dt>
<dd>
<t>right or attribute associated with a subject.
</t> </t>
<t>Note: The RO defines and maintains the rights and attributes asso
<t>Note: the RO defines and maintains the rights and attributes associated t ciated to the protected resource and might temporarily delegate some set of thos
o the protected resource, and might temporarily delegate some set of those privi e privileges to an end user. This process is referred to as "privilege delegatio
leges to an end user. This process is refered to as privilege delegation.</t> n".</t>
</dd> </dd>
<dt>Protected Resource:</dt> <dt>Protected Resource:</dt>
<dd> <dd>
<t>protected API (Application Programming Interface) served by an RS and tha <t>Protected API that is served by an RS and that can be accessed by
t can be accessed by a client, if and only if a valid and sufficient access toke a client, if and only if a valid and sufficient access token is provided.
n is provided.
</t> </t>
<t>Note: To avoid complex sentences, the specification document may
simply refer to "resource" instead of "protected resource".</t>
</dd>
<dt>Right:</dt>
<dd>
<t>Ability given to a subject to perform a given operation on a reso
urce under the control of an RS.</t>
</dd>
<dt>Subject:</dt>
<dd>
<t>Person or organization. The subject decides whether and under whi
ch conditions its attributes can be disclosed to other parties.</t>
</dd>
<dt>Subject Information:</dt>
<dd>
<t>Set of statements and attributes asserted by an AS about a subjec
t. These statements can be used by the client instance as part of an authenticat
ion decision.</t>
</dd>
</dl>
</section>
<section anchor="trust">
<name>Trust Relationships</name>
<t>Note: to avoid complex sentences, the specification document may simply r <t>GNAP defines its trust objective as follows: the RO trusts the AS to
efer to "resource" instead of "protected resource".</t> ensure access validation and delegation of protected resources to end users, thr
</dd> ough third party clients.</t>
<dt>Right:</dt> <t>This trust objective can be decomposed into trust relationships betwee
<dd> n software elements and roles, especially the pairs end user/RO, end user/client
<t>ability given to a subject to perform a given operation on a resource und , client/AS, RS/RO, AS/RO, and AS/RS. Trust of an agent by its pair can exist if
er the control of an RS.</t> the pair is informed that the agent has made a promise to follow the protocol i
</dd> n the past (e.g., pre-registration and uncompromised cryptographic components) o
<dt>Subject:</dt> r if the pair is able to infer by indirect means that the agent has made such a
<dd> promise (e.g., a compliant client request). Each agent defines its own valuation
<t>person or organization. The subject decides whether and under which condi function of promises given or received. Examples of such valuations can be the
tions its attributes can be disclosed to other parties.</t> benefits from interacting with other agents (e.g., safety in client access and i
</dd> nteroperability with identity standards), the cost of following the protocol (in
<dt>Subject Information:</dt> cluding its security and privacy requirements and recommendations), a ranking of
<dd> promise importance (e.g., a policy decision made by the AS), the assessment of
<t>set of statements and attributes asserted by an AS about a subject. These one's vulnerability or risk of not being able to defend against threats, etc. Th
statements can be used by the client instance as part of an authentication deci ose valuations may depend on the context of the request. For instance, depending
sion.</t> on the specific case in which GNAP is used, the AS may decide to either take in
</dd> to account or discard hints provided by the client, or the RS may refuse bearer
</dl> tokens. Some promises can be affected by previous interactions (e.g., repeated r
equests).</t>
</section>
<section anchor="trust"><name>Trust relationships</name>
<t>GNAP defines its trust objective as: "the RO trusts the AS to ensure access v
alidation and delegation of protected resources to end users, through third part
y clients."</t>
<t>This trust objective can be decomposed into trust relationships between softw
are elements and roles, especially the pairs end user/RO, end user/client, clien
t/AS, RS/RO, AS/RO, AS/RS. Trust of an agent by its pair can exist if the pair i
s informed that the agent has made a promise to follow the protocol in the past
(e.g. pre-registration, uncompromised cryptographic components) or if the pair i
s able to infer by indirect means that the agent has made such a promise (e.g. a
compliant client request). Each agent defines its own valuation function of pro
mises given or received. Examples of such valuations can be the benefits from in
teracting with other agents (e.g. safety in client access, interoperability with
identity standards), the cost of following the protocol (including its security
and privacy requirements and recommendations), a ranking of promise importance
(e.g. a policy decision made by the AS), the assessment of one's vulnerability o
r risk of not being able to defend against threats, etc. Those valuations may de
pend on the context of the request. For instance, the AS may decide to either ta
ke into account or discard hints provided by the client, the RS may refuse beare
r tokens, etc. depending on the specific case in which GNAP is used. Some promis
es can be affected by previous interactions (e.g., repeated requests).</t>
<t>Looking back on each trust relationship:</t>
<t><list style="symbols">
<t>end user/RO: this relationship exists only when the end user and the RO are
different, in which case the end user needs some out of band mechanism of getti
ng the RO consent (see <xref target="authorization"/>). GNAP generally assumes t
hat humans can be authenticated thanks to identity protocols (for instance, thro
ugh an id_token assertion in <xref target="request-subject"/>).</t>
<t>end user/client: the client acts as a user agent. Depending on the technolo
gy used (browser, SPA, mobile application, IoT device, etc.), some interactions
may or may not be possible (as described in <xref target="request-interact-start
"/>). Client developers implement requirements and generally some recommendation
s or best practices, so that the end users may confidently use their software. H
owever, end users might also be facing an attacker's client software or a poorly
-implemented client, without even realizing it.</t>
<t>end user/AS: when the client supports the interaction feature (see <xref ta
rget="response-interact"/>), the end user interacts with the AS through an AS-pr
ovided interface. In many cases, this happens through a front-channel interactio
n through the end user's browser. See <xref target="security-front-channel"/> fo
r some considerations in trusting these interactions.</t>
<t>client/AS: An honest AS may be facing an attacker's client (as discussed ju
st above), or the reverse, and GNAP aims at making common attacks impractical. T
he core specification makes access tokens opaque to the client and defines the r
equest/response scheme in detail, therefore avoiding extra trust hypotheses from
this critical piece of software. Yet the AS may further define cryptographic at
testations or optional rules to simplify the access of clients it already trusts
, due to past behavior or organizational policies (see <xref target="request-cli
ent"/>).</t>
<t>RS/RO: the RS promises it protects its resources on behalf of the RO from u
nauthorized access, and only accepts valid access tokens issued by a trusted AS.
In case tokens are key bound, proper validation of the proof method is expected
from the RS.</t>
<t>AS/RO: the AS is expected to follow the decisions made by the RO, either th
rough interactive consent requests, repeated interactions, or automated rules (a
s described in <xref target="sequence"/>). Privacy considerations aim to reduce
the risk of an honest but too-curious AS, or the consequences of an unexpected u
ser data exposure.</t>
<t>AS/RS: the AS promises to issue valid access tokens to legitimate client re
quests (i.e. after carrying out appropriate due diligence, as defined in the GNA
P protocol). Some optional configurations are covered by <xref target="I-D.ietf-
gnap-resource-servers"/>.</t>
</list></t>
<t>A global assumption made by GNAP is that authorization requests are security
and privacy sensitive, and appropriate measures are respectively detailed in <xr
ef target="security"/> and <xref target="privacy"/>.</t>
<t>A formal trust model is out of scope of this specification, but one could be
developed using techniques such as <xref target="promise-theory"/>.</t>
</section> <t>Below are details of each trust relationship:</t>
<section anchor="protocol"><name>Protocol Flow</name>
<t>GNAP is fundamentally designed to allow delegated access to APIs and other in <dl spacing="normal">
formation, such as subject information, using a multi-stage, stateful process. T <dt>end user/RO:</dt><dd>This relationship exists only when the end us
his process allows different parties to provide information into the system to a er and the RO are different, in which case the end user needs some out-of-band m
lter and augment the state of the delegated access and its artifacts.</t> echanism of getting the RO consent (see <xref target="authorization"/>). GNAP ge
nerally assumes that humans can be authenticated, thanks to identity protocols (
for instance, through an id_token assertion as described in <xref target="reques
t-subject"/>).</dd>
<dt>end user/client:</dt><dd>The client acts as a user agent. Dependin
g on the technology used (browser, single-page application (SPA), mobile applica
tion, Internet of Things (IoT) device, etc.), some interactions may or may not b
e possible (as described in <xref target="request-interact-start"/>). Client dev
elopers implement requirements and generally some recommendations or best practi
ces, so that the end users may confidently use their software. However, end user
s might also face an attacker's client software or a poorly implemented client w
ithout even realizing it.</dd>
<dt>end user/AS:</dt><dd>When the client supports the interaction feat
ure (see <xref target="response-interact"/>), the end user interacts with the AS
through an AS-provided interface. In many cases, this happens through a front-c
hannel interaction through the end user's browser. See <xref target="security-fr
ont-channel"/> for some considerations in trusting these interactions.</dd>
<dt>client/AS:</dt><dd>An honest AS may face an attacker's client (as
discussed just above), or the reverse, and GNAP aims to make common attacks impr
actical. This specification makes access tokens opaque to the client and defines
the request/response scheme in detail, therefore avoiding extra trust hypothese
s from this critical piece of software. Yet, the AS may further define cryptogra
phic attestations or optional rules to simplify the access of clients it already
trusts, due to past behavior or organizational policies (see <xref target="requ
est-client"/>).</dd>
<dt>RS/RO:</dt><dd>On behalf of the RO, the RS promises to protect its
resources from unauthorized access and only accepts valid access tokens issued b
y a trusted AS. In case tokens are key bound, proper validation of the proofing
method is expected from the RS.</dd>
<dt>AS/RO:</dt><dd>The AS is expected to follow the decisions made by
the RO, through either interactive consent requests, repeated interactions, or a
utomated rules (as described in <xref target="sequence"/>). Privacy consideratio
ns aim to reduce the risk of an honest but too-curious AS or the consequences of
an unexpected user data exposure.</dd>
<dt>AS/RS:</dt><dd>The AS promises to issue valid access tokens to leg
itimate client requests (i.e., after carrying out appropriate due diligence, as
defined in the GNAP). Some optional configurations are covered by <xref target="
I-D.ietf-gnap-resource-servers"/>.</dd>
</dl>
<t>The underlying requested grant moves through several states as different acti ons take place during the protocol:</t> <t>A global assumption made by GNAP is that authorization requests are s ecurity and privacy sensitive, and appropriate measures are detailed in Sections <xref target="security" format="counter"/> and <xref target="privacy" format="c ounter" />, respectively.</t>
<figure title="Figure 2: State diagram of a grant request throughout GNAP"><arts <t>A formal trust model is out of scope of this specification, but one c
et><artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" he ould be developed using techniques such as the Promise Theory <xref target="prom
ight="432" width="584" viewBox="0 0 584 432" class="diagram" text-anchor="middle ise-theory"/>.</t>
" font-family="monospace" font-size="13px" stroke-linecap="round"> </section>
<path d="M 112,192 L 112,256" fill="none" stroke="black"/> <section anchor="protocol">
<path d="M 216,192 L 216,256" fill="none" stroke="black"/> <name>Protocol Flow</name>
<path d="M 378,192 L 378,256" fill="none" stroke="black"/><path d="M 374,192 L 3 <t>GNAP is fundamentally designed to allow delegated access to APIs and
74,256" fill="none" stroke="black"/> other information, such as subject information, using a multi-stage, stateful pr
<path d="M 376,320 L 376,384" fill="none" stroke="black"/> ocess. This process allows different parties to provide information into the sys
<path d="M 384,64 L 384,128" fill="none" stroke="black"/> tem to alter and augment the state of the delegated access and its artifacts.</t
<path d="M 424,128 L 424,176" fill="none" stroke="black"/> >
<path d="M 424,272 L 424,320" fill="none" stroke="black"/> <t>The underlying requested grant moves through several states as differ
<path d="M 440,48 L 440,64" fill="none" stroke="black"/> ent actions take place during the protocol, as shown in <xref target="state-diag
<path d="M 440,384 L 440,400" fill="none" stroke="black"/> ram"/>.</t>
<path d="M 464,64 L 464,128" fill="none" stroke="black"/> <figure anchor="state-diagram">
<path d="M 464,320 L 464,384" fill="none" stroke="black"/> <name>State Diagram of a Grant Request in GNAP</name>
<path d="M 474,192 L 474,256" fill="none" stroke="black"/><path d="M 470,192 L 4 <artset>
70,256" fill="none" stroke="black"/> <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" version=
<path d="M 504,48 L 504,80" fill="none" stroke="black"/> "1.1" height="432" width="584" viewBox="0 0 584 432" class="diagram" text-anchor
<path d="M 504,368 L 504,400" fill="none" stroke="black"/> ="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 456,32 L 488,32" fill="none" stroke="black"/> <path d="M 112,192 L 112,256" fill="none" stroke="black"/>
<path d="M 384,64 L 464,64" fill="none" stroke="black"/> <path d="M 216,192 L 216,256" fill="none" stroke="black"/>
<path d="M 184,80 L 208,80" fill="none" stroke="black"/> <path d="M 378,192 L 378,256" fill="none" stroke="black"/>
<path d="M 344,80 L 376,80" fill="none" stroke="black"/> <path d="M 374,192 L 374,256" fill="none" stroke="black"/>
<path d="M 472,96 L 488,96" fill="none" stroke="black"/> <path d="M 376,320 L 376,384" fill="none" stroke="black"/>
<path d="M 200,112 L 216,112" fill="none" stroke="black"/> <path d="M 384,64 L 384,128" fill="none" stroke="black"/>
<path d="M 368,112 L 384,112" fill="none" stroke="black"/> <path d="M 424,128 L 424,176" fill="none" stroke="black"/>
<path d="M 384,128 L 464,128" fill="none" stroke="black"/> <path d="M 424,272 L 424,320" fill="none" stroke="black"/>
<path d="M 112,192 L 216,192" fill="none" stroke="black"/> <path d="M 440,48 L 440,64" fill="none" stroke="black"/>
<path d="M 376,190 L 472,190" fill="none" stroke="black"/><path d="M 376,194 L 4 <path d="M 440,384 L 440,400" fill="none" stroke="black"/>
72,194" fill="none" stroke="black"/> <path d="M 464,64 L 464,128" fill="none" stroke="black"/>
<path d="M 8,224 L 24,224" fill="none" stroke="black"/> <path d="M 464,320 L 464,384" fill="none" stroke="black"/>
<path d="M 88,224 L 104,224" fill="none" stroke="black"/> <path d="M 474,192 L 474,256" fill="none" stroke="black"/>
<path d="M 216,224 L 264,224" fill="none" stroke="black"/> <path d="M 470,192 L 470,256" fill="none" stroke="black"/>
<path d="M 336,224 L 368,224" fill="none" stroke="black"/> <path d="M 504,48 L 504,80" fill="none" stroke="black"/>
<path d="M 112,256 L 216,256" fill="none" stroke="black"/> <path d="M 504,368 L 504,400" fill="none" stroke="black"/>
<path d="M 376,254 L 472,254" fill="none" stroke="black"/><path d="M 376,258 L 4 <path d="M 456,32 L 488,32" fill="none" stroke="black"/>
72,258" fill="none" stroke="black"/> <path d="M 384,64 L 464,64" fill="none" stroke="black"/>
<path d="M 376,320 L 464,320" fill="none" stroke="black"/> <path d="M 184,80 L 208,80" fill="none" stroke="black"/>
<path d="M 208,336 L 248,336" fill="none" stroke="black"/> <path d="M 344,80 L 376,80" fill="none" stroke="black"/>
<path d="M 304,336 L 376,336" fill="none" stroke="black"/> <path d="M 472,96 L 488,96" fill="none" stroke="black"/>
<path d="M 472,352 L 488,352" fill="none" stroke="black"/> <path d="M 200,112 L 216,112" fill="none" stroke="black"/>
<path d="M 184,368 L 224,368" fill="none" stroke="black"/> <path d="M 368,112 L 384,112" fill="none" stroke="black"/>
<path d="M 344,368 L 368,368" fill="none" stroke="black"/> <path d="M 384,128 L 464,128" fill="none" stroke="black"/>
<path d="M 376,384 L 464,384" fill="none" stroke="black"/> <path d="M 112,192 L 216,192" fill="none" stroke="black"/>
<path d="M 456,416 L 488,416" fill="none" stroke="black"/> <path d="M 376,190 L 472,190" fill="none" stroke="black"/>
<path d="M 128,256 L 184,368" fill="none" stroke="black"/> <path d="M 376,194 L 472,194" fill="none" stroke="black"/>
<path d="M 172,264 L 208,336" fill="none" stroke="black"/> <path d="M 8,224 L 24,224" fill="none" stroke="black"/>
<path d="M 128,192 L 184,80" fill="none" stroke="black"/> <path d="M 88,224 L 104,224" fill="none" stroke="black"/>
<path d="M 164,184 L 200,112" fill="none" stroke="black"/> <path d="M 216,224 L 264,224" fill="none" stroke="black"/>
<path d="M 456,32 C 447.16936,32 440,39.16936 440,48" fill="none" stroke="black" <path d="M 336,224 L 368,224" fill="none" stroke="black"/>
/> <path d="M 112,256 L 216,256" fill="none" stroke="black"/>
<path d="M 488,32 C 496.83064,32 504,39.16936 504,48" fill="none" stroke="black" <path d="M 376,254 L 472,254" fill="none" stroke="black"/>
/> <path d="M 376,258 L 472,258" fill="none" stroke="black"/>
<path d="M 488,96 C 496.83064,96 504,88.83064 504,80" fill="none" stroke="black" <path d="M 376,320 L 464,320" fill="none" stroke="black"/>
/> <path d="M 208,336 L 248,336" fill="none" stroke="black"/>
<path d="M 488,352 C 496.83064,352 504,359.16936 504,368" fill="none" stroke="bl <path d="M 304,336 L 376,336" fill="none" stroke="black"/>
ack"/> <path d="M 472,352 L 488,352" fill="none" stroke="black"/>
<path d="M 456,416 C 447.16936,416 440,408.83064 440,400" fill="none" stroke="bl <path d="M 184,368 L 224,368" fill="none" stroke="black"/>
ack"/> <path d="M 344,368 L 368,368" fill="none" stroke="black"/>
<path d="M 488,416 C 496.83064,416 504,408.83064 504,400" fill="none" stroke="bl <path d="M 376,384 L 464,384" fill="none" stroke="black"/>
ack"/> <path d="M 456,416 L 488,416" fill="none" stroke="black"/>
<polygon class="arrowhead" points="480,352 468,346.4 468,357.6" fill="black" tra <path d="M 128,256 L 184,368" fill="none" stroke="black"/>
nsform="rotate(180,472,352)"/> <path d="M 172,264 L 208,336" fill="none" stroke="black"/>
<polygon class="arrowhead" points="480,96 468,90.4 468,101.6" fill="black" trans <path d="M 128,192 L 184,80" fill="none" stroke="black"/>
form="rotate(180,472,96)"/> <path d="M 164,184 L 200,112" fill="none" stroke="black"/>
<polygon class="arrowhead" points="432,272 420,266.4 420,277.6" fill="black" tra <path d="M 456,32 C 447.16936,32 440,39.16936 440,48" fill="none
nsform="rotate(270,424,272)"/> " stroke="black"/>
<polygon class="arrowhead" points="432,176 420,170.4 420,181.6" fill="black" tra <path d="M 488,32 C 496.83064,32 504,39.16936 504,48" fill="none
nsform="rotate(90,424,176)"/> " stroke="black"/>
<polygon class="arrowhead" points="384,80 372,74.4 372,85.6" fill="black" transf <path d="M 488,96 C 496.83064,96 504,88.83064 504,80" fill="none
orm="rotate(0,376,80)"/> " stroke="black"/>
<polygon class="arrowhead" points="376,368 364,362.4 364,373.6" fill="black" tra <path d="M 488,352 C 496.83064,352 504,359.16936 504,368" fill="
nsform="rotate(0,368,368)"/> none" stroke="black"/>
<polygon class="arrowhead" points="376,224 364,218.4 364,229.6" fill="black" tra <path d="M 456,416 C 447.16936,416 440,408.83064 440,400" fill="
nsform="rotate(0,368,224)"/> none" stroke="black"/>
<polygon class="arrowhead" points="180,264 168,258.4 168,269.6" fill="black" tra <path d="M 488,416 C 496.83064,416 504,408.83064 504,400" fill="
nsform="rotate(243.43494882292202,172,264)"/> none" stroke="black"/>
<polygon class="arrowhead" points="172,184 160,178.4 160,189.6" fill="black" tra <polygon class="arrowhead" points="480,352 468,346.4 468,357.6"
nsform="rotate(116.56505117707799,164,184)"/> fill="black" transform="rotate(180,472,352)"/>
<polygon class="arrowhead" points="112,224 100,218.4 100,229.6" fill="black" tra <polygon class="arrowhead" points="480,96 468,90.4 468,101.6" fi
nsform="rotate(0,104,224)"/> ll="black" transform="rotate(180,472,96)"/>
<g class="text"> <polygon class="arrowhead" points="432,272 420,266.4 420,277.6"
<text x="548" y="68">Continue</text> fill="black" transform="rotate(270,424,272)"/>
<text x="228" y="84">Need</text> <polygon class="arrowhead" points="432,176 420,170.4 420,181.6"
<text x="296" y="84">Interaction</text> fill="black" transform="rotate(90,424,176)"/>
<text x="424" y="100">Pending</text> <polygon class="arrowhead" points="384,80 372,74.4 372,85.6" fil
<text x="244" y="116">Finish</text> l="black" transform="rotate(0,376,80)"/>
<text x="320" y="116">Interaction</text> <polygon class="arrowhead" points="376,368 364,362.4 364,373.6"
<text x="292" y="132">(approve/deny)</text> fill="black" transform="rotate(0,368,368)"/>
<text x="460" y="164">Cancel</text> <polygon class="arrowhead" points="376,224 364,218.4 364,229.6"
<text x="56" y="228">Request</text> fill="black" transform="rotate(0,368,224)"/>
<text x="164" y="228">Processing</text> <polygon class="arrowhead" points="180,264 168,258.4 168,269.6"
<text x="300" y="228">Finalize</text> fill="black" transform="rotate(243.43494882292202,172,264)"/>
<text x="424" y="228">Finalized</text> <polygon class="arrowhead" points="172,184 160,178.4 160,189.6"
<text x="460" y="292">Revoke</text> fill="black" transform="rotate(116.56505117707799,164,184)"/>
<text x="500" y="292">or</text> <polygon class="arrowhead" points="112,224 100,218.4 100,229.6"
<text x="468" y="308">Finalize</text> fill="black" transform="rotate(0,104,224)"/>
<text x="276" y="340">Update</text> <g class="text">
<text x="420" y="356">Approved</text> <text x="548" y="68">Continue</text>
<text x="236" y="372">No</text> <text x="228" y="84">Need</text>
<text x="296" y="372">Interaction</text> <text x="296" y="84">Interaction</text>
<text x="548" y="388">Continue</text> <text x="424" y="100">Pending</text>
</g> <text x="244" y="116">Finish</text>
</svg> <text x="320" y="116">Interaction</text>
</artwork><artwork type="ascii-art"><![CDATA[ <text x="292" y="132">(approve/deny)</text>
<text x="460" y="164">Cancel</text>
<text x="56" y="228">Request</text>
<text x="164" y="228">Processing</text>
<text x="300" y="228">Finalize</text>
<text x="424" y="228">Finalized</text>
<text x="460" y="292">Revoke</text>
<text x="500" y="292">or</text>
<text x="468" y="308">Finalize</text>
<text x="276" y="340">Update</text>
<text x="420" y="356">Approved</text>
<text x="236" y="372">No</text>
<text x="296" y="372">Interaction</text>
<text x="548" y="388">Continue</text>
</g>
</svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
.-----. .-----.
| | | |
+------+--+ | Continue +------+--+ | Continue
.---Need Interaction---->| | | .---Need Interaction---->| | |
/ | Pending |<--` / | Pending |<--`
/ .--Finish Interaction--+ | / .--Finish Interaction--+ |
/ / (approve/deny) +----+----+ / / (approve/deny) +----+----+
/ / | / / |
/ / | Cancel / / | Cancel
/ v v / v v
skipping to change at line 509 skipping to change at line 485
\ ^ ^ \ ^ ^
\ \ | Revoke or \ \ | Revoke or
\ \ | Finalize \ \ | Finalize
\ \ +-----+----+ \ \ +-----+----+
\ `-----Update---------+ | \ `-----Update---------+ |
\ | Approved |<--. \ | Approved |<--.
`-----No Interaction--->| | | `-----No Interaction--->| | |
+-------+--+ | Continue +-------+--+ | Continue
| | | |
`-----` `-----`
]]></artwork></artset></figure> ]]></artwork>
</artset>
<t>The state of the grant request is defined and managed by the AS, though the c </figure>
lient instance also needs to manage its view of the grant request over time. The <t>The state of the grant request is defined and managed by the AS, thou
means by which these roles manage their state is outside the scope of this spec gh the client instance also needs to manage its view of the grant request over t
ification.</t> ime. The means by which these roles manage their state are outside the scope of
this specification.</t>
<dl> <dl>
<dt><em>Processing</em>:</dt> <dt><em>Processing</em>:</dt>
<dd> <dd>When a request for access (<xref target="request"> </xref>) is rec
<t>When a <xref target="request">request for access</xref> is received by th eived by the AS, a new grant request is created and placed in the <em>processing
e AS, a new grant request is created and placed in the <em>processing</em> state </em> state by the AS. This state is also entered when an existing grant request
by the AS. This state is also entered when an existing grant request is updated is updated by the client instance and when interaction is completed. In this st
by the client instance and when interaction is completed. In this state, the AS ate, the AS processes the context of the grant request to determine whether inte
processes the context of the grant request to determine whether interaction wit raction with the end user or RO is required for approval of the request. The gra
h the end user or RO is required for approval of the request. The grant request nt request has to exit this state before a response can be returned to the clien
has to exit this state before a response can be returned to the client instance. t instance. If approval is required, the request moves to the <em>pending</em> s
If approval is required, the request moves to the <em>pending</em> state and th tate, and the AS returns a continuation response (<xref target="response-continu
e AS returns a <xref target="response-continue">continue response</xref> along w e"> </xref>) along with any appropriate interaction responses (<xref target="res
ith any appropriate <xref target="response-interact">interaction responses</xref ponse-interact"> </xref>). If no such approval is required, such as when the cli
>. If no such approval is required, such as when the client instance is acting o ent instance is acting on its own behalf or the AS can determine that access has
n its own behalf or the AS can determine that access has been fulfilled, the req been fulfilled, the request moves to the <em>approved</em> state where access t
uest moves to the <em>approved</em> state where <xref target="response-token">ac okens for API access (<xref target="response-token"> </xref>) and subject inform
cess tokens for API access</xref> and <xref target="response-subject">subject in ation (<xref target="response-subject"> </xref>) can be issued to the client ins
formation</xref> can be issued to the client instance. If the AS determines that tance. If the AS determines that no additional processing can occur (such as a t
no additional processing can occur (such as a timeout or an unrecoverable error imeout or an unrecoverable error), the grant request is moved to the <em>finaliz
), the grant request is moved to the <em>finalized</em> state and is terminated. ed</em> state and is terminated.</dd>
</t> <dt><em>Pending</em>:</dt>
</dd> <dd>When a request needs to be approved by an RO, or interaction with
<dt><em>Pending</em>:</dt> the end user is required, the grant request enters a state of <em>pending</em>.
<dd> In this state, no access tokens can be granted, and no subject information can b
<t>When a request needs to be approved by a RO, or interaction with the end e released to the client instance. While a grant request is in this state, the A
user is required, the grant request enters a state of <em>pending</em>. In this S seeks to gather the required consent and authorization (<xref target="authoriz
state, no access tokens can be granted and no subject information can be release ation"> </xref>) for the requested access. A grant request in this state is alwa
d to the client instance. While a grant request is in this state, the AS seeks t ys associated with a continuation access token bound to the client instance's ke
o gather the required <xref target="authorization">consent and authorization</xr y (see <xref target="response-continue"/> for details of the continuation access
ef> for the requested access. A grant request in this state is always associated token). If no interaction finish method (<xref target="request-interact-finish"
with a <em>continuation access token</em> bound to the client instance's key (s > </xref>) is associated with this request, the client instance can send a polli
ee <xref target="response-continue"/> for details of the continuation access tok ng continuation request (<xref target="continue-poll"> </xref>) to the AS. This
en). If no <xref target="request-interact-finish">interaction finish method</xre returns a continuation response (<xref target="response-continue"> </xref>) whil
f> is associated with this request, the client instance can send a <xref target= e the grant request remains in this state, allowing the client instance to conti
"continue-poll">polling continue request</xref> to the AS. This returns a <xref nue to check the state of the pending grant request. If an interaction finish me
target="response-continue">continue response</xref> while the grant request rema thod (<xref target="request-interact-finish"> </xref>) is specified in the grant
ins in this state, allowing the client instance to continue to check the state o request, the client instance can continue the request after interaction (<xref
f the pending grant request. If an <xref target="request-interact-finish">intera target="continue-after-interaction"> </xref>) to the AS to move this request to
ction finish method</xref> is specified in the grant request, the client instanc the <em>processing</em> state to be re-evaluated by the AS. Note that this occur
e can <xref target="continue-after-interaction">continue the request after inter s whether the grant request has been approved or denied by the RO, since the AS
action</xref> to the AS to move this request to the <em>processing</em> state to needs to take into account the full context of the request before determining th
be re-evaluated by the AS. Note that this occurs whether the grant request has e next step for the grant request. When other information is made available in t
been approved or denied by the RO, since the AS needs to take into account the f he context of the grant request, such as through the asynchronous actions of the
ull context of the request before determining the next step for the grant reques RO, the AS moves this request to the <em>processing</em> state to be re-evaluat
t. When other information is made available in the context of the grant request, ed. If the AS determines that no additional interaction can occur, e.g., all the
such as through the asynchronous actions of the RO, the AS moves this request t interaction methods have timed out or a revocation request (<xref target="conti
o the <em>processing</em> state to be re-evaluated. If the AS determines that no nue-delete"> </xref>) is received from the client instance, the grant request ca
additional interaction can occur, such as all the interaction methods have time n be moved to the <em>finalized</em> state.</dd>
d out or a <xref target="continue-delete">revocation request</xref> is received <dt><em>Approved</em>:</dt>
from the client instance, the grant request can be moved to the <em>finalized</e <dd>When a request has been approved by an RO and no further interacti
m> state.</t> on with the end user is required, the grant request enters a state of <em>approv
</dd> ed</em>. In this state, responses to the client instance can include access toke
<dt><em>Approved</em>:</dt> ns for API access (<xref target="response-token"> </xref>) and subject informati
<dd> on (<xref target="response-subject"> </xref>). If continuation and updates are a
<t>When a request has been approved by an RO and no further interaction with llowed for this grant request, the AS can include the continuation response (<xr
the end user is required, the grant request enters a state of <em>approved</em> ef target="response-continue"> </xref>). In this state, post-interaction continu
. In this state, responses to the client instance can include <xref target="resp ation requests (<xref target="continue-after-interaction"> </xref>) are not allo
onse-token">access tokens for API access</xref> and <xref target="response-subje wed and will result in an error, since all interaction is assumed to have been c
ct">subject information</xref>. If continuation and updates are allowed for this ompleted. If the client instance sends a polling continuation request (<xref tar
grant request, the AS can include the <xref target="response-continue">continua get="continue-poll"> </xref>) while the request is in this state, new access tok
tion response</xref>. In this state, <xref target="continue-after-interaction">p ens (<xref target="response-token"> </xref>) can be issued in the response. Note
ost-interaction continuation requests</xref> are not allowed and will result in that this always creates a new access token, but any existing access tokens cou
an error, since all interaction is assumed to have been completed. If the client ld be rotated and revoked using the token management API (<xref target="token-ma
instance sends a <xref target="continue-poll">polling continue request</xref> w nagement"> </xref>). The client instance can send an update continuation request
hile the request is in this state, <xref target="response-token">new access toke (<xref target="continue-modify"> </xref>) to modify the requested access, causi
ns</xref> can be issued in the response. Note that this always creates a new acc ng the AS to move the request back to the <em>processing</em> state for re-evalu
ess token, but any existing access tokens could be rotated and revoked using the ation. If the AS determines that no additional tokens can be issued and that no
<xref target="token-management">token management API</xref>. The client instanc additional updates are to be accepted (e.g., the continuation access tokens have
e can send an <xref target="continue-modify">update continuation request</xref> expired), the grant is moved to the <em>finalized</em> state.</dd>
to modify the requested access, causing the AS to move the request back to the < <dt><em>Finalized</em>:</dt>
em>processing</em> state for re-evaluation. If the AS determines that no additio <dd>After the access tokens are issued, if the AS does not allow any a
nal tokens can be issued, and that no additional updates are to be accepted (suc dditional updates on the grant request, the grant request enters the <em>finaliz
h as the continuation access tokens have expired), the grant is moved to the <em ed</em> state. This state is also entered when an existing grant request is revo
>finalized</em> state.</t> ked by the client instance (<xref target="continue-delete"> </xref>) or otherwis
</dd> e revoked by the AS (such as through out-of-band action by the RO). This state c
<dt><em>Finalized</em>:</dt> an also be entered if the AS determines that no additional processing is possibl
<dd> e, for example, if the RO has denied the requested access or if interaction is r
<t>After the access tokens are issued, if the AS does not allow any addition equired but no compatible interaction methods are available. Once in this state,
al updates on the grant request, the grant request enters the <em>finalized</em> no new access tokens can be issued, no subject information can be returned, and
state. This state is also entered when an existing grant request is <xref targe no interactions can take place. Once in this state, the grant request is dead a
t="continue-delete">revoked by the client instance</xref> or otherwise revoked b nd cannot be revived. If future access is desired by the client instance, a new
y the AS (such as through out-of-band action by the RO). This state can also be grant request can be created, unrelated to this grant request.</dd>
entered if the AS determines that no additional processing is possible, for exam </dl>
ple if the RO has denied the requested access or if interaction is required but
no compatible interaction methods are available. Once in this state, no new acce
ss tokens can be issued, no subject information can be returned, and no interact
ions can take place. Once in this state, the grant request is dead and cannot be
revived. If future access is desired by the client instance, a new grant reques
t can be created, unrelated to this grant request.</t>
</dd>
</dl>
<t>While it is possible to deploy an AS in a stateless environment, GNAP is a st
ateful protocol and such deployments will need a way to manage the current state
of the grant request in a secure and deterministic fashion without relying on o
ther components, such as the client software, to keep track of the current state
.</t>
</section>
<section anchor="sequence"><name>Sequences</name>
<t>GNAP can be used in a variety of ways to allow the core <t>While it is possible to deploy an AS in a stateless environment, GNAP
is a stateful protocol, and such deployments will need a way to manage the curr
ent state of the grant request in a secure and deterministic fashion without rel
ying on other components, such as the client software, to keep track of the curr
ent state.</t>
</section>
<section anchor="sequence">
<name>Sequences</name>
<t>GNAP can be used in a variety of ways to allow the core
delegation process to take place. Many portions of this process are delegation process to take place. Many portions of this process are
conditionally present depending on the context of the deployments, conditionally present depending on the context of the deployments,
and not every step in this overview will happen in all circumstances.</t> and not every step in this overview will happen in all circumstances.</t>
<t>Note that a connection between roles in this process does not necessa
<t>Note that a connection between roles in this process does not necessarily rily
indicate that a specific protocol message is sent across the wire indicate that a specific protocol message is sent across the wire
between the components fulfilling the roles in question, or that a between the components fulfilling the roles in question or that a
particular step is required every time. For example, for a client instance inter ested particular step is required every time. For example, for a client instance inter ested
in only getting subject information directly, and not calling an RS, in only getting subject information directly and not calling an RS,
all steps involving the RS below do not apply.</t> all steps involving the RS below do not apply.</t>
<t>In some circumstances,
<t>In some circumstances,
the information needed at a given stage is communicated out of band the information needed at a given stage is communicated out of band
or is preconfigured between the components or entities performing or is pre-configured between the components or entities performing
the roles. For example, one entity can fulfill multiple roles, and so the roles. For example, one entity can fulfill multiple roles, so
explicit communication between the roles is not necessary within the explicit communication between the roles is not necessary within the
protocol flow. Additionally some components may not be involved protocol flow. Additionally, some components may not be involved
in all use cases. For example, a client instance could be calling the in all use cases. For example, a client instance could be calling the
AS just to get direct user information and have no need to get AS just to get direct user information and have no need to get
an access token to call an RS.</t> an access token to call an RS.</t>
<section anchor="sequence-overall">
<section anchor="sequence-overall"><name>Overall Protocol Sequence</name> <name>Overall Protocol Sequence</name>
<t>The following diagram provides a general overview of GNAP, includin
<t>The following diagram provides a general overview of GNAP, including many g many
different optional phases and connections. The diagrams in the following section s different optional phases and connections. The diagrams in the following section s
provide views of GNAP under more specific circumstances. These additional diagra ms provide views of GNAP under more specific circumstances. These additional diagra ms
use the same conventions as the overall diagram below.</t> use the same conventions as the overall diagram below.</t>
<figure title="Figure 3: Overall sequence of GNAP"><artset><artwork type="svg"> <figure>
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" height="624" width="456" v <name>Overall Sequence of GNAP</name>
iewBox="0 0 456 624" class="diagram" text-anchor="middle" font-family="monospace <artset>
" font-size="13px" stroke-linecap="round"> <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" versio
<path d="M 8,48 L 8,64" fill="none" stroke="black"/> n="1.1" height="624" width="456" viewBox="0 0 456 624" class="diagram" text-anch
<path d="M 8,176 L 8,512" fill="none" stroke="black"/> or="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 58,80 L 58,112" fill="none" stroke="black"/><path d="M 54,80 L 54,112 <path d="M 8,48 L 8,64" fill="none" stroke="black"/>
" fill="none" stroke="black"/> <path d="M 8,176 L 8,512" fill="none" stroke="black"/>
<path d="M 58,144 L 58,176" fill="none" stroke="black"/><path d="M 54,144 L 54,1 <path d="M 58,80 L 58,112" fill="none" stroke="black"/>
76" fill="none" stroke="black"/> <path d="M 54,80 L 54,112" fill="none" stroke="black"/>
<path d="M 80,176 L 80,512" fill="none" stroke="black"/> <path d="M 58,144 L 58,176" fill="none" stroke="black"/>
<path d="M 112,48 L 112,64" fill="none" stroke="black"/> <path d="M 54,144 L 54,176" fill="none" stroke="black"/>
<path d="M 152,224 L 152,328" fill="none" stroke="black"/> <path d="M 80,176 L 80,512" fill="none" stroke="black"/>
<path d="M 152,376 L 152,440" fill="none" stroke="black"/> <path d="M 112,48 L 112,64" fill="none" stroke="black"/>
<path d="M 152,456 L 152,512" fill="none" stroke="black"/> <path d="M 152,224 L 152,328" fill="none" stroke="black"/>
<path d="M 192,48 L 192,64" fill="none" stroke="black"/> <path d="M 152,376 L 152,440" fill="none" stroke="black"/>
<path d="M 250,80 L 250,112" fill="none" stroke="black"/><path d="M 246,80 L 246 <path d="M 152,456 L 152,512" fill="none" stroke="black"/>
,112" fill="none" stroke="black"/> <path d="M 192,48 L 192,64" fill="none" stroke="black"/>
<path d="M 250,144 L 250,224" fill="none" stroke="black"/><path d="M 246,144 L 2 <path d="M 250,80 L 250,112" fill="none" stroke="black"/>
46,224" fill="none" stroke="black"/> <path d="M 246,80 L 246,112" fill="none" stroke="black"/>
<path d="M 280,224 L 280,328" fill="none" stroke="black"/> <path d="M 250,144 L 250,224" fill="none" stroke="black"/>
<path d="M 280,376 L 280,440" fill="none" stroke="black"/> <path d="M 246,144 L 246,224" fill="none" stroke="black"/>
<path d="M 280,456 L 280,512" fill="none" stroke="black"/> <path d="M 280,224 L 280,328" fill="none" stroke="black"/>
<path d="M 296,48 L 296,64" fill="none" stroke="black"/> <path d="M 280,376 L 280,440" fill="none" stroke="black"/>
<path d="M 344,176 L 344,512" fill="none" stroke="black"/> <path d="M 280,456 L 280,512" fill="none" stroke="black"/>
<path d="M 448,176 L 448,512" fill="none" stroke="black"/> <path d="M 296,48 L 296,64" fill="none" stroke="black"/>
<path d="M 24,32 L 96,32" fill="none" stroke="black"/> <path d="M 344,176 L 344,512" fill="none" stroke="black"/>
<path d="M 208,32 L 280,32" fill="none" stroke="black"/> <path d="M 448,176 L 448,512" fill="none" stroke="black"/>
<path d="M 24,80 L 96,80" fill="none" stroke="black"/> <path d="M 24,32 L 96,32" fill="none" stroke="black"/>
<path d="M 208,80 L 280,80" fill="none" stroke="black"/> <path d="M 208,32 L 280,32" fill="none" stroke="black"/>
<path d="M 8,176 L 80,176" fill="none" stroke="black"/> <path d="M 24,80 L 96,80" fill="none" stroke="black"/>
<path d="M 344,176 L 448,176" fill="none" stroke="black"/> <path d="M 208,80 L 280,80" fill="none" stroke="black"/>
<path d="M 152,224 L 280,224" fill="none" stroke="black"/> <path d="M 8,176 L 80,176" fill="none" stroke="black"/>
<path d="M 80,240 L 104,240" fill="none" stroke="black"/> <path d="M 344,176 L 448,176" fill="none" stroke="black"/>
<path d="M 120,240 L 144,240" fill="none" stroke="black"/> <path d="M 152,224 L 280,224" fill="none" stroke="black"/>
<path d="M 88,256 L 104,256" fill="none" stroke="black"/> <path d="M 80,240 L 104,240" fill="none" stroke="black"/>
<path d="M 120,256 L 152,256" fill="none" stroke="black"/> <path d="M 120,240 L 144,240" fill="none" stroke="black"/>
<path d="M 80,288 L 104,288" fill="none" stroke="black"/> <path d="M 88,256 L 104,256" fill="none" stroke="black"/>
<path d="M 120,288 L 144,288" fill="none" stroke="black"/> <path d="M 120,256 L 152,256" fill="none" stroke="black"/>
<path d="M 88,304 L 104,304" fill="none" stroke="black"/> <path d="M 80,288 L 104,288" fill="none" stroke="black"/>
<path d="M 120,304 L 152,304" fill="none" stroke="black"/> <path d="M 120,288 L 144,288" fill="none" stroke="black"/>
<path d="M 80,336 L 208,336" fill="none" stroke="black"/> <path d="M 88,304 L 104,304" fill="none" stroke="black"/>
<path d="M 224,336 L 336,336" fill="none" stroke="black"/> <path d="M 120,304 L 152,304" fill="none" stroke="black"/>
<path d="M 88,368 L 208,368" fill="none" stroke="black"/> <path d="M 80,336 L 208,336" fill="none" stroke="black"/>
<path d="M 224,368 L 336,368" fill="none" stroke="black"/> <path d="M 224,336 L 336,336" fill="none" stroke="black"/>
<path d="M 80,400 L 104,400" fill="none" stroke="black"/> <path d="M 88,368 L 208,368" fill="none" stroke="black"/>
<path d="M 120,400 L 144,400" fill="none" stroke="black"/> <path d="M 224,368 L 336,368" fill="none" stroke="black"/>
<path d="M 88,416 L 104,416" fill="none" stroke="black"/> <path d="M 80,400 L 104,400" fill="none" stroke="black"/>
<path d="M 128,416 L 152,416" fill="none" stroke="black"/> <path d="M 120,400 L 144,400" fill="none" stroke="black"/>
<path d="M 80,448 L 208,448" fill="none" stroke="black"/> <path d="M 88,416 L 104,416" fill="none" stroke="black"/>
<path d="M 232,448 L 336,448" fill="none" stroke="black"/> <path d="M 128,416 L 152,416" fill="none" stroke="black"/>
<path d="M 80,480 L 104,480" fill="none" stroke="black"/> <path d="M 80,448 L 208,448" fill="none" stroke="black"/>
<path d="M 128,480 L 144,480" fill="none" stroke="black"/> <path d="M 232,448 L 336,448" fill="none" stroke="black"/>
<path d="M 8,512 L 80,512" fill="none" stroke="black"/> <path d="M 80,480 L 104,480" fill="none" stroke="black"/>
<path d="M 152,512 L 280,512" fill="none" stroke="black"/> <path d="M 128,480 L 144,480" fill="none" stroke="black"/>
<path d="M 344,512 L 448,512" fill="none" stroke="black"/> <path d="M 8,512 L 80,512" fill="none" stroke="black"/>
<path d="M 8,558 L 40,558" fill="none" stroke="black"/><path d="M 8,562 L 40,562 <path d="M 152,512 L 280,512" fill="none" stroke="black"/>
" fill="none" stroke="black"/> <path d="M 344,512 L 448,512" fill="none" stroke="black"/>
<path d="M 8,576 L 40,576" fill="none" stroke="black"/> <path d="M 8,558 L 40,558" fill="none" stroke="black"/>
<path d="M 24,32 C 15.16936,32 8,39.16936 8,48" fill="none" stroke="black"/> <path d="M 8,562 L 40,562" fill="none" stroke="black"/>
<path d="M 96,32 C 104.83064,32 112,39.16936 112,48" fill="none" stroke="black"/ <path d="M 8,576 L 40,576" fill="none" stroke="black"/>
> <path d="M 24,32 C 15.16936,32 8,39.16936 8,48" fill="none" st
<path d="M 208,32 C 199.16936,32 192,39.16936 192,48" fill="none" stroke="black" roke="black"/>
/> <path d="M 96,32 C 104.83064,32 112,39.16936 112,48" fill="non
<path d="M 280,32 C 288.83064,32 296,39.16936 296,48" fill="none" stroke="black" e" stroke="black"/>
/> <path d="M 208,32 C 199.16936,32 192,39.16936 192,48" fill="no
<path d="M 24,80 C 15.16936,80 8,72.83064 8,64" fill="none" stroke="black"/> ne" stroke="black"/>
<path d="M 96,80 C 104.83064,80 112,72.83064 112,64" fill="none" stroke="black"/ <path d="M 280,32 C 288.83064,32 296,39.16936 296,48" fill="no
> ne" stroke="black"/>
<path d="M 208,80 C 199.16936,80 192,72.83064 192,64" fill="none" stroke="black" <path d="M 24,80 C 15.16936,80 8,72.83064 8,64" fill="none" st
/> roke="black"/>
<path d="M 280,80 C 288.83064,80 296,72.83064 296,64" fill="none" stroke="black" <path d="M 96,80 C 104.83064,80 112,72.83064 112,64" fill="non
/> e" stroke="black"/>
<polygon class="arrowhead" points="344,448 332,442.4 332,453.6" fill="black" tra <path d="M 208,80 C 199.16936,80 192,72.83064 192,64" fill="no
nsform="rotate(0,336,448)"/> ne" stroke="black"/>
<polygon class="arrowhead" points="344,368 332,362.4 332,373.6" fill="black" tra <path d="M 280,80 C 288.83064,80 296,72.83064 296,64" fill="no
nsform="rotate(0,336,368)"/> ne" stroke="black"/>
<polygon class="arrowhead" points="344,336 332,330.4 332,341.6" fill="black" tra <polygon class="arrowhead" points="344,448 332,442.4 332,453.6
nsform="rotate(0,336,336)"/> " fill="black" transform="rotate(0,336,448)"/>
<polygon class="arrowhead" points="152,480 140,474.4 140,485.6" fill="black" tra <polygon class="arrowhead" points="344,368 332,362.4 332,373.6
nsform="rotate(0,144,480)"/> " fill="black" transform="rotate(0,336,368)"/>
<polygon class="arrowhead" points="152,400 140,394.4 140,405.6" fill="black" tra <polygon class="arrowhead" points="344,336 332,330.4 332,341.6
nsform="rotate(0,144,400)"/> " fill="black" transform="rotate(0,336,336)"/>
<polygon class="arrowhead" points="152,288 140,282.4 140,293.6" fill="black" tra <polygon class="arrowhead" points="152,480 140,474.4 140,485.6
nsform="rotate(0,144,288)"/> " fill="black" transform="rotate(0,144,480)"/>
<polygon class="arrowhead" points="152,240 140,234.4 140,245.6" fill="black" tra <polygon class="arrowhead" points="152,400 140,394.4 140,405.6
nsform="rotate(0,144,240)"/> " fill="black" transform="rotate(0,144,400)"/>
<polygon class="arrowhead" points="96,416 84,410.4 84,421.6" fill="black" transf <polygon class="arrowhead" points="152,288 140,282.4 140,293.6
orm="rotate(180,88,416)"/> " fill="black" transform="rotate(0,144,288)"/>
<polygon class="arrowhead" points="96,368 84,362.4 84,373.6" fill="black" transf <polygon class="arrowhead" points="152,240 140,234.4 140,245.6
orm="rotate(180,88,368)"/> " fill="black" transform="rotate(0,144,240)"/>
<polygon class="arrowhead" points="96,304 84,298.4 84,309.6" fill="black" transf <polygon class="arrowhead" points="96,416 84,410.4 84,421.6" f
orm="rotate(180,88,304)"/> ill="black" transform="rotate(180,88,416)"/>
<polygon class="arrowhead" points="96,256 84,250.4 84,261.6" fill="black" transf <polygon class="arrowhead" points="96,368 84,362.4 84,373.6" f
orm="rotate(180,88,256)"/> ill="black" transform="rotate(180,88,368)"/>
<g class="text"> <polygon class="arrowhead" points="96,304 84,298.4 84,309.6" f
<text x="40" y="52">End</text> ill="black" transform="rotate(180,88,304)"/>
<text x="76" y="52">user</text> <polygon class="arrowhead" points="96,256 84,250.4 84,261.6" f
<text x="128" y="52">~</text> ill="black" transform="rotate(180,88,256)"/>
<text x="144" y="52">~</text> <g class="text">
<text x="160" y="52">~</text> <text x="40" y="52">End</text>
<text x="176" y="52">~</text> <text x="76" y="52">User</text>
<text x="244" y="52">Resource</text> <text x="128" y="52">~</text>
<text x="224" y="68">Owner</text> <text x="144" y="52">~</text>
<text x="268" y="68">(RO)</text> <text x="160" y="52">~</text>
<text x="56" y="132">(A)</text> <text x="176" y="52">~</text>
<text x="248" y="132">(B)</text> <text x="244" y="52">Resource</text>
<text x="44" y="196">Client</text> <text x="224" y="68">Owner</text>
<text x="104" y="196">(1)</text> <text x="268" y="68">(RO)</text>
<text x="396" y="196">Resource</text> <text x="56" y="132">A</text>
<text x="44" y="212">Instance</text> <text x="248" y="132">B</text>
<text x="396" y="212">Server</text> <text x="44" y="196">Client</text>
<text x="396" y="228">(RS)</text> <text x="104" y="196">(1)</text>
<text x="112" y="244">2</text> <text x="396" y="196">Resource</text>
<text x="216" y="244">Authorization</text> <text x="44" y="212">Instance</text>
<text x="112" y="260">3</text> <text x="396" y="212">Server</text>
<text x="220" y="260">Server</text> <text x="396" y="228">(RS)</text>
<text x="220" y="276">(AS)</text> <text x="112" y="244">2</text>
<text x="112" y="292">4</text> <text x="216" y="244">Authorization</text>
<text x="112" y="308">5</text> <text x="112" y="260">3</text>
<text x="216" y="340">6</text> <text x="220" y="260">Server</text>
<text x="152" y="356">|</text> <text x="220" y="276">(AS)</text>
<text x="280" y="356">|</text> <text x="112" y="292">4</text>
<text x="320" y="356">(7)</text> <text x="112" y="308">5</text>
<text x="216" y="372">8</text> <text x="216" y="340">6</text>
<text x="112" y="404">9</text> <text x="152" y="356">|</text>
<text x="116" y="420">10</text> <text x="280" y="356">|</text>
<text x="220" y="452">11</text> <text x="320" y="356">(7)</text>
<text x="316" y="468">(12)</text> <text x="216" y="372">8</text>
<text x="116" y="484">13</text> <text x="112" y="404">9</text>
<text x="28" y="548">Legend</text> <text x="116" y="420">10</text>
<text x="88" y="564">indicates</text> <text x="220" y="452">11</text>
<text x="136" y="564">a</text> <text x="316" y="468">(12)</text>
<text x="180" y="564">possible</text> <text x="116" y="484">13</text>
<text x="264" y="564">interaction</text> <text x="28" y="548">Legend:</text>
<text x="332" y="564">with</text> <text x="88" y="564">indicates</text>
<text x="360" y="564">a</text> <text x="136" y="564">a</text>
<text x="392" y="564">human</text> <text x="180" y="564">possible</text>
<text x="88" y="580">indicates</text> <text x="264" y="564">interaction</text>
<text x="140" y="580">an</text> <text x="332" y="564">with</text>
<text x="200" y="580">interaction</text> <text x="360" y="564">a</text>
<text x="280" y="580">between</text> <text x="392" y="564">human</text>
<text x="348" y="580">protocol</text> <text x="88" y="580">indicates</text>
<text x="408" y="580">roles</text> <text x="140" y="580">an</text>
<text x="8" y="596">~</text> <text x="200" y="580">interaction</text>
<text x="24" y="596">~</text> <text x="280" y="580">between</text>
<text x="40" y="596">~</text> <text x="348" y="580">protocol</text>
<text x="88" y="596">indicates</text> <text x="408" y="580">roles</text>
<text x="136" y="596">a</text> <text x="8" y="596">~</text>
<text x="184" y="596">potential</text> <text x="24" y="596">~</text>
<text x="272" y="596">equivalence</text> <text x="40" y="596">~</text>
<text x="332" y="596">or</text> <text x="88" y="596">indicates</text>
<text x="392" y="596">out-of-band</text> <text x="136" y="596">a</text>
<text x="120" y="612">communication</text> <text x="184" y="596">potential</text>
<text x="208" y="612">between</text> <text x="272" y="596">equivalence</text>
<text x="264" y="612">roles</text> <text x="332" y="596">or</text>
</g> <text x="392" y="596">out-of-band</text>
</svg> <text x="120" y="612">communication</text>
</artwork><artwork type="ascii-art"><![CDATA[ <text x="208" y="612">between</text>
<text x="264" y="612">roles</text>
</g>
</svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
.----------. .----------. .----------. .----------.
| End user | ~ ~ ~ ~ | Resource | | End user | ~ ~ ~ ~ | Resource |
| | | Owner (RO) | | | | Owner (RO) |
`----+-----` `-----+----` `----+-----` `-----+----`
║ ║ ║ ║
║ ║ ║ ║
(A) (B) (A) (B)
║ ║ ║ ║
║ ║ ║ ║
+-----+--+ ║ +------------+ +-----+--+ ║ +------------+
skipping to change at line 732 skipping to change at line 705
| | | | | | | | | | | |
| +--(9)-->| | | | | +--(9)-->| | | |
| |<-(10)--+ | | | | |<-(10)--+ | | |
| | | | | | | | | | | |
| +---------------(11)------------>| | | +---------------(11)------------>| |
| | | | (12) | | | | | | (12) | |
| +--(13)->| | | | | +--(13)->| | | |
| | | | | | | | | | | |
+--------+ +---------------+ +------------+ +--------+ +---------------+ +------------+
Legend Legend:
===== indicates a possible interaction with a human ===== indicates a possible interaction with a human
----- indicates an interaction between protocol roles ----- indicates an interaction between protocol roles
~ ~ ~ indicates a potential equivalence or out-of-band ~ ~ ~ indicates a potential equivalence or out-of-band
communication between roles communication between roles
]]></artwork></artset></figure> ]]></artwork>
</artset>
<t><list style="symbols"> </figure>
<t>(A) The end user interacts with the client instance to indicate a need for <ul spacing="normal">
resources on <li>(A) The end user interacts with the client instance to indicate
behalf of the RO. This could identify the RS the client instance needs to call a need for resources on
, behalf of the RO. This could identify the RS that the client instance needs to
call,
the resources needed, or the RO that is needed to approve the the resources needed, or the RO that is needed to approve the
request. Note that the RO and end user are often request. Note that the RO and end user are often
the same entity in practice, but GNAP makes no general assumption that they ar the same entity in practice, but GNAP makes no general assumption that they ar
e.</t> e.
<t>(1) The client instance determines what access is needed and which AS to ap </li>
proach for access. Note that <li>
<t>(1) The client instance determines what access is needed and wh
ich AS to approach for access. Note that
for most situations, the client instance is pre-configured with which AS to ta lk to and which for most situations, the client instance is pre-configured with which AS to ta lk to and which
kinds of access it needs, but some more dynamic processes are discussed in kinds of access it needs, but some more dynamic processes are discussed in
<xref target="rs-request-without-token"/>.</t> <xref target="rs-request-without-token"/>.</t>
<t>(2) The client instance <xref target="request">requests access at the AS</x </li>
ref>.</t> <li>
<t>(3) The AS processes the request and determines what is needed to fulfill <t>(2) The client instance requests access at the AS (<xref target
the request (See <xref target="authorization"/>). ="request"> </xref>).</t>
The AS sends its <xref target="response">response to the client instance</xref </li>
>.</t> <li>
<t>(B) If interaction is required, the <t>(3) The AS processes the request and determines what is needed
AS <xref target="authorization">interacts with the RO</xref> to gather authori to fulfill
zation. the request (see <xref target="authorization"/>).
The AS sends its response to the client instance (<xref target="response"> </x
ref>).</t>
</li>
<li>
<t>(B) If interaction is required, the
AS interacts with the RO (<xref target="authorization"> </xref>) to gather aut
horization.
The interactive component of the AS can function The interactive component of the AS can function
using a variety of possible mechanisms including web page using a variety of possible mechanisms, including web page
redirects, applications, challenge/response protocols, or redirects, applications, challenge/response protocols, or
other methods. The RO approves the request for the client instance other methods. The RO approves the request for the client instance
being operated by the end user. Note that the RO and end user are often being operated by the end user. Note that the RO and end user are often
the same entity in practice, and many of GNAP's interaction methods allow the same entity in practice, and many of GNAP's interaction methods allow
the client instance to facilitate the end user interacting with the AS the client instance to facilitate the end user interacting with the AS
in order to fulfill the role of the RO.</t> in order to fulfill the role of the RO.</t>
<t>(4) The client instance <xref target="continue-request">continues the grant </li>
at the AS</xref>. This action could <li>
occur in response to receiving a signal that <xref target="interaction-finish" <t>(4) The client instance continues the grant at the AS (<xref ta
>interaction has finished</xref> or rget="continue-request"> </xref>). This action could
occur in response to receiving a signal that interaction has finished (<xref t
arget="interaction-finish"> </xref>) or
through a periodic polling mechanism, depending on the interaction capabilitie s of the client through a periodic polling mechanism, depending on the interaction capabilitie s of the client
software and the options active in the grant request.</t> software and the options active in the grant request.</t>
<t>(5) If the AS determines that access can be granted, it returns a </li>
<xref target="response">response to the client instance</xref> including an <x <li>
ref target="response-token">access token</xref> for <t>(5) If the AS determines that access can be granted, it returns
calling the RS and any <xref target="response-subject">directly returned infor a
mation</xref> about the RO.</t> response to the client instance (<xref target="response"> </xref>), including
<t>(6) The client instance <xref target="use-access-token">uses the access tok an access token (<xref target="response-token"> </xref>) for
en</xref> to call the RS.</t> calling the RS and any directly returned information (<xref target="response-s
<t>(7) The RS determines if the token is sufficient for the request by ubject"> </xref>) about the RO.</t>
</li>
<li>
<t>(6) The client instance uses the access token (<xref target="us
e-access-token"> </xref>) to call the RS.</t>
</li>
<li>
<t>(7) The RS determines if the token is sufficient for the reques
t by
examining the token. The means of the RS determining this access are examining the token. The means of the RS determining this access are
out of scope of this specification, but some options are discussed in out of scope of this specification, but some options are discussed in
<xref target="I-D.ietf-gnap-resource-servers"/>.</t> <xref target="I-D.ietf-gnap-resource-servers"/>.</t>
<t>(8) The client instance <xref target="use-access-token">calls the RS</xref> </li>
using the access token <li>
until the RS or client instance determine that the token is no longer valid.</ <t>(8) The client instance calls the RS (<xref target="use-access-
t> token"> </xref>) using the access token
<t>(9) When the token no longer works, the client instance until the RS or client instance determines that the token is no longer valid.<
<xref target="rotate-access-token">rotates the access token</xref>.</t> /t>
<t>(10) The AS issues a <xref target="response-token">new access token</xref> </li>
to the client instance <li>
<t>(9) When the token no longer works, the client instance
rotates the access token (<xref target="rotate-access-token"> </xref>).</t>
</li>
<li>
<t>(10) The AS issues a new access token (<xref target="response-t
oken"> </xref>) to the client instance
with the same rights as the original access token returned in (5).</t> with the same rights as the original access token returned in (5).</t>
<t>(11) The client instance <xref target="use-access-token">uses the new acces </li>
s token</xref> to call the RS.</t> <li>
<t>(12) The RS determines if the new token is sufficient for the request, as i <t>(11) The client instance uses the new access token (<xref targe
n (7).</t> t="use-access-token"> </xref>) to call the RS.</t>
<t>(13) The client instance <xref target="revoke-access-token">disposes of the </li>
token</xref> once the client instance <li>
<t>(12) The RS determines if the new token is sufficient for the r
equest, as in (7).</t>
</li>
<li>
<t>(13) The client instance disposes of the token (<xref target="r
evoke-access-token"> </xref>) once the client instance
has completed its access of the RS and no longer needs the token.</t> has completed its access of the RS and no longer needs the token.</t>
</list></t> </li>
</ul>
<t>The following sections and <xref target="examples"/> contain specific guidanc <t>The following sections and <xref target="examples"/> contain specif
e on how to use ic guidance on how to use
GNAP in different situations and deployments. For example, it is possible for th e GNAP in different situations and deployments. For example, it is possible for th e
client instance to never request an access token and never call an RS, just as i t is client instance to never request an access token and never call an RS, just as i t is
possible to have no end user involved in the delegation process.</t> possible to have no end user involved in the delegation process.</t>
</section>
</section> <section anchor="sequence-redirect">
<section anchor="sequence-redirect"><name>Redirect-based Interaction</name> <name>Redirect-Based Interaction</name>
<t>In this example flow, the client instance is a web application that
<t>In this example flow, the client instance is a web application that wants acc wants access to resources on behalf
ess to resources on behalf of the current user, who acts as both the end user and the RO. Since the client
of the current user, who acts as both the end user and the resource instance is capable of directing the user to an arbitrary URI and
owner (RO). Since the client instance is capable of directing the user to an arb
itrary URI and
receiving responses from the user's browser, interaction here is handled through receiving responses from the user's browser, interaction here is handled through
front-channel redirects using the user's browser. The redirection URI used for i nteraction is front-channel redirects using the user's browser. The redirection URI used for i nteraction is
a service hosted by the AS in this example. The client instance uses a persisten t session a service hosted by the AS in this example. The client instance uses a persisten t session
with the user to ensure the same user that is starting the interaction is the us er with the user to ensure the same user that is starting the interaction is the us er
that returns from the interaction.</t> that returns from the interaction.</t>
<figure>
<figure title="Figure 4: Diagram of a redirect-based interaction"><artset><artwo <name>Diagram of a Redirect-Based Interaction</name>
rk type="svg"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" height="496 <artset>
" width="576" viewBox="0 0 576 496" class="diagram" text-anchor="middle" font-fa <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" versio
mily="monospace" font-size="13px" stroke-linecap="round"> n="1.1" height="496" width="576" viewBox="0 0 576 496" class="diagram" text-anch
<path d="M 8,32 L 8,480" fill="none" stroke="black"/> or="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 80,32 L 80,480" fill="none" stroke="black"/> <path d="M 8,32 L 8,480" fill="none" stroke="black"/>
<path d="M 360,32 L 360,64" fill="none" stroke="black"/> <path d="M 80,32 L 80,480" fill="none" stroke="black"/>
<path d="M 360,96 L 360,160" fill="none" stroke="black"/> <path d="M 360,32 L 360,64" fill="none" stroke="black"/>
<path d="M 360,192 L 360,288" fill="none" stroke="black"/> <path d="M 360,96 L 360,160" fill="none" stroke="black"/>
<path d="M 360,320 L 360,408" fill="none" stroke="black"/> <path d="M 360,192 L 360,288" fill="none" stroke="black"/>
<path d="M 360,456 L 360,480" fill="none" stroke="black"/> <path d="M 360,320 L 360,408" fill="none" stroke="black"/>
<path d="M 432,32 L 432,64" fill="none" stroke="black"/> <path d="M 360,456 L 360,480" fill="none" stroke="black"/>
<path d="M 432,96 L 432,160" fill="none" stroke="black"/> <path d="M 432,32 L 432,64" fill="none" stroke="black"/>
<path d="M 432,192 L 432,288" fill="none" stroke="black"/> <path d="M 432,96 L 432,160" fill="none" stroke="black"/>
<path d="M 432,320 L 432,408" fill="none" stroke="black"/> <path d="M 432,192 L 432,288" fill="none" stroke="black"/>
<path d="M 432,456 L 432,480" fill="none" stroke="black"/> <path d="M 432,320 L 432,408" fill="none" stroke="black"/>
<path d="M 480,400 L 480,464" fill="none" stroke="black"/> <path d="M 432,456 L 432,480" fill="none" stroke="black"/>
<path d="M 512,48 L 512,304" fill="none" stroke="black"/> <path d="M 480,400 L 480,464" fill="none" stroke="black"/>
<path d="M 552,400 L 552,464" fill="none" stroke="black"/> <path d="M 512,48 L 512,304" fill="none" stroke="black"/>
<path d="M 568,48 L 568,304" fill="none" stroke="black"/> <path d="M 552,400 L 552,464" fill="none" stroke="black"/>
<path d="M 8,32 L 80,32" fill="none" stroke="black"/> <path d="M 568,48 L 568,304" fill="none" stroke="black"/>
<path d="M 360,32 L 432,32" fill="none" stroke="black"/> <path d="M 8,32 L 80,32" fill="none" stroke="black"/>
<path d="M 528,32 L 552,32" fill="none" stroke="black"/> <path d="M 360,32 L 432,32" fill="none" stroke="black"/>
<path d="M 88,78 L 104,78" fill="none" stroke="black"/><path d="M 88,82 L 104,82 <path d="M 528,32 L 552,32" fill="none" stroke="black"/>
" fill="none" stroke="black"/> <path d="M 88,78 L 104,78" fill="none" stroke="black"/>
<path d="M 120,78 L 136,78" fill="none" stroke="black"/><path d="M 120,82 L 136, <path d="M 88,82 L 104,82" fill="none" stroke="black"/>
82" fill="none" stroke="black"/> <path d="M 120,78 L 136,78" fill="none" stroke="black"/>
<path d="M 264,78 L 512,78" fill="none" stroke="black"/><path d="M 264,82 L 512, <path d="M 120,82 L 136,82" fill="none" stroke="black"/>
82" fill="none" stroke="black"/> <path d="M 264,78 L 512,78" fill="none" stroke="black"/>
<path d="M 80,112 L 104,112" fill="none" stroke="black"/> <path d="M 264,82 L 512,82" fill="none" stroke="black"/>
<path d="M 120,112 L 144,112" fill="none" stroke="black"/> <path d="M 80,112 L 104,112" fill="none" stroke="black"/>
<path d="M 280,112 L 352,112" fill="none" stroke="black"/> <path d="M 120,112 L 144,112" fill="none" stroke="black"/>
<path d="M 88,144 L 104,144" fill="none" stroke="black"/> <path d="M 280,112 L 352,112" fill="none" stroke="black"/>
<path d="M 120,144 L 136,144" fill="none" stroke="black"/> <path d="M 88,144 L 104,144" fill="none" stroke="black"/>
<path d="M 304,144 L 360,144" fill="none" stroke="black"/> <path d="M 120,144 L 136,144" fill="none" stroke="black"/>
<path d="M 80,174 L 104,174" fill="none" stroke="black"/><path d="M 80,178 L 104 <path d="M 304,144 L 360,144" fill="none" stroke="black"/>
,178" fill="none" stroke="black"/> <path d="M 80,174 L 104,174" fill="none" stroke="black"/>
<path d="M 120,174 L 136,174" fill="none" stroke="black"/><path d="M 120,178 L 1 <path d="M 80,178 L 104,178" fill="none" stroke="black"/>
36,178" fill="none" stroke="black"/> <path d="M 120,174 L 136,174" fill="none" stroke="black"/>
<path d="M 352,174 L 504,174" fill="none" stroke="black"/><path d="M 352,178 L 5 <path d="M 120,178 L 136,178" fill="none" stroke="black"/>
04,178" fill="none" stroke="black"/> <path d="M 352,174 L 504,174" fill="none" stroke="black"/>
<path d="M 512,192 L 568,192" fill="none" stroke="black"/> <path d="M 352,178 L 504,178" fill="none" stroke="black"/>
<path d="M 440,206 L 464,206" fill="none" stroke="black"/><path d="M 440,210 L 4 <path d="M 512,192 L 568,192" fill="none" stroke="black"/>
64,210" fill="none" stroke="black"/> <path d="M 440,206 L 464,206" fill="none" stroke="black"/>
<path d="M 480,206 L 504,206" fill="none" stroke="black"/><path d="M 480,210 L 5 <path d="M 440,210 L 464,210" fill="none" stroke="black"/>
04,210" fill="none" stroke="black"/> <path d="M 480,206 L 504,206" fill="none" stroke="black"/>
<path d="M 440,254 L 464,254" fill="none" stroke="black"/><path d="M 440,258 L 4 <path d="M 480,210 L 504,210" fill="none" stroke="black"/>
64,258" fill="none" stroke="black"/> <path d="M 440,254 L 464,254" fill="none" stroke="black"/>
<path d="M 480,254 L 504,254" fill="none" stroke="black"/><path d="M 480,258 L 5 <path d="M 440,258 L 464,258" fill="none" stroke="black"/>
04,258" fill="none" stroke="black"/> <path d="M 480,254 L 504,254" fill="none" stroke="black"/>
<path d="M 512,272 L 568,272" fill="none" stroke="black"/> <path d="M 480,258 L 504,258" fill="none" stroke="black"/>
<path d="M 88,302 L 104,302" fill="none" stroke="black"/><path d="M 88,306 L 104 <path d="M 512,272 L 568,272" fill="none" stroke="black"/>
,306" fill="none" stroke="black"/> <path d="M 88,302 L 104,302" fill="none" stroke="black"/>
<path d="M 120,302 L 136,302" fill="none" stroke="black"/><path d="M 120,306 L 1 <path d="M 88,306 L 104,306" fill="none" stroke="black"/>
36,306" fill="none" stroke="black"/> <path d="M 120,302 L 136,302" fill="none" stroke="black"/>
<path d="M 360,302 L 512,302" fill="none" stroke="black"/><path d="M 360,306 L 5 <path d="M 120,306 L 136,306" fill="none" stroke="black"/>
12,306" fill="none" stroke="black"/> <path d="M 360,302 L 512,302" fill="none" stroke="black"/>
<path d="M 528,320 L 552,320" fill="none" stroke="black"/> <path d="M 360,306 L 512,306" fill="none" stroke="black"/>
<path d="M 80,336 L 104,336" fill="none" stroke="black"/> <path d="M 528,320 L 552,320" fill="none" stroke="black"/>
<path d="M 120,336 L 144,336" fill="none" stroke="black"/> <path d="M 80,336 L 104,336" fill="none" stroke="black"/>
<path d="M 296,336 L 352,336" fill="none" stroke="black"/> <path d="M 120,336 L 144,336" fill="none" stroke="black"/>
<path d="M 88,368 L 104,368" fill="none" stroke="black"/> <path d="M 296,336 L 352,336" fill="none" stroke="black"/>
<path d="M 120,368 L 160,368" fill="none" stroke="black"/> <path d="M 88,368 L 104,368" fill="none" stroke="black"/>
<path d="M 280,368 L 360,368" fill="none" stroke="black"/> <path d="M 120,368 L 160,368" fill="none" stroke="black"/>
<path d="M 480,400 L 552,400" fill="none" stroke="black"/> <path d="M 280,368 L 360,368" fill="none" stroke="black"/>
<path d="M 80,416 L 104,416" fill="none" stroke="black"/> <path d="M 480,400 L 552,400" fill="none" stroke="black"/>
<path d="M 128,416 L 144,416" fill="none" stroke="black"/> <path d="M 80,416 L 104,416" fill="none" stroke="black"/>
<path d="M 248,416 L 472,416" fill="none" stroke="black"/> <path d="M 128,416 L 144,416" fill="none" stroke="black"/>
<path d="M 88,448 L 104,448" fill="none" stroke="black"/> <path d="M 248,416 L 472,416" fill="none" stroke="black"/>
<path d="M 128,448 L 144,448" fill="none" stroke="black"/> <path d="M 88,448 L 104,448" fill="none" stroke="black"/>
<path d="M 264,448 L 472,448" fill="none" stroke="black"/> <path d="M 128,448 L 144,448" fill="none" stroke="black"/>
<path d="M 480,464 L 552,464" fill="none" stroke="black"/> <path d="M 264,448 L 472,448" fill="none" stroke="black"/>
<path d="M 8,480 L 80,480" fill="none" stroke="black"/> <path d="M 480,464 L 552,464" fill="none" stroke="black"/>
<path d="M 360,480 L 432,480" fill="none" stroke="black"/> <path d="M 8,480 L 80,480" fill="none" stroke="black"/>
<path d="M 528,32 C 519.16936,32 512,39.16936 512,48" fill="none" stroke="black" <path d="M 360,480 L 432,480" fill="none" stroke="black"/>
/> <path d="M 528,32 C 519.16936,32 512,39.16936 512,48" fill="no
<path d="M 552,32 C 560.83064,32 568,39.16936 568,48" fill="none" stroke="black" ne" stroke="black"/>
/> <path d="M 552,32 C 560.83064,32 568,39.16936 568,48" fill="no
<path d="M 528,320 C 519.16936,320 512,312.83064 512,304" fill="none" stroke="bl ne" stroke="black"/>
ack"/> <path d="M 528,320 C 519.16936,320 512,312.83064 512,304" fill
<path d="M 552,320 C 560.83064,320 568,312.83064 568,304" fill="none" stroke="bl ="none" stroke="black"/>
ack"/> <path d="M 552,320 C 560.83064,320 568,312.83064 568,304" fill
<polygon class="arrowhead" points="512,256 500,250.4 500,261.6" fill="black" tra ="none" stroke="black"/>
nsform="rotate(0,504,256)"/> <polygon class="arrowhead" points="512,256 500,250.4 500,261.6
<polygon class="arrowhead" points="512,208 500,202.4 500,213.6" fill="black" tra " fill="black" transform="rotate(0,504,256)"/>
nsform="rotate(0,504,208)"/> <polygon class="arrowhead" points="512,208 500,202.4 500,213.6
<polygon class="arrowhead" points="512,176 500,170.4 500,181.6" fill="black" tra " fill="black" transform="rotate(0,504,208)"/>
nsform="rotate(0,504,176)"/> <polygon class="arrowhead" points="512,176 500,170.4 500,181.6
<polygon class="arrowhead" points="480,416 468,410.4 468,421.6" fill="black" tra " fill="black" transform="rotate(0,504,176)"/>
nsform="rotate(0,472,416)"/> <polygon class="arrowhead" points="480,416 468,410.4 468,421.6
<polygon class="arrowhead" points="448,256 436,250.4 436,261.6" fill="black" tra " fill="black" transform="rotate(0,472,416)"/>
nsform="rotate(180,440,256)"/> <polygon class="arrowhead" points="448,256 436,250.4 436,261.6
<polygon class="arrowhead" points="448,208 436,202.4 436,213.6" fill="black" tra " fill="black" transform="rotate(180,440,256)"/>
nsform="rotate(180,440,208)"/> <polygon class="arrowhead" points="448,208 436,202.4 436,213.6
<polygon class="arrowhead" points="360,336 348,330.4 348,341.6" fill="black" tra " fill="black" transform="rotate(180,440,208)"/>
nsform="rotate(0,352,336)"/> <polygon class="arrowhead" points="360,336 348,330.4 348,341.6
<polygon class="arrowhead" points="360,112 348,106.4 348,117.6" fill="black" tra " fill="black" transform="rotate(0,352,336)"/>
nsform="rotate(0,352,112)"/> <polygon class="arrowhead" points="360,112 348,106.4 348,117.6
<polygon class="arrowhead" points="96,448 84,442.4 84,453.6" fill="black" transf " fill="black" transform="rotate(0,352,112)"/>
orm="rotate(180,88,448)"/> <polygon class="arrowhead" points="96,448 84,442.4 84,453.6" f
<polygon class="arrowhead" points="96,368 84,362.4 84,373.6" fill="black" transf ill="black" transform="rotate(180,88,448)"/>
orm="rotate(180,88,368)"/> <polygon class="arrowhead" points="96,368 84,362.4 84,373.6" f
<polygon class="arrowhead" points="96,304 84,298.4 84,309.6" fill="black" transf ill="black" transform="rotate(180,88,368)"/>
orm="rotate(180,88,304)"/> <polygon class="arrowhead" points="96,304 84,298.4 84,309.6" f
<polygon class="arrowhead" points="96,144 84,138.4 84,149.6" fill="black" transf ill="black" transform="rotate(180,88,304)"/>
orm="rotate(180,88,144)"/> <polygon class="arrowhead" points="96,144 84,138.4 84,149.6" f
<polygon class="arrowhead" points="96,80 84,74.4 84,85.6" fill="black" transform ill="black" transform="rotate(180,88,144)"/>
="rotate(180,88,80)"/> <polygon class="arrowhead" points="96,80 84,74.4 84,85.6" fill
<g class="text"> ="black" transform="rotate(180,88,80)"/>
<text x="44" y="52">Client</text> <g class="text">
<text x="396" y="52">AS</text> <text x="44" y="52">Client</text>
<text x="536" y="52">End</text> <text x="396" y="52">AS</text>
<text x="44" y="68">Instance</text> <text x="536" y="52">End</text>
<text x="540" y="68">User</text> <text x="44" y="68">Instance</text>
<text x="112" y="84">1</text> <text x="540" y="68">User</text>
<text x="168" y="84">Start</text> <text x="112" y="84">1</text>
<text x="224" y="84">Session</text> <text x="168" y="84">Start</text>
<text x="112" y="116">2</text> <text x="224" y="84">Session</text>
<text x="184" y="116">Request</text> <text x="112" y="116">2</text>
<text x="244" y="116">Access</text> <text x="184" y="116">Request</text>
<text x="112" y="148">3</text> <text x="244" y="116">Access</text>
<text x="192" y="148">Interaction</text> <text x="112" y="148">3</text>
<text x="268" y="148">Needed</text> <text x="192" y="148">Interaction</text>
<text x="112" y="180">4</text> <text x="268" y="148">Needed</text>
<text x="180" y="180">Redirect</text> <text x="112" y="180">4</text>
<text x="232" y="180">for</text> <text x="180" y="180">Redirect</text>
<text x="296" y="180">Interaction</text> <text x="232" y="180">for</text>
<text x="472" y="212">5</text> <text x="296" y="180">Interaction</text>
<text x="472" y="228">AuthN</text> <text x="472" y="212">5</text>
<text x="540" y="228">RO</text> <text x="472" y="228">AuthN</text>
<text x="472" y="260">6</text> <text x="540" y="228">RO</text>
<text x="472" y="276">AuthZ</text> <text x="472" y="260">6</text>
<text x="536" y="292">End</text> <text x="472" y="276">AuthZ</text>
<text x="112" y="308">7</text> <text x="536" y="292">End</text>
<text x="180" y="308">Redirect</text> <text x="112" y="308">7</text>
<text x="232" y="308">for</text> <text x="180" y="308">Redirect</text>
<text x="300" y="308">Continuation</text> <text x="232" y="308">for</text>
<text x="540" y="308">User</text> <text x="300" y="308">Continuation</text>
<text x="112" y="340">8</text> <text x="540" y="308">User</text>
<text x="188" y="340">Continue</text> <text x="112" y="340">8</text>
<text x="256" y="340">Request</text> <text x="188" y="340">Continue</text>
<text x="112" y="372">9</text> <text x="256" y="340">Request</text>
<text x="192" y="372">Grant</text> <text x="112" y="372">9</text>
<text x="244" y="372">Access</text> <text x="192" y="372">Grant</text>
<text x="116" y="420">10</text> <text x="244" y="372">Access</text>
<text x="180" y="420">Access</text> <text x="116" y="420">10</text>
<text x="224" y="420">API</text> <text x="180" y="420">Access</text>
<text x="516" y="420">RS</text> <text x="224" y="420">API</text>
<text x="360" y="436">|</text> <text x="516" y="420">RS</text>
<text x="432" y="436">|</text> <text x="360" y="436">|</text>
<text x="116" y="452">11</text> <text x="432" y="436">|</text>
<text x="168" y="452">API</text> <text x="116" y="452">11</text>
<text x="220" y="452">Response</text> <text x="168" y="452">API</text>
</g> <text x="220" y="452">Response</text>
</svg> </g>
</artwork><artwork type="ascii-art"><![CDATA[ </svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
+--------+ +--------+ .----. +--------+ +--------+ .----.
| Client | | AS | | End | | Client | | AS | | End |
|Instance| | | | User | |Instance| | | | User |
| |<=(1)== Start Session ===============================+ | | |<=(1)== Start Session ===============================+ |
| | | | | | | | | | | |
| +--(2)--- Request Access --------->| | | | | +--(2)--- Request Access --------->| | | |
| | | | | | | | | | | |
| |<-(3)-- Interaction Needed -------+ | | | | |<-(3)-- Interaction Needed -------+ | | |
| | | | | | | | | | | |
| +==(4)== Redirect for Interaction ===================>| | | +==(4)== Redirect for Interaction ===================>| |
skipping to change at line 956 skipping to change at line 972
| +--(8)--- Continue Request ------->| | | +--(8)--- Continue Request ------->| |
| | | | | | | |
| |<-(9)----- Grant Access ----------+ | | |<-(9)----- Grant Access ----------+ |
| | | | | | | |
| | | | +--------+ | | | | +--------+
| +--(10)-- Access API ---------------------------->| RS | | +--(10)-- Access API ---------------------------->| RS |
| | | | | | | | | | | |
| |<-(11)-- API Response ---------------------------| | | |<-(11)-- API Response ---------------------------| |
| | | | +--------+ | | | | +--------+
+--------+ +--------+ +--------+ +--------+
]]></artwork></artset></figure> ]]></artwork>
</artset>
<t><list style="numbers"> </figure>
<t>The client instance establishes a session with the user, in the role of the <ul spacing="normal"><li>
end user.</t> <t>(1) The client instance establishes a session with the user, in
<t>The client instance <xref target="request">requests access to the resource< the role of the end user.</t>
/xref>. The client instance indicates that </li>
it can <xref target="request-interact-redirect">redirect to an arbitrary URI</x <li>
ref> and <t>(2) The client instance requests access to the resource (<xref
<xref target="request-interact-callback-redirect">receive a redirect from the b target="request"> </xref>). The client instance indicates that
rowser</xref>. The client instance it can redirect to an arbitrary URI (<xref target="request-interact-redirect">
</xref>) and
receive a redirect from the browser (<xref target="request-interact-callback-re
direct"> </xref>). The client instance
stores verification information for its redirect in the session created stores verification information for its redirect in the session created
in (1).</t> in (1).</t>
<t>The AS determines that interaction is needed and <xref target="response">re </li>
sponds</xref> with <li>
a <xref target="response-interact-redirect">URI to send the user to</xref> and <t>(3) The AS determines that interaction is needed and responds (
<xref target="response-interact-finish">information needed to verify the redire <xref target="response"> </xref>) with
ct</xref> in (7). a URI to send the user to (<xref target="response-interact-redirect"> </xref>)
and
information needed to verify the redirect (<xref target="response-interact-fini
sh"> </xref>) in (7).
The AS also includes information the client instance will need to The AS also includes information the client instance will need to
<xref target="response-continue">continue the request</xref> in (8). The AS ass ociates this continue the request (<xref target="response-continue"> </xref>) in (8). The AS associates this
continuation information with an ongoing request that will be referenced in (4) , (6), and (8).</t> continuation information with an ongoing request that will be referenced in (4) , (6), and (8).</t>
<t>The client instance stores the verification and continuation information fr </li>
om (3) in the session from (1). The client instance <li>
then <xref target="interaction-redirect">redirects the user to the URI</xref> g <t>(4) The client instance stores the verification and continuatio
iven by the AS in (3). n information from (3) in the session from (1). The client instance
then redirects the user to the URI (<xref target="interaction-redirect"> </xref
>) given by the AS in (3).
The user's browser loads the interaction redirect URI. The AS loads the pending The user's browser loads the interaction redirect URI. The AS loads the pending
request based on the incoming URI generated in (3).</t> request based on the incoming URI generated in (3).</t>
<t>The user authenticates at the AS, taking on the role of the RO.</t> </li>
<t>As the RO, the user authorizes the pending request from the client instance <li>
.</t> <t>(5) The user authenticates at the AS, taking on the role of the
<t>When the AS is done interacting with the user, the AS RO.</t>
<xref target="interaction-callback">redirects the user back</xref> to the </li>
<li>
<t>(6) As the RO, the user authorizes the pending request from the
client instance.</t>
</li>
<li>
<t>(7) When the AS is done interacting with the user, the AS
redirects the user back (<xref target="interaction-callback"> </xref>) to the
client instance using the redirect URI provided in (2). The redirect URI is aug mented with client instance using the redirect URI provided in (2). The redirect URI is aug mented with
an interaction reference that the AS associates with the ongoing an interaction reference that the AS associates with the ongoing
request created in (2) and referenced in (4). The redirect URI is also request created in (2) and referenced in (4). The redirect URI is also
augmented with a hash of the security information provided augmented with a hash of the security information provided
in (2) and (3). The client instance loads the verification information from (2) and (3) from in (2) and (3). The client instance loads the verification information from (2) and (3) from
the session created in (1). The client instance <xref target="interaction-hash" >calculates a hash</xref> the session created in (1). The client instance calculates a hash (<xref target ="interaction-hash"> </xref>)
based on this information and continues only if the hash validates. based on this information and continues only if the hash validates.
Note that the client instance needs to ensure that the parameters for the incom ing Note that the client instance needs to ensure that the parameters for the incom ing
request match those that it is expecting from the session created request match those that it is expecting from the session created
in (1). The client instance also needs to be prepared for the end user never be ing returned in (1). The client instance also needs to be prepared for the end user never be ing returned
to the client instance and handle timeouts appropriately.</t> to the client instance and handle timeouts appropriately.</t>
<t>The client instance loads the continuation information from (3) and sends t </li>
he <li>
<t>(8) The client instance loads the continuation information from
(3) and sends the
interaction reference from (7) in a request to interaction reference from (7) in a request to
<xref target="continue-after-interaction">continue the request</xref>. The AS continue the request (<xref target="continue-after-interaction"> </xref>). The
validates the interaction reference ensuring that the reference AS
validates the interaction reference, ensuring that the reference
is associated with the request being continued.</t> is associated with the request being continued.</t>
<t>If the request has been authorized, the AS grants access to the information </li>
in the form of <xref target="response-token">access tokens</xref> and <li>
<xref target="response-subject">direct subject information</xref> to the client <t>(9) If the request has been authorized, the AS grants access to
instance.</t> the information
<t>The client instance <xref target="use-access-token">uses the access token</ in the form of access tokens (<xref target="response-token"> </xref>) and
xref> to call the RS.</t> direct subject information (<xref target="response-subject"> </xref>) to the cl
<t>The RS validates the access token and returns an appropriate response for t ient instance.</t>
he </li>
<li>
<t>(10) The client instance uses the access token (<xref target="u
se-access-token"> </xref>) to call the RS.</t>
</li>
<li>
<t>(11) The RS validates the access token and returns an appropria
te response for the
API.</t> API.</t>
</list></t> </li>
</ul>
<t>An example set of protocol messages for this method can be found in <xref tar <t>An example set of protocol messages for this method can be found in
get="example-auth-code"/>.</t> <xref target="example-auth-code"/>.</t>
</section>
</section> <section anchor="sequence-user-code">
<section anchor="sequence-user-code"><name>User-code Interaction</name> <name>User Code Interaction</name>
<t>In this example flow, the client instance is a device that is capab
<t>In this example flow, the client instance is a device that is capable of pres le of presenting a short,
enting a short,
human-readable code to the user and directing the user to enter that code at human-readable code to the user and directing the user to enter that code at
a known URI. The user enters the code at a URI that is an interactive service ho sted by the a known URI. The user enters the code at a URI that is an interactive service ho sted by the
AS in this example. The client instance is not capable of presenting an arbitrar y URI to the user, AS in this example. The client instance is not capable of presenting an arbitrar y URI to the user,
nor is it capable of accepting incoming HTTP requests from the user's browser. nor is it capable of accepting incoming HTTP requests from the user's browser.
The client instance polls the AS while it is waiting for the RO to authorize the request. The client instance polls the AS while it is waiting for the RO to authorize the request.
The user's interaction is assumed to occur on a secondary device. In this exampl e The user's interaction is assumed to occur on a secondary device. In this exampl e,
it is assumed that the user is both the end user and RO. Note that since the use r is not assumed it is assumed that the user is both the end user and RO. Note that since the use r is not assumed
to be interacting with the client instance through the same web browser used for interaction at to be interacting with the client instance through the same web browser used for interaction at
the AS, the user is not shown as being connected to the client instance in this diagram.</t> the AS, the user is not shown as being connected to the client instance in this diagram.</t>
<figure>
<figure title="Figure 5: Diagram of a user-code-based interaction"><artset><artw <name>Diagram of a User-Code-Based Interaction</name>
ork type="svg"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" height="56 <artset>
0" width="576" viewBox="0 0 576 560" class="diagram" text-anchor="middle" font-f <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" versio
amily="monospace" font-size="13px" stroke-linecap="round"> n="1.1" height="560" width="576" viewBox="0 0 576 560" class="diagram" text-anch
<path d="M 8,32 L 8,544" fill="none" stroke="black"/> or="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 80,32 L 80,544" fill="none" stroke="black"/> <path d="M 8,32 L 8,544" fill="none" stroke="black"/>
<path d="M 360,32 L 360,112" fill="none" stroke="black"/> <path d="M 80,32 L 80,544" fill="none" stroke="black"/>
<path d="M 360,144 L 360,472" fill="none" stroke="black"/> <path d="M 360,32 L 360,112" fill="none" stroke="black"/>
<path d="M 360,520 L 360,544" fill="none" stroke="black"/> <path d="M 360,144 L 360,472" fill="none" stroke="black"/>
<path d="M 432,32 L 432,112" fill="none" stroke="black"/> <path d="M 360,520 L 360,544" fill="none" stroke="black"/>
<path d="M 432,144 L 432,472" fill="none" stroke="black"/> <path d="M 432,32 L 432,112" fill="none" stroke="black"/>
<path d="M 432,520 L 432,544" fill="none" stroke="black"/> <path d="M 432,144 L 432,472" fill="none" stroke="black"/>
<path d="M 480,464 L 480,528" fill="none" stroke="black"/> <path d="M 432,520 L 432,544" fill="none" stroke="black"/>
<path d="M 512,48 L 512,416" fill="none" stroke="black"/> <path d="M 480,464 L 480,528" fill="none" stroke="black"/>
<path d="M 552,464 L 552,528" fill="none" stroke="black"/> <path d="M 512,48 L 512,416" fill="none" stroke="black"/>
<path d="M 568,48 L 568,416" fill="none" stroke="black"/> <path d="M 552,464 L 552,528" fill="none" stroke="black"/>
<path d="M 8,32 L 80,32" fill="none" stroke="black"/> <path d="M 568,48 L 568,416" fill="none" stroke="black"/>
<path d="M 360,32 L 432,32" fill="none" stroke="black"/> <path d="M 8,32 L 80,32" fill="none" stroke="black"/>
<path d="M 528,32 L 552,32" fill="none" stroke="black"/> <path d="M 360,32 L 432,32" fill="none" stroke="black"/>
<path d="M 80,64 L 104,64" fill="none" stroke="black"/> <path d="M 528,32 L 552,32" fill="none" stroke="black"/>
<path d="M 120,64 L 144,64" fill="none" stroke="black"/> <path d="M 80,64 L 104,64" fill="none" stroke="black"/>
<path d="M 280,64 L 352,64" fill="none" stroke="black"/> <path d="M 120,64 L 144,64" fill="none" stroke="black"/>
<path d="M 88,96 L 104,96" fill="none" stroke="black"/> <path d="M 280,64 L 352,64" fill="none" stroke="black"/>
<path d="M 120,96 L 136,96" fill="none" stroke="black"/> <path d="M 88,96 L 104,96" fill="none" stroke="black"/>
<path d="M 304,96 L 360,96" fill="none" stroke="black"/> <path d="M 120,96 L 136,96" fill="none" stroke="black"/>
<path d="M 80,126 L 104,126" fill="none" stroke="black"/><path d="M 80,130 L 104 <path d="M 304,96 L 360,96" fill="none" stroke="black"/>
,130" fill="none" stroke="black"/> <path d="M 80,126 L 104,126" fill="none" stroke="black"/>
<path d="M 120,126 L 152,126" fill="none" stroke="black"/><path d="M 120,130 L 1 <path d="M 80,130 L 104,130" fill="none" stroke="black"/>
52,130" fill="none" stroke="black"/> <path d="M 120,126 L 152,126" fill="none" stroke="black"/>
<path d="M 312,126 L 504,126" fill="none" stroke="black"/><path d="M 312,130 L 5 <path d="M 120,130 L 152,130" fill="none" stroke="black"/>
04,130" fill="none" stroke="black"/> <path d="M 312,126 L 504,126" fill="none" stroke="black"/>
<path d="M 440,158 L 464,158" fill="none" stroke="black"/><path d="M 440,162 L 4 <path d="M 312,130 L 504,130" fill="none" stroke="black"/>
64,162" fill="none" stroke="black"/> <path d="M 440,158 L 464,158" fill="none" stroke="black"/>
<path d="M 480,158 L 512,158" fill="none" stroke="black"/><path d="M 480,162 L 5 <path d="M 440,162 L 464,162" fill="none" stroke="black"/>
12,162" fill="none" stroke="black"/> <path d="M 480,158 L 512,158" fill="none" stroke="black"/>
<path d="M 512,192 L 568,192" fill="none" stroke="black"/> <path d="M 480,162 L 512,162" fill="none" stroke="black"/>
<path d="M 440,206 L 464,206" fill="none" stroke="black"/><path d="M 440,210 L 4 <path d="M 512,192 L 568,192" fill="none" stroke="black"/>
64,210" fill="none" stroke="black"/> <path d="M 440,206 L 464,206" fill="none" stroke="black"/>
<path d="M 480,206 L 504,206" fill="none" stroke="black"/><path d="M 480,210 L 5 <path d="M 440,210 L 464,210" fill="none" stroke="black"/>
04,210" fill="none" stroke="black"/> <path d="M 480,206 L 504,206" fill="none" stroke="black"/>
<path d="M 80,240 L 104,240" fill="none" stroke="black"/> <path d="M 480,210 L 504,210" fill="none" stroke="black"/>
<path d="M 120,240 L 144,240" fill="none" stroke="black"/> <path d="M 80,240 L 104,240" fill="none" stroke="black"/>
<path d="M 328,240 L 352,240" fill="none" stroke="black"/> <path d="M 120,240 L 144,240" fill="none" stroke="black"/>
<path d="M 440,254 L 464,254" fill="none" stroke="black"/><path d="M 440,258 L 4 <path d="M 328,240 L 352,240" fill="none" stroke="black"/>
64,258" fill="none" stroke="black"/> <path d="M 440,254 L 464,254" fill="none" stroke="black"/>
<path d="M 480,254 L 504,254" fill="none" stroke="black"/><path d="M 480,258 L 5 <path d="M 440,258 L 464,258" fill="none" stroke="black"/>
04,258" fill="none" stroke="black"/> <path d="M 480,254 L 504,254" fill="none" stroke="black"/>
<path d="M 88,272 L 104,272" fill="none" stroke="black"/> <path d="M 480,258 L 504,258" fill="none" stroke="black"/>
<path d="M 128,272 L 144,272" fill="none" stroke="black"/> <path d="M 88,272 L 104,272" fill="none" stroke="black"/>
<path d="M 344,272 L 360,272" fill="none" stroke="black"/> <path d="M 128,272 L 144,272" fill="none" stroke="black"/>
<path d="M 440,302 L 464,302" fill="none" stroke="black"/><path d="M 440,306 L 4 <path d="M 344,272 L 360,272" fill="none" stroke="black"/>
64,306" fill="none" stroke="black"/> <path d="M 440,302 L 464,302" fill="none" stroke="black"/>
<path d="M 480,302 L 504,302" fill="none" stroke="black"/><path d="M 480,306 L 5 <path d="M 440,306 L 464,306" fill="none" stroke="black"/>
04,306" fill="none" stroke="black"/> <path d="M 480,302 L 504,302" fill="none" stroke="black"/>
<path d="M 440,350 L 464,350" fill="none" stroke="black"/><path d="M 440,354 L 4 <path d="M 480,306 L 504,306" fill="none" stroke="black"/>
64,354" fill="none" stroke="black"/> <path d="M 440,350 L 464,350" fill="none" stroke="black"/>
<path d="M 480,350 L 504,350" fill="none" stroke="black"/><path d="M 480,354 L 5 <path d="M 440,354 L 464,354" fill="none" stroke="black"/>
04,354" fill="none" stroke="black"/> <path d="M 480,350 L 504,350" fill="none" stroke="black"/>
<path d="M 512,384 L 568,384" fill="none" stroke="black"/> <path d="M 480,354 L 504,354" fill="none" stroke="black"/>
<path d="M 80,400 L 104,400" fill="none" stroke="black"/> <path d="M 512,384 L 568,384" fill="none" stroke="black"/>
<path d="M 128,400 L 144,400" fill="none" stroke="black"/> <path d="M 80,400 L 104,400" fill="none" stroke="black"/>
<path d="M 328,400 L 352,400" fill="none" stroke="black"/> <path d="M 128,400 L 144,400" fill="none" stroke="black"/>
<path d="M 88,432 L 104,432" fill="none" stroke="black"/> <path d="M 328,400 L 352,400" fill="none" stroke="black"/>
<path d="M 128,432 L 168,432" fill="none" stroke="black"/> <path d="M 88,432 L 104,432" fill="none" stroke="black"/>
<path d="M 288,432 L 360,432" fill="none" stroke="black"/> <path d="M 128,432 L 168,432" fill="none" stroke="black"/>
<path d="M 528,432 L 552,432" fill="none" stroke="black"/> <path d="M 288,432 L 360,432" fill="none" stroke="black"/>
<path d="M 480,464 L 552,464" fill="none" stroke="black"/> <path d="M 528,432 L 552,432" fill="none" stroke="black"/>
<path d="M 80,480 L 104,480" fill="none" stroke="black"/> <path d="M 480,464 L 552,464" fill="none" stroke="black"/>
<path d="M 128,480 L 144,480" fill="none" stroke="black"/> <path d="M 80,480 L 104,480" fill="none" stroke="black"/>
<path d="M 248,480 L 472,480" fill="none" stroke="black"/> <path d="M 128,480 L 144,480" fill="none" stroke="black"/>
<path d="M 88,512 L 104,512" fill="none" stroke="black"/> <path d="M 248,480 L 472,480" fill="none" stroke="black"/>
<path d="M 128,512 L 144,512" fill="none" stroke="black"/> <path d="M 88,512 L 104,512" fill="none" stroke="black"/>
<path d="M 264,512 L 480,512" fill="none" stroke="black"/> <path d="M 128,512 L 144,512" fill="none" stroke="black"/>
<path d="M 480,528 L 552,528" fill="none" stroke="black"/> <path d="M 264,512 L 480,512" fill="none" stroke="black"/>
<path d="M 8,544 L 80,544" fill="none" stroke="black"/> <path d="M 480,528 L 552,528" fill="none" stroke="black"/>
<path d="M 360,544 L 432,544" fill="none" stroke="black"/> <path d="M 8,544 L 80,544" fill="none" stroke="black"/>
<path d="M 528,32 C 519.16936,32 512,39.16936 512,48" fill="none" stroke="black" <path d="M 360,544 L 432,544" fill="none" stroke="black"/>
/> <path d="M 528,32 C 519.16936,32 512,39.16936 512,48" fill="no
<path d="M 552,32 C 560.83064,32 568,39.16936 568,48" fill="none" stroke="black" ne" stroke="black"/>
/> <path d="M 552,32 C 560.83064,32 568,39.16936 568,48" fill="no
<path d="M 528,432 C 519.16936,432 512,424.83064 512,416" fill="none" stroke="bl ne" stroke="black"/>
ack"/> <path d="M 528,432 C 519.16936,432 512,424.83064 512,416" fill
<path d="M 552,432 C 560.83064,432 568,424.83064 568,416" fill="none" stroke="bl ="none" stroke="black"/>
ack"/> <path d="M 552,432 C 560.83064,432 568,424.83064 568,416" fill
<polygon class="arrowhead" points="512,352 500,346.4 500,357.6" fill="black" tra ="none" stroke="black"/>
nsform="rotate(0,504,352)"/> <polygon class="arrowhead" points="512,352 500,346.4 500,357.6
<polygon class="arrowhead" points="512,304 500,298.4 500,309.6" fill="black" tra " fill="black" transform="rotate(0,504,352)"/>
nsform="rotate(0,504,304)"/> <polygon class="arrowhead" points="512,304 500,298.4 500,309.6
<polygon class="arrowhead" points="512,256 500,250.4 500,261.6" fill="black" tra " fill="black" transform="rotate(0,504,304)"/>
nsform="rotate(0,504,256)"/> <polygon class="arrowhead" points="512,256 500,250.4 500,261.6
<polygon class="arrowhead" points="512,208 500,202.4 500,213.6" fill="black" tra " fill="black" transform="rotate(0,504,256)"/>
nsform="rotate(0,504,208)"/> <polygon class="arrowhead" points="512,208 500,202.4 500,213.6
<polygon class="arrowhead" points="512,128 500,122.4 500,133.6" fill="black" tra " fill="black" transform="rotate(0,504,208)"/>
nsform="rotate(0,504,128)"/> <polygon class="arrowhead" points="512,128 500,122.4 500,133.6
<polygon class="arrowhead" points="480,480 468,474.4 468,485.6" fill="black" tra " fill="black" transform="rotate(0,504,128)"/>
nsform="rotate(0,472,480)"/> <polygon class="arrowhead" points="480,480 468,474.4 468,485.6
<polygon class="arrowhead" points="448,352 436,346.4 436,357.6" fill="black" tra " fill="black" transform="rotate(0,472,480)"/>
nsform="rotate(180,440,352)"/> <polygon class="arrowhead" points="448,352 436,346.4 436,357.6
<polygon class="arrowhead" points="448,304 436,298.4 436,309.6" fill="black" tra " fill="black" transform="rotate(180,440,352)"/>
nsform="rotate(180,440,304)"/> <polygon class="arrowhead" points="448,304 436,298.4 436,309.6
<polygon class="arrowhead" points="448,256 436,250.4 436,261.6" fill="black" tra " fill="black" transform="rotate(180,440,304)"/>
nsform="rotate(180,440,256)"/> <polygon class="arrowhead" points="448,256 436,250.4 436,261.6
<polygon class="arrowhead" points="448,208 436,202.4 436,213.6" fill="black" tra " fill="black" transform="rotate(180,440,256)"/>
nsform="rotate(180,440,208)"/> <polygon class="arrowhead" points="448,208 436,202.4 436,213.6
<polygon class="arrowhead" points="448,160 436,154.4 436,165.6" fill="black" tra " fill="black" transform="rotate(180,440,208)"/>
nsform="rotate(180,440,160)"/> <polygon class="arrowhead" points="448,160 436,154.4 436,165.6
<polygon class="arrowhead" points="360,400 348,394.4 348,405.6" fill="black" tra " fill="black" transform="rotate(180,440,160)"/>
nsform="rotate(0,352,400)"/> <polygon class="arrowhead" points="360,400 348,394.4 348,405.6
<polygon class="arrowhead" points="360,240 348,234.4 348,245.6" fill="black" tra " fill="black" transform="rotate(0,352,400)"/>
nsform="rotate(0,352,240)"/> <polygon class="arrowhead" points="360,240 348,234.4 348,245.6
<polygon class="arrowhead" points="360,64 348,58.4 348,69.6" fill="black" transf " fill="black" transform="rotate(0,352,240)"/>
orm="rotate(0,352,64)"/> <polygon class="arrowhead" points="360,64 348,58.4 348,69.6" f
<polygon class="arrowhead" points="96,512 84,506.4 84,517.6" fill="black" transf ill="black" transform="rotate(0,352,64)"/>
orm="rotate(180,88,512)"/> <polygon class="arrowhead" points="96,512 84,506.4 84,517.6" f
<polygon class="arrowhead" points="96,432 84,426.4 84,437.6" fill="black" transf ill="black" transform="rotate(180,88,512)"/>
orm="rotate(180,88,432)"/> <polygon class="arrowhead" points="96,432 84,426.4 84,437.6" f
<polygon class="arrowhead" points="96,272 84,266.4 84,277.6" fill="black" transf ill="black" transform="rotate(180,88,432)"/>
orm="rotate(180,88,272)"/> <polygon class="arrowhead" points="96,272 84,266.4 84,277.6" f
<polygon class="arrowhead" points="96,96 84,90.4 84,101.6" fill="black" transfor ill="black" transform="rotate(180,88,272)"/>
m="rotate(180,88,96)"/> <polygon class="arrowhead" points="96,96 84,90.4 84,101.6" fil
<g class="text"> l="black" transform="rotate(180,88,96)"/>
<text x="44" y="52">Client</text> <g class="text">
<text x="396" y="52">AS</text> <text x="44" y="52">Client</text>
<text x="536" y="52">End</text> <text x="396" y="52">AS</text>
<text x="44" y="68">Instance</text> <text x="536" y="52">End</text>
<text x="112" y="68">1</text> <text x="44" y="68">Instance</text>
<text x="184" y="68">Request</text> <text x="112" y="68">1</text>
<text x="244" y="68">Access</text> <text x="184" y="68">Request</text>
<text x="540" y="68">User</text> <text x="244" y="68">Access</text>
<text x="112" y="100">2</text> <text x="540" y="68">User</text>
<text x="192" y="100">Interaction</text> <text x="112" y="100">2</text>
<text x="268" y="100">Needed</text> <text x="192" y="100">Interaction</text>
<text x="112" y="132">3</text> <text x="268" y="100">Needed</text>
<text x="192" y="132">Display</text> <text x="112" y="132">3</text>
<text x="244" y="132">User</text> <text x="192" y="132">Display</text>
<text x="284" y="132">Code</text> <text x="244" y="132">User</text>
<text x="472" y="164">4</text> <text x="284" y="132">Code</text>
<text x="452" y="180">Open</text> <text x="472" y="164">4</text>
<text x="488" y="180">URI</text> <text x="452" y="180">Open</text>
<text x="472" y="212">5</text> <text x="488" y="180">URI</text>
<text x="540" y="212">RO</text> <text x="472" y="212">5</text>
<text x="472" y="228">AuthN</text> <text x="540" y="212">RO</text>
<text x="112" y="244">9</text> <text x="472" y="228">AuthN</text>
<text x="188" y="244">Continue</text> <text x="112" y="244">9</text>
<text x="256" y="244">Request</text> <text x="188" y="244">Continue</text>
<text x="304" y="244">(A)</text> <text x="256" y="244">Request</text>
<text x="472" y="260">6</text> <text x="304" y="244">(A)</text>
<text x="116" y="276">10</text> <text x="472" y="260">6</text>
<text x="168" y="276">Not</text> <text x="116" y="276">10</text>
<text x="200" y="276">Yet</text> <text x="168" y="276">Not</text>
<text x="248" y="276">Granted</text> <text x="200" y="276">Yet</text>
<text x="308" y="276">(Wait)</text> <text x="248" y="276">Granted</text>
<text x="468" y="276">Code</text> <text x="308" y="276">(Wait)</text>
<text x="472" y="308">7</text> <text x="468" y="276">Code</text>
<text x="472" y="324">AuthZ</text> <text x="472" y="308">7</text>
<text x="472" y="356">8</text> <text x="472" y="324">AuthZ</text>
<text x="468" y="372">Complete</text> <text x="472" y="356">8</text>
<text x="116" y="404">11</text> <text x="468" y="372">Complete</text>
<text x="188" y="404">Continue</text> <text x="116" y="404">11</text>
<text x="256" y="404">Request</text> <text x="188" y="404">Continue</text>
<text x="304" y="404">(B)</text> <text x="256" y="404">Request</text>
<text x="536" y="404">End</text> <text x="304" y="404">(B)</text>
<text x="540" y="420">User</text> <text x="536" y="404">End</text>
<text x="116" y="436">12</text> <text x="540" y="420">User</text>
<text x="200" y="436">Grant</text> <text x="116" y="436">12</text>
<text x="252" y="436">Access</text> <text x="200" y="436">Grant</text>
<text x="116" y="484">13</text> <text x="252" y="436">Access</text>
<text x="180" y="484">Access</text> <text x="116" y="484">13</text>
<text x="224" y="484">API</text> <text x="180" y="484">Access</text>
<text x="516" y="484">RS</text> <text x="224" y="484">API</text>
<text x="360" y="500">|</text> <text x="516" y="484">RS</text>
<text x="432" y="500">|</text> <text x="360" y="500">|</text>
<text x="116" y="516">14</text> <text x="432" y="500">|</text>
<text x="168" y="516">API</text> <text x="116" y="516">14</text>
<text x="220" y="516">Response</text> <text x="168" y="516">API</text>
</g> <text x="220" y="516">Response</text>
</svg> </g>
</artwork><artwork type="ascii-art"><![CDATA[ </svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
+--------+ +--------+ .----. +--------+ +--------+ .----.
| Client | | AS | | End | | Client | | AS | | End |
|Instance+--(1)--- Request Access --------->| | | User | |Instance+--(1)--- Request Access --------->| | | User |
| | | | | | | | | | | |
| |<-(2)-- Interaction Needed -------+ | | | | |<-(2)-- Interaction Needed -------+ | | |
| | | | | | | | | | | |
| +==(3)==== Display User Code ========================>| | | +==(3)==== Display User Code ========================>| |
| | | | | | | | | | | |
| | | |<==(4)===+ | | | | |<==(4)===+ |
| | | |Open URI | | | | | |Open URI | |
skipping to change at line 1192 skipping to change at line 1244
| +--(11)-- Continue Request (B) --->| | | End | | +--(11)-- Continue Request (B) --->| | | End |
| | | | | User | | | | | | User |
| |<-(12)----- Grant Access ---------+ | `----` | |<-(12)----- Grant Access ---------+ | `----`
| | | | | | | |
| | | | +--------+ | | | | +--------+
| +--(13)-- Access API ---------------------------->| RS | | +--(13)-- Access API ---------------------------->| RS |
| | | | | | | | | | | |
| |<-(14)-- API Response ---------------------------+ | | |<-(14)-- API Response ---------------------------+ |
| | | | +--------+ | | | | +--------+
+--------+ +--------+ +--------+ +--------+
]]></artwork></artset></figure> ]]></artwork>
</artset>
<t><list style="numbers"> </figure>
<t>The client instance <xref target="request">requests access to the resource< <ul spacing="normal"><li>
/xref>. The client instance indicates that <t>(1) The client instance requests access to the resource (<xref
it can <xref target="request-interact-usercode">display a user code</xref>.</t> target="request"> </xref>). The client instance indicates that
<t>The AS determines that interaction is needed and <xref target="response">re it can display a user code (<xref target="request-interact-usercode"> </xref>).
sponds</xref> with </t>
a <xref target="response-interact-usercode">user code to communicate to the use </li>
r</xref>. <li>
<t>(2) The AS determines that interaction is needed and responds (
<xref target="response"> </xref>) with
a user code to communicate to the user (<xref target="response-interact-usercod
e"> </xref>).
The AS also includes information the client instance will need to The AS also includes information the client instance will need to
<xref target="response-continue">continue the request</xref> in (8) and (10). T he AS associates this continue the request (<xref target="response-continue"> </xref>) in (8) and (10 ). The AS associates this
continuation information with an ongoing request that will be referenced in (4) , (6), (8), and (10).</t> continuation information with an ongoing request that will be referenced in (4) , (6), (8), and (10).</t>
<t>The client instance stores the continuation information from (2) for use in </li>
(8) and (10). The client instance <li>
then <xref target="interaction-usercode">communicates the code to the user</xre <t>(3) The client instance stores the continuation information fro
f> given by the AS in (2).</t> m (2) for use in (8) and (10). The client instance
<t>The users directs their browser to the user code URI. This URI is stable an then communicates the code to the user (<xref target="interaction-usercode"> </
d xref>) given by the AS in (2).</t>
</li>
<li>
<t>(4) The user directs their browser to the user code URI. This U
RI is stable and
can be communicated via the client software's documentation, the AS documentati on, or can be communicated via the client software's documentation, the AS documentati on, or
the client software itself. Since it is assumed that the RO will interact the client software itself. Since it is assumed that the RO will interact
with the AS through a secondary device, the client instance does not provide a mechanism to with the AS through a secondary device, the client instance does not provide a mechanism to
launch the RO's browser at this URI.</t> launch the RO's browser at this URI.</t>
<t>The end user authenticates at the AS, taking on the role of the RO.</t> </li>
<t>The RO enters the code communicated in (3) to the AS. The AS validates this <li>
code <t>(5) The end user authenticates at the AS, taking on the role of
the RO.</t>
</li>
<li>
<t>(6) The RO enters the code communicated in (3) to the AS. The A
S validates this code
against a current request in process.</t> against a current request in process.</t>
<t>As the RO, the user authorizes the pending request from the client instance </li>
.</t> <li>
<t>When the AS is done interacting with the user, the AS <t>(7) As the RO, the user authorizes the pending request from the
client instance.</t>
</li>
<li>
<t>(8) When the AS is done interacting with the user, the AS
indicates to the RO that the request has been completed.</t> indicates to the RO that the request has been completed.</t>
<t>Meanwhile, the client instance loads the continuation information stored at </li>
(3) and <li>
<xref target="continue-request">continues the request</xref>. The AS determines <t>(9) Meanwhile, the client instance loads the continuation infor
which mation stored at (3) and
continues the request (<xref target="continue-request"> </xref>). The AS determ
ines which
ongoing access request is referenced here and checks its state.</t> ongoing access request is referenced here and checks its state.</t>
<t>If the access request has not yet been authorized by the RO in (6), </li>
the AS responds to the client instance to <xref target="response-continue">conti <li>
nue the request</xref> <t>(10) If the access request has not yet been authorized by the R
O in (6),
the AS responds to the client instance to continue the request (<xref target="re
sponse-continue"> </xref>)
at a future time through additional polled continuation requests. This response can include at a future time through additional polled continuation requests. This response can include
updated continuation information as well as information regarding how long the updated continuation information as well as information regarding how long the
client instance should wait before calling again. The client instance replaces i ts stored client instance should wait before calling again. The client instance replaces i ts stored
continuation information from the previous response (2). continuation information from the previous response (2).
Note that the AS may need to determine that the RO has not approved Note that the AS may need to determine that the RO has not approved
the request in a sufficient amount of time and return an appropriate the request in a sufficient amount of time and return an appropriate
error to the client instance.</t> error to the client instance.</t>
<t>The client instance continues to <xref target="continue-poll">poll the AS</ </li>
xref> with the new <li>
<t>(11) The client instance continues to poll the AS (<xref target
="continue-poll"> </xref>) with the new
continuation information in (9).</t> continuation information in (9).</t>
<t>If the request has been authorized, the AS grants access to the information </li>
in the form of <xref target="response-token">access tokens</xref> and <li>
<xref target="response-subject">direct subject information</xref> to the client <t>(12) If the request has been authorized, the AS grants access t
instance.</t> o the information
<t>The client instance <xref target="use-access-token">uses the access token</ in the form of access tokens (<xref target="response-token"> </xref>) and
xref> to call the RS.</t> direct subject information (<xref target="response-subject"> </xref>) to the cli
<t>The RS validates the access token and returns an appropriate response for t ent instance.</t>
he </li>
<li>
<t>(13) The client instance uses the access token (<xref target="u
se-access-token"> </xref>) to call the RS.</t>
</li>
<li>
<t>(14) The RS validates the access token and returns an appropria
te response for the
API.</t> API.</t>
</list></t> </li>
</ul>
<t>An example set of protocol messages for this method can be found in <xref tar <t>An example set of protocol messages for this method can be found in
get="example-device"/>.</t> <xref target="example-device"/>.</t>
</section>
</section> <section anchor="sequence-async">
<section anchor="sequence-async"><name>Asynchronous Authorization</name> <name>Asynchronous Authorization</name>
<t>In this example flow, the end user and RO roles are fulfilled by di
<t>In this example flow, the end user and RO roles are fulfilled by different pa fferent parties, and
rties, and
the RO does not interact with the client instance. The AS reaches out asynchrono usly to the RO the RO does not interact with the client instance. The AS reaches out asynchrono usly to the RO
during the request process to gather the RO's authorization for the client insta nce's request. during the request process to gather the RO's authorization for the client insta nce's request.
The client instance polls the AS while it is waiting for the RO to authorize the request.</t> The client instance polls the AS while it is waiting for the RO to authorize the request.</t>
<figure>
<figure title="Figure 6: Diagram of an asynchronous authorization process, with <name>Diagram of an Asynchronous Authorization Process, with No End-
no end user interaction"><artset><artwork type="svg"><svg xmlns="http://www.w3. User Interaction</name>
org/2000/svg" version="1.1" height="416" width="576" viewBox="0 0 576 416" class <artset>
="diagram" text-anchor="middle" font-family="monospace" font-size="13px" stroke- <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" versio
linecap="round"> n="1.1" height="416" width="576" viewBox="0 0 576 416" class="diagram" text-anch
<path d="M 8,32 L 8,400" fill="none" stroke="black"/> or="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 80,32 L 80,400" fill="none" stroke="black"/> <path d="M 8,32 L 8,400" fill="none" stroke="black"/>
<path d="M 360,32 L 360,328" fill="none" stroke="black"/> <path d="M 80,32 L 80,400" fill="none" stroke="black"/>
<path d="M 360,376 L 360,400" fill="none" stroke="black"/> <path d="M 360,32 L 360,328" fill="none" stroke="black"/>
<path d="M 432,32 L 432,328" fill="none" stroke="black"/> <path d="M 360,376 L 360,400" fill="none" stroke="black"/>
<path d="M 432,376 L 432,400" fill="none" stroke="black"/> <path d="M 432,32 L 432,328" fill="none" stroke="black"/>
<path d="M 480,320 L 480,384" fill="none" stroke="black"/> <path d="M 432,376 L 432,400" fill="none" stroke="black"/>
<path d="M 512,48 L 512,240" fill="none" stroke="black"/> <path d="M 480,320 L 480,384" fill="none" stroke="black"/>
<path d="M 552,320 L 552,384" fill="none" stroke="black"/> <path d="M 512,48 L 512,240" fill="none" stroke="black"/>
<path d="M 568,48 L 568,240" fill="none" stroke="black"/> <path d="M 552,320 L 552,384" fill="none" stroke="black"/>
<path d="M 8,32 L 80,32" fill="none" stroke="black"/> <path d="M 568,48 L 568,240" fill="none" stroke="black"/>
<path d="M 360,32 L 432,32" fill="none" stroke="black"/> <path d="M 8,32 L 80,32" fill="none" stroke="black"/>
<path d="M 528,32 L 552,32" fill="none" stroke="black"/> <path d="M 360,32 L 432,32" fill="none" stroke="black"/>
<path d="M 80,64 L 104,64" fill="none" stroke="black"/> <path d="M 528,32 L 552,32" fill="none" stroke="black"/>
<path d="M 120,64 L 144,64" fill="none" stroke="black"/> <path d="M 80,64 L 104,64" fill="none" stroke="black"/>
<path d="M 280,64 L 352,64" fill="none" stroke="black"/> <path d="M 120,64 L 144,64" fill="none" stroke="black"/>
<path d="M 88,96 L 104,96" fill="none" stroke="black"/> <path d="M 280,64 L 352,64" fill="none" stroke="black"/>
<path d="M 120,96 L 136,96" fill="none" stroke="black"/> <path d="M 88,96 L 104,96" fill="none" stroke="black"/>
<path d="M 336,96 L 360,96" fill="none" stroke="black"/> <path d="M 120,96 L 136,96" fill="none" stroke="black"/>
<path d="M 440,110 L 464,110" fill="none" stroke="black"/><path d="M 440,114 L 4 <path d="M 336,96 L 360,96" fill="none" stroke="black"/>
64,114" fill="none" stroke="black"/> <path d="M 440,110 L 464,110" fill="none" stroke="black"/>
<path d="M 480,110 L 504,110" fill="none" stroke="black"/><path d="M 480,114 L 5 <path d="M 440,114 L 464,114" fill="none" stroke="black"/>
04,114" fill="none" stroke="black"/> <path d="M 480,110 L 504,110" fill="none" stroke="black"/>
<path d="M 80,144 L 104,144" fill="none" stroke="black"/> <path d="M 480,114 L 504,114" fill="none" stroke="black"/>
<path d="M 120,144 L 144,144" fill="none" stroke="black"/> <path d="M 80,144 L 104,144" fill="none" stroke="black"/>
<path d="M 328,144 L 352,144" fill="none" stroke="black"/> <path d="M 120,144 L 144,144" fill="none" stroke="black"/>
<path d="M 440,158 L 464,158" fill="none" stroke="black"/><path d="M 440,162 L 4 <path d="M 328,144 L 352,144" fill="none" stroke="black"/>
64,162" fill="none" stroke="black"/> <path d="M 440,158 L 464,158" fill="none" stroke="black"/>
<path d="M 480,158 L 504,158" fill="none" stroke="black"/><path d="M 480,162 L 5 <path d="M 440,162 L 464,162" fill="none" stroke="black"/>
04,162" fill="none" stroke="black"/> <path d="M 480,158 L 504,158" fill="none" stroke="black"/>
<path d="M 88,176 L 104,176" fill="none" stroke="black"/> <path d="M 480,162 L 504,162" fill="none" stroke="black"/>
<path d="M 120,176 L 136,176" fill="none" stroke="black"/> <path d="M 88,176 L 104,176" fill="none" stroke="black"/>
<path d="M 336,176 L 360,176" fill="none" stroke="black"/> <path d="M 120,176 L 136,176" fill="none" stroke="black"/>
<path d="M 440,206 L 464,206" fill="none" stroke="black"/><path d="M 440,210 L 4 <path d="M 336,176 L 360,176" fill="none" stroke="black"/>
64,210" fill="none" stroke="black"/> <path d="M 440,206 L 464,206" fill="none" stroke="black"/>
<path d="M 480,206 L 504,206" fill="none" stroke="black"/><path d="M 480,210 L 5 <path d="M 440,210 L 464,210" fill="none" stroke="black"/>
04,210" fill="none" stroke="black"/> <path d="M 480,206 L 504,206" fill="none" stroke="black"/>
<path d="M 80,256 L 104,256" fill="none" stroke="black"/> <path d="M 480,210 L 504,210" fill="none" stroke="black"/>
<path d="M 120,256 L 144,256" fill="none" stroke="black"/> <path d="M 80,256 L 104,256" fill="none" stroke="black"/>
<path d="M 328,256 L 352,256" fill="none" stroke="black"/> <path d="M 120,256 L 144,256" fill="none" stroke="black"/>
<path d="M 528,256 L 552,256" fill="none" stroke="black"/> <path d="M 328,256 L 352,256" fill="none" stroke="black"/>
<path d="M 88,288 L 104,288" fill="none" stroke="black"/> <path d="M 528,256 L 552,256" fill="none" stroke="black"/>
<path d="M 120,288 L 168,288" fill="none" stroke="black"/> <path d="M 88,288 L 104,288" fill="none" stroke="black"/>
<path d="M 288,288 L 360,288" fill="none" stroke="black"/> <path d="M 120,288 L 168,288" fill="none" stroke="black"/>
<path d="M 480,320 L 552,320" fill="none" stroke="black"/> <path d="M 288,288 L 360,288" fill="none" stroke="black"/>
<path d="M 80,336 L 104,336" fill="none" stroke="black"/> <path d="M 480,320 L 552,320" fill="none" stroke="black"/>
<path d="M 128,336 L 144,336" fill="none" stroke="black"/> <path d="M 80,336 L 104,336" fill="none" stroke="black"/>
<path d="M 248,336 L 472,336" fill="none" stroke="black"/> <path d="M 128,336 L 144,336" fill="none" stroke="black"/>
<path d="M 88,368 L 104,368" fill="none" stroke="black"/> <path d="M 248,336 L 472,336" fill="none" stroke="black"/>
<path d="M 128,368 L 144,368" fill="none" stroke="black"/> <path d="M 88,368 L 104,368" fill="none" stroke="black"/>
<path d="M 264,368 L 480,368" fill="none" stroke="black"/> <path d="M 128,368 L 144,368" fill="none" stroke="black"/>
<path d="M 480,384 L 552,384" fill="none" stroke="black"/> <path d="M 264,368 L 480,368" fill="none" stroke="black"/>
<path d="M 8,400 L 80,400" fill="none" stroke="black"/> <path d="M 480,384 L 552,384" fill="none" stroke="black"/>
<path d="M 360,400 L 432,400" fill="none" stroke="black"/> <path d="M 8,400 L 80,400" fill="none" stroke="black"/>
<path d="M 528,32 C 519.16936,32 512,39.16936 512,48" fill="none" stroke="black" <path d="M 360,400 L 432,400" fill="none" stroke="black"/>
/> <path d="M 528,32 C 519.16936,32 512,39.16936 512,48" fill="no
<path d="M 552,32 C 560.83064,32 568,39.16936 568,48" fill="none" stroke="black" ne" stroke="black"/>
/> <path d="M 552,32 C 560.83064,32 568,39.16936 568,48" fill="no
<path d="M 528,256 C 519.16936,256 512,248.83064 512,240" fill="none" stroke="bl ne" stroke="black"/>
ack"/> <path d="M 528,256 C 519.16936,256 512,248.83064 512,240" fill
<path d="M 552,256 C 560.83064,256 568,248.83064 568,240" fill="none" stroke="bl ="none" stroke="black"/>
ack"/> <path d="M 552,256 C 560.83064,256 568,248.83064 568,240" fill
<polygon class="arrowhead" points="512,208 500,202.4 500,213.6" fill="black" tra ="none" stroke="black"/>
nsform="rotate(0,504,208)"/> <polygon class="arrowhead" points="512,208 500,202.4 500,213.6
<polygon class="arrowhead" points="512,160 500,154.4 500,165.6" fill="black" tra " fill="black" transform="rotate(0,504,208)"/>
nsform="rotate(0,504,160)"/> <polygon class="arrowhead" points="512,160 500,154.4 500,165.6
<polygon class="arrowhead" points="512,112 500,106.4 500,117.6" fill="black" tra " fill="black" transform="rotate(0,504,160)"/>
nsform="rotate(0,504,112)"/> <polygon class="arrowhead" points="512,112 500,106.4 500,117.6
<polygon class="arrowhead" points="480,336 468,330.4 468,341.6" fill="black" tra " fill="black" transform="rotate(0,504,112)"/>
nsform="rotate(0,472,336)"/> <polygon class="arrowhead" points="480,336 468,330.4 468,341.6
<polygon class="arrowhead" points="448,208 436,202.4 436,213.6" fill="black" tra " fill="black" transform="rotate(0,472,336)"/>
nsform="rotate(180,440,208)"/> <polygon class="arrowhead" points="448,208 436,202.4 436,213.6
<polygon class="arrowhead" points="448,160 436,154.4 436,165.6" fill="black" tra " fill="black" transform="rotate(180,440,208)"/>
nsform="rotate(180,440,160)"/> <polygon class="arrowhead" points="448,160 436,154.4 436,165.6
<polygon class="arrowhead" points="448,112 436,106.4 436,117.6" fill="black" tra " fill="black" transform="rotate(180,440,160)"/>
nsform="rotate(180,440,112)"/> <polygon class="arrowhead" points="448,112 436,106.4 436,117.6
<polygon class="arrowhead" points="360,256 348,250.4 348,261.6" fill="black" tra " fill="black" transform="rotate(180,440,112)"/>
nsform="rotate(0,352,256)"/> <polygon class="arrowhead" points="360,256 348,250.4 348,261.6
<polygon class="arrowhead" points="360,144 348,138.4 348,149.6" fill="black" tra " fill="black" transform="rotate(0,352,256)"/>
nsform="rotate(0,352,144)"/> <polygon class="arrowhead" points="360,144 348,138.4 348,149.6
<polygon class="arrowhead" points="360,64 348,58.4 348,69.6" fill="black" transf " fill="black" transform="rotate(0,352,144)"/>
orm="rotate(0,352,64)"/> <polygon class="arrowhead" points="360,64 348,58.4 348,69.6" f
<polygon class="arrowhead" points="96,368 84,362.4 84,373.6" fill="black" transf ill="black" transform="rotate(0,352,64)"/>
orm="rotate(180,88,368)"/> <polygon class="arrowhead" points="96,368 84,362.4 84,373.6" f
<polygon class="arrowhead" points="96,288 84,282.4 84,293.6" fill="black" transf ill="black" transform="rotate(180,88,368)"/>
orm="rotate(180,88,288)"/> <polygon class="arrowhead" points="96,288 84,282.4 84,293.6" f
<polygon class="arrowhead" points="96,176 84,170.4 84,181.6" fill="black" transf ill="black" transform="rotate(180,88,288)"/>
orm="rotate(180,88,176)"/> <polygon class="arrowhead" points="96,176 84,170.4 84,181.6" f
<polygon class="arrowhead" points="96,96 84,90.4 84,101.6" fill="black" transfor ill="black" transform="rotate(180,88,176)"/>
m="rotate(180,88,96)"/> <polygon class="arrowhead" points="96,96 84,90.4 84,101.6" fil
<g class="text"> l="black" transform="rotate(180,88,96)"/>
<text x="44" y="52">Client</text> <g class="text">
<text x="396" y="52">AS</text> <text x="44" y="52">Client</text>
<text x="540" y="52">RO</text> <text x="396" y="52">AS</text>
<text x="44" y="68">Instance</text> <text x="540" y="52">RO</text>
<text x="112" y="68">1</text> <text x="44" y="68">Instance</text>
<text x="184" y="68">Request</text> <text x="112" y="68">1</text>
<text x="244" y="68">Access</text> <text x="184" y="68">Request</text>
<text x="112" y="100">2</text> <text x="244" y="68">Access</text>
<text x="160" y="100">Not</text> <text x="112" y="100">2</text>
<text x="192" y="100">Yet</text> <text x="160" y="100">Not</text>
<text x="240" y="100">Granted</text> <text x="192" y="100">Yet</text>
<text x="300" y="100">(Wait)</text> <text x="240" y="100">Granted</text>
<text x="472" y="116">3</text> <text x="300" y="100">(Wait)</text>
<text x="472" y="132">AuthN</text> <text x="472" y="116">3</text>
<text x="112" y="148">6</text> <text x="472" y="132">AuthN</text>
<text x="188" y="148">Continue</text> <text x="112" y="148">6</text>
<text x="256" y="148">Request</text> <text x="188" y="148">Continue</text>
<text x="304" y="148">(A)</text> <text x="256" y="148">Request</text>
<text x="472" y="164">4</text> <text x="304" y="148">(A)</text>
<text x="112" y="180">7</text> <text x="472" y="164">4</text>
<text x="160" y="180">Not</text> <text x="112" y="180">7</text>
<text x="192" y="180">Yet</text> <text x="160" y="180">Not</text>
<text x="240" y="180">Granted</text> <text x="192" y="180">Yet</text>
<text x="300" y="180">(Wait)</text> <text x="240" y="180">Granted</text>
<text x="472" y="180">AuthZ</text> <text x="300" y="180">(Wait)</text>
<text x="472" y="212">5</text> <text x="472" y="180">AuthZ</text>
<text x="472" y="228">Completed</text> <text x="472" y="212">5</text>
<text x="112" y="260">8</text> <text x="472" y="228">Completed</text>
<text x="188" y="260">Continue</text> <text x="112" y="260">8</text>
<text x="256" y="260">Request</text> <text x="188" y="260">Continue</text>
<text x="304" y="260">(B)</text> <text x="256" y="260">Request</text>
<text x="112" y="292">9</text> <text x="304" y="260">(B)</text>
<text x="200" y="292">Grant</text> <text x="112" y="292">9</text>
<text x="252" y="292">Access</text> <text x="200" y="292">Grant</text>
<text x="116" y="340">10</text> <text x="252" y="292">Access</text>
<text x="180" y="340">Access</text> <text x="116" y="340">10</text>
<text x="224" y="340">API</text> <text x="180" y="340">Access</text>
<text x="516" y="340">RS</text> <text x="224" y="340">API</text>
<text x="360" y="356">|</text> <text x="516" y="340">RS</text>
<text x="432" y="356">|</text> <text x="360" y="356">|</text>
<text x="116" y="372">11</text> <text x="432" y="356">|</text>
<text x="168" y="372">API</text> <text x="116" y="372">11</text>
<text x="220" y="372">Response</text> <text x="168" y="372">API</text>
</g> <text x="220" y="372">Response</text>
</svg> </g>
</artwork><artwork type="ascii-art"><![CDATA[ </svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
+--------+ +--------+ .----. +--------+ +--------+ .----.
| Client | | AS | | RO | | Client | | AS | | RO |
|Instance+--(1)--- Request Access --------->| | | | |Instance+--(1)--- Request Access --------->| | | |
| | | | | | | | | | | |
| |<-(2)-- Not Yet Granted (Wait) ---+ | | | | |<-(2)-- Not Yet Granted (Wait) ---+ | | |
| | | |<==(3)==>| | | | | |<==(3)==>| |
| | | | AuthN | | | | | | AuthN | |
| +--(6)--- Continue Request (A) --->| | | | | +--(6)--- Continue Request (A) --->| | | |
| | | |<==(4)==>| | | | | |<==(4)==>| |
| |<-(7)-- Not Yet Granted (Wait) ---+ | AuthZ | | | |<-(7)-- Not Yet Granted (Wait) ---+ | AuthZ | |
skipping to change at line 1385 skipping to change at line 1472
| +--(8)--- Continue Request (B) --->| | `----` | +--(8)--- Continue Request (B) --->| | `----`
| | | | | | | |
| |<-(9)------ Grant Access ---------+ | | |<-(9)------ Grant Access ---------+ |
| | | | | | | |
| | | | +--------+ | | | | +--------+
| +--(10)-- Access API ---------------------------->| RS | | +--(10)-- Access API ---------------------------->| RS |
| | | | | | | | | | | |
| |<-(11)-- API Response ---------------------------+ | | |<-(11)-- API Response ---------------------------+ |
| | | | +--------+ | | | | +--------+
+--------+ +--------+ +--------+ +--------+
]]></artwork></artset></figure> ]]></artwork>
</artset>
</figure>
<ul spacing="normal"><li>
<t><list style="numbers"> <t>(1) The client instance requests access to the resource (<xref tar
<t>The client instance <xref target="request">requests access to the resource< get="request"> </xref>). The client instance does not
/xref>. The client instance does not
send any interaction modes to the server, indicating that send any interaction modes to the server, indicating that
it does not expect to interact with the RO. The client instance can also signal it does not expect to interact with the RO. The client instance can also signal
which RO it requires authorization from, if known, by using the which RO it requires authorization from, if known, by using the
<xref target="request-subject">subject request</xref> and subject request field (<xref target="request-subject"> </xref>) and
<xref target="request-user">user request</xref> sections. It's also possible fo user request field (<xref target="request-user"> </xref>). It's also possible f
r the AS to determine which or the AS to determine which
RO needs to be contacted by the nature of what access is being requested.</t> RO needs to be contacted by the nature of what access is being requested.</t>
<t>The AS determines that interaction is needed, but the client instance canno </li>
t interact <li>
with the RO. The AS <xref target="response">responds</xref> with the informatio <t>(2) The AS determines that interaction is needed, but the clien
n the client instance t instance cannot interact
will need to <xref target="response-continue">continue the request</xref> in (6 with the RO. The AS responds (<xref target="response"> </xref>) with the inform
) and (8), including ation the client instance
will need to continue the request (<xref target="response-continue"> </xref>) i
n (6) and (8), including
a signal that the client instance should wait before checking the status of the request again. a signal that the client instance should wait before checking the status of the request again.
The AS associates this continuation information with an ongoing request that wi ll be The AS associates this continuation information with an ongoing request that wi ll be
referenced in (3), (4), (5), (6), and (8).</t> referenced in (3), (4), (5), (6), and (8).</t>
<t>The AS determines which RO to contact based on the request in (1), through </li>
a <li>
combination of the <xref target="request-user">user request</xref>, the <t>(3) The AS determines which RO to contact based on the request
<xref target="request-subject">subject request</xref>, the in (1), through a
<xref target="request-token">access request</xref>, and other policy informatio combination of the user request (<xref target="request-user"> </xref>), the
n. The AS subject request (<xref target="request-subject"> </xref>), the
access request (<xref target="request-token"> </xref>), and other policy inform
ation. The AS
contacts the RO and authenticates them.</t> contacts the RO and authenticates them.</t>
<t>The RO authorizes the pending request from the client instance.</t> </li>
<t>When the AS is done interacting with the RO, the AS <li>
<t>(4) The RO authorizes the pending request from the client insta
nce.</t>
</li>
<li>
<t>(5) When the AS is done interacting with the RO, the AS
indicates to the RO that the request has been completed.</t> indicates to the RO that the request has been completed.</t>
<t>Meanwhile, the client instance loads the continuation information stored at </li>
(2) and <li>
<xref target="continue-request">continues the request</xref>. The AS determines <t>(6) Meanwhile, the client instance loads the continuation infor
which mation stored at (2) and
continues the request (<xref target="continue-request"> </xref>). The AS determ
ines which
ongoing access request is referenced here and checks its state.</t> ongoing access request is referenced here and checks its state.</t>
<t>If the access request has not yet been authorized by the RO in (6), </li>
the AS responds to the client instance to <xref target="response-continue">cont <li>
inue the request</xref> <t>(7) If the access request has not yet been authorized by the RO
in (6),
the AS responds to the client instance to continue the request (<xref target="r
esponse-continue"> </xref>)
at a future time through additional polling. Note that this response is not at a future time through additional polling. Note that this response is not
an error message, since no error has yet occurred. This response can include an error message, since no error has yet occurred. This response can include
refreshed credentials as well as information regarding how long the refreshed credentials as well as information regarding how long the
client instance should wait before calling again. The client instance replaces its stored client instance should wait before calling again. The client instance replaces its stored
continuation information from the previous response (2). continuation information from the previous response (2).
Note that the AS may need to determine that the RO has not approved Note that the AS may need to determine that the RO has not approved
the request in a sufficient amount of time and return an appropriate the request in a sufficient amount of time and return an appropriate
error to the client instance.</t> error to the client instance.</t>
<t>The client instance continues to <xref target="continue-poll">poll the AS</ </li>
xref> with the new <li>
<t>(8) The client instance continues to poll the AS (<xref target=
"continue-poll"></xref>) with the new
continuation information from (7).</t> continuation information from (7).</t>
<t>If the request has been authorized, the AS grants access to the information </li>
in the form of <xref target="response-token">access tokens</xref> and <li>
<xref target="response-subject">direct subject information</xref> to the client <t>(9) If the request has been authorized, the AS grants access to
instance.</t> the information
<t>The client instance <xref target="use-access-token">uses the access token</ in the form of access tokens (<xref target="response-token"> </xref>) and
xref> to call the RS.</t> direct subject information (<xref target="response-subject"> </xref>) to the cl
<t>The RS validates the access token and returns an appropriate response for t ient instance.</t>
he </li>
<li>
<t>(10) The client instance uses the access token (<xref target="u
se-access-token"> </xref>) to call the RS.</t>
</li>
<li>
<t>(11) The RS validates the access token and returns an appropria
te response for the
API.</t> API.</t>
</list></t> </li>
</ul>
<t>An example set of protocol messages for this method can be found in <xref tar <t>An example set of protocol messages for this method can be found in
get="example-async"/>.</t> <xref target="example-async"/>.</t>
<t>Additional considerations for asynchronous interactions like this a
<t>Additional considerations for asynchronous interactions like this are discuss re discussed in
ed in
<xref target="security-async"/>.</t> <xref target="security-async"/>.</t>
</section>
</section> <section anchor="sequence-no-user">
<section anchor="sequence-no-user"><name>Software-only Authorization</name> <name>Software-Only Authorization</name>
<t>In this example flow, the AS policy allows the client instance to m
<t>In this example flow, the AS policy allows the client instance to make a call ake a call on its own behalf,
on its own behalf,
without the need for an RO to be involved at runtime to approve the decision. without the need for an RO to be involved at runtime to approve the decision.
Since there is no explicit RO, the client instance does not interact with an RO. </t> Since there is no explicit RO, the client instance does not interact with an RO. </t>
<figure>
<figure title="Figure 7: Diagram of a software-only authorization, with no end u <name>Diagram of a Software-Only Authorization, with No End User or
ser or explicit resource owner"><artset><artwork type="svg"><svg xmlns="http:// Explicit Resource Owner</name>
www.w3.org/2000/svg" version="1.1" height="208" width="488" viewBox="0 0 488 208 <artset>
" class="diagram" text-anchor="middle" font-family="monospace" font-size="13px" <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" versio
stroke-linecap="round"> n="1.1" height="208" width="488" viewBox="0 0 488 208" class="diagram" text-anch
<path d="M 8,32 L 8,192" fill="none" stroke="black"/> or="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 80,32 L 80,192" fill="none" stroke="black"/> <path d="M 8,32 L 8,192" fill="none" stroke="black"/>
<path d="M 312,32 L 312,120" fill="none" stroke="black"/> <path d="M 80,32 L 80,192" fill="none" stroke="black"/>
<path d="M 312,168 L 312,192" fill="none" stroke="black"/> <path d="M 312,32 L 312,120" fill="none" stroke="black"/>
<path d="M 384,32 L 384,120" fill="none" stroke="black"/> <path d="M 312,168 L 312,192" fill="none" stroke="black"/>
<path d="M 384,168 L 384,192" fill="none" stroke="black"/> <path d="M 384,32 L 384,120" fill="none" stroke="black"/>
<path d="M 408,112 L 408,176" fill="none" stroke="black"/> <path d="M 384,168 L 384,192" fill="none" stroke="black"/>
<path d="M 480,112 L 480,176" fill="none" stroke="black"/> <path d="M 408,112 L 408,176" fill="none" stroke="black"/>
<path d="M 8,32 L 80,32" fill="none" stroke="black"/> <path d="M 480,112 L 480,176" fill="none" stroke="black"/>
<path d="M 312,32 L 384,32" fill="none" stroke="black"/> <path d="M 8,32 L 80,32" fill="none" stroke="black"/>
<path d="M 80,64 L 104,64" fill="none" stroke="black"/> <path d="M 312,32 L 384,32" fill="none" stroke="black"/>
<path d="M 120,64 L 144,64" fill="none" stroke="black"/> <path d="M 80,64 L 104,64" fill="none" stroke="black"/>
<path d="M 280,64 L 304,64" fill="none" stroke="black"/> <path d="M 120,64 L 144,64" fill="none" stroke="black"/>
<path d="M 88,96 L 104,96" fill="none" stroke="black"/> <path d="M 280,64 L 304,64" fill="none" stroke="black"/>
<path d="M 120,96 L 152,96" fill="none" stroke="black"/> <path d="M 88,96 L 104,96" fill="none" stroke="black"/>
<path d="M 272,96 L 312,96" fill="none" stroke="black"/> <path d="M 120,96 L 152,96" fill="none" stroke="black"/>
<path d="M 408,112 L 480,112" fill="none" stroke="black"/> <path d="M 272,96 L 312,96" fill="none" stroke="black"/>
<path d="M 80,128 L 104,128" fill="none" stroke="black"/> <path d="M 408,112 L 480,112" fill="none" stroke="black"/>
<path d="M 120,128 L 144,128" fill="none" stroke="black"/> <path d="M 80,128 L 104,128" fill="none" stroke="black"/>
<path d="M 248,128 L 400,128" fill="none" stroke="black"/> <path d="M 120,128 L 144,128" fill="none" stroke="black"/>
<path d="M 88,160 L 104,160" fill="none" stroke="black"/> <path d="M 248,128 L 400,128" fill="none" stroke="black"/>
<path d="M 120,160 L 144,160" fill="none" stroke="black"/> <path d="M 88,160 L 104,160" fill="none" stroke="black"/>
<path d="M 264,160 L 408,160" fill="none" stroke="black"/> <path d="M 120,160 L 144,160" fill="none" stroke="black"/>
<path d="M 408,176 L 480,176" fill="none" stroke="black"/> <path d="M 264,160 L 408,160" fill="none" stroke="black"/>
<path d="M 8,192 L 80,192" fill="none" stroke="black"/> <path d="M 408,176 L 480,176" fill="none" stroke="black"/>
<path d="M 312,192 L 384,192" fill="none" stroke="black"/> <path d="M 8,192 L 80,192" fill="none" stroke="black"/>
<polygon class="arrowhead" points="408,128 396,122.4 396,133.6" fill="black" tra <path d="M 312,192 L 384,192" fill="none" stroke="black"/>
nsform="rotate(0,400,128)"/> <polygon class="arrowhead" points="408,128 396,122.4 396,133.6
<polygon class="arrowhead" points="312,64 300,58.4 300,69.6" fill="black" transf " fill="black" transform="rotate(0,400,128)"/>
orm="rotate(0,304,64)"/> <polygon class="arrowhead" points="312,64 300,58.4 300,69.6" f
<polygon class="arrowhead" points="96,160 84,154.4 84,165.6" fill="black" transf ill="black" transform="rotate(0,304,64)"/>
orm="rotate(180,88,160)"/> <polygon class="arrowhead" points="96,160 84,154.4 84,165.6" f
<polygon class="arrowhead" points="96,96 84,90.4 84,101.6" fill="black" transfor ill="black" transform="rotate(180,88,160)"/>
m="rotate(180,88,96)"/> <polygon class="arrowhead" points="96,96 84,90.4 84,101.6" fil
<g class="text"> l="black" transform="rotate(180,88,96)"/>
<text x="44" y="52">Client</text> <g class="text">
<text x="348" y="52">AS</text> <text x="44" y="52">Client</text>
<text x="44" y="68">Instance</text> <text x="348" y="52">AS</text>
<text x="112" y="68">1</text> <text x="44" y="68">Instance</text>
<text x="184" y="68">Request</text> <text x="112" y="68">1</text>
<text x="244" y="68">Access</text> <text x="184" y="68">Request</text>
<text x="112" y="100">2</text> <text x="244" y="68">Access</text>
<text x="184" y="100">Grant</text> <text x="112" y="100">2</text>
<text x="236" y="100">Access</text> <text x="184" y="100">Grant</text>
<text x="112" y="132">3</text> <text x="236" y="100">Access</text>
<text x="180" y="132">Access</text> <text x="112" y="132">3</text>
<text x="224" y="132">API</text> <text x="180" y="132">Access</text>
<text x="444" y="132">RS</text> <text x="224" y="132">API</text>
<text x="312" y="148">|</text> <text x="444" y="132">RS</text>
<text x="384" y="148">|</text> <text x="312" y="148">|</text>
<text x="112" y="164">4</text> <text x="384" y="148">|</text>
<text x="168" y="164">API</text> <text x="112" y="164">4</text>
<text x="220" y="164">Response</text> <text x="168" y="164">API</text>
</g> <text x="220" y="164">Response</text>
</svg> </g>
</artwork><artwork type="ascii-art"><![CDATA[ </svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
+--------+ +--------+ +--------+ +--------+
| Client | | AS | | Client | | AS |
|Instance+--(1)--- Request Access --->| | |Instance+--(1)--- Request Access --->| |
| | | | | | | |
| |<-(2)---- Grant Access -----+ | | |<-(2)---- Grant Access -----+ |
| | | | +--------+ | | | | +--------+
| +--(3)--- Access API ------------------->| RS | | +--(3)--- Access API ------------------->| RS |
| | | | | | | | | | | |
| |<-(4)--- API Response ------------------+ | | |<-(4)--- API Response ------------------+ |
| | | | +--------+ | | | | +--------+
+--------+ +--------+ +--------+ +--------+
]]></artwork></artset></figure> ]]></artwork>
</artset>
<t><list style="numbers"> </figure>
<t>The client instance <xref target="request">requests access to the resource< <ul spacing="normal"><li>
/xref>. The client instance does not <t>(1) The client instance requests access to the resource (<xref
target="request"> </xref>). The client instance does not
send any interaction modes to the server.</t> send any interaction modes to the server.</t>
<t>The AS determines that the request has been authorized based on the identit </li>
y of <li>
the client instance making the request and the <xref target="request-token">acc <t>(2) The AS determines that the request has been authorized base
ess requested</xref>. d on the identity of
the client instance making the request and the access requested (<xref target="
request-token"> </xref>).
The AS grants access to the resource The AS grants access to the resource
in the form of <xref target="response-token">access tokens</xref> to the client in the form of access tokens (<xref target="response-token"> </xref>) to the cl
instance. ient instance.
Note that <xref target="response-subject">direct subject information</xref> is Note that direct subject information (<xref target="response-subject"> </xref>)
not is not
generally applicable in this use case, as there is no user involved.</t> generally applicable in this use case, as there is no user involved.</t>
<t>The client instance <xref target="use-access-token">uses the access token</ </li>
xref> to call the RS.</t> <li>
<t>The RS validates the access token and returns an appropriate response for t <t>(3) The client instance uses the access token (<xref target="us
he e-access-token"> </xref>) to call the RS.</t>
</li>
<li>
<t>(4) The RS validates the access token and returns an appropriat
e response for the
API.</t> API.</t>
</list></t> </li>
</ul>
<t>An example set of protocol messages for this method can be found in <xref tar <t>An example set of protocol messages for this method can be found in
get="example-no-user"/>.</t> <xref target="example-no-user"/>.</t>
</section>
</section> <section anchor="sequence-refresh">
<section anchor="sequence-refresh"><name>Refreshing an Expired Access Token</nam <name>Refreshing an Expired Access Token</name>
e> <t>In this example flow, the client instance receives an access token
to access an RS through
<t>In this example flow, the client instance receives an access token to access
a resource server through
some valid GNAP process. The client instance uses that token at the RS for some time, but eventually some valid GNAP process. The client instance uses that token at the RS for some time, but eventually
the access token expires. The client instance then gets a refreshed access token by rotating the the access token expires. The client instance then gets a refreshed access token by rotating the
expired access token's value at the AS using the token management API.</t> expired access token's value at the AS using the token management API.<
/t>
<figure title="Figure 8: Diagram of the process of refreshing an access token">< <figure>
artset><artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" version="1.1 <name>Diagram of the Process of Refreshing an Expired Access Token</
" height="400" width="504" viewBox="0 0 504 400" class="diagram" text-anchor="mi name>
ddle" font-family="monospace" font-size="13px" stroke-linecap="round"> <artset>
<path d="M 8,32 L 8,384" fill="none" stroke="black"/> <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" versio
<path d="M 80,32 L 80,384" fill="none" stroke="black"/> n="1.1" height="400" width="504" viewBox="0 0 504 400" class="diagram" text-anch
<path d="M 320,128 L 320,288" fill="none" stroke="black"/> or="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 392,128 L 392,288" fill="none" stroke="black"/> <path d="M 8,32 L 8,384" fill="none" stroke="black"/>
<path d="M 424,32 L 424,384" fill="none" stroke="black"/> <path d="M 80,32 L 80,384" fill="none" stroke="black"/>
<path d="M 496,32 L 496,384" fill="none" stroke="black"/> <path d="M 320,128 L 320,288" fill="none" stroke="black"/>
<path d="M 8,32 L 80,32" fill="none" stroke="black"/> <path d="M 392,128 L 392,288" fill="none" stroke="black"/>
<path d="M 424,32 L 496,32" fill="none" stroke="black"/> <path d="M 424,32 L 424,384" fill="none" stroke="black"/>
<path d="M 80,64 L 104,64" fill="none" stroke="black"/> <path d="M 496,32 L 496,384" fill="none" stroke="black"/>
<path d="M 120,64 L 144,64" fill="none" stroke="black"/> <path d="M 8,32 L 80,32" fill="none" stroke="black"/>
<path d="M 280,64 L 416,64" fill="none" stroke="black"/> <path d="M 424,32 L 496,32" fill="none" stroke="black"/>
<path d="M 88,96 L 104,96" fill="none" stroke="black"/> <path d="M 80,64 L 104,64" fill="none" stroke="black"/>
<path d="M 120,96 L 144,96" fill="none" stroke="black"/> <path d="M 120,64 L 144,64" fill="none" stroke="black"/>
<path d="M 264,96 L 424,96" fill="none" stroke="black"/> <path d="M 280,64 L 416,64" fill="none" stroke="black"/>
<path d="M 320,128 L 392,128" fill="none" stroke="black"/> <path d="M 88,96 L 104,96" fill="none" stroke="black"/>
<path d="M 80,144 L 104,144" fill="none" stroke="black"/> <path d="M 120,96 L 144,96" fill="none" stroke="black"/>
<path d="M 120,144 L 144,144" fill="none" stroke="black"/> <path d="M 264,96 L 424,96" fill="none" stroke="black"/>
<path d="M 288,144 L 312,144" fill="none" stroke="black"/> <path d="M 320,128 L 392,128" fill="none" stroke="black"/>
<path d="M 88,176 L 104,176" fill="none" stroke="black"/> <path d="M 80,144 L 104,144" fill="none" stroke="black"/>
<path d="M 120,176 L 144,176" fill="none" stroke="black"/> <path d="M 120,144 L 144,144" fill="none" stroke="black"/>
<path d="M 296,176 L 320,176" fill="none" stroke="black"/> <path d="M 288,144 L 312,144" fill="none" stroke="black"/>
<path d="M 80,240 L 104,240" fill="none" stroke="black"/> <path d="M 88,176 L 104,176" fill="none" stroke="black"/>
<path d="M 120,240 L 144,240" fill="none" stroke="black"/> <path d="M 120,176 L 144,176" fill="none" stroke="black"/>
<path d="M 288,240 L 312,240" fill="none" stroke="black"/> <path d="M 296,176 L 320,176" fill="none" stroke="black"/>
<path d="M 88,272 L 104,272" fill="none" stroke="black"/> <path d="M 80,240 L 104,240" fill="none" stroke="black"/>
<path d="M 120,272 L 144,272" fill="none" stroke="black"/> <path d="M 120,240 L 144,240" fill="none" stroke="black"/>
<path d="M 280,272 L 320,272" fill="none" stroke="black"/> <path d="M 288,240 L 312,240" fill="none" stroke="black"/>
<path d="M 320,288 L 392,288" fill="none" stroke="black"/> <path d="M 88,272 L 104,272" fill="none" stroke="black"/>
<path d="M 80,320 L 104,320" fill="none" stroke="black"/> <path d="M 120,272 L 144,272" fill="none" stroke="black"/>
<path d="M 120,320 L 144,320" fill="none" stroke="black"/> <path d="M 280,272 L 320,272" fill="none" stroke="black"/>
<path d="M 264,320 L 416,320" fill="none" stroke="black"/> <path d="M 320,288 L 392,288" fill="none" stroke="black"/>
<path d="M 88,352 L 104,352" fill="none" stroke="black"/> <path d="M 80,320 L 104,320" fill="none" stroke="black"/>
<path d="M 120,352 L 144,352" fill="none" stroke="black"/> <path d="M 120,320 L 144,320" fill="none" stroke="black"/>
<path d="M 272,352 L 424,352" fill="none" stroke="black"/> <path d="M 264,320 L 416,320" fill="none" stroke="black"/>
<path d="M 8,384 L 80,384" fill="none" stroke="black"/> <path d="M 88,352 L 104,352" fill="none" stroke="black"/>
<path d="M 424,384 L 496,384" fill="none" stroke="black"/> <path d="M 120,352 L 144,352" fill="none" stroke="black"/>
<polygon class="arrowhead" points="424,320 412,314.4 412,325.6" fill="black" tra <path d="M 272,352 L 424,352" fill="none" stroke="black"/>
nsform="rotate(0,416,320)"/> <path d="M 8,384 L 80,384" fill="none" stroke="black"/>
<polygon class="arrowhead" points="424,64 412,58.4 412,69.6" fill="black" transf <path d="M 424,384 L 496,384" fill="none" stroke="black"/>
orm="rotate(0,416,64)"/> <polygon class="arrowhead" points="424,320 412,314.4 412,325.6
<polygon class="arrowhead" points="320,240 308,234.4 308,245.6" fill="black" tra " fill="black" transform="rotate(0,416,320)"/>
nsform="rotate(0,312,240)"/> <polygon class="arrowhead" points="424,64 412,58.4 412,69.6" f
<polygon class="arrowhead" points="320,144 308,138.4 308,149.6" fill="black" tra ill="black" transform="rotate(0,416,64)"/>
nsform="rotate(0,312,144)"/> <polygon class="arrowhead" points="320,240 308,234.4 308,245.6
<polygon class="arrowhead" points="96,352 84,346.4 84,357.6" fill="black" transf " fill="black" transform="rotate(0,312,240)"/>
orm="rotate(180,88,352)"/> <polygon class="arrowhead" points="320,144 308,138.4 308,149.6
<polygon class="arrowhead" points="96,272 84,266.4 84,277.6" fill="black" transf " fill="black" transform="rotate(0,312,144)"/>
orm="rotate(180,88,272)"/> <polygon class="arrowhead" points="96,352 84,346.4 84,357.6" f
<polygon class="arrowhead" points="96,176 84,170.4 84,181.6" fill="black" transf ill="black" transform="rotate(180,88,352)"/>
orm="rotate(180,88,176)"/> <polygon class="arrowhead" points="96,272 84,266.4 84,277.6" f
<polygon class="arrowhead" points="96,96 84,90.4 84,101.6" fill="black" transfor ill="black" transform="rotate(180,88,272)"/>
m="rotate(180,88,96)"/> <polygon class="arrowhead" points="96,176 84,170.4 84,181.6" f
<g class="text"> ill="black" transform="rotate(180,88,176)"/>
<text x="44" y="52">Client</text> <polygon class="arrowhead" points="96,96 84,90.4 84,101.6" fil
<text x="460" y="52">AS</text> l="black" transform="rotate(180,88,96)"/>
<text x="44" y="68">Instance</text> <g class="text">
<text x="112" y="68">1</text> <text x="44" y="52">Client</text>
<text x="184" y="68">Request</text> <text x="460" y="52">AS</text>
<text x="244" y="68">Access</text> <text x="44" y="68">Instance</text>
<text x="112" y="100">2</text> <text x="112" y="68">1</text>
<text x="176" y="100">Grant</text> <text x="184" y="68">Request</text>
<text x="228" y="100">Access</text> <text x="244" y="68">Access</text>
<text x="112" y="148">3</text> <text x="112" y="100">2</text>
<text x="180" y="148">Access</text> <text x="176" y="100">Grant</text>
<text x="244" y="148">Resource</text> <text x="228" y="100">Access</text>
<text x="356" y="148">RS</text> <text x="112" y="148">3</text>
<text x="112" y="180">4</text> <text x="180" y="148">Access</text>
<text x="184" y="180">Success</text> <text x="244" y="148">Resource</text>
<text x="252" y="180">Response</text> <text x="356" y="148">RS</text>
<text x="144" y="212">(</text> <text x="112" y="180">4</text>
<text x="172" y="212">Time</text> <text x="184" y="180">Success</text>
<text x="220" y="212">Passes</text> <text x="252" y="180">Response</text>
<text x="256" y="212">)</text> <text x="144" y="212">(</text>
<text x="112" y="244">5</text> <text x="172" y="212">Time</text>
<text x="180" y="244">Access</text> <text x="220" y="212">Passes</text>
<text x="244" y="244">Resource</text> <text x="256" y="212">)</text>
<text x="112" y="276">6</text> <text x="112" y="244">5</text>
<text x="176" y="276">Error</text> <text x="180" y="244">Access</text>
<text x="236" y="276">Response</text> <text x="244" y="244">Resource</text>
<text x="112" y="324">7</text> <text x="112" y="276">6</text>
<text x="180" y="324">Rotate</text> <text x="176" y="276">Error</text>
<text x="232" y="324">Token</text> <text x="236" y="276">Response</text>
<text x="112" y="356">8</text> <text x="112" y="324">7</text>
<text x="184" y="356">Rotated</text> <text x="180" y="324">Rotate</text>
<text x="240" y="356">Token</text> <text x="232" y="324">Token</text>
</g> <text x="112" y="356">8</text>
</svg> <text x="184" y="356">Rotated</text>
</artwork><artwork type="ascii-art"><![CDATA[ <text x="240" y="356">Token</text>
</g>
</svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
+--------+ +--------+ +--------+ +--------+
| Client | | AS | | Client | | AS |
|Instance+--(1)--- Request Access ----------------->| | |Instance+--(1)--- Request Access ----------------->| |
| | | | | | | |
| |<-(2)--- Grant Access --------------------+ | | |<-(2)--- Grant Access --------------------+ |
| | | | | | | |
| | +--------+ | | | | +--------+ | |
| +--(3)--- Access Resource --->| RS | | | | +--(3)--- Access Resource --->| RS | | |
| | | | | | | | | | | |
| |<-(4)--- Success Response ---+ | | | | |<-(4)--- Success Response ---+ | | |
skipping to change at line 1638 skipping to change at line 1757
| +--(5)--- Access Resource --->| | | | | +--(5)--- Access Resource --->| | | |
| | | | | | | | | | | |
| |<-(6)--- Error Response -----+ | | | | |<-(6)--- Error Response -----+ | | |
| | +--------+ | | | | +--------+ | |
| | | | | | | |
| +--(7)--- Rotate Token ------------------->| | | +--(7)--- Rotate Token ------------------->| |
| | | | | | | |
| |<-(8)--- Rotated Token -------------------+ | | |<-(8)--- Rotated Token -------------------+ |
| | | | | | | |
+--------+ +--------+ +--------+ +--------+
]]></artwork></artset></figure> ]]></artwork>
</artset>
<t><list style="numbers"> </figure>
<t>The client instance <xref target="request">requests access to the resource< <ul spacing="normal"><li>
/xref>.</t> <t>(1) The client instance requests access to the resource (<xref
<t>The AS <xref target="response">grants access to the resource</xref> with an target="request"> </xref>).</t>
<xref target="response-token">access token</xref> usable at the RS. The access </li>
token <li>
<t>(2) The AS grants access to the resource (<xref target="respons
e"> </xref>) with an
access token (<xref target="response-token"> </xref>) usable at the RS. The acc
ess token
response includes a token management URI.</t> response includes a token management URI.</t>
<t>The client instance <xref target="use-access-token">uses the access token</ </li>
xref> to call the RS.</t> <li>
<t>The RS validates the access token and returns an appropriate response for t <t>(3) The client instance uses the access token (<xref target="us
he e-access-token"> </xref>) to call the RS.</t>
</li>
<li>
<t>(4) The RS validates the access token and returns an appropriat
e response for the
API.</t> API.</t>
<t>Time passes and the client instance uses the access token to call the RS ag </li>
ain.</t> <li>
<t>The RS validates the access token and determines that the access token is e <t>(5) Time passes and the client instance uses the access token t
xpired. o call the RS again.</t>
</li>
<li>
<t>(6) The RS validates the access token and determines that the a
ccess token is expired.
The RS responds to the client instance with an error.</t> The RS responds to the client instance with an error.</t>
<t>The client instance calls the token management URI returned in (2) to </li>
<xref target="rotate-access-token">rotate the access token</xref>. The client i <li>
nstance
<xref target="use-access-token">uses the access token</xref> in this call as we <t>(7) The client instance calls the token management URI returned
ll as the appropriate key, in (2) to
see the token rotation section for details.</t> rotate the access token (<xref target="rotate-access-token"> </xref>). The clie
<t>The AS validates the rotation request including the signature nt instance
and keys presented in (7) and refreshes the uses the access token (<xref target="use-access-token"> </xref>) in this call a
<xref target="response-token-single">access token</xref>. The response includes s well as the appropriate key;
see <xref target="rotate-access-token"/> for details.</t>
</li>
<li>
<t>(8) The AS validates the rotation request, including the signat
ure
and keys presented in (7), and refreshes the
access token (<xref target="response-token-single"> </xref>). The response incl
udes
a new version of the access token and can also include updated token management a new version of the access token and can also include updated token management
information, which the client instance will store in place of the values information, which the client instance will store in place of the values
returned in (2).</t> returned in (2).</t>
</list></t> </li>
</ul>
</section> </section>
<section anchor="sequence-user"><name>Requesting Subject Information Only</name> <section anchor="sequence-user">
<name>Requesting Subject Information Only</name>
<t>In this scenario, the client instance does not call an RS and does not <t>In this scenario, the client instance does not call an RS and does
not
request an access token. Instead, the client instance only requests request an access token. Instead, the client instance only requests
and is returned <xref target="response-subject">direct subject information</xref >. Many different and is returned direct subject information (<xref target="response-subject"></xr ef>). Many different
interaction modes can be used in this scenario, so these are shown only in interaction modes can be used in this scenario, so these are shown only in
the abstract as functions of the AS here.</t> the abstract as functions of the AS here.</t>
<figure>
<figure title="Figure 9: Diagram of the process of requesting and releasing subj <name>Diagram of the Process of Requesting and Releasing Subject Inf
ect information apart from access tokens"><artset><artwork type="svg"><svg xmln ormation apart from Access Tokens</name>
s="http://www.w3.org/2000/svg" version="1.1" height="384" width="576" viewBox="0 <artset>
0 576 384" class="diagram" text-anchor="middle" font-family="monospace" font-si <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" versio
ze="13px" stroke-linecap="round"> n="1.1" height="384" width="576" viewBox="0 0 576 384" class="diagram" text-anch
<path d="M 8,32 L 8,368" fill="none" stroke="black"/> or="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 80,32 L 80,368" fill="none" stroke="black"/> <path d="M 8,32 L 8,368" fill="none" stroke="black"/>
<path d="M 360,32 L 360,128" fill="none" stroke="black"/> <path d="M 80,32 L 80,368" fill="none" stroke="black"/>
<path d="M 360,160 L 360,256" fill="none" stroke="black"/> <path d="M 360,32 L 360,128" fill="none" stroke="black"/>
<path d="M 360,288 L 360,368" fill="none" stroke="black"/> <path d="M 360,160 L 360,256" fill="none" stroke="black"/>
<path d="M 432,32 L 432,128" fill="none" stroke="black"/> <path d="M 360,288 L 360,368" fill="none" stroke="black"/>
<path d="M 432,160 L 432,256" fill="none" stroke="black"/> <path d="M 432,32 L 432,128" fill="none" stroke="black"/>
<path d="M 432,288 L 432,368" fill="none" stroke="black"/> <path d="M 432,160 L 432,256" fill="none" stroke="black"/>
<path d="M 512,48 L 512,272" fill="none" stroke="black"/> <path d="M 432,288 L 432,368" fill="none" stroke="black"/>
<path d="M 568,48 L 568,272" fill="none" stroke="black"/> <path d="M 512,48 L 512,272" fill="none" stroke="black"/>
<path d="M 8,32 L 80,32" fill="none" stroke="black"/> <path d="M 568,48 L 568,272" fill="none" stroke="black"/>
<path d="M 360,32 L 432,32" fill="none" stroke="black"/> <path d="M 8,32 L 80,32" fill="none" stroke="black"/>
<path d="M 528,32 L 552,32" fill="none" stroke="black"/> <path d="M 360,32 L 432,32" fill="none" stroke="black"/>
<path d="M 80,80 L 104,80" fill="none" stroke="black"/> <path d="M 528,32 L 552,32" fill="none" stroke="black"/>
<path d="M 120,80 L 144,80" fill="none" stroke="black"/> <path d="M 80,80 L 104,80" fill="none" stroke="black"/>
<path d="M 280,80 L 352,80" fill="none" stroke="black"/> <path d="M 120,80 L 144,80" fill="none" stroke="black"/>
<path d="M 88,112 L 104,112" fill="none" stroke="black"/> <path d="M 280,80 L 352,80" fill="none" stroke="black"/>
<path d="M 120,112 L 136,112" fill="none" stroke="black"/> <path d="M 88,112 L 104,112" fill="none" stroke="black"/>
<path d="M 304,112 L 360,112" fill="none" stroke="black"/> <path d="M 120,112 L 136,112" fill="none" stroke="black"/>
<path d="M 80,142 L 104,142" fill="none" stroke="black"/><path d="M 80,146 L 104 <path d="M 304,112 L 360,112" fill="none" stroke="black"/>
,146" fill="none" stroke="black"/> <path d="M 80,142 L 104,142" fill="none" stroke="black"/>
<path d="M 120,142 L 136,142" fill="none" stroke="black"/><path d="M 120,146 L 1 <path d="M 80,146 L 104,146" fill="none" stroke="black"/>
36,146" fill="none" stroke="black"/> <path d="M 120,142 L 136,142" fill="none" stroke="black"/>
<path d="M 336,142 L 504,142" fill="none" stroke="black"/><path d="M 336,146 L 5 <path d="M 120,146 L 136,146" fill="none" stroke="black"/>
04,146" fill="none" stroke="black"/> <path d="M 336,142 L 504,142" fill="none" stroke="black"/>
<path d="M 512,160 L 568,160" fill="none" stroke="black"/> <path d="M 336,146 L 504,146" fill="none" stroke="black"/>
<path d="M 440,174 L 464,174" fill="none" stroke="black"/><path d="M 440,178 L 4 <path d="M 512,160 L 568,160" fill="none" stroke="black"/>
64,178" fill="none" stroke="black"/> <path d="M 440,174 L 464,174" fill="none" stroke="black"/>
<path d="M 480,174 L 504,174" fill="none" stroke="black"/><path d="M 480,178 L 5 <path d="M 440,178 L 464,178" fill="none" stroke="black"/>
04,178" fill="none" stroke="black"/> <path d="M 480,174 L 504,174" fill="none" stroke="black"/>
<path d="M 440,222 L 464,222" fill="none" stroke="black"/><path d="M 440,226 L 4 <path d="M 480,178 L 504,178" fill="none" stroke="black"/>
64,226" fill="none" stroke="black"/> <path d="M 440,222 L 464,222" fill="none" stroke="black"/>
<path d="M 480,222 L 504,222" fill="none" stroke="black"/><path d="M 480,226 L 5 <path d="M 440,226 L 464,226" fill="none" stroke="black"/>
04,226" fill="none" stroke="black"/> <path d="M 480,222 L 504,222" fill="none" stroke="black"/>
<path d="M 512,240 L 568,240" fill="none" stroke="black"/> <path d="M 480,226 L 504,226" fill="none" stroke="black"/>
<path d="M 88,270 L 104,270" fill="none" stroke="black"/><path d="M 88,274 L 104 <path d="M 512,240 L 568,240" fill="none" stroke="black"/>
,274" fill="none" stroke="black"/> <path d="M 88,270 L 104,270" fill="none" stroke="black"/>
<path d="M 120,270 L 136,270" fill="none" stroke="black"/><path d="M 120,274 L 1 <path d="M 88,274 L 104,274" fill="none" stroke="black"/>
36,274" fill="none" stroke="black"/> <path d="M 120,270 L 136,270" fill="none" stroke="black"/>
<path d="M 312,270 L 512,270" fill="none" stroke="black"/><path d="M 312,274 L 5 <path d="M 120,274 L 136,274" fill="none" stroke="black"/>
12,274" fill="none" stroke="black"/> <path d="M 312,270 L 512,270" fill="none" stroke="black"/>
<path d="M 528,288 L 552,288" fill="none" stroke="black"/> <path d="M 312,274 L 512,274" fill="none" stroke="black"/>
<path d="M 80,304 L 104,304" fill="none" stroke="black"/> <path d="M 528,288 L 552,288" fill="none" stroke="black"/>
<path d="M 120,304 L 144,304" fill="none" stroke="black"/> <path d="M 80,304 L 104,304" fill="none" stroke="black"/>
<path d="M 296,304 L 352,304" fill="none" stroke="black"/> <path d="M 120,304 L 144,304" fill="none" stroke="black"/>
<path d="M 88,336 L 104,336" fill="none" stroke="black"/> <path d="M 296,304 L 352,304" fill="none" stroke="black"/>
<path d="M 120,336 L 160,336" fill="none" stroke="black"/> <path d="M 88,336 L 104,336" fill="none" stroke="black"/>
<path d="M 280,336 L 360,336" fill="none" stroke="black"/> <path d="M 120,336 L 160,336" fill="none" stroke="black"/>
<path d="M 8,368 L 80,368" fill="none" stroke="black"/> <path d="M 280,336 L 360,336" fill="none" stroke="black"/>
<path d="M 360,368 L 432,368" fill="none" stroke="black"/> <path d="M 8,368 L 80,368" fill="none" stroke="black"/>
<path d="M 528,32 C 519.16936,32 512,39.16936 512,48" fill="none" stroke="black" <path d="M 360,368 L 432,368" fill="none" stroke="black"/>
/> <path d="M 528,32 C 519.16936,32 512,39.16936 512,48" fill="no
<path d="M 552,32 C 560.83064,32 568,39.16936 568,48" fill="none" stroke="black" ne" stroke="black"/>
/> <path d="M 552,32 C 560.83064,32 568,39.16936 568,48" fill="no
<path d="M 528,288 C 519.16936,288 512,280.83064 512,272" fill="none" stroke="bl ne" stroke="black"/>
ack"/> <path d="M 528,288 C 519.16936,288 512,280.83064 512,272" fill
<path d="M 552,288 C 560.83064,288 568,280.83064 568,272" fill="none" stroke="bl ="none" stroke="black"/>
ack"/> <path d="M 552,288 C 560.83064,288 568,280.83064 568,272" fill
<polygon class="arrowhead" points="512,224 500,218.4 500,229.6" fill="black" tra ="none" stroke="black"/>
nsform="rotate(0,504,224)"/> <polygon class="arrowhead" points="512,224 500,218.4 500,229.6
<polygon class="arrowhead" points="512,176 500,170.4 500,181.6" fill="black" tra " fill="black" transform="rotate(0,504,224)"/>
nsform="rotate(0,504,176)"/> <polygon class="arrowhead" points="512,176 500,170.4 500,181.6
<polygon class="arrowhead" points="512,144 500,138.4 500,149.6" fill="black" tra " fill="black" transform="rotate(0,504,176)"/>
nsform="rotate(0,504,144)"/> <polygon class="arrowhead" points="512,144 500,138.4 500,149.6
<polygon class="arrowhead" points="448,224 436,218.4 436,229.6" fill="black" tra " fill="black" transform="rotate(0,504,144)"/>
nsform="rotate(180,440,224)"/> <polygon class="arrowhead" points="448,224 436,218.4 436,229.6
<polygon class="arrowhead" points="448,176 436,170.4 436,181.6" fill="black" tra " fill="black" transform="rotate(180,440,224)"/>
nsform="rotate(180,440,176)"/> <polygon class="arrowhead" points="448,176 436,170.4 436,181.6
<polygon class="arrowhead" points="360,304 348,298.4 348,309.6" fill="black" tra " fill="black" transform="rotate(180,440,176)"/>
nsform="rotate(0,352,304)"/> <polygon class="arrowhead" points="360,304 348,298.4 348,309.6
<polygon class="arrowhead" points="360,80 348,74.4 348,85.6" fill="black" transf " fill="black" transform="rotate(0,352,304)"/>
orm="rotate(0,352,80)"/> <polygon class="arrowhead" points="360,80 348,74.4 348,85.6" f
<polygon class="arrowhead" points="96,336 84,330.4 84,341.6" fill="black" transf ill="black" transform="rotate(0,352,80)"/>
orm="rotate(180,88,336)"/> <polygon class="arrowhead" points="96,336 84,330.4 84,341.6" f
<polygon class="arrowhead" points="96,272 84,266.4 84,277.6" fill="black" transf ill="black" transform="rotate(180,88,336)"/>
orm="rotate(180,88,272)"/> <polygon class="arrowhead" points="96,272 84,266.4 84,277.6" f
<polygon class="arrowhead" points="96,112 84,106.4 84,117.6" fill="black" transf ill="black" transform="rotate(180,88,272)"/>
orm="rotate(180,88,112)"/> <polygon class="arrowhead" points="96,112 84,106.4 84,117.6" f
<g class="text"> ill="black" transform="rotate(180,88,112)"/>
<text x="44" y="52">Client</text> <g class="text">
<text x="396" y="52">AS</text> <text x="44" y="52">Client</text>
<text x="536" y="52">End</text> <text x="396" y="52">AS</text>
<text x="44" y="68">Instance</text> <text x="536" y="52">End</text>
<text x="540" y="68">User</text> <text x="44" y="68">Instance</text>
<text x="112" y="84">1</text> <text x="540" y="68">User</text>
<text x="184" y="84">Request</text> <text x="112" y="84">1</text>
<text x="244" y="84">Access</text> <text x="184" y="84">Request</text>
<text x="112" y="116">2</text> <text x="244" y="84">Access</text>
<text x="192" y="116">Interaction</text> <text x="112" y="116">2</text>
<text x="268" y="116">Needed</text> <text x="192" y="116">Interaction</text>
<text x="112" y="148">3</text> <text x="268" y="116">Needed</text>
<text x="188" y="148">Facilitate</text> <text x="112" y="148">3</text>
<text x="280" y="148">Interaction</text> <text x="188" y="148">Facilitate</text>
<text x="472" y="180">4</text> <text x="280" y="148">Interaction</text>
<text x="540" y="180">RO</text> <text x="472" y="180">4</text>
<text x="472" y="196">AuthN</text> <text x="540" y="180">RO</text>
<text x="472" y="228">5</text> <text x="472" y="196">AuthN</text>
<text x="472" y="244">AuthZ</text> <text x="472" y="228">5</text>
<text x="536" y="260">End</text> <text x="472" y="244">AuthZ</text>
<text x="112" y="276">6</text> <text x="536" y="260">End</text>
<text x="172" y="276">Signal</text> <text x="112" y="276">6</text>
<text x="252" y="276">Continuation</text> <text x="172" y="276">Signal</text>
<text x="540" y="276">User</text> <text x="252" y="276">Continuation</text>
<text x="112" y="308">7</text> <text x="540" y="276">User</text>
<text x="188" y="308">Continue</text> <text x="112" y="308">7</text>
<text x="256" y="308">Request</text> <text x="188" y="308">Continue</text>
<text x="112" y="340">8</text> <text x="256" y="308">Request</text>
<text x="192" y="340">Grant</text> <text x="112" y="340">8</text>
<text x="244" y="340">Access</text> <text x="192" y="340">Grant</text>
</g> <text x="244" y="340">Access</text>
</svg> </g>
</artwork><artwork type="ascii-art"><![CDATA[ </svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
+--------+ +--------+ .----. +--------+ +--------+ .----.
| Client | | AS | | End | | Client | | AS | | End |
|Instance| | | | User | |Instance| | | | User |
| +--(1)--- Request Access --------->| | | | | +--(1)--- Request Access --------->| | | |
| | | | | | | | | | | |
| |<-(2)-- Interaction Needed -------+ | | | | |<-(2)-- Interaction Needed -------+ | | |
| | | | | | | | | | | |
| +==(3)== Facilitate Interaction =====================>| | | +==(3)== Facilitate Interaction =====================>| |
| | | | +------+ | | | | +------+
| | | |<==(4)==>| RO | | | | |<==(4)==>| RO |
skipping to change at line 1783 skipping to change at line 1931
| | | |<==(5)==>| | | | | |<==(5)==>| |
| | | | AuthZ +------+ | | | | AuthZ +------+
| | | | | End | | | | | | End |
| |<=(6)== Signal Continuation =========================+ User | | |<=(6)== Signal Continuation =========================+ User |
| | | | `----` | | | | `----`
| +--(7)--- Continue Request ------->| | | +--(7)--- Continue Request ------->| |
| | | | | | | |
| |<-(8)----- Grant Access ----------+ | | |<-(8)----- Grant Access ----------+ |
| | | | | | | |
+--------+ +--------+ +--------+ +--------+
]]></artwork></artset></figure> ]]></artwork>
</artset>
<t><list style="numbers"> </figure>
<t>The client instance <xref target="request">requests access to subject infor <ul spacing="normal"><li>
mation</xref>.</t> <t>(1) The client instance requests access to subject information
<t>The AS determines that interaction is needed and <xref target="response">re (<xref target="request"> </xref>).</t>
sponds</xref> with </li>
appropriate information for <xref target="response-interact">facilitating user <li>
interaction</xref>.</t> <t>(2) The AS determines that interaction is needed and responds (
<t>The client instance facilitates <xref target="authorization">the user inter <xref target="response"> </xref>) with
acting with the AS</xref> as directed in (2).</t> appropriate information for facilitating user interaction (<xref target="respon
<t>The user authenticates at the AS, taking on the role of the RO.</t> se-interact"> </xref>).</t>
<t>As the RO, the user authorizes the pending request from the client instance </li>
.</t> <li>
<t>When the AS is done interacting with the user, the AS <t>(3) The client instance facilitates the user interacting with t
he AS (<xref target="authorization"> </xref>) as directed in (2).</t>
</li>
<li>
<t>(4) The user authenticates at the AS, taking on the role of the
RO.</t>
</li>
<li>
<t>(5) As the RO, the user authorizes the pending request from the
client instance.</t>
</li>
<li>
<t>(6) When the AS is done interacting with the user, the AS
returns the user to the client instance and signals continuation.</t> returns the user to the client instance and signals continuation.</t>
<t>The client instance loads the continuation information from (2) and </li>
calls the AS to <xref target="continue-request">continue the request</xref>.</t <li>
> <t>(7) The client instance loads the continuation information from
<t>If the request has been authorized, the AS grants access to the requested (2) and
<xref target="response-subject">direct subject information</xref> to the client calls the AS to continue the request (<xref target="continue-request"> </xref>)
instance. .</t>
</li>
<li>
<t>(8) If the request has been authorized, the AS grants access to
the requested
direct subject information (<xref target="response-subject"> </xref>) to the cl
ient instance.
At this stage, the user is generally considered "logged in" to the client At this stage, the user is generally considered "logged in" to the client
instance based on the identifiers and assertions provided by the AS. instance based on the identifiers and assertions provided by the AS.
Note that the AS can restrict the subject information returned and it Note that the AS can restrict the subject information returned, and it
might not match what the client instance requested, see the section on might not match what the client instance requested; see <xref target="response-
subject information for details.</t> subject"/> for details.</t>
</list></t> </li>
</ul>
</section> </section>
<section anchor="sequence-cross-user"><name>Cross-User Authentication</name> <section anchor="sequence-cross-user">
<name>Cross-User Authentication</name>
<t>In this scenario, the end user and resource owner are two different people. <t>In this scenario, the end user and RO are two different people.
Here, the client instance already knows who the end user Here, the client instance already knows who the end user
is, likely through a separate authentication process. The is, likely through a separate authentication process. The
end user, operating the client instance, needs to get subject information end user, operating the client instance, needs to get subject information
about another person in the system, the RO. The RO is given an opportunity about another person in the system, the RO. The RO is given an opportunity
to release this information using an asynchronous interaction method to release this information using an asynchronous interaction method
with the AS. This scenario would apply, for instance, when the end user with the AS. This scenario would apply, for instance, when the end user
is an agent in a call-center and the resource owner is a customer is an agent in a call center and the RO is a customer
authorizing the call center agent to access their account on their behalf.</t> authorizing the call-center agent to access their account on their behalf.</t>
<figure>
<figure title="Figure 10: Diagram of cross-user authorization, where the end use <name>Diagram of Cross-User Authorization, Where the End User and RO
r and RO are different"><artset><artwork type="svg"><svg xmlns="http://www.w3.o Are Different</name>
rg/2000/svg" version="1.1" height="480" width="576" viewBox="0 0 576 480" class= <artset>
"diagram" text-anchor="middle" font-family="monospace" font-size="13px" stroke-l <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" versio
inecap="round"> n="1.1" height="480" width="576" viewBox="0 0 576 480" class="diagram" text-anch
<path d="M 8,48 L 8,448" fill="none" stroke="black"/> or="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 64,48 L 64,448" fill="none" stroke="black"/> <path d="M 8,48 L 8,448" fill="none" stroke="black"/>
<path d="M 136,96 L 136,464" fill="none" stroke="black"/> <path d="M 64,48 L 64,448" fill="none" stroke="black"/>
<path d="M 208,96 L 208,464" fill="none" stroke="black"/> <path d="M 136,96 L 136,464" fill="none" stroke="black"/>
<path d="M 360,96 L 360,464" fill="none" stroke="black"/> <path d="M 208,96 L 208,464" fill="none" stroke="black"/>
<path d="M 432,96 L 432,464" fill="none" stroke="black"/> <path d="M 360,96 L 360,464" fill="none" stroke="black"/>
<path d="M 512,48 L 512,448" fill="none" stroke="black"/> <path d="M 432,96 L 432,464" fill="none" stroke="black"/>
<path d="M 568,48 L 568,448" fill="none" stroke="black"/> <path d="M 512,48 L 512,448" fill="none" stroke="black"/>
<path d="M 24,32 L 48,32" fill="none" stroke="black"/> <path d="M 568,48 L 568,448" fill="none" stroke="black"/>
<path d="M 528,32 L 552,32" fill="none" stroke="black"/> <path d="M 24,32 L 48,32" fill="none" stroke="black"/>
<path d="M 72,62 L 216,62" fill="none" stroke="black"/><path d="M 72,66 L 216,66 <path d="M 528,32 L 552,32" fill="none" stroke="black"/>
" fill="none" stroke="black"/> <path d="M 72,62 L 216,62" fill="none" stroke="black"/>
<path d="M 232,62 L 248,62" fill="none" stroke="black"/><path d="M 232,66 L 248, <path d="M 72,66 L 216,66" fill="none" stroke="black"/>
66" fill="none" stroke="black"/> <path d="M 232,62 L 248,62" fill="none" stroke="black"/>
<path d="M 360,62 L 504,62" fill="none" stroke="black"/><path d="M 360,66 L 504, <path d="M 232,66 L 248,66" fill="none" stroke="black"/>
66" fill="none" stroke="black"/> <path d="M 360,62 L 504,62" fill="none" stroke="black"/>
<path d="M 136,96 L 208,96" fill="none" stroke="black"/> <path d="M 360,66 L 504,66" fill="none" stroke="black"/>
<path d="M 360,96 L 432,96" fill="none" stroke="black"/> <path d="M 136,96 L 208,96" fill="none" stroke="black"/>
<path d="M 64,110 L 88,110" fill="none" stroke="black"/><path d="M 64,114 L 88,1 <path d="M 360,96 L 432,96" fill="none" stroke="black"/>
14" fill="none" stroke="black"/> <path d="M 64,110 L 88,110" fill="none" stroke="black"/>
<path d="M 104,110 L 128,110" fill="none" stroke="black"/><path d="M 104,114 L 1 <path d="M 64,114 L 88,114" fill="none" stroke="black"/>
28,114" fill="none" stroke="black"/> <path d="M 104,110 L 128,110" fill="none" stroke="black"/>
<path d="M 208,160 L 232,160" fill="none" stroke="black"/> <path d="M 104,114 L 128,114" fill="none" stroke="black"/>
<path d="M 248,160 L 264,160" fill="none" stroke="black"/> <path d="M 208,160 L 232,160" fill="none" stroke="black"/>
<path d="M 320,160 L 352,160" fill="none" stroke="black"/> <path d="M 248,160 L 264,160" fill="none" stroke="black"/>
<path d="M 216,192 L 232,192" fill="none" stroke="black"/> <path d="M 320,160 L 352,160" fill="none" stroke="black"/>
<path d="M 248,192 L 264,192" fill="none" stroke="black"/> <path d="M 216,192 L 232,192" fill="none" stroke="black"/>
<path d="M 320,192 L 360,192" fill="none" stroke="black"/> <path d="M 248,192 L 264,192" fill="none" stroke="black"/>
<path d="M 440,206 L 464,206" fill="none" stroke="black"/><path d="M 440,210 L 4 <path d="M 320,192 L 360,192" fill="none" stroke="black"/>
64,210" fill="none" stroke="black"/> <path d="M 440,206 L 464,206" fill="none" stroke="black"/>
<path d="M 480,206 L 504,206" fill="none" stroke="black"/><path d="M 480,210 L 5 <path d="M 440,210 L 464,210" fill="none" stroke="black"/>
04,210" fill="none" stroke="black"/> <path d="M 480,206 L 504,206" fill="none" stroke="black"/>
<path d="M 440,254 L 464,254" fill="none" stroke="black"/><path d="M 440,258 L 4 <path d="M 480,210 L 504,210" fill="none" stroke="black"/>
64,258" fill="none" stroke="black"/> <path d="M 440,254 L 464,254" fill="none" stroke="black"/>
<path d="M 480,254 L 504,254" fill="none" stroke="black"/><path d="M 480,258 L 5 <path d="M 440,258 L 464,258" fill="none" stroke="black"/>
04,258" fill="none" stroke="black"/> <path d="M 480,254 L 504,254" fill="none" stroke="black"/>
<path d="M 440,302 L 464,302" fill="none" stroke="black"/><path d="M 440,306 L 4 <path d="M 480,258 L 504,258" fill="none" stroke="black"/>
64,306" fill="none" stroke="black"/> <path d="M 440,302 L 464,302" fill="none" stroke="black"/>
<path d="M 480,302 L 504,302" fill="none" stroke="black"/><path d="M 480,306 L 5 <path d="M 440,306 L 464,306" fill="none" stroke="black"/>
04,306" fill="none" stroke="black"/> <path d="M 480,302 L 504,302" fill="none" stroke="black"/>
<path d="M 216,320 L 232,320" fill="none" stroke="black"/> <path d="M 480,306 L 504,306" fill="none" stroke="black"/>
<path d="M 248,320 L 272,320" fill="none" stroke="black"/> <path d="M 216,320 L 232,320" fill="none" stroke="black"/>
<path d="M 344,320 L 360,320" fill="none" stroke="black"/> <path d="M 248,320 L 272,320" fill="none" stroke="black"/>
<path d="M 208,352 L 232,352" fill="none" stroke="black"/> <path d="M 344,320 L 360,320" fill="none" stroke="black"/>
<path d="M 248,352 L 272,352" fill="none" stroke="black"/> <path d="M 208,352 L 232,352" fill="none" stroke="black"/>
<path d="M 336,352 L 352,352" fill="none" stroke="black"/> <path d="M 248,352 L 272,352" fill="none" stroke="black"/>
<path d="M 216,384 L 232,384" fill="none" stroke="black"/> <path d="M 336,352 L 352,352" fill="none" stroke="black"/>
<path d="M 256,384 L 272,384" fill="none" stroke="black"/> <path d="M 216,384 L 232,384" fill="none" stroke="black"/>
<path d="M 336,384 L 360,384" fill="none" stroke="black"/> <path d="M 256,384 L 272,384" fill="none" stroke="black"/>
<path d="M 72,398 L 88,398" fill="none" stroke="black"/><path d="M 72,402 L 88,4 <path d="M 336,384 L 360,384" fill="none" stroke="black"/>
02" fill="none" stroke="black"/> <path d="M 72,398 L 88,398" fill="none" stroke="black"/>
<path d="M 112,398 L 136,398" fill="none" stroke="black"/><path d="M 112,402 L 1 <path d="M 72,402 L 88,402" fill="none" stroke="black"/>
36,402" fill="none" stroke="black"/> <path d="M 112,398 L 136,398" fill="none" stroke="black"/>
<path d="M 24,464 L 48,464" fill="none" stroke="black"/> <path d="M 112,402 L 136,402" fill="none" stroke="black"/>
<path d="M 136,464 L 208,464" fill="none" stroke="black"/> <path d="M 24,464 L 48,464" fill="none" stroke="black"/>
<path d="M 360,464 L 432,464" fill="none" stroke="black"/> <path d="M 136,464 L 208,464" fill="none" stroke="black"/>
<path d="M 528,464 L 552,464" fill="none" stroke="black"/> <path d="M 360,464 L 432,464" fill="none" stroke="black"/>
<path d="M 24,32 C 15.16936,32 8,39.16936 8,48" fill="none" stroke="black"/> <path d="M 528,464 L 552,464" fill="none" stroke="black"/>
<path d="M 48,32 C 56.83064,32 64,39.16936 64,48" fill="none" stroke="black"/> <path d="M 24,32 C 15.16936,32 8,39.16936 8,48" fill="none" st
<path d="M 528,32 C 519.16936,32 512,39.16936 512,48" fill="none" stroke="black" roke="black"/>
/> <path d="M 48,32 C 56.83064,32 64,39.16936 64,48" fill="none"
<path d="M 552,32 C 560.83064,32 568,39.16936 568,48" fill="none" stroke="black" stroke="black"/>
/> <path d="M 528,32 C 519.16936,32 512,39.16936 512,48" fill="no
<path d="M 24,464 C 15.16936,464 8,456.83064 8,448" fill="none" stroke="black"/> ne" stroke="black"/>
<path d="M 48,464 C 56.83064,464 64,456.83064 64,448" fill="none" stroke="black" <path d="M 552,32 C 560.83064,32 568,39.16936 568,48" fill="no
/> ne" stroke="black"/>
<path d="M 528,464 C 519.16936,464 512,456.83064 512,448" fill="none" stroke="bl <path d="M 24,464 C 15.16936,464 8,456.83064 8,448" fill="none
ack"/> " stroke="black"/>
<path d="M 552,464 C 560.83064,464 568,456.83064 568,448" fill="none" stroke="bl <path d="M 48,464 C 56.83064,464 64,456.83064 64,448" fill="no
ack"/> ne" stroke="black"/>
<polygon class="arrowhead" points="512,304 500,298.4 500,309.6" fill="black" tra <path d="M 528,464 C 519.16936,464 512,456.83064 512,448" fill
nsform="rotate(0,504,304)"/> ="none" stroke="black"/>
<polygon class="arrowhead" points="512,256 500,250.4 500,261.6" fill="black" tra <path d="M 552,464 C 560.83064,464 568,456.83064 568,448" fill
nsform="rotate(0,504,256)"/> ="none" stroke="black"/>
<polygon class="arrowhead" points="512,208 500,202.4 500,213.6" fill="black" tra <polygon class="arrowhead" points="512,304 500,298.4 500,309.6
nsform="rotate(0,504,208)"/> " fill="black" transform="rotate(0,504,304)"/>
<polygon class="arrowhead" points="512,64 500,58.4 500,69.6" fill="black" transf <polygon class="arrowhead" points="512,256 500,250.4 500,261.6
orm="rotate(0,504,64)"/> " fill="black" transform="rotate(0,504,256)"/>
<polygon class="arrowhead" points="448,304 436,298.4 436,309.6" fill="black" tra <polygon class="arrowhead" points="512,208 500,202.4 500,213.6
nsform="rotate(180,440,304)"/> " fill="black" transform="rotate(0,504,208)"/>
<polygon class="arrowhead" points="448,256 436,250.4 436,261.6" fill="black" tra <polygon class="arrowhead" points="512,64 500,58.4 500,69.6" f
nsform="rotate(180,440,256)"/> ill="black" transform="rotate(0,504,64)"/>
<polygon class="arrowhead" points="448,208 436,202.4 436,213.6" fill="black" tra <polygon class="arrowhead" points="448,304 436,298.4 436,309.6
nsform="rotate(180,440,208)"/> " fill="black" transform="rotate(180,440,304)"/>
<polygon class="arrowhead" points="360,352 348,346.4 348,357.6" fill="black" tra <polygon class="arrowhead" points="448,256 436,250.4 436,261.6
nsform="rotate(0,352,352)"/> " fill="black" transform="rotate(180,440,256)"/>
<polygon class="arrowhead" points="360,160 348,154.4 348,165.6" fill="black" tra <polygon class="arrowhead" points="448,208 436,202.4 436,213.6
nsform="rotate(0,352,160)"/> " fill="black" transform="rotate(180,440,208)"/>
<polygon class="arrowhead" points="224,384 212,378.4 212,389.6" fill="black" tra <polygon class="arrowhead" points="360,352 348,346.4 348,357.6
nsform="rotate(180,216,384)"/> " fill="black" transform="rotate(0,352,352)"/>
<polygon class="arrowhead" points="224,320 212,314.4 212,325.6" fill="black" tra <polygon class="arrowhead" points="360,160 348,154.4 348,165.6
nsform="rotate(180,216,320)"/> " fill="black" transform="rotate(0,352,160)"/>
<polygon class="arrowhead" points="224,192 212,186.4 212,197.6" fill="black" tra <polygon class="arrowhead" points="224,384 212,378.4 212,389.6
nsform="rotate(180,216,192)"/> " fill="black" transform="rotate(180,216,384)"/>
<polygon class="arrowhead" points="136,112 124,106.4 124,117.6" fill="black" tra <polygon class="arrowhead" points="224,320 212,314.4 212,325.6
nsform="rotate(0,128,112)"/> " fill="black" transform="rotate(180,216,320)"/>
<polygon class="arrowhead" points="80,400 68,394.4 68,405.6" fill="black" transf <polygon class="arrowhead" points="224,192 212,186.4 212,197.6
orm="rotate(180,72,400)"/> " fill="black" transform="rotate(180,216,192)"/>
<polygon class="arrowhead" points="80,64 68,58.4 68,69.6" fill="black" transform <polygon class="arrowhead" points="136,112 124,106.4 124,117.6
="rotate(180,72,64)"/> " fill="black" transform="rotate(0,128,112)"/>
<g class="text"> <polygon class="arrowhead" points="80,400 68,394.4 68,405.6" f
<text x="32" y="52">End</text> ill="black" transform="rotate(180,72,400)"/>
<text x="540" y="52">RO</text> <polygon class="arrowhead" points="80,64 68,58.4 68,69.6" fill
<text x="36" y="68">User</text> ="black" transform="rotate(180,72,64)"/>
<text x="224" y="68">1</text> <g class="text">
<text x="292" y="68">Identify</text> <text x="32" y="52">End</text>
<text x="340" y="68">RO</text> <text x="540" y="52">RO</text>
<text x="96" y="116">2</text> <text x="36" y="68">User</text>
<text x="172" y="116">Client</text> <text x="224" y="68">1</text>
<text x="396" y="116">AS</text> <text x="292" y="68">Identify</text>
<text x="84" y="132">RO</text> <text x="340" y="68">RO</text>
<text x="108" y="132">ID</text> <text x="96" y="116">2</text>
<text x="172" y="132">Instance</text> <text x="172" y="116">Client</text>
<text x="240" y="164">3</text> <text x="396" y="116">AS</text>
<text x="292" y="164">Req.</text> <text x="84" y="132">RO</text>
<text x="240" y="196">4</text> <text x="108" y="132">ID</text>
<text x="292" y="196">Res.</text> <text x="172" y="132">Instance</text>
<text x="472" y="212">5</text> <text x="240" y="164">3</text>
<text x="472" y="228">AuthN</text> <text x="292" y="164">Req.</text>
<text x="472" y="260">6</text> <text x="240" y="196">4</text>
<text x="472" y="276">AuthZ</text> <text x="292" y="196">Res.</text>
<text x="472" y="308">7</text> <text x="472" y="212">5</text>
<text x="240" y="324">8</text> <text x="472" y="228">AuthN</text>
<text x="308" y="324">Finish</text> <text x="472" y="260">6</text>
<text x="472" y="324">Completed</text> <text x="472" y="276">AuthZ</text>
<text x="240" y="356">9</text> <text x="472" y="308">7</text>
<text x="304" y="356">Cont.</text> <text x="240" y="324">8</text>
<text x="244" y="388">10</text> <text x="308" y="324">Finish</text>
<text x="304" y="388">Subj.</text> <text x="472" y="324">Completed</text>
<text x="100" y="404">11</text> <text x="240" y="356">9</text>
<text x="300" y="404">Info</text> <text x="304" y="356">Cont.</text>
<text x="100" y="420">Return</text> <text x="244" y="388">10</text>
<text x="84" y="436">RO</text> <text x="304" y="388">Subj.</text>
<text x="92" y="452">Info</text> <text x="100" y="404">11</text>
</g> <text x="300" y="404">Info</text>
</svg> <text x="100" y="420">Return</text>
</artwork><artwork type="ascii-art"><![CDATA[ <text x="84" y="436">RO</text>
<text x="92" y="452">Info</text>
</g>
</svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
.----. .----. .----. .----.
| End | | RO | | End | | RO |
| User |<=================(1)== Identify RO ==================>| | | User |<=================(1)== Identify RO ==================>| |
| | | | | | | |
| | +--------+ +--------+ | | | | +--------+ +--------+ | |
| +==(2)==>| Client | | AS | | | | +==(2)==>| Client | | AS | | |
| | RO ID |Instance| | | | | | | RO ID |Instance| | | | |
| | | | | | | | | | | | | | | |
| | | +--(3)-- Req. ---->| | | | | | | +--(3)-- Req. ---->| | | |
| | | | | | | | | | | | | | | |
skipping to change at line 1951 skipping to change at line 2130
| | | |<-(8)--- Finish --+ |Completed| | | | | |<-(8)--- Finish --+ |Completed| |
| | | | | | | | | | | | | | | |
| | | +--(9)--- Cont. -->| | | | | | | +--(9)--- Cont. -->| | | |
| | | | | | | | | | | | | | | |
| | | |<-(10)-- Subj. ---+ | | | | | | |<-(10)-- Subj. ---+ | | |
| |<=(11)==+ | Info | | | | | |<=(11)==+ | Info | | | |
| | Return | | | | | | | | Return | | | | | |
| | RO | | | | | | | | RO | | | | | |
| | Info | | | | | | | | Info | | | | | |
`----` +--------+ +--------+ `----` `----` +--------+ +--------+ `----`
]]></artwork></artset></figure> ]]></artwork>
</artset>
<t>Precondition: The end user is authenticated to the client instance, and the c </figure>
lient <t>Precondition: The end user is authenticated to the client instance,
and the client
instance has an identifier representing the end user that it can present to the AS. instance has an identifier representing the end user that it can present to the AS.
This identifier should be unique to the particular session with the client insta nce This identifier should be unique to the particular session with the client insta nce
and the AS. and the AS.
The client instance is also known to the AS and allowed to access this The client instance is also known to the AS and allowed to access this
advanced functionality where the information of someone other than advanced functionality where the information of someone other than
the end user is returned to the client instance.</t> the end user is returned to the client instance.</t>
<ul spacing="normal"><li>
<t><list style="numbers"> <t>(1) The RO communicates a human-readable
<t>The RO communicates a human-readable
identifier to the end user, such as an email address or account number. This com munication identifier to the end user, such as an email address or account number. This com munication
happens out of band from the protocol, such as over the phone between parties. N ote that the happens out of band from the protocol, such as over the phone between parties. N ote that the
RO is not interacting with the client instance.</t> RO is not interacting with the client instance.</t>
<t>The end user communicates the identifier to the client instance. The means </li>
by which the <li>
identifier is communicated to the client instance is out of scope for this spec <t>(2) The end user communicates the identifier to the client inst
ification.</t> ance. The means by which the
<t>The client instance <xref target="request">requests access to subject infor identifier is communicated to the client instance are out of scope for this spe
mation</xref>. The request includes cification.</t>
the RO's identifier in the <xref target="request-subject">subject information r </li>
equest</xref> <spanx style="verb">sub_ids</spanx> field, <li>
and the end user's identifier in the <xref target="request-user">user informati <t>(3) The client instance requests access to subject information
on field</xref> of the request. (<xref target="request"> </xref>).
The request includes the RO's identifier in the
<tt>sub_ids</tt> field of the subject information request
(<xref target="request-subject"> </xref>)
and the end user's identifier in the <tt>user</tt> field (<xref target="request
-user"> </xref>).
The request includes no interaction start methods, since the end user is not ex pected to The request includes no interaction start methods, since the end user is not ex pected to
be the one interacting with the AS. The request does include the be the one interacting with the AS. The request does include the
<xref target="request-interact-callback-push">push based interaction finish met hod</xref> to allow the AS push-based interaction finish method (<xref target="request-interact-callback-p ush"> </xref>) to allow the AS
to signal to the client instance when the interaction with the RO has concluded .</t> to signal to the client instance when the interaction with the RO has concluded .</t>
<t>The AS sees that the identifier for the end user and subject being requeste </li>
d are different. <li>
<t>(4) The AS sees that the identifiers for the end user and subje
ct being requested are different.
The AS determines that it can reach out to the RO asynchronously for approval. While it The AS determines that it can reach out to the RO asynchronously for approval. While it
is doing so, the AS returns a <xref target="response-continue">continuation res ponse</xref> with a <spanx style="verb">finish</spanx> nonce is doing so, the AS returns a continuation response (<xref target="response-con tinue"> </xref>) with a <tt>finish</tt> nonce
to allow the client instance to continue the grant request after interaction wi th the RO has concluded.</t> to allow the client instance to continue the grant request after interaction wi th the RO has concluded.</t>
<t>The AS contacts the RO and has them authenticate to the system. The means f </li>
or doing this are <li>
outside the scope of this specification, but the identity of the RO is known fr <t>(5) The AS contacts the RO and has them authenticate to the sys
om the subject tem. The means for doing this are
identifier sent in (3).</t> outside the scope of this specification, but the identity of the RO is known fr
<t>The RO is prompted to authorize the end user's request via the client insta om the Subject
nce. Since the end Identifier sent in (3).</t>
user was identified in (3) via the user field, the AS can show this information </li>
to the <li>
<t>(6) The RO is prompted to authorize the end user's request via
the client instance. Since the end
user was identified in (3) via the <tt>user</tt> field, the AS can show this in
formation to the
RO during the authorization request.</t> RO during the authorization request.</t>
<t>The RO completes the authorization with the AS. The AS marks the request as </li>
<em>approved</em>.</t> <li>
<t>The RO pushes the <xref target="interaction-pushback">interaction finish me <t>(7) The RO completes the authorization with the AS. The AS mark
ssage</xref> to the client instance. s the request as <em>approved</em>.</t>
</li>
<li>
<t>(8) The RO pushes the interaction finish message (<xref target=
"interaction-pushback"> </xref>) to the client instance.
Note that in the case the RO cannot be reached or the RO denies the request, th e AS still sends the interaction Note that in the case the RO cannot be reached or the RO denies the request, th e AS still sends the interaction
finish message to the client instance, after which the client instance can nego tiate next steps if possible.</t> finish message to the client instance, after which the client instance can nego tiate next steps if possible.</t>
<t>The client instance validates the interaction finish message and </li>
<xref target="continue-after-interaction">continues the grant request</xref>.</ <li>
t> <t>(9) The client instance validates the interaction finish messag
<t>The AS returns the RO's <xref target="response-subject">subject information e and
</xref> to the client instance.</t> continues the grant request (<xref target="continue-after-interaction"> </xref>
<t>The client instance can display or otherwise utilize the RO's user informat ).</t>
ion in its session </li>
<li>
<t>(10) The AS returns the RO's subject information (<xref target=
"response-subject"> </xref>) to the client instance.</t>
</li>
<li>
<t>(11) The client instance can display or otherwise utilize the R
O's user information in its session
with the end user. Note that since the client instance requested different sets of user with the end user. Note that since the client instance requested different sets of user
information in (3), the client instance does not conflate the end user with the RO.</t> information in (3), the client instance does not conflate the end user with the RO.</t>
</list></t> </li>
</ul>
<t>Additional considerations for asynchronous interactions like this are discuss <t>Additional considerations for asynchronous interactions like this a
ed in re discussed in
<xref target="security-async"/>.</t> <xref target="security-async"/>.</t>
</section>
</section> </section>
</section> </section>
</section> <section anchor="request">
<section anchor="request"><name>Requesting Access</name> <name>Requesting Access</name>
<t>To start a request, the client instance sends an HTTP POST with a JSON
<t>To start a request, the client instance sends an HTTP POST with a <xref targe <xref target="RFC8259"> </xref> document
t="RFC8259">JSON</xref> document
to the grant endpoint of the AS. The grant endpoint is a URI that uniquely ident ifies to the grant endpoint of the AS. The grant endpoint is a URI that uniquely ident ifies
the AS to client instances and serves as the identifier for the AS. The document is a JSON object the AS to client instances and serves as the identifier for the AS. The document is a JSON object
where each field represents a different aspect of the where each field represents a different aspect of the
client instance's request. Each field is described in detail in a section below. client instance's request. Each field is described in detail in a subsection bel
</t> ow.</t>
<dl>
<dl> <dt><tt>access_token</tt> (object / array of objects):</dt>
<dt><spanx style="verb">access_token</spanx> (object / array of objects):</dt> <dd>
<dd> <t>Describes the rights and properties associated with the requested a
<t>Describes the rights and properties associated with the requested access ccess token. <bcp14>REQUIRED</bcp14> if requesting an access token. See <xref ta
token. <bcp14>REQUIRED</bcp14> if requesting an access token. See <xref target=" rget="request-token"/>.</t>
request-token"/>.</t> </dd>
</dd> <dt><tt>subject</tt> (object):</dt>
<dt><spanx style="verb">subject</spanx> (object):</dt> <dd>
<dd> <t>Describes the information about the RO that the client instance is
<t>Describes the information about the RO that the client instance is reques requesting to be returned
ting to be returned
directly in the response from the AS. <bcp14>REQUIRED</bcp14> if requesting su bject information. See <xref target="request-subject"/>.</t> directly in the response from the AS. <bcp14>REQUIRED</bcp14> if requesting su bject information. See <xref target="request-subject"/>.</t>
</dd> </dd>
<dt><spanx style="verb">client</spanx> (object / string):</dt> <dt><tt>client</tt> (object / string):</dt>
<dd> <dd>
<t>Describes the client instance that is making this request, including <t>Describes the client instance that is making this request, includin
the key that the client instance will use to protect this request and any cont g
inuation the key that the client instance will use to protect this request, any continu
requests at the AS and any user-facing information about the client instance u ation
sed in requests at the AS, and any user-facing information about the client instance
used in
interactions. <bcp14>REQUIRED</bcp14>. See <xref target="request-client"/>.</t > interactions. <bcp14>REQUIRED</bcp14>. See <xref target="request-client"/>.</t >
</dd> </dd>
<dt><spanx style="verb">user</spanx> (object / string):</dt> <dt><tt>user</tt> (object / string):</dt>
<dd> <dd>
<t>Identifies the end user to the AS in a manner that the AS can verify, eit <t>Identifies the end user to the AS in a manner that the AS can verif
her directly or y, either directly or
by interacting with the end user to determine their status as the RO. <bcp14>O PTIONAL</bcp14>. See <xref target="request-user"/>.</t> by interacting with the end user to determine their status as the RO. <bcp14>O PTIONAL</bcp14>. See <xref target="request-user"/>.</t>
</dd> </dd>
<dt><spanx style="verb">interact</spanx> (object):</dt> <dt><tt>interact</tt> (object):</dt>
<dd> <dd>
<t>Describes the modes that the client instance supports for allowing the RO <t>Describes the modes that the client instance supports for allowing
to interact with the the RO to interact with the
AS and modes for the client instance to receive updates when interaction is co mplete. <bcp14>REQUIRED</bcp14> if interaction is supported. See <xref target="r equest-interact"/>.</t> AS and modes for the client instance to receive updates when interaction is co mplete. <bcp14>REQUIRED</bcp14> if interaction is supported. See <xref target="r equest-interact"/>.</t>
</dd> </dd>
</dl> </dl>
<t>Additional members of this request object can be defined by extensions using
the <xref target="IANA-grant-request">GNAP Grant Request Parameters Registry</xr
ef>.</t>
<t>A non-normative example of a grant request is below:</t>
<figure><sourcecode type="json"><![CDATA[ <t>Additional members of this request object can be defined by extensions
using the "GNAP Grant Request Parameters" registry (<xref target="IANA-grant-req
uest"></xref>).</t>
<t>A non-normative example of a grant request is below:</t>
<sourcecode type="json"><![CDATA[
{ {
"access_token": { "access_token": {
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "actions": [
"read", "read",
"write", "write",
"dolphin" "dolphin"
], ],
skipping to change at line 2096 skipping to change at line 2293
"method": "redirect", "method": "redirect",
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
}, },
"subject": { "subject": {
"sub_id_formats": ["iss_sub", "opaque"], "sub_id_formats": ["iss_sub", "opaque"],
"assertion_formats": ["id_token"] "assertion_formats": ["id_token"]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Sending a request to the grant endpoint creates a grant request in the
<t>Sending a request to the grant endpoint creates a grant request in the <em>pr <em>processing</em> state. The AS processes this request to determine whether in
ocessing</em> state. The AS processes this request to determine whether interact teraction or authorization are necessary (moving to the <em>pending</em> state)
ion or authorization are necessary (moving to the <em>pending</em> state), or if or if access can be granted immediately (moving to the <em>approved</em> state).
access can be granted immediately (moving to the <em>approved</em> state).</t> </t>
<t>The request <bcp14>MUST</bcp14> be sent as a JSON object in the content
<t>The request <bcp14>MUST</bcp14> be sent as a JSON object in the content of th of the HTTP
e HTTP POST request with Content-Type <tt>application/json</tt>. A key proofing mechani
POST request with Content-Type <spanx style="verb">application/json</spanx>. A k sm <bcp14>MAY</bcp14>
ey proofing mechanism <bcp14>MAY</bcp14>
define an alternative content type, as long as the content is formed from define an alternative content type, as long as the content is formed from
the JSON object. For example, the attached JWS key proofing mechanism (see <xref target="attached-jws"/>) places the JSON object the JSON object. For example, the attached JSON Web Signature (JWS) key proofing mechanism (see <xref target="attached-jws"/>) places the JSON object
into the payload of a JWS wrapper, which is in turn sent as the message content. </t> into the payload of a JWS wrapper, which is in turn sent as the message content. </t>
<section anchor="request-token">
<section anchor="request-token"><name>Requesting Access to Resources</name> <name>Requesting Access to Resources</name>
<t>If the client instance is requesting one or more access tokens for th
<t>If the client instance is requesting one or more access tokens for the e
purpose of accessing an API, the client instance <bcp14>MUST</bcp14> include an purpose of accessing an API, the client instance <bcp14>MUST</bcp14> include an
<spanx style="verb">access_token</spanx> <tt>access_token</tt>
field. This field <bcp14>MUST</bcp14> be an object (for a <xref target="request- field. This field <bcp14>MUST</bcp14> be an object (for a single access token (<
token-single">single access token</xref>) or xref target="request-token-single"> </xref>)) or
an array of these objects (for <xref target="request-token-multiple">multiple ac an array of these objects (for multiple access tokens (<xref target="request-tok
cess tokens</xref>), en-multiple"> </xref>)),
as described in the following sections.</t> as described in the following subsections.</t>
<section anchor="request-token-single">
<section anchor="request-token-single"><name>Requesting a Single Access Token</n <name>Requesting a Single Access Token</name>
ame> <t>To request a single access token, the client instance sends an <tt>
access_token</tt> object
<t>To request a single access token, the client instance sends an <spanx style="
verb">access_token</spanx> object
composed of the following fields.</t> composed of the following fields.</t>
<dl>
<dl> <dt><tt>access</tt> (array of objects/strings):</dt>
<dt><spanx style="verb">access</spanx> (array of objects/strings):</dt> <dd>
<dd> <t>Describes the rights that the client instance is requesting for
<t>Describes the rights that the client instance is requesting for the acces the access token to be
s token to be
used at the RS. <bcp14>REQUIRED</bcp14>. See <xref target="resource-access-rig hts"/>.</t> used at the RS. <bcp14>REQUIRED</bcp14>. See <xref target="resource-access-rig hts"/>.</t>
</dd> </dd>
<dt><spanx style="verb">label</spanx> (string):</dt> <dt><tt>label</tt> (string):</dt>
<dd> <dd>
<t>A unique name chosen by the client instance to refer to the resulting acc
ess token. The value of this <t>A unique name chosen by the client instance to refer to the res
ulting access token. The value of this
field is opaque to the AS and is not intended to be exposed to or used by the end user. If this field field is opaque to the AS and is not intended to be exposed to or used by the end user. If this field
is included in the request, the AS <bcp14>MUST</bcp14> include the same label is included in the request, the AS <bcp14>MUST</bcp14> include the same label
in the <xref target="response-token">token response</xref>. in the token response (<xref target="response-token"> </xref>).
<bcp14>REQUIRED</bcp14> if used as part of a <xref target="request-token-multi <bcp14>REQUIRED</bcp14> if used as part of a request for multiple access token
ple">multiple access token request</xref>, s (<xref target="request-token-multiple"> </xref>);
<bcp14>OPTIONAL</bcp14> otherwise.</t> <bcp14>OPTIONAL</bcp14> otherwise.</t>
</dd> </dd>
<dt><spanx style="verb">flags</spanx> (array of strings):</dt> <dt><tt>flags</tt> (array of strings):</dt>
<dd> <dd>
<t>A set of flags that indicate desired attributes or behavior to be attache <t>A set of flags that indicate desired attributes or behavior to
d to the access token by the be attached to the access token by the
AS. <bcp14>OPTIONAL</bcp14>.</t> AS. <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>The values of the <tt>flags</tt> field defined by this specificatio
<t>The values of the <spanx style="verb">flags</spanx> field defined by this spe n are as follows:</t>
cification are as follows:</t> <dl>
<dt><tt>"bearer"</tt>:</dt>
<dl> <dd>
<dt><spanx style="verb">"bearer"</spanx>:</dt> <t>If this flag is included, the access token being requested is a
<dd> bearer token.
<t>If this flag is included, the access token being requested is a bearer to
ken.
If this flag is omitted, the access token is bound to the key used If this flag is omitted, the access token is bound to the key used
by the client instance in this request (or that key's most recent rotation) by the client instance in this request (or that key's most recent rotation),
and the access token <bcp14>MUST</bcp14> be presented using the same key and p roofing method. and the access token <bcp14>MUST</bcp14> be presented using the same key and p roofing method.
Methods for presenting bound and bearer access tokens are described Methods for presenting bound and bearer access tokens are described
in <xref target="use-access-token"/>. See <xref target="security-bearer-tokens "/> for additional in <xref target="use-access-token"/>. See <xref target="security-bearer-tokens "/> for additional
considerations on the use of bearer tokens.</t> considerations on the use of bearer tokens.</t>
</dd> </dd>
</dl> </dl>
<t>Flag values <bcp14>MUST NOT</bcp14> be included more than once. If
<t>Flag values <bcp14>MUST NOT</bcp14> be included more than once. If the reques the request includes a flag value multiple times, the AS <bcp14>MUST</bcp14> ret
t includes a flag value multiple times, the AS <bcp14>MUST</bcp14> return an <sp urn an <tt>invalid_flag</tt> error defined in <xref target="response-error"/>.</
anx style="verb">invalid_flag</spanx> error defined in <xref target="response-er t>
ror"/>.</t> <t>Additional flags can be defined by extensions using the "GNAP Acces
s Token Flags" registry (<xref target="IANA-token-flags"></xref>).</t>
<t>Additional flags can be defined by extensions using the <xref target="IANA-to <t>In the following non-normative example, the client instance is requ
ken-flags">GNAP Access Token Flags Registry</xref>.</t> esting access to a complex resource
<t>In the following non-normative example, the client instance is requesting acc
ess to a complex resource
described by a pair of access request object.</t> described by a pair of access request object.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"access_token": { "access_token": {
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "actions": [
"read", "read",
"write", "write",
"delete" "delete"
], ],
"locations": [ "locations": [
skipping to change at line 2199 skipping to change at line 2386
], ],
"datatypes": [ "datatypes": [
"data", "data",
"pictures", "pictures",
"walrus whiskers" "walrus whiskers"
] ]
} }
], ],
"label": "token1-23" "label": "token1-23"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If access is approved, the resulting access token is valid for the
<t>If access is approved, the resulting access token is valid for the described described resource.
resource. Since the <tt>bearer</tt> flag is not provided in this example, the token is bou
Since the "bearer" flag is not provided in this example, the token is bound to t nd to the client instance's key (or its most recent rotation). The token
he client instance's key (or its most recent rotation). The token
is labeled "token1-23". The token response structure is described in <xref targe t="response-token-single"/>.</t> is labeled "token1-23". The token response structure is described in <xref targe t="response-token-single"/>.</t>
</section>
<section anchor="request-token-multiple">
<name>Requesting Multiple Access Tokens</name>
</section> <t>To request that multiple access tokens be returned in a single resp
<section anchor="request-token-multiple"><name>Requesting Multiple Access Tokens onse, the
</name> client instance sends an array of objects as the value of the <tt>access_token</
tt>
<t>To request multiple access tokens to be returned in a single response, the
client instance sends an array of objects as the value of the <spanx style="verb
">access_token</spanx>
parameter. Each object <bcp14>MUST</bcp14> conform to the request format for a s ingle parameter. Each object <bcp14>MUST</bcp14> conform to the request format for a s ingle
access token request, as specified in access token request, as specified in
<xref target="request-token-single">requesting a single access token</xref>. <xref target="request-token-single"></xref>.
Additionally, each object in the array <bcp14>MUST</bcp14> include the <spanx st Additionally, each object in the array <bcp14>MUST</bcp14> include the <tt>label
yle="verb">label</spanx> field, and </tt> field, and
all values of these fields <bcp14>MUST</bcp14> be unique within the request. If the all values of these fields <bcp14>MUST</bcp14> be unique within the request. If the
client instance does not include a <spanx style="verb">label</spanx> value for a client instance does not include a <tt>label</tt> value for any entry in the
ny entry in the array or the values of the <tt>label</tt> field are not unique within the array,
array, or the values of the <spanx style="verb">label</spanx> field are not uniq
ue within the array,
the AS <bcp14>MUST</bcp14> return an "invalid_request" error (<xref target="resp onse-error"/>).</t> the AS <bcp14>MUST</bcp14> return an "invalid_request" error (<xref target="resp onse-error"/>).</t>
<t>The following non-normative example shows a request for two
<t>The following non-normative example shows a request for two separate access tokens: <tt>token1</tt> and <tt>token2</tt>.</t>
separate access tokens, <spanx style="verb">token1</spanx> and <spanx style="ver <sourcecode type="json"><![CDATA[
b">token2</spanx>.</t>
<figure><sourcecode type="json"><![CDATA[
"access_token": [ "access_token": [
{ {
"label": "token1", "label": "token1",
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "actions": [
"read", "read",
"write", "write",
"dolphin" "dolphin"
skipping to change at line 2268 skipping to change at line 2452
"datatypes": [ "datatypes": [
"data", "data",
"pictures", "pictures",
"walrus whiskers" "walrus whiskers"
] ]
} }
], ],
"flags": [ "bearer" ] "flags": [ "bearer" ]
} }
] ]
]]></sourcecode>
]]></sourcecode></figure> <t>All approved access requests are returned in the response structure for
multiple access tokens (<xref target="response-token-multiple"> </xref>) using
<t>All approved access requests are returned in the the values of the <tt>label</tt> fields in the request.</t>
<xref target="response-token-multiple">multiple access token response</xref> str </section>
ucture using </section>
the values of the <spanx style="verb">label</spanx> fields in the request.</t> <section anchor="request-subject">
<name>Requesting Subject Information</name>
</section> <t>If the client instance is requesting information about the RO from
</section> the AS, it sends a <tt>subject</tt> field as a JSON object. This object <bcp14>M
<section anchor="request-subject"><name>Requesting Subject Information</name> AY</bcp14>
<t>If the client instance is requesting information about the RO from
the AS, it sends a <spanx style="verb">subject</spanx> field as a JSON object. T
his object <bcp14>MAY</bcp14>
contain the following fields.</t> contain the following fields.</t>
<dl>
<dl> <dt><tt>sub_id_formats</tt> (array of strings):</dt>
<dt><spanx style="verb">sub_id_formats</spanx> (array of strings):</dt> <dd>
<dd> <t>An array of Subject Identifier subject formats
<t>An array of subject identifier subject formats
requested for the RO, as defined by <xref target="RFC9493"/>. requested for the RO, as defined by <xref target="RFC9493"/>.
<bcp14>REQUIRED</bcp14> if subject identifiers are requested.</t> <bcp14>REQUIRED</bcp14> if Subject Identifiers are requested.</t>
</dd> </dd>
<dt><spanx style="verb">assertion_formats</spanx> (array of strings):</dt> <dt><tt>assertion_formats</tt> (array of strings):</dt>
<dd> <dd>
<t>An array of requested assertion formats. Possible values include
<spanx style="verb">id_token</spanx> for an OpenID Connect ID Token (<xref tar <t>An array of requested assertion formats. Possible values include
get="OIDC"/>) and <spanx style="verb">saml2</spanx> for a SAML 2 assertion (<xre <tt>id_token</tt> for an OpenID Connect ID Token <xref target="OIDC"/> and <tt
f target="SAML2"/>). Additional >saml2</tt> for a Security Assertion Markup Language (SAML) 2 assertion <xref ta
assertion formats are defined by the <xref target="IANA-assertion-formats">GNA rget="SAML2"/>. Additional
P Assertion Formats Registry</xref>. assertion formats can be defined in the "GNAP Assertion Formats" registry (<xr
ef target="IANA-assertion-formats"></xref>).
<bcp14>REQUIRED</bcp14> if assertions are requested.</t> <bcp14>REQUIRED</bcp14> if assertions are requested.</t>
</dd> </dd>
<dt><spanx style="verb">sub_ids</spanx> (array of objects):</dt> <dt><tt>sub_ids</tt> (array of objects):</dt>
<dd> <dd>
<t>An array of subject identifiers representing the subject for which inform <t>An array of Subject Identifiers representing the subject for whic
ation h information
is being requested. Each object is a subject identifier as defined by is being requested. Each object is a Subject Identifier as defined by
<xref target="RFC9493"/>. All identifiers in the <spanx style="verb">sub_ids</ <xref target="RFC9493"/>. All identifiers in the <tt>sub_ids</tt> array <bcp14
spanx> array <bcp14>MUST</bcp14> identify >MUST</bcp14> identify
the same subject. If omitted, the AS <bcp14>SHOULD</bcp14> assume the same subject. If omitted, the AS <bcp14>SHOULD</bcp14> assume
that subject information requests are about the current user and <bcp14>SHOULD </bcp14> that subject information requests are about the current user and <bcp14>SHOULD </bcp14>
require direct interaction or proof of presence before releasing information. <bcp14>OPTIONAL</bcp14>.</t> require direct interaction or proof of presence before releasing information. <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>Additional fields can be defined in the "GNAP Subject Information Req
<t>Additional fields are defined in the <xref target="IANA-subject-request">GNAP uest Fields" registry (<xref target="IANA-subject-request"></xref>).</t>
Subject Information Request Fields Registry</xref>.</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"subject": { "subject": {
"sub_id_formats": [ "iss_sub", "opaque" ], "sub_id_formats": [ "iss_sub", "opaque" ],
"assertion_formats": [ "id_token", "saml2" ] "assertion_formats": [ "id_token", "saml2" ]
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS can determine the RO's identity and permission for releasing
<t>The AS can determine the RO's identity and permission for releasing this information through interaction with the RO (<xref target="authorization">
this information through <xref target="authorization">interaction with the RO</x </xref>),
ref>, AS policies, or assertions presented by the client instance (<xref target="reque
AS policies, or <xref target="request-user">assertions presented by the client i st-user"> </xref>). If
nstance</xref>. If this is determined positively, the AS <bcp14>MAY</bcp14> return the RO's informa
this is determined positively, the AS <bcp14>MAY</bcp14> <xref target="response- tion in its response (<xref target="response-subject"> </xref>)
subject">return the RO's information in its response</xref>
as requested.</t> as requested.</t>
<t>Subject Identifier types requested by the client instance serve only
<t>Subject identifier types requested by the client instance serve only to ident to identify
ify
the RO in the context of the AS and can't be used as communication the RO in the context of the AS and can't be used as communication
channels by the client instance, as discussed in <xref target="response-subject" />.</t> channels by the client instance, as discussed in <xref target="response-subject" />.</t>
</section>
<section anchor="request-client">
<name>Identifying the Client Instance</name>
</section> <t>When sending a new grant request to the AS, the client instance <bcp14
<section anchor="request-client"><name>Identifying the Client Instance</name> >MUST</bcp14> identify
itself by including its client information in the <tt>client</tt> field of the r
<t>When sending new grant request to the AS, the client instance <bcp14>MUST</bc equest and by signing the
p14> identify
itself by including its client information in the <spanx style="verb">client</sp
anx> field of the request and by signing the
request with its unique key as described in <xref target="binding-keys"/>. Note that once a request with its unique key as described in <xref target="binding-keys"/>. Note that once a
grant has been created and is in the <em>pending</em> or <em>accepted</em> state s, the AS can grant has been created and is in either the <em>pending</em> or the <em>approved </em> state, the AS can
determine which client is associated with the grant by dereferencing the determine which client is associated with the grant by dereferencing the
continuation access token sent in the <xref target="continue-request">continuati continuation access token sent in the continuation request (<xref target="contin
on request</xref>. ue-request"> </xref>).
As a consequence, the <spanx style="verb">client</spanx> field is not sent or ac As a consequence, the <tt>client</tt> field is not sent or accepted for continua
cepted for continuation requests.</t> tion requests.</t>
<t>Client information is sent by value as an object or by reference as a
<t>Client information is sent by value as an object or by reference as a string string (see <xref target="request-instance"/>).</t>
(see <xref target="request-instance"/>).</t> <t>When client instance information is sent
by value, the <tt>client</tt> field of the request consists of a JSON
<t>When client instance information is sent
by value, the <spanx style="verb">client</spanx> field of the request consists o
f a JSON
object with the following fields.</t> object with the following fields.</t>
<dl>
<dl> <dt><tt>key</tt> (object / string):</dt>
<dt><spanx style="verb">key</spanx> (object / string):</dt> <dd>
<dd> <t>The public key of the client instance to be used in this request
<t>The public key of the client instance to be used in this request as as
described in <xref target="key-format"/> or a reference to a key as described in <xref target="key-format"/> or a reference to a key as
described in <xref target="key-reference"/>. <bcp14>REQUIRED</bcp14>.</t> described in <xref target="key-reference"/>. <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">class_id</spanx> (string):</dt> <dt><tt>class_id</tt> (string):</dt>
<dd> <dd>
<t>An identifier string that the AS can use to identify the <t>An identifier string that the AS can use to identify the
client software comprising this client instance. The contents client software comprising this client instance. The contents
and format of this field are up to the AS. <bcp14>OPTIONAL</bcp14>.</t> and format of this field are up to the AS. <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">display</spanx> (object):</dt> <dt><tt>display</tt> (object):</dt>
<dd> <dd>
<t>An object containing additional information that the AS <t>An object containing additional information that the AS
<bcp14>MAY</bcp14> display to the RO during interaction, authorization, <bcp14>MAY</bcp14> display to the RO during interaction, authorization,
and management. <bcp14>OPTIONAL</bcp14>. (<xref target="request-display"/>)</t and management. <bcp14>OPTIONAL</bcp14>. See <xref target="request-display"/>.
> </t>
</dd> </dd>
</dl> </dl>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"client": { "client": {
"key": { "key": {
"proof": "httpsig", "proof": "httpsig",
"jwk": { "jwk": {
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"kid": "xyz-1", "kid": "xyz-1",
"alg": "RS256", "alg": "RS256",
"n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..."
} }
}, },
"class_id": "web-server-1234", "class_id": "web-server-1234",
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://example.net/client" "uri": "https://example.net/client"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Additional fields can be defined in the "GNAP Client Instance Fields"
<t>Additional fields are defined in the <xref target="IANA-client-instance">GNAP registry (<xref target="IANA-client-instance"></xref>).</t>
Client Instance Fields Registry</xref>.</t> <t>Absent additional attestations, profiles, or trust mechanisms, both t
he <tt>display</tt> and <tt>class_id</tt> fields are self-declarative, presented
<t>Absent additional attestations, profiles, or trust mechanisms, both the <span by the client instance. The AS needs to exercise caution in their interpretatio
x style="verb">display</spanx> and <spanx style="verb">class_id</spanx> fields a n, taking them as a hint but not as absolute truth. The <tt>class_id</tt> field
re self-declarative, presented by the client instance. The AS needs to exercise can be used in a variety of ways to help the AS make sense of the particular con
caution in their interpretation, taking them as a hint but not as absolute truth text in which the client instance is operating. In corporate environments, for e
. The <spanx style="verb">class_id</spanx> field can be used in a variety of way xample, different levels of trust might apply depending on security policies. Th
s to help the AS make sense of the particular context in which the client instan is field aims to help the AS adjust its own access decisions for different class
ce is operating. In corporate environments, for example, different levels of tru es of client software. It is possible to configure a set of values and rules dur
st might apply depending on security policies. This field aims to help the AS ad ing a pre-registration and then have the client instances provide them later in
just its own access decisions for different classes of client software. It is po runtime as a hint to the AS. In other cases, the client runs with a specific AS
ssible to configure a set of values and rules during a pre-registration, and the in mind, so a single hardcoded value would be acceptable (for instance, a set-to
n have the client instances provide them later in runtime as a hint to the AS. I p box with a <tt>class_id</tt> claiming to be "FooBarTV version 4"). While the c
n other cases, the client runs with a specific AS in mind, so a single hardcoded lient instance may not have contacted the AS yet, the value of this <tt>class_id
value would acceptable (for instance, a set top box with a <spanx style="verb"> </tt> field can be evaluated by the AS according to a broader context of dynamic
class_id</spanx> claiming to be "FooBarTV version 4"). While the client instance use, alongside other related information available elsewhere (for instance, cor
may not have contacted the AS yet, the value of this <spanx style="verb">class_ responding fields in a certificate). If the AS is not able to interpret or valid
id</spanx> field can be evaluated by the AS according to a broader context of dy ate the class_id field, it <bcp14>MUST</bcp14> either return an <tt>invalid_clie
namic use, alongside other related information available elsewhere (for instance nt</tt> error (<xref target="response-error"/>) or interpret the request as if t
, corresponding fields in a certificate). If the AS is not able to interpret or he class_id were not present. See additional discussion of client instance imper
validate the class_id field, it <bcp14>MUST</bcp14> either return an <spanx styl sonation in <xref target="security-impersonation"/>.</t>
e="verb">invalid_client</spanx> error (<xref target="response-error"/>) or inter <t>The client instance <bcp14>MUST</bcp14> prove possession of any prese
pret the request as if the class_id were not present. See additional discussion nted key by the proofing mechanism
of client instance impersonation in <xref target="security-impersonation"/>.</t>
<t>The client instance <bcp14>MUST</bcp14> prove possession of any presented key
by the <spanx style="verb">proof</spanx> mechanism
associated with the key in the request. Key proofing methods associated with the key in the request. Key proofing methods
are defined in the <xref target="IANA-key-proof-methods">GNAP Key Proofing Metho ds Registry</xref> and an initial set of methods are defined in the "GNAP Key Proofing Methods" registry (<xref target="IANA-key- proof-methods"></xref>), and an initial set of methods
is described in <xref target="binding-keys"/>.</t> is described in <xref target="binding-keys"/>.</t>
<t>If the same public key is sent by value on different access requests,
<t>If the same public key is sent by value on different access requests, the AS the AS <bcp14>MUST</bcp14>
<bcp14>MUST</bcp14>
treat these requests as coming from the same client instance for purposes treat these requests as coming from the same client instance for purposes
of identification, authentication, and policy application.</t> of identification, authentication, and policy application.</t>
<t>If the AS does not know the client instance's public key ahead of tim
<t>If the AS does not know the client instance's public key ahead of time, the A e, the AS
S
can choose how to process the unknown key. Common approaches include:</t> can choose how to process the unknown key. Common approaches include:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>Allowing the request and requiring RO authorization in a trust-on-first-use <t>Allowing the request and requiring RO authorization in a trust-on
model</t> -first-use model</t>
<t>Limiting the client's requested access to only certain APIs and information </li>
</t> <li>
<t>Denying the request entirely by returning an <spanx style="verb">invalid_cl <t>Limiting the client's requested access to only certain APIs and i
ient</spanx> error (<xref target="response-error"/>)</t> nformation</t>
</list></t> </li>
<li>
<t>The client instance <bcp14>MUST NOT</bcp14> send a symmetric key by value in <t>Denying the request entirely by returning an <tt>invalid_client</
the <spanx style="verb">key</spanx> field of the request, as doing so would expo tt> error (<xref target="response-error"/>)</t>
se </li>
</ul>
<t>The client instance <bcp14>MUST NOT</bcp14> send a symmetric key by v
alue in the <tt>key</tt> field of the request, as doing so would expose
the key directly instead of simply proving possession of it. See considerations on symmetric keys the key directly instead of simply proving possession of it. See considerations on symmetric keys
in <xref target="security-symmetric"/>. To use symmetric keys, the client instan ce can send the <spanx style="verb">key</spanx> by reference (<xref target="key- reference"/>) or in <xref target="security-symmetric"/>. To use symmetric keys, the client instan ce can send the <tt>key</tt> by reference (<xref target="key-reference"/>) or
send the entire client identity by reference (<xref target="request-instance"/>) .</t> send the entire client identity by reference (<xref target="request-instance"/>) .</t>
<t>The client instance's key can be pre-registered with the AS ahead of
<t>The client instance's key can be pre-registered with the AS ahead of time and time and associated
associated
with a set of policies and allowable actions pertaining to that client. If this pre-registration with a set of policies and allowable actions pertaining to that client. If this pre-registration
includes other fields that can occur in the <spanx style="verb">client</spanx> r includes other fields that can occur in the <tt>client</tt> request object descr
equest object described in this section, ibed in this section,
such as <spanx style="verb">class_id</spanx> or <spanx style="verb">display</spa such as <tt>class_id</tt> or <tt>display</tt>, the pre-registered values <bcp14>
nx>, the pre-registered values <bcp14>MUST</bcp14> take precedence over any valu MUST</bcp14> take precedence over any values
es
given at runtime. Additional fields sent during a request but not present in a p re-registered given at runtime. Additional fields sent during a request but not present in a p re-registered
client instance record at the AS <bcp14>SHOULD NOT</bcp14> be added to the clien t's pre-registered record. client instance record at the AS <bcp14>SHOULD NOT</bcp14> be added to the clien t's pre-registered record.
See additional considerations regarding client instance impersonation in <xref t arget="security-impersonation"/>.</t> See additional considerations regarding client instance impersonation in <xref t arget="security-impersonation"/>.</t>
<t>A client instance that is capable of talking to multiple ASes <bcp14>
<t>A client instance that is capable of talking to multiple AS's <bcp14>SHOULD</ SHOULD</bcp14> use a different key for each
bcp14> use a different key for each AS to prevent a class of mix-up attacks as described in <xref target="security-c
AS to prevent a class of mix-up attacks as described in <xref target="security-c uckoo"/>, unless other mechanisms
uckoo"/> unless other mechanisms
can be used to assure the identity of the AS for a given request.</t> can be used to assure the identity of the AS for a given request.</t>
<section anchor="request-instance">
<section anchor="request-instance"><name>Identifying the Client Instance by Refe <name>Identifying the Client Instance by Reference</name>
rence</name> <t>If the client instance has an instance identifier that the AS can u
se to determine
<t>If the client instance has an instance identifier that the AS can use to dete
rmine
appropriate key information, the client instance can send this instance appropriate key information, the client instance can send this instance
identifier as a direct reference value in lieu of the <spanx style="verb">client </spanx> object. identifier as a direct reference value in lieu of the <tt>client</tt> object.
The instance identifier <bcp14>MAY</bcp14> be assigned to a client instance at r untime The instance identifier <bcp14>MAY</bcp14> be assigned to a client instance at r untime
through a grant response (<xref target="response-dynamic-handles"/>) or <bcp14>M AY</bcp14> be obtained in another fashion, through a grant response (<xref target="response-dynamic-handles"/>) or <bcp14>M AY</bcp14> be obtained in another fashion,
such as a static registration process at the AS.</t> such as a static registration process at the AS.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"client": "client-541-ab" "client": "client-541-ab"
]]></sourcecode></figure> ]]></sourcecode>
<t>When the AS receives a request with an instance identifier, the AS
<t>When the AS receives a request with an instance identifier, the AS <bcp14>MUS <bcp14>MUST</bcp14>
T</bcp14> ensure that the key used to sign the request (<xref target="binding-keys"> </xre
ensure that the key used to <xref target="binding-keys">sign the request</xref> f>) is
is
associated with the instance identifier.</t> associated with the instance identifier.</t>
<t>If the AS does not recognize the instance identifier, the request <
<t>If the AS does not recognize the instance identifier, the request <bcp14>MUST bcp14>MUST</bcp14> be rejected
</bcp14> be rejected with an <tt>invalid_client</tt> error (<xref target="response-error"/>).</t>
with an <spanx style="verb">invalid_client</spanx> error (<xref target="response </section>
-error"/>).</t> <section anchor="request-display">
<name>Providing Displayable Client Instance Information</name>
</section> <t>If the client instance has additional information to display to the
<section anchor="request-display"><name>Providing Displayable Client Instance In RO
formation</name>
<t>If the client instance has additional information to display to the RO
during any interactions at the AS, it <bcp14>MAY</bcp14> send that information i n the during any interactions at the AS, it <bcp14>MAY</bcp14> send that information i n the
"display" field. This field is a JSON object that declares information "display" field. This field is a JSON object that declares information
to present to the RO during any interactive sequences.</t> to present to the RO during any interactive sequences.</t>
<dl>
<dl> <dt><tt>name</tt> (string):</dt>
<dt><spanx style="verb">name</spanx> (string):</dt> <dd>
<dd> <t>Display name of the client software. <bcp14>RECOMMENDED</bcp14>
<t>Display name of the client software. <bcp14>RECOMMENDED</bcp14>.</t> .</t>
</dd> </dd>
<dt><spanx style="verb">uri</spanx> (string):</dt> <dt><tt>uri</tt> (string):</dt>
<dd> <dd>
<t>User-facing information about the client software, such as a web page. Th <t>User-facing information about the client software, such as a we
is URI <bcp14>MUST</bcp14> be an absolute URI. <bcp14>OPTIONAL</bcp14>.</t> b page. This URI <bcp14>MUST</bcp14> be an absolute URI. <bcp14>OPTIONAL</bcp14>
</dd> .</t>
<dt><spanx style="verb">logo_uri</spanx> (string)</dt> </dd>
<dd> <dt><tt>logo_uri</tt> (string):</dt>
<t>Display image to represent the client software. This URI <bcp14>MUST</bcp <dd>
14> be an absolute URI. The logo <bcp14>MAY</bcp14> be passed by value by using <t>Display image to represent the client software. This URI <bcp14
a data: URI <xref target="RFC2397"/> referencing an image mediatype. <bcp14>OPTI >MUST</bcp14> be an absolute URI. The logo <bcp14>MAY</bcp14> be passed by value
ONAL</bcp14>.</t> by using a data: URI <xref target="RFC2397"/> referencing an image media type.
</dd> <bcp14>OPTIONAL</bcp14>.</t>
</dl> </dd>
</dl>
<figure><sourcecode type="json"><![CDATA[ <sourcecode type="json"><![CDATA[
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://example.net/client", "uri": "https://example.net/client",
"logo_uri": "data:image/png;base64,Eeww...=" "logo_uri": "data:image/png;base64,Eeww...="
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Additional display fields can be defined in the "GNAP Client Instan
<t>Additional display fields are defined by the <xref target="IANA-client-instan ce Display Fields" registry (<xref target="IANA-client-instance-display"></xref>
ce-display">GNAP Client Instance Display Fields Registry</xref>.</t> ).</t>
<t>The AS <bcp14>SHOULD</bcp14> use these values during interaction wi
<t>The AS <bcp14>SHOULD</bcp14> use these values during interaction with the RO. th the RO.
The values are for informational purposes only and <bcp14>MUST NOT</bcp14> The values are for informational purposes only and <bcp14>MUST NOT</bcp14>
be taken as authentic proof of the client instance's identity or source. be taken as authentic proof of the client instance's identity or source.
The AS <bcp14>MAY</bcp14> restrict display values to specific client instances, as identified The AS <bcp14>MAY</bcp14> restrict display values to specific client instances, as identified
by their keys in <xref target="request-client"/>. See additional considerations for displayed by their keys in <xref target="request-client"/>. See additional considerations for displayed
client information in <xref target="security-impersonation"/> and for the <spanx style="verb">logo_uri</spanx> in client information in <xref target="security-impersonation"/> and for the <tt>lo go_uri</tt> in
particular in <xref target="security-client-hosted-logo"/>.</t> particular in <xref target="security-client-hosted-logo"/>.</t>
</section>
</section> <section anchor="request-key-authenticate">
<section anchor="request-key-authenticate"><name>Authenticating the Client Insta <name>Authenticating the Client Instance</name>
nce</name> <t>If the presented key is known to the AS and is associated with a si
ngle instance
<t>If the presented key is known to the AS and is associated with a single insta
nce
of the client software, the process of presenting a key and proving possession o f that key of the client software, the process of presenting a key and proving possession o f that key
is sufficient to authenticate the client instance to the AS. The AS <bcp14>MAY</ bcp14> associate policies is sufficient to authenticate the client instance to the AS. The AS <bcp14>MAY</ bcp14> associate policies
with the client instance identified by this key, such as limiting which resource s with the client instance identified by this key, such as limiting which resource s
can be requested and which interaction methods can be used. For example, only can be requested and which interaction methods can be used. For example, only
specific client instances with certain known keys might be trusted with access t okens without the specific client instances with certain known keys might be trusted with access t okens without the
AS interacting directly with the RO as in <xref target="example-no-user"/>.</t> AS interacting directly with the RO, as in <xref target="example-no-user"/>.</t>
<t>The presentation of a key allows the AS to strongly associate multi
<t>The presentation of a key allows the AS to strongly associate multiple ple
successive requests from the same client instance with each other. This successive requests from the same client instance with each other. This
is true when the AS knows the key ahead of time and can use the key to is true when the AS knows the key ahead of time and can use the key to
authenticate the client instance, but also if the key is authenticate the client instance, but it is also true if the key is
ephemeral and created just for this series of requests. As such the ephemeral and created just for this series of requests. As such, the
AS <bcp14>MAY</bcp14> allow for client instances to make requests with unknown k eys. This pattern allows AS <bcp14>MAY</bcp14> allow for client instances to make requests with unknown k eys. This pattern allows
for ephemeral client instances, such as single-page applications, and client sof for ephemeral client instances (such as single-page applications) and client sof
tware with many individual long-lived instances, tware with many individual long-lived instances
such as mobile applications, to generate key pairs per instance and use the keys (such as mobile applications) to generate key pairs per instance and use the key
within s within
the protocol without having to go through a separate registration step. the protocol without having to go through a separate registration step.
The AS <bcp14>MAY</bcp14> limit which capabilities are made available to client instances The AS <bcp14>MAY</bcp14> limit which capabilities are made available to client instances
with unknown keys. For example, the AS could have a policy saying that only with unknown keys. For example, the AS could have a policy saying that only
previously-registered client instances can request particular resources, or that all previously registered client instances can request particular resources or that all
client instances with unknown keys have to be interactively approved by an RO.</ t> client instances with unknown keys have to be interactively approved by an RO.</ t>
</section>
</section> </section>
</section> <section anchor="request-user">
<section anchor="request-user"><name>Identifying the User</name> <name>Identifying the User</name>
<t>If the client instance knows the identity of the end user through one
<t>If the client instance knows the identity of the end user through one or more or more
identifiers or assertions, the client instance <bcp14>MAY</bcp14> send that info rmation to the identifiers or assertions, the client instance <bcp14>MAY</bcp14> send that info rmation to the
AS in the "user" field. The client instance <bcp14>MAY</bcp14> pass this informa AS in the <tt>user</tt> field. The client instance <bcp14>MAY</bcp14> pass this
tion by value information by value
or by reference (See <xref target="request-user-reference"/>).</t> or by reference (see <xref target="request-user-reference"/>).</t>
<dl>
<dl> <dt><tt>sub_ids</tt> (array of objects):</dt>
<dt><spanx style="verb">sub_ids</spanx> (array of objects):</dt> <dd>
<dd> <t>An array of Subject Identifiers for the
<t>An array of subject identifiers for the
end user, as defined by <xref target="RFC9493"/>. end user, as defined by <xref target="RFC9493"/>.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">assertions</spanx> (array of objects)</dt> <dt><tt>assertions</tt> (array of objects):</dt>
<dd> <dd>
<t>An array containing assertions as objects each containing the assertion <t>An array containing assertions as objects, each containing the as
sertion
format and the assertion value as the JSON string serialization of the asserti on, format and the assertion value as the JSON string serialization of the asserti on,
as defined in <xref target="response-subject"/>. as defined in <xref target="response-subject"/>.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"user": { "user": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
} ], } ],
"assertions": [ { "assertions": [ {
"format": "id_token", "format": "id_token",
"value": "eyj..." "value": "eyj..."
} ] } ]
} }
]]></sourcecode>
]]></sourcecode></figure> <t>Subject Identifiers are hints to the AS in determining the
<t>Subject identifiers are hints to the AS in determining the
RO and <bcp14>MUST NOT</bcp14> be taken as authoritative statements that a parti cular RO and <bcp14>MUST NOT</bcp14> be taken as authoritative statements that a parti cular
RO is present at the client instance and acting as the end user.</t> RO is present at the client instance and acting as the end user.</t>
<t>Assertions presented by the client instance <bcp14>SHOULD</bcp14> be
<t>Assertions presented by the client instance <bcp14>SHOULD</bcp14> be validate validated by the AS. While the details of
d by the AS. While the details of
such validation are outside the scope of this specification, common validation s teps include such validation are outside the scope of this specification, common validation s teps include
verifying the signature of the assertion against a trusted signing key, verifyin g the audience verifying the signature of the assertion against a trusted signing key, verifyin g the audience
and issuer of the assertion map to expected values, and verifying the time windo w for the and issuer of the assertion map to expected values, and verifying the time windo w for the
assertion itself. However, note that in many use cases, some of these common ste ps are relaxed. assertion itself. However, note that in many use cases, some of these common ste ps are relaxed.
For example, an AS acting as an identity provider (IdP) could expect that assert ions being presented using this For example, an AS acting as an identity provider (IdP) could expect that assert ions being presented using this
mechanism were issued by the AS to the client software. The AS would verify that the AS is the mechanism were issued by the AS to the client software. The AS would verify that the AS is the
issuer of the assertion, not the audience, and that the client instance is inste ad the audience of issuer of the assertion, not the audience, and that the client instance is inste ad the audience of
the assertion. Similarly, an AS might accept a recently-expired assertion in ord er to help the assertion. Similarly, an AS might accept a recently expired assertion in ord er to help
bootstrap a new session with a specific end user.</t> bootstrap a new session with a specific end user.</t>
<t>If the identified end user does not match the RO present at the AS
<t>If the identified end user does not match the RO present at the AS during an interaction step and the AS is not explicitly allowing a cross-user
during an interaction step, and the AS is not explicitly allowing a cross-user authorization, the AS <bcp14>SHOULD</bcp14> reject the request with an <tt>unkno
authorization, the AS <bcp14>SHOULD</bcp14> reject the request with an <spanx st wn_user</tt> error (<xref target="response-error"/>).</t>
yle="verb">unknown_user</spanx> error (<xref target="response-error"/>).</t> <t>If the AS trusts the client instance to present verifiable assertions
or known Subject Identifiers,
<t>If the AS trusts the client instance to present verifiable assertions or know
n subject identifiers,
such as an opaque identifier issued by the AS for this specific client instance, the AS <bcp14>MAY</bcp14> such as an opaque identifier issued by the AS for this specific client instance, the AS <bcp14>MAY</bcp14>
decide, based on its policy, to skip interaction with the RO, even decide, based on its policy, to skip interaction with the RO, even
if the client instance provides one or more interaction modes in its request.</t > if the client instance provides one or more interaction modes in its request.</t >
<t>See <xref target="security-assertions"/> for considerations for the A
<t>See <xref target="security-assertions"/> for considerations that the AS has t S when accepting and
o make when accepting and
processing assertions from the client instance.</t> processing assertions from the client instance.</t>
<section anchor="request-user-reference">
<section anchor="request-user-reference"><name>Identifying the User by Reference <name>Identifying the User by Reference</name>
</name> <t>The AS can identify the current end user to the client instance wit
h a reference
<t>The AS can identify the current end user to the client instance with a refere that can be used by the client instance to refer to the end user across
nce
which can be used by the client instance to refer to the end user across
multiple requests. multiple requests.
If the client instance has a reference for the end user at this AS, the If the client instance has a reference for the end user at this AS, the
client instance <bcp14>MAY</bcp14> pass that reference as a string. The format o f this string client instance <bcp14>MAY</bcp14> pass that reference as a string. The format o f this string
is opaque to the client instance.</t> is opaque to the client instance.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"user": "XUT2MFM1XBIKJKSDU8QM" "user": "XUT2MFM1XBIKJKSDU8QM"
]]></sourcecode></figure> ]]></sourcecode>
<t>One means of dynamically obtaining such a user reference is from th
<t>One means of dynamically obtaining such a user reference is from the AS retur e AS returning
ning an <tt>opaque</tt> Subject Identifier as described in <xref target="response-sub
an <spanx style="verb">opaque</spanx> subject identifier as described in <xref t ject"/>.
arget="response-subject"/>.
Other means of configuring a client instance with a user identifier are out Other means of configuring a client instance with a user identifier are out
of scope of this specification. of scope of this specification.
The lifetime and validity of these user references is determined by the AS and The lifetime and validity of these user references are determined by the AS, and
this lifetime is not exposed to the client instance in GNAP. As such, a client i nstance this lifetime is not exposed to the client instance in GNAP. As such, a client i nstance
using such a user reference is likely to keep using that reference until such a time as using such a user reference is likely to keep using that reference until
it stops working.</t> it stops working.</t>
<t>User reference identifiers are not intended to be human-readable
<t>User reference identifiers are not intended to be human-readable
user identifiers or structured assertions. For the client instance to send user identifiers or structured assertions. For the client instance to send
either of these, the client can use the full <xref target="request-user">user re either of these, the client can use the full user request object (<xref target="
quest object</xref> instead.</t> request-user"> </xref>) instead.</t>
<t>If the AS does not recognize the user reference, it <bcp14>MUST</bc
<t>If the AS does not recognize the user reference, it <bcp14>MUST</bcp14> p14>
return an <spanx style="verb">unknown_user</spanx> error (<xref target="response return an <tt>unknown_user</tt> error (<xref target="response-error"/>).</t>
-error"/>).</t> </section>
</section>
</section> <section anchor="request-interact">
</section> <name>Interacting with the User</name>
<section anchor="request-interact"><name>Interacting with the User</name> <t>Often, the AS will require interaction with the RO (<xref target="aut
horization"> </xref>) in order to
<t>Often, the AS will require <xref target="authorization">interaction with the
RO</xref> in order to
approve a requested delegation to the client instance for both access to resourc es and direct approve a requested delegation to the client instance for both access to resourc es and direct
subject information. Many times the end user using the client instance is the sa me person as subject information. Many times, the end user using the client instance is the s ame person as
the RO, and the client instance can directly drive interaction with the end user by facilitating the RO, and the client instance can directly drive interaction with the end user by facilitating
the process through means such as redirection to a URI or launching an applicati on. Other times, the the process through means such as redirection to a URI or launching an applicati on. Other times, the
client instance can provide information to start the RO's interaction on a secon dary client instance can provide information to start the RO's interaction on a secon dary
device, or the client instance will wait for the RO to approve the request async hronously. device, or the client instance will wait for the RO to approve the request async hronously.
The client instance could also be signaled that interaction has concluded throug h a The client instance could also be signaled that interaction has concluded throug h a
callback mechanism.</t> callback mechanism.</t>
<t>The client instance declares the parameters for interaction methods t
<t>The client instance declares the parameters for interaction methods that it c hat it can support
an support using the <tt>interact</tt> field.</t>
using the <spanx style="verb">interact</spanx> field.</t> <t>The <tt>interact</tt> field is a JSON object with three keys whose va
lues declare how the client can initiate
<t>The <spanx style="verb">interact</spanx> field is a JSON object with three ke
ys whose values declare how the client can initiate
and complete the request, as well as provide hints to the AS about user preferen ces such as locale. and complete the request, as well as provide hints to the AS about user preferen ces such as locale.
A client instance <bcp14>MUST NOT</bcp14> declare an interaction mode it does no t support. A client instance <bcp14>MUST NOT</bcp14> declare an interaction mode it does no t support.
The client instance <bcp14>MAY</bcp14> send multiple modes in the same request. The client instance <bcp14>MAY</bcp14> send multiple modes in the same request.
There is no preference order specified in this request. An AS <bcp14>MAY</bcp14> There is no preference order specified in this request. An AS <bcp14>MAY</bcp14>
<xref target="response-interact">respond to any, all, or none of the presented i nteraction modes</xref> in a request, depending on respond to any, all, or none of the presented interaction modes (<xref target="response-interact"> </xref>) in a request, depending on
its capabilities and what is allowed to fulfill the request.</t> its capabilities and what is allowed to fulfill the request.</t>
<dl>
<dl> <dt><tt>start</tt> (array of objects/strings):</dt>
<dt><spanx style="verb">start</spanx> (array of objects/strings):</dt> <dd>
<dd> <t>Indicates how the client instance can start an interaction. <bcp1
<t>Indicates how the client instance can start an interaction. <bcp14>REQUIR 4>REQUIRED</bcp14>. See <xref target="request-interact-start"/>.</t>
ED</bcp14>. (<xref target="request-interact-start"/>)</t> </dd>
</dd> <dt><tt>finish</tt> (object):</dt>
<dt><spanx style="verb">finish</spanx> (object):</dt> <dd>
<dd> <t>Indicates how the client instance can receive an indication that
<t>Indicates how the client instance can receive an indication that interact interaction has finished at the AS. <bcp14>OPTIONAL</bcp14>. See <xref target="r
ion has finished at the AS. <bcp14>OPTIONAL</bcp14>. (<xref target="request-inte equest-interact-finish"/>.</t>
ract-finish"/>)</t> </dd>
</dd> <dt><tt>hints</tt> (object):</dt>
<dt><spanx style="verb">hints</spanx> (object):</dt> <dd>
<dd> <t>Provides additional information to inform the interaction process
<t>Provides additional information to inform the interaction process at the at the AS. <bcp14>OPTIONAL</bcp14>. See <xref target="request-interact-hint"/>.
AS. <bcp14>OPTIONAL</bcp14>. (<xref target="request-interact-hint"/>)</t> </t>
</dd> </dd>
</dl> </dl>
<t>In the following non-normative example, the client instance is indica
<t>In the following non-normative example, the client instance is indicating tha ting that it can redirect (<xref target="request-interact-redirect"> </xref>)
t it can <xref target="request-interact-redirect">redirect</xref> the end user to an arbitrary URI and can receive a redirect (<xref target="reque
the end user to an arbitrary URI and can receive a <xref target="request-interac st-interact-callback-redirect"> </xref>) through
t-callback-redirect">redirect</xref> through
a browser request. Note that the client instance does not accept a push-style ca llback. a browser request. Note that the client instance does not accept a push-style ca llback.
The pattern of using a redirect for both interaction start and finish is common for web-based client software.</t> The pattern of using a redirect for both interaction start and finish is common for web-based client software.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>In the following non-normative example, the client instance is indica
<t>In the following non-normative example, the client instance is indicating tha ting that it can
t it can display a user code (<xref target="request-interact-usercode"> </xref>) and dire
display a <xref target="request-interact-usercode">user code</xref> and direct t ct the end user
he end user to an arbitrary URI (<xref target="request-interact-redirect"> </xref>), but it
to an <xref target="request-interact-redirect">arbitrary URI</xref>, but it cann cannot accept a redirect or push-style callback.
ot accept a redirect or push callback. This pattern is common for devices that have robust display capabilities but exp
This pattern is common for devices with robust display capabilities but that exp ect
ect
the use of a secondary device to facilitate end-user interaction with the AS, su ch the use of a secondary device to facilitate end-user interaction with the AS, su ch
as a set-top box capable of displaying an interaction URL as a QR code.</t> as a set-top box capable of displaying an interaction URL as a QR code.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"start": ["redirect", "user_code"] "start": ["redirect", "user_code"]
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>In the following non-normative example, the client instance is indica
<t>In the following non-normative example, the client instance is indicating tha ting that it cannot start any interaction with the end user but that the AS can
t it can push an interaction finish message (<xref target="request-interact-callback-push
not start any interaction with the end-user, but that the AS can "> </xref>) when
<xref target="request-interact-callback-push">push an interaction finish message
</xref> when
authorization from the RO is received asynchronously. This pattern is authorization from the RO is received asynchronously. This pattern is
common for scenarios where a service needs to be authorized, but the RO is common for scenarios where a service needs to be authorized, but the RO is
able to be contacted separately from the GNAP transaction itself, such as throug h a push able to be contacted separately from the GNAP transaction itself, such as throug h a push
notification or existing interactive session on a secondary device.</t> notification or existing interactive session on a secondary device.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"start": [], "start": [],
"finish": { "finish": {
"method": "push", "method": "push",
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If the client instance does not provide a suitable interaction mechanism, the
AS cannot contact the RO asynchronously, and the AS determines
that interaction is required, then the AS <bcp14>MUST</bcp14> return an <spanx s
tyle="verb">invalid_interaction</spanx>
error (<xref target="response-error"/>) since the client instance will be unable
to complete the
request without authorization.</t>
<section anchor="request-interact-start"><name>Start Mode Definitions</name>
<t>If the client instance is capable of starting interaction with the end user, <t>If all of the following conditions are true, the AS
the client instance <bcp14>MUST</bcp14> return an <tt>invalid_interaction</tt> error
indicates this by sending an array of start modes under the <spanx style="verb"> (<xref target="response-error"/>) since the client instance will be
start</spanx> key. unable to complete the request without authorization:
Each interaction start modes has a unique identifying name. </t>
<ul spacing="normal">
<li>The client instance does not provide a suitable interaction mechani
sm.
</li>
<li>The AS cannot contact the RO asynchronously.
</li>
<li>The AS determines that
interaction is required.
</li>
</ul>
<section anchor="request-interact-start">
<name>Start Mode Definitions</name>
<t>If the client instance is capable of starting interaction with the
end user, the client instance
indicates this by sending an array of start modes under the <tt>start</tt> key.
Each interaction start mode has a unique identifying name.
Interaction start modes are specified in the array either by a string, which con sists of the start Interaction start modes are specified in the array either by a string, which con sists of the start
mode name on its own, or by a JSON object with the required field <spanx style=" mode name on its own, or by a JSON object with the required field <tt>mode</tt>:
verb">mode</spanx>:</t> </t>
<dl>
<dl> <dt><tt>mode</tt>:</dt>
<dt><spanx style="verb">mode</spanx>:</dt> <dd>
<dd> <t>The interaction start mode. <bcp14>REQUIRED</bcp14>.</t>
<t>The interaction start mode. <bcp14>REQUIRED</bcp14>.</t> </dd>
</dd> </dl>
</dl> <t>Interaction start modes defined as objects <bcp14>MAY</bcp14> defin
e additional parameters to be required in the object.</t>
<t>Interaction start modes defined as objects <bcp14>MAY</bcp14> define addition <t>The <tt>start</tt> array can contain both string-type and object-ty
al parameters to be required in the object.</t> pe modes.</t>
<t>This specification defines the following interaction start modes:</
<t>The <spanx style="verb">start</spanx> array can contain both string-type and t>
object-type modes.</t> <dl>
<dt><tt>"redirect"</tt> (string):</dt>
<t>This specification defines the following interaction start modes:</t> <dd>
<t>Indicates that the client instance can direct the end user to a
<dl> n arbitrary URI
<dt><spanx style="verb">"redirect"</spanx> (string):</dt> for interaction. See <xref target="request-interact-redirect"/>.</t>
<dd> </dd>
<t>Indicates that the client instance can direct the end user to an arbitrar <dt><tt>"app"</tt> (string):</dt>
y URI <dd>
for interaction. <xref target="request-interact-redirect"/></t> <t>Indicates that the client instance can launch an application on
</dd> the end user's
<dt><spanx style="verb">"app"</spanx> (string):</dt> device for interaction. See <xref target="request-interact-app"/>.</t>
<dd> </dd>
<t>Indicates that the client instance can launch an application on the end u <dt><tt>"user_code"</tt> (string):</dt>
ser's <dd>
device for interaction. <xref target="request-interact-app"/></t> <t>Indicates that the client instance can communicate a short, hum
</dd> an-readable
<dt><spanx style="verb">"user_code"</spanx> (string):</dt> code to the end user for use with a stable URI. See <xref target="request-inte
<dd> ract-usercode"/>.</t>
<t>Indicates that the client instance can communicate a human-readable short </dd>
code to the end user for use with a stable URI. <xref target="request-interact <dt><tt>"user_code_uri"</tt> (string):</dt>
-usercode"/></t> <dd>
</dd> <t>Indicates that the client instance can communicate a short, hum
<dt><spanx style="verb">"user_code_uri"</spanx> (string):</dt> an-readable
<dd> code to the end user for use with a short, dynamic URI. See <xref target="requ
<t>Indicates that the client instance can communicate a human-readable short est-interact-usercodeuri"/>.</t>
code to the end user for use with a short, dynamic URI. <xref target="request- </dd>
interact-usercodeuri"/></t> </dl>
</dd> <t>Additional start modes can be defined in the "GNAP Interaction Star
</dl> t Modes" registry (<xref target="IANA-interaction-start-modes"> </xref>).</t>
<section anchor="request-interact-redirect">
<t>Additional start modes are defined in the <xref target="IANA-interaction-star <name>Redirect to an Arbitrary URI</name>
t-modes">GNAP Interaction Start Modes Registry</xref>.</t> <t>If the client instance is capable of directing the end user to a
URI defined
<section anchor="request-interact-redirect"><name>Redirect to an Arbitrary URI</
name>
<t>If the client instance is capable of directing the end user to a URI defined
by the AS at runtime, the client instance indicates this by including by the AS at runtime, the client instance indicates this by including
<spanx style="verb">redirect</spanx> in the array under the <spanx style="verb"> <tt>redirect</tt> in the array under the <tt>start</tt> key. The means by which
start</spanx> key. The means by which the client instance will activate this URI are out of scope of this
the client instance will activate this URI is out of scope of this
specification, but common methods include an HTTP redirect, specification, but common methods include an HTTP redirect,
launching a browser on the end user's device, providing a scannable launching a browser on the end user's device, providing a scannable
image encoding, and printing out a URI to an interactive image encoding, and printing out a URI to an interactive
console. While this URI is generally hosted at the AS, the client console. While this URI is generally hosted at the AS, the client
instance can make no assumptions about its contents, composition, instance can make no assumptions about its contents, composition,
or relationship to the grant endpoint URI.</t> or relationship to the grant endpoint URI.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"start": ["redirect"] "start": ["redirect"]
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If this interaction mode is supported for this client instance an
<t>If this interaction mode is supported for this client instance and d
request, the AS returns a redirect interaction response <xref target="response-i request, the AS returns a redirect interaction response (<xref target="response-
nteract-redirect"/>. interact-redirect"/>).
The client instance manages this interaction method as described in <xref target ="interaction-redirect"/>.</t> The client instance manages this interaction method as described in <xref target ="interaction-redirect"/>.</t>
<t>See <xref target="security-front-channel"/> for more consideratio
<t>See <xref target="security-front-channel"/> for more considerations regarding ns regarding the use of front-channel
the use of front-channel
communication techniques.</t> communication techniques.</t>
</section>
</section> <section anchor="request-interact-app">
<section anchor="request-interact-app"><name>Open an Application-specific URI</n <name>Open an Application-Specific URI</name>
ame> <t>If the client instance can open a URI associated with an applicat
ion on
<t>If the client instance can open a URI associated with an application on the end user's device, the client instance indicates this by including <tt>app</
the end user's device, the client instance indicates this by including <spanx st tt>
yle="verb">app</spanx> in the array under the <tt>start</tt> key. The means by which the client instanc
in the array under the <spanx style="verb">start</spanx> key. The means by which e
the client instance
determines the application to open with this URI are out of scope of determines the application to open with this URI are out of scope of
this specification.</t> this specification.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"start": ["app"] "start": ["app"]
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If this interaction mode is supported for this client instance an
<t>If this interaction mode is supported for this client instance and d
request, the AS returns an app interaction response with an app URI request, the AS returns an app interaction response with an app URI
payload (<xref target="response-interact-app"/>). The client instance manages payload (<xref target="response-interact-app"/>). The client instance manages
this interaction method as described in <xref target="interaction-app"/>.</t> this interaction method as described in <xref target="interaction-app"/>.</t>
</section>
</section> <section anchor="request-interact-usercode">
<section anchor="request-interact-usercode"><name>Display a Short User Code</nam <name>Display a Short User Code</name>
e> <t>If the client instance is capable of displaying or otherwise comm
unicating
<t>If the client instance is capable of displaying or otherwise communicating
a short, human-entered code to the RO, the client instance indicates this a short, human-entered code to the RO, the client instance indicates this
by including <spanx style="verb">user_code</spanx> in the array under the <spanx style="verb">start</spanx> key. This by including <tt>user_code</tt> in the array under the <tt>start</tt> key. This
code is to be entered at a static URI that does not change at code is to be entered at a static URI that does not change at
runtime. The client instance has no reasonable means to communicate a dynamic runtime. The client instance has no reasonable means to communicate a dynamic
URI to the RO, and so this URI is usually communicated out of band to the URI to the RO, so this URI is usually communicated out of band to the
RO through documentation or other messaging outside of GNAP. RO through documentation or other messaging outside of GNAP.
While this URI is generally hosted at the AS, the client While this URI is generally hosted at the AS, the client
instance can make no assumptions about its contents, composition, instance can make no assumptions about its contents, composition,
or relationship to the grant endpoint URI.</t> or relationship to the grant endpoint URI.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"start": ["user_code"] "start": ["user_code"]
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If this interaction mode is supported for this client instance an
<t>If this interaction mode is supported for this client instance and d
request, the AS returns a user code as specified request, the AS returns a user code as specified
in <xref target="response-interact-usercode"/>. The client instance manages this interaction in <xref target="response-interact-usercode"/>. The client instance manages this interaction
method as described in <xref target="interaction-usercode"/>.</t> method as described in <xref target="interaction-usercode"/>.</t>
</section>
</section> <section anchor="request-interact-usercodeuri">
<section anchor="request-interact-usercodeuri"><name>Display a Short User Code a <name>Display a Short User Code and URI</name>
nd URI</name> <t>If the client instance is capable of displaying or otherwise comm
unicating
<t>If the client instance is capable of displaying or otherwise communicating
a short, human-entered code along with a short, human-entered URI to the RO, a short, human-entered code along with a short, human-entered URI to the RO,
the client instance indicates this the client instance indicates this
by including <spanx style="verb">user_code_uri</spanx> in the array under the <s panx style="verb">start</spanx> key. This by including <tt>user_code_uri</tt> in the array under the <tt>start</tt> key. T his
code is to be entered at the dynamic URL given in the response. code is to be entered at the dynamic URL given in the response.
While this URL is generally hosted at the AS, the client While this URL is generally hosted at the AS, the client
instance can make no assumptions about its contents, composition, instance can make no assumptions about its contents, composition,
or relationship to the grant endpoint URI.</t> or relationship to the grant endpoint URI.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"start": ["user_code_uri"] "start": ["user_code_uri"]
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If this interaction mode is supported for this client instance an
<t>If this interaction mode is supported for this client instance and d
request, the AS returns a user code and interaction URL as specified request, the AS returns a user code and interaction URL as specified
in <xref target="response-interact-usercodeuri"/>. The client instance manages t his interaction in <xref target="response-interact-usercodeuri"/>. The client instance manages t his interaction
method as described in <xref target="interaction-usercodeuri"/>.</t> method as described in <xref target="interaction-usercodeuri"/>.</t>
</section>
</section> </section>
</section> <section anchor="request-interact-finish">
<section anchor="request-interact-finish"><name>Interaction Finish Methods</name <name>Interaction Finish Methods</name>
> <t>If the client instance is capable of receiving a message from the A
S indicating
<t>If the client instance is capable of receiving a message from the AS indicati
ng
that the RO has completed their interaction, the client instance that the RO has completed their interaction, the client instance
indicates this by sending the following members of an object under the <spanx st indicates this by sending the following members of an object under the <tt>finis
yle="verb">finish</spanx> key.</t> h</tt> key.</t>
<dl>
<dl> <dt><tt>method</tt> (string):</dt>
<dt><spanx style="verb">method</spanx> (string):</dt> <dd>
<dd> <t>The callback method that the AS will use to contact the client
<t>The callback method that the AS will use to contact the client instance. instance.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">uri</spanx> (string):</dt>
<dd> <dt><tt>uri</tt> (string):</dt>
<t>Indicates the URI that the AS will either send the RO to <dd>
after interaction or send an HTTP POST request. This URI <bcp14>MAY</bcp14> be <t>Indicates the URI that the AS will use to signal the client
unique per request and <bcp14>MUST</bcp14> instance that interaction has completed. This URI
be hosted by or accessible by the client instance. This URI <bcp14>MUST</bcp14 <bcp14>MAY</bcp14> be unique per request and <bcp14>MUST</bcp14>
> be an absolute be hosted by or accessible to the client instance. This URI
URI, and <bcp14>MUST NOT</bcp14> contain <bcp14>MUST</bcp14> be an absolute URI and <bcp14>MUST
any fragment component. If the client instance needs any NOT</bcp14> contain any fragment component. If the client
state information to tie to the front channel interaction instance needs any state information to tie to the front-channel
response, it <bcp14>MUST</bcp14> use a unique callback URI to link to interaction response, it <bcp14>MUST</bcp14> use a unique
that ongoing state. The allowable URIs and URI patterns <bcp14>MAY</bcp14> be callback URI to link to that ongoing state. The allowable URIs
restricted by the AS and URI patterns <bcp14>MAY</bcp14> be restricted by the AS
based on the client instance's presented key information. The callback URI based on the client instance's presented key information. The
<bcp14>SHOULD</bcp14> be presented to the RO during the interaction phase callback URI <bcp14>SHOULD</bcp14> be presented to the RO during
before redirect. <bcp14>REQUIRED</bcp14> for <spanx style="verb">redirect</spa the interaction phase before redirect. <bcp14>REQUIRED</bcp14>
nx> and <spanx style="verb">push</spanx> methods.</t> for <tt>redirect</tt> and <tt>push</tt> methods.</t>
</dd> </dd>
<dt><spanx style="verb">nonce</spanx> (string):</dt> <dt><tt>nonce</tt> (string):</dt>
<dd> <dd>
<t>Unique ASCII string value to be used in the <t>Unique ASCII string value to be used in the
calculation of the "hash" query parameter sent to the callback URI, calculation of the "hash" query parameter sent to the callback URI. It
must be sufficiently random to be unguessable by an attacker. must be sufficiently random to be unguessable by an attacker. It
<bcp14>MUST</bcp14> be generated by the client instance as a unique value for this <bcp14>MUST</bcp14> be generated by the client instance as a unique value for this
request. <bcp14>REQUIRED</bcp14>.</t> request. <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">hash_method</spanx> (string):</dt> <dt><tt>hash_method</tt> (string):</dt>
<dd> <dd>
<t>An identifier of a hash calculation mechanism to be used for the callback <t>An identifier of a hash calculation mechanism to be used for th
hash in <xref target="interaction-hash"/>, e callback hash in <xref target="interaction-hash"/>,
as defined in the <xref target="HASH-ALG">IANA Named Information Hash Algorith as defined in the IANA "Named Information Hash Algorithm Registry" <xref targe
m Registry</xref>. t="HASH-ALG"></xref>.
If absent, the default value is <spanx style="verb">sha-256</spanx>. <bcp14>OP If absent, the default value is <tt>sha-256</tt>. <bcp14>OPTIONAL</bcp14>.</t>
TIONAL</bcp14>.</t> </dd>
</dd> </dl>
</dl> <t>This specification defines the following values for the <tt>method<
/tt> parameter; additional values can be
<t>This specification defines the following values for the <spanx style="verb">m defined in the "GNAP Interaction Finish Methods" registry (<xref target="IANA-in
ethod</spanx> parameter, teraction-finish-methods"> </xref>):</t>
with other values defined by the <xref target="IANA-interaction-finish-methods"> <dl>
GNAP Interaction Finish Methods Registry</xref>:</t> <dt><tt>"redirect"</tt>:</dt>
<dd>
<dl> <t>Indicates that the client instance can receive a redirect from
<dt><spanx style="verb">"redirect"</spanx>:</dt> the end user's device
<dd> after interaction with the RO has concluded. See <xref target="request-interac
<t>Indicates that the client instance can receive a redirect from the end us t-callback-redirect"/>.</t>
er's device </dd>
after interaction with the RO has concluded. <xref target="request-interact-ca <dt><tt>"push"</tt>:</dt>
llback-redirect"/></t> <dd>
</dd> <t>Indicates that the client instance can receive an HTTP POST req
<dt><spanx style="verb">"push"</spanx>:</dt> uest from the AS
<dd> after interaction with the RO has concluded. See <xref target="request-interac
<t>Indicates that the client instance can receive an HTTP POST request from t-callback-push"/>.</t>
the AS </dd>
after interaction with the RO has concluded. <xref target="request-interact-ca </dl>
llback-push"/></t> <t>If interaction finishing is supported for this client instance and
</dd> request, the AS will return a nonce (<xref target="response-interact-finish"> </
</dl> xref>) used by the client
<t>If interaction finishing is supported for this client instance and
request, the AS will <xref target="response-interact-finish">return a nonce</xre
f> used by the client
instance to validate the callback. instance to validate the callback.
All interaction finish methods <bcp14>MUST</bcp14> use this nonce to allow the c lient to verify the connection All interaction finish methods <bcp14>MUST</bcp14> use this nonce to allow the c lient to verify the connection
between the pending interaction request and the callback. GNAP does this through the use of the between the pending interaction request and the callback. GNAP does this through the use of the
interaction hash, defined in <xref target="interaction-hash"/>. interaction hash, defined in <xref target="interaction-hash"/>.
All requests to the callback URI <bcp14>MUST</bcp14> be processed as described i n All requests to the callback URI <bcp14>MUST</bcp14> be processed as described i n
<xref target="interaction-finish"/>.</t> <xref target="interaction-finish"/>.</t>
<t>All interaction finish methods <bcp14>MUST</bcp14> require presenta
<t>All interaction finish methods <bcp14>MUST</bcp14> require presentation of an tion of an interaction reference for continuing
interaction reference for continuing
this grant request. This means that the interaction this grant request. This means that the interaction
reference <bcp14>MUST</bcp14> be returned by the AS and <bcp14>MUST</bcp14> be p resented by the client as described in reference <bcp14>MUST</bcp14> be returned by the AS and <bcp14>MUST</bcp14> be p resented by the client as described in
<xref target="continue-after-interaction"/>. The means by which the interaction reference is returned to the <xref target="continue-after-interaction"/>. The means by which the interaction reference is returned to the
client instance is specific to the interaction finish method.</t> client instance are specific to the interaction finish method.</t>
<section anchor="request-interact-callback-redirect">
<section anchor="request-interact-callback-redirect"><name>Receive an HTTP Callb <name>Receive an HTTP Callback through the Browser</name>
ack Through the Browser</name> <t>A finish <tt>method</tt> value of <tt>redirect</tt> indicates tha
t the client instance
<t>A finish <spanx style="verb">method</spanx> value of <spanx style="verb">redi
rect</spanx> indicates that the client instance
will expect a request from the RO's browser using the HTTP method will expect a request from the RO's browser using the HTTP method
GET as described in <xref target="interaction-callback"/>.</t> GET as described in <xref target="interaction-callback"/>.</t>
<t>The client instance's URI <bcp14>MUST</bcp14> be protected by HTTPS, be <t>The client instance's URI <bcp14>MUST</bcp14> be protected by HTTPS, be
hosted on a server local to the RO's browser ("localhost"), or hosted on a server local to the RO's browser ("localhost"), or
use an application-specific URI scheme that is loaded on the use an application-specific URI scheme that is loaded on the
end user's device.</t> end user's device.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Requests to the callback URI <bcp14>MUST</bcp14> be processed by
<t>Requests to the callback URI <bcp14>MUST</bcp14> be processed by the client i the client instance as described in
nstance as described in
<xref target="interaction-callback"/>.</t> <xref target="interaction-callback"/>.</t>
<t>Since the incoming request to the callback URI is from the RO's
<t>Since the incoming request to the callback URI is from the RO's
browser, this method is usually used when the RO and end user are the browser, this method is usually used when the RO and end user are the
same entity. See <xref target="security-sessions"/> for considerations on ensuri ng the incoming HTTP message same entity. See <xref target="security-sessions"/> for considerations on ensuri ng the incoming HTTP message
matches the expected context of the request. matches the expected context of the request.
See <xref target="security-front-channel"/> for more considerations regarding th e use of front-channel See <xref target="security-front-channel"/> for more considerations regarding th e use of front-channel
communication techniques.</t> communication techniques.</t>
</section>
</section> <section anchor="request-interact-callback-push">
<section anchor="request-interact-callback-push"><name>Receive an HTTP Direct Ca <name>Receive an HTTP Direct Callback</name>
llback</name> <t>A finish <tt>method</tt> value of <tt>push</tt> indicates that th
e client instance will
<t>A finish <spanx style="verb">method</spanx> value of <spanx style="verb">push
</spanx> indicates that the client instance will
expect a request from the AS directly using the HTTP method POST expect a request from the AS directly using the HTTP method POST
as described in <xref target="interaction-pushback"/>.</t> as described in <xref target="interaction-pushback"/>.</t>
<t>The client instance's URI <bcp14>MUST</bcp14> be protected by HTT
<t>The client instance's URI <bcp14>MUST</bcp14> be protected by HTTPS, be PS, be
hosted on a server local to the RO's browser ("localhost"), or hosted on a server local to the RO's browser ("localhost"), or
use an application-specific URI scheme that is loaded on the end user's device.< /t> use an application-specific URI scheme that is loaded on the end user's device.< /t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"finish": { "finish": {
"method": "push", "method": "push",
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Requests to the callback URI <bcp14>MUST</bcp14> be processed by
<t>Requests to the callback URI <bcp14>MUST</bcp14> be processed by the client i the client instance as described in
nstance as described in
<xref target="interaction-pushback"/>.</t> <xref target="interaction-pushback"/>.</t>
<t>Since the incoming request to the callback URI is from the AS and
<t>Since the incoming request to the callback URI is from the AS and
not from the RO's browser, this request is not expected to have any shared not from the RO's browser, this request is not expected to have any shared
session information from the start method. See <xref target="security-sessions"/ > and <xref target="security-polling"/> for session information from the start method. See Sections <xref target="security-s essions" format="counter"/> and <xref target="security-polling" format="counter" /> for
more considerations regarding the use of back-channel and polling mechanisms lik e this.</t> more considerations regarding the use of back-channel and polling mechanisms lik e this.</t>
</section>
</section> </section>
</section> <section anchor="request-interact-hint">
<section anchor="request-interact-hint"><name>Hints</name> <name>Hints</name>
<t>The <tt>hints</tt> key is an object describing one or more suggesti
<t>The <spanx style="verb">hints</spanx> key is an object describing one or more ons from the client
suggestions from the client
instance that the AS can use to help drive user interaction.</t> instance that the AS can use to help drive user interaction.</t>
<t>This specification defines the following property under the <tt>hin
<t>This specification defines the following properties under the <spanx style="v ts</tt> key:</t>
erb">hints</spanx> key:</t> <dl>
<dt><tt>ui_locales</tt> (array of strings):</dt>
<dl> <dd>
<dt><spanx style="verb">ui_locales</spanx> (array of strings):</dt> <t>Indicates the end user's preferred locales that the AS can use
<dd>
<t>Indicates the end user's preferred locales that the AS can use
during interaction, particularly before the RO has during interaction, particularly before the RO has
authenticated. <bcp14>OPTIONAL</bcp14>. <xref target="request-interact-locale" /></t> authenticated. <bcp14>OPTIONAL</bcp14>. <xref target="request-interact-locale" /></t>
</dd> </dd>
</dl> </dl>
<t>The following subsection details requests for interaction
<t>The following sections detail requests for interaction hints. Additional interaction hints can be defined in
hints. Additional interaction hints are defined in the "GNAP Interaction Hints" registry (<xref target="IANA-interaction-hints"> </
the <xref target="IANA-interaction-hints">GNAP Interaction Hints Registry</xref> xref>).</t>
.</t> <section anchor="request-interact-locale">
<name>Indicate Desired Interaction Locales</name>
<section anchor="request-interact-locale"><name>Indicate Desired Interaction Loc <t>If the client instance knows the end user's locale and language p
ales</name> references, the
client instance can send this information to the AS using the <tt>ui_locales</tt
<t>If the client instance knows the end user's locale and language preferences, > field
the
client instance can send this information to the AS using the <spanx style="verb
">ui_locales</spanx> field
with an array of locale strings as defined by <xref target="RFC5646"/>.</t> with an array of locale strings as defined by <xref target="RFC5646"/>.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"hints": { "hints": {
"ui_locales": ["en-US", "fr-CA"] "ui_locales": ["en-US", "fr-CA"]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If possible, the AS <bcp14>SHOULD</bcp14> use one of the locales
<t>If possible, the AS <bcp14>SHOULD</bcp14> use one of the locales in the array in the array, with
, with
preference to the first item in the array supported by the AS. If none preference to the first item in the array supported by the AS. If none
of the given locales are supported, the AS <bcp14>MAY</bcp14> use a default loca le.</t> of the given locales are supported, the AS <bcp14>MAY</bcp14> use a default loca le.</t>
</section>
</section> </section>
</section> </section>
</section> </section>
</section> <section anchor="response">
<section anchor="response"><name>Grant Response</name> <name>Grant Response</name>
<t>In response to a client instance's request, the AS responds with a JSON
<t>In response to a client instance's request, the AS responds with a JSON objec object
t as the HTTP content. Each possible field is detailed in the subsections below.</
as the HTTP content. Each possible field is detailed in the sections below.</t> t>
<dl>
<dl> <dt><tt>continue</tt> (object):</dt>
<dt><spanx style="verb">continue</spanx> (object):</dt> <dd>
<dd> <t>Indicates that the client instance can continue the request by maki
<t>Indicates that the client instance can continue the request by making one ng one or
or
more continuation requests. <bcp14>REQUIRED</bcp14> if continuation calls are allowed for this client instance on this grant request. See <xref target="respon se-continue"/>.</t> more continuation requests. <bcp14>REQUIRED</bcp14> if continuation calls are allowed for this client instance on this grant request. See <xref target="respon se-continue"/>.</t>
</dd> </dd>
<dt><spanx style="verb">access_token</spanx> (object / array of objects):</dt> <dt><tt>access_token</tt> (object / array of objects):</dt>
<dd> <dd>
<t>A single access token or set of access tokens that the client instance ca <t>A single access token or set of access tokens that the client insta
n use to call the RS on nce can use to call the RS on
behalf of the RO. <bcp14>REQUIRED</bcp14> if an access token is included. See <xref target="response-token"/>.</t> behalf of the RO. <bcp14>REQUIRED</bcp14> if an access token is included. See <xref target="response-token"/>.</t>
</dd> </dd>
<dt><spanx style="verb">interact</spanx> (object):</dt> <dt><tt>interact</tt> (object):</dt>
<dd> <dd>
<t>Indicates that interaction through some set of defined mechanisms <t>Indicates that interaction through some set of defined mechanisms
needs to take place. <bcp14>REQUIRED</bcp14> if interaction is expected. See < xref target="response-interact"/>.</t> needs to take place. <bcp14>REQUIRED</bcp14> if interaction is expected. See < xref target="response-interact"/>.</t>
</dd> </dd>
<dt><spanx style="verb">subject</spanx> (object):</dt> <dt><tt>subject</tt> (object):</dt>
<dd> <dd>
<t>Claims about the RO as known and declared by the AS. <bcp14>REQUIRED</bcp <t>Claims about the RO as known and declared by the AS. <bcp14>REQUIRE
14> if subject information is included. See <xref target="response-subject"/>.</ D</bcp14> if subject information is included. See <xref target="response-subject
t> "/>.</t>
</dd> </dd>
<dt><spanx style="verb">instance_id</spanx> (string):</dt> <dt><tt>instance_id</tt> (string):</dt>
<dd> <dd>
<t>An identifier this client instance can use to identify itself when making <t>An identifier this client instance can use to identify itself when
making
future requests. <bcp14>OPTIONAL</bcp14>. See <xref target="response-dynamic-h andles"/>.</t> future requests. <bcp14>OPTIONAL</bcp14>. See <xref target="response-dynamic-h andles"/>.</t>
</dd> </dd>
<dt><spanx style="verb">error</spanx> (object or string):</dt> <dt><tt>error</tt> (object or string):</dt>
<dd> <dd>
<t>An error code indicating that something has gone wrong. <bcp14>REQUIRED</ <t>An error code indicating that something has gone wrong. <bcp14>REQU
bcp14> for an error condition. See <xref target="response-error"/>.</t> IRED</bcp14> for an error condition. See <xref target="response-error"/>.</t>
</dd> </dd>
</dl> </dl>
<t>Additional fields can be defined by extensions to GNAP in the "GNAP Gra
<t>Additional fields can be defined by extensions to GNAP in the <xref target="I nt Response Parameters" registry (<xref target="IANA-grant-response"> </xref>).<
ANA-grant-response">GNAP Grant Response Parameters Registry</xref>.</t> /t>
<t>In the following non-normative example, the AS is returning an interact
<t>In the following non-normative example, the AS is returning an <xref target=" ion URI (<xref target="response-interact-redirect"> </xref>),
response-interact-redirect">interaction URI</xref>, a callback nonce (<xref target="response-interact-finish"> </xref>), and a conti
a <xref target="response-interact-finish">callback nonce</xref>, and a <xref tar nuation response (<xref target="response-continue"> </xref>).</t>
get="response-continue">continuation response</xref>.</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"interact": { "interact": {
"redirect": "https://server.example.com/interact/4CF492ML\ "redirect": "https://server.example.com/interact/4CF492ML\
VMSW9MKMXKHQ", VMSW9MKMXKHQ",
"finish": "MBDOFXG4Y5CVJCX821LH" "finish": "MBDOFXG4Y5CVJCX821LH"
}, },
"continue": { "continue": {
"access_token": { "access_token": {
"value": "80UPRY5NM33OMUKMKSKU", "value": "80UPRY5NM33OMUKMKSKU",
}, },
"uri": "https://server.example.com/tx" "uri": "https://server.example.com/tx"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>In the following non-normative example, the AS is returning a bearer ac
<t>In the following non-normative example, the AS is returning a bearer <xref ta cess token (<xref target="response-token-single"> </xref>) with a management URI
rget="response-token-single">access token</xref> with a management URI and a <xr and a Subject Identifier (<xref target="response-subject"> </xref>) in the form
ef target="response-subject">subject identifier</xref> in the form of of
an opaque identifier.</t> an opaque identifier.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"flags": ["bearer"], "flags": ["bearer"],
"manage": { "manage": {
"uri": "https://server.example.com/token/PRY5NM33O", "uri": "https://server.example.com/token/PRY5NM33O",
"access_token": { "access_token": {
"value": "B8CDFONP21-4TB8N6.BW7ONM" "value": "B8CDFONP21-4TB8N6.BW7ONM"
} }
} }
}, },
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
} ] } ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>In following non-normative example, the AS is returning set of <xref target="
response-subject">subject identifiers</xref>,
simultaneously as an opaque identifier, an email address, and a decentralized id
entifier (DID), formatted as a set of Subject Identifiers defined in <xref targe
t="RFC9493"/>.</t>
<figure><sourcecode type="json"><![CDATA[ <t>In the following non-normative example, the AS is returning set of Subj
ect Identifiers (<xref target="response-subject"> </xref>),
simultaneously as an opaque identifier, an email address, and a decentralized id
entifier (DID), formatted as a set of Subject Identifiers as defined in <xref ta
rget="RFC9493"/>.</t>
<sourcecode type="json"><![CDATA[
{ {
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
}, { }, {
"format": "email", "format": "email",
"email": "user@example.com" "email": "user@example.com"
}, { }, {
"format": "did", "format": "did",
"url": "did:example:123456" "url": "did:example:123456"
} ] } ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The response <bcp14>MUST</bcp14> be sent as a JSON object in the conten
<t>The response <bcp14>MUST</bcp14> be sent as a JSON object in the content of t t of the HTTP response with Content-Type <tt>application/json</tt>, unless other
he HTTP response with Content-Type <spanx style="verb">application/json</spanx>, wise specified by the specific response (e.g., an empty response with no Content
unless otherwise specified by the specific response (e.g., an empty response wi -Type).</t>
th no Content-Type).</t> <t>The AS <bcp14>MUST</bcp14> include the HTTP Cache-Control response head
er field <xref target="RFC9111"/> with a value set to "no-store".</t>
<t>The authorization server <bcp14>MUST</bcp14> include the HTTP Cache-Control r <section anchor="response-continue">
esponse header field <xref target="RFC9111"/> with a value set to "no-store".</t <name>Request Continuation</name>
> <t>If the AS determines that the grant request can be continued by the
client instance, the AS responds with the <tt>continue</tt> field. This field
<section anchor="response-continue"><name>Request Continuation</name>
<t>If the AS determines that the grant request can be continued by the
client instance, the AS responds with the <spanx style="verb">continue</spanx> f
ield. This field
contains a JSON object with the following properties.</t> contains a JSON object with the following properties.</t>
<dl>
<dl> <dt><tt>uri</tt> (string):</dt>
<dt><spanx style="verb">uri</spanx> (string):</dt> <dd>
<dd> <t>The URI at which the client instance can make
<t>The URI at which the client instance can make
continuation requests. This URI <bcp14>MAY</bcp14> vary per continuation requests. This URI <bcp14>MAY</bcp14> vary per
request, or <bcp14>MAY</bcp14> be stable at the AS. This URI <bcp14>MUST</bcp1 4> be an absolute URI. request or <bcp14>MAY</bcp14> be stable at the AS. This URI <bcp14>MUST</bcp14 > be an absolute URI.
The client instance <bcp14>MUST</bcp14> use this The client instance <bcp14>MUST</bcp14> use this
value exactly as given when making a <xref target="continue-request">continuat ion request</xref>. value exactly as given when making a continuation request (<xref target="conti nue-request"> </xref>).
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">wait</spanx> (integer):</dt> <dt><tt>wait</tt> (integer):</dt>
<dd> <dd>
<t>The amount of time in integer <t>The amount of time in integer
seconds the client instance <bcp14>MUST</bcp14> wait after receiving this requ est continuation seconds the client instance <bcp14>MUST</bcp14> wait after receiving this requ est continuation
response and calling the continuation URI. The value <bcp14>SHOULD NOT</bcp14> be less than five seconds, response and calling the continuation URI. The value <bcp14>SHOULD NOT</bcp14> be less than five seconds,
and omission of the value <bcp14>MUST</bcp14> be interpreted as five seconds. and omission of the value <bcp14>MUST</bcp14> be interpreted as five seconds.
<bcp14>RECOMMENDED</bcp14>.</t> <bcp14>RECOMMENDED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">access_token</spanx> (object):</dt> <dt><tt>access_token</tt> (object):</dt>
<dd> <dd>
<t>A unique access token for continuing the request, called the "continuatio <t>A unique access token for continuing the request, called the "con
n access token". tinuation access token".
The value of this property <bcp14>MUST</bcp14> be an object in the format spec ified The value of this property <bcp14>MUST</bcp14> be an object in the format spec ified
in <xref target="response-token-single"/>. This access token <bcp14>MUST</bcp1 4> be bound to the in <xref target="response-token-single"/>. This access token <bcp14>MUST</bcp1 4> be bound to the
client instance's key used in the request and <bcp14>MUST NOT</bcp14> be a bea rer token. As a consequence, client instance's key used in the request and <bcp14>MUST NOT</bcp14> be a bea rer token. As a consequence,
the <spanx style="verb">flags</spanx> array of this access token <bcp14>MUST N the <tt>flags</tt> array of this access token <bcp14>MUST NOT</bcp14> contain
OT</bcp14> contain the string <spanx style="verb">bearer</spanx> and the the string <tt>bearer</tt>, and the
<spanx style="verb">key</spanx> field <bcp14>MUST</bcp14> be omitted. <tt>key</tt> field <bcp14>MUST</bcp14> be omitted.
This access token <bcp14>MUST NOT</bcp14> have a <spanx style="verb">manage</s This access token <bcp14>MUST NOT</bcp14> have a <tt>manage</tt> field.
panx> field.
The client instance <bcp14>MUST</bcp14> present the continuation access token in all requests to the continuation URI as described in <xref target="use-access -token"/>. The client instance <bcp14>MUST</bcp14> present the continuation access token in all requests to the continuation URI as described in <xref target="use-access -token"/>.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"continue": { "continue": {
"access_token": { "access_token": {
"value": "80UPRY5NM33OMUKMKSKU" "value": "80UPRY5NM33OMUKMKSKU"
}, },
"uri": "https://server.example.com/continue", "uri": "https://server.example.com/continue",
"wait": 60 "wait": 60
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>This field is <bcp14>REQUIRED</bcp14> if the grant request is in the
<t>This field is <bcp14>REQUIRED</bcp14> if the grant request is in the <em>pend <em>pending</em> state, as
ing</em> state, as
the field contains the information needed by the client request to continue the the field contains the information needed by the client request to continue the
request as described in <xref target="continue-request"/>. Note that the request as described in <xref target="continue-request"/>. Note that the
continuation access token is bound to the client instance's key, and therefore t he continuation access token is bound to the client instance's key; therefore, the
client instance <bcp14>MUST</bcp14> sign all continuation requests with its key as described client instance <bcp14>MUST</bcp14> sign all continuation requests with its key as described
in <xref target="binding-keys"/> and in <xref target="binding-keys"/> and
<bcp14>MUST</bcp14> present the continuation access token in its continuation re quest.</t> <bcp14>MUST</bcp14> present the continuation access token in its continuation re quest.</t>
</section>
</section> <section anchor="response-token">
<section anchor="response-token"><name>Access Tokens</name> <name>Access Tokens</name>
<t>If the AS has successfully granted one or more access tokens to the c
<t>If the AS has successfully granted one or more access tokens to the client in lient instance,
stance, the AS responds with the <tt>access_token</tt> field. This field contains either
the AS responds with the <spanx style="verb">access_token</spanx> field. This fi a single
eld contains either a single
access token as described in <xref target="response-token-single"/> or an array of access tokens access token as described in <xref target="response-token-single"/> or an array of access tokens
as described in <xref target="response-token-multiple"/>.</t> as described in <xref target="response-token-multiple"/>.</t>
<t>The client instance uses any access tokens in this response to call t
<t>The client instance uses any access tokens in this response to call the RS as he RS as
described in <xref target="use-access-token"/>.</t> described in <xref target="use-access-token"/>.</t>
<t>The grant request <bcp14>MUST</bcp14> be in the <em>approved</em> sta
<t>The grant request <bcp14>MUST</bcp14> be in the <em>approved</em> state to in te to include this field in the response.</t>
clude this field in the response.</t> <section anchor="response-token-single">
<name>Single Access Token</name>
<section anchor="response-token-single"><name>Single Access Token</name> <t>If the client instance has requested a single access token and the
AS has
<t>If the client instance has requested a single access token and the AS has
granted that access token, the AS responds with the "access_token" granted that access token, the AS responds with the "access_token"
field. The value of this field is an object with the following field. The value of this field is an object with the following
properties.</t> properties.</t>
<dl>
<dl> <dt><tt>value</tt> (string):</dt>
<dt><spanx style="verb">value</spanx> (string):</dt> <dd>
<dd> <t>The value of the access token as a
<t>The value of the access token as a
string. The value is opaque to the client instance. The value <bcp14>MUST</bcp 14> be string. The value is opaque to the client instance. The value <bcp14>MUST</bcp 14> be
limited to the <spanx style="verb">token68</spanx> character set defined in <x ref section="11.2" sectionFormat="of" target="HTTP"/> to facilitate transmission over HTTP limited to the <tt>token68</tt> character set defined in <xref section="11.2" sectionFormat="of" target="RFC9110"/> to facilitate transmission over HTTP
headers and within other protocols without requiring additional encoding. headers and within other protocols without requiring additional encoding.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">label</spanx> (string):</dt> <dt><tt>label</tt> (string):</dt>
<dd> <dd>
<t>The value of the <spanx style="verb">label</spanx> the client instance pr <t>The value of the <tt>label</tt> the client instance provided in
ovided in the associated the associated
<xref target="request-token">token request</xref>, if present. token request (<xref target="request-token"> </xref>), if present.
<bcp14>REQUIRED</bcp14> for multiple access tokens or if a <spanx style="verb" <bcp14>REQUIRED</bcp14> for multiple access tokens or if a <tt>label</tt> was
>label</spanx> was included in the single access token request, <bcp14>OPTIONAL< included in the single access token request; <bcp14>OPTIONAL</bcp14> for a singl
/bcp14> for a single access token where no <spanx style="verb">label</spanx> was e access token where no <tt>label</tt> was included in the request.</t>
included in the request.</t> </dd>
</dd>
<dt><spanx style="verb">manage</spanx> (object):</dt> <dt><tt>manage</tt> (object):</dt>
<dd> <dd>
<t>Access information for the token management API for this access token. <t>Access information for the token management API for
The management URI for this this access token.
access token.
If provided, the client instance <bcp14>MAY</bcp14> manage its access If provided, the client instance <bcp14>MAY</bcp14> manage its access
token as described in <xref target="token-management"/>. token as described in <xref target="token-management"/>.
This management API is a function of the AS and is separate from the RS This management API is a function of the AS and is separate from the RS
the client instance is requesting access to. the client instance is requesting access to.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">access</spanx> (array of objects/strings):</dt> <dt><tt>access</tt> (array of objects/strings):</dt>
<dd> <dd>
<t>A description of the rights <t>A description of the rights
associated with this access token, as defined in associated with this access token, as defined in
<xref target="resource-access-rights"/>. If included, this <bcp14>MUST</bcp14> reflect the rights <xref target="resource-access-rights"/>. If included, this <bcp14>MUST</bcp14> reflect the rights
associated with the issued access token. These rights <bcp14>MAY</bcp14> vary associated with the issued access token. These rights <bcp14>MAY</bcp14> vary
from what was requested by the client instance. from what was requested by the client instance.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">expires_in</spanx> (integer):</dt> <dt><tt>expires_in</tt> (integer):</dt>
<dd> <dd>
<t>The number of seconds in <t>The number of seconds in
which the access will expire. The client instance <bcp14>MUST NOT</bcp14> use the access which the access will expire. The client instance <bcp14>MUST NOT</bcp14> use the access
token past this time. Note that the access token <bcp14>MAY</bcp14> be revoked by the token past this time. Note that the access token <bcp14>MAY</bcp14> be revoked by the
AS or RS at any point prior to its expiration. AS or RS at any point prior to its expiration.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">key</spanx> (object / string):</dt> <dt><tt>key</tt> (object / string):</dt>
<dd> <dd>
<t>The key that the token is bound to, if different from the <t>The key that the token is bound to, if different from the
client instance's presented key. The key <bcp14>MUST</bcp14> be an object or s tring in a format client instance's presented key. The key <bcp14>MUST</bcp14> be an object or s tring in a format
described in <xref target="key-format"/>. The client instance <bcp14>MUST</bcp 14> be able to described in <xref target="key-format"/>. The client instance <bcp14>MUST</bcp 14> be able to
dereference or process the key information in order to be able dereference or process the key information in order to be able
to <xref target="use-access-token">sign subsequent requests using the access t oken</xref>. to sign subsequent requests using the access token (<xref target="use-access-t oken"> </xref>).
When the key is provided by value from the AS, the token shares some security properties When the key is provided by value from the AS, the token shares some security properties
with bearer tokens as discussed in <xref target="security-as-keys"/>. with bearer tokens as discussed in <xref target="security-as-keys"/>.
It is <bcp14>RECOMMENDED</bcp14> that keys returned for use with access tokens be key references It is <bcp14>RECOMMENDED</bcp14> that keys returned for use with access tokens be key references
as described in <xref target="key-reference"/> that the client instance can co rrelate to as described in <xref target="key-reference"/> that the client instance can co rrelate to
its known keys. its known keys.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">flags</spanx> (array of strings):</dt> <dt><tt>flags</tt> (array of strings):</dt>
<dd> <dd>
<t>A set of flags that represent attributes or behaviors of the access token <t>A set of flags that represent attributes or behaviors of the ac
cess token
issued by the AS. issued by the AS.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>The value of the <tt>manage</tt> field is an object with the follow
<t>The value of the <spanx style="verb">manage</spanx> field is an object with t ing properties:</t>
he following properties:</t> <dl>
<dt><tt>uri</tt> (string):</dt>
<t><spanx style="verb">uri</spanx> (string): <dd>The URI of the token management API for this access token.
The URI of the token management API for this access token.
This URI <bcp14>MUST</bcp14> be an absolute URI. This URI <bcp14>MUST</bcp14> be an absolute URI.
This URI <bcp14>MUST NOT</bcp14> include the
access token value and <bcp14>SHOULD</bcp14> be different for each access
token issued in a request and <bcp14>MUST NOT</bcp14> include the value of t
he
access token being managed.
<bcp14>REQUIRED</bcp14>.</t>
<dl> This URI <bcp14>MUST NOT</bcp14> include the value of the access token being
<dt><spanx style="verb">access_token</spanx> (object):</dt> managed
<dd> or the value of the access token used to protect the URI.
<t>A unique access token for continuing the request, called the "token manag This URI <bcp14>SHOULD</bcp14> be different for each access
ement access token". token issued in a request.
<bcp14>REQUIRED</bcp14>.</dd>
<dt><tt>access_token</tt> (object):</dt>
<dd>
<t>A unique access token for continuing the request, called the "t
oken management access token".
The value of this property <bcp14>MUST</bcp14> be an object in the format spec ified The value of this property <bcp14>MUST</bcp14> be an object in the format spec ified
in <xref target="response-token-single"/>. This access token <bcp14>MUST</bcp1 4> be bound to the in <xref target="response-token-single"/>. This access token <bcp14>MUST</bcp1 4> be bound to the
client instance's key used in the request (or its most recent rotation) and <b cp14>MUST NOT</bcp14> be a bearer token. As a consequence, client instance's key used in the request (or its most recent rotation) and <b cp14>MUST NOT</bcp14> be a bearer token. As a consequence,
the <spanx style="verb">flags</spanx> array of this access token <bcp14>MUST N the <tt>flags</tt> array of this access token <bcp14>MUST NOT</bcp14> contain
OT</bcp14> contain the string <spanx style="verb">bearer</spanx> and the the string <tt>bearer</tt>, and the
<spanx style="verb">key</spanx> field <bcp14>MUST</bcp14> be omitted. <tt>key</tt> field <bcp14>MUST</bcp14> be omitted.
This access token <bcp14>MUST NOT</bcp14> have a <spanx style="verb">manage</s This access token <bcp14>MUST NOT</bcp14> have a <tt>manage</tt> field.
panx> field.
This access token <bcp14>MUST NOT</bcp14> have the same value as the token it is managing. This access token <bcp14>MUST NOT</bcp14> have the same value as the token it is managing.
The client instance <bcp14>MUST</bcp14> present the continuation access token in all requests to the continuation URI as described in <xref target="use-access -token"/>. The client instance <bcp14>MUST</bcp14> present the continuation access token in all requests to the continuation URI as described in <xref target="use-access -token"/>.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>The values of the <tt>flags</tt> field defined by this specificatio
<t>The values of the <spanx style="verb">flags</spanx> field defined by this spe n are as follows:</t>
cification are as follows:</t> <dl>
<dt><tt>"bearer"</tt>:</dt>
<dl> <dd>
<dt><spanx style="verb">"bearer"</spanx>:</dt> <t>Flag indicating whether the token is a bearer token, not bound
<dd> to a key and proofing mechanism.
<t>This flag indicates whether the token is a bearer token, not bound to a k If the <tt>bearer</tt> flag is present, the access token is a bearer token, an
ey and proofing mechanism. d the <tt>key</tt>
If the <spanx style="verb">bearer</spanx> flag is present, the access token is
a bearer token, and the <spanx style="verb">key</spanx>
field in this response <bcp14>MUST</bcp14> be omitted. field in this response <bcp14>MUST</bcp14> be omitted.
See <xref target="security-bearer-tokens"/> for additional considerations on t he use of bearer tokens.</t> See <xref target="security-bearer-tokens"/> for additional considerations on t he use of bearer tokens.</t>
</dd> </dd>
<dt><spanx style="verb">"durable"</spanx>:</dt> <dt><tt>"durable"</tt>:</dt>
<dd> <dd>
<t>Flag indicating a hint of AS behavior on token rotation. <t>Flag indicating a hint of AS behavior on token rotation.
If this flag is present, then the client instance can expect If this flag is present, then the client instance can expect
a previously-issued access token to continue to work after it has been <xref t a previously issued access token to continue to work after it has been rotated
arget="rotate-access-token">rotated</xref> (<xref target="rotate-access-token"> </xref>)
or the underlying grant request has been <xref target="continue-modify">modifi or the underlying grant request has been modified (<xref target="continue-modi
ed</xref>, resulting fy"> </xref>), resulting
in the issuance of new access tokens. If this flag is omitted, the client in the issuance of new access tokens. If this flag is omitted, the client
instance can anticipate a given access token instance can anticipate a given access token
could stop working after token rotation or grant request modification. could stop working after token rotation or grant request modification.
Note that a token flagged as <spanx style="verb">durable</spanx> can still exp ire or be revoked through Note that a token flagged as <tt>durable</tt> can still expire or be revoked t hrough
any normal means.</t> any normal means.</t>
</dd> </dd>
</dl> </dl>
<t>Flag values <bcp14>MUST NOT</bcp14> be included more than once.</t>
<t>Flag values <bcp14>MUST NOT</bcp14> be included more than once.</t> <t>Additional flags can be defined by extensions using the "GNAP Acces
s Token Flags" registry (<xref target="IANA-token-flags"></xref>).</t>
<t>Additional flags can be defined by extensions using the <xref target="IANA-to <t>If the <tt>bearer</tt> flag and the <tt>key</tt> field
ken-flags">GNAP Access Token Fields Registry</xref>.</t> in this response are omitted, the token is bound to the key used by the client i
nstance (<xref target="request-client"> </xref>)
<t>If the <spanx style="verb">bearer</spanx> flag and the <spanx style="verb">ke in its request for access. If the <tt>bearer</tt> flag is omitted and the <tt>ke
y</spanx> field y</tt> field is present,
in this response are omitted, the token is bound the <xref target="request-clien the token is bound to the key and proofing mechanism indicated in the <tt>key</t
t">key used by the client instance</xref> t> field.
in its request for access. If the <spanx style="verb">bearer</spanx> flag is omi
tted, and the <spanx style="verb">key</spanx> field is present,
the token is bound to the key and proofing mechanism indicated in the <spanx sty
le="verb">key</spanx> field.
The means by which the AS determines how to bind an access token to a key The means by which the AS determines how to bind an access token to a key
other than that presented by the client instance is out of scope for this other than that presented by the client instance are out of scope for this
specification, but common practices include pre-registering specific keys in a s tatic fashion.</t> specification, but common practices include pre-registering specific keys in a s tatic fashion.</t>
<t>The client software <bcp14>MUST</bcp14> reject any access token whe
re the <tt>flags</tt> field contains the <tt>bearer</tt> flag
and the <tt>key</tt> field is present with any value.</t>
<t>The client software <bcp14>MUST</bcp14> reject any access token where the <sp <t>The following non-normative example shows a single access token bound to
anx style="verb">flags</spanx> field contains the <spanx style="verb">bearer</sp the client instance's key used in the initial request. The access token has a
anx> flag management URI and has access to three described resources (one using an
and the <spanx style="verb">key</spanx> field is present with any value.</t> object and two described by reference strings).
</t>
<t>The following non-normative example shows a single access token bound to the <sourcecode type="json"><![CDATA[
client instance's key
used in the initial request, with a management URI, and that has access to three
described resources
(one using an object and two described by reference strings).</t>
<figure><sourcecode type="json"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": { "manage": {
"uri": "https://server.example.com/token/PRY5NM33O", "uri": "https://server.example.com/token/PRY5NM33O",
"access_token": { "access_token": {
"value": "B8CDFONP21-4TB8N6.BW7ONM" "value": "B8CDFONP21-4TB8N6.BW7ONM"
} }
}, },
skipping to change at line 3369 skipping to change at line 3449
"https://resource.local/other" "https://resource.local/other"
], ],
"datatypes": [ "datatypes": [
"metadata", "metadata",
"images" "images"
] ]
}, },
"read", "dolphin-metadata" "read", "dolphin-metadata"
] ]
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The following non-normative example shows a single bearer access to
<t>The following non-normative example shows a single bearer access token ken
with access to two described resources.</t> with access to two described resources.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"flags": ["bearer"], "flags": ["bearer"],
"access": [ "access": [
"finance", "medical" "finance", "medical"
] ]
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If the client instance requested a single access token (<xref
<t>If the client instance <xref target="request-token-single">requested a single target="request-token-single"> </xref>), the AS <bcp14>MUST
access token</xref>, the AS <bcp14>MUST NOT</bcp14> respond with the multiple NOT</bcp14> respond with the structure for multiple access
access token structure.</t> tokens.</t>
</section>
</section> <section anchor="response-token-multiple">
<section anchor="response-token-multiple"><name>Multiple Access Tokens</name> <name>Multiple Access Tokens</name>
<t>If the client instance has requested multiple access tokens and the
<t>If the client instance has requested multiple access tokens and the AS has AS has
granted at least one of them, the AS responds with the granted at least one of them, the AS responds with the
"access_token" field. The value of this field is a JSON "access_token" field. The value of this field is a JSON
array, the members of which are distinct access array, the members of which are distinct access
tokens as described in <xref target="response-token-single"/>. tokens as described in <xref target="response-token-single"/>.
Each object <bcp14>MUST</bcp14> have a unique <spanx style="verb">label</spanx> Each object <bcp14>MUST</bcp14> have a unique <tt>label</tt> field, correspondin
field, corresponding to the token labels g to the token labels
chosen by the client instance in the <xref target="request-token-multiple">multi chosen by the client instance in the request for multiple access tokens (<xref t
ple access token request</xref>.</t> arget="request-token-multiple"> </xref>).</t>
<t>In the following non-normative example, two tokens are issued under
<t>In the following non-normative example, two tokens are issued under the the
names <spanx style="verb">token1</spanx> and <spanx style="verb">token2</spanx>, names <tt>token1</tt> and <tt>token2</tt>, and only the first token has a manage
and only the first token has a management ment
URI associated with it.</t> URI associated with it.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"access_token": [ "access_token": [
{ {
"label": "token1", "label": "token1",
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": { "manage": {
"uri": "https://server.example.com/token/PRY5NM33O", "uri": "https://server.example.com/token/PRY5NM33O",
"access_token": { "access_token": {
"value": "B8CDFONP21-4TB8N6.BW7ONM" "value": "B8CDFONP21-4TB8N6.BW7ONM"
} }
}, },
"access": [ "finance" ] "access": [ "finance" ]
}, },
{ {
"label": "token2", "label": "token2",
"value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1", "value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1",
"access": [ "medical" ] "access": [ "medical" ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Each access token corresponds to one of the objects in the <tt>acce
<t>Each access token corresponds to one of the objects in the <spanx style="verb ss_token</tt> array of
">access_token</spanx> array of the client instance's request (<xref target="request-token-multiple"> </xref>).<
the client instance's <xref target="request-token-multiple">request</xref>.</t> /t>
<t>The AS <bcp14>MAY</bcp14> refuse to issue one or more of the
<t>The AS <bcp14>MAY</bcp14> refuse to issue one or more of the requested access tokens for any reason. In such cases, the refused token is omit
requested access tokens, for any reason. In such cases the refused token is omit ted
ted from the response, and all of the other issued access
from the response and all of the other issued access
tokens are included in the response under their respective requested labels. tokens are included in the response under their respective requested labels.
If the client instance <xref target="request-token-multiple">requested multiple access tokens</xref>, the AS <bcp14>MUST NOT</bcp14> respond with a If the client instance requested multiple access tokens (<xref target="request-t oken-multiple"> </xref>), the AS <bcp14>MUST NOT</bcp14> respond with a
single access token structure, even if only a single access token is granted. In such cases, the AS <bcp14>MUST</bcp14> respond single access token structure, even if only a single access token is granted. In such cases, the AS <bcp14>MUST</bcp14> respond
with a multiple access token structure containing one access token.</t> with a structure for multiple access tokens containing one access token.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"access_token": [ "access_token": [
{ {
"label": "token2", "label": "token2",
"value": "8N6BW7OZB8CDFONP219-OS9M2PMHKUR64TBRP1LT0", "value": "8N6BW7OZB8CDFONP219-OS9M2PMHKUR64TBRP1LT0",
"manage": { "manage": {
"uri": "https://server.example.com/token/PRY5NM33O", "uri": "https://server.example.com/token/PRY5NM33O",
"access_token": { "access_token": {
"value": "B8CDFONP21-4TB8N6.BW7ONM" "value": "B8CDFONP21-4TB8N6.BW7ONM"
} }
}, },
"access": [ "fruits" ] "access": [ "fruits" ]
} }
] ]
]]></sourcecode></figure> ]]></sourcecode>
<t>The parameters of each access token are separate. For example, each
<t>The parameters of each access token are separate. For example, each access to access token is expected to
ken is expected to have a unique value and (if present) label, and each access token likely has dif
have a unique value and (if present) label, and likely has different access righ ferent access rights associated with
ts associated with
it. Each access token could also be bound to different keys with different proof ing mechanisms.</t> it. Each access token could also be bound to different keys with different proof ing mechanisms.</t>
</section>
</section> </section>
</section> <section anchor="response-interact">
<section anchor="response-interact"><name>Interaction Modes</name> <name>Interaction Modes</name>
<t>If the client instance has indicated a capability to interact with th
<t>If the client instance has indicated a <xref target="request-interact">capabi e RO in its request (<xref target="request-interact"> </xref>)
lity to interact with the RO in its request</xref>,
and the AS has determined that interaction is both and the AS has determined that interaction is both
supported and necessary, the AS responds to the client instance with any of the supported and necessary, the AS responds to the client instance with any of the
following values in the <spanx style="verb">interact</spanx> field of the respon se. There is following values in the <tt>interact</tt> field of the response. There is
no preference order for interaction modes in the response, no preference order for interaction modes in the response,
and it is up to the client instance to determine which ones to use. All supporte d and it is up to the client instance to determine which ones to use. All supporte d
interaction methods are included in the same <spanx style="verb">interact</spanx interaction methods are included in the same <tt>interact</tt> object.</t>
> object.</t> <dl>
<dt><tt>redirect</tt> (string):</dt>
<dl> <dd>
<dt><spanx style="verb">redirect</spanx> (string):</dt> <t>Redirect to an arbitrary URI. <bcp14>REQUIRED</bcp14> if the <tt>
<dd> redirect</tt> interaction start mode is possible for this request. See <xref tar
<t>Redirect to an arbitrary URI. <bcp14>REQUIRED</bcp14> if the <spanx style get="response-interact-redirect"/>.</t>
="verb">redirect</spanx> interaction start mode is possible for this request. Se </dd>
e <xref target="response-interact-redirect"/>.</t> <dt><tt>app</tt> (string):</dt>
</dd> <dd>
<dt><spanx style="verb">app</spanx> (string):</dt> <t>Launch of an application URI. <bcp14>REQUIRED</bcp14> if the <tt>
<dd> app</tt> interaction start mode is possible for this request. See <xref target="
<t>Launch of an application URI. <bcp14>REQUIRED</bcp14> if the <spanx style response-interact-app"/>.</t>
="verb">app</spanx> interaction start mode is possible for this request. See <xr </dd>
ef target="response-interact-app"/>.</t> <dt><tt>user_code</tt> (string):</dt>
</dd> <dd>
<dt><spanx style="verb">user_code</spanx> (string):</dt> <t>Display a short user code. <bcp14>REQUIRED</bcp14> if the <tt>use
<dd> r_code</tt> interaction start mode is possible for this request. See <xref targe
<t>Display a short user code. <bcp14>REQUIRED</bcp14> if the <spanx style="v t="response-interact-usercode"/>.</t>
erb">user_code</spanx> interaction start mode is possible for this request. See </dd>
<xref target="response-interact-usercode"/>.</t> <dt><tt>user_code_uri</tt> (object):</dt>
</dd> <dd>
<dt><spanx style="verb">user_code_uri</spanx> (object):</dt> <t>Display a short user code and URI. <bcp14>REQUIRED</bcp14> if the
<dd> <tt>user_code_uri</tt> interaction start mode is possible for this request. <xr
<t>Display a short user code and URI. <bcp14>REQUIRED</bcp14> if the <spanx ef target="response-interact-usercodeuri"/></t>
style="verb">user_code_uri</spanx> interaction start mode is possible for this r </dd>
equest. <xref target="response-interact-usercodeuri"/></t> <dt><tt>finish</tt> (string):</dt>
</dd> <dd>
<dt><spanx style="verb">finish</spanx> (string):</dt> <t>A unique ASCII string value provided by the AS as a nonce. This i
<dd> s used by the client instance to verify the callback after interaction is comple
<t>A unique ASCII string value provided by the AS as a nonce. This is used b ted. <bcp14>REQUIRED</bcp14> if the interaction finish method requested by the c
y the client instance to verify the callback after interaction is completed. <bc lient instance is possible for this request. See <xref target="response-interact
p14>REQUIRED</bcp14> if the interaction finish method requested by the client in -finish"/>.</t>
stance is possible for this request. See <xref target="response-interact-finish" </dd>
/>.</t> <dt><tt>expires_in</tt> (integer):</dt>
</dd> <dd>
<dt><spanx style="verb">expires_in</spanx> (integer):</dt> <t>The number of integer seconds after which this set of interaction
<dd> responses will expire and no longer be usable by the client instance. If the in
<t>The number of integer seconds after which this set of interaction respons teraction methods expire, the client <bcp14>MAY</bcp14> restart the interaction
es will expire and no longer be usable by the client instance. If the interactio process for this grant request by sending an update (<xref target="continue-modi
n methods expire, the client <bcp14>MAY</bcp14> re-start the interaction process fy"> </xref>) with a new interaction request field (<xref target="request-intera
for this grant request by sending an <xref target="continue-modify">update</xre ct"> </xref>). <bcp14>OPTIONAL</bcp14>. If omitted, the interaction response mod
f> with a new <xref target="request-interact">interaction request</xref> section es returned do not expire but <bcp14>MAY</bcp14> be invalidated by the AS at any
. <bcp14>OPTIONAL</bcp14>. If omitted, the interaction response modes returned d time.</t>
o not expire but <bcp14>MAY</bcp14> be invalidated by the AS at any time.</t> </dd>
</dd> </dl>
</dl> <t>Additional interaction mode responses can be defined in the "GNAP Int
eraction Mode Responses" registry (<xref target="IANA-interaction-response"> </x
<t>Additional interaction mode responses can be defined in the <xref target="IAN ref>).</t>
A-interaction-response">GNAP Interaction Mode Responses Registry</xref>.</t> <t>The AS <bcp14>MUST NOT</bcp14> respond with any interaction mode that
the
<t>The AS <bcp14>MUST NOT</bcp14> respond with any interaction mode that the client instance did not indicate in its request, and the AS <bcp14>MUST NOT</bcp
client instance did not indicate in its request. The AS <bcp14>MUST NOT</bcp14> 14> respond with
respond with
any interaction mode that the AS does not support. Since interaction any interaction mode that the AS does not support. Since interaction
responses include secret or unique information, the AS <bcp14>SHOULD</bcp14> responses include secret or unique information, the AS <bcp14>SHOULD</bcp14>
respond to each interaction mode only once in an ongoing request, respond to each interaction mode only once in an ongoing request,
particularly if the client instance <xref target="continue-modify">modifies its particularly if the client instance modifies its request (<xref target="continue
request</xref>.</t> -modify"> </xref>).</t>
<t>The grant request <bcp14>MUST</bcp14> be in the <em>pending</em> stat
<t>The grant request <bcp14>MUST</bcp14> be in the <em>pending</em> state to inc e to include this field in the response.</t>
lude this field in the response.</t> <section anchor="response-interact-redirect">
<name>Redirection to an Arbitrary URI</name>
<section anchor="response-interact-redirect"><name>Redirection to an arbitrary U <t>If the client instance indicates that it can redirect to an arbitra
RI</name> ry URI (<xref target="request-interact-redirect"> </xref>) and the AS supports t
his mode for the client instance's
<t>If the client instance indicates that it can <xref target="request-interact-r
edirect">redirect to an arbitrary URI</xref> and the AS supports this mode for t
he client instance's
request, the AS responds with the "redirect" field, which is request, the AS responds with the "redirect" field, which is
a string containing the URI for the end user to visit. This URI <bcp14>MUST</bcp 14> be a string containing the URI for the end user to visit. This URI <bcp14>MUST</bcp 14> be
unique for the request and <bcp14>MUST NOT</bcp14> contain any security-sensitiv e unique for the request and <bcp14>MUST NOT</bcp14> contain any security-sensitiv e
information such as user identifiers or access tokens.</t> information such as user identifiers or access tokens.</t>
<artwork><![CDATA[
<figure><artwork><![CDATA[
"interact": { "interact": {
"redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ" "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ"
} }
]]></artwork></figure> ]]></artwork>
<t>The URI returned is a function of the AS, but the URI itself <bcp14>MAY</bcp1 <t>The URI returned is a function of the AS, but the URI itself <bcp14
4> be completely >MAY</bcp14> be completely
distinct from the grant endpoint URI that the client instance uses to <xref targ distinct from the grant endpoint URI that the client instance uses to request ac
et="request">request access</xref>, allowing an cess (<xref target="request"> </xref>), allowing an
AS to separate its user-interactive functionality from its back-end security AS to separate its user-interaction functionality from its backend security
functionality. The AS will need to dereference the specific grant functionality. The AS will need to dereference the specific grant
request and its information from the URI alone. If the AS does not directly host the functionality accessed through request and its information from the URI alone. If the AS does not directly host the functionality accessed through
the redirect URI, then the means for the interaction functionality to communicat e the redirect URI, then the means for the interaction functionality to communicat e
with the rest of the AS are out of scope for this specification.</t> with the rest of the AS are out of scope for this specification.</t>
<t>The client instance sends the end user to the URI to interact with
<t>The client instance sends the end user to the URI to interact with the AS. Th the AS. The
e
client instance <bcp14>MUST NOT</bcp14> alter the URI in any way. The means for the client instance client instance <bcp14>MUST NOT</bcp14> alter the URI in any way. The means for the client instance
to send the end user to this URI is out of scope of this specification, to send the end user to this URI are out of scope of this specification,
but common methods include an HTTP redirect, launching the system but common methods include an HTTP redirect, launching the system
browser, displaying a scannable code, or printing out the URI in an browser, displaying a scannable code, or printing out the URI in an
interactive console. See details of the interaction in <xref target="interaction -redirect"/>.</t> interactive console. See details of the interaction in <xref target="interaction -redirect"/>.</t>
</section>
</section> <section anchor="response-interact-app">
<section anchor="response-interact-app"><name>Launch of an application URI</name <name>Launch of an Application URI</name>
> <t>If the client instance indicates that it can launch an application
URI (<xref target="request-interact-app"> </xref>) and
<t>If the client instance indicates that it can <xref target="request-interact-a
pp">launch an application URI</xref> and
the AS supports this mode for the client instance's request, the AS the AS supports this mode for the client instance's request, the AS
responds with the "app" field, which is a string containing the URI responds with the "app" field, which is a string containing the URI
for the client instance to launch. This URI <bcp14>MUST</bcp14> be unique for th e request and for the client instance to launch. This URI <bcp14>MUST</bcp14> be unique for th e request and
<bcp14>MUST NOT</bcp14> contain any security-sensitive information such as user identifiers or access tokens.</t> <bcp14>MUST NOT</bcp14> contain any security-sensitive information such as user identifiers or access tokens.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"app": "https://app.example.com/launch?tx=4CF492MLV" "app": "https://app.example.com/launch?tx=4CF492MLV"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The means for the launched application to communicate with the AS a
<t>The means for the launched application to communicate with the AS are out of re out of
scope for this specification.</t> scope for this specification.</t>
<t>The client instance launches the URI as appropriate on its platform
<t>The client instance launches the URI as appropriate on its platform, and ; the means for the client instance to launch this URI are out of scope of this
the means for the client instance to launch this URI is out of scope of this
specification. The client instance <bcp14>MUST NOT</bcp14> alter the URI in any way. The specification. The client instance <bcp14>MUST NOT</bcp14> alter the URI in any way. The
client instance <bcp14>MAY</bcp14> attempt to detect if an installed application will client instance <bcp14>MAY</bcp14> attempt to detect if an installed application will
service the URI being sent before attempting to launch the service the URI being sent before attempting to launch the
application URI. See details of the interaction in <xref target="interaction-app "/>.</t> application URI. See details of the interaction in <xref target="interaction-app "/>.</t>
</section>
</section> <section anchor="response-interact-usercode">
<section anchor="response-interact-usercode"><name>Display of a Short User Code< <name>Display of a Short User Code</name>
/name> <t>If the client instance indicates that it can
display a short, user-typeable code (<xref target="request-interact-usercode"> <
<t>If the client instance indicates that it can /xref>)
<xref target="request-interact-usercode">display a short user-typeable code</xre
f>
and the AS supports this mode for the client instance's and the AS supports this mode for the client instance's
request, the AS responds with a "user_code" field. This field is string request, the AS responds with a "user_code" field. This field is string
containing a unique short code that the user containing a unique short code that the user
can type into a web page. To facilitate usability, this string <bcp14>MUST</bcp1 4> consist only of characters can type into a web page. To facilitate usability, this string <bcp14>MUST</bcp1 4> consist only of characters
that can be easily typed by the end user that can be easily typed by the end user
(such as ASCII letters or numbers) and (such as ASCII letters or numbers) and
<bcp14>MUST</bcp14> be processed by the AS in a case-insensitive manner (see <xr ef target="interaction-usercode"/>). <bcp14>MUST</bcp14> be processed by the AS in a case-insensitive manner (see <xr ef target="interaction-usercode"/>).
The string <bcp14>MUST</bcp14> be randomly generated The string <bcp14>MUST</bcp14> be randomly generated
so as to be unguessable by an attacker within the time it is accepted. The time in which this so as to be unguessable by an attacker within the time it is accepted. The time in which this
code will be accepted <bcp14>SHOULD</bcp14> be short lived, such as several code will be accepted <bcp14>SHOULD</bcp14> be short lived, such as several
minutes. It is <bcp14>RECOMMENDED</bcp14> that this code be no more than eight minutes. It is <bcp14>RECOMMENDED</bcp14> that this code be between six and eigh t
characters in length.</t> characters in length.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"user_code": "A1BC3DFF" "user_code": "A1BC3DFF"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The client instance <bcp14>MUST</bcp14> communicate the "user_code"
<t>The client instance <bcp14>MUST</bcp14> communicate the "user_code" value to value to the end user in some
the end user in some
fashion, such as displaying it on a screen or reading it out fashion, such as displaying it on a screen or reading it out
audibly. This code is used by the interaction component of the AS as a means audibly. This code is used by the interaction component of the AS as a means
of identifying the pending grant request and does not function as an of identifying the pending grant request and does not function as an
authentication factor for the RO.</t> authentication factor for the RO.</t>
<t>The URI that the end user is intended to enter the code into <bcp14
<t>The URI that the end user is intended to enter the code into <bcp14>MUST</bcp >MUST</bcp14> be stable,
14> be stable,
since the client instance is expected to have no means of communicating a since the client instance is expected to have no means of communicating a
dynamic URI to the end user at runtime.</t> dynamic URI to the end user at runtime.</t>
<t>As this interaction mode is designed to facilitate interaction
<t>As this interaction mode is designed to facilitate interaction
via a secondary device, it is not expected that the client instance redirect via a secondary device, it is not expected that the client instance redirect
the end user to the URI where the code is entered. the end user to the URI where the code is entered.
If the client instance is capable of communicating an If the client instance is capable of communicating a
short arbitrary URI to the end user for use with the user code, the client short arbitrary URI to the end user for use with the user code, the client
instance <bcp14>SHOULD</bcp14> instead use the <xref target="request-interact-us ercodeuri">"user_code_uri"</xref> mode. instance <bcp14>SHOULD</bcp14> instead use the "user_code_uri" mode (<xref targe t="request-interact-usercodeuri"></xref>).
If the client instance is capable of communicating a long arbitrary URI to the e nd user, If the client instance is capable of communicating a long arbitrary URI to the e nd user,
such as through a scannable code, the such as through a scannable code, the
client instance <bcp14>SHOULD</bcp14> use the <xref target="request-interact-red client instance <bcp14>SHOULD</bcp14> use the "redirect" mode (<xref target="req
irect">"redirect"</xref> mode uest-interact-redirect"> </xref>)
for this purpose instead of or in addition to the user code mode.</t> for this purpose, instead of or in addition to the user code mode.</t>
<t>See details of the interaction in <xref target="interaction-usercod
<t>See details of the interaction in <xref target="interaction-usercode"/>.</t> e"/>.</t>
</section>
</section> <section anchor="response-interact-usercodeuri">
<section anchor="response-interact-usercodeuri"><name>Display of a Short User Co <name>Display of a Short User Code and URI</name>
de and URI</name> <t>If the client instance indicates that it can
display a short, user-typeable code (<xref target="request-interact-usercode"> <
<t>If the client instance indicates that it can /xref>)
<xref target="request-interact-usercode">display a short user-typeable code</xre
f>
and the AS supports this mode for the client instance's and the AS supports this mode for the client instance's
request, the AS responds with a "user_code_uri" request, the AS responds with a "user_code_uri"
object that contains the following members.</t> object that contains the following members.</t>
<dl>
<dl> <dt><tt>code</tt> (string):</dt>
<dt><spanx style="verb">code</spanx> (string):</dt> <dd>
<dd> <t>A unique short code that the end user
<t>A unique short code that the end user
can type into a provided URI. To facilitate usability, this string <bcp14>MUST </bcp14> consist only of characters can type into a provided URI. To facilitate usability, this string <bcp14>MUST </bcp14> consist only of characters
that can be easily typed by the end user that can be easily typed by the end user
(such as ASCII letters or numbers) and (such as ASCII letters or numbers) and
<bcp14>MUST</bcp14> be processed by the AS in a case-insensitive manner (see < xref target="interaction-usercodeuri"/>). <bcp14>MUST</bcp14> be processed by the AS in a case-insensitive manner (see < xref target="interaction-usercodeuri"/>).
The string <bcp14>MUST</bcp14> be randomly generated The string <bcp14>MUST</bcp14> be randomly generated
so as to be unguessable by an attacker within the time it is accepted. The tim e in which this so as to be unguessable by an attacker within the time it is accepted. The tim e in which this
code will be accepted <bcp14>SHOULD</bcp14> be short lived, such as several code will be accepted <bcp14>SHOULD</bcp14> be short lived, such as several
minutes. It is <bcp14>RECOMMENDED</bcp14> that this code be no more than eight minutes. It is <bcp14>RECOMMENDED</bcp14> that this code be between six and ei ght
characters in length. characters in length.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">uri</spanx> (string):</dt> <dt><tt>uri</tt> (string):</dt>
<dd> <dd>
<t>The interaction URI that the client instance <t>The interaction URI that the client instance
will direct the RO to. This URI <bcp14>MUST</bcp14> be short enough to be will direct the RO to. This URI <bcp14>MUST</bcp14> be short enough to be
communicated to the end user by the client instance. It is <bcp14>RECOMMENDED< /bcp14> that this URI communicated to the end user by the client instance. It is <bcp14>RECOMMENDED< /bcp14> that this URI
be short enough for an end user to type in manually. The URI be short enough for an end user to type in manually. The URI
<bcp14>MUST NOT</bcp14> contain the <spanx style="verb">code</spanx> value. Th is URI <bcp14>MUST</bcp14> be an absolute URI. <bcp14>MUST NOT</bcp14> contain the <tt>code</tt> value. This URI <bcp14>MUST< /bcp14> be an absolute URI.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"user_code_uri": { "user_code_uri": {
"code": "A1BC3DFF", "code": "A1BC3DFF",
"uri": "https://s.example/device" "uri": "https://s.example/device"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The client instance <bcp14>MUST</bcp14> communicate the "code" to t
<t>The client instance <bcp14>MUST</bcp14> communicate the "code" to the end use he end user in some
r in some
fashion, such as displaying it on a screen or reading it out fashion, such as displaying it on a screen or reading it out
audibly. This code is used by the interaction component of the AS as a means audibly. This code is used by the interaction component of the AS as a means
of identifying the pending grant request and does not function as an of identifying the pending grant request and does not function as an
authentication factor for the RO.</t> authentication factor for the RO.</t>
<t>The client instance <bcp14>MUST</bcp14> also communicate the URI to
<t>The client instance <bcp14>MUST</bcp14> also communicate the URI to the end u the end user. Since it is expected
ser. Since it is expected
that the end user will continue interaction on a secondary device, that the end user will continue interaction on a secondary device,
the URI needs to be short enough to allow the end user to type or copy it to a s econdary the URI needs to be short enough to allow the end user to type or copy it to a s econdary
device without mistakes.</t> device without mistakes.</t>
<t>The URI returned is a function of the AS, but the URI itself <bcp14
<t>The URI returned is a function of the AS, but the URI itself <bcp14>MAY</bcp1 >MAY</bcp14> be completely
4> be completely distinct from the grant endpoint URI that the client instance uses to request ac
distinct from the grant endpoint URI that the client instance uses to <xref targ cess (<xref target="request"> </xref>), allowing an
et="request">request access</xref>, allowing an AS to separate its user-interaction functionality from its backend security
AS to separate its user-interactive functionality from its back-end security
functionality. If the AS does not directly host the functionality accessed throu gh functionality. If the AS does not directly host the functionality accessed throu gh
the given URI, then the means for the interaction functionality to communicate the given URI, then the means for the interaction functionality to communicate
with the rest of the AS are out of scope for this specification.</t> with the rest of the AS are out of scope for this specification.</t>
<t>See details of the interaction in <xref target="interaction-usercod
<t>See details of the interaction in <xref target="interaction-usercode"/>.</t> e"/>.</t>
</section>
</section> <section anchor="response-interact-finish">
<section anchor="response-interact-finish"><name>Interaction Finish</name> <name>Interaction Finish</name>
<t>If the client instance indicates that it can receive a post-interac
<t>If the client instance indicates that it can <xref target="request-interact-f tion redirect or push at a URI (<xref target="request-interact-finish"> </xref>)
inish">receive a post-interaction redirect or push at a URI</xref>
and the AS supports this mode for the and the AS supports this mode for the
client instance's request, the AS responds with a <spanx style="verb">finish</sp anx> field containing a nonce client instance's request, the AS responds with a <tt>finish</tt> field containi ng a nonce
that the client instance will use in validating the callback as defined in that the client instance will use in validating the callback as defined in
<xref target="interaction-finish"/>.</t> <xref target="interaction-finish"/>.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"interact": { "interact": {
"finish": "MBDOFXG4Y5CVJCX821LH" "finish": "MBDOFXG4Y5CVJCX821LH"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>When the interaction is completed, the interaction component of the
<t>When the interaction is completed, the interaction component of the AS <bcp14 AS <bcp14>MUST</bcp14> contact the client instance using the means defined by t
>MUST</bcp14> contact the client instance using the means defined by the finish he finish method
method
as described in <xref target="interaction-finish"/>.</t> as described in <xref target="interaction-finish"/>.</t>
<t>If the AS returns the <tt>finish</tt> field, the client instance <b
<t>If the AS returns the finish field, the client instance <bcp14>MUST NOT</bcp1 cp14>MUST NOT</bcp14>
4>
continue a grant request before it receives the associated continue a grant request before it receives the associated
interaction reference on the callback URI. See details in <xref target="interact ion-finish"/>.</t> interaction reference on the callback URI. See details in <xref target="interact ion-finish"/>.</t>
</section>
</section> </section>
</section> <section anchor="response-subject">
<section anchor="response-subject"><name>Returning Subject Information</name> <name>Returning Subject Information</name>
<t>If information about the RO is requested and the AS
<t>If information about the RO is requested and the AS
grants the client instance access to that data, the AS returns the approved grants the client instance access to that data, the AS returns the approved
information in the "subject" response field. The AS <bcp14>MUST</bcp14> return t he <spanx style="verb">subject</spanx> field only in cases where the AS is sure that information in the "subject" response field. The AS <bcp14>MUST</bcp14> return t he <tt>subject</tt> field only in cases where the AS is sure that
the RO and the end user are the same party. This can be accomplished through som e forms of the RO and the end user are the same party. This can be accomplished through som e forms of
<xref target="authorization">interaction with the RO</xref>.</t> interaction with the RO (<xref target="authorization"> </xref>).</t>
<t>This field is an object with the following properties.</t>
<t>This field is an object with the following properties.</t> <dl>
<dt><tt>sub_ids</tt> (array of objects):</dt>
<dl> <dd>
<dt><spanx style="verb">sub_ids</spanx> (array of objects):</dt> <t>An array of Subject Identifiers for the
<dd>
<t>An array of subject identifiers for the
RO, as defined by RO, as defined by
<xref target="RFC9493"/>. <xref target="RFC9493"/>.
<bcp14>REQUIRED</bcp14> if returning subject identifiers.</t> <bcp14>REQUIRED</bcp14> if returning Subject Identifiers.</t>
</dd> </dd>
<dt><spanx style="verb">assertions</spanx> (array of objects):</dt> <dt><tt>assertions</tt> (array of objects):</dt>
<dd> <dd>
<t>An array containing assertions as objects each containing the assertion <t>An array containing assertions as objects, each containing the as
sertion
object described below. object described below.
<bcp14>REQUIRED</bcp14> if returning assertions.</t> <bcp14>REQUIRED</bcp14> if returning assertions.</t>
</dd> </dd>
<dt><spanx style="verb">updated_at</spanx> (string):</dt> <dt><tt>updated_at</tt> (string):</dt>
<dd> <dd>
<t>Timestamp as an <xref target="RFC3339"/> date string, indicating <t>Timestamp as a date string as described in <xref target="RFC3339"
/>, indicating
when the identified account was last updated. The client instance <bcp14>MAY</ bcp14> use when the identified account was last updated. The client instance <bcp14>MAY</ bcp14> use
this value to determine if it needs to request updated profile this value to determine if it needs to request updated profile
information through an identity API. The definition of such an information through an identity API. The definition of such an
identity API is out of scope for this specification. identity API is out of scope for this specification.
<bcp14>RECOMMENDED</bcp14>.</t> <bcp14>RECOMMENDED</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>Assertion objects contain the following fields:</t>
<t>Assertion objects contain the following fields:</t> <dl>
<dt><tt>format</tt> (string):</dt>
<dl> <dd>
<dt><spanx style="verb">format</spanx> (string):</dt> <t>The assertion format.
<dd>
<t>The assertion format.
Possible formats are listed in <xref target="assertion-formats"/>. Possible formats are listed in <xref target="assertion-formats"/>.
Additional assertion formats are defined by the <xref target="IANA-assertion-f ormats">GNAP Assertion Formats Registry</xref>. Additional assertion formats can be defined in the "GNAP Assertion Formats" re gistry (<xref target="IANA-assertion-formats"> </xref>).
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">value</spanx> (string):</dt> <dt><tt>value</tt> (string):</dt>
<dd> <dd>
<t>The assertion value as the JSON string serialization of the assertion. <t>The assertion value as the JSON string serialization of the asser
tion.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>The following non-normative example contains an opaque identifier and
<t>The following non-normative example contains an opaque identifier and an Open an OpenID Connect ID Token:</t>
ID Connect ID Token:</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "XUT2MFM1XBIKJKSDU8QM" "id": "XUT2MFM1XBIKJKSDU8QM"
} ], } ],
"assertions": [ { "assertions": [ {
"format": "id_token", "format": "id_token",
"value": "eyj..." "value": "eyj..."
} ] } ]
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Subject Identifiers returned by the AS <bcp14>SHOULD</bcp14> uniquely
<t>Subject identifiers returned by the AS <bcp14>SHOULD</bcp14> uniquely identif identify the RO at the
y the RO at the AS. Some forms of Subject Identifiers are opaque to the client instance (such as
AS. Some forms of subject identifier are opaque to the client instance (such as the subject of an
the subject of an issuer and subject pair), while other forms (such as email address and phone num
issuer and subject pair), while others forms (such as email address and phone nu ber) are
mber) are
intended to allow the client instance to correlate the identifier with other acc ount information intended to allow the client instance to correlate the identifier with other acc ount information
at the client instance. The client instance <bcp14>MUST NOT</bcp14> request or u at the client instance. The client instance <bcp14>MUST NOT</bcp14> request or u
se any returned subject identifiers for communication se any returned Subject Identifiers for communication
purposes (see <xref target="request-subject"/>). That is, a subject identifier r purposes (see <xref target="request-subject"/>). That is, a Subject Identifier r
eturned in the format of an email address or eturned in the format of an email address or
a phone number only identifies the RO to the AS and does not indicate that the a phone number only identifies the RO to the AS and does not indicate that the
AS has validated that the represented email address or phone number in the ident ifier AS has validated that the represented email address or phone number in the ident ifier
is suitable for communication with the current user. To get such information, is suitable for communication with the current user. To get such information,
the client instance <bcp14>MUST</bcp14> use an identity protocol to request and receive additional identity the client instance <bcp14>MUST</bcp14> use an identity protocol to request and receive additional identity
claims. The details of an identity protocol and associated schema claims. The details of an identity protocol and associated schema
are outside the scope of this specification.</t> are outside the scope of this specification.</t>
<t>The AS <bcp14>MUST</bcp14> ensure that the returned subject informati
<t>The AS <bcp14>MUST</bcp14> ensure that the returned subject information repre on represents the RO. In most cases,
sents the RO. In most cases,
the AS will also ensure that the returned subject information represents the end user authenticated the AS will also ensure that the returned subject information represents the end user authenticated
interactively at the AS. interactively at the AS.
The AS <bcp14>SHOULD NOT</bcp14> re-use subject identifiers for multiple differe The AS <bcp14>SHOULD NOT</bcp14> reuse Subject Identifiers for multiple differen
nt ROs.</t> t ROs.</t>
<t>The "sub_ids" and "assertions" response fields are independent of eac
<t>The "sub_ids" and "assertions" response fields are independent of each other. h other. That is, a
That is, a returned assertion <bcp14>MAY</bcp14> use a different Subject Identifier than ot
returned assertion <bcp14>MAY</bcp14> use a different subject identifier than ot her assertions and
her assertions and Subject Identifiers in the response. However, all Subject Identifiers and assert
subject identifiers in the response. However, all subject identifiers and assert ions returned
ions returned
<bcp14>MUST</bcp14> refer to the same party.</t> <bcp14>MUST</bcp14> refer to the same party.</t>
<t>The client instance <bcp14>MUST</bcp14> interpret all subject informa
<t>The client instance <bcp14>MUST</bcp14> interpret all subject information in tion in the context of the AS from which the
the context of the AS from which the
subject information is received, as is discussed in Section 6 of <xref target="S P80063C"/>. For example, one AS could subject information is received, as is discussed in Section 6 of <xref target="S P80063C"/>. For example, one AS could
return an email identifier of "user@example.com" for one RO, and a different AS could return that return an email identifier of "user@example.com" for one RO, and a different AS could return that
same email identifier of "user@example.com" for a completely different RO. A cli ent instance talking to same email identifier of "user@example.com" for a completely different RO. A cli ent instance talking to
both AS's needs to differentiate between these two accounts by accounting for th e AS source both ASes needs to differentiate between these two accounts by accounting for th e AS source
of each identifier and not assuming that either has a canonical claim on the ide ntifier without of each identifier and not assuming that either has a canonical claim on the ide ntifier without
additional configuration and trust agreements. Otherwise, a rogue AS could explo it this to additional configuration and trust agreements. Otherwise, a rogue AS could explo it this to
take over a targeted account asserted by a different AS.</t> take over a targeted account asserted by a different AS.</t>
<t>Extensions to this specification <bcp14>MAY</bcp14> define additional
<t>Extensions to this specification <bcp14>MAY</bcp14> define additional respons response
e properties in the "GNAP Subject Information Response Fields" registry (<xref tar
properties in the <xref target="IANA-subject-response">GNAP Subject Information get="IANA-subject-response"> </xref>).</t>
Response Fields Registry</xref>.</t> <t>The grant request <bcp14>MUST</bcp14> be in the <em>approved</em> sta
te to return this field in the response.</t>
<t>The grant request <bcp14>MUST</bcp14> be in the <em>approved</em> state to re <t>See <xref target="security-assertions"/> for considerations that the
turn this field in the response.</t> client instance has to make when accepting
<t>See <xref target="security-assertions"/> for considerations that the client i
nstance has to make when accepting
and processing assertions from the AS.</t> and processing assertions from the AS.</t>
<section anchor="assertion-formats">
<section anchor="assertion-formats"><name>Assertion Formats</name> <name>Assertion Formats</name>
<t>The following assertion formats are defined in this specification:<
<t>The following assertion formats are defined in this specification:</t> /t>
<dl>
<dl> <dt><tt>id_token</tt>:</dt>
<dt><spanx style="verb">id_token</spanx>:</dt> <dd>
<dd> <t>An OpenID Connect ID Token <xref target="OIDC"/>, in JSON Web
<t>An OpenID Connect ID Token (<xref target="OIDC"/>), in JWT compact format Token (JWT) compact format as a single string.</t>
as a single string.</t> </dd>
</dd> <dt><tt>saml2</tt>:</dt>
<dt><spanx style="verb">saml2</spanx>:</dt> <dd>
<dd> <t>A SAML 2.0 assertion <xref target="SAML2"/>, encoded as a singl
<t>A SAML 2 assertion (<xref target="SAML2"/>), encoded as a single base64ur e base64url string with no padding.</t>
l string with no padding.</t> </dd>
</dd> </dl>
</dl> </section>
</section>
</section> <section anchor="response-dynamic-handles">
</section> <name>Returning a Dynamically Bound Client Instance Identifier</name>
<section anchor="response-dynamic-handles"><name>Returning a Dynamically-bound C <t>Many parts of the client instance's request can be passed as either a
lient Instance Identifier</name> value
<t>Many parts of the client instance's request can be passed as either a value
or a reference. The use of a reference in place of a value allows or a reference. The use of a reference in place of a value allows
for a client instance to optimize requests to the AS.</t> for a client instance to optimize requests to the AS.</t>
<t>Some references, such as for the client instance's identity (<xref ta
<t>Some references, such as for the <xref target="request-instance">client insta rget="request-instance"> </xref>)
nce's identity</xref> or the requested resources (<xref target="resource-access-reference"> </xref>),
or the <xref target="resource-access-reference">requested resources</xref>, can can be managed statically through an
be managed statically through an
admin console or developer portal provided by the AS or RS. The developer admin console or developer portal provided by the AS or RS. The developer
of the client software can include these values in their code for a more of the client software can include these values in their code for a more
efficient and compact request.</t> efficient and compact request.</t>
<t>If desired, the AS <bcp14>MAY</bcp14> also generate and return an ins
<t>If desired, the AS <bcp14>MAY</bcp14> also generate and return an instance id tance identifier
entifier
dynamically to the client instance in the response to facilitate multiple dynamically to the client instance in the response to facilitate multiple
interactions with the same client instance over time. The client instance <bcp14 >SHOULD</bcp14> use this interactions with the same client instance over time. The client instance <bcp14 >SHOULD</bcp14> use this
instance identifier in future requests in lieu of sending the associated data instance identifier in future requests in lieu of sending the associated data
values in the <spanx style="verb">client</spanx> field.</t> values in the <tt>client</tt> field.</t>
<t>Dynamically generated client instance identifiers are string values t
<t>Dynamically generated client instance identifiers are string values that <bcp hat <bcp14>MUST</bcp14> be
14>MUST</bcp14> be
protected by the client instance as secrets. Instance identifier values <bcp14>M UST</bcp14> be unguessable protected by the client instance as secrets. Instance identifier values <bcp14>M UST</bcp14> be unguessable
and <bcp14>MUST NOT</bcp14> contain any information that would compromise any pa rty if revealed. Instance identifier values are and <bcp14>MUST NOT</bcp14> contain any information that would compromise any pa rty if revealed. Instance identifier values are
opaque to the client instance, and their content is determined by the AS. The in stance opaque to the client instance, and their content is determined by the AS. The in stance
identifier <bcp14>MUST</bcp14> be unique per client instance at the AS.</t> identifier <bcp14>MUST</bcp14> be unique per client instance at the AS.</t>
<dl>
<dl> <dt><tt>instance_id</tt> (string):</dt>
<dt><spanx style="verb">instance_id</spanx> (string):</dt> <dd>
<dd> <t>A string value used to represent the information
<t>A string value used to represent the information in the <tt>client</tt> object that the client instance can use in a future req
in the <spanx style="verb">client</spanx> object that the client instance can uest, as
use in a future request, as
described in <xref target="request-instance"/>. described in <xref target="request-instance"/>.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>The following non-normative example shows an instance identifier alon
<t>The following non-normative example shows an instance identifier along side a gside an issued access token.</t>
n issued access token.</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"instance_id": "7C7C4AZ9KHRS6X63AJAO", "instance_id": "7C7C4AZ9KHRS6X63AJAO",
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0"
} }
} }
]]></sourcecode>
]]></sourcecode></figure> </section>
<section anchor="response-error">
</section> <name>Error Response</name>
<section anchor="response-error"><name>Error Response</name> <t>If the AS determines that the request cannot be completed for any rea
son, it responds to the client instance with an <tt>error</tt> field in the resp
<t>If the AS determines that the request cannot be completed for any reason, it onse message. This field is either an object or a string.</t>
responds to the client instance with an <spanx style="verb">error</spanx> field <t>When returned as an object, the object contains the following fields:
in the response message. This field is either an object or a string.</t> </t>
<dl>
<t>When returned as an object, the object contains the following fields:</t> <dt><tt>code</tt> (string):</dt>
<dd>
<dl> <t>A single ASCII error code defining the error.
<dt><spanx style="verb">code</spanx> (string):</dt> The value <bcp14>MUST</bcp14> be defined in the "GNAP Error Codes" registry (<xr
<dd> ef target="IANA-error-code"> </xref>).
<t>A single ASCII error code defining the error.
The value <bcp14>MUST</bcp14> be defined in the <xref target="IANA-error-code">G
NAP Error Codes Registry</xref>.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">description</spanx> (string):</dt> <dt><tt>description</tt> (string):</dt>
<dd> <dd>
<t>A human-readable string description of the error intended for the <t>A human-readable string description of the error intended for the
developer of the client. The value is chosen by the implementation. developer of the client. The value is chosen by the implementation.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>This specification defines the following <tt>code</tt> values:</t>
<t>This specification defines the following <spanx style="verb">code</spanx> val <dl>
ues:</t> <dt><tt>"invalid_request"</tt>:</dt>
<dd>
<dl> <t>The request is missing a required parameter, includes an
<dt><spanx style="verb">"invalid_request"</spanx>:</dt> invalid parameter value, or is otherwise malformed.</t>
<dd> </dd>
<t>The request is missing a required parameter, includes an <dt><tt>"invalid_client"</tt>:</dt>
invalid parameter value or is otherwise malformed.</t> <dd>
</dd> <t>The request was made from a client that was not recognized
<dt><spanx style="verb">"invalid_client"</spanx>:</dt>
<dd>
<t>The request was made from a client that was not recognized
or allowed by the AS, or the client's signature validation failed.</t> or allowed by the AS, or the client's signature validation failed.</t>
</dd> </dd>
<dt><spanx style="verb">"invalid_interaction"</spanx></dt> <dt><tt>"invalid_interaction"</tt>:</dt>
<dd> <dd>
<t>The client instance has provided an interaction reference that is incorre <t>The client instance has provided an interaction reference that is
ct incorrect
for this request or the interaction modes in use have expired.</t> for this request, or the interaction modes in use have expired.</t>
</dd> </dd>
<dt><spanx style="verb">"invalid_flag"</spanx></dt> <dt><tt>"invalid_flag"</tt>:</dt>
<dd> <dd>
<t>The flag configuration is not valid.</t> <t>The flag configuration is not valid.</t>
</dd> </dd>
<dt><spanx style="verb">"invalid_rotation"</spanx></dt> <dt><tt>"invalid_rotation"</tt>:</dt>
<dd> <dd>
<t>The token rotation request is not valid.</t> <t>The token rotation request is not valid.</t>
</dd> </dd>
<dt><spanx style="verb">"key_rotation_not_supported"</spanx></dt> <dt><tt>"key_rotation_not_supported"</tt>:</dt>
<dd> <dd>
<t>The AS does not allow rotation of this access token's key.</t> <t>The AS does not allow rotation of this access token's key.</t>
</dd> </dd>
<dt><spanx style="verb">"invalid_continuation"</spanx>:</dt> <dt><tt>"invalid_continuation"</tt>:</dt>
<dd> <dd>
<t>The continuation of the referenced grant could not be processed.</t> <t>The continuation of the referenced grant could not be processed.<
</dd> /t>
<dt><spanx style="verb">"user_denied"</spanx>:</dt> </dd>
<dd> <dt><tt>"user_denied"</tt>:</dt>
<t>The RO denied the request.</t> <dd>
</dd> <t>The RO denied the request.</t>
<dt><spanx style="verb">"request_denied"</spanx>:</dt> </dd>
<dd> <dt><tt>"request_denied"</tt>:</dt>
<t>The request was denied for an unspecified reason.</t> <dd>
</dd> <t>The request was denied for an unspecified reason.</t>
<dt><spanx style="verb">"unknown_user"</spanx>:</dt> </dd>
<dd> <dt><tt>"unknown_user"</tt>:</dt>
<t>The user presented in the request is not known to the AS or does not matc <dd>
h the user present during interaction.</t> <t>The user presented in the request is not known to the AS or does
</dd> not match the user present during interaction.</t>
<dt><spanx style="verb">"unknown_interaction"</spanx>:</dt> </dd>
<dd> <dt><tt>"unknown_interaction"</tt>:</dt>
<t>The interaction integrity could not be established.</t> <dd>
</dd> <t>The interaction integrity could not be established.</t>
<dt><spanx style="verb">"too_fast"</spanx>:</dt> </dd>
<dd> <dt><tt>"too_fast"</tt>:</dt>
<t>The client instance did not respect the timeout in the wait response befo <dd>
re the next call.</t> <t>The client instance did not respect the timeout in the wait respo
</dd> nse before the next call.</t>
<dt><spanx style="verb">"too_many_attempts"</spanx>:</dt> </dd>
<dd> <dt><tt>"too_many_attempts"</tt>:</dt>
<t>A limit has been reached in the total number of reasonable attempts. This <dd>
number is either defined statically or adjusted based on runtime conditions by <t>A limit has been reached in the total number of reasonable attemp
the AS.</t> ts. This number is either defined statically or adjusted based on runtime condit
</dd> ions by the AS.</t>
</dl> </dd>
</dl>
<t>Additional error codes can be defined in the <xref target="IANA-error-code">G <t>Additional error codes can be defined in the "GNAP Error Codes" regis
NAP Error Codes Registry</xref>.</t> try (<xref target="IANA-error-code"> </xref>).</t>
<t>For example, if the RO denied the request while interacting with the
<t>For example, if the RO denied the request while interacting with the AS, AS,
the AS would return the following error when the client instance tries to the AS would return the following error when the client instance tries to
continue the grant request:</t> continue the grant request:</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"error": { "error": {
"code": "user_denied", "code": "user_denied",
"description": "The RO denied the request" "description": "The RO denied the request"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Alternatively, the AS <bcp14>MAY</bcp14> choose to only return the er
<t>Alternatively, the AS <bcp14>MAY</bcp14> choose to only return the error as c ror as codes and provide the error as a string. Since the <tt>description</tt> f
odes and provide the error as a string. Since the <spanx style="verb">descriptio ield is not intended to be machine-readable, the following response is considere
n</spanx> field is not intended to be machine-readable, the following response i d functionally equivalent to the previous example for the purposes of the client
s considered functionally equivalent to the previous example for the purposes of software's understanding:</t>
the client software's understanding:</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"error": "user_denied" "error": "user_denied"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If an error state is reached but the grant is in the <em>pending</em>
<t>If an error state is reached but the grant is in the <em>pending</em> state ( state (and therefore the client instance can continue), the AS <bcp14>MAY</bcp1
and therefore the client instance can continue), the AS <bcp14>MAY</bcp14> inclu 4> include the <tt>continue</tt> field in the response along with the <tt>error<
de the <spanx style="verb">continue</spanx> field in the response along with the /tt>, as defined in <xref target="response-continue"/>. This allows the client i
<spanx style="verb">error</spanx>, as defined <xref target="response-continue"/ nstance to modify its request for access, potentially leading to prompting the R
>. This allows the client instance to modify its request for access, potentially O again. Other fields <bcp14>MUST NOT</bcp14> be included in the response.</t>
leading to prompting the RO again. Other fields <bcp14>MUST NOT</bcp14> be incl </section>
uded in the response.</t> </section>
<section anchor="authorization">
</section> <name>Determining Authorization and Consent</name>
</section> <t>When the client instance makes its initial request (<xref target="reque
<section anchor="authorization"><name>Determining Authorization and Consent</nam st"> </xref>) to the AS for delegated access, it
e>
<t>When the client instance makes its <xref target="request">initial request</xr
ef> to the AS for delegated access, it
is capable of asking for several different kinds of information in response:</t> is capable of asking for several different kinds of information in response:</t>
<t><list style="symbols"> <ul spacing="normal">
<t>the access being requested, in the <spanx style="verb">access_token</spanx> <li>
request parameter</t> <t>the access being requested, in the <tt>access_token</tt> request pa
<t>the subject information being requested, in the <spanx style="verb">subject rameter</t>
</spanx> request parameter</t> </li>
<t>any additional requested information defined by extensions of this protocol <li>
</t> <t>the subject information being requested, in the <tt>subject</tt> re
</list></t> quest parameter</t>
</li>
<t>When the grant request is in the <em>processing</em> state, the AS determines <li>
what authorizations and <t>any additional requested information defined by extensions of this
protocol</t>
</li>
</ul>
<t>When the grant request is in the <em>processing</em> state, the AS dete
rmines what authorizations and
consents are required to fulfill this requested delegation. The details of how t he consents are required to fulfill this requested delegation. The details of how t he
AS makes this determination are out of scope for this document. However, there a re several common AS makes this determination are out of scope for this document. However, there a re several common
patterns defined and supported by GNAP for fulfilling these requirements, includ ing information patterns defined and supported by GNAP for fulfilling these requirements, includ ing information
sent by the client instance, information gathered through the interaction proces s, and information sent by the client instance, information gathered through the interaction proces s, and information
supplied by external parties. An individual AS can define its own policies and p rocesses for supplied by external parties. An individual AS can define its own policies and p rocesses for
deciding when and how to gather the necessary authorizations and consent, and ho w those are applied deciding when and how to gather the necessary authorizations and consent and how those are applied
to the grant request.</t> to the grant request.</t>
<t>To facilitate the AS fulfilling this request, the client instance sends
<t>To facilitate the AS fulfilling this request, the client instance sends infor information about the
mation about the
actions the client software can take, including:</t> actions the client software can take, including:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>starting interaction with the end user, in the <spanx style="verb">interact <t>starting interaction with the end user, in the <tt>interact</tt> re
</spanx> request parameter</t> quest parameter</t>
<t>receiving notification that interaction with the RO has concluded, in the < </li>
spanx style="verb">interact</spanx> request parameter</t> <li>
<t>any additional capabilities defined by extensions of this protocol</t> <t>receiving notification that interaction with the RO has concluded,
</list></t> in the <tt>interact</tt> request parameter</t>
</li>
<t>The client instance can also supply information directly to the AS in its req <li>
uest. The client instance can send several kinds of things, including:</t> <t>any additional capabilities defined by extensions of this protocol<
/t>
<t><list style="symbols"> </li>
<t>the identity of the client instance, known from the keys or identifiers in </ul>
the <spanx style="verb">client</spanx> request parameter</t> <t>The client instance can also supply information directly to the AS in i
<t>the identity of the end user, in the <spanx style="verb">user</spanx> reque ts request. The client instance can send several kinds of things, including:</t>
st parameter</t> <ul spacing="normal">
<t>any additional information presented by the client instance in the request <li>
defined by extensions of this protocol</t> <t>the identity of the client instance, known from the keys or identif
</list></t> iers in the <tt>client</tt> request parameter</t>
</li>
<t>The AS will process this presented information in the context of the client i <li>
nstance's request and <t>the identity of the end user, in the <tt>user</tt> request paramete
r</t>
</li>
<li>
<t>any additional information presented by the client instance in the
request defined by extensions of this protocol</t>
</li>
</ul>
<t>The AS will process this presented information in the context of the cl
ient instance's request and
can only trust the information as much as it trusts the presentation and context of that request. can only trust the information as much as it trusts the presentation and context of that request.
If the AS determines that the information presented in the initial request is su fficient for granting the requested If the AS determines that the information presented in the initial request is su fficient for granting the requested
access, the AS <bcp14>MAY</bcp14> move the grant request to the <em>approved</em > state and return results <xref target="response">immediately in its response</ xref> with access, the AS <bcp14>MAY</bcp14> move the grant request to the <em>approved</em > state and return results <xref target="response">immediately in its response</ xref> with
access tokens and subject information.</t> access tokens and subject information.</t>
<t>If the AS determines that additional runtime authorization is required,
<t>If the AS determines that additional runtime authorization is required, the A the AS can either deny the
S can either deny the
request outright (if there is no possible recovery) or move the grant request to the <em>pending</em> request outright (if there is no possible recovery) or move the grant request to the <em>pending</em>
state and use a number of means at its disposal to gather that authorization fro state and use a number of means at its disposal to gather that authorization fro
m the appropriate ROs, including for example:</t> m the appropriate ROs, including:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>starting interaction with the end user facilitated by the client software, <t>starting interaction with the end user facilitated by the client so
such as a redirection or user code</t> ftware, such as a redirection or user code</t>
<t>challenging the client instance through a challenge-response mechanism</t> </li>
<t>requesting that the client instance present specific additional information <li>
, such as a user's credential or an assertion</t> <t>challenging the client instance through a challenge-response mechan
<t>contacting an RO through an out-of-band mechanism, such as a push notificat ism</t>
ion</t> </li>
<t>executing an auxiliary software process through an out-of-band mechanism, s <li>
uch as querying a digital wallet</t> <t>requesting that the client instance present specific additional inf
</list></t> ormation, such as a user's credential or an assertion</t>
</li>
<li>
<t>contacting an RO through an out-of-band mechanism, such as a push n
otification</t>
</li>
<li>
<t>executing an auxiliary software process through an out-of-band mech
anism, such as querying a digital wallet</t>
</li>
</ul>
<t>The authorization and consent gathering process in GNAP is left deliberately flexible to allow for a <t>The process of gathering authorization and consent in GNAP is left deli berately flexible to allow for a
wide variety of different deployments, interactions, and methodologies. wide variety of different deployments, interactions, and methodologies.
In this process, the AS can gather consent from the RO or apply the RO's policy as necessitated by the access that has In this process, the AS can gather consent from the RO or apply the RO's policy as necessitated by the access that has
been requested. The AS can sometimes determine which RO needs to prompt for cons ent based on what has been requested been requested. The AS can sometimes determine which RO needs to prompt for cons ent based on what has been requested
by the client instance, such as a specific RS record, an identified subject, or a request requiring specific by the client instance, such as a specific RS record, an identified subject, or a request requiring specific
access such as approval by an administrator. In other cases, the request is appl ied to whichever RO is present at the time of consent gathering. This pattern is especially prevalent when the access such as approval by an administrator. In other cases, the request is appl ied to whichever RO is present at the time of consent gathering. This pattern is especially prevalent when the
end user is sent to the AS for an interactive session, during which the end user takes on the role of the RO. In these cases, the end user is delegating their o wn access as RO to the client instance.</t> end user is sent to the AS for an interactive session, during which the end user takes on the role of the RO. In these cases, the end user is delegating their o wn access as RO to the client instance.</t>
<t>The client instance can indicate that it is capable of facilitating int
<t>The client instance can indicate that it is capable of facilitating interacti eraction with the end user,
on with the end user, another party, or another piece of software through its interaction start reques
another party, or another piece of software through its <xref target="request-in t (<xref target="request-interact-start"></xref>). Here, the
teract-start">interaction start</xref> request. Here, the
AS usually needs to interact directly with AS usually needs to interact directly with
the end user to determine their identity, determine their status as an RO, and c ollect their consent. If the AS has determined the end user to determine their identity, determine their status as an RO, and c ollect their consent. If the AS has determined
that authorization is required and the AS can support one or more of the request ed interaction start that authorization is required and the AS can support one or more of the request ed interaction start
methods, the AS returns the associated <xref target="response-interact">interact methods, the AS returns the associated interaction start responses (<xref target
ion start responses</xref>. The client ="response-interact"> </xref>). The client
instance <bcp14>SHOULD</bcp14> <xref target="interaction-start">initiate one or instance <bcp14>SHOULD</bcp14> initiate one or more of these interaction methods
more of these interaction methods</xref> in order to (<xref target="interaction-start"> </xref>) in order to
facilitate the granting of the request. If more than one interaction start metho d is available, facilitate the granting of the request. If more than one interaction start metho d is available,
the means by which the client chooses which methods to follow is out of scope of the means by which the client chooses which methods to follow are out of scope o
this specification.</t> f this specification.</t>
<t>After starting interaction, the client instance can then make a continu
<t>After starting interaction, the client instance can then make a <xref target= ation request (<xref target="continue-request"> </xref>)
"continue-request">continuation request</xref> either in response to a signal indicating the finish of the interaction (<xref t
either in response to a signal indicating the <xref target="interaction-finish"> arget="interaction-finish"> </xref>), after a time-based
finish of the interaction</xref>, after a time-based polling, or through some other method defined by an extension of this specificat
polling, or through some other method defined by an extension of this specificat ion through the "GNAP Interaction Mode Responses" registry (<xref target="IANA-i
ion through the <xref target="IANA-interaction-response">GNAP Interaction Mode R nteraction-response"></xref>).</t>
esponses registry</xref>.</t> <t>If the grant request is not in the <em>approved</em> state, the
client instance can repeat the interaction process by sending a grant update req
<t>If the grant request is not in the <em>approved</em> state, the uest (<xref target="continue-modify"></xref>) with new interaction methods (<xre
client instance can repeat the interaction process by sending a <xref target="co f target="request-interact"> </xref>).</t>
ntinue-modify">grant update request</xref> with new <xref target="request-intera <t>The client instance <bcp14>MUST</bcp14> use each interaction method onc
ct">interaction</xref> methods.</t> e at most if a response can be detected.
<t>The client instance <bcp14>MUST</bcp14> use each interaction method at most o
nce, if a response can be detected.
The AS <bcp14>MUST</bcp14> handle any interact request as a one-time-use mechani sm and <bcp14>SHOULD</bcp14> apply suitable The AS <bcp14>MUST</bcp14> handle any interact request as a one-time-use mechani sm and <bcp14>SHOULD</bcp14> apply suitable
timeouts to any interaction start methods provided, including user codes and red irection URIs. timeouts to any interaction start methods provided, including user codes and red irection URIs.
The client instance <bcp14>SHOULD</bcp14> apply suitable timeouts to any interac tion finish method.</t> The client instance <bcp14>SHOULD</bcp14> apply suitable timeouts to any interac tion finish method.</t>
<t>In order to support client software deployed in disadvantaged network c
<t>In order to support client software deployed in disadvantaged network conditi onditions, the AS <bcp14>MAY</bcp14>
ons, the AS <bcp14>MAY</bcp14>
allow for processing of the same interaction method multiple times if the AS can determine allow for processing of the same interaction method multiple times if the AS can determine
that the request is from the same party and the results are idempotent. that the request is from the same party and the results are idempotent.
For example, if a client instance launches a redirect to the AS but does not rec eive a response For example, if a client instance launches a redirect to the AS but does not rec eive a response
within a reasonable time, the client software can launch the redirect again, ass uming that it never within a reasonable time, the client software can launch the redirect again, ass uming that it never
reached the AS in the first place. However, if the AS in question reached the AS in the first place. However, if the AS in question
receives both requests, it could mistakenly process them separately, creating an undefined state for the receives both requests, it could mistakenly process them separately, creating an undefined state for the
client instance. If the AS can determine that both requests come from the same o rigin or under the same session, client instance. If the AS can determine that both requests come from the same o rigin or under the same session,
and the requests both came before any additional state change to the grant occur s, the AS can reasonably and the requests both came before any additional state change to the grant occur s, the AS can reasonably
conclude that the initial response was not received and the same response can be returned to the client instance.</t> conclude that the initial response was not received and the same response can be returned to the client instance.</t>
<t>If the AS instead has a means of contacting the RO directly, it could
<t>If the AS instead has a means of contacting the RO directly, it could do so without involving the client instance in its consent-gathering process. Fo
do so without involving the client instance in its consent gathering process. Fo r example, the AS could
r example, the AS could
push a notification to a known RO and have the RO approve the pending request as ynchronously. These interactions push a notification to a known RO and have the RO approve the pending request as ynchronously. These interactions
can be through an interface of the AS itself (such as a hosted web page), throug h another application (such as can be through an interface of the AS itself (such as a hosted web page), throug h another application (such as
something installed on the RO's device), through a messaging fabric, or any othe r means.</t> something installed on the RO's device), through a messaging fabric, or any othe r means.</t>
<t>When interacting with an RO, the AS can do anything it needs to determine the <t>When interacting with an RO, the AS can use various strategies to determine
authorization of the requested grant, the authorization of the requested grant, including:
including:</t> </t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>authenticate the RO, through a local account or some other means such as fe <t>authenticate the RO through a local account or some other means, su
derated login</t> ch as federated login</t>
<t>validate the RO through presentation of claims, attributes, or other inform </li>
ation</t> <li>
<t>prompt the RO for consent for the requested delegation</t> <t>validate the RO through presentation of claims, attributes, or othe
<t>describe to the RO what information is being released, to whom, and for wha r information</t>
t purpose</t> </li>
<t>provide warnings to the RO about potential attacks or negative effects of a <li>
llowing the information</t> <t>prompt the RO for consent for the requested delegation</t>
<t>allow the RO to modify the client instance's requested access, including li </li>
miting or expanding that access</t> <li>
<t>provide the RO with artifacts such as receipts to facilitate an audit trail <t>describe to the RO what information is being released, to whom, and
of authorizations</t> for what purpose</t>
<t>allow the RO to deny the requested delegation</t> </li>
</list></t> <li>
<t>provide warnings to the RO about potential attacks or negative effe
cts of allowing the information</t>
</li>
<li>
<t>allow the RO to modify the client instance's requested access, incl
uding limiting or expanding that access</t>
</li>
<li>
<t>provide the RO with artifacts such as receipts to facilitate an aud
it trail of authorizations</t>
</li>
<li>
<t>allow the RO to deny the requested delegation</t>
</li>
</ul>
<t>The AS is also allowed to request authorization from more than one RO, if the AS deems fit. For example, a medical <t>The AS is also allowed to request authorization from more than one RO, if the AS deems fit. For example, a medical
record might need to be released by both an attending nurse and a physician, or both owners of a bank account record might need to be released by both an attending nurse and a physician, or both owners of a bank account
need to sign off on a transfer request. Alternatively, the AS could require N of M possible RO's need to sign off on a transfer request. Alternatively, the AS could require N of M possible ROs
to approve a given request. In some circumstances, the AS could even determine t hat the end user to approve a given request. In some circumstances, the AS could even determine t hat the end user
present during the interaction is not the appropriate RO present during the interaction is not the appropriate RO
for a given request and reach out to the appropriate RO asynchronously.</t> for a given request and reach out to the appropriate RO asynchronously.</t>
<t>The RO is also allowed to define an automated policy at the AS to determine w hich kind of end user can get access to the resource and under which conditions. For instance, such a condition might require the end user to log in and accept the RO's legal provisions. Alternatively, client software could be acting withou t an end user, and the RO's policy allows issuance of access tokens to specific instances of that client software without human interaction.</t>
<t>The RO is also allowed to define an automated policy at the AS to determine w <t>While all of these cases are supported by GNAP, the details of their
hich kind of end user can get access to the resource, and under which condition. implementation and the methods for determining which ROs or related policies
For instance, such a condition might require the end user login and the accepta are required for a given request are out of scope for this specification.
nce of the RO's legal provisions. Alternatively, client software could be acting </t>
without an end user, and the RO's policy allows issuance of access tokens to sp <section anchor="interaction-start">
ecific instances of that client software without human interaction.</t> <name>Starting Interaction with the End User</name>
<t>When a grant request is in the <em>pending</em> state, the interactio
<t>While all of these cases n start methods sent by
are supported by GNAP, the details of their implementation, and for determining
which RO's or
related policies are required for a given request, are out of scope for this spe
cification.</t>
<section anchor="interaction-start"><name>Starting Interaction With the End User
</name>
<t>When a grant request is in the <em>pending</em> state, the interaction start
methods sent by
the client instance can be used to facilitate interaction with the end user. the client instance can be used to facilitate interaction with the end user.
To initiate an interaction start method indicated by the To initiate an interaction start method indicated by the
<xref target="response-interact">interaction start responses</xref> from the AS, the client instance interaction start responses (<xref target="response-interact"> </xref>) from the AS, the client instance
follows the steps defined by that interaction start mode. The actions of the cli ent instance follows the steps defined by that interaction start mode. The actions of the cli ent instance
required for the interaction start modes defined in this specification are descr ibed required for the interaction start modes defined in this specification are descr ibed
in the following sections. Interaction start modes defined in extensions to this specification in the following subsections. Interaction start modes defined in extensions to t his specification
<bcp14>MUST</bcp14> define the expected actions of the client software when that interaction start mode is used.</t> <bcp14>MUST</bcp14> define the expected actions of the client software when that interaction start mode is used.</t>
<t>If the client instance does not start an interaction start mode withi
<t>If the client instance does not start an interaction start mode within an AS- n an AS-determined amount of
determined amount of
time, the AS <bcp14>MUST</bcp14> reject attempts to use the interaction start mo des. If the client instance has time, the AS <bcp14>MUST</bcp14> reject attempts to use the interaction start mo des. If the client instance has
already begun one interaction start mode and the interaction has been successful ly completed, the AS <bcp14>MUST</bcp14> reject attempts to use other interactio n already begun one interaction start mode and the interaction has been successful ly completed, the AS <bcp14>MUST</bcp14> reject attempts to use other interactio n
start modes. For example, if a user code has been successfully entered for a gra nt request, the AS start modes. For example, if a user code has been successfully entered for a gra nt request, the AS
will need to reject requests to an arbitrary redirect URI on the same grant requ est in order to prevent an will need to reject requests to an arbitrary redirect URI on the same grant requ est in order to prevent an
attacker from capturing and altering an active authorization process.</t> attacker from capturing and altering an active authorization process.</t>
<section anchor="interaction-redirect">
<section anchor="interaction-redirect"><name>Interaction at a Redirected URI</na <name>Interaction at a Redirected URI</name>
me> <t>When the end user is directed to an arbitrary URI through the "redi
rect" mode (<xref target="response-interact-redirect"> </xref>), the client inst
<t>When the end user is directed to an arbitrary URI through the <xref target="r ance facilitates opening the URI through the end user's web browser.
esponse-interact-redirect">"redirect"</xref>
mode, the client instance facilitates opening the URI through the end user's web
browser.
The client instance could launch the URI through the system browser, provide a c lickable The client instance could launch the URI through the system browser, provide a c lickable
link, redirect the user through HTTP response codes, or display the URI in a for m link, redirect the user through HTTP response codes, or display the URI in a for m
the end user can use to launch such as a multidimensional barcode. In all cases, the URI the end user can use to launch, such as a multidimensional barcode. In all cases , the URI
is accessed with an HTTP GET request, and the resulting page is assumed to allow direct interaction is accessed with an HTTP GET request, and the resulting page is assumed to allow direct interaction
with the end user through an HTTP user agent. with the end user through an HTTP user agent.
With this method, it is common (though not required) for the RO to be the same p arty as the end user, since With this method, it is common (though not required) for the RO to be the same p arty as the end user, since
the client instance has to communicate the redirection URI to the end user.</t> the client instance has to communicate the redirection URI to the end user.</t>
<t>In many cases, the URI indicates a web page hosted at the AS, allow
<t>In many cases, the URI indicates a web page hosted at the AS, allowing the ing the
AS to authenticate the end user as the RO and interactively provide consent. AS to authenticate the end user as the RO and interactively provide consent.
The URI value is used to identify the grant request being authorized. The URI value is used to identify the grant request being authorized.
If the URI cannot be associated with a currently active If the URI cannot be associated with a currently active
request, the AS <bcp14>MUST</bcp14> display an error to the RO and <bcp14>MUST N OT</bcp14> attempt request, the AS <bcp14>MUST</bcp14> display an error to the RO and <bcp14>MUST N OT</bcp14> attempt
to redirect the RO back to any client instance even if a <xref target="request-i nteract-callback-redirect">redirect finish method is supplied</xref>. to redirect the RO back to any client instance, even if a redirect finish method is supplied (<xref target="request-interact-callback-redirect"> </xref>).
If the URI is not hosted by the AS directly, the means of communication between If the URI is not hosted by the AS directly, the means of communication between
the AS and the service provided by this URI are out of scope for this specificat ion.</t> the AS and the service provided by this URI are out of scope for this specificat ion.</t>
<t>The client instance <bcp14>MUST NOT</bcp14> modify the URI when lau
<t>The client instance <bcp14>MUST NOT</bcp14> modify the URI when launching it, nching it;
in particular the client instance <bcp14>MUST NOT</bcp14> add any parameters to in particular, the client instance <bcp14>MUST NOT</bcp14> add any parameters to
the URI. the URI.
The URI <bcp14>MUST</bcp14> be reachable from the end user's browser, though The URI <bcp14>MUST</bcp14> be reachable from the end user's browser, though
the URI <bcp14>MAY</bcp14> be opened on a separate device from the client instan ce the URI <bcp14>MAY</bcp14> be opened on a separate device from the client instan ce
itself. The URI <bcp14>MUST</bcp14> be accessible from an HTTP GET itself. The URI <bcp14>MUST</bcp14> be accessible from an HTTP GET
request and <bcp14>MUST</bcp14> be protected by HTTPS, be request, and it <bcp14>MUST</bcp14> be protected by HTTPS, be
hosted on a server local to the RO's browser ("localhost"), or hosted on a server local to the RO's browser ("localhost"), or
use an application-specific URI scheme that is loaded on the end user's device.< /t> use an application-specific URI scheme that is loaded on the end user's device.< /t>
</section>
</section> <section anchor="interaction-usercode">
<section anchor="interaction-usercode"><name>Interaction at the Static User Code <name>Interaction at the Static User Code URI</name>
URI</name> <t>When the end user is directed to enter a short code through the "us
er_code" mode (<xref target="response-interact-usercode"> </xref>), the client i
<t>When the end user is directed to enter a short code through the <xref target= nstance communicates the user code to the end user and
"response-interact-usercode">"user_code"</xref>
mode, the client instance communicates the user code to the end user and
directs the end user to enter that code at an associated URI. directs the end user to enter that code at an associated URI.
The client instance <bcp14>MAY</bcp14> The client instance <bcp14>MAY</bcp14>
format the user code in such a way as to facilitate memorability and transfer of the format the user code in such a way as to facilitate memorability and transfer of the
code, so long as this formatting does not alter the value as accepted at the use r code code, so long as this formatting does not alter the value as accepted at the use r code
URI. For example, a client instance receiving the user code "A1BC3DFF" could cho ose to URI. For example, a client instance receiving the user code "A1BC3DFF" could cho ose to
display this to the user as "A1BC 3DFF", breaking up the long string into two sh orter display this to the user as "A1BC 3DFF", breaking up the long string into two sh orter
strings.</t> strings.</t>
<t>When processing input codes, the AS <bcp14>MUST</bcp14> transform t
<t>When processing input codes, the AS <bcp14>MUST</bcp14> transform the input s he input string to remove invalid characters.
tring to remove invalid characters.
In the above example, the space in between the two parts would be removed upon i ts In the above example, the space in between the two parts would be removed upon i ts
entry into the interactive form at the user code URI. Additionally, the AS <bcp1 4>MUST</bcp14> treat entry into the interactive form at the user code URI. Additionally, the AS <bcp1 4>MUST</bcp14> treat
user input as case insensitive. For example, if the user inputs the string "a1bc 3DFF", the user input as case insensitive. For example, if the user inputs the string "a1bc 3DFF", the
AS will treat the input the same as "A1BC3DFF". To facilitate this, it is <bcp14 >RECOMMENDED</bcp14> AS will treat the input the same as "A1BC3DFF". To facilitate this, it is <bcp14 >RECOMMENDED</bcp14>
that the AS use only ASCII letters and numbers as valid characters for the user code.</t> that the AS use only ASCII letters and numbers as valid characters for the user code.</t>
<t>It is <bcp14>RECOMMENDED</bcp14> that the AS choose from character
<t>It is <bcp14>RECOMMENDED</bcp14> that the AS choose from character values tha values that are easily copied and typed without ambiguity.
t are easily copied and typed without ambiguity. For example, some glyphs have multiple Unicode code points for the same visual c
For example, some glyphs have multiple Unicode code points for the same visual c haracter, and the end user
haracter, and the end-user
could potentially type a different character than what the AS has returned. could potentially type a different character than what the AS has returned.
For additional considerations of internationalized character strings, see <xref For additional considerations of internationalized character strings, see <xref
target="RFC8264"/></t> target="RFC8264"/>.</t>
<t>This mode is designed to be used when the client instance is not ab
<t>This mode is designed to be used when the client instance is not able to comm le to communicate or facilitate launching
unicate or facilitate launching
an arbitrary URI. The associated URI could be statically configured with the cli ent instance or an arbitrary URI. The associated URI could be statically configured with the cli ent instance or
in the client software's documentation. As a consequence, these URIs <bcp14>SHOU LD</bcp14> be short. in the client software's documentation. As a consequence, these URIs <bcp14>SHOU LD</bcp14> be short.
The user code URI <bcp14>MUST</bcp14> be reachable from the end user's browser, though The user code URI <bcp14>MUST</bcp14> be reachable from the end user's browser, though
the URI is usually opened on a separate device from the client instance the URI is usually opened on a separate device from the client instance
itself. The URI <bcp14>MUST</bcp14> be accessible from an HTTP GET itself. The URI <bcp14>MUST</bcp14> be accessible from an HTTP GET
request and <bcp14>MUST</bcp14> be protected by HTTPS, be request, and it <bcp14>MUST</bcp14> be protected by HTTPS, be
hosted on a server local to the RO's browser ("localhost"), or hosted on a server local to the RO's browser ("localhost"), or
use an application-specific URI scheme that is loaded on the end user's device.< /t> use an application-specific URI scheme that is loaded on the end user's device.< /t>
<t>In many cases, the URI indicates a web page hosted at the AS, allow
<t>In many cases, the URI indicates a web page hosted at the AS, allowing the ing the
AS to authenticate the end user as the RO and interactively provide consent. AS to authenticate the end user as the RO and interactively provide consent.
The value of the user code is used to identify the grant request being authorize d. The value of the user code is used to identify the grant request being authorize d.
If the user code cannot be associated with a currently active If the user code cannot be associated with a currently active
request, the AS <bcp14>MUST</bcp14> display an error to the RO and <bcp14>MUST N OT</bcp14> attempt request, the AS <bcp14>MUST</bcp14> display an error to the RO and <bcp14>MUST N OT</bcp14> attempt
to redirect the RO back to any client instance even if a <xref target="request-i nteract-callback-redirect">redirect finish method is supplied</xref>. to redirect the RO back to any client instance, even if a redirect finish method is supplied (<xref target="request-interact-callback-redirect"> </xref>).
If the interaction component at the user code URI is not hosted by the AS direct ly, the means of communication between If the interaction component at the user code URI is not hosted by the AS direct ly, the means of communication between
the AS and this URI, including communication of the user code itself, are out of scope for this specification.</t> the AS and this URI, including communication of the user code itself, are out of scope for this specification.</t>
<t>When the RO enters this code at the user code URI,
<t>When the RO enters this code at the user code URI,
the AS <bcp14>MUST</bcp14> uniquely identify the pending request that the code w as associated the AS <bcp14>MUST</bcp14> uniquely identify the pending request that the code w as associated
with. If the AS does not recognize the entered code, the interaction component < bcp14>MUST</bcp14> with. If the AS does not recognize the entered code, the interaction component < bcp14>MUST</bcp14>
display an error to the user. If the AS detects too many unrecognized code display an error to the user. If the AS detects too many unrecognized code
enter attempts, the interaction component <bcp14>SHOULD</bcp14> display an error to the user indicating too many attempts and enter attempts, the interaction component <bcp14>SHOULD</bcp14> display an error to the user indicating too many attempts and
<bcp14>MAY</bcp14> take additional actions such as slowing down the input intera ctions. <bcp14>MAY</bcp14> take additional actions such as slowing down the input intera ctions.
The user should be warned as such an error state is approached, if possible.</t> The user should be warned as such an error state is approached, if possible.</t>
</section>
</section> <section anchor="interaction-usercodeuri">
<section anchor="interaction-usercodeuri"><name>Interaction at a Dynamic User Co <name>Interaction at a Dynamic User Code URI</name>
de URI</name> <t>When the end user is directed to enter a short code through the "us
er_code_uri" mode (<xref target="response-interact-usercodeuri"> </xref>), the c
<t>When the end user is directed to enter a short code through the <xref target= lient instance communicates the user code and associated URI to the end user and
"response-interact-usercodeuri">"user_code_uri"</xref>
mode, the client instance communicates the user code and associated URI to the e
nd user and
directs the end user to enter that code at the URI. directs the end user to enter that code at the URI.
The client instance <bcp14>MAY</bcp14> The client instance <bcp14>MAY</bcp14>
format the user code in such a way as to facilitate memorability and transfer of the format the user code in such a way as to facilitate memorability and transfer of the
code, so long as this formatting does not alter the value as accepted at the use r code code, so long as this formatting does not alter the value as accepted at the use r code
URI. For example, a client instance receiving the user code "A1BC3DFF" could cho ose to URI. For example, a client instance receiving the user code "A1BC3DFF" could cho ose to
display this to the user as "A1BC 3DFF", breaking up the long string into two sh orter display this to the user as "A1BC 3DFF", breaking up the long string into two sh orter
strings.</t> strings.</t>
<t>When processing input codes, the AS <bcp14>MUST</bcp14> transform t
<t>When processing input codes, the AS <bcp14>MUST</bcp14> transform the input s he input string to remove invalid characters.
tring to remove invalid characters.
In the above example, the space in between the two parts would be removed upon i ts In the above example, the space in between the two parts would be removed upon i ts
entry into the interactive form at the user code URI. Additionally, the AS <bcp1 4>MUST</bcp14> treat entry into the interactive form at the user code URI. Additionally, the AS <bcp1 4>MUST</bcp14> treat
user input as case insensitive. For example, if the user inputs the string "a1bc 3DFF", the user input as case insensitive. For example, if the user inputs the string "a1bc 3DFF", the
AS will treat the input the same as "A1BC3DFF". To facilitate this, it is <bcp14 >RECOMMENDED</bcp14> AS will treat the input the same as "A1BC3DFF". To facilitate this, it is <bcp14 >RECOMMENDED</bcp14>
that the AS use only ASCII letters and numbers as valid characters for the user code.</t> that the AS use only ASCII letters and numbers as valid characters for the user code.</t>
<t>This mode is used when the client instance is not able to facilitat
<t>This mode is used when the client instance is not able to facilitate launchin e launching
g
a complex arbitrary URI but can communicate arbitrary values like URIs. As a con sequence, these URIs a complex arbitrary URI but can communicate arbitrary values like URIs. As a con sequence, these URIs
<bcp14>SHOULD</bcp14> be short enough to allow the URI to be typed by the end us er, <bcp14>SHOULD</bcp14> be short enough to allow the URI to be typed by the end us er,
such as a total length of 20 characters or fewer. such as a total length of 20 characters or fewer.
The client instance <bcp14>MUST NOT</bcp14> modify the URI when communicating it to the end user; The client instance <bcp14>MUST NOT</bcp14> modify the URI when communicating it to the end user;
in particular the client instance <bcp14>MUST NOT</bcp14> add any parameters to the URI. in particular the client instance <bcp14>MUST NOT</bcp14> add any parameters to the URI.
The user code URI <bcp14>MUST</bcp14> be reachable from the end user's browser, though The user code URI <bcp14>MUST</bcp14> be reachable from the end user's browser, though
the URI is usually be opened on a separate device from the client instance the URI is usually be opened on a separate device from the client instance
itself. The URI <bcp14>MUST</bcp14> be accessible from an HTTP GET itself. The URI <bcp14>MUST</bcp14> be accessible from an HTTP GET
request and <bcp14>MUST</bcp14> be protected by HTTPS, be request, and it <bcp14>MUST</bcp14> be protected by HTTPS, be
hosted on a server local to the RO's browser ("localhost"), or hosted on a server local to the RO's browser ("localhost"), or
use an application-specific URI scheme that is loaded on the end user's device.< /t> use an application-specific URI scheme that is loaded on the end user's device.< /t>
<t>In many cases, the URI indicates a web page hosted at the AS, allow
<t>In many cases, the URI indicates a web page hosted at the AS, allowing the ing the
AS to authenticate the end user as the RO and interactively provide consent. AS to authenticate the end user as the RO and interactively provide consent.
The value of the user code is used to identify the grant request being authorize d. The value of the user code is used to identify the grant request being authorize d.
If the user code cannot be associated with a currently active If the user code cannot be associated with a currently active
request, the AS <bcp14>MUST</bcp14> display an error to the RO and <bcp14>MUST N OT</bcp14> attempt request, the AS <bcp14>MUST</bcp14> display an error to the RO and <bcp14>MUST N OT</bcp14> attempt
to redirect the RO back to any client instance even if a <xref target="request-i nteract-callback-redirect">redirect finish method is supplied</xref>. to redirect the RO back to any client instance, even if a redirect finish method is supplied (<xref target="request-interact-callback-redirect"> </xref>).
If the interaction component at the user code URI is not hosted by the AS direct ly, the means of communication between If the interaction component at the user code URI is not hosted by the AS direct ly, the means of communication between
the AS and this URI, including communication of the user code itself, are out of scope for this specification.</t> the AS and this URI, including communication of the user code itself, are out of scope for this specification.</t>
<t>When the RO enters this code at the given URI,
<t>When the RO enters this code at the given URI,
the AS <bcp14>MUST</bcp14> uniquely identify the pending request that the code w as associated the AS <bcp14>MUST</bcp14> uniquely identify the pending request that the code w as associated
with. If the AS does not recognize the entered code, the interaction component < bcp14>MUST</bcp14> with. If the AS does not recognize the entered code, the interaction component < bcp14>MUST</bcp14>
display an error to the user. If the AS detects too many unrecognized code display an error to the user. If the AS detects too many unrecognized code
enter attempts, the interaction component <bcp14>SHOULD</bcp14> display an error to the user indicating too many attempts and enter attempts, the interaction component <bcp14>SHOULD</bcp14> display an error to the user indicating too many attempts and
<bcp14>MAY</bcp14> take additional actions such as slowing down the input intera ctions. <bcp14>MAY</bcp14> take additional actions such as slowing down the input intera ctions.
The user should be warned as such an error state is approached, if possible.</t> The user should be warned as such an error state is approached, if possible.</t>
</section>
</section> <section anchor="interaction-app">
<section anchor="interaction-app"><name>Interaction through an Application URI</ <name>Interaction through an Application URI</name>
name> <t>When the client instance is directed to launch an application throu
gh the
<t>When the client instance is directed to launch an application through the "app" mode (<xref target="response-interact-app"> </xref>), the client launches
<xref target="response-interact-app">"app"</xref> mode, the client launches the the
URI as appropriate to the system, such as through a deep link or custom URI URI as appropriate to the system, such as through a deep link or custom URI
scheme registered to a mobile application. The means by which the AS and the scheme registered to a mobile application. The means by which the AS and the
launched application communicate with each other and perform any launched application communicate with each other and perform any
of the required actions are out of scope for this specification.</t> of the required actions are out of scope for this specification.</t>
</section>
</section> </section>
</section> <section anchor="interaction-finish">
<section anchor="interaction-finish"><name>Post-Interaction Completion</name> <name>Post-Interaction Completion</name>
<t>If an interaction "finish" method (<xref target="response-interact-fi
<t>If an interaction <xref target="response-interact-finish">"finish"</xref> met nish"> </xref>) is
hod is
associated with the current request, the AS <bcp14>MUST</bcp14> follow the appro priate associated with the current request, the AS <bcp14>MUST</bcp14> follow the appro priate
method upon completion of interaction in order to signal the client method upon completion of interaction in order to signal the client
instance to continue, except for some limited error cases discussed below. instance to continue, except for some limited error cases discussed below.
If a finish method is not available, the AS <bcp14>SHOULD</bcp14> instruct the R O to If a finish method is not available, the AS <bcp14>SHOULD</bcp14> instruct the R O to
return to the client instance upon completion. In such cases, it is expected return to the client instance upon completion. In such cases, it is expected
that the client instance will poll the continuation endpoint as described in <xr ef target="continue-poll"/>.</t> that the client instance will poll the continuation endpoint as described in <xr ef target="continue-poll"/>.</t>
<t>The AS <bcp14>MUST</bcp14> create an interaction reference and associ
<t>The AS <bcp14>MUST</bcp14> create an interaction reference and associate that ate that
reference with the current interaction and the underlying pending reference with the current interaction and the underlying pending
request. The interaction reference value is an ASCII string consisting of only request. The interaction reference value is an ASCII string consisting of only
unreserved characters per <xref section="2.3" sectionFormat="of" target="RFC3986 "/>. unreserved characters per <xref section="2.3" sectionFormat="of" target="RFC3986 "/>.
The interaction reference value <bcp14>MUST</bcp14> be sufficiently random so as not to be The interaction reference value <bcp14>MUST</bcp14> be sufficiently random so as not to be
guessable by an attacker. The interaction reference <bcp14>MUST</bcp14> be guessable by an attacker. The interaction reference <bcp14>MUST</bcp14> be
one-time-use to prevent interception and replay attacks.</t> one-time-use to prevent interception and replay attacks.</t>
<t>The AS <bcp14>MUST</bcp14> calculate a hash value based on the client
<t>The AS <bcp14>MUST</bcp14> calculate a hash value based on the client instanc instance, AS nonces, and the
e and AS nonces and the
interaction reference, as described in interaction reference, as described in
<xref target="interaction-hash"/>. The client instance will use this value to <xref target="interaction-hash"/>. The client instance will use this value to
validate the "finish" call.</t> validate the "finish" call.</t>
<t>All interaction finish methods <bcp14>MUST</bcp14> define a way
<t>All interaction finish methods <bcp14>MUST</bcp14> define a way
to convey the hash and interaction reference back to the client instance. When a n to convey the hash and interaction reference back to the client instance. When a n
interaction finish method is used, the client instance <bcp14>MUST</bcp14> prese nt the interaction interaction finish method is used, the client instance <bcp14>MUST</bcp14> prese nt the interaction
reference back to the AS as part of its <xref target="continue-after-interaction reference back to the AS as part of its continuation request (<xref target="cont
">continuation request</xref>.</t> inue-after-interaction"> </xref>).</t>
<t>Note that in many error cases, such as when the RO has denied
<t>Note that in many error cases, such as when the RO has denied
access, the "finish" method is still enacted by the AS. access, the "finish" method is still enacted by the AS.
This pattern allows the client instance to potentially recover from the error This pattern allows the client instance to potentially recover from the error
state by modifying its request or providing additional information directly to t he AS in a state by modifying its request or providing additional information directly to t he AS in a
continuation request. The AS <bcp14>MUST NOT</bcp14> follow the "finish" method in the continuation request. The AS <bcp14>MUST NOT</bcp14> follow the "finish" method in the
following circumstances:</t> following circumstances:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>The AS has determined that any URIs involved with the finish method are dan <t>The AS has determined that any URIs involved with the finish meth
gerous or blocked.</t> od are dangerous or blocked.</t>
<t>The AS cannot determine which ongoing grant request is being referenced.</t </li>
> <li>
<t>The ongoing grant request has been cancelled or otherwise blocked.</t> <t>The AS cannot determine which ongoing grant request is being refe
</list></t> renced.</t>
</li>
<section anchor="interaction-callback"><name>Completing Interaction with a Brows <li>
er Redirect to the Callback URI</name> <t>The ongoing grant request has been canceled or otherwise blocked.
</t>
<t>When using the <spanx style="verb">redirect</spanx> interaction finish method </li>
defined in <xref target="request-interact-callback-redirect"/> and <xref target </ul>
="response-interact-finish"/>, <section anchor="interaction-callback">
<name>Completing Interaction with a Browser Redirect to the Callback U
RI</name>
<t>When using the <tt>redirect</tt> interaction finish method defined
in Sections <xref target="request-interact-callback-redirect" format="counter"/>
and <xref target="response-interact-finish" format="counter"/>,
the AS signals to the client instance that interaction is the AS signals to the client instance that interaction is
complete and the request can be continued by directing the RO (in complete and the request can be continued by directing the RO (in
their browser) back to the client instance's redirect URI.</t> their browser) back to the client instance's redirect URI.</t>
<t>The AS secures this redirect by adding the hash and interaction
<t>The AS secures this redirect by adding the hash and interaction
reference as query parameters to the client instance's redirect URI.</t> reference as query parameters to the client instance's redirect URI.</t>
<dl>
<dl> <dt><tt>hash</tt>:</dt>
<dt><spanx style="verb">hash</spanx>:</dt> <dd>
<dd> <t>The interaction hash value as
<t>The interaction hash value as
described in <xref target="interaction-hash"/>. described in <xref target="interaction-hash"/>.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">interact_ref</spanx>:</dt> <dt><tt>interact_ref</tt>:</dt>
<dd> <dd>
<t>The interaction reference <t>The interaction reference
generated for this interaction. generated for this interaction.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>The means of directing the RO to this URI are outside the scope
<t>The means of directing the RO to this URI are outside the scope
of this specification, but common options include redirecting the of this specification, but common options include redirecting the
RO from a web page and launching the system browser with the RO from a web page and launching the system browser with the
target URI. See <xref target="security-redirect-status-codes"/> for consideratio ns on target URI. See <xref target="security-redirect-status-codes"/> for consideratio ns on
which HTTP status code to use when redirecting a request that which HTTP status code to use when redirecting a request that
potentially contains credentials.</t> potentially contains credentials.</t>
<artwork><![CDATA[
<figure><artwork><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
https://client.example.net/return/123455\ https://client.example.net/return/123455\
?hash=x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY\ ?hash=x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY\
&interact_ref=4IFWWIKYBC2PQ6U56NL1 &interact_ref=4IFWWIKYBC2PQ6U56NL1
]]></artwork></figure> ]]></artwork>
<t>The client instance <bcp14>MUST</bcp14> be able to process a reques
<t>The client instance <bcp14>MUST</bcp14> be able to process a request on the U t on the URI. If the URI is
RI. If the URI is
HTTP, the request <bcp14>MUST</bcp14> be an HTTP GET.</t> HTTP, the request <bcp14>MUST</bcp14> be an HTTP GET.</t>
<t>When receiving the request, the client instance <bcp14>MUST</bcp14>
<t>When receiving the request, the client instance <bcp14>MUST</bcp14> parse the parse the query
query
parameters to extract the hash and interaction reference values. parameters to extract the hash and interaction reference values.
The client instance <bcp14>MUST</bcp14> calculate and validate the hash value as described in The client instance <bcp14>MUST</bcp14> calculate and validate the hash value as described in
<xref target="interaction-hash"/>. If the hash validates, the client instance <xref target="interaction-hash"/>. If the hash validates, the client instance
sends a continuation request to the AS as described in sends a continuation request to the AS as described in
<xref target="continue-after-interaction"/> using the interaction <xref target="continue-after-interaction"/>, using the interaction
reference value received here. If the hash does not validate, the client instanc e reference value received here. If the hash does not validate, the client instanc e
<bcp14>MUST NOT</bcp14> send the interaction reference to the AS.</t> <bcp14>MUST NOT</bcp14> send the interaction reference to the AS.</t>
</section>
</section> <section anchor="interaction-pushback">
<section anchor="interaction-pushback"><name>Completing Interaction with a Direc <name>Completing Interaction with a Direct HTTP Request Callback</name
t HTTP Request Callback</name> >
<t>When using the <tt>push</tt> interaction finish method defined in S
<t>When using the <spanx style="verb">push</spanx> interaction finish method def ections <xref target="request-interact-callback-redirect" format="counter"/> and
ined in <xref target="request-interact-callback-redirect"/> and <xref target="re <xref target="response-interact-finish" format="counter"/>,
sponse-interact-finish"/>,
the AS signals to the client instance that interaction is the AS signals to the client instance that interaction is
complete and the request can be continued by sending an HTTP POST complete and the request can be continued by sending an HTTP POST
request to the client instance's callback URI.</t> request to the client instance's callback URI.</t>
<t>The HTTP message content is a JSON object consisting of the
<t>The HTTP message content is a JSON object consisting of the
following two fields:</t> following two fields:</t>
<dl>
<dl> <dt><tt>hash</tt> (string):</dt>
<dt><spanx style="verb">hash</spanx> (string):</dt> <dd>
<dd> <t>The interaction hash value as
<t>The interaction hash value as
described in <xref target="interaction-hash"/>. described in <xref target="interaction-hash"/>.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">interact_ref</spanx> (string)</dt> <dt><tt>interact_ref</tt> (string):</dt>
<dd> <dd>
<t>The interaction reference <t>The interaction reference
generated for this interaction. generated for this interaction.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
POST /push/554321 HTTP/1.1 POST /push/554321 HTTP/1.1
Host: client.example.net Host: client.example.net
Content-Type: application/json Content-Type: application/json
{ {
"hash": "pjdHcrti02HLCwGU3qhUZ3wZXt8IjrV_BtE3oUyOuKNk", "hash": "pjdHcrti02HLCwGU3qhUZ3wZXt8IjrV_BtE3oUyOuKNk",
"interact_ref": "4IFWWIKYBC2PQ6U56NL1" "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Since the AS is making an outbound connection to a URI supplied by
<t>Since the AS is making an outbound connection to a URI supplied by an outside an outside party (the client
party (the client instance), the AS <bcp14>MUST</bcp14> protect itself against Server-Side Request
instance), the AS <bcp14>MUST</bcp14> protect itself against SSRF attacks when m Forgery (SSRF) attacks when making this call, as discussed in
aking this call as discussed in
<xref target="security-ssrf"/>.</t> <xref target="security-ssrf"/>.</t>
<t>When receiving the request, the client instance <bcp14>MUST</bcp14>
<t>When receiving the request, the client instance <bcp14>MUST</bcp14> parse the parse the JSON object
JSON object
and validate the hash value as described in and validate the hash value as described in
<xref target="interaction-hash"/>. If either fails, the client instance <bcp14>M <xref target="interaction-hash"/>. If either fails, the client instance <bcp14>M
UST</bcp14> return an <spanx style="verb">unknown_interaction</spanx> error (<xr UST</bcp14> return an <tt>unknown_interaction</tt> error (<xref target="response
ef target="response-error"/>). If the hash validates, the client instance sends -error"/>). If the hash validates, the client instance sends
a continuation request to the AS as described in <xref target="continue-after-in a continuation request to the AS as described in <xref target="continue-after-in
teraction"/> using the interaction teraction"/>, using the interaction
reference value received here.</t> reference value received here.</t>
</section>
<section anchor="interaction-hash">
<name>Calculating the Interaction Hash</name>
</section> <t>The "hash" parameter in the request to the client instance's callba
<section anchor="interaction-hash"><name>Calculating the interaction hash</name> ck URI ties
the front-channel response to an ongoing request by using values
<t>The "hash" parameter in the request to the client instance's callback URI tie
s
the front channel response to an ongoing request by using values
known only to the parties involved. This security mechanism allows the client in stance to protect itself against known only to the parties involved. This security mechanism allows the client in stance to protect itself against
several kinds of session fixation and injection attacks as discussed in <xref ta rget="security-interact-hash"/> and related sections. The AS <bcp14>MUST</bcp14> several kinds of session fixation and injection attacks as discussed in <xref ta rget="security-interact-hash"/>. The AS <bcp14>MUST</bcp14>
always provide this hash, and the client instance <bcp14>MUST</bcp14> validate t he hash when received.</t> always provide this hash, and the client instance <bcp14>MUST</bcp14> validate t he hash when received.</t>
<t>To calculate the "hash" value, the party doing the calculation
<t>To calculate the "hash" value, the party doing the calculation
creates a hash base string by concatenating the following values in the followin g order creates a hash base string by concatenating the following values in the followin g order
using a single newline (0x0A) character to separate them:</t> using a single newline (0x0A) character to separate them:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>the "nonce" value sent by the client instance in the <xref target="request- <t>the "nonce" value sent by the client instance in the interactio
interact-finish">interaction "finish" section of the initial request</xref></t> n <tt>finish</tt> field of the initial request (<xref target="request-interact-f
<t>the AS's nonce value from <xref target="response-interact-finish">the inter inish"> </xref>)</t>
action finish response</xref></t> </li>
<t>the "interact_ref" returned from the AS as part of the <xref target="intera <li>
ction-finish">interaction finish method</xref></t> <t>the AS's nonce value from the interaction finish response (<xre
<t>the grant endpoint URI the client instance used to make its <xref target="r f target="response-interact-finish"> </xref>)</t>
equest">initial request</xref></t> </li>
</list></t> <li>
<t>the "interact_ref" returned from the AS as part of the interact
<t>There is no padding or whitespace before or after any of the lines, ion finish method (<xref target="interaction-finish"> </xref>)</t>
</li>
<li>
<t>the grant endpoint URI the client instance used to make its ini
tial request (<xref target="request"> </xref>)</t>
</li>
</ul>
<t>There is no padding or whitespace before or after any of the lines
and no trailing newline character. The following non-normative example shows a c onstructed and no trailing newline character. The following non-normative example shows a c onstructed
hash base string consisting of these four elements.</t> hash base string consisting of these four elements.</t>
<artwork><![CDATA[
<figure><artwork><![CDATA[
VJLO6A4CATR0KRO VJLO6A4CATR0KRO
MBDOFXG4Y5CVJCX821LH MBDOFXG4Y5CVJCX821LH
4IFWWIKYB2PQ6U56NL1 4IFWWIKYB2PQ6U56NL1
https://server.example.com/tx https://server.example.com/tx
]]></artwork></figure> ]]></artwork>
<t>The party then hashes the bytes of the ASCII encoding of this strin
<t>The party then hashes the bytes of the ASCII encoding of this string with the g with the appropriate algorithm
appropriate algorithm based on the "hash_method" parameter under the "finish" key of the interaction f
based on the "hash_method" parameter under the "finish" key of the <xref target= inish request (<xref target="request-interact-finish"> </xref>). The resulting
"request-interact-finish">interaction finish request</xref>. The resulting byte array from the hash function is then encoded using URL-Safe base64
byte array from the hash function is then encoded using URL-Safe Base64
with no padding <xref target="RFC4648"/>. The resulting string is the hash value .</t> with no padding <xref target="RFC4648"/>. The resulting string is the hash value .</t>
<t>If provided, the "hash_method" value <bcp14>MUST</bcp14> be one of
<t>If provided, the "hash_method" value <bcp14>MUST</bcp14> be one of the hash n the hash name strings defined in the
ame strings defined in the IANA "Named Information Hash Algorithm Registry" <xref target="HASH-ALG"></xref>
<xref target="HASH-ALG">IANA Named Information Hash Algorithm Registry</xref>. .
If the "hash_method" value is not present in the client instance's If the "hash_method" value is not present in the client instance's
request, the algorithm defaults to "sha-256".</t> request, the algorithm defaults to "sha-256".</t>
<t>For example, the "sha-256" hash method consists of hashing the input string <t>For example, the "sha-256" hash method consists of hashing the input string
with the 256-bit SHA2 algorithm. The following is the encoded "sha-256" hash of with the 256-bit SHA2 algorithm. The following is the encoded "sha-256" hash of
the above example the hash base string in the example above.
hash base string.</t> </t>
<artwork><![CDATA[
<figure><artwork><![CDATA[
x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY
]]></artwork></figure> ]]></artwork>
<t>As another example, the "sha3-512" hash method consists of hashing
<t>For another example, the "sha3-512" hash method consists of hashing the input the input string
string with the 512-bit SHA3 algorithm. The following is the encoded "sha3-512" hash of
with the 512-bit SHA3 algorithm. The following is the encoded "sha3-512" hash of the hash base string in the example above.
the above example </t>
hash base string.</t> <artwork><![CDATA[
<figure><artwork><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
pyUkVJSmpqSJMaDYsk5G8WCvgY91l-agUPe1wgn-cc5rUtN69gPI2-S_s-Eswed8iB4\ pyUkVJSmpqSJMaDYsk5G8WCvgY91l-agUPe1wgn-cc5rUtN69gPI2-S_s-Eswed8iB4\
PJ_a5Hg6DNi7qGgKwSQ PJ_a5Hg6DNi7qGgKwSQ
]]></artwork></figure> ]]></artwork>
</section>
</section> </section>
</section> </section>
</section> <section anchor="continue-request">
<section anchor="continue-request"><name>Continuing a Grant Request</name> <name>Continuing a Grant Request</name>
<t>While it is possible for the AS to return an approved grant response (<
<t>While it is possible for the AS to return an approved <xref target="response" xref target="response"> </xref>) with all the
>grant response</xref> with all the client instance's requested information (including access tokens (<xref target="
client instance's requested information (including <xref target="response-token" response-token"> </xref>) and
>access tokens</xref> and subject information (<xref target="response-subject"></xref>)) immediately, it's
<xref target="response-subject">subject information</xref>) immediately, it's mo more common that the AS will
re common that the AS will
place the grant request into the <em>pending</em> state and require communicatio n with place the grant request into the <em>pending</em> state and require communicatio n with
the client instance several times over the lifetime of a grant request. the client instance several times over the lifetime of a grant request.
This is often part of facilitating <xref target="authorization">interaction</xre f>, but it could This is often part of facilitating interaction (<xref target="authorization"> </ xref>), but it could
also be used to allow the AS and client instance to continue negotiating the par ameters of also be used to allow the AS and client instance to continue negotiating the par ameters of
the <xref target="request">original grant request</xref> through modification of the original grant request (<xref target="request"> </xref>) through modificatio
the request.</t> n of the request.</t>
<t>The ability to continue an already-started request allows the client in
<t>The ability to continue an already-started request allows the client instance stance to perform several
to perform several
important functions, including presenting additional information from interactio n, important functions, including presenting additional information from interactio n,
modifying the initial request, and revoking a grant request in progress.</t> modifying the initial request, and revoking a grant request in progress.</t>
<t>To enable this ongoing negotiation, the AS provides a continuation API
<t>To enable this ongoing negotiation, the AS provides a continuation API to the to the client software.
client software. The AS returns a <tt>continue</tt> field
The AS returns a <spanx style="verb">continue</spanx> field in the response (<xref target="response-continue"> </xref>) that contains inform
<xref target="response-continue">in the response</xref> that contains informatio ation the client instance needs to
n the client instance needs to
access this API, including a URI to access access this API, including a URI to access
as well as a special access token to use during the requests, called the <em>con as well as a special access token to use during the requests, called the "contin
tinuation access token</em>.</t> uation access token".</t>
<t>All requests to the continuation API are protected by a bound continuat
<t>All requests to the continuation API are protected by a bound continuation ac ion access token.
cess token.
The continuation access token is bound to the same key and method the client ins tance used to make The continuation access token is bound to the same key and method the client ins tance used to make
the initial request (or its most recent rotation). As a consequence, the initial request (or its most recent rotation). As a consequence,
when the client instance makes any calls to the continuation URI, the client ins tance <bcp14>MUST</bcp14> present when the client instance makes any calls to the continuation URI, the client ins tance <bcp14>MUST</bcp14> present
the continuation access token as described in <xref target="use-access-token"/> and present the continuation access token as described in <xref target="use-access-token"/> and present
proof of the client instance's key (or its most recent rotation) proof of the client instance's key (or its most recent rotation)
by signing the request as described in <xref target="binding-keys"/>. by signing the request as described in <xref target="binding-keys"/>.
The AS <bcp14>MUST</bcp14> validate the signature and ensure that it is bound to the appropriate key for The AS <bcp14>MUST</bcp14> validate the signature and ensure that it is bound to the appropriate key for
the continuation access token.</t> the continuation access token.</t>
<t>Access tokens other than the continuation access tokens <bcp14>MUST NOT
<t>Access tokens other than the continuation access tokens <bcp14>MUST NOT</bcp1 </bcp14> be usable for continuation
4> be usable for continuation
requests. Conversely, continuation access tokens <bcp14>MUST NOT</bcp14> be usab le to make authorized requests to requests. Conversely, continuation access tokens <bcp14>MUST NOT</bcp14> be usab le to make authorized requests to
RS's, even if co-located within the AS.</t> RSs, even if co-located within the AS.</t>
<t>In the following non-normative example, the client instance makes a POS
<t>In the following non-normative example, the client instance makes a POST requ T request to a unique URI and signs
est to a unique URI and signs the request with HTTP message signatures:</t>
the request with HTTP Message Signatures:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /continue/KSKUOMUKM HTTP/1.1 POST /continue/KSKUOMUKM HTTP/1.1
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Host: server.example.com Host: server.example.com
Content-Length: 0 Content-Length: 0
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS <bcp14>MUST</bcp14> be able to tell from the client instance's r
<t>The AS <bcp14>MUST</bcp14> be able to tell from the client instance's request equest which specific ongoing request
which specific ongoing request
is being accessed, using a combination of the continuation URI and is being accessed, using a combination of the continuation URI and
the continuation access token. the continuation access token.
If the AS cannot determine a single active grant request to map the If the AS cannot determine a single active grant request to map the
continuation request to, the AS <bcp14>MUST</bcp14> return an <spanx style="verb continuation request to, the AS <bcp14>MUST</bcp14> return an <tt>invalid_contin
">invalid_continuation</spanx> error (<xref target="response-error"/>).</t> uation</tt> error (<xref target="response-error"/>).</t>
<t>In the following non-normative example, the client instance makes a POS
<t>In the following non-normative example, the client instance makes a POST requ T request to a stable continuation endpoint
est to a stable continuation endpoint URI with the interaction reference (<xref target="continue-after-interaction"> <
URI with the <xref target="continue-after-interaction">interaction reference</xr /xref>),
ef>, includes the access token, and signs with HTTP message signatures:</t>
includes the access token, and signs with HTTP Message Signatures:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /continue HTTP/1.1 POST /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"interact_ref": "4IFWWIKYBC2PQ6U56NL1" "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>In the following non-normative alternative example, the client instance
<t>In following non-normative alternative example, the client instance had been had been provided a continuation URI unique to this ongoing grant request:</t>
provided a continuation URI unique to this ongoing grant request:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /tx/rxgIIEVMBV-BQUO7kxbsp HTTP/1.1 POST /tx/rxgIIEVMBV-BQUO7kxbsp HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP eyJhbGciOiJub25lIiwidHlwIjoiYmFkIn0 Authorization: GNAP eyJhbGciOiJub25lIiwidHlwIjoiYmFkIn0
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"interact_ref": "4IFWWIKYBC2PQ6U56NL1" "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>In both cases, the AS determines which grant is being asked for based o
<t>In both cases, the AS determines which grant is being asked for based on the n the URI and continuation access token provided.</t>
URI and continuation access token provided.</t> <t>If a <tt>wait</tt> parameter was included in the continuation response
(<xref target="response-continue"> </xref>), the
<t>If a <spanx style="verb">wait</spanx> parameter was included in the <xref tar
get="response-continue">continuation response</xref>, the
client instance <bcp14>MUST NOT</bcp14> call the continuation URI prior to waiti ng the number of client instance <bcp14>MUST NOT</bcp14> call the continuation URI prior to waiti ng the number of
seconds indicated. If no <spanx style="verb">wait</spanx> period is indicated, t he client instance seconds indicated. If no <tt>wait</tt> period is indicated, the client instance
<bcp14>MUST NOT</bcp14> poll immediately and <bcp14>SHOULD</bcp14> <bcp14>MUST NOT</bcp14> poll immediately and <bcp14>SHOULD</bcp14>
wait at least 5 seconds. If the client instance does not respect the wait at least 5 seconds. If the client instance does not respect the
given wait period, the AS <bcp14>MUST</bcp14> return the <spanx style="verb">too given wait period, the AS <bcp14>MUST</bcp14> return the <tt>too_fast</tt> error
_fast</spanx> error (<xref target="response-error"/>).</t> (<xref target="response-error"/>).</t>
<t>The response from the AS is a JSON object of a grant response and <bcp1
<t>The response from the AS is a JSON object of a grant response and <bcp14>MAY< 4>MAY</bcp14> contain any of the
/bcp14> contain any of the
fields described in <xref target="response"/>, as described in more detail in th e fields described in <xref target="response"/>, as described in more detail in th e
sections below.</t> subsections below.</t>
<t>If the AS determines that the client instance can
<t>If the AS determines that the client instance can
make further requests to the continuation API, the AS <bcp14>MUST</bcp14> includ e a new make further requests to the continuation API, the AS <bcp14>MUST</bcp14> includ e a new
<xref target="response-continue">"continue" response</xref>. continuation response (<xref target="response-continue"> </xref>).
The new <spanx style="verb">continue</spanx> response <bcp14>MUST</bcp14> includ The new continuation response <bcp14>MUST</bcp14> include a continuation access
e a continuation access token as well, and token as well, and
this token <bcp14>SHOULD</bcp14> be a new access token, invalidating the previou s access token. this token <bcp14>SHOULD</bcp14> be a new access token, invalidating the previou s access token.
If the AS does not return a new <spanx style="verb">continue</spanx> response, t he client instance If the AS does not return a new continuation response, the client instance
<bcp14>MUST NOT</bcp14> make an additional continuation request. If a client ins tance does so, <bcp14>MUST NOT</bcp14> make an additional continuation request. If a client ins tance does so,
the AS <bcp14>MUST</bcp14> return an <spanx style="verb">invalid_continuation</s the AS <bcp14>MUST</bcp14> return an <tt>invalid_continuation</tt> error (<xref
panx> error (<xref target="response-error"/>).</t> target="response-error"/>).</t>
<t>For continuation functions that require the client instance to send mes
<t>For continuation functions that require the client instance to send a message sage content, the content <bcp14>MUST</bcp14> be
content, the content <bcp14>MUST</bcp14> be
a JSON object.</t> a JSON object.</t>
<t>For all requests to the grant continuation API, the AS <bcp14>MAY</bcp1
<t>For all requests to the grant continuation API, the AS <bcp14>MAY</bcp14> mak 4> make use of long polling mechanisms such as those discussed in <xref target="
e use of long polling mechanisms such as discussed in <xref target="RFC6202"/>. RFC6202"/>. That is to say, instead of
That is to say, instead of
returning the current status immediately, the long polling technique returning the current status immediately, the long polling technique
allows the AS additional time to process and fulfill the request before returnin g the HTTP response allows the AS additional time to process and fulfill the request before returnin g the HTTP response
to the client instance. For example, when the AS receives a continuation request but the to the client instance. For example, when the AS receives a continuation request but the
grant request is in the <em>processing</em> state, the AS could wait until the g rant request has moved grant request is in the <em>processing</em> state, the AS could wait until the g rant request has moved
to the <em>pending</em> or <em>approved</em> state before returning the response message.</t> to the <em>pending</em> or <em>approved</em> state before returning the response message.</t>
<section anchor="continue-after-interaction">
<section anchor="continue-after-interaction"><name>Continuing After a Completed <name>Continuing after a Completed Interaction</name>
Interaction</name> <t>When the AS responds to the client instance's <tt>finish</tt> method
as in <xref target="interaction-callback"/>, this
<t>When the AS responds to the client instance's <spanx style="verb">finish</spa
nx> method as in <xref target="interaction-callback"/>, this
response includes an interaction reference. The client instance <bcp14>MUST</bcp 14> include that value as the field response includes an interaction reference. The client instance <bcp14>MUST</bcp 14> include that value as the field
<spanx style="verb">interact_ref</spanx> in a POST request to the continuation U <tt>interact_ref</tt> in a POST request to the continuation URI.</t>
RI.</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /continue HTTP/1.1 POST /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"interact_ref": "4IFWWIKYBC2PQ6U56NL1" "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Since the interaction reference is a one-time-use value as described
<t>Since the interaction reference is a one-time-use value as described in <xref in <xref target="interaction-callback"/>,
target="interaction-callback"/>,
if the client instance needs to make additional continuation calls after this re quest, the client instance if the client instance needs to make additional continuation calls after this re quest, the client instance
<bcp14>MUST NOT</bcp14> include the interaction reference in subsequent calls. I f the AS detects a client instance <bcp14>MUST NOT</bcp14> include the interaction reference in subsequent calls. I f the AS detects a client instance
submitting an interaction reference when the request is not in the <em>pending</ em> state, the AS <bcp14>MUST</bcp14> submitting an interaction reference when the request is not in the <em>pending</ em> state, the AS <bcp14>MUST</bcp14>
return a <spanx style="verb">too_many_attempts</spanx> error (<xref target="resp onse-error"/>) and <bcp14>SHOULD</bcp14> invalidate return a <tt>too_many_attempts</tt> error (<xref target="response-error"/>) and <bcp14>SHOULD</bcp14> invalidate
the ongoing request by moving it to the <em>finalized</em> state.</t> the ongoing request by moving it to the <em>finalized</em> state.</t>
<t>If the grant request is in the <em>approved</em> state, the grant res
ponse (<xref target="response"> </xref>) <bcp14>MAY</bcp14> contain any
newly created access tokens (<xref target="response-token"> </xref>) or
newly released subject information (<xref target="response-subject"> </xref>). T
he response <bcp14>MAY</bcp14> contain
a new continuation response (<xref target="response-continue"> </xref>) as descr
ibed above. The response
<bcp14>SHOULD NOT</bcp14> contain any interaction responses (<xref target="respo
nse-interact"> </xref>).</t>
<t>If the grant request is in the <em>approved</em> state, the <xref target="res <t>If the grant request is in the <em>pending</em> state, the grant response (<x
ponse">grant response</xref> <bcp14>MAY</bcp14> contain any ref target="response"> </xref>) <bcp14>MUST NOT</bcp14> contain access tokens or
newly-created <xref target="response-token">access tokens</xref> or subject information and <bcp14>MAY</bcp14> contain a new interaction response (
newly-released <xref target="response-subject">subject information</xref>. The r <xref target="response-interact"> </xref>) to any interaction methods that have
esponse <bcp14>MAY</bcp14> contain not been exhausted at the AS.</t>
a new <xref target="response-continue">"continue" response</xref> as described a <t>For example, if the request is successful in causing the AS to issue
bove. The response access tokens and
<bcp14>SHOULD NOT</bcp14> contain any <xref target="response-interact">interacti
on responses</xref>.</t>
<t>If the grant request is in the <em>pending</em> state, the <xref target="resp
onse">grant response</xref> <bcp14>MUST NOT</bcp14> contain access tokens or sub
ject information, and <bcp14>MAY</bcp14> contain a new <xref target="response-in
teract">interaction responses</xref> to any interaction methods that have not be
en exhausted at the AS.</t>
<t>For example, if the request is successful in causing the AS to issue access t
okens and
release opaque subject claims, the response could look like this:</t> release opaque subject claims, the response could look like this:</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": { "manage": {
"uri": "https://server.example.com/token/PRY5NM33O", "uri": "https://server.example.com/token/PRY5NM33O",
"access_token": { "access_token": {
"value": "B8CDFONP21-4TB8N6.BW7ONM" "value": "B8CDFONP21-4TB8N6.BW7ONM"
} }
} }
}, },
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
} ] } ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>With the above example, the client instance cannot make an additional
<t>With the above example, the client instance can not make an additional contin continuation request because
uation request because a <tt>continue</tt> field is not included.</t>
a <spanx style="verb">continue</spanx> field is not included.</t> <t>In the following non-normative example, the RO has denied the client
instance's request, and the AS responds with the following response:</t>
<t>In the following non-normative example, the RO has denied the client instance <artwork><![CDATA[
's request and the AS responds with the following response:</t>
<figure><artwork><![CDATA[
{ {
"error": "user_denied", "error": "user_denied",
"continue": { "continue": {
"access_token": { "access_token": {
"value": "33OMUKMKSKU80UPRY5NM" "value": "33OMUKMKSKU80UPRY5NM"
}, },
"uri": "https://server.example.com/continue", "uri": "https://server.example.com/continue",
"wait": 30 "wait": 30
} }
} }
]]></artwork></figure> ]]></artwork>
<t>In the preceding example, the AS includes the <tt>continue</tt> field
<t>In the preceding example, the AS includes the <spanx style="verb">continue</s in the response. Therefore, the client instance can continue the grant negotiat
panx> field in the response. Therefore, the client instance can continue the gra ion process, perhaps modifying the request as discussed in <xref target="continu
nt negotiation process, perhaps modifying the request as discussed in <xref targ e-modify"/>.</t>
et="continue-modify"/>.</t> </section>
<section anchor="continue-poll">
</section> <name>Continuing during Pending Interaction (Polling)</name>
<section anchor="continue-poll"><name>Continuing During Pending Interaction (Pol <t>When the client instance does not include a <tt>finish</tt> parameter
ling)</name> , the client instance will often need to
<t>When the client instance does not include a <spanx style="verb">finish</spanx
> parameter, the client instance will often need to
poll the AS until the RO has authorized the request. To do so, the client instan ce makes a POST poll the AS until the RO has authorized the request. To do so, the client instan ce makes a POST
request to the continuation URI as in <xref target="continue-after-interaction"/ >, but does not request to the continuation URI as in <xref target="continue-after-interaction"/ > but does not
include message content.</t> include message content.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /continue HTTP/1.1 POST /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
]]></sourcecode></figure> ]]></sourcecode>
<t>If the grant request is in the <em>approved</em> state, the grant res
<t>If the grant request is in the <em>approved</em> state, the <xref target="res ponse (<xref target="response"> </xref>) <bcp14>MAY</bcp14> contain any
ponse">grant response</xref> <bcp14>MAY</bcp14> contain any newly created access tokens (<xref target="response-token"> </xref>) or
newly-created <xref target="response-token">access tokens</xref> or newly released subject claims (<xref target="response-subject"> </xref>). The re
newly-released <xref target="response-subject">subject claims</xref>. The respon sponse <bcp14>MAY</bcp14> contain
se <bcp14>MAY</bcp14> contain a new continuation response (<xref target="response-continue"> </xref>) as descr
a new <xref target="response-continue">"continue" response</xref> as described a ibed above. If a <tt>continue</tt>
bove. If a <spanx style="verb">continue</spanx> field is included, it <bcp14>SHOULD</bcp14> include a <tt>wait</tt> field to fac
field is included, it <bcp14>SHOULD</bcp14> include a <spanx style="verb">wait</ ilitate a reasonable polling rate by
spanx> field to facilitate a reasonable polling rate by the client instance. The response <bcp14>SHOULD NOT</bcp14> contain interaction
the client instance. The response <bcp14>SHOULD NOT</bcp14> contain <xref target responses (<xref target="response-interact"> </xref>).</t>
="response-interact">interaction responses</xref>.</t> <t>If the grant request is in the <em>pending</em> state, the grant resp
onse (<xref target="response"> </xref>) <bcp14>MUST NOT</bcp14> contain access t
<t>If the grant request is in the <em>pending</em> state, the <xref target="resp okens or subject information and <bcp14>MAY</bcp14> contain a new interaction re
onse">grant response</xref> <bcp14>MUST NOT</bcp14> contain access tokens or sub sponse (<xref target="response-interact"> </xref>) to any interaction methods th
ject information, and <bcp14>MAY</bcp14> contain a new <xref target="response-in at have not been exhausted at the AS.</t>
teract">interaction responses</xref> to any interaction methods that have not be <t>For example, if the request has not yet been authorized by the RO, th
en exhausted at the AS.</t> e AS could respond
<t>For example, if the request has not yet been authorized by the RO, the AS cou
ld respond
by telling the client instance to make another continuation request in the futur e. In the following non-normative example, by telling the client instance to make another continuation request in the futur e. In the following non-normative example,
a new, unique access token has been issued for the call, which the client instan ce will use in its a new, unique access token has been issued for the call, which the client instan ce will use in its
next continuation request.</t> next continuation request.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"continue": { "continue": {
"access_token": { "access_token": {
"value": "33OMUKMKSKU80UPRY5NM" "value": "33OMUKMKSKU80UPRY5NM"
}, },
"uri": "https://server.example.com/continue", "uri": "https://server.example.com/continue",
"wait": 30 "wait": 30
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If the request is successful in causing the AS to issue access tokens
<t>If the request is successful in causing the AS to issue access tokens and and
release subject information, the response could look like the following non-norm ative example:</t> release subject information, the response could look like the following non-norm ative example:</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": { "manage": {
"uri": "https://server.example.com/token/PRY5NM33O", "uri": "https://server.example.com/token/PRY5NM33O",
"access_token": { "access_token": {
"value": "B8CDFONP21-4TB8N6.BW7ONM" "value": "B8CDFONP21-4TB8N6.BW7ONM"
} }
} }
}, },
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
} ] } ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>See <xref target="security-polling"/> for considerations on polling f
<t>See <xref target="security-polling"/> for considerations on polling for conti or continuation without an interaction
nuation without an interaction <tt>finish</tt> method.</t>
<spanx style="verb">finish</spanx> method.</t> <t>In error conditions, the AS responds to the client instance with an e
rror code as discussed in <xref target="response-error"/>.
<t>In error conditions, the AS responds to the client instance with the error co
de as discussed in <xref target="response-error"/>.
For example, if the client instance has polled too many times before the RO has approved the request, the AS would respond with a message like the following:</t > For example, if the client instance has polled too many times before the RO has approved the request, the AS would respond with a message like the following:</t >
<artwork><![CDATA[
<figure><artwork><![CDATA[
{ {
"error": "too_many_attempts" "error": "too_many_attempts"
} }
]]></artwork></figure> ]]></artwork>
<t>Since this response does not include a <spanx style="verb">continue</spanx> s ection, the client instance cannot continue to <t>Since this response does not include a <tt>continue</tt> field, the c lient instance cannot continue to
poll the AS for additional updates and the grant request is <em>finalized</em>. If the client instance poll the AS for additional updates and the grant request is <em>finalized</em>. If the client instance
still needs access to the resource, it will need to start with a new grant reque st.</t> still needs access to the resource, it will need to start with a new grant reque st.</t>
</section>
</section> <section anchor="continue-modify">
<section anchor="continue-modify"><name>Modifying an Existing Request</name> <name>Modifying an Existing Request</name>
<t>The client instance might need to modify an ongoing request, whether
<t>The client instance might need to modify an ongoing request, whether or not t or not tokens have already been
okens have already been
issued or subject information has already been released. In such cases, the clie nt instance makes an HTTP PATCH issued or subject information has already been released. In such cases, the clie nt instance makes an HTTP PATCH
request to the continuation URI and includes any fields it needs to modify. Fiel ds request to the continuation URI and includes any fields it needs to modify. Fiel ds
that aren't included in the request are considered unchanged from the original r equest.</t> that aren't included in the request are considered unchanged from the original r equest.</t>
<t>A grant request associated with a modification request <bcp14>MUST</b
<t>A grant request associated with a modification request <bcp14>MUST</bcp14> be cp14> be in the <em>approved</em> or <em>pending</em> state.
in the <em>approved</em> or <em>pending</em> state.
When the AS receives a valid modification request, the AS <bcp14>MUST</bcp14> pl ace the grant request into the When the AS receives a valid modification request, the AS <bcp14>MUST</bcp14> pl ace the grant request into the
<em>processing</em> state and re-evaluate the authorization in the new context c reated by the update <em>processing</em> state and re-evaluate the authorization in the new context c reated by the update
request, since the extent and context of the request could have changed.</t> request, since the extent and context of the request could have changed.</t>
<t>The client instance <bcp14>MAY</bcp14> include the <tt>access_token</
<t>The client instance <bcp14>MAY</bcp14> include the <spanx style="verb">access tt> and <tt>subject</tt> fields as described in Sections <xref target="request-t
_token</spanx> and <spanx style="verb">subject</spanx> fields as described in <x oken" format="counter"/>
ref target="request-token"/> and <xref target="request-subject" format="counter"/>. Inclusion of these fields
and <xref target="request-subject"/>. Inclusion of these fields override any val override any values in the initial request,
ues in the initial request,
which <bcp14>MAY</bcp14> trigger additional requirements and policies by the AS. For example, if the client instance is asking for which <bcp14>MAY</bcp14> trigger additional requirements and policies by the AS. For example, if the client instance is asking for
more access, the AS could require additional interaction with the RO to gather a dditional consent. more access, the AS could require additional interaction with the RO to gather a dditional consent.
If the client instance is asking for more limited access, the AS could determine that sufficient authorization If the client instance is asking for more limited access, the AS could determine that sufficient authorization
has been granted to the client instance and return the more limited access right s immediately. has been granted to the client instance and return the more limited access right s immediately.
If the grant request was previously in the <em>approved</em> state, the AS could decide to remember the larger scale of access rights associated If the grant request was previously in the <em>approved</em> state, the AS could decide to remember the larger scale of access rights associated
with the grant request, allowing the client instance to make subsequent requests of different with the grant request, allowing the client instance to make subsequent requests of different
subsets of granted access. The details of this processing are out of scope for t his specification, subsets of granted access. The details of this processing are out of scope for t his specification,
but a one possible approach is as follows:</t> but a one possible approach is as follows:</t>
<ol spacing="normal" type="1"><li>
<t><list style="numbers"> <t>A client instance requests access to <tt>Foo</tt>, and this is gr
<t>A client instance requests access to <spanx style="verb">Foo</spanx>, and i anted by the RO. This results in an access token: <tt>AT1</tt>.</t>
s granted by the RO. This results in an access token, <spanx style="verb">AT1</s </li>
panx>.</t> <li>
<t>The client instance later modifies the grant request to include <spanx styl <t>The client instance later modifies the grant request to include <
e="verb">Foo</spanx> and <spanx style="verb">Bar</spanx> together. Since the cli tt>Foo</tt> and <tt>Bar</tt> together. Since the client instance was previously
ent instance was previously granted <spanx style="verb">Foo</spanx> under this g granted <tt>Foo</tt> under this grant request, the RO is prompted to allow the c
rant request, the RO is prompted to allow the client instance access to <spanx s lient instance access to <tt>Foo</tt> and <tt>Bar</tt> together. This results in
tyle="verb">Foo</spanx> and <spanx style="verb">Bar</spanx> together. This resul a new access token: <tt>AT2</tt>. This access token has access to both <tt>Foo<
ts in a new access token, <spanx style="verb">AT2</spanx> This access token has /tt> and <tt>Bar</tt>. The rights of the original access token <tt>AT1</tt> are
access to both <spanx style="verb">Foo</spanx> and <spanx style="verb">Bar</span not modified.</t>
x>. The rights of the original access token <spanx style="verb">AT1</spanx> are </li>
not modified.</t> <li>
<t>The client instance makes another grant modification to ask only for <spanx <t>The client instance makes another grant modification to ask only
style="verb">Bar</spanx>. Since the client instance was previously granted <spa for <tt>Bar</tt>. Since the client instance was previously granted <tt>Foo</tt>
nx style="verb">Foo</spanx> and <spanx style="verb">Bar</spanx> together under t and <tt>Bar</tt> together under this grant request, the RO is not prompted, and
his grant request, the RO is not prompted and the access to <spanx style="verb"> the access to <tt>Bar</tt> is granted in a new access token: <tt>AT3</tt>. This
Bar</spanx> is granted in a new access token, <spanx style="verb">AT3</spanx>. T new access token does not allow access to <tt>Foo</tt>.</t>
his new access token does not allow access to <spanx style="verb">Foo</spanx>.</ </li>
t> <li>
<t>The original access token <spanx style="verb">AT1</spanx> expires and the c <t>The original access token <tt>AT1</tt> expires, and the client se
lient seeks a new access token to replace it. The client instance makes another eks a new access token to replace it. The client instance makes another grant mo
grant modification to ask only for <spanx style="verb">Foo</spanx>. Since the cl dification to ask only for <tt>Foo</tt>. Since the client instance was previousl
ient instance was previously granted <spanx style="verb">Foo</spanx> and <spanx y granted <tt>Foo</tt> and <tt>Bar</tt> together under this grant request, the R
style="verb">Bar</spanx> together under this grant request, the RO is not prompt O is not prompted, and the access to <tt>Foo</tt> is granted in a new access tok
ed and the access to <spanx style="verb">Foo</spanx> is granted in a new access en: <tt>AT4</tt>. This new access token does not allow access to <tt>Bar</tt>.</
token, <spanx style="verb">AT4</spanx>. This new access token does not allow acc t>
ess to <spanx style="verb">Bar</spanx>.</t> </li>
</list></t> </ol>
<t>All four access tokens are independent of each other and associated w
<t>All four access tokens are independent of each other and associated with the ith the same underlying grant request. Each of these access tokens could possibl
same underlying grant request. Each of these access tokens could possibly also b y also be rotated using token management, if available. For example, instead of
e rotated using token management, if available. For example, instead of asking f asking for a new token to replace <tt>AT1</tt>, the client instance could ask fo
or a new token to replace <spanx style="verb">AT1</spanx>, the client instance c r a refresh of <tt>AT1</tt> using the rotation method of the token management AP
ould ask for a refresh of <spanx style="verb">AT1</spanx> using the rotation met I. This would result in a refreshed <tt>AT1</tt> with a different token value an
hod of the token management API. This would result in a refreshed <spanx style=" d expiration from the original <tt>AT1</tt> but with the same access rights of a
verb">AT1</spanx> with a different token value and expiration from the original llowing only access to <tt>Foo</tt>.</t>
<spanx style="verb">AT1</spanx> but with the same access rights of allowing only <t>The client instance <bcp14>MAY</bcp14> include the <tt>interact</tt>
access to <spanx style="verb">Foo</spanx>.</t> field as described in <xref target="request-interact"/>.
<t>The client instance <bcp14>MAY</bcp14> include the <spanx style="verb">intera
ct</spanx> field as described in <xref target="request-interact"/>.
Inclusion of this field indicates that the client instance is capable of driving interaction with Inclusion of this field indicates that the client instance is capable of driving interaction with
the end user, and this field replaces any values from a previous request. The AS <bcp14>MAY</bcp14> respond to any the end user, and this field replaces any values from a previous request. The AS <bcp14>MAY</bcp14> respond to any
of the interaction responses as described in <xref target="response-interact"/>, just like it would to a new of the interaction responses as described in <xref target="response-interact"/>, just like it would to a new
request.</t> request.</t>
<t>The client instance <bcp14>MAY</bcp14> include the <tt>user</tt> fiel
<t>The client instance <bcp14>MAY</bcp14> include the <spanx style="verb">user</ d as described in <xref target="request-user"/> to present new assertions
spanx> field as described in <xref target="request-user"/> to present new assert
ions
or information about the end user. The AS <bcp14>SHOULD</bcp14> check that this presented user information is or information about the end user. The AS <bcp14>SHOULD</bcp14> check that this presented user information is
consistent with any user information previously presented by the client instance or otherwise consistent with any user information previously presented by the client instance or otherwise
associated with this grant request.</t> associated with this grant request.</t>
<t>The client instance <bcp14>MUST NOT</bcp14> include the <tt>client</t
<t>The client instance <bcp14>MUST NOT</bcp14> include the <spanx style="verb">c t> field of the request, since the client
lient</spanx> section of the request, since the client
instance is assumed not to have changed. Modification of client instance informa tion, including instance is assumed not to have changed. Modification of client instance informa tion, including
rotation of keys associated with the client instance, is outside the rotation of keys associated with the client instance, is outside the
scope of this specification.</t> scope of this specification.</t>
<t>The client instance <bcp14>MUST NOT</bcp14> include post-interaction response <t>The client instance <bcp14>MUST NOT</bcp14> include post-interaction response
s such as described in <xref target="continue-after-interaction"/>.</t> s such as those described in <xref target="continue-after-interaction"/>.</t>
<t>Modification requests <bcp14>MUST NOT</bcp14> alter previously issued
<t>Modification requests <bcp14>MUST NOT</bcp14> alter previously-issued access access tokens. Instead, any access
tokens. Instead, any access
tokens issued from a continuation are considered new, separate access tokens. Th e AS tokens issued from a continuation are considered new, separate access tokens. Th e AS
<bcp14>MAY</bcp14> revoke previously-issued access tokens after a modification h <bcp14>MAY</bcp14> revoke previously issued access tokens after a modification h
as occurred.</t> as occurred.</t>
<t>If the modified request can be granted immediately by the AS (the gra
<t>If the modified request can be granted immediately by the AS (the grant reque nt request is in the <em>approved</em> state),
st is in the <em>approved</em> state), the grant response (<xref target="response"> </xref>) <bcp14>MAY</bcp14> contain
the <xref target="response">grant response</xref> <bcp14>MAY</bcp14> contain any any newly created access tokens (<xref target="response-token"> </xref>) or
newly-created <xref target="response-token">access tokens</xref> or newly released subject claims (<xref target="response-subject"> </xref>). The re
newly-released <xref target="response-subject">subject claims</xref>. The respon sponse <bcp14>MAY</bcp14> contain
se <bcp14>MAY</bcp14> contain a new continuation response (<xref target="response-continue"> </xref>) as descr
a new <xref target="response-continue">"continue" response</xref> as described a ibed above. If interaction
bove. If interaction can occur, the response <bcp14>SHOULD</bcp14> contain interaction responses (<xr
can occur, the response <bcp14>SHOULD</bcp14> contain <xref target="response-int ef target="response-interact"> </xref>) as well.</t>
eract">interaction responses</xref> as well.</t> <t>For example, a client instance initially requests a set of resources
using references:</t>
<t>For example, a client instance initially requests a set of resources using re <sourcecode type="http-message"><![CDATA[
ferences:</t>
<figure><sourcecode type="http-message"><![CDATA[
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
skipping to change at line 4837 skipping to change at line 4796
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
}, },
"client": "987YHGRT56789IOLK" "client": "987YHGRT56789IOLK"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Access is granted by the RO, and a token is issued by the AS.
<t>Access is granted by the RO, and a token is issued by the AS. In its final response, the AS includes a <tt>continue</tt> field, which includes
In its final response, the AS includes a <spanx style="verb">continue</spanx> fi
eld, which includes
a separate access token for accessing the continuation API:</t> a separate access token for accessing the continuation API:</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"continue": { "continue": {
"access_token": { "access_token": {
"value": "80UPRY5NM33OMUKMKSKU" "value": "80UPRY5NM33OMUKMKSKU"
}, },
"uri": "https://server.example.com/continue", "uri": "https://server.example.com/continue",
"wait": 30 "wait": 30
}, },
"access_token": { "access_token": {
"value": "RP1LT0-OS9M2P_R64TB", "value": "RP1LT0-OS9M2P_R64TB",
"access": [ "access": [
"read", "write" "read", "write"
] ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>This <tt>continue</tt> field allows the client instance to make an ev
<t>This <spanx style="verb">continue</spanx> field allows the client instance to entual continuation call.
make an eventual continuation call.
Some time later, the client instance realizes that it no longer needs Some time later, the client instance realizes that it no longer needs
"write" access and therefore modifies its ongoing request, here asking for just "read" access "write" access and therefore modifies its ongoing request, here asking for just "read" access
instead of both "read" and "write" as before.</t> instead of both "read" and "write" as before.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
PATCH /continue HTTP/1.1 PATCH /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
"read" "read"
] ]
} }
... ...
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS replaces the previous <tt>access</tt> from the first request,
<t>The AS replaces the previous <spanx style="verb">access</spanx> from the firs allowing the AS to
t request, allowing the AS to determine if any previously granted consent already applies. In this case, the A
determine if any previously-granted consent already applies. In this case, the A S would
S would
determine that reducing the breadth of the requested access means that new acces s determine that reducing the breadth of the requested access means that new acces s
tokens can be issued to the client instance without additional interaction or co nsent. The AS would likely revoke previously-issued access tokens tokens can be issued to the client instance without additional interaction or co nsent. The AS would likely revoke previously issued access tokens
that had the greater access rights associated with them, unless they had been is sued that had the greater access rights associated with them, unless they had been is sued
with the <spanx style="verb">durable</spanx> flag.</t> with the <tt>durable</tt> flag.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"continue": { "continue": {
"access_token": { "access_token": {
"value": "M33OMUK80UPRY5NMKSKU" "value": "M33OMUK80UPRY5NMKSKU"
}, },
"uri": "https://server.example.com/continue", "uri": "https://server.example.com/continue",
"wait": 30 "wait": 30
}, },
"access_token": { "access_token": {
"value": "0EVKC7-2ZKwZM_6N760", "value": "0EVKC7-2ZKwZM_6N760",
"access": [ "access": [
"read" "read"
] ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>As another example, the client instance initially requests read-only
<t>For another example, the client instance initially requests read-only access access but later
but later needs to step up its access. The initial request could look like the following H
needs to step up its access. The initial request could look like the following H TTP message:</t>
TTP message.</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
skipping to change at line 4937 skipping to change at line 4888
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
}, },
"client": "987YHGRT56789IOLK" "client": "987YHGRT56789IOLK"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Access is granted by the RO, and a token is issued by the AS.
<t>Access is granted by the RO, and a token is issued by the AS. In its final response, the AS includes a <tt>continue</tt> field:</t>
In its final response, the AS includes a <spanx style="verb">continue</spanx> fi <sourcecode type="http-message"><![CDATA[
eld:</t>
<figure><sourcecode type="http-message"><![CDATA[
{ {
"continue": { "continue": {
"access_token": { "access_token": {
"value": "80UPRY5NM33OMUKMKSKU" "value": "80UPRY5NM33OMUKMKSKU"
}, },
"uri": "https://server.example.com/continue", "uri": "https://server.example.com/continue",
"wait": 30 "wait": 30
}, },
"access_token": { "access_token": {
"value": "RP1LT0-OS9M2P_R64TB", "value": "RP1LT0-OS9M2P_R64TB",
"access": [ "access": [
"read" "read"
] ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>This allows the client instance to make an eventual continuation call
<t>This allows the client instance to make an eventual continuation call. The cl . The client instance later realizes that it now
ient instance later realizes that it now
needs "write" access in addition to the "read" access. Since this is an expansio n of what needs "write" access in addition to the "read" access. Since this is an expansio n of what
it asked for previously, the client instance also includes a new interaction sec tion in case the AS needs it asked for previously, the client instance also includes a new interaction fie ld in case the AS needs
to interact with the RO again to gather additional authorization. Note that the client instance's to interact with the RO again to gather additional authorization. Note that the client instance's
nonce and callback are different from the initial request. Since the original ca llback was nonce and callback are different from the initial request. Since the original ca llback was
already used in the initial exchange, and the callback is intended for one-time- use, a new one already used in the initial exchange and the callback is intended for one-time u se, a new one
needs to be included in order to use the callback again.</t> needs to be included in order to use the callback again.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
PATCH /continue HTTP/1.1 PATCH /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
skipping to change at line 4992 skipping to change at line 4939
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.example.net/return/654321", "uri": "https://client.example.net/return/654321",
"nonce": "K82FX4T4LKLTI25DQFZC" "nonce": "K82FX4T4LKLTI25DQFZC"
} }
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>From here, the AS can determine that the client instance is asking fo
<t>From here, the AS can determine that the client instance is asking for more t r more than it was previously granted,
han it was previously granted,
but since the client instance has also provided a mechanism to interact with the RO, the AS can use that but since the client instance has also provided a mechanism to interact with the RO, the AS can use that
to gather the additional consent. The protocol continues as it would with a new request. to gather the additional consent. The protocol continues as it would with a new request.
Since the old access tokens are good for a subset of the rights requested here, the Since the old access tokens are good for a subset of the rights requested here, the
AS might decide to not revoke them. However, any access tokens granted after thi s update AS might decide to not revoke them. However, any access tokens granted after thi s update
process are new access tokens and do not modify the rights of existing access to kens.</t> process are new access tokens and do not modify the rights of existing access to kens.</t>
</section>
</section> <section anchor="continue-delete">
<section anchor="continue-delete"><name>Revoking a Grant Request</name> <name>Revoking a Grant Request</name>
<t>If the client instance wishes to cancel an ongoing grant request and
<t>If the client instance wishes to cancel an ongoing grant request and place it place it into the <em>finalized</em>
into the <em>finalized</em>
state, the client instance makes an state, the client instance makes an
HTTP DELETE request to the continuation URI.</t> HTTP DELETE request to the continuation URI.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
DELETE /continue HTTP/1.1 DELETE /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
]]></sourcecode></figure> ]]></sourcecode>
<t>If the request is successfully revoked, the AS responds with HTTP sta
<t>If the request is successfully revoked, the AS responds with status code HTTP tus code 204 (No Content).
204 (No Content).
The AS <bcp14>SHOULD</bcp14> revoke all associated access tokens, if possible. T he AS <bcp14>SHOULD</bcp14> disable all The AS <bcp14>SHOULD</bcp14> revoke all associated access tokens, if possible. T he AS <bcp14>SHOULD</bcp14> disable all
token rotation and other token management functions on such access tokens, if po ssible. token rotation and other token management functions on such access tokens, if po ssible.
Once the grant request is in the <em>finalized</em> state, it <bcp14>MUST NOT</b cp14> be moved to any other state.</t> Once the grant request is in the <em>finalized</em> state, it <bcp14>MUST NOT</b cp14> be moved to any other state.</t>
<t>If the request is not revoked, the AS responds with an <tt>invalid_co
<t>If the request is not revoked, the AS responds with an <spanx style="verb">in ntinuation</tt> error (<xref target="response-error"/>).</t>
valid_continuation</spanx> error (<xref target="response-error"/>).</t> </section>
</section>
</section> <section anchor="token-management">
</section> <name>Token Management</name>
<section anchor="token-management"><name>Token Management</name> <t>If an access token response includes the <tt>manage</tt> field as
<t>If an access token response includes the <spanx style="verb">manage</spanx> f
ield as
described in <xref target="response-token-single"/>, the client instance <bcp14> MAY</bcp14> call described in <xref target="response-token-single"/>, the client instance <bcp14> MAY</bcp14> call
this URI to manage the access token with the rotate and revoke actions defined i n this URI to manage the access token with the rotate and revoke actions defined i n
the following sections. Other actions are undefined by this the following subsections. Other actions are undefined by this
specification.</t> specification.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"flags": ["bearer"], "flags": ["bearer"],
"manage": { "manage": {
"uri": "https://server.example.com/token/PRY5NM33O", "uri": "https://server.example.com/token/PRY5NM33O",
"access_token": { "access_token": {
"value": "B8CDFONP21-4TB8N6.BW7ONM" "value": "B8CDFONP21-4TB8N6.BW7ONM"
} }
} }
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The token management access token issued under the <tt>manage</tt> fiel
<t>The token management access token issued under the <spanx style="verb">manage d is used to protect
</spanx> field is used to protect
all calls to the token management API. all calls to the token management API.
The client instance <bcp14>MUST</bcp14> present proof of the key associated with the token The client instance <bcp14>MUST</bcp14> present proof of the key associated with the token
along with the token management access token value.</t> along with the value of the token management access token.</t>
<t>The AS <bcp14>MUST</bcp14> validate the proof and ensure that it is ass
<t>The AS <bcp14>MUST</bcp14> validate the proof and ensure that it is associate ociated with the
d with the
token management access token.</t> token management access token.</t>
<t>The AS <bcp14>MUST</bcp14> uniquely identify the token being managed fr
<t>The AS <bcp14>MUST</bcp14> uniquely identify the token being managed from the om the token management URI,
token management URI,
the token management access token, or a combination of both.</t> the token management access token, or a combination of both.</t>
<section anchor="rotate-access-token">
<section anchor="rotate-access-token"><name>Rotating the Access Token Value</nam <name>Rotating the Access Token Value</name>
e> <t>If the client instance has an access token and that access token expi
res, the
<t>If the client instance has an access token and that access token expires, the
client instance might want to rotate the access token to a new value without exp iration. client instance might want to rotate the access token to a new value without exp iration.
Rotating an access token consists of issuing a new access token in place of an Rotating an access token consists of issuing a new access token in place of an
existing access token, with the same rights and properties as the original token , existing access token, with the same rights and properties as the original token ,
apart from an updated token value and expiration time.</t> apart from an updated token value and expiration time.</t>
<t>To rotate an access token, the client instance makes an HTTP POST to
<t>To rotate an access token, the client instance makes an HTTP POST to the toke the token management URI
n management URI
with no message content, with no message content,
sending the access token in the authorization header as described in <xref targe t="use-access-token"/> and signing the request sending the access token in the authorization header as described in <xref targe t="use-access-token"/> and signing the request
with the appropriate key.</t> with the appropriate key.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /token/PRY5NM33O HTTP/1.1 POST /token/PRY5NM33O HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP B8CDFONP21-4TB8N6.BW7ONM Authorization: GNAP B8CDFONP21-4TB8N6.BW7ONM
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
]]></sourcecode></figure> ]]></sourcecode>
<t>The client instance cannot request to alter the access rights
<t>The client instance can not request to alter the access rights
associated with the access token during a rotation request. To get an access tok en with different associated with the access token during a rotation request. To get an access tok en with different
access rights for this grant request, the client instance has to call the <xref access rights for this grant request, the client instance has to call the contin
target="continue-modify">continuation API's update</xref> uation API's update functionality (<xref target="continue-modify"> </xref>)
functionality to get a new access token. The client instance can also create a n to get a new access token. The client instance can also create a new grant reque
ew grant request st
with the required access rights.</t> with the required access rights.</t>
<t>The AS validates that the token management access token presented is
<t>The AS validates that the token management access token presented is associat associated with the management
ed with the management
URI, that the AS issued the token to the given client instance, and that URI, that the AS issued the token to the given client instance, and that
the presented key is the correct key for the token management access token. The AS determines the presented key is the correct key for the token management access token. The AS determines
which access token is being rotated from the token management URI, the token man agement access token, or both.</t> which access token is being rotated from the token management URI, the token man agement access token, or both.</t>
<t>If the token is validated and the key is appropriate for the
<t>If the token is validated and the key is appropriate for the
request, the AS <bcp14>MUST</bcp14> invalidate the current access token value as sociated request, the AS <bcp14>MUST</bcp14> invalidate the current access token value as sociated
with this URI, if possible. Note that stateless access tokens can make proactive with this URI, if possible. Note that stateless access tokens can make proactive
revocation difficult within a system, see <xref target="security-stateless-token revocation difficult within a system; see <xref target="security-stateless-token
s"/>.</t> s"/>.</t>
<t>For successful rotations, the AS responds with an HTTP status code 20
<t>For successful rotations, the AS responds with an HTTP 200 with a JSON-format 0 (OK) with JSON-formatted message content consisting of the rotated access toke
ted message content consisting of the rotated access token n
in the <spanx style="verb">access_token</spanx> field described in <xref target= in the <tt>access_token</tt> field described in <xref target="response-token-sin
"response-token-single"/>. The value of the gle"/>. The value of the
access token <bcp14>MUST NOT</bcp14> be the same as the current value of the acc ess access token <bcp14>MUST NOT</bcp14> be the same as the current value of the acc ess
token used to access the management API. The response <bcp14>MUST</bcp14> includ e an token used to access the management API. The response <bcp14>MUST</bcp14> includ e an
access token management URI, and the value of this URI <bcp14>MAY</bcp14> be dif ferent access token management URI, and the value of this URI <bcp14>MAY</bcp14> be dif ferent
from the URI used by the client instance to make the rotation call. The client i nstance from the URI used by the client instance to make the rotation call. The client i nstance
<bcp14>MUST</bcp14> use this new URI to manage the rotated access token.</t> <bcp14>MUST</bcp14> use this new URI to manage the rotated access token.</t>
<t>The access rights in the <tt>access</tt> array for the rotated access
<t>The access rights in the <spanx style="verb">access</spanx> array for the rot token <bcp14>MUST</bcp14>
ated access token <bcp14>MUST</bcp14>
be included in the response and <bcp14>MUST</bcp14> be the same be included in the response and <bcp14>MUST</bcp14> be the same
as the token before rotation.</t> as the token before rotation.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"access_token": { "access_token": {
"value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2", "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2",
"manage": { "manage": {
"uri": "https://server.example.com/token/PRY5NM33O", "uri": "https://server.example.com/token/PRY5NM33O",
"access_token": { "access_token": {
"value": "B8CDFONP21-4TB8N6.BW7ONM" "value": "B8CDFONP21-4TB8N6.BW7ONM"
} }
skipping to change at line 5144 skipping to change at line 5072
], ],
"datatypes": [ "datatypes": [
"metadata", "metadata",
"images" "images"
] ]
}, },
"read", "dolphin-metadata" "read", "dolphin-metadata"
] ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>If the AS is unable or unwilling to rotate the value of the access to
<t>If the AS is unable or unwilling to rotate the value of the access token, the ken, the AS responds with an <tt>invalid_rotation</tt> error (<xref target="resp
AS responds with an <spanx style="verb">invalid_rotation</spanx> error (<xref t onse-error"/>). Upon receiving such an error, the client instance <bcp14>MUST</b
arget="response-error"/>). Upon receiving such an error, the client instance <bc cp14> consider the access token to not have changed its state.</t>
p14>MUST</bcp14> consider the access token to not have changed its state.</t> <section anchor="rotate-access-token-key">
<name>Binding a New Key to the Rotated Access Token</name>
<section anchor="rotate-access-token-key"><name>Binding a New Key to the Rotated <t>If the client instance wishes to bind a new presentation key to an
Access Token</name> access token, the client
<t>If the client instance wishes to bind a new presentation key to an access tok
en, the client
instance <bcp14>MUST</bcp14> present both the new key and the proof of previous key material in the access token rotation request. instance <bcp14>MUST</bcp14> present both the new key and the proof of previous key material in the access token rotation request.
The client instance makes an HTTP POST as a JSON object with the following field :</t> The client instance makes an HTTP POST as a JSON object with the following field :</t>
<dl>
<dl> <dt><tt>key</tt>:</dt>
<dt><spanx style="verb">key</spanx>:</dt> <dd>
<dd> <t>The new key value or reference in the format described in <xref
<t>The new key value or reference in the format described in <xref target="k target="key-format"/>. Note that keys
ey-format"/>. Note that keys
passed by value are always public keys. <bcp14>REQUIRED</bcp14> when doing key rotation.</t> passed by value are always public keys. <bcp14>REQUIRED</bcp14> when doing key rotation.</t>
</dd> </dd>
</dl> </dl>
<t>The proofing method and parameters for the new key <bcp14>MUST</bcp
<t>The <spanx style="verb">proof</spanx> method and parameters for the new key < 14> be the same as those established for the
bcp14>MUST</bcp14> be the same as those established for the
previous key.</t> previous key.</t>
<t>The client instance <bcp14>MUST</bcp14> prove possession of both th
<t>The client instance <bcp14>MUST</bcp14> prove possession of both the currentl e currently bound key and the newly requested
y-bound key and the newly-requested
key simultaneously in the rotation request. Specifically, the signature from the previous key <bcp14>MUST</bcp14> key simultaneously in the rotation request. Specifically, the signature from the previous key <bcp14>MUST</bcp14>
cover the value or reference of the new key, and the signature of the new key <b cp14>MUST</bcp14> cover the cover the value or reference of the new key, and the signature of the new key <b cp14>MUST</bcp14> cover the
signature value of the old key. The signature value of the old key. The
means of doing so varies depending on the proofing method in use. For example, t means of doing so vary depending on the proofing method in use. For example, the
he HTTP Message HTTP message
Signatures proofing method uses multiple signatures in the request as described signatures proofing method uses multiple signatures in the request as described
in in
<xref target="httpsig-rotate"/>, as shown in this example.</t> <xref target="httpsig-rotate"/>. This is shown in the following example.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /token/PRY5NM33O HTTP/1.1 POST /token/PRY5NM33O HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP B8CDFONP21-4TB8N6.BW7ONM Authorization: GNAP B8CDFONP21-4TB8N6.BW7ONM
Signature-Input: \ Signature-Input: \
sig1=("@method" "@target-uri" "content-digest" \ sig1=("@method" "@target-uri" "content-digest" \
"authorization"),\ "authorization"),\
sig2=("@method" "@target-uri" "content-digest" \ sig2=("@method" "@target-uri" "content-digest" \
"authorization" "signature";key="sig1" \ "authorization" "signature";key="sig1" \
"signature-input";key="sig1") "signature-input";key="sig1")
Signature: sig1=..., sig2=... Signature: sig1=..., sig2=...
skipping to change at line 5198 skipping to change at line 5120
"proof": "httpsig", "proof": "httpsig",
"jwk": { "jwk": {
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"kid": "xyz-2", "kid": "xyz-2",
"alg": "RS256", "alg": "RS256",
"n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..."
} }
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Failure to present the appropriate proof of either the new key or t
<t>Failure to present the appropriate proof of either the new key or the previou he previous key for the access token, as defined by the proofing method, <bcp14>
s key for the access token, as defined by the proof method, <bcp14>MUST</bcp14> MUST</bcp14> result in an <tt>invalid_rotation</tt> error code from the AS (<xre
result in an <spanx style="verb">invalid_rotation</spanx> error code from the AS f target="response-error"/>).</t>
(<xref target="response-error"/>).</t> <t>An attempt to change the proofing method or parameters, including a
n attempt to rotate the key of a bearer token (which has no key), <bcp14>MUST</b
<t>An attempt to change the <spanx style="verb">proof</spanx> method or paramete cp14> result in an <tt>invalid_rotation</tt> error code returned from the AS (<x
rs, including an attempt to rotate the key of a bearer token (which has no key), ref target="response-error"/>).</t>
<bcp14>MUST</bcp14> result in an <spanx style="verb">invalid_rotation</spanx> e <t>If the AS does not allow rotation of the access token's key for any
rror code returned from the AS (<xref target="response-error"/>).</t> reason, including but not limited to lack of permission for this client instanc
e or lack of capability by the AS, the AS <bcp14>MUST</bcp14> return a <tt>key_r
<t>If the AS does not allow rotation of the access token's key for any reason, i otation_not_supported</tt> error code (<xref target="response-error"/>).</t>
ncluding but not limited to lack of permission for this client instance or lack </section>
of capability by the AS, the AS <bcp14>MUST</bcp14> return a <spanx style="verb" </section>
>key_rotation_not_supported</spanx> error code (<xref target="response-error"/>) <section anchor="revoke-access-token">
.</t> <name>Revoking the Access Token</name>
<t>If the client instance wishes to revoke the access token proactively,
</section> such as when
</section>
<section anchor="revoke-access-token"><name>Revoking the Access Token</name>
<t>If the client instance wishes to revoke the access token proactively, such as
when
a user indicates to the client instance that they no longer wish for it to have a user indicates to the client instance that they no longer wish for it to have
access or the client instance application detects that it is being uninstalled, access or the client instance application detects that it is being uninstalled,
the client instance can use the token management URI to indicate to the AS that the client instance can use the token management URI to indicate to the AS that
the AS <bcp14>SHOULD</bcp14> invalidate the access token for all purposes.</t> the AS <bcp14>SHOULD</bcp14> invalidate the access token for all purposes.</t>
<t>The client instance makes an HTTP DELETE request to the token managem
<t>The client instance makes an HTTP DELETE request to the token management ent
URI, presenting the access token and signing the request with URI, presenting the access token and signing the request with
the appropriate key.</t> the appropriate key.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
DELETE /token/PRY5NM33O HTTP/1.1 DELETE /token/PRY5NM33O HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP B8CDFONP21-4TB8N6.BW7ONM Authorization: GNAP B8CDFONP21-4TB8N6.BW7ONM
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
]]></sourcecode></figure> ]]></sourcecode>
<t>If the key presented is associated with the token (or the client inst
<t>If the key presented is associated with the token (or the client instance, in ance, in
the case of a bearer token), the AS <bcp14>MUST</bcp14> invalidate the access to ken, if the case of a bearer token), the AS <bcp14>MUST</bcp14> invalidate the access to ken, if
possible, and return an HTTP 204 response code.</t> possible, and return an HTTP response code 204.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
204 No Content 204 No Content
]]></sourcecode></figure> ]]></sourcecode>
<t>Though the AS <bcp14>MAY</bcp14> revoke an access token at any time f
<t>Though the AS <bcp14>MAY</bcp14> revoke an access token at any time for or
any reason, the token management function is specifically for the client instanc e's use. any reason, the token management function is specifically for the client instanc e's use.
If the access token has already expired or has been revoked through other If the access token has already expired or has been revoked through other
means, the AS <bcp14>SHOULD</bcp14> honor the revocation request to means, the AS <bcp14>SHOULD</bcp14> honor the revocation request to
the token management URI as valid, since the end result is still the token the token management URI as valid, since the end result is
not being usable.</t> that the token is still not usable.
</t>
</section> </section>
</section> </section>
<section anchor="secure-requests"><name>Securing Requests from the Client Instan <section anchor="secure-requests">
ce</name> <name>Securing Requests from the Client Instance</name>
<t>In GNAP, the client instance secures its requests to an AS and RS by pr
<t>In GNAP, the client instance secures its requests to an AS and RS by presenti esenting an access
ng an access token, proof of a key that it possesses (aka, a "key proof"), or both an access
token, presenting proof of a key that it possesses (aka, a "key proof"), or both token and
an access token and
key proof together.</t> key proof together.</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>When an access token is used with a key proof, this is a bound token reques <t>When an access token is used with a key proof, this is a bound toke
t. This type of n request. This type of
request is used for calls to the RS as well as the AS during grant negotiation .</t> request is used for calls to the RS as well as the AS during grant negotiation .</t>
<t>When a key proof is used with no access token, this is a non-authorized sig </li>
ned request. This <li>
<t>When a key proof is used with no access token, this is a non-author
ized signed request. This
type of request is used for calls to the AS to initiate a grant negotiation.</ t> type of request is used for calls to the AS to initiate a grant negotiation.</ t>
<t>When an access token is used with no key proof, this is a bearer token requ </li>
est. This type of <li>
request is used only for calls to the RS, and only with access tokens that are <t>When an access token is used with no key proof, this is a bearer to
ken request. This type of
request is used only for calls to the RS and only with access tokens that are
not bound to any key as described in <xref target="response-token-single"/>.</ t> not bound to any key as described in <xref target="response-token-single"/>.</ t>
<t>When neither an access token nor key proof are used, this is an unsecured r </li>
equest. This type <li>
<t>When neither an access token nor key proof are used, this is an uns
ecured request. This type
of request is used optionally for calls to the RS as part of an RS-first disco very of request is used optionally for calls to the RS as part of an RS-first disco very
process as described in <xref target="rs-request-without-token"/>.</t> process as described in <xref target="rs-request-without-token"/>.</t>
</list></t> </li>
</ul>
<section anchor="key-format"><name>Key Formats</name> <section anchor="key-format">
<name>Key Formats</name>
<t>Several different places in GNAP require the presentation of key material <t>Several different places in GNAP require the presentation of key mate
rial
by value or by reference. Key material sent by value is sent using a JSON object with several fields described in this section.</t> by value or by reference. Key material sent by value is sent using a JSON object with several fields described in this section.</t>
<t>All keys are associated with a specific key proofing method.
<t>All keys are associated with a specific key proofing method.
The proofing method associated with the key The proofing method associated with the key
is indicated using the <spanx style="verb">proof</spanx> field of the key object is indicated using the <tt>proof</tt> field of the key object.</t>
.</t> <dl>
<dt><tt>proof</tt> (string or object):</dt>
<dl> <dd>
<dt><spanx style="verb">proof</spanx> (string or object):</dt> <t>The form of proof that the client instance will use when
<dd>
<t>The form of proof that the client instance will use when
presenting the key. The valid values of this field and presenting the key. The valid values of this field and
the processing requirements for each are detailed in the processing requirements for each are detailed in
<xref target="binding-keys"/>. <bcp14>REQUIRED</bcp14>.</t> <xref target="binding-keys"/>. <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>A key presented by value <bcp14>MUST</bcp14> be a public key and <bcp
<t>A key presented by value <bcp14>MUST</bcp14> be a public key and <bcp14>MUST< 14>MUST</bcp14> be presented in only one
/bcp14> be presented in one and only one
supported format, as discussed in <xref target="security-multiple-key-formats"/> . Note that supported format, as discussed in <xref target="security-multiple-key-formats"/> . Note that
while most formats present the full value of the public key, some while most formats present the full value of the public key, some
formats present a value cryptographically derived from the public key. See formats present a value cryptographically derived from the public key. See
additional discussion of the presentation of public keys in <xref target="securi ty-symmetric"/>.</t> additional discussion of the presentation of public keys in <xref target="securi ty-symmetric"/>.</t>
<dl>
<dl> <dt><tt>jwk</tt> (object):</dt>
<dt><spanx style="verb">jwk</spanx> (object):</dt> <dd>
<dd> <t>The public key and its properties represented as a JSON Web Key (
<t>The public key and its properties represented as a JSON Web Key <xref tar JWK) <xref target="RFC7517"/>.
get="RFC7517"/>. A JWK <bcp14>MUST</bcp14> contain the <tt>alg</tt> (Algorithm) and <tt>kid</tt
A JWK <bcp14>MUST</bcp14> contain the <spanx style="verb">alg</spanx> (Algorit > (Key ID) parameters. The <tt>alg</tt>
hm) and <spanx style="verb">kid</spanx> (Key ID) parameters. The <spanx style="v parameter <bcp14>MUST NOT</bcp14> be "none". The <tt>x5c</tt> (X.509 Certifica
erb">alg</spanx> te Chain) parameter <bcp14>MAY</bcp14>
parameter <bcp14>MUST NOT</bcp14> be "none". The <spanx style="verb">x5c</span
x> (X.509 Certificate Chain) parameter <bcp14>MAY</bcp14>
be used to provide the X.509 representation of the provided public key. be used to provide the X.509 representation of the provided public key.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">cert</spanx> (string):</dt> <dt><tt>cert</tt> (string):</dt>
<dd> <dd>
<t>PEM serialized value of the certificate used to <t>The Privacy-Enhanced Mail (PEM) serialized value of the certifica
te used to
sign the request, with optional internal whitespace per <xref target="RFC7468" />. The sign the request, with optional internal whitespace per <xref target="RFC7468" />. The
PEM header and footer are optionally removed. PEM header and footer are optionally removed.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">cert#S256</spanx> (string):</dt> <dt><tt>cert#S256</tt> (string):</dt>
<dd> <dd>
<t>The certificate thumbprint calculated as
per <xref target="RFC8705">OAuth-MTLS</xref> in base64 URL <t>The certificate thumbprint calculated as
per MTLS for OAuth <xref target="RFC8705"> </xref> in base64url
encoding. Note that this format does not include encoding. Note that this format does not include
the full public key. the full public key.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>Additional key formats can be defined in the "GNAP Key Formats" regis
<t>Additional key formats are defined in the <xref target="IANA-key-formats">GNA try (<xref target="IANA-key-formats"> </xref>).</t>
P Key Formats Registry</xref>.</t> <t>The following non-normative example shows a single key presented in t
wo different formats. The example key is intended to be used with the HTTP messa
<t>The following non-normative example shows a single key presented in two diffe ge signatures proofing mechanism (<xref target="httpsig-binding"> </xref>), as i
rent formats. The example key is intended to be used with the <xref target="http ndicated by the <tt>httpsig</tt> value of the <tt>proof</tt> field.</t>
sig-binding">HTTP Message Signatures</xref> <t>As a JWK:</t>
proofing mechanism, as indicated by the <spanx style="verb">httpsig</spanx> valu <sourcecode type="json"><![CDATA[
e of the <spanx style="verb">proof</spanx> field.</t>
<t>As a JSON Web Key:</t>
<figure><sourcecode type="json"><![CDATA[
"key": { "key": {
"proof": "httpsig", "proof": "httpsig",
"jwk": { "jwk": {
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"kid": "xyz-1", "kid": "xyz-1",
"alg": "RS256", "alg": "RS256",
"n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..."
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>As a certificate in PEM format:</t>
<t>As a certificate in PEM format:</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"key": { "key": {
"proof": "httpsig", "proof": "httpsig",
"cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..."
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>When the key is presented in GNAP, proof of this key material <bcp14>MUST</bc <t>When the key is presented in GNAP, proof of this key material <bcp14>M
p14> be used to bind the request, the nature of which varies with UST</bcp14> be used to bind the request, the nature of which varies with
the location in the protocol the key is used. For a key used as part of a client the location in the protocol where the key is used. For a key used as part of a
instance's initial request client instance's initial request
in <xref target="request-client"/>, the key value represents the client instance 's public key, and in <xref target="request-client"/>, the key value represents the client instance 's public key, and
proof of that key <bcp14>MUST</bcp14> be presented in that request. For a key us ed as part of an proof of that key <bcp14>MUST</bcp14> be presented in that request. For a key us ed as part of an
access token response in <xref target="response-token-single"/>, the proof of th at key <bcp14>MUST</bcp14> access token response in <xref target="response-token-single"/>, the proof of th at key <bcp14>MUST</bcp14>
be used when the client instance later presents the access token to the RS.</t> be used when the client instance later presents the access token to the RS.</t>
<section anchor="key-reference">
<section anchor="key-reference"><name>Key References</name> <name>Key References</name>
<t>Keys in GNAP can also be passed by reference such that the party re
<t>Keys in GNAP can also be passed by reference such that the party receiving ceiving
the reference will be able to determine the appropriate keying material for the reference will be able to determine the appropriate keying material for
use in that part of the protocol. Key references are a single opaque string.</t> use in that part of the protocol. A key reference is a single opaque string.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"key": "S-P4XJQ_RYJCRTSU1.63N3E" "key": "S-P4XJQ_RYJCRTSU1.63N3E"
]]></sourcecode></figure> ]]></sourcecode>
<t>Keys referenced in this manner <bcp14>MAY</bcp14> be shared symmetr
<t>Keys referenced in this manner <bcp14>MAY</bcp14> be shared symmetric keys. S ic keys. See the additional considerations for symmetric keys in <xref target="s
ee the additional considerations for symmetric keys in <xref target="security-sy ecurity-symmetric"/>.
mmetric"/>.
The key reference <bcp14>MUST NOT</bcp14> contain any unencrypted private or sha red symmetric key information.</t> The key reference <bcp14>MUST NOT</bcp14> contain any unencrypted private or sha red symmetric key information.</t>
<t>Keys referenced in this manner <bcp14>MUST</bcp14> be bound to a si
<t>Keys referenced in this manner <bcp14>MUST</bcp14> be bound to a single proof ngle proofing mechanism.</t>
ing mechanism.</t> <t>The means of dereferencing this reference to a key value and proofi
ng mechanism are out of scope for this specification.
<t>The means of dereferencing this reference to a key value and proofing mechani Commonly, key references are created by the AS and do not necessarily need
sm are out of scope for this specification.
Commonly, key references are created by the AS and are not necessarily needed
to be understood by the client. These types of key references are an to be understood by the client. These types of key references are an
internal reference to the AS, such as an identifier of a record in a database. internal reference to the AS, such as an identifier of a record in a database.
In other applications, it can be useful to use key references that are resolvabl e In other applications, it can be useful to use key references that are resolvabl e
by both clients and AS, which could be accomplished by a client publishing by both clients and the AS, which could be accomplished by a client publishing
a public key at a URI, for example. For interoperability, this method could late r be described a public key at a URI, for example. For interoperability, this method could late r be described
as an extension, but doing so is out of scope for this specification.</t> as an extension, but doing so is out of scope for this specification.</t>
</section>
</section> <section anchor="key-protection">
<section anchor="key-protection"><name>Key Protection</name> <name>Key Protection</name>
<t>The security of GNAP relies on the cryptographic security of the ke
<t>The security of GNAP relies on the cryptographic security of the keys themsel ys themselves.
ves. When symmetric keys are used in GNAP, a key management system or secure key deri
When symmetric keys are used in GNAP, a key management system or secure key deri vation mechanism <bcp14>MUST</bcp14> be used to supply the keys. Symmetric keys
vation mechanism <bcp14>MUST</bcp14> be used to supply the keys. Symmetric keys <bcp14>MUST NOT</bcp14> be a human-memorable password or a value derived from on
<bcp14>MUST NOT</bcp14> be a human memorable password or a value derived from on e. Symmetric keys <bcp14>MUST NOT</bcp14> be passed by value from the client ins
e. Symmetric keys <bcp14>MUST NOT</bcp14> be passed by value from the client ins tance to the AS.</t>
tance to the AS.</t> <t>Additional security considerations apply when rotating keys (see <x
ref target="security-key-rotation"> </xref>).</t>
<t>Additional security considerations apply when <xref target="security-key-rota </section>
tion">rotating keys</xref>.</t> </section>
<section anchor="use-access-token">
</section> <name>Presenting Access Tokens</name>
</section> <t>Access tokens are issued to client instances in GNAP to allow the cli
<section anchor="use-access-token"><name>Presenting Access Tokens</name> ent instance to make
<t>Access tokens are issued to client instances in GNAP to allow the client inst
ance to make
an authorized call to an API. an authorized call to an API.
The method the client instance uses to send an access token depends on whether The method the client instance uses to send an access token depends on whether
the token is bound to a key, and if so which proofing method is associated the token is bound to a key and, if so, which proofing method is associated
with the key. This information is conveyed by the with the key. This information is conveyed by the
<spanx style="verb">key</spanx> parameter and the <spanx style="verb">bearer</sp <tt>key</tt> parameter and the <tt>bearer</tt> flag in the access token response
anx> flag in <xref target="response-token-single">the access token response stru structure (<xref target="response-token-single"> </xref>).</t>
cture</xref>.</t> <t>If the <tt>flags</tt> field does not contain the <tt>bearer</tt> flag
and the <tt>key</tt> is absent, the access token
<t>If the <spanx style="verb">flags</spanx> field does not contain the <spanx st
yle="verb">bearer</spanx> flag and the <spanx style="verb">key</spanx> is absent
, the access token
<bcp14>MUST</bcp14> be sent using the same key and proofing mechanism that the c lient instance used <bcp14>MUST</bcp14> be sent using the same key and proofing mechanism that the c lient instance used
in its initial request (or its most recent rotation).</t> in its initial request (or its most recent rotation).</t>
<t>If the <tt>flags</tt> field does not contain the <tt>bearer</tt> flag
<t>If the <spanx style="verb">flags</spanx> field does not contain the <spanx st and the <tt>key</tt> value is an object as
yle="verb">bearer</spanx> flag and the <spanx style="verb">key</spanx> value is
an object as
described in <xref target="key-format"/>, the access token <bcp14>MUST</bcp14> b e sent using the key and proofing described in <xref target="key-format"/>, the access token <bcp14>MUST</bcp14> b e sent using the key and proofing
mechanism defined by the value of the <spanx style="verb">proof</spanx> field wi mechanism defined by the value of the <tt>proof</tt> field within the key object
thin the key object.</t> .</t>
<t>The access token <bcp14>MUST</bcp14> be sent using the HTTP Authoriza
<t>The access token <bcp14>MUST</bcp14> be sent using the HTTP "Authorization" r tion request header field and
equest header field and
the "GNAP" authorization scheme along with a key proof as described in <xref tar get="binding-keys"/> the "GNAP" authorization scheme along with a key proof as described in <xref tar get="binding-keys"/>
for the key bound to the access token. For example, an access token bound using for the key bound to the access token. For example, an access token bound using
HTTP Message Signatures would be sent as follows:</t> HTTP message signatures would be sent as follows:</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
GET /stuff HTTP/1.1 GET /stuff HTTP/1.1
Host: resource.example.com Host: resource.example.com
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=("@method" "@target-uri" "authorization")\ Signature-Input: sig1=("@method" "@target-uri" "authorization")\
;created=1618884473;keyid="gnap-rsa";nonce="NAOEJF12ER2";tag="gnap" ;created=1618884473;keyid="gnap-rsa";nonce="NAOEJF12ER2";tag="gnap"
Signature: sig1=:FQ+EjWqc38uLFByKa5y+c4WyYYwCTGUhidWKfr5L1Cha8FiPEw\ Signature: sig1=:FQ+EjWqc38uLFByKa5y+c4WyYYwCTGUhidWKfr5L1Cha8FiPEw\
DxG7nWttpBLS/B6VLfkZJogPbclySs9MDIsAIJwHnzlcJjwXWR2lfvm2z3X7EkJHm\ DxG7nWttpBLS/B6VLfkZJogPbclySs9MDIsAIJwHnzlcJjwXWR2lfvm2z3X7EkJHm\
Zp4SmyKOS34luAiKR1xwf32NYFolHmZf/SbHZJuWvQuS4U33C+BbsXz8MflFH1Dht\ Zp4SmyKOS34luAiKR1xwf32NYFolHmZf/SbHZJuWvQuS4U33C+BbsXz8MflFH1Dht\
H/C1E5i244gSbdLCPxzABc/Q0NHVSLo1qaouYIvnxXB8OT3K7mwWjsLh1GC5vFThb\ H/C1E5i244gSbdLCPxzABc/Q0NHVSLo1qaouYIvnxXB8OT3K7mwWjsLh1GC5vFThb\
3XQ363r6f0OPRa4qWHhubR/d/J/lNOjbBdjq9AJ69oqNJ+A2XT+ZCrVasEJE0OBvD\ 3XQ363r6f0OPRa4qWHhubR/d/J/lNOjbBdjq9AJ69oqNJ+A2XT+ZCrVasEJE0OBvD\
auQoiywhb8BMB7+PEINsPk5/8UvaNxbw==: auQoiywhb8BMB7+PEINsPk5/8UvaNxbw==:
]]></sourcecode></figure> ]]></sourcecode>
<t>If the <tt>flags</tt> field contains the <tt>bearer</tt> flag, the ac
<t>If the <spanx style="verb">flags</spanx> field contains the <spanx style="ver cess token is a bearer token
b">bearer</spanx> flag, the access token is a bearer token that <bcp14>MUST</bcp14> be sent using the Authorization request header field me
that <bcp14>MUST</bcp14> be sent using the <spanx style="verb">Authorization Req thod defined in <xref target="RFC6750"/>.</t>
uest Header Field</spanx> method defined in <xref target="RFC6750"/>.</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0
]]></sourcecode></figure> ]]></sourcecode>
<t>The <tt>Form-Encoded Body Parameter</tt> and <tt>URI Query Parameter<
<t>The <spanx style="verb">Form-Encoded Body Parameter</spanx> and <spanx style= /tt> methods of <xref target="RFC6750"/> <bcp14>MUST NOT</bcp14>
"verb">URI Query Parameter</spanx> methods of <xref target="RFC6750"/> <bcp14>MU
ST NOT</bcp14>
be used for GNAP access tokens.</t> be used for GNAP access tokens.</t>
</section>
</section> <section anchor="binding-keys">
<section anchor="binding-keys"><name>Proving Possession of a Key with a Request< <name>Proving Possession of a Key with a Request</name>
/name> <t>Any keys presented by the client instance to the AS or RS <bcp14>MUST
</bcp14> be validated as
<t>Any keys presented by the client instance to the AS or RS <bcp14>MUST</bcp14>
be validated as
part of the request in which they are presented. The type of binding part of the request in which they are presented. The type of binding
used is indicated by the <spanx style="verb">proof</spanx> parameter of the key used is indicated by the <tt>proof</tt> parameter of the key object in <xref tar
object in <xref target="key-format"/>. get="key-format"/>.
Key proof methods are specified either by a string, which consists of the key pr Key proofing methods are specified either by a string, which consists of the key
oof proofing
method name on its own, or by a JSON object with the required field <spanx style method name on its own, or by a JSON object with the required field <tt>method</
="verb">method</spanx>:</t> tt>:</t>
<dl>
<dl> <dt><tt>method</tt>:</dt>
<dt><spanx style="verb">method</spanx>:</dt> <dd>
<dd> <t>The name of the key proofing method to be used.
<t>The name of the key proofing method to be used.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>Individual methods defined as objects <bcp14>MAY</bcp14> define addit
<t>Individual methods defined as objects <bcp14>MAY</bcp14> define additional pa ional parameters as members in this object.</t>
rameters as members in this object.</t> <t>Values for the <tt>method</tt> defined by this specification are as f
ollows:</t>
<t>Values for the <spanx style="verb">method</spanx> defined by this specificati <dl>
on are as follows:</t> <dt><tt>"httpsig"</tt> (string or object):</dt>
<dd>
<dl> <t>HTTP message signing. See <xref target="httpsig-binding"/>.</t>
<dt><spanx style="verb">"httpsig"</spanx> (string or object):</dt> </dd>
<dd> <dt><tt>"mtls"</tt> (string):</dt>
<t>HTTP Signing signature headers. See <xref target="httpsig-binding"/>.</t> <dd>
</dd> <t>MTLS certificate verification. See <xref target="mtls"/>.</t>
<dt><spanx style="verb">"mtls"</spanx> (string):</dt> </dd>
<dd> <dt><tt>"jwsd"</tt> (string):</dt>
<t>Mutual TLS certificate verification. See <xref target="mtls"/>.</t> <dd>
</dd> <t>A detached JWS signature header. See <xref target="detached-jws"/
<dt><spanx style="verb">"jwsd"</spanx> (string):</dt> >.</t>
<dd> </dd>
<t>A detached JWS signature header. See <xref target="detached-jws"/>.</t> <dt><tt>"jws"</tt> (string):</dt>
</dd> <dd>
<dt><spanx style="verb">"jws"</spanx> (string):</dt> <t>Attached JWS Payload. See <xref target="attached-jws"/>.</t>
<dd> </dd>
<t>Attached JWS payload. See <xref target="attached-jws"/>.</t> </dl>
</dd> <t>Additional proofing methods can be defined in the "GNAP Key Proofing
</dl> Methods" registry (<xref target="IANA-key-proof-methods"> </xref>).</t>
<t>Additional proofing methods are defined by the <xref target="IANA-key-proof-m
ethods">GNAP Key Proofing Methods Registry</xref>.</t>
<t>Proof methods <bcp14>MAY</bcp14> be defined as both an object and a string. F or example, the <spanx style="verb">httpsig</spanx> method can be specified as a n <t>Proofing methods <bcp14>MAY</bcp14> be defined as both an object and a string. For example, the <tt>httpsig</tt> method can be specified as an
object with its parameters explicitly declared, such as:</t> object with its parameters explicitly declared, such as:</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"proof": { "proof": {
"method": "httpsig", "method": "httpsig",
"alg": "ecdsa-p384-sha384", "alg": "ecdsa-p384-sha384",
"content-digest-alg": "sha-256" "content-digest-alg": "sha-256"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The <tt>httpsig</tt> method also defines default behavior when it is
<t>The <spanx style="verb">httpsig</spanx> method also defines default behavior passed as a string form,
when it is passed as a string form,
using the signature algorithm specified by the associated key using the signature algorithm specified by the associated key
material and the content digest is calculated using sha-256. This configuration can be selected material and the content digest is calculated using sha-256. This configuration can be selected
using the following shortened form:</t> using the following shortened form:</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"proof": "httpsig" "proof": "httpsig"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>All key binding methods used by this specification <bcp14>MUST</bcp14
<t>All key binding methods used by this specification <bcp14>MUST</bcp14> cover > cover all relevant portions
all relevant portions
of the request, including anything that would change the nature of the request, to allow of the request, including anything that would change the nature of the request, to allow
for secure validation of the request. Relevant aspects include for secure validation of the request. Relevant aspects include
the URI being called, the HTTP method being used, any relevant HTTP headers and the URI being called, the HTTP method being used, any relevant HTTP headers and
values, and the HTTP message content itself. The verifier of the signed message values, and the HTTP message content itself. The verifier of the signed message
<bcp14>MUST</bcp14> validate all components of the signed message to ensure that nothing <bcp14>MUST</bcp14> validate all components of the signed message to ensure that nothing
has been tampered with or substituted in a way that would change the nature of has been tampered with or substituted in a way that would change the nature of
the request. Key binding method definitions <bcp14>MUST</bcp14> enumerate how th ese the request. Definitions of key binding methods <bcp14>MUST</bcp14> enumerate ho w these
requirements are fulfilled.</t> requirements are fulfilled.</t>
<t>When a key proofing mechanism is bound to an access token, the key be
<t>When a key proofing mechanism is bound to an access token, the key being pres ing presented <bcp14>MUST</bcp14>
ented <bcp14>MUST</bcp14> be the key associated with the access token, and the access token <bcp14>MUST</b
be the key associated with the access token and the access token <bcp14>MUST</bc cp14> be covered
p14> be covered
by the signature method of the proofing mechanism.</t> by the signature method of the proofing mechanism.</t>
<t>The key binding methods in this section <bcp14>MAY</bcp14> be used by other c <t>The key binding methods in this section <bcp14>MAY</bcp14> be used by other
omponents making calls components making calls as part of GNAP, such as the extensions allowing the
as part of GNAP, such as the extensions allowing the RS to make calls to the RS to make calls to the AS defined in <xref
AS defined in <xref target="I-D.ietf-gnap-resource-servers"/>. To facilitate thi target="I-D.ietf-gnap-resource-servers"/>. To facilitate this extended use,
s extended use, the "signer" and "verifier" are used as generic terms in the subsections below.
sections below are defined in generic terms of the "signer" and "verifier" of th In the core functions of GNAP specified in this document, the "signer" is the
e HTTP message. client instance, and the "verifier" is the AS (for grant requests) or RS (for
In the core functions of GNAP specified in this document, the "signer" is the cl resource requests), as appropriate.</t>
ient instance and the "verifier" <t>When used for delegation in GNAP, these key binding mechanisms allow
is the AS (for grant requests) or RS (for resource requests), as appropriate.</t
>
<t>When used for delegation in GNAP, these key binding mechanisms allow
the AS to ensure that the keys presented by the client instance in the initial r equest are in the AS to ensure that the keys presented by the client instance in the initial r equest are in
control of the party calling any follow-up or continuation requests. To facilita te control of the party calling any follow-up or continuation requests. To facilita te
this requirement, the <xref target="response-continue">continuation response</xr this requirement, the continuation response (<xref target="response-continue"> <
ef> includes /xref>) includes
an access token bound to the <xref target="request-client">client instance's key an access token bound to the client instance's key (<xref target="request-client
</xref>, and that key (or its most recent rotation) "> </xref>), and that key (or its most recent rotation)
<bcp14>MUST</bcp14> be proved in all continuation requests <bcp14>MUST</bcp14> be proved in all continuation requests
(<xref target="continue-request"/>). Token management requests (<xref target="to ken-management"/>) are similarly bound (<xref target="continue-request"/>). Token management requests (<xref target="to ken-management"/>) are similarly bound
to either the access token's own key or, in the case of bearer tokens, the clien t instance's key.</t> to either the access token's own key or, in the case of bearer tokens, the clien t instance's key.</t>
<t>In the following subsections, unless otherwise noted, the <tt>RS256</
<t>In the following sections, unless otherwise noted, the <spanx style="verb">RS tt> JSON Object Signing and Encryption (JOSE) signature algorithm (defined in <x
256</spanx> JOSE Signature Algorithm (defined in <xref section="3.3" sectionForm ref section="3.3" sectionFormat="of" target="RFC7518"/>) is applied
at="of" target="RFC7518"/>) is applied
using the following RSA key (presented here in JWK format):</t> using the following RSA key (presented here in JWK format):</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"kid": "gnap-rsa", "kid": "gnap-rsa",
"p": "xS4-YbQ0SgrsmcA7xDzZKuVNxJe3pCYwdAe6efSy4hdDgF9-vhC5gjaRk\ "p": "xS4-YbQ0SgrsmcA7xDzZKuVNxJe3pCYwdAe6efSy4hdDgF9-vhC5gjaRk\
i1wWuERSMW4Tv44l5HNrL-Bbj_nCJxr_HAOaesDiPn2PnywwEfg3Nv95Nn-\ i1wWuERSMW4Tv44l5HNrL-Bbj_nCJxr_HAOaesDiPn2PnywwEfg3Nv95Nn-\
eilhqXRaW-tJKEMjDHu_fmJBeemHNZI412gBnXdGzDVo22dvYoxd6GM", eilhqXRaW-tJKEMjDHu_fmJBeemHNZI412gBnXdGzDVo22dvYoxd6GM",
"kty": "RSA", "kty": "RSA",
"q": "rVdcT_uy-CD0GKVLGpEGRR7k4JO6Tktc8MEHkC6NIFXihk_6vAIOCzCD6\ "q": "rVdcT_uy-CD0GKVLGpEGRR7k4JO6Tktc8MEHkC6NIFXihk_6vAIOCzCD6\
LMovMinOYttpRndKoGTNdJfWlDFDScAs8C5n2y1STCQPRximBY-bw39-aZq\ LMovMinOYttpRndKoGTNdJfWlDFDScAs8C5n2y1STCQPRximBY-bw39-aZq\
skipping to change at line 5567 skipping to change at line 5449
"dq": "iMZmELaKgT9_W_MRT-UfDWtTLeFjIGRW8aFeVmZk9R7Pnyt8rNzyN-IQ\ "dq": "iMZmELaKgT9_W_MRT-UfDWtTLeFjIGRW8aFeVmZk9R7Pnyt8rNzyN-IQ\
M40ql8u8J6vc2GmQGfokLlPQ6XLSCY68_xkTXrhoU1f-eDntkhP7L6XawSK\ M40ql8u8J6vc2GmQGfokLlPQ6XLSCY68_xkTXrhoU1f-eDntkhP7L6XawSK\
Onv5F2H7wyBQ75HUmHTg8AK2B_vRlMyFKjXbVlzKf4kvqChSGEz4IjQ", Onv5F2H7wyBQ75HUmHTg8AK2B_vRlMyFKjXbVlzKf4kvqChSGEz4IjQ",
"n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAt\ "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAt\
YKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZGYX\ YKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZGYX\
jHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZx\ jHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZx\
e0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0\ e0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0\
bunS0K3bA_3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kO\ bunS0K3bA_3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kO\
zywzwPTuq-cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" zywzwPTuq-cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Key proofing methods <bcp14>SHOULD</bcp14> define a mechanism to allo
<t>Key proofing methods <bcp14>SHOULD</bcp14> define a mechanism to allow the ro w the rotation of keys discussed
tation of keys discussed
in <xref target="rotate-access-token-key"/>. Key rotation mechanisms <bcp14>MUST </bcp14> define a way for presenting in <xref target="rotate-access-token-key"/>. Key rotation mechanisms <bcp14>MUST </bcp14> define a way for presenting
proof of two keys simultaneously with the following attributes:</t> proof of two keys simultaneously with the following attributes:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>The value of or reference to the new key material <bcp14>MUST</bcp14> be si <t>The value of or reference to the new key material <bcp14>MUST</bc
gned by the existing key. p14> be signed by the existing key.
Generally speaking, this amounts to using the existing key to sign the content of the Generally speaking, this amounts to using the existing key to sign the content of the
message which contains the new key.</t> message that contains the new key.</t>
<t>The signature of the old key <bcp14>MUST</bcp14> be signed by the new key. </li>
<li>
<t>The signature of the old key <bcp14>MUST</bcp14> be signed by the
new key.
Generally speaking, this means including the signature value of the old key un der the Generally speaking, this means including the signature value of the old key un der the
coverage of the new key.</t> coverage of the new key.</t>
</list></t> </li>
</ul>
<section anchor="httpsig-binding"><name>HTTP Message Signatures</name> <section anchor="httpsig-binding">
<name>HTTP Message Signatures</name>
<t>This method is indicated by the method value <spanx style="verb">httpsig</spa <t>This method is indicated by the method value <tt>httpsig</tt> and c
nx> and can be declared in either object an be declared in either object
form or string form.</t> form or string form.</t>
<t>When the proofing method is specified in object form, the following
<t>When the proof method is specified in object form, the following parameters a parameters are defined:</t>
re defined:</t> <dl>
<dt><tt>alg</tt>:</dt>
<dl> <dd>
<dt><spanx style="verb">alg</spanx>:</dt> <t>The HTTP signature algorithm, from the "HTTP Signature Algorith
<dd> ms" registry. <bcp14>REQUIRED</bcp14>.</t>
<t>The HTTP signature algorithm, from the HTTP Signature Algorithm registry. </dd>
<bcp14>REQUIRED</bcp14>.</t> <dt><tt>content-digest-alg</tt>:</dt>
</dd> <dd>
<dt><spanx style="verb">content-digest-alg</spanx>:</dt> <t>The algorithm used for the Content-Digest field, used to protec
<dd> t the content when present in the message. <bcp14>REQUIRED</bcp14>.</t>
<t>The algorithm used for the Content-Digest field, used to protect the cont </dd>
ent when present in the message. <bcp14>REQUIRED</bcp14>.</t> </dl>
</dd> <t>This example uses the Elliptic Curve Digital Signature Algorithm (E
</dl> CDSA) signing algorithm over the P384 curve and the SHA-512 hashing
<t>This example uses the ECDSA signing algorithm over the P384 curve and the SHA
-512 hashing
algorithm for the content digest.</t> algorithm for the content digest.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"proof": { "proof": {
"method": "httpsig", "method": "httpsig",
"alg": "ecdsa-p384-sha384", "alg": "ecdsa-p384-sha384",
"content-digest-alg": "sha-512" "content-digest-alg": "sha-512"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>When the proofing method is specified in string form, the signing a
<t>When the proof method is specified in string form, the signing algorithm <bcp lgorithm <bcp14>MUST</bcp14> be derived from the
14>MUST</bcp14> be derived from the
key material (such as using the JWS algorithm in a JWK formatted key), and the c ontent digest key material (such as using the JWS algorithm in a JWK formatted key), and the c ontent digest
algorithm <bcp14>MUST</bcp14> be <spanx style="verb">sha-256</spanx>.</t> algorithm <bcp14>MUST</bcp14> be <tt>sha-256</tt>.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"proof": "httpsig" "proof": "httpsig"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>When using this method, the signer creates an HTTP message signatur
<t>When using this method, the signer creates an HTTP Message Signature as descr e as described in
ibed in
<xref target="RFC9421"/>. The covered components of the signature <bcp14>MUST</b cp14> include the <xref target="RFC9421"/>. The covered components of the signature <bcp14>MUST</b cp14> include the
following:</t> following:</t>
<dl>
<dl> <dt><tt>"@method"</tt>:</dt>
<dt><spanx style="verb">"@method"</spanx>:</dt> <dd>
<dd> <t>The method used in the HTTP request.</t>
<t>The method used in the HTTP request.</t> </dd>
</dd> <dt><tt>"@target-uri"</tt>:</dt>
<dt><spanx style="verb">"@target-uri"</spanx>:</dt> <dd>
<dd> <t>The full request URI of the HTTP request.</t>
<t>The full request URI of the HTTP request.</t> </dd>
</dd> </dl>
</dl> <t>When the message contains request content, the covered components <
bcp14>MUST</bcp14> also include the following:</t>
<t>When the message contains request content, the covered components <bcp14>MUST <dl>
</bcp14> also include the following:</t> <dt><tt>"content-digest"</tt>:</dt>
<dd>
<dl> <t>The Content-Digest header as defined in <xref target="RFC9530"/
<dt><spanx style="verb">"content-digest"</spanx>:</dt> >. When the
<dd>
<t>The Content-Digest header as defined in <xref target="RFC9530"/>. When th
e
request message has content, the signer <bcp14>MUST</bcp14> calculate this fie ld value and include request message has content, the signer <bcp14>MUST</bcp14> calculate this fie ld value and include
the field in the request. The verifier the field in the request. The verifier
<bcp14>MUST</bcp14> validate this field value. <bcp14>REQUIRED</bcp14> when th e message request contains message content.</t> <bcp14>MUST</bcp14> validate this field value. <bcp14>REQUIRED</bcp14> when th e message request contains message content.</t>
</dd> </dd>
</dl> </dl>
<t>When the request is bound to an access token, the covered component
<t>When the request is bound to an access token, the covered components s
<bcp14>MUST</bcp14> also include the following:</t> <bcp14>MUST</bcp14> also include the following:</t>
<dl>
<dl> <dt><tt>"authorization"</tt>:</dt>
<dt><spanx style="verb">"authorization"</spanx>:</dt> <dd>
<dd> <t>The Authorization header used to present the access token as di
<t>The Authorization header used to present the access token as discussed in scussed in
<xref target="use-access-token"/>.</t> <xref target="use-access-token"/>.</t>
</dd> </dd>
</dl> </dl>
<t>Other message components <bcp14>MAY</bcp14> also be included.</t>
<t>Other message components <bcp14>MAY</bcp14> also be included.</t> <t>The signer <bcp14>MUST</bcp14> include the <tt>tag</tt> signature
parameter with the value <tt>gnap</tt>, and the verifier <bcp14>MUST</bcp14> ver
<t>The signer <bcp14>MUST</bcp14> include the <spanx style="verb">tag</spanx> si ify that the parameter exists with this value. The signer <bcp14>MUST</bcp14> in
gnature parameter with the value <spanx style="verb">gnap</spanx>, and the veri clude the <tt>created</tt> signature parameter with a timestamp of when the sign
fier <bcp14>MUST</bcp14> verify that the parameter exists with this value. The s ature was created, and the verifier <bcp14>MUST</bcp14> ensure that the creation
igner <bcp14>MUST</bcp14> include the <spanx style="verb">created</spanx> signat timestamp is sufficiently close to the current time given expected network dela
ure parameter with a timestamp of when the signature was created, and the verifi y and clock skew. The signer <bcp14>SHOULD</bcp14> include the <tt>nonce</tt> pa
er <bcp14>MUST</bcp14> ensure that the creation timestamp is sufficiently close rameter with a unique and unguessable value. When included, the verifier <bcp14>
to the current time given expected network delay and clock skew. The signer <bcp MUST</bcp14> determine that the nonce value is unique within a reasonably short
14>SHOULD</bcp14> include the <spanx style="verb">nonce</spanx> parameter with a time period such as several minutes.</t>
unique and unguessable value. When included, the verifier <bcp14>MUST</bcp14> d <t>If the signer's key presented is a JWK, the <tt>keyid</tt> paramete
etermine that the nonce value is unique within a reasonably short time period su r of the signature <bcp14>MUST</bcp14> be set
ch as several minutes.</t> to the <tt>kid</tt> value of the JWK, and the signing algorithm used <bcp14>MUST
</bcp14> be the JWS
<t>If the signer's key presented is a JWK, the <spanx style="verb">keyid</spanx> algorithm denoted by the key's <tt>alg</tt> field of the JWK.</t>
parameter of the signature <bcp14>MUST</bcp14> be set <t>The explicit <tt>alg</tt> signature parameter <bcp14>MUST NOT</bcp1
to the <spanx style="verb">kid</spanx> value of the JWK, the signing algorithm u 4> be included in the signature, since the algorithm
sed <bcp14>MUST</bcp14> be the JWS will be derived from either the key material or the <tt>proof</tt> valu
algorithm denoted by the key's <spanx style="verb">alg</spanx> field of the JWK. e.</t>
</t>
<t>The explicit <spanx style="verb">alg</spanx> signature parameter <bcp14>MUST
NOT</bcp14> be included in the signature, since the algorithm
will be derived either from the key material or from the <spanx style="verb">pro
of</spanx> value.</t>
<t>In the following non-normative example, the message content is the following
JSON object:</t>
<figure><sourcecode type="json"><![CDATA[ <t>In the following non-normative example, the message content is a JS
ON object:</t>
<sourcecode type="json"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"access_token": { "access_token": {
"access": [ "access": [
"dolphin-metadata" "dolphin-metadata"
] ]
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
skipping to change at line 5713 skipping to change at line 5579
3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\
N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ"
} }
} }
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://client.foo/" "uri": "https://client.foo/"
}, },
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>This content is hashed for the Content-Digest header using <tt>sha-
<t>This content is hashed for the Content-Digest header using <spanx style="verb 256</tt> into the following encoded value:</t>
">sha-256</spanx> into the following encoded value:</t> <artwork><![CDATA[
<figure><artwork><![CDATA[
sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAGg=: sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAGg=:
]]></artwork></figure> ]]></artwork>
<t>The HTTP message signature input string is calculated to be the fol
<t>The HTTP message signature input string is calculated to be the following:</t lowing:</t>
> <artwork><![CDATA[
<figure><artwork><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"@method": POST "@method": POST
"@target-uri": https://server.example.com/gnap "@target-uri": https://server.example.com/gnap
"content-digest": \ "content-digest": \
sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAGg=: sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAGg=:
"content-length": 988 "content-length": 988
"content-type": application/json "content-type": application/json
"@signature-params": ("@method" "@target-uri" "content-digest" \ "@signature-params": ("@method" "@target-uri" "content-digest" \
"content-length" "content-type");created=1618884473\ "content-length" "content-type");created=1618884473\
;keyid="gnap-rsa";nonce="NAOEJF12ER2";tag="gnap" ;keyid="gnap-rsa";nonce="NAOEJF12ER2";tag="gnap"
]]></artwork></figure> ]]></artwork>
<t>This leads to the following full HTTP message request:</t>
<t>This leads to the following full HTTP message request:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
POST /gnap HTTP/1.1 POST /gnap HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Content-Length: 988 Content-Length: 988
Content-Digest: sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAG\ Content-Digest: sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAG\
g=: g=:
Signature-Input: sig1=("@method" "@target-uri" "content-digest" \ Signature-Input: sig1=("@method" "@target-uri" "content-digest" \
"content-length" "content-type");created=1618884473\ "content-length" "content-type");created=1618884473\
skipping to change at line 5794 skipping to change at line 5654
3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\
N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ"
} }
} }
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://client.foo/" "uri": "https://client.foo/"
}, },
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The verifier <bcp14>MUST</bcp14> ensure that the signature covers all require <t>The verifier <bcp14>MUST</bcp14> ensure that the signature covers a
d message components. ll required message components.
If the HTTP Message includes content, the verifier <bcp14>MUST</bcp14> If the HTTP message includes content, the verifier <bcp14>MUST</bcp14>
calculate and verify the value of the <spanx style="verb">Content-Digest</spanx> calculate and verify the value of the <tt>Content-Digest</tt> header. The verifi
header. The verifier <bcp14>MUST</bcp14> validate er <bcp14>MUST</bcp14> validate
the signature against the expected key of the signer.</t> the signature against the expected key of the signer.</t>
<t>A received message <bcp14>MAY</bcp14> include multiple signatures,
<t>A received message <bcp14>MAY</bcp14> include multiple signatures, each with each with its own label. The verifier <bcp14>MUST</bcp14> examine all included s
its own label. The verifier <bcp14>MUST</bcp14> examine all included signatures ignatures until it finds (at least) one that is acceptable according to its poli
until it finds (at least) one that's acceptable according to its policy and meet cy and meets the requirements in this section.</t>
s the requirements in this section.</t> <section anchor="httpsig-rotate">
<name>Key Rotation Using HTTP Message Signatures</name>
<section anchor="httpsig-rotate"><name>Key Rotation using HTTP Message Signature <t>When rotating a key using HTTP message signatures, the message, w
s</name> hich includes the new public key
<t>When rotating a key using HTTP Message Signatures, the message, which include
s the new public key
value or reference, is first signed with the old key following all of the requir ements in <xref target="httpsig-binding"/>. value or reference, is first signed with the old key following all of the requir ements in <xref target="httpsig-binding"/>.
The message is then signed again with the new key by following all of the requir ements in <xref target="httpsig-binding"/> again The message is then signed again with the new key by following all of the requir ements in <xref target="httpsig-binding"/> again,
with the following additional requirements:</t> with the following additional requirements:</t>
<ul spacing="normal">
<t><list style="symbols"> <li>
<t>The covered components <bcp14>MUST</bcp14> include the Signature and Signat <t>The covered components <bcp14>MUST</bcp14> include the Signat
ure-Input values from the signature generated with the old key</t> ure and Signature-Input values from the signature generated with the old key.</t
<t>The tag value <bcp14>MUST</bcp14> be <spanx style="verb">gnap-rotate</spanx >
></t> </li>
</list></t> <li>
<t>The tag value <bcp14>MUST</bcp14> be <tt>gnap-rotate</tt>.</t
<t>For example, the following request to the token management endpoint for rotat >
ing a token value </li>
contains the new key in the request. The message is first signed using the old k </ul>
ey <t>For example, the following request to the token management endpoi
nt for rotating a token value
contains the new key in the request. The message is first signed using the old k
ey,
and the resulting signature is placed in "old-key":</t> and the resulting signature is placed in "old-key":</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
POST /token/PRY5NM33 HTTP/1.1 POST /token/PRY5NM33 HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP 4398.34-12-asvDa.a Authorization: GNAP 4398.34-12-asvDa.a
Content-Digest: sha-512=:Fb/A5vnawhuuJ5xk2RjGrbbxr6cvinZqd4+JPY85u/\ Content-Digest: sha-512=:Fb/A5vnawhuuJ5xk2RjGrbbxr6cvinZqd4+JPY85u/\
JNyTlmRmCOtyVhZ1Oz/cSS4tsYen6fzpCwizy6UQxNBQ==: JNyTlmRmCOtyVhZ1Oz/cSS4tsYen6fzpCwizy6UQxNBQ==:
Signature-Input: old-key=("@method" "@target-uri" "content-digest" \ Signature-Input: old-key=("@method" "@target-uri" "content-digest" \
"authorization");created=1618884475;keyid="test-key-ecc-p256"\ "authorization");created=1618884475;keyid="test-key-ecc-p256"\
;tag="gnap" ;tag="gnap"
skipping to change at line 5845 skipping to change at line 5704
"proof": "httpsig", "proof": "httpsig",
"jwk": { "jwk": {
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"kid": "xyz-2", "kid": "xyz-2",
"alg": "RS256", "alg": "RS256",
"n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..."
} }
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The signer then creates a new signature using the new key, adding
<t>The signer then creates a new signature using the new key, adding the signatu the signature
re
input and value to the signature base.</t> input and value to the signature base.</t>
<artwork><![CDATA[
<figure><artwork><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"@method": POST "@method": POST
"@target-uri": https://server.example.com/token/PRY5NM33 "@target-uri": https://server.example.com/token/PRY5NM33
"content-digest": sha-512=:Fb/A5vnawhuuJ5xk2RjGrbbxr6cvinZqd4+JPY85\ "content-digest": sha-512=:Fb/A5vnawhuuJ5xk2RjGrbbxr6cvinZqd4+JPY85\
u/JNyTlmRmCOtyVhZ1Oz/cSS4tsYen6fzpCwizy6UQxNBQ==: u/JNyTlmRmCOtyVhZ1Oz/cSS4tsYen6fzpCwizy6UQxNBQ==:
"authorization": GNAP 4398.34-12-asvDa.a "authorization": GNAP 4398.34-12-asvDa.a
"signature";key="old-key": :YdDJjDn2Sq8FR82e5IcOLWmmf6wILoswlnRcz+n\ "signature";key="old-key": :YdDJjDn2Sq8FR82e5IcOLWmmf6wILoswlnRcz+n\
M+e8xjFDpWS2YmiMYDqUdri2UiJsZx63T1z7As9Kl6HTGkQ==: M+e8xjFDpWS2YmiMYDqUdri2UiJsZx63T1z7As9Kl6HTGkQ==:
"signature-input";key="old-key": ("@method" "@target-uri" \ "signature-input";key="old-key": ("@method" "@target-uri" \
"content-digest" "authorization");created=1618884475\ "content-digest" "authorization");created=1618884475\
;keyid="test-key-ecc-p256";tag="gnap" ;keyid="test-key-ecc-p256";tag="gnap"
"@signature-params": ("@method" "@target-uri" "content-digest" \ "@signature-params": ("@method" "@target-uri" "content-digest" \
"authorization" "signature";key="old-key" "signature-input"\ "authorization" "signature";key="old-key" "signature-input"\
;key="old-key");created=1618884480;keyid="xyz-2" ;key="old-key");created=1618884480;keyid="xyz-2"
;tag="gnap-rotate" ;tag="gnap-rotate"
]]></artwork></figure> ]]></artwork>
<t>This signature is then added to the message:</t>
<t>This signature is then added to the message:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
POST /token/PRY5NM33 HTTP/1.1 POST /token/PRY5NM33 HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP 4398.34-12-asvDa.a Authorization: GNAP 4398.34-12-asvDa.a
Content-Digest: sha-512=:Fb/A5vnawhuuJ5xk2RjGrbbxr6cvinZqd4+JPY85u/\ Content-Digest: sha-512=:Fb/A5vnawhuuJ5xk2RjGrbbxr6cvinZqd4+JPY85u/\
JNyTlmRmCOtyVhZ1Oz/cSS4tsYen6fzpCwizy6UQxNBQ==: JNyTlmRmCOtyVhZ1Oz/cSS4tsYen6fzpCwizy6UQxNBQ==:
Signature-Input: old-key=("@method" "@target-uri" "content-digest" \ Signature-Input: old-key=("@method" "@target-uri" "content-digest" \
"authorization");created=1618884475;keyid="test-key-ecc-p256"\ "authorization");created=1618884475;keyid="test-key-ecc-p256"\
;tag="gnap", \ ;tag="gnap", \
skipping to change at line 5907 skipping to change at line 5762
"proof": "httpsig", "proof": "httpsig",
"jwk": { "jwk": {
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"kid": "xyz-2", "kid": "xyz-2",
"alg": "RS256", "alg": "RS256",
"n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..."
} }
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The verifier <bcp14>MUST</bcp14> validate both signatures before
<t>The verifier <bcp14>MUST</bcp14> validate both signatures before processing t processing the request for key rotation.</t>
he request for key rotation.</t> </section>
</section>
</section> <section anchor="mtls">
</section> <name>Mutual TLS</name>
<section anchor="mtls"><name>Mutual TLS</name> <t>This method is indicated by the method value <tt>mtls</tt> in strin
g form.</t>
<t>This method is indicated by the method value <spanx style="verb">mtls</spanx> <sourcecode type="json"><![CDATA[
in string form.</t>
<figure><sourcecode type="json"><![CDATA[
{ {
"proof": "mtls" "proof": "mtls"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The signer presents its TLS client certificate during TLS negotiati
<t>The signer presents its TLS client certificate during TLS negotiation with th on with the verifier.</t>
e verifier.</t> <t>In the following non-normative example, the certificate is communic
ated to the application
<t>In the following non-normative example, the certificate is communicated to th
e application
through the Client-Cert header field from a TLS reverse proxy as per <xref targe t="RFC9440"/>, leading through the Client-Cert header field from a TLS reverse proxy as per <xref targe t="RFC9440"/>, leading
to the following full HTTP request message:</t> to the following full HTTP request message:</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /gnap HTTP/1.1 POST /gnap HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/jose Content-Type: application/jose
Content-Length: 1567 Content-Length: 1567
Client-Cert: \ Client-Cert: \
:MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMDYxNDAyBgNVBAMM\ :MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMDYxNDAyBgNVBAMM\
K05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV6QzY2bVEwHhcN\ K05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV6QzY2bVEwHhcN\
MjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQDDCtOSVlNeUJq\ MjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQDDCtOSVlNeUJq\
c0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBIjANBgkqhkiG\ c0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBIjANBgkqhkiG\
9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT0VWtQBsmBB\ 9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT0VWtQBsmBB\
skipping to change at line 5995 skipping to change at line 5844
} }
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://client.foo/" "uri": "https://client.foo/"
}, },
}, },
"subject": { "subject": {
"formats": ["iss_sub", "opaque"] "formats": ["iss_sub", "opaque"]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The verifier compares the TLS client certificate presented during
<t>The verifier compares the TLS client certificate presented during MTLS negotiation to the expected key of the signer. Since the
mutual TLS negotiation to the expected key of the signer. Since the
TLS connection covers the entire message, there are no additional TLS connection covers the entire message, there are no additional
requirements to check.</t> requirements to check.</t>
<t>Note that in many instances, the verifier will not do a full
<t>Note that in many instances, the verifier will not do a full certificate certificate chain validation of the presented TLS client
chain validation of the presented TLS client certificate, as the certificate, as the means of trust for this certificate could be in
means of trust for this certificate could be in something other than something other than a PKI system, such as a static registration or
a PKI system, such as a static registration or trust-on-first-use. trust-on-first-use. See Sections <xref target="security-mtls"
See <xref target="security-mtls"/> and <xref target="security-mtls-patterns"/> f format="counter"/> and <xref target="security-mtls-patterns"
or some additional format="counter"/> for some additional considerations for this key
considerations for this key proofing method.</t> proofing method.</t>
<section anchor="key-rotation-using-mtls">
<section anchor="key-rotation-using-mtls"><name>Key Rotation using MTLS</name> <name>Key Rotation Using MTLS</name>
<t>Since it is not possible to present two client authenticated cert
<t>Since it is not possible to present two client authenticated certificates to ificates to a MTLS
a mutual TLS
connection simultaneously, dynamic key rotation for this proofing method is not defined. connection simultaneously, dynamic key rotation for this proofing method is not defined.
Instead, key rotation for MTLS-based client instances is expected to be managed through Instead, key rotation for MTLS-based client instances is expected to be managed through
deployment practices, as discussed in <xref target="security-mtls-patterns"/>.</ t> deployment practices, as discussed in <xref target="security-mtls-patterns"/>.</ t>
</section>
</section> </section>
</section> <section anchor="detached-jws">
<section anchor="detached-jws"><name>Detached JWS</name> <name>Detached JWS</name>
<t>This method is indicated by the method value <tt>jwsd</tt> in strin
<t>This method is indicated by the method value <spanx style="verb">jwsd</spanx> g form.</t>
in string form.</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"proof": "jwsd" "proof": "jwsd"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The signer creates a JSON Web Signature (JWS) <xref target="RFC7515
<t>The signer creates a JSON Web Signature (JWS) <xref target="RFC7515"/> object "/> object as follows.</t>
as follows:</t> <t>To protect the request, the JOSE header of the signature contains t
he following
<t>To protect the request, the JOSE header of the signature contains the followi
ng
claims:</t> claims:</t>
<dl>
<dt><tt>kid</tt> (string):</dt>
<dd>
<dl> <t>The key identifier. <bcp14>REQUIRED</bcp14> if the key is prese
<dt><spanx style="verb">kid</spanx> (string):</dt> nted in JWK format. This
<dd> <bcp14>MUST</bcp14> be the value of the <tt>kid</tt> field of the key.</t>
<t>The key identifier. <bcp14>REQUIRED</bcp14> if the key is presented in JW </dd>
K format, this <dt><tt>alg</tt> (string):</dt>
<bcp14>MUST</bcp14> be the value of the <spanx style="verb">kid</spanx> field of <dd>
the key.</t> <t>The algorithm used to sign the request. The algorithm <bcp14>MU
</dd> ST</bcp14> be appropriate to the key presented.
<dt><spanx style="verb">alg</spanx> (string):</dt> If the key is presented as a JWK, this <bcp14>MUST</bcp14> be equal to the <tt>a
<dd> lg</tt> parameter of the key. The algorithm <bcp14>MUST NOT</bcp14> be <tt>none<
<t>The algorithm used to sign the request. <bcp14>MUST</bcp14> be appropriat /tt>.
e to the key presented.
If the key is presented as a JWK, this <bcp14>MUST</bcp14> be equal to the <span
x style="verb">alg</spanx> parameter of the key. <bcp14>MUST NOT</bcp14> be <spa
nx style="verb">none</spanx>.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">typ</spanx> (string):</dt> <dt><tt>typ</tt> (string):</dt>
<dd> <dd>
<t>The type header, value "gnap-binding-jwsd". <bcp14>REQUIRED</bcp14>.</t> <t>The type header, value "gnap-binding-jwsd". <bcp14>REQUIRED</bc
</dd> p14>.</t>
<dt><spanx style="verb">htm</spanx> (string):</dt> </dd>
<dd> <dt><tt>htm</tt> (string):</dt>
<t>The HTTP Method used to make this request, as a case-sensitive ASCII stri <dd>
ng. Note that most public HTTP methods are in uppercase ASCII by convention. <bc <t>The HTTP method used to make this request, as a case-sensitive
p14>REQUIRED</bcp14>.</t> ASCII string. Note that most public HTTP methods are in uppercase ASCII by conve
</dd> ntion. <bcp14>REQUIRED</bcp14>.</t>
<dt><spanx style="verb">uri</spanx> (string):</dt> </dd>
<dd> <dt><tt>uri</tt> (string):</dt>
<t>The HTTP URI used for this request. This value <bcp14>MUST</bcp14> be an <dd>
absolute URI, including all path and query components and no fragment component. <t>The HTTP URI used for this request. This value <bcp14>MUST</bcp
<bcp14>REQUIRED</bcp14>.</t> 14> be an absolute URI, including all path and query components and no fragment
</dd> components. <bcp14>REQUIRED</bcp14>.</t>
<dt><spanx style="verb">created</spanx> (integer):</dt> </dd>
<dd> <dt><tt>created</tt> (integer):</dt>
<t>A timestamp of when the signature was created, in integer seconds since U <dd>
NIX Epoch. <bcp14>REQUIRED</bcp14>.</t> <t>A timestamp of when the signature was created, in integer secon
</dd> ds since UNIX Epoch. <bcp14>REQUIRED</bcp14>.</t>
</dl> </dd>
</dl>
<t>When the request is bound to an access token, the JOSE header <bcp14>MUST</bc <t>When the request is bound to an access token, the JOSE header <bcp1
p14> also include the following:</t> 4>MUST</bcp14> also include the following:</t>
<dl>
<dl> <dt><tt>ath</tt> (string):</dt>
<dt><spanx style="verb">ath</spanx> (string):</dt> <dd>
<dd> <t>The hash of the access token. The value <bcp14>MUST</bcp14> be
<t>The hash of the access token. The value <bcp14>MUST</bcp14> be the the
result of Base64url encoding (with no padding) the SHA-256 digest result of base64url encoding (with no padding) the SHA-256 digest
of the ASCII encoding of the associated access token's value. <bcp14>REQUIRED</b cp14>.</t> of the ASCII encoding of the associated access token's value. <bcp14>REQUIRED</b cp14>.</t>
</dd> </dd>
</dl> </dl>
<t>If the HTTP request has content (such as an HTTP POST or PUT method
<t>If the HTTP request has content, such as an HTTP POST or PUT method, ),
the payload of the JWS object is the Base64url encoding (without padding) the payload of the JWS object is the base64url encoding (without padding)
of the SHA256 digest of the bytes of the content. of the SHA-256 digest of the bytes of the content.
If the request being made does not have content, such as If the request being made does not have content (such as
an HTTP GET, OPTIONS, or DELETE method, the JWS signature is an HTTP GET, OPTIONS, or DELETE method), the JWS signature is
calculated over an empty payload.</t> calculated over an empty payload.</t>
<t>The signer presents the signed object in compact form
<t>The signer presents the signed object in compact form <xref target="RFC7515"/> in the Detached-JWS header field.</t>
<xref target="RFC7515"/> in the Detached-JWS HTTP Header field.</t> <t>In the following non-normative example, the JOSE header contains th
e following parameters:</t>
<t>In the following non-normative example, the JOSE Header contains the followin <sourcecode type="json"><![CDATA[
g parameters:</t>
<figure><sourcecode type="json"><![CDATA[
{ {
"alg": "RS256", "alg": "RS256",
"kid": "gnap-rsa", "kid": "gnap-rsa",
"uri": "https://server.example.com/gnap", "uri": "https://server.example.com/gnap",
"htm": "POST", "htm": "POST",
"typ": "gnap-binding-jwsd", "typ": "gnap-binding-jwsd",
"created": 1618884475 "created": 1618884475
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The request content is the following JSON object:</t>
<t>The request content is the following JSON object:</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"access_token": { "access_token": {
"access": [ "access": [
"dolphin-metadata" "dolphin-metadata"
] ]
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
skipping to change at line 6138 skipping to change at line 5974
3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\
N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ"
} }
} }
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://client.foo/" "uri": "https://client.foo/"
}, },
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>This is hashed to the following base64-encoded value:</t>
<t>This is hashed to the following Base64 encoded value:</t> <artwork><![CDATA[
<figure><artwork><![CDATA[
PGiVuOZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc PGiVuOZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc
]]></artwork></figure> ]]></artwork>
<t>This leads to the following full HTTP request message:</t>
<t>This leads to the following full HTTP request message:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
POST /gnap HTTP/1.1 POST /gnap HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Content-Length: 983 Content-Length: 983
Detached-JWS: eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0b\ Detached-JWS: eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0b\
SI6IlBPU1QiLCJraWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3\ SI6IlBPU1QiLCJraWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3\
NkIiwidXJpIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.PGiVuO\ NkIiwidXJpIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.PGiVuO\
ZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc.fUq-SV-A1iFN2MwCRW_yolVtT2_\ ZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc.fUq-SV-A1iFN2MwCRW_yolVtT2_\
skipping to change at line 6201 skipping to change at line 6033
3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\
N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ"
} }
} }
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://client.foo/" "uri": "https://client.foo/"
}, },
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>When the verifier receives the Detached-JWS header, it <bcp14>MUST<
<t>When the verifier receives the Detached-JWS header, it <bcp14>MUST</bcp14> pa /bcp14> parse and
rse and
validate the JWS object. The signature <bcp14>MUST</bcp14> be validated against the validate the JWS object. The signature <bcp14>MUST</bcp14> be validated against the
expected key of the signer. If the HTTP message request contains expected key of the signer. If the HTTP message request contains
content, the verifier <bcp14>MUST</bcp14> calculate the hash of the content just as content, the verifier <bcp14>MUST</bcp14> calculate the hash of the content just as
the signer does, with no normalization or transformation of the request. the signer does, with no normalization or transformation of the request.
All required fields <bcp14>MUST</bcp14> be present All required fields <bcp14>MUST</bcp14> be present,
and their values <bcp14>MUST</bcp14> be valid. All fields <bcp14>MUST</bcp14> ma tch the corresponding portions of the HTTP and their values <bcp14>MUST</bcp14> be valid. All fields <bcp14>MUST</bcp14> ma tch the corresponding portions of the HTTP
message. For example, the <spanx style="verb">htm</spanx> field of the JWS heade message. For example, the <tt>htm</tt> field of the JWS header has to be the sam
r has to be the same as the HTTP verb e as the HTTP verb
used in the request.</t> used in the request.</t>
<t>Note that this proof method depends on a specific cryptographic algorithm, SH
A-256, in two ways:
the <spanx style="verb">ath</spanx> hash algorithm is hardcoded, and computing t
he payload of the detached/attached signature
also uses a hardcoded hash. A future version of this document may address crypto
-agility for both
these uses by replacing ath with a new header that upgrades the algorithm, and p
ossibly defining a
new JWS header that indicates the HTTP content's hash method.</t>
<section anchor="key-rotation-using-detached-jws"><name>Key Rotation using Detac
hed JWS</name>
<t>When rotating a key using Detached JWS, the message, which includes the new p <t>Note that this proofing method depends on a specific cryptographic
ublic key value or algorithm, SHA-256, in two ways: 1) the <tt>ath</tt> hash algorithm
reference, is first signed with the old key as described above using a JWS objec is hardcoded and 2) the payload of the detached/attached signature
t with <spanx style="verb">typ</spanx> header value is computed using a hardcoded hash.
A future version of this
document may address crypto-agility for both these uses by replacing
ath with a new header that upgrades the algorithm and possibly
defining a new JWS header that indicates the HTTP content's hash
method.</t>
<section anchor="key-rotation-using-detached-jws">
<name>Key Rotation Using Detached JWS</name>
<t>When rotating a key using detached JWS, the message, which includ
es the new public key value or
reference, is first signed with the old key as described above using a JWS objec
t with <tt>typ</tt> header value
"gnap-binding-rotation-jwsd". The value of the JWS object is then taken as the p ayload of a new JWS "gnap-binding-rotation-jwsd". The value of the JWS object is then taken as the p ayload of a new JWS
object, to be signed by the new key using the parameters above.</t> object, to be signed by the new key using the parameters above.</t>
<t>The value of the new JWS object is sent in the Detached-JWS heade
<t>The value of the new JWS object is sent in the Detached-JWS header.</t> r.</t>
</section>
</section> </section>
</section> <section anchor="attached-jws">
<section anchor="attached-jws"><name>Attached JWS</name> <name>Attached JWS</name>
<t>This method is indicated by the method value <tt>jws</tt> in string
<t>This method is indicated by the method value <spanx style="verb">jws</spanx> form.</t>
in string form.</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"proof": "jws" "proof": "jws"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The signer creates a JWS <xref target="RFC7515"/> object as follows
<t>The signer creates a JWS <xref target="RFC7515"/> object as follows:</t> .</t>
<t>To protect the request, the JWS header contains the following claim
<t>To protect the request, the JWS header contains the following claims.</t> s:</t>
<dl>
<dl> <dt><tt>kid</tt> (string):</dt>
<dt><spanx style="verb">kid</spanx> (string):</dt> <dd>
<dd> <t>The key identifier. <bcp14>REQUIRED</bcp14> if the key is prese
<t>The key identifier. <bcp14>REQUIRED</bcp14> if the key is presented in JW nted in JWK format. This
K format, this <bcp14>MUST</bcp14> be the value of the <tt>kid</tt> field of the key.</t>
<bcp14>MUST</bcp14> be the value of the <spanx style="verb">kid</spanx> field of </dd>
the key.</t> <dt><tt>alg</tt> (string):</dt>
</dd> <dd>
<dt><spanx style="verb">alg</spanx> (string):</dt> <t>The algorithm used to sign the request. <bcp14>MUST</bcp14> be
<dd> appropriate to the key presented.
<t>The algorithm used to sign the request. <bcp14>MUST</bcp14> be appropriat If the key is presented as a JWK, this <bcp14>MUST</bcp14> be equal to the <tt>a
e to the key presented. lg</tt> parameter of the key. <bcp14>MUST NOT</bcp14> be <tt>none</tt>.
If the key is presented as a JWK, this <bcp14>MUST</bcp14> be equal to the <span
x style="verb">alg</spanx> parameter of the key. <bcp14>MUST NOT</bcp14> be <spa
nx style="verb">none</spanx>.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">typ</spanx> (string):</dt> <dt><tt>typ</tt> (string):</dt>
<dd> <dd>
<t>The type header, value "gnap-binding-jws". <bcp14>REQUIRED</bcp14>.</t> <t>The type header, value "gnap-binding-jws". <bcp14>REQUIRED</bcp
</dd> 14>.</t>
<dt><spanx style="verb">htm</spanx> (string):</dt> </dd>
<dd> <dt><tt>htm</tt> (string):</dt>
<t>The HTTP Method used to make this request, as a case-sensitive ASCII stri <dd>
ng. (Note that most public HTTP methods are in uppercase.) <bcp14>REQUIRED</bcp1 <t>The HTTP method used to make this request, as a case-sensitive
4>.</t> ASCII string. (Note that most public HTTP methods are in uppercase.) <bcp14>REQU
</dd> IRED</bcp14>.</t>
<dt><spanx style="verb">uri</spanx> (string):</dt> </dd>
<dd> <dt><tt>uri</tt> (string):</dt>
<t>The HTTP URI used for this request, including all path and query componen <dd>
ts and no fragment component. <bcp14>REQUIRED</bcp14>.</t> <t>The HTTP URI used for this request, including all path and quer
</dd> y components and no fragment components. <bcp14>REQUIRED</bcp14>.</t>
<dt><spanx style="verb">created</spanx> (integer):</dt> </dd>
<dd> <dt><tt>created</tt> (integer):</dt>
<t>A timestamp of when the signature was created, in integer seconds since U <dd>
NIX Epoch. <bcp14>REQUIRED</bcp14>.</t> <t>A timestamp of when the signature was created, in integer secon
</dd> ds since UNIX Epoch. <bcp14>REQUIRED</bcp14>.</t>
</dl> </dd>
</dl>
<t>When the request is bound to an access token, the JOSE header <bcp14>MUST</bc <t>When the request is bound to an access token, the JOSE header <bcp1
p14> also include the following:</t> 4>MUST</bcp14> also include the following:</t>
<dl>
<dl> <dt><tt>ath</tt> (string):</dt>
<dt><spanx style="verb">ath</spanx> (string):</dt> <dd>
<dd> <t>The hash of the access token. The value <bcp14>MUST</bcp14> be
<t>The hash of the access token. The value <bcp14>MUST</bcp14> be the the
result of Base64url encoding (with no padding) the SHA-256 digest result of base64url encoding (with no padding) the SHA-256 digest
of the ASCII encoding of the associated access token's value. <bcp14>REQUIRED</b cp14>.</t> of the ASCII encoding of the associated access token's value. <bcp14>REQUIRED</b cp14>.</t>
</dd> </dd>
</dl> </dl>
<t>If the HTTP request has content (such as an HTTP POST or PUT method
<t>If the HTTP request has content, such as an HTTP POST or PUT method, ),
the payload of the JWS object is the JSON serialized content of the request, and the payload of the JWS object is the JSON serialized content of the request, and
the object is signed according to JWS and serialized into compact form <xref tar get="RFC7515"/>. the object is signed according to JWS and serialized into compact form <xref tar get="RFC7515"/>.
The signer presents the JWS as the content of the request along with a The signer presents the JWS as the content of the request along with a
content type of <spanx style="verb">application/jose</spanx>. The verifier content type of <tt>application/jose</tt>. The verifier
<bcp14>MUST</bcp14> extract the payload of the JWS and treat it as the request c ontent <bcp14>MUST</bcp14> extract the payload of the JWS and treat it as the request c ontent
for further processing.</t> for further processing.</t>
<t>If the request being made does not have content (such as
<t>If the request being made does not have content, such as an HTTP GET, OPTIONS, or DELETE method), the JWS signature is
an HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated over an empty payload and passed in the <tt>Detached-JWS</tt>
calculated over an empty payload and passed in the <spanx style="verb">Detached-
JWS</spanx>
header as described in <xref target="detached-jws"/>.</t> header as described in <xref target="detached-jws"/>.</t>
<t>In the following non-normative example, the JOSE header contains th
<t>In the following non-normative example, the JOSE header contains the followin e following parameters:</t>
g parameters:</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
{ {
"alg": "RS256", "alg": "RS256",
"kid": "gnap-rsa", "kid": "gnap-rsa",
"uri": "https://server.example.com/gnap", "uri": "https://server.example.com/gnap",
"htm": "POST", "htm": "POST",
"typ": "gnap-binding-jws", "typ": "gnap-binding-jws",
"created": 1618884475 "created": 1618884475
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The request content, used as the JWS Payload, is the following JSON
<t>The request content, used as the JWS Payload, is the following JSON object:</ object:</t>
t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"access_token": { "access_token": {
"access": [ "access": [
"dolphin-metadata" "dolphin-metadata"
] ]
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
skipping to change at line 6356 skipping to change at line 6176
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://client.foo/" "uri": "https://client.foo/"
}, },
}, },
"subject": { "subject": {
"formats": ["iss_sub", "opaque"] "formats": ["iss_sub", "opaque"]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>This leads to the following full HTTP request message:</t>
<t>This leads to the following full HTTP request message:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
POST /gnap HTTP/1.1 POST /gnap HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/jose Content-Type: application/jose
Content-Length: 1047 Content-Length: 1047
eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0bSI6IlBPU1QiLCJ\ eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0bSI6IlBPU1QiLCJ\
raWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3NkIiwidXJpIjoiaH\ raWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3NkIiwidXJpIjoiaH\
R0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.CnsKICAgICJhY2Nlc3NfdG9r\ R0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.CnsKICAgICJhY2Nlc3NfdG9r\
skipping to change at line 6397 skipping to change at line 6215
YjNIYzRJZHFEYU1nOHFIVXlPYnBQaXREUSIKICAgICAgICB9CiAgICAgIH0KICAgICA\ YjNIYzRJZHFEYU1nOHFIVXlPYnBQaXREUSIKICAgICAgICB9CiAgICAgIH0KICAgICA\
gImRpc3BsYXkiOiB7CiAgICAgICAgIm5hbWUiOiAiTXkgQ2xpZW50IERpc3BsYXkgTm\ gImRpc3BsYXkiOiB7CiAgICAgICAgIm5hbWUiOiAiTXkgQ2xpZW50IERpc3BsYXkgTm\
FtZSIsCiAgICAgICAgInVyaSI6ICJodHRwczovL2NsaWVudC5mb28vIgogICAgICB9L\ FtZSIsCiAgICAgICAgInVyaSI6ICJodHRwczovL2NsaWVudC5mb28vIgogICAgICB9L\
AogICAgfSwKICAgICJzdWJqZWN0IjogewogICAgICAgICJmb3JtYXRzIjogWyJpc3Nf\ AogICAgfSwKICAgICJzdWJqZWN0IjogewogICAgICAgICJmb3JtYXRzIjogWyJpc3Nf\
c3ViIiwgIm9wYXF1ZSJdCiAgICB9Cn0K.MwNoVMQp5hVxI0mCs9LlOUdFtkDXaA1_eT\ c3ViIiwgIm9wYXF1ZSJdCiAgICB9Cn0K.MwNoVMQp5hVxI0mCs9LlOUdFtkDXaA1_eT\
vOXq7DOGrtDKH7q4vP2xUq3fH2jRAZqnobo0WdPP3eM3NH5QUjW8pa6_QpwdIWkK7r-\ vOXq7DOGrtDKH7q4vP2xUq3fH2jRAZqnobo0WdPP3eM3NH5QUjW8pa6_QpwdIWkK7r-\
u_52puE0lPBp7J4U2w4l9gIbg8iknsmWmXeY5F6wiGT8ptfuEYGgmloAJd9LIeNvD3U\ u_52puE0lPBp7J4U2w4l9gIbg8iknsmWmXeY5F6wiGT8ptfuEYGgmloAJd9LIeNvD3U\
LW2h2dz1Pn2eDnbyvgB0Ugae0BoZB4f69fKWj8Z9wvTIjk1LZJN1PcL7_zT8Lrlic9a\ LW2h2dz1Pn2eDnbyvgB0Ugae0BoZB4f69fKWj8Z9wvTIjk1LZJN1PcL7_zT8Lrlic9a\
PyzT7Q9ovkd1s-4whE7TrnGUzFc5mgWUn_gsOpsP5mIIljoEEv-FqOW2RyNYulOZl0Q\ PyzT7Q9ovkd1s-4whE7TrnGUzFc5mgWUn_gsOpsP5mIIljoEEv-FqOW2RyNYulOZl0Q\
8EnnDHV_vPzrHlUarbGg4YffgtwkQhdK72-JOxYQ 8EnnDHV_vPzrHlUarbGg4YffgtwkQhdK72-JOxYQ
]]></sourcecode></figure> ]]></sourcecode>
<t>When the verifier receives an attached JWS request, it <bcp14>MUST<
<t>When the verifier receives an attached JWS request, it <bcp14>MUST</bcp14> pa /bcp14> parse and
rse and
validate the JWS object. The signature <bcp14>MUST</bcp14> be validated against the validate the JWS object. The signature <bcp14>MUST</bcp14> be validated against the
expected key of the signer. All required fields <bcp14>MUST</bcp14> be present expected key of the signer. All required fields <bcp14>MUST</bcp14> be present,
and their values <bcp14>MUST</bcp14> be valid. All fields <bcp14>MUST</bcp14> ma tch the corresponding portions of the HTTP and their values <bcp14>MUST</bcp14> be valid. All fields <bcp14>MUST</bcp14> ma tch the corresponding portions of the HTTP
message. For example, the <spanx style="verb">htm</spanx> field of the JWS heade r has to be the same as the HTTP verb message. For example, the <tt>htm</tt> field of the JWS header has to be the sam e as the HTTP verb
used in the request.</t> used in the request.</t>
<t>Note that this proofing method depends on a specific cryptographic
<t>Note that this proof method depends on a specific cryptographic algorithm, SH algorithm, SHA-256, in two ways:
A-256, in two ways: the <tt>ath</tt> hash algorithm is hardcoded, and computing the payload of the d
the <spanx style="verb">ath</spanx> hash algorithm is hardcoded, and computing t etached/attached signature
he payload of the detached/attached signature
also uses a hardcoded hash. A future version of this document may address crypto -agility for both also uses a hardcoded hash. A future version of this document may address crypto -agility for both
these uses by replacing ath with a new header that upgrades the algorithm, and p ossibly defining a these uses by replacing ath with a new header that upgrades the algorithm and po ssibly defining a
new header that indicates the HTTP content's hash method.</t> new header that indicates the HTTP content's hash method.</t>
<section anchor="key-rotation-using-attached-jws">
<section anchor="key-rotation-using-attached-jws"><name>Key Rotation using Attac <name>Key Rotation Using Attached JWS</name>
hed JWS</name> <t>When rotating a key using attached JWS, the message, which includ
es the new public key value or reference, is first signed with the old key using
<t>When rotating a key using Attached JWS, the message, which includes the new p a JWS object with <tt>typ</tt> header value "gnap-binding-rotation-jws". The va
ublic key value or reference, is first signed with the old key using a JWS objec lue of the JWS object is then taken as the payload of a new JWS object, to be si
t with <spanx style="verb">typ</spanx> header value "gnap-binding-rotation-jws". gned by the new key.</t>
The value of the JWS object is then taken as the payload of a new JWS object, t </section>
o be signed by the new key.</t> </section>
</section>
</section> </section>
</section> <section anchor="resource-access-rights">
</section> <name>Resource Access Rights</name>
</section> <t>GNAP provides a rich structure for describing the protected resources
<section anchor="resource-access-rights"><name>Resource Access Rights</name>
<t>GNAP provides a rich structure for describing the protected resources
hosted by RSs and accessed by client software. This structure is used when hosted by RSs and accessed by client software. This structure is used when
the client instance <xref target="request-token">requests an access token</xref> the client instance requests an access token (<xref target="request-token"> </xr
and when ef>) and when
an <xref target="response-token">access token is returned</xref>. GNAP's structu an access token is returned (<xref target="response-token"> </xref>). GNAP's str
re is ucture is
designed to be analogous to the OAuth 2.0 Rich Authorization Request designed to be analogous to the OAuth 2.0 Rich Authorization Requests
data structure defined in <xref target="RFC9396"/>.</t> data structure defined in <xref target="RFC9396"/>.</t>
<t>The root of this structure is a JSON array. The elements of the JSON
<t>The root of this structure is a JSON array. The elements of the JSON
array represent rights of access that are associated with the array represent rights of access that are associated with the
access token. Individual rights of access can be defined by the RS as access token. Individual rights of access can be defined by the RS as
either an object or a string. The resulting access is the union of all elements either an object or a string. The resulting access is the union of all elements
within the array.</t> within the array.</t>
<t>The access associated with the access token is described
<t>The access associated with the access token is described
using objects that each contain multiple using objects that each contain multiple
dimensions of access. Each object contains a <bcp14>REQUIRED</bcp14> <spanx styl e="verb">type</spanx> dimensions of access. Each object contains a <bcp14>REQUIRED</bcp14> <tt>type</t t>
property that determines the type of API that the token is used for and property that determines the type of API that the token is used for and
the structure of the rest of the object. There is no expected the structure of the rest of the object. There is no expected
interoperability between different <spanx style="verb">type</spanx> definitions. interoperability between different <tt>type</tt> definitions.</t>
</t> <dl>
<dt><tt>type</tt> (string):</dt>
<dl> <dd>
<dt><spanx style="verb">type</spanx> (string):</dt> <t>The type of resource request as a string. This field <bcp14>MAY</bc
<dd> p14>
<t>The type of resource request as a string. This field <bcp14>MAY</bcp14>
define which other fields are allowed in the request object. define which other fields are allowed in the request object.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
</dl> </dl>
<t>The value of the <tt>type</tt> field is under the control of the AS.
<t>The value of the <spanx style="verb">type</spanx> field is under the control
of the AS.
This field <bcp14>MUST</bcp14> be compared using an exact byte match of the stri ng This field <bcp14>MUST</bcp14> be compared using an exact byte match of the stri ng
value against known types by the AS. The AS <bcp14>MUST</bcp14> ensure that the re value against known types by the AS. The AS <bcp14>MUST</bcp14> ensure that the re
is no collision between different authorization data types that it is no collision between different authorization data types that it
supports. The AS <bcp14>MUST NOT</bcp14> do any collation or normalization of da ta supports. The AS <bcp14>MUST NOT</bcp14> do any collation or normalization of da ta
types during comparison. It is <bcp14>RECOMMENDED</bcp14> that designers of gene ral-purpose types during comparison. It is <bcp14>RECOMMENDED</bcp14> that designers of gene ral-purpose
APIs use a URI for this field to avoid collisions between multiple APIs use a URI for this field to avoid collisions between multiple
API types protected by a single AS.</t> API types protected by a single AS.</t>
<t>While it is expected that many APIs will have their own properties,
<t>While it is expected that many APIs will have their own properties,
this specification defines a set of common data fields that are designed to be this specification defines a set of common data fields that are designed to be
usable across different types of APIs. This specification does not require the usable across different types of APIs. This specification does not require the
use of these common fields by an API definition but, instead, provides them as use of these common fields by an API definition but, instead, provides them as
reusable generic components for API designers to make use of. The allowable reusable generic components for API designers to make use of. The allowable
values of all fields are determined by the API being protected, as defined values of all fields are determined by the API being protected, as defined
by a particular <spanx style="verb">type</spanx> value.</t> by a particular <tt>type</tt> value.</t>
<dl>
<dl> <dt><tt>actions</tt> (array of strings):</dt>
<dt><spanx style="verb">actions</spanx> (array of strings):</dt> <dd>
<dd> <t>The types of actions the client instance will take at the RS as
<t>The types of actions the client instance will take at the RS as an array an array of strings (for example, a client instance asking for a
of strings. combination of "read" and "write" access).</t>
For example, a client instance asking for a combination of "read" and "write" </dd>
access.</t> <dt><tt>locations</tt> (array of strings):</dt>
</dd> <dd>
<dt><spanx style="verb">locations</spanx> (array of strings):</dt> <t>The location of the RS as an array of
<dd>
<t>The location of the RS as an array of
strings. These strings are typically URIs identifying the strings. These strings are typically URIs identifying the
location of the RS.</t> location of the RS.</t>
</dd> </dd>
<dt><spanx style="verb">datatypes</spanx> (array of strings):</dt> <dt><tt>datatypes</tt> (array of strings):</dt>
<dd> <dd>
<t>The kinds of data available to the client instance at the RS's API as an <t>The kinds of data available to the client instance at the RS's API
array of strings. For example, a client instance asking for access to as an
raw "image" data and "metadata" at a photograph API.</t> array of strings (for example, a client instance asking for access to
</dd> raw "image" data and "metadata" at a photograph API).</t>
<dt><spanx style="verb">identifier</spanx> (string):</dt> </dd>
<dd> <dt><tt>identifier</tt> (string):</dt>
<t>A string identifier indicating a specific resource at the RS. <dd>
For example, a patient identifier for a medical API or <t>A string identifier indicating a specific resource at the RS
a bank account number for a financial API.</t> (for example, a patient identifier for a medical API or
</dd> a bank account number for a financial API).</t>
<dt><spanx style="verb">privileges</spanx> (array of strings):</dt> </dd>
<dd> <dt><tt>privileges</tt> (array of strings):</dt>
<t>The types or levels of privilege being requested at the resource. For exa <dd>
mple, a client <t>The types or levels of privilege being requested at the resource (f
instance asking for administrative level access, or access when the resource o or example, a client
wner instance asking for administrative-level access or access when the RO
is no longer online.</t> is no longer online).</t>
</dd> </dd>
</dl> </dl>
<t>The following non-normative example describes three kinds of access (re
<t>The following non-normative example is describing three kinds of access (read ad, write, and delete) to each of
, write, delete) to each of two different locations and two different data types (metadata and images) for a
two different locations and two different data types (metadata, images) for a si single access token
ngle access token using the fictitious <tt>photo-api</tt> type definition.</t>
using the fictitious <spanx style="verb">photo-api</spanx> type definition.</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "actions": [
"read", "read",
"write", "write",
"delete" "delete"
], ],
"locations": [ "locations": [
"https://server.example.net/", "https://server.example.net/",
"https://resource.local/other" "https://resource.local/other"
], ],
"datatypes": [ "datatypes": [
"metadata", "metadata",
"images" "images"
] ]
} }
] ]
]]></sourcecode></figure> ]]></sourcecode>
<t>While the exact semantics of interpreting the fields of an access
<t>While the exact semantics of interpreting the fields of an access request object are subject to the definition of the <tt>type</tt>,
request object is subject to the definition of the <spanx style="verb">type</spa
nx>,
it is expected that the access requested for each object in the array it is expected that the access requested for each object in the array
is the cross-product of all fields of the object. That is to is the cross-product of all fields of the object. That is to
say, the object represents a request for all <spanx style="verb">actions</spanx> say, the object represents a request for all <tt>actions</tt> listed
listed to be used at all <tt>locations</tt> listed for all possible <tt>datatypes</tt>
to be used at all <spanx style="verb">locations</spanx> listed for all possible
<spanx style="verb">datatypes</spanx>
listed within the object. Assuming the request above was granted, listed within the object. Assuming the request above was granted,
the client instance could assume that it the client instance could assume that it
would be able to do a <spanx style="verb">read</spanx> action against the <spanx would be able to do a <tt>read</tt> action against the <tt>images</tt> on the fi
style="verb">images</spanx> on the first server rst server
as well as a <spanx style="verb">delete</spanx> action on the <spanx style="verb as well as a <tt>delete</tt> action on the <tt>metadata</tt> of the second serve
">metadata</spanx> of the second server, or any other r, or any other
combination of these fields, using the same access token.</t> combination of these fields, using the same access token.</t>
<t>To request a different combination of access,
<t>To request a different combination of access, such as requesting one of the possible <tt>actions</tt> against one of the possi
such as requesting one of the possible <spanx style="verb">actions</spanx> again ble <tt>locations</tt>
st one of the possible <spanx style="verb">locations</spanx> and a different choice of possible <tt>actions</tt> against a different one of t
and a different choice of possible <spanx style="verb">actions</spanx> against a he possible <tt>locations</tt>, the
different one of the possible <spanx style="verb">locations</spanx>, the client instance can include multiple separate objects in the <tt>resources</tt>
client instance can include multiple separate objects in the <spanx style="verb" array.
>resources</spanx> array.
The total access rights for the resulting access The total access rights for the resulting access
token is the union of all objects. The following non-normative example uses the same fictitious <spanx style="verb">photo-api</spanx> token are the union of all objects. The following non-normative example uses the same fictitious <tt>photo-api</tt>
type definition to request a single access token with more specifically type definition to request a single access token with more specifically
targeted access rights by using two discrete objects within the request.</t> targeted access rights by using two discrete objects within the request.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "actions": [
"read" "read"
], ],
"locations": [ "locations": [
"https://server.example.net/" "https://server.example.net/"
], ],
"datatypes": [ "datatypes": [
skipping to change at line 6574 skipping to change at line 6378
"delete" "delete"
], ],
"locations": [ "locations": [
"https://resource.local/other" "https://resource.local/other"
], ],
"datatypes": [ "datatypes": [
"metadata" "metadata"
] ]
} }
] ]
]]></sourcecode></figure> ]]></sourcecode>
<t>The access requested here is for <spanx style="verb">read</spanx> access to <
spanx style="verb">images</spanx> on one server
while simultaneously requesting <spanx style="verb">write</spanx> and <spanx sty
le="verb">delete</spanx> access for <spanx style="verb">metadata</spanx> on a di
fferent
server, but importantly without requesting <spanx style="verb">write</spanx> or
<spanx style="verb">delete</spanx> access to <spanx style="verb">images</spanx>
on the
first server.</t>
<t>It is anticipated that API designers will use a combination <t>The access requested here is for <tt>read</tt> access to <tt>images</tt
> on one server
as well as <tt>write</tt> and <tt>delete</tt> access for <tt>metadata</tt> on a
different
server (importantly, without requesting <tt>write</tt> or <tt>delete</tt> access
to <tt>images</tt> on the
first server).</t>
<t>It is anticipated that API designers will use a combination
of common fields defined in this specification as well as of common fields defined in this specification as well as
fields specific to the API itself. The following non-normative fields specific to the API itself. The following non-normative
example shows the use of both common and API-specific fields as example shows the use of both common and API-specific fields as
part of two different fictitious API <spanx style="verb">type</spanx> values. Th part of two different fictitious API <tt>type</tt> values. The first
e first access request includes the <tt>actions</tt>, <tt>locations</tt>, and <tt>dataty
access request includes the <spanx style="verb">actions</spanx>, <spanx style="v pes</tt>
erb">locations</spanx>, and <spanx style="verb">datatypes</spanx> fields specified here as well as the API-specific <tt>geolocation</tt>
fields specified here as well as the API-specific <spanx style="verb">geolocatio field. The second access request includes the <tt>actions</tt> and
n</spanx> <tt>identifier</tt> fields specified here as well as the API-specific
field. The second access request includes the <spanx style="verb">actions</spanx <tt>currency</tt> field.</t>
> and <sourcecode type="json"><![CDATA[
<spanx style="verb">identifier</spanx> fields specified here as well as the API-
specific
<spanx style="verb">currency</spanx> field.</t>
<figure><sourcecode type="json"><![CDATA[
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "actions": [
"read", "read",
"write" "write"
], ],
"locations": [ "locations": [
"https://server.example.net/", "https://server.example.net/",
"https://resource.local/other" "https://resource.local/other"
skipping to change at line 6622 skipping to change at line 6424
}, },
{ {
"type": "financial-transaction", "type": "financial-transaction",
"actions": [ "actions": [
"withdraw" "withdraw"
], ],
"identifier": "account-14-32-32-3", "identifier": "account-14-32-32-3",
"currency": "USD" "currency": "USD"
} }
] ]
]]></sourcecode></figure> ]]></sourcecode>
<t>If this request is approved,
<t>If this request is approved,
the resulting access token's access rights will be the resulting access token's access rights will be
the union of the requested types of access for each of the two APIs, just as abo ve.</t> the union of the requested types of access for each of the two APIs, just as abo ve.</t>
<section anchor="resource-access-reference">
<section anchor="resource-access-reference"><name>Requesting Resources By Refere <name>Requesting Resources by Reference</name>
nce</name> <t>Instead of sending an object describing the requested resource (<xref
target="resource-access-rights"> </xref>),
<t>Instead of sending an <xref target="resource-access-rights">object describing
the requested resource</xref>,
access rights <bcp14>MAY</bcp14> be communicated as a string known to access rights <bcp14>MAY</bcp14> be communicated as a string known to
the AS representing the access being requested. Just like access rights communic ated the AS representing the access being requested. Just like access rights communic ated
as an object, access rights communicated as reference strings indicate a specifi c as an object, access rights communicated as reference strings indicate a specifi c
access at a protected resource. In the following non-normative example, access at a protected resource. In the following non-normative example,
three distinct resource access rights are being requested.</t> three distinct resource access rights are being requested.</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"access": [ "access": [
"read", "dolphin-metadata", "some other thing" "read", "dolphin-metadata", "some other thing"
] ]
]]></sourcecode></figure> ]]></sourcecode>
<t>This value is opaque to the client instance and <bcp14>MAY</bcp14> be
<t>This value is opaque to the client instance and <bcp14>MAY</bcp14> be any any
valid JSON string, and therefore could include spaces, unicode valid JSON string; therefore, it could include spaces, Unicode
characters, and properly escaped string sequences. However, in some characters, and properly escaped string sequences. However, in some
situations the value is intended to be situations, the value is intended to be
seen and understood by the client software's developer. In such cases, the seen and understood by the client software's developer. In such cases, the
API designer choosing any such human-readable strings <bcp14>SHOULD</bcp14> take steps API designer choosing any such human-readable strings <bcp14>SHOULD</bcp14> take steps
to ensure the string values are not easily confused by a developer, to ensure the string values are not easily confused by a developer,
such as by limiting the strings to easily disambiguated characters.</t> such as by limiting the strings to easily disambiguated characters.</t>
<t>This functionality is similar in practice to OAuth 2.0's <tt>scope</t
<t>This functionality is similar in practice to OAuth 2.0's <spanx style="verb"> t> parameter <xref target="RFC6749"/>, where a single string
scope</spanx> parameter <xref target="RFC6749"/>, where a single string
represents the set of access rights requested by the client instance. As such, t he reference represents the set of access rights requested by the client instance. As such, t he reference
string could contain any valid OAuth 2.0 scope value as in <xref target="example string could contain any valid OAuth 2.0 scope value, as in <xref target="exampl
-oauth2"/>. Note that the reference e-oauth2"/>. Note that the reference
string here is not bound to the same character restrictions as in OAuth 2.0's <s string here is not bound to the same character restrictions as OAuth 2.0's <tt>s
panx style="verb">scope</spanx> definition.</t> cope</tt> definition.</t>
<t>A single <tt>access</tt> array <bcp14>MAY</bcp14> include both object
<t>A single <spanx style="verb">access</spanx> array <bcp14>MAY</bcp14> include -type and
both object-type and
string-type resource items. In this non-normative example, string-type resource items. In this non-normative example,
the client instance is requesting access to a <spanx style="verb">photo-api</spa the client instance is requesting access to a <tt>photo-api</tt> and <tt>financi
nx> and <spanx style="verb">financial-transaction</spanx> API type al-transaction</tt> API type
as well as the reference values of <spanx style="verb">read</spanx>, <spanx styl as well as the reference values of <tt>read</tt>, <tt>dolphin-metadata</tt>, and
e="verb">dolphin-metadata</spanx>, and <spanx style="verb">some other thing</spa <tt>some other thing</tt>.</t>
nx>.</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "actions": [
"read", "read",
"write", "write",
"delete" "delete"
], ],
"locations": [ "locations": [
"https://server.example.net/", "https://server.example.net/",
skipping to change at line 6692 skipping to change at line 6487
{ {
"type": "financial-transaction", "type": "financial-transaction",
"actions": [ "actions": [
"withdraw" "withdraw"
], ],
"identifier": "account-14-32-32-3", "identifier": "account-14-32-32-3",
"currency": "USD" "currency": "USD"
}, },
"some other thing" "some other thing"
] ]
]]></sourcecode></figure> ]]></sourcecode>
<t>The requested access is the union of all elements of the array, inclu
<t>The requested access is the union of all elements of the array, including bot ding both objects and
h objects and
reference strings.</t> reference strings.</t>
<t>In order to facilitate the use of both object and reference strings t
<t>In order to facilitate the use of both object and reference strings to access o access the same
the same
kind of APIs, the API designer can define a clear mapping between these forms. kind of APIs, the API designer can define a clear mapping between these forms.
One possible approach for choosing reference string values is to use the same va lue as the One possible approach for choosing reference string values is to use the same va lue as the
<spanx style="verb">type</spanx> parameter from the fully-specified object, with the API defining a set of default <tt>type</tt> parameter from the fully specified object, with the API defining a set of default
behaviors in this case. For example, an API definition could declare the followi ng string:</t> behaviors in this case. For example, an API definition could declare the followi ng string:</t>
<sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"access": [ "access": [
"photo-api" "photo-api"
] ]
]]></sourcecode></figure> ]]></sourcecode>
<t>As being equivalent to the following fully defined object:</t>
<t>As being equivalent to the following fully-defined object:</t> <sourcecode type="json"><![CDATA[
<figure><sourcecode type="json"><![CDATA[
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "read", "write", "delete" ], "actions": [ "read", "write", "delete" ],
"datatypes": [ "metadata", "image" ] "datatypes": [ "metadata", "image" ]
} }
] ]
]]></sourcecode></figure> ]]></sourcecode>
<t>The exact mechanisms for relating reference strings is up to the API
<t>The exact mechanisms for relating reference strings is up to the API designer designer. These are enforced
. These are enforced
by the AS, and the details are out of scope for this specification.</t> by the AS, and the details are out of scope for this specification.</t>
</section>
</section> </section>
</section> <section anchor="discovery">
<section anchor="discovery"><name>Discovery</name> <name>Discovery</name>
<t>By design, GNAP minimizes the need for any pre-flight
<t>By design, GNAP minimizes the need for any pre-flight
discovery. To begin a request, the client instance only needs to know the grant endpoint of discovery. To begin a request, the client instance only needs to know the grant endpoint of
the AS (a single URI) and which keys it will use to sign the request. Everything else the AS (a single URI) and which keys it will use to sign the request. Everything else
can be negotiated dynamically in the course of the protocol.</t> can be negotiated dynamically in the course of the protocol.</t>
<t>However, the AS can have limits on its allowed functionality. If the
<t>However, the AS can have limits on its allowed functionality. If the
client instance wants to optimize its calls to the AS before making a request, i t <bcp14>MAY</bcp14> client instance wants to optimize its calls to the AS before making a request, i t <bcp14>MAY</bcp14>
send an HTTP OPTIONS request to the grant request endpoint to retrieve the send an HTTP OPTIONS request to the grant request endpoint to retrieve the
server's discovery information. The AS <bcp14>MUST</bcp14> respond with a JSON d ocument with Content-Type server's discovery information. The AS <bcp14>MUST</bcp14> respond with a JSON d ocument with Content-Type
<spanx style="verb">application/json</spanx> containing a single object with the <tt>application/json</tt> containing a single object with the following fields:<
following fields:</t> /t>
<dl>
<dl> <dt><tt>grant_request_endpoint</tt> (string):</dt>
<dt><spanx style="verb">grant_request_endpoint</spanx> (string):</dt> <dd>
<dd> <t>The location of the
<t>The location of the
AS's grant request endpoint. The location <bcp14>MUST</bcp14> be an absolute U RL <xref target="RFC3986"/> AS's grant request endpoint. The location <bcp14>MUST</bcp14> be an absolute U RL <xref target="RFC3986"/>
with a scheme component (which <bcp14>MUST</bcp14> be "https"), a host compone with a scheme component (which <bcp14>MUST</bcp14> be "https"), a host compone
nt, and optionally, nt, and optionally
port, path and query components and no fragment components. This URL <bcp14>MU port, path, and query components and no fragment components. This URL <bcp14>M
ST</bcp14> UST</bcp14>
match the URL the client instance used to make the discovery request. match the URL the client instance used to make the discovery request.
<bcp14>REQUIRED</bcp14>.</t> <bcp14>REQUIRED</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">interaction_start_modes_supported</spanx> (array of st <dt><tt>interaction_start_modes_supported</tt> (array of strings):</dt>
rings):</dt> <dd>
<dd>
<t>A list of the AS's interaction start methods. The values of this list cor <t>A list of the AS's interaction start methods. The values of this list corresp
respond to the ond to the
possible values for the <xref target="request-interact-start">interaction star possible values for the interaction start field of the request (<xref target="
t section</xref> of the request and request-interact-start"> </xref>) and
<bcp14>MUST</bcp14> be values from the <xref target="IANA-interaction-start-mo <bcp14>MUST</bcp14> be values from the "GNAP Interaction Start Modes" registry
des">GNAP Interaction Start Modes Registry</xref>. (<xref target="IANA-interaction-start-modes"> </xref>).
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">interaction_finish_methods_supported</spanx> (array of <dt><tt>interaction_finish_methods_supported</tt> (array of strings):</d
strings):</dt> t>
<dd> <dd>
<t>A list of the AS's interaction finish methods. The values of this list co <t>A list of the AS's interaction finish methods. The values of this l
rrespond to the ist correspond to the
possible values for the method element of the <xref target="request-interact-f possible values for the method element of the interaction finish field of the
inish">interaction finish section</xref> of the request and <bcp14>MUST</bcp14> request (<xref target="request-interact-finish"> </xref>) and <bcp14>MUST</bcp1
be values from 4> be values from
the <xref target="IANA-interaction-finish-methods">GNAP Interaction Finish Met the "GNAP Interaction Finish Methods" registry (<xref target="IANA-interaction
hods Registry</xref>. -finish-methods"> </xref>).
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">key_proofs_supported</spanx> (array of strings):</dt> <dt><tt>key_proofs_supported</tt> (array of strings):</dt>
<dd> <dd>
<t>A list of the AS's supported key <t>A list of the AS's supported key
proofing mechanisms. The values of this list correspond to possible proofing mechanisms. The values of this list correspond to possible
values of the <spanx style="verb">proof</spanx> field of the values of the <tt>proof</tt> field of the
<xref target="key-format">key section</xref> of the request and <bcp14>MUST</b key section of the request (<xref target="key-format"> </xref>) and <bcp14>MUS
cp14> be values from the T</bcp14> be values from the
<xref target="IANA-key-proof-methods">GNAP Key Proofing Methods Registry</xref "GNAP Key Proofing Methods" registry (<xref target="IANA-key-proof-methods"> <
>. /xref>).
<bcp14>OPTIONAL</bcp14>.</t>
</dd>
<dt><spanx style="verb">sub_id_formats_supported</spanx> (array of strings):</
dt>
<dd>
<t>A list of the AS's supported
subject identifier formats. The values of this list correspond to possible val
ues
of the <xref target="request-subject">subject identifier section</xref> of the
request and <bcp14>MUST</bcp14>
be values from the Subject Identifier Formats Registry established by
<xref target="RFC9493"/>.
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">assertion_formats_supported</spanx> (array of strings)
:</dt> <dt><tt>sub_id_formats_supported</tt> (array of strings):</dt>
<dd> <dd>
<t>A list of the AS's supported <t>A list of the AS's supported Subject Identifier formats. The
values of this list correspond to possible values of the Subject
Identifier field of the
request (<xref target="request-subject"> </xref>) and <bcp14>MUST</bcp
14> be values from the "Subject
Identifier Formats" registry <xref
target="Subj-ID-Formats"/>. <bcp14>OPTIONAL</bcp14>.</t>
</dd>
<dt><tt>assertion_formats_supported</tt> (array of strings):</dt>
<dd>
<t>A list of the AS's supported
assertion formats. The values of this list correspond to possible assertion formats. The values of this list correspond to possible
values of the <xref target="request-subject">subject assertion section</xref> values of the subject assertion field of the request (<xref target="request-su
of the request and <bcp14>MUST</bcp14> bject"> </xref>) and <bcp14>MUST</bcp14>
be values from the <xref target="IANA-assertion-formats">GNAP Assertion Format be values from the "GNAP Assertion Formats" registry (<xref target="IANA-asser
s Registry</xref>. tion-formats"> </xref>).
<bcp14>OPTIONAL</bcp14>.</t> <bcp14>OPTIONAL</bcp14>.</t>
</dd> </dd>
<dt><spanx style="verb">key_rotation_supported</spanx> (boolean):</dt> <dt><tt>key_rotation_supported</tt> (boolean):</dt>
<dd> <dd>
<t>The boolean "true" indicates that <xref target="rotate-access-token-key"> <t>The boolean "true" indicates that rotation of access token bound ke
rotation of access token bound keys by the client</xref> is supported by the AS. ys by the client (<xref target="rotate-access-token-key"> </xref>) is supported
by the AS.
The absence of this field or a boolean "false" value indicates that this featu re is not supported.</t> The absence of this field or a boolean "false" value indicates that this featu re is not supported.</t>
</dd> </dd>
</dl> </dl>
<t>The information returned from this method is for optimization
<t>The information returned from this method is for optimization
purposes only. The AS <bcp14>MAY</bcp14> deny any request, or any portion of a r equest, purposes only. The AS <bcp14>MAY</bcp14> deny any request, or any portion of a r equest,
even if it lists a capability as supported. For example, a given client instance even if it lists a capability as supported. For example, if a given client insta
can be registered with the <spanx style="verb">mtls</spanx> key proofing nce
mechanism, but the AS also returns other proofing methods from the discovery doc can be registered with the <tt>mtls</tt> key proofing
ument, then the AS mechanism but the AS also returns other proofing methods from the discovery docu
ment, then the AS
will still deny a request from that client instance using a different proofing will still deny a request from that client instance using a different proofing
mechanism. Similarly, an AS with <spanx style="verb">key_rotation_supported</spa nx> set to "true" can still deny mechanism. Similarly, an AS with <tt>key_rotation_supported</tt> set to "true" c an still deny
any request for rotating any access token's key for a variety of reasons.</t> any request for rotating any access token's key for a variety of reasons.</t>
<t>Additional fields can be defined in the "GNAP Authorization Server Disc
<t>Additional fields can be defined the <xref target="IANA-as-discovery">GNAP Au overy Fields" registry (<xref target="IANA-as-discovery"> </xref>).</t>
thorization Server Discovery Fields Registry</xref>.</t> <section anchor="rs-request-without-token">
<name>RS-First Method of AS Discovery</name>
<section anchor="rs-request-without-token"><name>RS-first Method of AS Discovery <t>If the client instance calls an RS without an access token or with an
</name> invalid access token, the RS <bcp14>SHOULD</bcp14> be explicit about the fact t
hat GNAP needs to be used to access the resource by responding with the WWW-Auth
<t>If the client instance calls an RS without an access token, or with an invali enticate header field and a GNAP challenge.</t>
d access token, the RS <bcp14>SHOULD</bcp14> be explicit about the fact that GNA <t>In some situations, the client instance might want to know with which
P needs to be used to access the resource by responding with the WWW-Authenticat specific AS it needs to negotiate for access to that RS.
e header field and a GNAP challenge.</t>
<t>In some situations, the client instance might want to know with which specifi
c AS it needs to negotiate for access to that RS.
The RS <bcp14>MAY</bcp14> additionally return the following <bcp14>OPTIONAL</bcp 14> parameters:</t> The RS <bcp14>MAY</bcp14> additionally return the following <bcp14>OPTIONAL</bcp 14> parameters:</t>
<dl>
<dl> <dt><tt>as_uri</tt>:</dt>
<dt><spanx style="verb">as_uri</spanx>:</dt> <dd>
<dd> <t>The URI of the grant endpoint of the GNAP AS. Used by the client
<t>The URI of the grant endpoint of the GNAP AS. Used by the client instance instance to call the AS to request an access token.</t>
to call the AS to request an access token.</t> </dd>
</dd> <dt><tt>referrer</tt>:</dt>
<dt><spanx style="verb">referrer</spanx>:</dt> <dd>
<dd> <t>The URI of the GNAP RS. Sent by the client instance in the Refere
<t>The URI of the GNAP RS. Sent by the client instance in the Referer header r header as part of the grant request.</t>
as part of the grant request.</t> </dd>
</dd> <dt><tt>access</tt>:</dt>
<dt><spanx style="verb">access</spanx>:</dt> <dd>
<dd> <t>An opaque access reference as defined in <xref target="resource-a
<t>An opaque access reference as defined in <xref target="resource-access-re ccess-reference"/>.
ference"/>.
<bcp14>MUST</bcp14> be sufficient for at least the action the client instance was attempting to take at the RS and <bcp14>MAY</bcp14> allow additional access rights as well. <bcp14>MUST</bcp14> be sufficient for at least the action the client instance was attempting to take at the RS and <bcp14>MAY</bcp14> allow additional access rights as well.
Sent by the client as an access right in the grant request.</t> Sent by the client as an access right in the grant request.</t>
</dd> </dd>
</dl> </dl>
<t>The client instance <bcp14>SHOULD</bcp14> then use both the <tt>refer
<t>The client instance <bcp14>SHOULD</bcp14> then use both the <spanx style="ver rer</tt> and <tt>access</tt> parameters in its access token request. The client
b">referrer</spanx> and <spanx style="verb">access</spanx> parameters in its acc instance <bcp14>MUST</bcp14> check that the <tt>referrer</tt> parameter is equal
ess token request. The client instance <bcp14>MUST</bcp14> check that the <spanx to the URI of the RS using the simple string comparison method in <xref section
style="verb">referrer</spanx> parameter is equal to the URI of the RS using the ="6.2.1" sectionFormat="of" target="RFC3986"/>.</t>
simple string comparison method in <xref section="6.2.1" sectionFormat="of" tar <t>The means for the RS to determine the value for the <tt>access</tt> r
get="RFC3986"/>.</t> eference are out of scope of this specification, but some dynamic methods are di
scussed in
<t>The means for the RS to determine the value for the <spanx style="verb">acces
s</spanx> reference are out of scope of this specification, but some dynamic met
hods are discussed in
<xref target="I-D.ietf-gnap-resource-servers"/>.</t> <xref target="I-D.ietf-gnap-resource-servers"/>.</t>
<t>When receiving the following response from the RS:</t>
<t>When receiving the following response from the RS:</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
WWW-Authenticate: \ WWW-Authenticate: \
GNAP as_uri=https://as.example/tx\ GNAP as_uri=https://as.example/tx\
;access=FWWIKYBQ6U56NL1\ ;access=FWWIKYBQ6U56NL1\
;referrer=https://rs.example ;referrer=https://rs.example
]]></sourcecode></figure> ]]></sourcecode>
<t>The client instance then makes a request to the <tt>as_uri</tt> as de
<t>The client instance then makes a request to the <spanx style="verb">as_uri</s scribed in <xref target="request"/>, with the value of <tt>referrer</tt> passed
panx> as described in <xref target="request"/>, with the value of <spanx style=" as an HTTP Referer header field and the <tt>access</tt> reference passed unchang
verb">referrer</spanx> passed as an HTTP Referer header field and the <spanx sty ed into the <tt>access</tt> array in the <tt>access_token</tt> portion of the re
le="verb">access</spanx> reference passed unchanged into the <spanx style="verb" quest. The client instance <bcp14>MAY</bcp14> request additional resources and o
>access</spanx> array in the <spanx style="verb">access_token</spanx> portion of ther information.</t>
the request. The client instance <bcp14>MAY</bcp14> request additional resource
s and other information.</t>
<t>In the following non-normative example, the client instance is requesting a s
ingle access token using the opaque access reference <spanx style="verb">FWWIKYB
Q6U56NL1</spanx> received from the RS in addition to the <spanx style="verb">dol
phin-metadata</spanx> that the client instance has been configured with out of b
and.</t>
<figure><sourcecode type="http-message"><![CDATA[ <t>In the following non-normative example, the client instance is request
ing a single access token using the opaque access reference <tt>FWWIKYBQ6U56NL1<
/tt> received from the RS in addition to the <tt>dolphin-metadata</tt> that the
client instance has been configured with out of band.</t>
<sourcecode type="http-message"><![CDATA[
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: as.example Host: as.example
Referer: https://rs.example/resource Referer: https://rs.example/resource
Content-Type: application/json Content-Type: application/json
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
"FWWIKYBQ6U56NL1", "FWWIKYBQ6U56NL1",
"dolphin-metadata" "dolphin-metadata"
] ]
}, },
"client": "KHRS6X63AJ7C7C4AZ9AO" "client": "KHRS6X63AJ7C7C4AZ9AO"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The client instance includes the Referer header field as a way for th
<t>The client instance includes the Referer header field as a way for the AS to e AS to know that the process is initiated through a discovery process at the RS
know that the process is initiated through a discovery process at the RS.</t> .</t>
<t>If issued, the resulting access token would contain sufficient access
<t>If issued, the resulting access token would contain sufficient access to be u to be used at both referenced resources.</t>
sed at both referenced resources.</t> <t>Security considerations, especially related to the potential of a com
promised RS (<xref target="security-compromised-rs"> </xref>) redirecting the re
<t>Security considerations, especially related to the potential of a <xref targe quests of an otherwise properly authenticated client, need to be carefully consi
t="security-compromised-rs">compromised RS</xref> redirecting the requests of an dered when allowing such a discovery process. This risk can be mitigated by an a
otherwise properly authenticated client, need to be carefully considered when a lternative pre-registration process so that the client knows which AS protects w
llowing such a discovery process. This risk can be mitigated by an alternative p hich RS. There are also privacy considerations related to revealing which AS is
re-registration process so that the client knows which AS protects which RS. The protecting a given resource; these are discussed in <xref target="privacy-correl
re are also privacy considerations related to revealing which AS is protecting a ation-client"/>.</t>
given resource, discussed in <xref target="privacy-correlation-client"/>.</t> </section>
<section anchor="grant-discovery">
</section> <name>Dynamic Grant Endpoint Discovery</name>
<section anchor="grant-discovery"><name>Dynamic grant endpoint discovery</name>
<t>Additional methods of discovering the appropriate grant endpoint for a given application <t>Additional methods of discovering the appropriate grant endpoint for a given application
are outside the scope of this specification. This limitation is intentional, as many applications are outside the scope of this specification. This limitation is intentional, as many applications
rely on static configuration between the client instance and AS, as is common in OAuth 2.0. rely on static configuration between the client instance and AS, as is common in OAuth 2.0.
However, the dynamic nature of GNAP makes it a prime candidate for other extensi ons defining methods However, the dynamic nature of GNAP makes it a prime candidate for other extensi ons defining methods
for discovery of the appropriate AS grant endpoint at runtime. Advanced use case s could define for discovery of the appropriate AS grant endpoint at runtime. Advanced use case s could define
contextual methods for contextually providing this endpoint to the client insta nce securely. contextual methods for securely providing this endpoint to the client instance.
Furthermore, GNAP's design intentionally requires the client instance to only kn ow the grant Furthermore, GNAP's design intentionally requires the client instance to only kn ow the grant
endpoint and not additional parameters, since other functions and values can be disclosed endpoint and not additional parameters, since other functions and values can be disclosed
and negotiated during the grant process.</t> and negotiated during the grant process.</t>
</section>
</section>
<section anchor="IANA">
<name>IANA Considerations</name>
</section> <t>IANA has added values to existing registries as well as created 16 regi
</section> stries for GNAP <xref target="GNAP-REG"/> and populated those registries with in
<section anchor="Acknowledgements"><name>Acknowledgements</name> itial values as described in this section.</t>
<t>All use of value typing is based on data types in <xref target="RFC8259
<t>The editors would like to thank the feedback of the following individuals for "/> and <bcp14>MUST</bcp14> be one of the following: number, object, string, boo
their reviews, lean, or array. When the type is array, the contents of the array <bcp14>MUST</b
implementations, and contributions: cp14> be specified, as in "array of objects" when one subtype is allowed or "arr
<contact fullname="Åke Axeland" asciiFullname="Ake Axeland"/>, ay of strings/objects" when multiple simultaneous subtypes are allowed. When the
Aaron Parecki, type is object, the structure of the object <bcp14>MUST</bcp14> be specified in
Adam Omar Oueidat, the definition. If a parameter is available in different types, each type <bcp1
Andrii Deinega, 4>SHOULD</bcp14> be registered separately.</t>
Annabelle Backman, <t>General guidance for extension parameters is found in <xref target="ext
Dick Hardt, ensions"/>.</t>
Dmitri Zagidulin, <section anchor="http-authentication-scheme-registration">
Dmitry Barinov, <name>HTTP Authentication Scheme Registration</name>
Fabien Imbault, <t>IANA has registered of the following scheme in the
Florian Helmschmidt, "HTTP Authentication Schemes" registry <xref target="Auth-Schemes"/> defined in
Francis Pouatcha, <xref section="18.5" sectionFormat="of" target="RFC9110"/>:</t>
George Fletcher, <dl>
Haardik Haardik, <dt>Authentication Scheme Name:</dt><dd>GNAP</dd>
Hamid Massaoud, <dt>Reference:</dt><dd><xref target="use-access-token"/> of RFC 9635
Jacky Yuan, </dd>
Joseph Heenan, </dl>
Justin Richer, </section>
Kathleen Moriarty, <section anchor="media-type-registration">
Leif Johansson, <name>Media Type Registration</name>
Mike Jones,
Mike Varley,
Nat Sakimura,
Takahiko Kawasaki,
Takahiro Tsuchiya,
Yaron Sheffer.</t>
<t>The editors would also like to thank the GNAP working group design team of
Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, and Justin Richer, wh
o incorporated
elements from the XAuth and XYZ proposals to create the first version of this do
cument.</t>
<t>In addition, the editors would like to thank Aaron Parecki and Mike Jones for
insights into how
to integrate identity and authentication systems into the core protocol, and Jus
tin Richer and Dick Hardt for
the use cases, diagrams, and insights provided in the XYZ and XAuth proposals th
at have been
incorporated here. The editors would like to especially thank Mike Varley and th
e team at SecureKey
for feedback and development of early versions of the XYZ protocol that fed into
this standards work.</t>
<t>Finally, the editors want to acknowledge the immense contributions of Aaron P <t>Per this section, IANA has registered the following media types <xref
arecki to the content target="RFC2046"/> in
of this document. We thank him for his insight, input, and hard work, without wh the "Media Types" registry <xref target="MediaTypes"/> as described
ich GNAP would in <xref target="RFC6838"/>.</t>
not have grown to what it is.</t>
</section> <section anchor="media-type-reg1">
<section anchor="IANA"><name>IANA Considerations</name> <name>application/gnap-binding-jwsd</name>
<t>This media type indicates that the content is a GNAP message to be bound with
a detached JWS mechanism.</t>
<dl spacing="normal">
<dt>Type name:</dt><dd>application</dd>
<t>IANA is requested to add values to existing registries and to create 16 regis tries for the Grant Negotiation and Authorization Protocol and to populate those registries with initial values as described in this section.</t> <dt>Subtype name:</dt><dd>gnap-binding-jwsd</dd>
<t>All use of value typing is based on <xref target="RFC8259"/> data types and < bcp14>MUST</bcp14> be one of the following: number, object, string, boolean, or array. When the type is array, the contents of the array <bcp14>MUST</bcp14> be specified, as in "array of objects" when one subtype is allowed or "array of str ings/objects" when multiple simultaneous subtypes are allowed. When the type is object, the structure of the object <bcp14>MUST</bcp14> be specified in the defi nition. If a parameter is available in different types, each type <bcp14>SHOULD< /bcp14> be registered separately.</t> <dt>Required parameters:</dt><dd>N/A</dd>
<t>General guidance for extension parameters is found in <xref target="extension s"/>.</t> <dt>Optional parameters:</dt><dd>N/A</dd>
<section anchor="http-authentication-scheme-registration"><name>HTTP Authenticat ion Scheme Registration</name> <dt>Encoding considerations:</dt><dd>binary</dd>
<t>This specification requests registration of the following scheme in the <dt>Security considerations:</dt><dd>See <xref target="security"/> of
"Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry" defined be < RFC 9635.</dd>
xref section="18.5" sectionFormat="of" target="HTTP"/>:</t>
<t><list style="symbols"> <dt>Interoperability considerations:</dt><dd>N/A</dd>
<t>Authentication Scheme Name: <spanx style="verb">GNAP</spanx></t>
<t>Reference: <xref target="use-access-token"/> of &SELF;</t>
</list></t>
</section> <dt>Published specification:</dt><dd>RFC 9635</dd>
<section anchor="media-type-registration"><name>Media Type Registration</name>
<t>This section requests registration of the following media types <xref target= <dt>Applications that use this media type:</dt><dd>GNAP</dd>
"RFC2046"/> in
the "Media Types" registry <xref target="IANA.MediaTypes"/> in the manner descri
bed
in <xref target="RFC6838"/>.</t>
<t>To indicate that the content is a GNAP message to be bound with a detached JW S mechanism:</t> <dt>Fragment identifier considerations:</dt><dd>N/A</dd>
<t><list style="symbols"> <dt>Additional information:</dt><dd>
<t>Type name: application</t> <t><br/></t>
<t>Subtype name: gnap-binding-jwsd</t>
<t>Required parameters: n/a</t>
<t>Optional parameters: n/a</t>
<t>Encoding considerations: binary</t>
<t>Security considerations: See <xref target="security"/> of &SELF;</t>
<t>Interoperability considerations: n/a</t>
<t>Published specification: &SELF;</t>
<t>Applications that use this media type: GNAP</t>
<t>Fragment identifier considerations: n/a</t>
<t>Additional information:
<list style="symbols">
<t>Magic number(s): n/a</t>
<t>File extension(s): n/a</t>
<t>Macintosh file type code(s): n/a</t>
</list></t>
<t>Person &amp; email address to contact for further information: IETF GNAP Wo
rking Group, txauth@ietf.org</t>
<t>Intended usage: COMMON</t>
<t>Restrictions on usage: none</t>
<t>Author: IETF GNAP Working Group, txauth@ietf.org</t>
<t>Change Controller: IETF</t>
<t>Provisional registration? No</t>
</list></t>
<t>To indicate that the content is a GNAP message to be bound with an attached J <dl spacing="compact">
WS mechanism:</t> <dt>Deprecated alias names for this type:</dt><dd>N/A</dd>
<dt>Magic number(s):</dt><dd>N/A</dd>
<t><list style="symbols"> <dt>File extension(s):</dt><dd>N/A</dd>
<t>Type name: application</t>
<t>Subtype name: gnap-binding-jws</t>
<t>Required parameters: n/a</t>
<t>Optional parameters: n/a</t>
<t>Encoding considerations: binary</t>
<t>Security considerations: See <xref target="security"/> of &SELF;</t>
<t>Interoperability considerations: n/a</t>
<t>Published specification: &SELF;</t>
<t>Applications that use this media type: GNAP</t>
<t>Fragment identifier considerations: n/a</t>
<t>Additional information:
<list style="symbols">
<t>Magic number(s): n/a</t>
<t>File extension(s): n/a</t>
<t>Macintosh file type code(s): n/a</t>
</list></t>
<t>Person &amp; email address to contact for further information: IETF GNAP Wo
rking Group, txauth@ietf.org</t>
<t>Intended usage: COMMON</t>
<t>Restrictions on usage: none</t>
<t>Author: IETF GNAP Working Group, txauth@ietf.org</t>
<t>Change Controller: IETF</t>
<t>Provisional registration? No</t>
</list></t>
<t>To indicate that the content is a GNAP token rotation message to be bound wit <dt>Macintosh file type code(s):</dt><dd>N/A</dd>
h a detached JWS mechanism:</t> </dl>
</dd>
<t><list style="symbols"> <dt>Person &amp; email address to contact for further information:</dt><dd>IETF
<t>Type name: application</t> GNAP Working Group (txauth@ietf.org)</dd>
<t>Subtype name: gnap-binding-rotation-jwsd</t>
<t>Required parameters: n/a</t>
<t>Optional parameters: n/a</t>
<t>Encoding considerations: binary</t>
<t>Security considerations: See <xref target="security"/> of &SELF;</t>
<t>Interoperability considerations: n/a</t>
<t>Published specification: &SELF;</t>
<t>Applications that use this media type: GNAP</t>
<t>Fragment identifier considerations: n/a</t>
<t>Additional information:
<list style="symbols">
<t>Magic number(s): n/a</t>
<t>File extension(s): n/a</t>
<t>Macintosh file type code(s): n/a</t>
</list></t>
<t>Person &amp; email address to contact for further information: IETF GNAP Wo
rking Group, txauth@ietf.org</t>
<t>Intended usage: COMMON</t>
<t>Restrictions on usage: none</t>
<t>Author: IETF GNAP Working Group, txauth@ietf.org</t>
<t>Change Controller: IETF</t>
<t>Provisional registration? No</t>
</list></t>
<t>To indicate that the content is a GNAP token rotation message to be bound wit h an attached JWS mechanism:</t> <dt>Intended usage:</dt><dd>COMMON</dd>
<t><list style="symbols"> <dt>Restrictions on usage:</dt><dd>none</dd>
<t>Type name: application</t>
<t>Subtype name: gnap-binding-rotation-jws</t>
<t>Required parameters: n/a</t>
<t>Optional parameters: n/a</t>
<t>Encoding considerations: binary</t>
<t>Security considerations: See <xref target="security"/> of &SELF;</t>
<t>Interoperability considerations: n/a</t>
<t>Published specification: &SELF;</t>
<t>Applications that use this media type: GNAP</t>
<t>Fragment identifier considerations: n/a</t>
<t>Additional information:
<list style="symbols">
<t>Magic number(s): n/a</t>
<t>File extension(s): n/a</t>
<t>Macintosh file type code(s): n/a</t>
</list></t>
<t>Person &amp; email address to contact for further information: IETF GNAP Wo
rking Group, txauth@ietf.org</t>
<t>Intended usage: COMMON</t>
<t>Restrictions on usage: none</t>
<t>Author: IETF GNAP Working Group, txauth@ietf.org</t>
<t>Change Controller: IETF</t>
<t>Provisional registration? No</t>
</list></t>
</section> <dt>Author:</dt><dd>IETF GNAP Working Group (txauth@ietf.org)</dd>
<section anchor="IANA-grant-request"><name>GNAP Grant Request Parameters</name>
<t>This document defines a GNAP grant request, for which IANA is asked to create and maintain a new registry titled "GNAP Grant Request Parameters". Initial val ues for this registry are given in <xref target="IANA-grant-request-contents"/>. Future assignments and modifications to existing assignment are to be made thro ugh the Specification Required registration policy <xref target="RFC8126"/>.</t> <dt>Change Controller:</dt><dd>IETF</dd>
<t>The Designated Expert (DE) is expected to ensure that all registrations follo </dl>
w the template presented in <xref target="IANA-grant-request-template"/>. </section>
The DE is expected to ensure that the request parameter's definition is sufficie
ntly orthogonal to existing functionality provided by existing parameters.
The DE is expected to ensure that registrations for the same name with different
types are sufficiently close in functionality so as not to cause confusion for
developers.
The DE is expected to ensure that the request parameter's definition specifies t
he expected behavior of the AS in response to the request parameter for each pot
ential state of the grant request.</t>
<section anchor="IANA-grant-request-template"><name>Registration Template</name> <section anchor="media-type-reg2">
<name>application/gnap-binding-jws</name>
<t>This media type indicates that the content is a GNAP message to be bo
und with an attached JWS mechanism.</t>
<dl newline="true"> <dl spacing="normal">
<dt>Name:</dt> <dt>Type name:</dt><dd>application</dd>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Specification document(s):</dt>
<dd>
<t>Reference to the document(s) that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section> <dt>Subtype name:</dt><dd>gnap-binding-jws</dd>
<section anchor="IANA-grant-request-contents"><name>Initial Contents</name>
<texttable> <dt>Required parameters:</dt><dd>N/A</dd>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Type</ttcol>
<ttcol align='left'>Specification document(s)</ttcol>
<c>access_token</c>
<c>object</c>
<c><xref target="request-token-single"/> of &SELF;</c>
<c>access_token</c>
<c>array of objects</c>
<c><xref target="request-token-multiple"/> of &SELF;</c>
<c>subject</c>
<c>object</c>
<c><xref target="request-subject"/> of &SELF;</c>
<c>client</c>
<c>object</c>
<c><xref target="request-client"/> of &SELF;</c>
<c>client</c>
<c>string</c>
<c><xref target="request-instance"/> of &SELF;</c>
<c>user</c>
<c>object</c>
<c><xref target="request-user"/> of &SELF;</c>
<c>user</c>
<c>string</c>
<c><xref target="request-user-reference"/> of &SELF;</c>
<c>interact</c>
<c>object</c>
<c><xref target="request-interact"/> of &SELF;</c>
<c>interact_ref</c>
<c>string</c>
<c><xref target="continue-after-interaction"/> of &SELF;</c>
</texttable>
</section> <dt>Optional parameters:</dt><dd>N/A</dd>
</section>
<section anchor="IANA-token-flags"><name>GNAP Access Token Flags</name>
<t>This document defines a GNAP access token flags, for which IANA is asked to c reate and maintain a new registry titled "GNAP Access Token Flags". Initial valu es for this registry are given in <xref target="IANA-token-flags-contents"/>. Fu ture assignments and modifications to existing assignment are to be made through the Specification Required registration policy <xref target="RFC8126"/>.</t> <dt>Encoding considerations:</dt><dd>binary</dd>
<t>The DE is expected to ensure that all registrations follow the template prese <dt>Security considerations:</dt><dd>See <xref target="security"/> o
nted in <xref target="IANA-token-flags-template"/>. f RFC 9635.</dd>
The DE is expected to ensure that the flag specifies whether it applies to reque
sts for tokens to the AS, responses with tokens from the AS, or both.</t>
<section anchor="IANA-token-flags-template"><name>Registration Template</name> <dt>Interoperability considerations:</dt><dd>N/A</dd>
<dl newline="true"> <dt>Published specification:</dt><dd>RFC 9635</dd>
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Allowed Use:</dt>
<dd>
<t>Where the flag is allowed to occur. Possible values are
"Request", "Response", and "Request, Response".</t>
</dd>
<dt>Specification document(s):</dt>
<dd>
<t>Reference to the document(s) that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section> <dt>Applications that use this media type:</dt><dd>GNAP</dd>
<section anchor="IANA-token-flags-contents"><name>Initial Contents</name>
<texttable> <dt>Fragment identifier considerations:</dt><dd>N/A</dd>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Allowed Use</ttcol>
<ttcol align='left'>Specification document(s)</ttcol>
<c>bearer</c>
<c>Request, Response</c>
<c><xref target="request-token-single"/> and <xref target="response-token-
single"/> of &SELF;</c>
<c>durable</c>
<c>Response</c>
<c><xref target="response-token-single"/> of &SELF;</c>
</texttable>
</section> <dt>Additional information:</dt><dd>
</section>
<section anchor="IANA-subject-request"><name>GNAP Subject Information Request Fi
elds</name>
<t>This document defines a means to request subject information from the AS to t <t><br/></t>
he client instance, for which IANA is asked to create and maintain a new registr <dl spacing="compact">
y titled "GNAP Subject Information Request Fields". Initial values for this regi <dt>Deprecated alias names for this type:</dt><dd>N/A</dd>
stry are given in <xref target="IANA-subject-request-contents"/>. Future assignm
ents and modifications to existing assignment are to be made through the Specifi
cation Required registration policy <xref target="RFC8126"/>.</t>
<t>The DE is expected to ensure that all registrations follow the template prese <dt>Magic number(s):</dt><dd>N/A</dd>
nted in <xref target="IANA-subject-request-template"/>.
The DE is expected to ensure that registrations for the same name with different
types are sufficiently close in functionality so as not to cause confusion for
developers.</t>
<section anchor="IANA-subject-request-template"><name>Registration Template</nam e> <dt>File extension(s):</dt><dd>N/A</dd>
<dl newline="true"> <dt>Macintosh file type code(s):</dt><dd>N/A</dd>
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Specification document(s):</dt>
<dd>
<t>Reference to the document(s) that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl> </dl>
</dd>
</section> <dt>Person &amp; email address to contact for further information:</
<section anchor="IANA-subject-request-contents"><name>Initial Contents</name> dt><dd>IETF GNAP Working Group (txauth@ietf.org)</dd>
<texttable> <dt>Intended usage:</dt><dd>COMMON</dd>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Type</ttcol>
<ttcol align='left'>Specification document(s)</ttcol>
<c>sub_id_formats</c>
<c>array of strings</c>
<c><xref target="request-subject"/> of &SELF;</c>
<c>assertion_formats</c>
<c>array of strings</c>
<c><xref target="request-subject"/> of &SELF;</c>
<c>sub_ids</c>
<c>array of objects</c>
<c><xref target="request-subject"/> of &SELF;</c>
</texttable>
</section> <dt>Restrictions on usage:</dt><dd>none</dd>
</section>
<section anchor="IANA-assertion-formats"><name>GNAP Assertion Formats</name>
<t>This document defines a means to pass identity assertions between the AS and client instance, for which IANA is asked to create and maintain a new registry t itled "GNAP Assertion Formats". Initial values for this registry are given in <x ref target="IANA-assertion-formats-contents"/>. Future assignments and modificat ions to existing assignment are to be made through the Specification Required re gistration policy <xref target="RFC8126"/>.</t> <dt>Author:</dt><dd>IETF GNAP Working Group (txauth@ietf.org)</dd>
<t>The DE is expected to ensure that all registrations follow the template prese <dt>Change Controller:</dt><dd>IETF</dd>
nted in <xref target="IANA-assertion-formats-template"/>.
The DE is expected to ensure that the definition specifies the serialization for
mat of the assertion value as used within GNAP.</t>
<section anchor="IANA-assertion-formats-template"><name>Registration Template</n </dl>
ame> </section>
<section anchor="media-type-reg3">
<name>application/gnap-binding-rotation-jwsd</name>
<t>This media type indicates that the content is a GNAP token rotation m
essage to be bound with a detached JWS mechanism.</t>
<dl spacing="normal">
<dl newline="true"> <dt>Type name:</dt><dd>application</dd>
<dt>Name:</dt>
<dd>
<t>An identifier for the assertion format.</t>
</dd>
<dt>Specification document(s):</dt>
<dd>
<t>Reference to the document(s) that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section> <dt>Subtype name:</dt><dd>gnap-binding-rotation-jwsd</dd>
<section anchor="IANA-assertion-formats-contents"><name>Initial Contents</name>
<texttable> <dt>Required parameters:</dt><dd>N/A</dd>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Specification document(s)</ttcol>
<c>id_token</c>
<c><xref target="assertion-formats"/> of &SELF;</c>
<c>saml2</c>
<c><xref target="assertion-formats"/> of &SELF;</c>
</texttable>
</section> <dt>Optional parameters:</dt><dd>N/A</dd>
</section>
<section anchor="IANA-client-instance"><name>GNAP Client Instance Fields</name>
<t>This document defines a means to send information about the client instance, for which IANA is asked to create and maintain a new registry titled "GNAP Clien t Instance Fields". Initial values for this registry are given in <xref target=" IANA-client-instance-contents"/>. Future assignments and modifications to existi ng assignment are to be made through the Specification Required registration pol icy <xref target="RFC8126"/>.</t> <dt>Encoding considerations:</dt><dd>binary</dd>
<t>The DE is expected to ensure that all registrations follow the template prese <dt>Security considerations:</dt><dd>See <xref target="security"/> o
nted in <xref target="IANA-client-instance-template"/>. f RFC 9635.</dd>
The DE is expected to ensure that registrations for the same name with different
types are sufficiently close in functionality so as not to cause confusion for
developers.</t>
<section anchor="IANA-client-instance-template"><name>Registration Template</nam e> <dt>Interoperability considerations:</dt><dd>N/A</dd>
<dl newline="true"> <dt>Published specification:</dt><dd>RFC 9635</dd>
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Specification document(s):</dt>
<dd>
<t>Reference to the document(s) that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section> <dt>Applications that use this media type:</dt><dd>GNAP</dd>
<section anchor="IANA-client-instance-contents"><name>Initial Contents</name>
<texttable> <dt>Fragment identifier considerations:</dt><dd>N/A</dd>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Type</ttcol>
<ttcol align='left'>Specification document(s)</ttcol>
<c>key</c>
<c>object</c>
<c><xref target="key-format"/> of &SELF;</c>
<c>key</c>
<c>string</c>
<c><xref target="key-reference"/> of &SELF;</c>
<c>class_id</c>
<c>string</c>
<c><xref target="request-client"/> of &SELF;</c>
<c>display</c>
<c>object</c>
<c><xref target="request-display"/> of &SELF;</c>
</texttable>
</section> <dt>Additional information:</dt><dd>
</section> <t><br/></t>
<section anchor="IANA-client-instance-display"><name>GNAP Client Instance Displa
y Fields</name>
<t>This document defines a means to send end-user facing displayable information <dl spacing="compact">
about the client instance, for which IANA is asked to create and maintain a new <dt>Deprecated alias names for this type:</dt><dd>N/A</dd>
registry titled "GNAP Client Instance Display Fields". Initial values for this
registry are given in <xref target="IANA-client-instance-display-contents"/>. Fu
ture assignments and modifications to existing assignment are to be made through
the Specification Required registration policy <xref target="RFC8126"/>.</t>
<t>The DE is expected to ensure that all registrations follow the template prese <dt>Magic number(s):</dt><dd>N/A</dd>
nted in <xref target="IANA-client-instance-display-template"/>.
The DE is expected to ensure that registrations for the same name with different
types are sufficiently close in functionality so as not to cause confusion for
developers.</t>
<section anchor="IANA-client-instance-display-template"><name>Registration Templ ate</name> <dt>File extension(s):</dt><dd>N/A</dd>
<dl newline="true"> <dt>Macintosh file type code(s):</dt><dd>N/A</dd>
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Specification document(s):</dt>
<dd>
<t>Reference to the document(s) that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl> </dl>
</dd>
</section> <dt>Person &amp; email address to contact for further information:</
<section anchor="IANA-client-instance-display-contents"><name>Initial Contents</ dt><dd>IETF GNAP Working Group (txauth@ietf.org)</dd>
name>
<texttable> <dt>Intended usage:</dt><dd>COMMON</dd>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Type</ttcol>
<ttcol align='left'>Specification document(s)</ttcol>
<c>name</c>
<c>string</c>
<c><xref target="request-display"/> of &SELF;</c>
<c>uri</c>
<c>string</c>
<c><xref target="request-display"/> of &SELF;</c>
<c>logo_uri</c>
<c>string</c>
<c><xref target="request-display"/> of &SELF;</c>
</texttable>
</section> <dt>Restrictions on usage:</dt><dd>none</dd>
</section>
<section anchor="IANA-interaction-start-modes"><name>GNAP Interaction Start Mode
s</name>
<t>This document defines a means for the client instance to begin interaction be tween the end-user and the AS, for which IANA is asked to create and maintain a new registry titled "GNAP Interaction Start Modes". Initial values for this regi stry are given in <xref target="IANA-interaction-start-modes-contents"/>. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy <xref target="RFC8126"/>.</t> <dt>Author:</dt><dd>IETF GNAP Working Group (txauth@ietf.org)</dd>
<t>The DE is expected to ensure that all registrations follow the template prese <dt>Change Controller:</dt><dd>IETF</dd>
nted in <xref target="IANA-interaction-start-modes-template"/>. </dl>
The DE is expected to ensure that registrations for the same name with different
types are sufficiently close in functionality so as not to cause confusion for
developers.
The DE is expected to ensure that any registration using an "object" type declar
es all additional parameters, their optionality, and purpose.
The DE is expected to ensure that the start mode clearly defines what actions th
e client is expected to take to begin interaction, what the expected user experi
ence is, and any security considerations for this communication from either part
y.
The DE is expected to ensure that the start mode documents incompatibilities wit
h other start modes or finish methods, if applicable.
The DE is expected to ensure that the start mode provides enough information to
uniquely identify the grant request during the interaction. For example, tn the
<spanx style="verb">redirect</spanx> and <spanx style="verb">app</spanx> modes,
this is done using a unique URI (including its parameters). In the <spanx style=
"verb">user_code</spanx> and <spanx style="verb">user_code_uri</spanx> mode, thi
s is done using the value of the user code.</t>
<section anchor="IANA-interaction-start-modes-template"><name>Registration Templ </section>
ate</name> <section anchor="media-type-reg4">
<name>application/gnap-binding-rotation-jws</name>
<t>This media type indicates that the content is a GNAP token rotation m
essage to be bound with an attached JWS mechanism.</t>
<dl spacing="normal">
<dl newline="true"> <dt>Type name:</dt><dd>application</dd>
<dt>Mode:</dt>
<dd>
<t>An identifier for the interaction start mode.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type for the value, either "string" or "object", as described in
<xref target="request-interact-start"/>.</t>
</dd>
<dt>Specification document(s):</dt>
<dd>
<t>Reference to the document(s) that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section> <dt>Subtype name:</dt><dd>gnap-binding-rotation-jws</dd>
<section anchor="IANA-interaction-start-modes-contents"><name>Initial Contents</
name>
<texttable> <dt>Required parameters:</dt><dd>N/A</dd>
<ttcol align='left'>Mode</ttcol>
<ttcol align='left'>Type</ttcol>
<ttcol align='left'>Specification document(s)</ttcol>
<c>redirect</c>
<c>string</c>
<c><xref target="request-interact-redirect"/> of &SELF;</c>
<c>app</c>
<c>string</c>
<c><xref target="request-interact-app"/> of &SELF;</c>
<c>user_code</c>
<c>string</c>
<c><xref target="request-interact-usercode"/> of &SELF;</c>
<c>user_code_uri</c>
<c>string</c>
<c><xref target="request-interact-usercodeuri"/> of &SELF;</c>
</texttable>
</section> <dt>Optional parameters:</dt><dd>N/A</dd>
</section>
<section anchor="IANA-interaction-finish-methods"><name>GNAP Interaction Finish
Methods</name>
<t>This document defines a means for the client instance to be notified of the e nd of interaction between the end-user and the AS, for which IANA is asked to cr eate and maintain a new registry titled "GNAP Interaction Finish Methods". Initi al values for this registry are given in <xref target="IANA-interaction-finish-m ethods-contents"/>. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy <xref targ et="RFC8126"/>.</t> <dt>Encoding considerations:</dt><dd>binary</dd>
<t>The DE is expected to ensure that all registrations follow the template prese <dt>Security considerations:</dt><dd>See <xref target="security"/> o
nted in <xref target="IANA-interaction-finish-methods-template"/>. f RFC 9635.</dd>
The DE is expected to ensure that all finish methods clearly define what actions
the AS is expected to take, what listening methods the client instance needs to
enable, and any security considerations for this communication from either part
y.
The DE is expected to ensure that all finish methods document incompatibilities
with any start modes, if applicable.</t>
<section anchor="IANA-interaction-finish-methods-template"><name>Registration Te mplate</name> <dt>Interoperability considerations:</dt><dd>N/A</dd>
<dl newline="true"> <dt>Published specification:</dt><dd>RFC 9635</dd>
<dt>Method:</dt>
<dd>
<t>An identifier for the interaction finish method.</t>
</dd>
<dt>Specification document(s):</dt>
<dd>
<t>Reference to the document(s) that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section> <dt>Applications that use this media type:</dt><dd>GNAP</dd>
<section anchor="IANA-interaction-finish-methods-contents"><name>Initial Content
s</name>
<texttable> <dt>Fragment identifier considerations:</dt><dd>N/A</dd>
<ttcol align='left'>Mode</ttcol>
<ttcol align='left'>Specification document(s)</ttcol>
<c>redirect</c>
<c><xref target="request-interact-callback-redirect"/> of &SELF;</c>
<c>push</c>
<c><xref target="request-interact-callback-push"/> of &SELF;</c>
</texttable>
</section> <dt>Additional information:</dt><dd>
</section> <t><br/></t>
<section anchor="IANA-interaction-hints"><name>GNAP Interaction Hints</name>
<t>This document defines a set of hints that a client instance can provide to th <dl spacing="compact">
e AS to facilitate interaction with the end user, for which IANA is asked to cre <dt>Deprecated alias names for this type:</dt><dd>N/A</dd>
ate and maintain a new registry titled "GNAP Interaction Hints". Initial values
for this registry are given in <xref target="IANA-interaction-hints-contents"/>.
Future assignments and modifications to existing assignment are to be made thro
ugh the Specification Required registration policy <xref target="RFC8126"/>.</t>
<t>The DE is expected to ensure that all registrations follow the template prese <dt>Magic number(s):</dt><dd>N/A</dd>
nted in <xref target="IANA-interaction-hints-template"/>.
The DE is expected to ensure that all interaction hints clearly document the exp
ected behaviors of the AS in response to the hint, and that an AS not processing
the hint does not impede the operation of the AS or client instance.</t>
<section anchor="IANA-interaction-hints-template"><name>Registration Template</n ame> <dt>File extension(s):</dt><dd>N/A</dd>
<dl newline="true"> <dt>Macintosh file type code(s):</dt><dd>N/A</dd>
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Specification document(s):</dt>
<dd>
<t>Reference to the document(s) that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl> </dl>
</dd>
</section> <dt>Person &amp; email address to contact for further information:</
<section anchor="IANA-interaction-hints-contents"><name>Initial Contents</name> dt><dd>IETF GNAP Working Group (txauth@ietf.org)</dd>
<texttable> <dt>Intended usage:</dt><dd>COMMON</dd>
<ttcol align='left'>Mode</ttcol>
<ttcol align='left'>Specification document(s)</ttcol>
<c>ui_locales</c>
<c><xref target="request-interact-hint"/> of &SELF;</c>
</texttable>
</section> <dt>Restrictions on usage:</dt><dd>none</dd>
</section>
<section anchor="IANA-grant-response"><name>GNAP Grant Response Parameters</name
>
<t>This document defines a GNAP grant response, for which IANA is asked to creat e and maintain a new registry titled "GNAP Grant Response Parameters". Initial v alues for this registry are given in <xref target="IANA-grant-response-contents" />. Future assignments and modifications to existing assignment are to be made t hrough the Specification Required registration policy <xref target="RFC8126"/>.< /t> <dt>Author:</dt><dd>IETF GNAP Working Group (txauth@ietf.org)</dd>
<t>The DE is expected to ensure that all registrations follow the template prese <dt>Change Controller:</dt><dd>IETF</dd>
nted in <xref target="IANA-grant-response-template"/>. </dl>
The DE is expected to ensure that the response parameter's definition is suffici </section>
ently orthogonal to existing functionality provided by existing parameters. </section>
The DE is expected to ensure that registrations for the same name with different <section anchor="IANA-grant-request">
types are sufficiently close in functionality so as not to cause confusion for <name>GNAP Grant Request Parameters</name>
developers. <t>This document defines a GNAP grant request, for which IANA has create
The DE is expected to ensure that the response parameter's definition specifies d and maintains a new registry titled "GNAP Grant Request Parameters". Initial v
grant states for which the client instance can expect this parameter to appear i alues for this registry are given in <xref target="IANA-grant-request-contents"/
n a response message.</t> >. Future assignments and modifications to existing assignments are to be made t
hrough the Specification Required registration policy <xref target="RFC8126"/>.<
/t>
<section anchor="IANA-grant-response-template"><name>Registration Template</name > <t>The designated expert (DE) is expected to ensure the following:</t>
<dl newline="true"> <ul spacing="normal">
<dt>Name:</dt> <li>All registrations follow the template presented in <xref target="IANA-grant-
<dd> request-template"/>.</li>
<t>An identifier for the parameter.</t> <li>The request parameter's definition is sufficiently orthogonal to existing fu
</dd> nctionality provided by existing parameters.</li>
<dt>Type:</dt> <li>Registrations for the same name with different types are sufficiently close
<dd> in functionality so as not to cause confusion for developers.</li>
<t>The JSON type allowed for the value.</t> <li>The request parameter's definition specifies the expected behavior of the AS
</dd> in response to the request parameter for each potential state of the grant requ
<dt>Specification document(s):</dt> est.</li>
<dd> </ul>
<t>Reference to the document(s) that specify the <section anchor="IANA-grant-request-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t> relevant sections may also be included but is not required.</t>
</dd> </dd>
</dl> </dl>
</section>
</section> <section anchor="IANA-grant-request-contents">
<section anchor="IANA-grant-response-contents"><name>Initial Contents</name> <name>Initial Contents</name>
<table>
<texttable> <thead>
<ttcol align='left'>Name</ttcol> <tr>
<ttcol align='left'>Type</ttcol> <th align="left">Name</th>
<ttcol align='left'>Specification document(s)</ttcol> <th align="left">Type</th>
<c>continue</c> <th align="left">Reference</th>
<c>object</c> </tr>
<c><xref target="response-continue"/> of &SELF;</c> </thead>
<c>acces_token</c> <tbody>
<c>object</c> <tr>
<c><xref target="response-token-single"/> of &SELF;</c> <td align="left">access_token</td>
<c>acces_token</c> <td align="left">object</td>
<c>array of objects</c> <td align="left">
<c><xref target="response-token-multiple"/> of &SELF;</c> <xref target="request-token-single"/> of RFC 9635</td>
<c>interact</c> </tr>
<c>object</c> <tr>
<c><xref target="response-interact"/> of &SELF;</c> <td align="left">access_token</td>
<c>subject</c> <td align="left">array of objects</td>
<c>object</c> <td align="left">
<c><xref target="response-subject"/> of &SELF;</c> <xref target="request-token-multiple"/> of RFC 9635</td>
<c>instance_id</c> </tr>
<c>string</c> <tr>
<c><xref target="response-dynamic-handles"/> of &SELF;</c> <td align="left">subject</td>
<c>error</c> <td align="left">object</td>
<c>object</c> <td align="left">
<c><xref target="response-error"/> of &SELF;</c> <xref target="request-subject"/> of RFC 9635</td>
</texttable> </tr>
<tr>
</section> <td align="left">client</td>
</section> <td align="left">object</td>
<section anchor="IANA-interaction-response"><name>GNAP Interaction Mode Response <td align="left">
s</name> <xref target="request-client"/> of RFC 9635</td>
</tr>
<t>This document defines a means for the AS to provide to the client instance in <tr>
formation that is required to complete a particular interaction mode, for which <td align="left">client</td>
IANA is asked to create and maintain a new registry titled "GNAP Interaction Mod <td align="left">string</td>
e Responses". Initial values for this registry are given in <xref target="IANA-i <td align="left">
nteraction-response-contents"/>. Future assignments and modifications to existin <xref target="request-instance"/> of RFC 9635</td>
g assignment are to be made through the Specification Required registration poli </tr>
cy <xref target="RFC8126"/>.</t> <tr>
<td align="left">user</td>
<t>The DE is expected to ensure that all registrations follow the template prese <td align="left">object</td>
nted in <xref target="IANA-interaction-response-template"/>. <td align="left">
If the name of the registration matches the name of an interaction start mode, t <xref target="request-user"/> of RFC 9635</td>
he DE is expected to ensure that the response parameter is unambiguously associa </tr>
ted with the interaction start mode of the same name.</t> <tr>
<td align="left">user</td>
<section anchor="IANA-interaction-response-template"><name>Registration Template <td align="left">string</td>
</name> <td align="left">
<xref target="request-user-reference"/> of RFC 9635</td>
<dl newline="true"> </tr>
<dt>Name:</dt> <tr>
<dd> <td align="left">interact</td>
<t>An identifier for the parameter.</t> <td align="left">object</td>
</dd> <td align="left">
<dt>Specification document(s):</dt> <xref target="request-interact"/> of RFC 9635</td>
<dd> </tr>
<t>Reference to the document(s) that specify the <tr>
<td align="left">interact_ref</td>
<td align="left">string</td>
<td align="left">
<xref target="continue-after-interaction"/> of RFC 9635</td>
</tr>
</tbody>
</table>
</section>
</section>
<section anchor="IANA-token-flags">
<name>GNAP Access Token Flags</name>
<t>This document defines GNAP access token flags, for which IANA has cre
ated and maintains a new registry titled "GNAP Access Token Flags". Initial valu
es for this registry are given in <xref target="IANA-token-flags-contents"/>. Fu
ture assignments and modifications to existing assignments are to be made throug
h the Specification Required registration policy <xref target="RFC8126"/>.</t>
<t>The DE is expected to ensure the following:</t>
<ul spacing="normal">
<li>All registrations follow the template presented in <xref target="IANA
-token-flags-template"/>.</li>
<li>The flag specifies whether it applies to requests for tokens to the A
S, responses with tokens from the AS, or both.</li>
</ul>
<section anchor="IANA-token-flags-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Allowed Use:</dt>
<dd>
<t>Where the flag is allowed to occur. Possible values are
"Request", "Response", and "Request, Response".</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t> relevant sections may also be included but is not required.</t>
</dd> </dd>
</dl> </dl>
</section>
</section> <section anchor="IANA-token-flags-contents">
<section anchor="IANA-interaction-response-contents"><name>Initial Contents</nam <name>Initial Contents</name>
e> <table>
<thead>
<texttable> <tr>
<ttcol align='left'>Name</ttcol> <th align="left">Name</th>
<ttcol align='left'>Specification document(s)</ttcol> <th align="left">Allowed Use</th>
<c>redirect</c> <th align="left">Reference</th>
<c><xref target="response-interact"/> of &SELF;</c> </tr>
<c>app</c> </thead>
<c><xref target="response-interact"/> of &SELF;</c> <tbody>
<c>user_code</c> <tr>
<c><xref target="response-interact"/> of &SELF;</c> <td align="left">bearer</td>
<c>user_code_uri</c> <td align="left">Request, Response</td>
<c><xref target="response-interact"/> of &SELF;</c> <td align="left">
<c>finish</c> Sections <xref target="request-token-single"
<c><xref target="response-interact"/> of &SELF;</c> format="counter"/> and <xref target="response-token-single"
<c>expires_in</c> format="counter"/> of RFC 9635</td>
<c><xref target="response-interact"/> of &SELF;</c> </tr>
</texttable> <tr>
<td align="left">durable</td>
</section> <td align="left">Response</td>
</section> <td align="left">
<section anchor="IANA-subject-response"><name>GNAP Subject Information Response <xref target="response-token-single"/> of RFC 9635</td>
Fields</name> </tr>
</tbody>
<t>This document defines a means to return subject information from the AS to th </table>
e client instance, for which IANA is asked to create and maintain a new registry </section>
titled "GNAP Subject Information Response Fields". Initial values for this regi </section>
stry are given in <xref target="IANA-subject-response-contents"/>. Future assign <section anchor="IANA-subject-request">
ments and modifications to existing assignment are to be made through the Specif <name>GNAP Subject Information Request Fields</name>
ication Required registration policy <xref target="RFC8126"/>.</t> <t>This document defines a means to request subject information from the
AS to the client instance, for which IANA has created and maintains a new regis
<t>The DE is expected to ensure that all registrations follow the template prese try titled "GNAP Subject Information Request Fields". Initial values for this re
nted in <xref target="IANA-subject-response-template"/>. gistry are given in <xref target="IANA-subject-request-contents"/>. Future assig
The DE is expected to ensure that registrations for the same name with different nments and modifications to existing assignments are to be made through the Spec
types are sufficiently close in functionality so as not to cause confusion for ification Required registration policy <xref target="RFC8126"/>.</t>
developers.</t>
<section anchor="IANA-subject-response-template"><name>Registration Template</na
me>
<dl newline="true"> <t>The DE is expected to ensure the following:</t>
<dt>Name:</dt> <ul spacing="normal">
<dd> <li>All registrations follow the template presented in <xref target="IANA
<t>An identifier for the parameter.</t> -subject-request-template"/>.</li>
</dd> <li>Registrations for the same name with different types are sufficiently
<dt>Type:</dt> close in functionality so as not to cause confusion for developers.</li>
<dd> </ul>
<t>The JSON type allowed for the value.</t> <section anchor="IANA-subject-request-template">
</dd> <name>Registration Template</name>
<dt>Specification document(s):</dt> <dl newline="true">
<dd> <dt>Name:</dt>
<t>Reference to the document(s) that specify the <dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t> relevant sections may also be included but is not required.</t>
</dd> </dd>
</dl> </dl>
</section>
</section> <section anchor="IANA-subject-request-contents">
<section anchor="IANA-subject-response-contents"><name>Initial Contents</name> <name>Initial Contents</name>
<table>
<texttable> <thead>
<ttcol align='left'>Name</ttcol> <tr>
<ttcol align='left'>Type</ttcol> <th align="left">Name</th>
<ttcol align='left'>Specification document(s)</ttcol> <th align="left">Type</th>
<c>sub_ids</c> <th align="left">Reference</th>
<c>array of objects</c> </tr>
<c><xref target="response-subject"/> of &SELF;</c> </thead>
<c>assertions</c> <tbody>
<c>array of objects</c> <tr>
<c><xref target="response-subject"/> of &SELF;</c> <td align="left">sub_id_formats</td>
<c>updated_at</c> <td align="left">array of strings</td>
<c>string</c> <td align="left">
<c><xref target="response-subject"/> of &SELF;</c> <xref target="request-subject"/> of RFC 9635</td>
</texttable> </tr>
<tr>
</section> <td align="left">assertion_formats</td>
</section> <td align="left">array of strings</td>
<section anchor="IANA-error-code"><name>GNAP Error Codes</name> <td align="left">
<xref target="request-subject"/> of RFC 9635</td>
<t>This document defines a set of errors that the AS can return to the client in </tr>
stance, for which IANA is asked to create and maintain a new registry titled "GN <tr>
AP Error Codes". Initial values for this registry are given in <xref target="IAN <td align="left">sub_ids</td>
A-error-code-contents"/>. Future assignments and modifications to existing assig <td align="left">array of objects</td>
nment are to be made through the Specification Required registration policy <xre <td align="left">
f target="RFC8126"/>.</t> <xref target="request-subject"/> of RFC 9635</td>
</tr>
<t>The DE is expected to ensure that all registrations follow the template prese </tbody>
nted in <xref target="IANA-error-code-template"/>. </table>
The DE is expected to ensure that the error response is sufficiently unique from </section>
other errors to provide actionable information to the client instance. </section>
The DE is expected to ensure that the definition of the error response specifies <section anchor="IANA-assertion-formats">
all conditions in which the error response is returned, and what the client ins <name>GNAP Assertion Formats</name>
tance's expected action is.</t> <t>This document defines a means to pass identity assertions between the
AS and client instance, for which IANA has created and maintains a new registry
<section anchor="IANA-error-code-template"><name>Registration Template</name> titled "GNAP Assertion Formats". Initial values for this registry are given in
<xref target="IANA-assertion-formats-contents"/>. Future assignments and modific
<dl newline="true"> ations to existing assignments are to be made through the Specification Required
<dt>Error:</dt> registration policy <xref target="RFC8126"/>.</t>
<dd> <t>The DE is expected to ensure the following:</t>
<t>A unique string code for the error.</t> <ul spacing="normal">
</dd> <li>All registrations follow the template presented in <xref target="IANA
<dt>Specification document(s):</dt> -assertion-formats-template"/>.</li>
<dd> <li>The definition specifies the serialization format of the assertion va
<t>Reference to the document(s) that specify the lue as used within GNAP.</li>
</ul>
<section anchor="IANA-assertion-formats-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Name:</dt>
<dd>
<t>An identifier for the assertion format.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t> relevant sections may also be included but is not required.</t>
</dd> </dd>
</dl> </dl>
</section>
</section> <section anchor="IANA-assertion-formats-contents">
<section anchor="IANA-error-code-contents"><name>Initial Contents</name> <name>Initial Contents</name>
<table>
<texttable> <thead>
<ttcol align='left'>Error</ttcol> <tr>
<ttcol align='left'>Specification document(s)</ttcol> <th align="left">Name</th>
<c>invalid_request</c> <th align="left">Reference</th>
<c><xref target="response-error"/> of &SELF;</c> </tr>
<c>invalid_client</c> </thead>
<c><xref target="response-error"/> of &SELF;</c> <tbody>
<c>invalid_interaction</c> <tr>
<c><xref target="response-error"/> of &SELF;</c> <td align="left">id_token</td>
<c>invalid_flag</c> <td align="left">
<c><xref target="response-error"/> of &SELF;</c> <xref target="assertion-formats"/> of RFC 9635</td>
<c>invalid_rotation</c> </tr>
<c><xref target="response-error"/> of &SELF;</c> <tr>
<c>key_rotation_not_supported</c> <td align="left">saml2</td>
<c><xref target="response-error"/> of &SELF;</c> <td align="left">
<c>invalid_continuation</c> <xref target="assertion-formats"/> of RFC 9635</td>
<c><xref target="response-error"/> of &SELF;</c> </tr>
<c>user_denied</c> </tbody>
<c><xref target="response-error"/> of &SELF;</c> </table>
<c>request_denied</c> </section>
<c><xref target="response-error"/> of &SELF;</c> </section>
<c>unknown_interaction</c> <section anchor="IANA-client-instance">
<c><xref target="response-error"/> of &SELF;</c> <name>GNAP Client Instance Fields</name>
<c>too_fast</c> <t>This document defines a means to send information about the client in
<c><xref target="response-error"/> of &SELF;</c> stance, for which IANA has created and maintains a new registry titled "GNAP Cli
<c>too_many_attempts</c> ent Instance Fields". Initial values for this registry are given in <xref target
<c><xref target="response-error"/> of &SELF;</c> ="IANA-client-instance-contents"/>. Future assignments and modifications to exis
</texttable> ting assignments are to be made through the Specification Required registration
policy <xref target="RFC8126"/>.</t>
</section> <t>The DE is expected to ensure the following:</t>
</section> <ul spacing="normal">
<section anchor="IANA-key-proof-methods"><name>GNAP Key Proofing Methods</name> <li>All registrations follow the template presented in <xref target="IANA
-client-instance-template"/>.</li>
<t>This document defines methods that the client instance can use to prove posse <li>Registrations for the same name with different types are sufficiently
ssion of a key, for which IANA is asked to create and maintain a new registry ti close in functionality so as not to cause confusion for developers.</li>
tled "GNAP Key Proofing Methods". Initial values for this registry are given in </ul>
<xref target="IANA-key-proof-methods-contents"/>. Future assignments and modific <section anchor="IANA-client-instance-template">
ations to existing assignment are to be made through the Specification Required <name>Registration Template</name>
registration policy <xref target="RFC8126"/>.</t> <dl newline="true">
<dt>Name:</dt>
<t>The DE is expected to ensure that all registrations follow the template prese <dd>
nted in <xref target="IANA-key-proof-methods-template"/>. <t>An identifier for the parameter.</t>
The DE is expected to ensure that registrations for the same name with different </dd>
types are sufficiently close in functionality so as not to cause confusion for <dt>Type:</dt>
developers. <dd>
The DE is expected to ensure that the proofing method provides sufficient covera <t>The JSON type allowed for the value.</t>
ge of and binding to the protocol messages to which it is applied. </dd>
The DE is expected to ensure that the proofing method definition clearly enumera <dt>Reference:</dt>
tes how all requirements in <xref target="binding-keys"/> are fulfilled by the d <dd>
efinition.</t> <t>Reference to one or more documents that specify the
<section anchor="IANA-key-proof-methods-template"><name>Registration Template</n
ame>
<dl newline="true">
<dt>Method:</dt>
<dd>
<t>A unique string code for the key proofing method.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Specification document(s):</dt>
<dd>
<t>Reference to the document(s) that specify the
value, preferably including a URI that can be used value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t> relevant sections may also be included but is not required.</t>
</dd> </dd>
</dl> </dl>
</section>
</section> <section anchor="IANA-client-instance-contents">
<section anchor="IANA-key-proof-methods-contents"><name>Initial Contents</name> <name>Initial Contents</name>
<table>
<texttable> <thead>
<ttcol align='left'>Method</ttcol> <tr>
<ttcol align='left'>Type</ttcol> <th align="left">Name</th>
<ttcol align='left'>Specification document(s)</ttcol> <th align="left">Type</th>
<c>httpsig</c> <th align="left">Reference</th>
<c>string</c> </tr>
<c><xref target="httpsig-binding"/> of &SELF;</c> </thead>
<c>httpsig</c> <tbody>
<c>object</c> <tr>
<c><xref target="httpsig-binding"/> of &SELF;</c> <td align="left">key</td>
<c>mtls</c> <td align="left">object</td>
<c>string</c> <td align="left">
<c><xref target="mtls"/> of &SELF;</c> <xref target="key-format"/> of RFC 9635</td>
<c>jwsd</c> </tr>
<c>string</c> <tr>
<c><xref target="detached-jws"/> of &SELF;</c> <td align="left">key</td>
<c>jws</c> <td align="left">string</td>
<c>string</c> <td align="left">
<c><xref target="attached-jws"/> of &SELF;</c> <xref target="key-reference"/> of RFC 9635</td>
</texttable> </tr>
<tr>
</section> <td align="left">class_id</td>
</section> <td align="left">string</td>
<section anchor="IANA-key-formats"><name>GNAP Key Formats</name> <td align="left">
<xref target="request-client"/> of RFC 9635</td>
<t>This document defines formats for a public key value, for which IANA is asked </tr>
to create and maintain a new registry titled "GNAP Key Formats". Initial values <tr>
for this registry are given in <xref target="IANA-key-formats-contents"/>. Futu <td align="left">display</td>
re assignments and modifications to existing assignment are to be made through t <td align="left">object</td>
he Specification Required registration policy <xref target="RFC8126"/>.</t> <td align="left">
<xref target="request-display"/> of RFC 9635</td>
<t>The DE is expected to ensure that all registrations follow the template prese </tr>
nted in <xref target="IANA-key-formats-template"/>. </tbody>
The DE is expected to ensure the key format specifies the structure and serializ </table>
ation of the key material.</t> </section>
</section>
<section anchor="IANA-key-formats-template"><name>Registration Template</name> <section anchor="IANA-client-instance-display">
<name>GNAP Client Instance Display Fields</name>
<dl newline="true"> <t>This document defines a means to send end-user-facing displayable inf
<dt>Format:</dt> ormation about the client instance, for which IANA has created and maintains a n
<dd> ew registry titled "GNAP Client Instance Display Fields". Initial values for thi
<t>A unique string code for the key format.</t> s registry are given in <xref target="IANA-client-instance-display-contents"/>.
</dd> Future assignments and modifications to existing assignments are to be made thro
<dt>Specification document(s):</dt> ugh the Specification Required registration policy <xref target="RFC8126"/>.</t>
<dd> <t>The DE is expected to ensure the following:</t>
<t>Reference to the document(s) that specify the <ul spacing="normal">
<li>All registrations follow the template presented in <xref target="IANA
-client-instance-display-template"/>.</li>
<li>Registrations for the same name with different types are sufficiently
close in functionality so as not to cause confusion for developers.</li>
</ul>
<section anchor="IANA-client-instance-display-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t> relevant sections may also be included but is not required.</t>
</dd> </dd>
</dl> </dl>
</section>
</section> <section anchor="IANA-client-instance-display-contents">
<section anchor="IANA-key-formats-contents"><name>Initial Contents</name> <name>Initial Contents</name>
<table>
<texttable> <thead>
<ttcol align='left'>Format</ttcol> <tr>
<ttcol align='left'>Specification document(s)</ttcol> <th align="left">Name</th>
<c>jwk</c> <th align="left">Type</th>
<c><xref target="key-format"/> of &SELF;</c> <th align="left">Reference</th>
<c>cert</c> </tr>
<c><xref target="key-format"/> of &SELF;</c> </thead>
<c>cert#S256</c> <tbody>
<c><xref target="key-format"/> of &SELF;</c> <tr>
</texttable> <td align="left">name</td>
<td align="left">string</td>
</section> <td align="left">
</section> <xref target="request-display"/> of RFC 9635</td>
<section anchor="IANA-as-discovery"><name>GNAP Authorization Server Discovery Fi </tr>
elds</name> <tr>
<td align="left">uri</td>
<t>This document defines a discovery document for an AS, for which IANA is asked <td align="left">string</td>
to create and maintain a new registry titled "GNAP Authorization Server Discove <td align="left">
ry Fields". Initial values for this registry are given in <xref target="IANA-as- <xref target="request-display"/> of RFC 9635</td>
discovery-contents"/>. Future assignments and modifications to existing assignme </tr>
nt are to be made through the Specification Required registration policy <xref t <tr>
arget="RFC8126"/>.</t> <td align="left">logo_uri</td>
<td align="left">string</td>
<t>The DE is expected to ensure that all registrations follow the template prese <td align="left">
nted in <xref target="IANA-as-discovery-template"/>. <xref target="request-display"/> of RFC 9635</td>
The DE is expected to ensure that registrations for the same name with different </tr>
types are sufficiently close in functionality so as not to cause confusion for </tbody>
developers. </table>
The DE is expected to ensure that the values in the discovery document are suffi </section>
cient to provide optimization and hints to the client instance, but that knowled </section>
ge of the discovered value is not required for starting a transaction with the A <section anchor="IANA-interaction-start-modes">
S.</t> <name>GNAP Interaction Start Modes</name>
<t>This document defines a means for the client instance to begin intera
<section anchor="IANA-as-discovery-template"><name>Registration Template</name> ction between the end user and the AS, for which IANA has created and maintains
a new registry titled "GNAP Interaction Start Modes". Initial values for this re
<dl newline="true"> gistry are given in <xref target="IANA-interaction-start-modes-contents"/>. Futu
<dt>Name:</dt> re assignments and modifications to existing assignments are to be made through
<dd> the Specification Required registration policy <xref target="RFC8126"/>.</t>
<t>An identifier for the parameter.</t> <t>The DE is expected to ensure the following:</t>
</dd> <ul spacing="normal">
<dt>Type:</dt> <li>All registrations follow the template presented in <xref target="IANA
<dd> -interaction-start-modes-template"/>.</li>
<t>The JSON type allowed for the value.</t> <li>Registrations for the same name with different types are sufficiently close
</dd> in functionality so as not to cause confusion for developers.</li>
<dt>Specification document(s):</dt> <li>Any registration using an "object" type declares all additional parameters,
<dd> their optionality, and their purpose.</li>
<t>Reference to the document(s) that specify the <li>The start mode clearly defines what actions the client is expected to take t
o begin interaction, what the expected user experience is, and any security cons
iderations for this communication from either party.</li>
<li>The start mode documents incompatibilities with other start modes or finish
methods, if applicable.</li>
<li>The start mode provides enough information to uniquely identify the grant re
quest during the interaction. For example, in the <tt>redirect</tt> and <tt>app<
/tt> modes, this is done using a unique URI (including its parameters). In the <
tt>user_code</tt> and <tt>user_code_uri</tt> modes, this is done using the value
of the user code.</li>
</ul>
<section anchor="IANA-interaction-start-modes-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Mode:</dt>
<dd>
<t>An identifier for the interaction start mode.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type for the value, either "string" or "object", as de
scribed in <xref target="request-interact-start"/>.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t> relevant sections may also be included but is not required.</t>
</dd> </dd>
</dl> </dl>
</section>
</section> <section anchor="IANA-interaction-start-modes-contents">
<section anchor="IANA-as-discovery-contents"><name>Initial Contents</name> <name>Initial Contents</name>
<table>
<texttable> <thead>
<ttcol align='left'>Name</ttcol> <tr>
<ttcol align='left'>Type</ttcol> <th align="left">Mode</th>
<ttcol align='left'>Specification document(s)</ttcol> <th align="left">Type</th>
<c>grant_request_endpoint</c> <th align="left">Reference</th>
<c>string</c> </tr>
<c><xref target="discovery"/> of &SELF;</c> </thead>
<c>interaction_start_modes_supported</c> <tbody>
<c>array of strings</c> <tr>
<c><xref target="discovery"/> of &SELF;</c> <td align="left">redirect</td>
<c>interaction_finish_methods_supported</c> <td align="left">string</td>
<c>array of strings</c> <td align="left">
<c><xref target="discovery"/> of &SELF;</c> <xref target="request-interact-redirect"/> of RFC 9635</td>
<c>key_proofs_supported</c> </tr>
<c>array of strings</c> <tr>
<c><xref target="discovery"/> of &SELF;</c> <td align="left">app</td>
<c>sub_id_formats_supported</c> <td align="left">string</td>
<c>array of strings</c> <td align="left">
<c><xref target="discovery"/> of &SELF;</c> <xref target="request-interact-app"/> of RFC 9635</td>
<c>assertion_formats_supported</c> </tr>
<c>array of strings</c> <tr>
<c><xref target="discovery"/> of &SELF;</c> <td align="left">user_code</td>
<c>key_rotation_supported</c> <td align="left">string</td>
<c>boolean</c> <td align="left">
<c><xref target="discovery"/> of &SELF;</c> <xref target="request-interact-usercode"/> of RFC 9635</td>
</texttable> </tr>
<tr>
</section> <td align="left">user_code_uri</td>
</section> <td align="left">string</td>
</section> <td align="left">
<section anchor="implementation"><name>Implementation Status</name> <xref target="request-interact-usercodeuri"/> of RFC 9635</td>
</tr>
<ul empty="true"><li> </tbody>
<t>Note: To be removed by RFC editor before publication.</t> </table>
</li></ul> </section>
</section>
<t><strong>GNAP Authorization Service in Rust</strong> implementation by David S <section anchor="IANA-interaction-finish-methods">
kyberg. <name>GNAP Interaction Finish Methods</name>
<eref target="https://github.com/dskyberg/gnap">https://github.com/dskyberg/gnap <t>This document defines a means for the client instance to be notified
</eref> Prototype implementation of AS and client in Rust. MIT license.</t> of the end of interaction between the end user and the AS, for which IANA has cr
eated and maintains a new registry titled "GNAP Interaction Finish Methods". Ini
tial values for this registry are given in <xref target="IANA-interaction-finish
-methods-contents"/>. Future assignments and modifications to existing assignmen
ts are to be made through the Specification Required registration policy <xref t
arget="RFC8126"/>.</t>
<t>The DE is expected to ensure the following:</t>
<t><strong>GNAP JS Client</strong> from Interop Alliance, implementation by Dmit <ul spacing="normal">
ri Zagidulin. <eref target="https://github.com/interop-alliance/gnap-client-js"> <li>All registrations follow the template presented in <xref target="IANA
https://github.com/interop-alliance/gnap-client-js</eref> Prototype implementati -interaction-finish-methods-template"/>.</li>
on of client in JavaScript. MIT License.</t> <li>All finish methods clearly define what actions the AS is expected to take, w
hat listening methods the client instance needs to enable, and any security cons
iderations for this communication from either party.</li>
<li>All finish methods document incompatibilities with any start modes, if appli
cable.</li>
</ul>
<section anchor="IANA-interaction-finish-methods-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Method:</dt>
<dd>
<t>An identifier for the interaction finish method.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section>
<section anchor="IANA-interaction-finish-methods-contents">
<name>Initial Contents</name>
<table>
<thead>
<tr>
<th align="left">Method</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">redirect</td>
<td align="left">
<xref target="request-interact-callback-redirect"/> of RFC 963
5</td>
</tr>
<tr>
<td align="left">push</td>
<td align="left">
<xref target="request-interact-callback-push"/> of RFC 9635</t
d>
</tr>
</tbody>
</table>
</section>
</section>
<section anchor="IANA-interaction-hints">
<name>GNAP Interaction Hints</name>
<t>This document defines a set of hints that a client instance can provi
de to the AS to facilitate interaction with the end user, for which IANA has cre
ated and maintains a new registry titled "GNAP Interaction Hints". Initial value
s for this registry are given in <xref target="IANA-interaction-hints-contents"/
>. Future assignments and modifications to existing assignments are to be made t
hrough the Specification Required registration policy <xref target="RFC8126"/>.<
/t>
<t>The DE is expected to ensure the following:</t>
<ul spacing="normal">
<li>All registrations follow the template presented in <xref target="IANA
-interaction-hints-template"/>.</li>
<li>All interaction hints clearly document the expected behaviors of the
AS in response to the hint, and an AS not processing the hint does not impede th
e operation of the AS or client instance.</li>
</ul>
<section anchor="IANA-interaction-hints-template">
<name>Registration Template</name>
<t><strong>Rafiki</strong> from Interledger Foundation. <eref target="https://gi <dl newline="true">
thub.com/interledger/rafiki">https://github.com/interledger/rafiki</eref> Produc <dt>Name:</dt>
tion implementation of AS in JavaScript. Apache 2.0 license.</t> <dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section>
<section anchor="IANA-interaction-hints-contents">
<name>Initial Contents</name>
<table>
<thead>
<tr>
<th align="left">Name</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">ui_locales</td>
<td align="left">
<xref target="request-interact-hint"/> of RFC 9635</td>
</tr>
</tbody>
</table>
</section>
</section>
<section anchor="IANA-grant-response">
<name>GNAP Grant Response Parameters</name>
<t>This document defines a GNAP grant response, for which IANA has creat
ed and maintains a new registry titled "GNAP Grant Response Parameters". Initial
values for this registry are given in <xref target="IANA-grant-response-content
s"/>. Future assignments and modifications to existing assignments are to be mad
e through the Specification Required registration policy <xref target="RFC8126"/
>.</t>
<t>The DE is expected to ensure the following:</t>
<t><strong>Sample GNAP Client in PHP</strong> implementation by Aaron Parecki. < <ul spacing="normal">
eref target="https://github.com/aaronpk/gnap-client-php">https://github.com/aaro <li>All registrations follow the template presented in <xref target="IANA-grant-
npk/gnap-client-php</eref> Prototype implementation of web application client an response-template"/>.</li>
d CLI client in PHP, with common support library. CC0 license.</t> <li>The response parameter's definition is sufficiently orthogonal to existing f
unctionality provided by existing parameters.</li>
<li>Registrations for the same name with different types are sufficiently close
in functionality so as not to cause confusion for developers.</li>
<li>The response parameter's definition specifies grant states for which the cli
ent instance can expect this parameter to appear in a response message.</li>
</ul>
<section anchor="IANA-grant-response-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section>
<section anchor="IANA-grant-response-contents">
<name>Initial Contents</name>
<table>
<thead>
<tr>
<th align="left">Name</th>
<th align="left">Type</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">continue</td>
<td align="left">object</td>
<td align="left">
<xref target="response-continue"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">access_token</td>
<td align="left">object</td>
<td align="left">
<xref target="response-token-single"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">access_token</td>
<td align="left">array of objects</td>
<td align="left">
<xref target="response-token-multiple"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">interact</td>
<td align="left">object</td>
<td align="left">
<xref target="response-interact"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">subject</td>
<td align="left">object</td>
<td align="left">
<xref target="response-subject"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">instance_id</td>
<td align="left">string</td>
<td align="left">
<xref target="response-dynamic-handles"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">error</td>
<td align="left">object</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
</tbody>
</table>
</section>
</section>
<section anchor="IANA-interaction-response">
<name>GNAP Interaction Mode Responses</name>
<t>This document defines a means for the AS to provide the client instan
ce with information that is required to complete a particular interaction mode,
for which IANA has created and maintains a new registry titled "GNAP Interaction
Mode Responses". Initial values for this registry are given in <xref target="IA
NA-interaction-response-contents"/>. Future assignments and modifications to exi
sting assignments are to be made through the Specification Required registration
policy <xref target="RFC8126"/>.</t>
<t>The DE is expected to ensure the following:</t>
<t><strong>SUNET Auth Server</strong> from SUNET. <eref target="https://github.c <ul spacing="normal">
om/SUNET/sunet-auth-server">https://github.com/SUNET/sunet-auth-server</eref> Pr <li>All registrations follow the template presented in <xref target="IANA
oduction implementation of AS in Python. BSD license.</t> -interaction-response-template"/>.</li>
<li>If the name of the registration matches the name of an interaction start mod
e, the response parameter is unambiguously associated with the interaction start
mode of the same name.</li></ul>
<section anchor="IANA-interaction-response-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section>
<section anchor="IANA-interaction-response-contents">
<name>Initial Contents</name>
<table>
<thead>
<tr>
<th align="left">Name</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">redirect</td>
<td align="left">
<xref target="response-interact"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">app</td>
<td align="left">
<xref target="response-interact"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">user_code</td>
<td align="left">
<xref target="response-interact"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">user_code_uri</td>
<td align="left">
<xref target="response-interact"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">finish</td>
<td align="left">
<xref target="response-interact"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">expires_in</td>
<td align="left">
<xref target="response-interact"/> of RFC 9635</td>
</tr>
</tbody>
</table>
</section>
</section>
<section anchor="IANA-subject-response">
<name>GNAP Subject Information Response Fields</name>
<t>This document defines a means to return subject information from the
AS to the client instance, for which IANA has created and maintains a new regist
ry titled "GNAP Subject Information Response Fields". Initial values for this re
gistry are given in <xref target="IANA-subject-response-contents"/>. Future assi
gnments and modifications to existing assignments are to be made through the Spe
cification Required registration policy <xref target="RFC8126"/>.</t>
<t>The DE is expected to ensure the following:</t>
<t><strong>Trustbloc</strong> from Gen Digital. <eref target="https://github.com <ul spacing="normal">
/trustbloc/docs/blob/main/readthedocs/designs/auth.md">https://github.com/trustb <li>All registrations follow the template presented in <xref target="IANA
loc/docs/blob/main/readthedocs/designs/auth.md</eref> Production implementation -subject-response-template"/>.</li>
of AS and client in Go. Apache 2.0 license.</t> <li>Registrations for the same name with different types are sufficiently
close in functionality so as not to cause confusion for developers.</li>
</ul>
<section anchor="IANA-subject-response-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section>
<section anchor="IANA-subject-response-contents">
<name>Initial Contents</name>
<table>
<thead>
<tr>
<th align="left">Name</th>
<th align="left">Type</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">sub_ids</td>
<td align="left">array of objects</td>
<td align="left">
<xref target="response-subject"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">assertions</td>
<td align="left">array of objects</td>
<td align="left">
<xref target="response-subject"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">updated_at</td>
<td align="left">string</td>
<td align="left">
<xref target="response-subject"/> of RFC 9635</td>
</tr>
</tbody>
</table>
</section>
</section>
<section anchor="IANA-error-code">
<name>GNAP Error Codes</name>
<t>This document defines a set of errors that the AS can return to the c
lient instance, for which IANA has created and maintains a new registry titled "
GNAP Error Codes". Initial values for this registry are given in <xref target="I
ANA-error-code-contents"/>. Future assignments and modifications to existing ass
ignments are to be made through the Specification Required registration policy <
xref target="RFC8126"/>.</t>
<t>The DE is expected to ensure the following:</t>
<t><strong>Verified.ME</strong> from SecureKey. <eref target="https://verified.m <ul spacing="normal">
e/">https://verified.me/</eref> Production implementation of AS, client and RS. <li>All registrations follow the template presented in <xref target="IANA
Proprietary license.</t> -error-code-template"/>.</li>
<li>The error response is sufficiently unique from other errors to provide actio
nable information to the client instance.</li>
<li>The definition of the error response specifies all conditions in which the e
rror response is returned and the client instance's expected action.</li>
</ul>
<section anchor="IANA-error-code-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Error:</dt>
<dd>
<t>A unique string code for the error.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section>
<t><strong>XYZ</strong> from Bespoke Engineering, implementation by Justin Riche <section anchor="IANA-error-code-contents">
r. <eref target="https://github.com/bspk/oauth.xyz-java">https://github.com/bspk <name>Initial Contents</name>
/oauth.xyz-java</eref> Advanced prototype implementation of AS, client, and RS i <table>
n Java, with common support library. Prototype implementation of SPA client in J <thead>
avaScript. Apache 2.0 license.</t> <tr>
<th align="left">Error</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">invalid_request</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">invalid_client</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">invalid_interaction</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">invalid_flag</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">invalid_rotation</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">key_rotation_not_supported</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">invalid_continuation</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">user_denied</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">request_denied</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">unknown_user</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">unknown_interaction</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">too_fast</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">too_many_attempts</td>
<td align="left">
<xref target="response-error"/> of RFC 9635</td>
</tr>
</tbody>
</table>
</section>
</section>
<section anchor="IANA-key-proof-methods">
<name>GNAP Key Proofing Methods</name>
<t>This document defines methods that the client instance can use to pro
ve possession of a key, for which IANA has created and maintains a new registry
titled "GNAP Key Proofing Methods". Initial values for this registry are given i
n <xref target="IANA-key-proof-methods-contents"/>. Future assignments and modif
ications to existing assignments are to be made through the Specification Requir
ed registration policy <xref target="RFC8126"/>.</t>
<t>The DE is expected to ensure the following:</t>
</section> <ul spacing="normal">
<section anchor="security"><name>Security Considerations</name> <li>All registrations follow the template presented in <xref target="IANA
-key-proof-methods-template"/>.</li>
<li>Registrations for the same name with different types are sufficiently close
in functionality so as not to cause confusion for developers.</li>
<li>The proofing method provides sufficient coverage of and binding to the proto
col messages to which it is applied.</li>
<li>The proofing method definition clearly enumerates how all requirements in <x
ref target="binding-keys"/> are fulfilled by the definition.</li>
</ul>
<section anchor="IANA-key-proof-methods-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Method:</dt>
<dd>
<t>A unique string code for the key proofing method.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section>
<section anchor="IANA-key-proof-methods-contents">
<name>Initial Contents</name>
<table>
<thead>
<tr>
<th align="left">Method</th>
<th align="left">Type</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">httpsig</td>
<td align="left">string</td>
<td align="left">
<xref target="httpsig-binding"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">httpsig</td>
<td align="left">object</td>
<td align="left">
<xref target="httpsig-binding"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">mtls</td>
<td align="left">string</td>
<td align="left">
<xref target="mtls"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">jwsd</td>
<td align="left">string</td>
<td align="left">
<xref target="detached-jws"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">jws</td>
<td align="left">string</td>
<td align="left">
<xref target="attached-jws"/> of RFC 9635</td>
</tr>
</tbody>
</table>
</section>
</section>
<section anchor="IANA-key-formats">
<name>GNAP Key Formats</name>
<t>This document defines formats for a public key value, for which IANA
has created and maintains a new registry titled "GNAP Key Formats". Initial valu
es for this registry are given in <xref target="IANA-key-formats-contents"/>. Fu
ture assignments and modifications to existing assignments are to be made throug
h the Specification Required registration policy <xref target="RFC8126"/>.</t>
<t>The DE is expected to ensure the following:</t>
<t>In addition to the normative requirements in this document, implementors are <ul spacing="normal">
strongly encouraged to consider these additional security considerations in impl <li>All registrations follow the template presented in <xref target="IANA
ementations and deployments of GNAP.</t> -key-formats-template"/>.</li>
<li>The key format specifies the structure and serialization of the key m
aterial.</li>
</ul>
<section anchor="IANA-key-formats-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Format:</dt>
<dd>
<t>A unique string code for the key format.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section>
<section anchor="IANA-key-formats-contents">
<name>Initial Contents</name>
<table>
<thead>
<tr>
<th align="left">Format</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">jwk</td>
<td align="left">
<xref target="key-format"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">cert</td>
<td align="left">
<xref target="key-format"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">cert#S256</td>
<td align="left">
<xref target="key-format"/> of RFC 9635</td>
</tr>
</tbody>
</table>
</section>
</section>
<section anchor="IANA-as-discovery">
<name>GNAP Authorization Server Discovery Fields</name>
<t>This document defines a discovery document for an AS, for which IANA
has created and maintains a new registry titled "GNAP Authorization Server Disco
very Fields". Initial values for this registry are given in <xref target="IANA-a
s-discovery-contents"/>. Future assignments and modifications to existing assign
ments are to be made through the Specification Required registration policy <xre
f target="RFC8126"/>.</t>
<t>The DE is expected to ensure the following:</t>
<section anchor="security-tls"><name>TLS Protection in Transit</name> <ul spacing="normal">
<li>All registrations follow the template presented in <xref target="IANA-as-dis
covery-template"/>.</li>
<li>Registrations for the same name with different types are sufficiently close
in functionality so as not to cause confusion for developers.</li>
<li>The values in the discovery document are sufficient to provide optimization
and hints to the client instance, but knowledge of the discovered value is not r
equired for starting a transaction with the AS.</li>
</ul>
<section anchor="IANA-as-discovery-template">
<name>Registration Template</name>
<dl newline="true">
<dt>Name:</dt>
<dd>
<t>An identifier for the parameter.</t>
</dd>
<dt>Type:</dt>
<dd>
<t>The JSON type allowed for the value.</t>
</dd>
<dt>Reference:</dt>
<dd>
<t>Reference to one or more documents that specify the
value, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.</t>
</dd>
</dl>
</section>
<section anchor="IANA-as-discovery-contents">
<name>Initial Contents</name>
<table>
<thead>
<tr>
<th align="left">Name</th>
<th align="left">Type</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">grant_request_endpoint</td>
<td align="left">string</td>
<td align="left">
<xref target="discovery"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">interaction_start_modes_supported</td>
<td align="left">array of strings</td>
<td align="left">
<xref target="discovery"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">interaction_finish_methods_supported</td>
<td align="left">array of strings</td>
<td align="left">
<xref target="discovery"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">key_proofs_supported</td>
<td align="left">array of strings</td>
<td align="left">
<xref target="discovery"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">sub_id_formats_supported</td>
<td align="left">array of strings</td>
<td align="left">
<xref target="discovery"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">assertion_formats_supported</td>
<td align="left">array of strings</td>
<td align="left">
<xref target="discovery"/> of RFC 9635</td>
</tr>
<tr>
<td align="left">key_rotation_supported</td>
<td align="left">boolean</td>
<td align="left">
<xref target="discovery"/> of RFC 9635</td>
</tr>
</tbody>
</table>
</section>
</section>
</section>
<section anchor="security">
<t>All requests in GNAP made over untrusted network connections have to be made <name>Security Considerations</name>
over TLS as outlined in <xref target="BCP195"/> <t>In addition to the normative requirements in this document, implementor
s are strongly encouraged to consider these additional security considerations i
n implementations and deployments of GNAP.</t>
<section anchor="security-tls">
<name>TLS Protection in Transit</name>
<t>All requests in GNAP made over untrusted network connections have to
be made over TLS as outlined in <xref target="BCP195"/>
to protect the contents of the request and response from manipulation and interc eption by an attacker. to protect the contents of the request and response from manipulation and interc eption by an attacker.
This includes all requests from a client instance to the AS, all requests from t he client instance to This includes all requests from a client instance to the AS, all requests from t he client instance to
an RS, and any requests back to a client instance such as the push-based interac tion finish method. an RS, and any requests back to a client instance such as the push-based interac tion finish method.
Additionally, all requests between a browser and other components, such as durin g redirect-based Additionally, all requests between a browser and other components, such as durin g redirect-based
interaction, need to be made over TLS or use equivalent protection such as a net work connection local to the browser ("localhost").</t> interaction, need to be made over TLS or use equivalent protection such as a net work connection local to the browser ("localhost").</t>
<t>Even though requests from the client instance to the AS are signed, t
<t>Even though requests from the client instance to the AS are signed, the signa he signature method alone does not protect
ture method alone does not protect
the request from interception by an attacker. TLS protects the response as well as the request, the request from interception by an attacker. TLS protects the response as well as the request,
preventing an attacker from intercepting requested information as it is returned . This is particularly preventing an attacker from intercepting requested information as it is returned . This is particularly
important in the core protocol for security artifacts such as nonces and for important in this specification for security artifacts such as nonces and for
personal information such as subject information.</t> personal information such as subject information.</t>
<t>The use of key-bound access tokens does not negate the requirement for protec ting calls to the RS with TLS. <t>The use of key-bound access tokens does not negate the requirement for protec ting calls to the RS with TLS.
While the keys and signatures associated a bound access token will prevent an at The keys and signatures associated with a bound access token will prevent an att
tacker from using a stolen acker from using a stolen
token, without TLS an attacker would be able to watch the data being sent to the token; however, without TLS, an attacker would be able to watch the data being s
RS and returned from the RS ent to the RS and returned from the RS
during legitimate use of the client instance under attack. Additionally, without during legitimate use of the client instance under attack. Additionally, without
TLS an attacker would be TLS, an attacker would be
able to profile the calls made between the client instance and RS, possibly gain ing information about the functioning able to profile the calls made between the client instance and RS, possibly gain ing information about the functioning
of the API between the client software and RS software that would be otherwise u of the API between the client software and RS software that would otherwise be u
nknown to the attacker.</t> nknown to the attacker.</t>
<t>Note that connections from the end user and RO's browser also need to
<t>Note that connections from the end user and RO's browser also need to be be p be protected with TLS. This applies during initial
rotected with TLS. This applies during initial redirects to an AS's components during interaction, during any interaction with
redirects to an AS's components during interaction, during any interaction with the RO, and during
the resource owner, and during
any redirect back to the client instance. Without TLS protection on these portio ns of the process, an any redirect back to the client instance. Without TLS protection on these portio ns of the process, an
attacker could wait for a valid request to start and then take over the resource attacker could wait for a valid request to start and then take over the RO's int
owner's interaction session.</t> eraction session.</t>
</section>
</section> <section anchor="security-signing">
<section anchor="security-signing"><name>Signing Requests from the Client Softwa <name>Signing Requests from the Client Software</name>
re</name> <t>Even though all requests in GNAP need to be transmitted over TLS or i
ts equivalent, the use of TLS
<t>Even though all requests in GNAP need to be transmitted over TLS or its equiv
alent, the use of TLS
alone is not sufficient to protect all parts of a multi-party and multi-stage pr otocol like GNAP, alone is not sufficient to protect all parts of a multi-party and multi-stage pr otocol like GNAP,
and TLS is not targeted at tying multiple requests to each other over time. and TLS is not targeted at tying multiple requests to each other over time.
To account for this, GNAP makes use of message-level protection and key presenta tion mechanisms To account for this, GNAP makes use of message-level protection and key presenta tion mechanisms
that strongly associate a request with a key held by the client instance (see <x ref target="secure-requests"/>).</t> that strongly associate a request with a key held by the client instance (see <x ref target="secure-requests"/>).</t>
<t>During the initial request from a client instance to the AS, the clie
<t>During the initial request from a client instance to the AS, the client insta nt instance has to identify and
nce has to identify and prove possession of a cryptographic key. If the key is known to the AS, e.g., pr
prove possession of a cryptographic key. If the key is known to the AS, such as eviously
if it is previously
registered or dereferenceable to a trusted source, the AS can associate a set of policies to the registered or dereferenceable to a trusted source, the AS can associate a set of policies to the
client instance identified by the key. Without the requirement that the client i nstance prove that it holds client instance identified by the key. Without the requirement that the client i nstance prove that it holds
that key, the AS could not trust that the connection came from any particular cl ient and could that key, the AS could not trust that the connection came from any particular cl ient and could
not apply any associated policies.</t> not apply any associated policies.</t>
<t>Even more importantly, the client instance proving possession of a
<t>Even more importantly, the client instance proving possession of a key on the key on the first request allows the AS to associate future requests
first request allows with each other by binding all future requests in that transaction to
the AS to associate future requests with each other by binding all future reques the same key. The access token used for grant continuation is bound to
ts in that the same key and proofing mechanism used by the client instance in its
transaction to the same key. The access token used for grant continuation initial request; this means that the client instance needs to prove
is bound to the same key and proofing mechanism used by the client instance in i possession of that same key in future requests, which allows the AS to
ts initial request, be sure that the same client instance is executing the follow-ups for
which means that the client instance needs to prove possession of that same key a given ongoing grant request. Therefore, the AS has to ensure that
in future requests all subsequent requests for a grant are associated with the same key
allowing the AS to be sure that the same client instance is executing the follow that started the grant or with the most recent rotation of that key. Th
-ups for a given is
ongoing grant request. Therefore, the AS has to ensure that all subsequent reque need holds true even if the initial key is previously unknown to the
sts for a grant are AS, such as would be the case when a client instance creates an
associated with the same key that started the grant, or the most recent rotation ephemeral key for its request. Without this ongoing association, an
of that key. attacker would be able to impersonate a client instance in the midst
This need holds true even if the initial key is previously unknown to the AS, su of a grant request, potentially stealing access tokens and subject
ch as would be information with impunity.</t>
the case when a client instance creates an ephemeral key for its request. <t>Additionally, all access tokens in GNAP default to be associated with
Without this ongoing association, an attacker would be able to impersonate a cli the key that was presented
ent instance
in the midst of a grant request, potentially stealing access tokens and subject
information
with impunity.</t>
<t>Additionally, all access tokens in GNAP default to be associated with the key
that was presented
during the grant request that created the access token. This association allows an RS to know that during the grant request that created the access token. This association allows an RS to know that
the presenter of the access token is the same party that the token was issued to , as identified the presenter of the access token is the same party that the token was issued to , as identified
by their keys. While non-bound bearer tokens are an option in GNAP, these types of tokens by their keys. While non-bound bearer tokens are an option in GNAP, these types of tokens
have their own tradeoffs discussed in <xref target="security-bearer-tokens"/>.</ t> have their own trade-offs, which are discussed in <xref target="security-bearer- tokens"/>.</t>
<t>TLS functions at the transport layer, ensuring that only the parties on eithe r end of that <t>TLS functions at the transport layer, ensuring that only the parties on either end of that
connection can read the information passed along that connection. Each time a ne w connection connection can read the information passed along that connection. Each time a ne w connection
is made, such as for a new HTTP request, a new trust is re-established that is m is made, such as for a new HTTP request, a new trust that is mostly unrelated to
ostly unrelated to previous previous
connections. While modern TLS does make use of session resumption, this still ne connections is re-established. While modern TLS does make use of session resumpt
eds to be augmented ion, this still needs to be augmented
with authentication methods to determine the identity of parties on the with authentication methods to determine the identity of parties on the
connections. In other words, it is not possible with TLS alone to know that the same party is making connections. In other words, it is not possible with TLS alone to know that the same party is making
a set of calls over time, since each time a new TLS connection is established, b oth the client and the server (or the server only when using <xref target="mtls" />) have to validate a set of calls over time, since each time a new TLS connection is established, b oth the client and the server (or the server only when using MTLS (<xref target= "mtls"/>)) have to validate
the other party's identity. Such a verification can be achieved via methods desc ribed in <xref target="RFC9525"/>, but these are not enough to establish the ide ntity of the client instance in many cases.</t> the other party's identity. Such a verification can be achieved via methods desc ribed in <xref target="RFC9525"/>, but these are not enough to establish the ide ntity of the client instance in many cases.</t>
<t>To counter this, GNAP defines a set of key binding methods in <xref t
<t>To counter this, GNAP defines a set of key binding methods in <xref target="b arget="binding-keys"/> that allows authentication and
inding-keys"/> that allow authentication and
proof of possession by the caller, which is usually the client instance. These m ethods are intended to be used in proof of possession by the caller, which is usually the client instance. These m ethods are intended to be used in
addition to TLS on all connections.</t> addition to TLS on all connections.</t>
</section>
</section> <section anchor="security-mtls">
<section anchor="security-mtls"><name>MTLS Message Integrity</name> <name>MTLS Message Integrity</name>
<t>The MTLS key proofing mechanism (<xref target="mtls"> </xref>) provid
<t>The <xref target="mtls">MTLS key proofing mechanism</xref> provides a means f es a means for a client instance to present a key
or a client instance to present a key
using a certificate at the TLS layer. Since TLS protects the entire HTTP message in transit, using a certificate at the TLS layer. Since TLS protects the entire HTTP message in transit,
verification of the TLS client certificate presented with the message provides a sufficient binding verification of the TLS client certificate presented with the message provides a sufficient binding
between the two. However, since TLS is functioning at a separate layer from HTTP , there is no between the two. However, since TLS is functioning at a separate layer from HTTP , there is no
direct connection between the TLS key presentation and the message itself, other than the fact that direct connection between the TLS key presentation and the message itself, other than the fact that
the message was presented over the TLS channel. That is to say, any HTTP message can be presented the message was presented over the TLS channel. That is to say, any HTTP message can be presented
over the TLS channel in question with the same level of trust. The verifier is r esponsible for over the TLS channel in question with the same level of trust. The verifier is r esponsible for
ensuring the key in the TLS client certificate is the one expected for a particu lar request. For ensuring the key in the TLS client certificate is the one expected for a particu lar request. For
example, if the request is a <xref target="request">grant request</xref>, the AS needs to compare the TLS client example, if the request is a grant request (<xref target="request"> </xref>), th e AS needs to compare the TLS client
certificate presented at the TLS layer to the key identified in the request cont ent itself (either certificate presented at the TLS layer to the key identified in the request cont ent itself (either
by value or through a referenced identifier).</t> by value or through a referenced identifier).</t>
<t>Furthermore, the prevalence of the TLS terminating reverse proxy (TTR
<t>Furthermore, the prevalence of the TLS-terminating reverse proxy (TTRP) patte P) pattern in deployments adds
rn in deployments adds
a wrinkle to the situation. In this common pattern, the TTRP validates the TLS c onnection and then forwards the HTTP message contents onward to an internal syst em for processing. The system a wrinkle to the situation. In this common pattern, the TTRP validates the TLS c onnection and then forwards the HTTP message contents onward to an internal syst em for processing. The system
processing the HTTP message no longer has access to the original TLS connection' s information and processing the HTTP message no longer has access to the original TLS connection' s information and
context. To compensate for this, the TTRP could inject the TLS client certificat context.
e into the forwarded
request as a header parameter using <xref target="RFC9111"/>, giving the downstr
eam
system access to the certificate information. The TTRP has to be trusted to prov
ide accurate
certificate information, and the connection between the TTRP and the downstream
system also has to
be protected. The TTRP could provide some additional assurance, for example, by
adding its own
signature to the Client-Cert header field using <xref target="RFC9421"/>. This
signature would be effectively ignored by GNAP (since it would not use GNAP's <s
panx style="verb">tag</spanx> parameter
value) but would be understood by the downstream service as part
of its deployment.</t>
<t>Additional considerations for different types of deployment patterns and key To compensate for this, the TTRP could inject the TLS client certificate into
distribution the forwarded request using the HTTP Client-Cert header field <xref
target="RFC9111"/>, giving the downstream system access to the certificate
information. The TTRP has to be trusted to provide accurate certificate
information, and the connection between the TTRP and the downstream system
also has to be protected. The TTRP could provide some additional assurance,
for example, by adding its own signature to the Client-Cert header field using
HTTP message signatures <xref target="RFC9421"/>. This signature would be
effectively ignored by GNAP (since it would not use GNAP's <tt>tag</tt>
parameter value) but would be understood by the downstream service as part of
its deployment.</t>
<t>Additional considerations for different types of deployment patterns
and key distribution
mechanisms for MTLS are found in <xref target="security-mtls-patterns"/>.</t> mechanisms for MTLS are found in <xref target="security-mtls-patterns"/>.</t>
</section>
</section> <section anchor="security-mtls-patterns">
<section anchor="security-mtls-patterns"><name>MTLS Deployment Patterns</name> <name>MTLS Deployment Patterns</name>
<t>GNAP does not specify how a client instance's keys could be made know
<t>GNAP does not specify how a client instance's keys could be made known to the n to the AS ahead of time.
AS ahead of time. The Public Key Infrastructure (PKI) can be used to manage the keys used by clien
Public Key Infrastructure (PKI) can be used to manage the keys used by client in t instances when calling
stances when calling
the AS, allowing the AS to trust a root key from a trusted authority. This metho d is particularly the AS, allowing the AS to trust a root key from a trusted authority. This metho d is particularly
relevant to the MTLS key proofing method, where the client instance relevant to the MTLS key proofing method, where the client instance
presents its certificate to the AS as part of the TLS connection. An AS using PK I to validate the presents its certificate to the AS as part of the TLS connection. An AS using PK I to validate the
MTLS connection would need to ensure that the presented certificate was issued b y a trusted certificate MTLS connection would need to ensure that the presented certificate was issued b y a trusted certificate
authority before allowing the connection to continue. PKI-based certificates wou ld allow a key to be revoked authority before allowing the connection to continue. PKI-based certificates wou ld allow a key to be revoked
and rotated through management at the certificate authority without requiring ad ditional registration and rotated through management at the certificate authority without requiring ad ditional registration
or management at the AS. The PKI required to manage mutually-authenticated TLS h as historically been or management at the AS. The PKI required to manage mutually authenticated TLS h as historically been
difficult to deploy, especially at scale, but it remains an appropriate solution for systems where difficult to deploy, especially at scale, but it remains an appropriate solution for systems where
the required management overhead is not an impediment.</t> the required management overhead is not an impediment.</t>
<t>MTLS in GNAP need not use a PKI backing, as self-signed certificates
<t>MTLS in GNAP need not use a PKI backing, as self-signed certificates and cert and certificates from untrusted
ificates from untrusted
authorities can still be presented as part of a TLS connection. In this case, th e verifier would authorities can still be presented as part of a TLS connection. In this case, th e verifier would
validate the connection but accept whatever certificate was presented by the cli ent software. This validate the connection but accept whatever certificate was presented by the cli ent software. This
specific certificate can then be bound to all future connections from that clien t software by specific certificate can then be bound to all future connections from that clien t software by
being bound to the resulting access tokens, in a trust-on-first-use pattern. See <xref target="security-mtls"/> being bound to the resulting access tokens, in a trust-on-first-use pattern. See <xref target="security-mtls"/>
for more considerations on MTLS as a key proofing mechanism.</t> for more considerations on MTLS as a key proofing mechanism.</t>
</section>
</section> <section anchor="security-keys">
<section anchor="security-keys"><name>Protection of Client Instance Key Material <name>Protection of Client Instance Key Material</name>
</name> <t>Client instances are identified by their unique keys, and anyone with
access to a client instance's key material
<t>Client instances are identified by their unique keys, and anyone with access
to a client instance's key material
will be able to impersonate that client instance to all parties. This is true fo r both calls to the AS will be able to impersonate that client instance to all parties. This is true fo r both calls to the AS
as well as calls to an RS using an access token bound to the client instance's u nique key. As a consequence, it is of utmost importance for a client instance to protect its private key material.</t> as well as calls to an RS using an access token bound to the client instance's u nique key. As a consequence, it is of utmost importance for a client instance to protect its private key material.</t>
<t>Different types of client software have different methods for creating, manag ing, and registering <t>Different types of client software have different methods for creating, manag ing, and registering
keys. GNAP explicitly allows for ephemeral clients such as single-page applicati ons (SPAs) and single-user clients (such as keys. GNAP explicitly allows for ephemeral clients such as single-page applicati ons (SPAs) and single-user clients (such as
mobile applications) to create and present their own keys during the initial gra nt request without any explicit pre-registration step. The client mobile applications) to create and present their own keys during the initial gra nt request without any explicit pre-registration step. The client
software can securely generate a keypair on-device and present the public key, a long with proof of holding the associated software can securely generate a key pair on the device and present the public k ey, along with proof of holding the associated
private key, to the AS as part of the initial request. To facilitate trust in th ese ephemeral keys, private key, to the AS as part of the initial request. To facilitate trust in th ese ephemeral keys,
GNAP further allows for an extensible set of client information to be passed wit h the request. This GNAP further allows for an extensible set of client information to be passed wit h the request. This
information can include device posture and third-party attestations of the clien t software's provenance information can include device posture and third-party attestations of the clien t software's provenance
and authenticity, depending on the needs and capabilities of the client software and its deployment.</t> and authenticity, depending on the needs and capabilities of the client software and its deployment.</t>
<t>From GNAP's perspective, each distinct key is a different client inst
<t>From GNAP's perspective, each distinct key is a different client instance. Ho ance. However, multiple client
wever, multiple client
instances can be grouped together by an AS policy and treated similarly to each other. For instance, instances can be grouped together by an AS policy and treated similarly to each other. For instance,
if an AS knows of several different keys for different servers within a cluster, the AS can if an AS knows of several different keys for different servers within a cluster, the AS can
decide that authorization of one of these servers applies to all other servers w ithin the cluster. An AS decide that authorization of one of these servers applies to all other servers w ithin the cluster. An AS
that chooses to do this needs to be careful with how it groups different client keys together in its policy, that chooses to do this needs to be careful with how it groups different client keys together in its policy,
since the breach of one instance would have direct effects on the others in the cluster.</t> since the breach of one instance would have direct effects on the others in the cluster.</t>
<t>Additionally, if an end user controls multiple instances of a single
<t>Additionally, if an end user controls multiple instances of a single type of type of client software, such as
client software, such as
having an application installed on multiple devices, each of these instances is expected to have a having an application installed on multiple devices, each of these instances is expected to have a
separate key and be issued separate access tokens. However, if the AS is able to group these separate separate key and be issued separate access tokens. However, if the AS is able to group these separate
instances together as described above, it can streamline the authorization proce ss for new instances instances together as described above, it can streamline the authorization proce ss for new instances
of the same client software. For example, if two client instances can present pr oof of a valid installation of the same client software. For example, if two client instances can present pr oof of a valid installation
of a piece of client software, the AS would be able to associate the approval of the first instance of this of a piece of client software, the AS would be able to associate the approval of the first instance of this
software to all related instances. The AS could then choose to bypass an explici software to all related instances. The AS could then choose to bypass an explici
t prompt of the resource t prompt of the RO for approval during authorization, since such approval has al
owner for approval during authorization, since such approval has already been gi ready been given. An AS doing such
ven. An AS doing such
a process would need to take assurance measures that the different instances are in fact correlated a process would need to take assurance measures that the different instances are in fact correlated
and authentic, as well as ensuring the expected resource owner is in control of and authentic, as well as ensure that the expected RO is in control of the clien
the client instance.</t> t instance.</t>
<t>Finally, if multiple instances of client software each have the same
<t>Finally, if multiple instances of client software each have the same key, the key, then from GNAP's perspective,
n from GNAP's perspective,
these are functionally the same client instance as GNAP has no reasonable way to differentiate between these are functionally the same client instance as GNAP has no reasonable way to differentiate between
them. This situation could happen if multiple instances within a cluster can sec urely share secret them. This situation could happen if multiple instances within a cluster can sec urely share secret
information among themselves. Even though there are multiple copies of the softw are, the shared key information among themselves. Even though there are multiple copies of the softw are, the shared key
makes these copies all present as a single instance. It is considered bad practi ce to share keys between makes these copies all present as a single instance. It is considered bad practi ce to share keys between
copies of software unless they are very tightly integrated with each other and c an be closely managed. copies of software unless they are very tightly integrated with each other and c an be closely managed.
It is particularly bad practice to allow an end user to copy keys between client instances and to It is particularly bad practice to allow an end user to copy keys between client instances and to
willingly use the same key in multiple instances.</t> willingly use the same key in multiple instances.</t>
</section>
</section> <section anchor="security-as">
<section anchor="security-as"><name>Protection of Authorization Server</name> <name>Protection of Authorization Server</name>
<t>The AS performs critical functions in GNAP, including authenticating
<t>The AS performs critical functions in GNAP, including authenticating client s client software, managing interactions
oftware, managing interactions
with end users to gather consent and provide notice, and issuing access tokens f or client instances with end users to gather consent and provide notice, and issuing access tokens f or client instances
to present to resource servers. As such, protecting the AS is central to any GNA to present to RSs. As such, protecting the AS is central to any GNAP deployment.
P deployment.</t> </t>
<t>If an attacker is able to gain control over an AS, they would be able
<t>If an attacker is able to gain control over an AS, they would be able to crea to create fraudulent tokens and
te fraudulent tokens and
manipulate registration information to allow for malicious clients. These tokens and clients would manipulate registration information to allow for malicious clients. These tokens and clients would
be trusted by other components in the ecosystem under the protection of the AS.< /t> be trusted by other components in the ecosystem under the protection of the AS.< /t>
<t>If the AS uses signed access tokens, an attacker in control of the AS
<t>If the AS is using signed access tokens, an attacker in control of the AS's s 's signing keys would
igning keys would be able to manufacture fraudulent tokens for use at RSs under the protection of
be able to manufacture fraudulent tokens for use at RS's under the protection of the AS.</t>
the AS.</t> <t>If an attacker is able to impersonate an AS, they would be able to tr
ick legitimate client instances
<t>If an attacker is able to impersonate an AS, they would be able to trick legi into making signed requests for information that could potentially be proxied to
timate client instances a real AS. To combat
into making signed requests for information which could potentially be proxied t
o a real AS. To combat
this, all communications to the AS need to be made over TLS or its equivalent, a nd the software this, all communications to the AS need to be made over TLS or its equivalent, a nd the software
making the connection has to validate the certificate chain of the host it is co nnecting to.</t> making the connection has to validate the certificate chain of the host it is co nnecting to.</t>
<t>Consequently, protecting, monitoring, and auditing the AS is paramoun
<t>Consequently, protecting, monitoring, and auditing the AS is paramount to pre t to preserving the security
serving the security
of a GNAP-protected ecosystem. The AS presents attackers with a valuable target for attack. of a GNAP-protected ecosystem. The AS presents attackers with a valuable target for attack.
Fortunately, the core focus and function of the AS is to provide security for th e ecosystem, unlike Fortunately, the core focus and function of the AS is to provide security for th e ecosystem, unlike
the RS whose focus is to provide an API or the client software whose focus is to access the API.</t> the RS whose focus is to provide an API or the client software whose focus is to access the API.</t>
</section>
</section> <section anchor="security-symmetric">
<section anchor="security-symmetric"><name>Symmetric and Asymmetric Client Insta <name>Symmetric and Asymmetric Client Instance Keys</name>
nce Keys</name> <t>Many of the cryptographic methods used by GNAP for key proofing can s
upport both asymmetric and symmetric
<t>Many of the cryptographic methods used by GNAP for key-proofing can support b cryptography, and they can be extended to use a wide variety of mechanisms.
oth asymmetric and symmetric Implementors will find the available guidelines on cryptographic key management
cryptography, and can be extended to use a wide variety of mechanisms. provided in <xref target="RFC4107"/> useful. While symmetric
Implementers will find useful the available guidelines on cryptographic key mana cryptographic systems have some benefits in speed and simplicity, they have a di
gement provided in <xref target="RFC4107"/>. While symmetric stinct drawback --
cryptographic systems have some benefits in speed and simplicity, they have a di both parties need access to the same key in order to do both signing and verific
stinct drawback ation of
that both parties need access to the same key in order to do both signing and ve
rification of
the message. the message.
When more than two parties share the same symmetric key, When more than two parties share the same symmetric key,
data origin authentication is not provided. Any party that knows the data origin authentication is not provided. Any party that knows the
symmetric key can compute a valid MAC; therefore, the symmetric key can compute a valid MAC; therefore, the
contents could originate from any one of the parties.</t> contents could originate from any one of the parties.</t>
<t>Use of symmetric cryptography means that when the client instance cal
<t>Use of symmetric cryptography means that when the client instance calls the A ls the AS to request a token, the
S to request a token, the
AS needs to know the exact value of the client instance's key (or be able to der ive it) in AS needs to know the exact value of the client instance's key (or be able to der ive it) in
order to validate the key proof signature. With asymmetric keys, the client need s only to order to validate the key proof signature. With asymmetric keys, the client need s to only
send its public key to the AS to allow for verification that the client holds th e associated send its public key to the AS to allow for verification that the client holds th e associated
private key, regardless of whether that key was pre-registered or not with the A private key, regardless of whether or not that key was pre-registered with the A
S.</t> S.</t>
<t>Symmetric keys also have the expected advantage of providing better p
<t>Symmetric keys also have the expected advantage of providing better protectio rotection against quantum
n against quantum
threats in the future. Also, these types of keys (and their secure derivations) are widely threats in the future. Also, these types of keys (and their secure derivations) are widely
supported among many cloud-based key management systems.</t> supported among many cloud-based key management systems.</t>
<t>When used to bind to an access token, a key value must be known by th
<t>When used to bind to an access token, a key value must be known by the RS in e RS in order
order
to validate the proof signature on the request. Common methods for communicating these proofing to validate the proof signature on the request. Common methods for communicating these proofing
keys include putting information in a structured access token and allowing the R S to look keys include putting information in a structured access token and allowing the R S to look
up the associated key material against the value of the access token. With symme tric cryptography, up the associated key material against the value of the access token. With symme tric cryptography,
both of these methods would expose the signing key to the RS, and in the case of an structured both of these methods would expose the signing key to the RS and, in the case of a structured
access token, potentially to any party that can see the access token itself unle ss the token's access token, potentially to any party that can see the access token itself unle ss the token's
payload has been encrypted. Any of these parties would then be able to make call s using the payload has been encrypted. Any of these parties would then be able to make call s using the
access token by creating a valid signature using the shared key. With asymmetric cryptography, the RS needs access token by creating a valid signature using the shared key. With asymmetric cryptography, the RS needs
to know only the public key associated with the token in order to validate the r equest, and therefore the RS cannot to only know the public key associated with the token in order to validate the r equest; therefore, the RS cannot
create any new signed calls.</t> create any new signed calls.</t>
<t>While both signing approaches are allowed, GNAP treats these two clas
<t>While both signing approaches are allowed, GNAP treats these two classes of k ses of keys somewhat
eys somewhat
differently. Only the public portion of asymmetric keys are allowed to be sent b y value differently. Only the public portion of asymmetric keys are allowed to be sent b y value
in requests to the AS when establishing a connection. Since sending a symmetric key (or in requests to the AS when establishing a connection. Since sending a symmetric key (or
the private portion of an asymmetric key) would expose the signing material to a ny parties the private portion of an asymmetric key) would expose the signing material to a ny parties
on the request path, including any attackers, sending these kinds of keys by val ue is prohibited. on the request path, including any attackers, sending these kinds of keys by val ue is prohibited.
Symmetric keys can still be used by client instances, but only if the client ins tance can send a reference to the key and Symmetric keys can still be used by client instances, but only if the client ins tance can send a reference to the key and
not its value. This approach allows the AS to use pre-registered symmetric keys as well not its value. This approach allows the AS to use pre-registered symmetric keys as well
as key derivation schemes to take advantage of symmetric cryptography but withou t requiring as key derivation schemes to take advantage of symmetric cryptography without re quiring
key distribution at runtime, which would expose the keys in transit.</t> key distribution at runtime, which would expose the keys in transit.</t>
<t>Both the AS and client software can use systems such as hardware secu
<t>Both the AS and client software can use systems such as hardware security mod rity modules to strengthen
ules to strengthen
their key security storage and generation for both asymmetric and symmetric keys (see also <xref target="key-protection"/>).</t> their key security storage and generation for both asymmetric and symmetric keys (see also <xref target="key-protection"/>).</t>
</section>
</section> <section anchor="security-access-tokens">
<section anchor="security-access-tokens"><name>Generation of Access Tokens</name <name>Generation of Access Tokens</name>
> <t>The contents of access tokens need to be such that only the generatin
g AS would be able to
<t>The content of access tokens need to be such that only the generating AS woul
d be able to
create them, and the contents cannot be manipulated by an attacker to gain diffe rent or additional create them, and the contents cannot be manipulated by an attacker to gain diffe rent or additional
access rights.</t> access rights.</t>
<t>One method for accomplishing this is to use a cryptographically rando
<t>One method for accomplishing this is to use a cryptographically random value m value for the access token,
for the access token,
generated by the AS using a secure randomization function with sufficiently high entropy. The odds of generated by the AS using a secure randomization function with sufficiently high entropy. The odds of
an attacker guessing the output of the randomization function to collide with a valid access token an attacker guessing the output of the randomization function to collide with a valid access token
are exceedingly small, and even then the attacker would not have any control ove r what the are exceedingly small, and even then, the attacker would not have any control ov er what the
access token would represent since that information would be held close by the A S.</t> access token would represent since that information would be held close by the A S.</t>
<t>Another method for accomplishing this is to use a structured token th
<t>Another method for accomplishing this is to use a structured token that is cr at is cryptographically signed.
yptographically signed.
In this case, the payload of the access token declares to the RS what the token is good for, but In this case, the payload of the access token declares to the RS what the token is good for, but
the signature applied by the AS during token generation covers this payload. Onl y the AS can create the signature applied by the AS during token generation covers this payload. Onl y the AS can create
such a signature and therefore only the AS can create such a signed token. The o dds of an attacker such a signature; therefore, only the AS can create such a signed token. The odd s of an attacker
being able to guess a signature value with a useful payload are exceedingly smal l. This technique being able to guess a signature value with a useful payload are exceedingly smal l. This technique
only works if all targeted RS's check the signature of the access token. Any RS that does not only works if all targeted RSs check the signature of the access token. Any RS t hat does not
validate the signature of all presented tokens would be susceptible to injection of a modified validate the signature of all presented tokens would be susceptible to injection of a modified
or falsified token. Furthermore, an AS has to carefully protect the keys used to sign access or falsified token. Furthermore, an AS has to carefully protect the keys used to sign access
tokens, since anyone with access to these signing keys would be able to create s eemingly-valid tokens, since anyone with access to these signing keys would be able to create s eemingly valid
access tokens using them.</t> access tokens using them.</t>
</section>
<section anchor="security-bearer-tokens">
<name>Bearer Access Tokens</name>
</section> <t>Bearer access tokens can be used by any party that has access to the t
<section anchor="security-bearer-tokens"><name>Bearer Access Tokens</name> oken itself, without any additional
<t>Bearer access tokens can be used by any party that has access to the token it
self, without any additional
information. As a natural consequence, any RS that a bearer token is presented t o has the technical information. As a natural consequence, any RS that a bearer token is presented t o has the technical
capability of presenting that bearer token to another RS, as long as the token i s valid. It also capability of presenting that bearer token to another RS, as long as the token i s valid. It also
means that any party that is able capture of the token value in storage or in tr ansit is able to means that any party that is able to capture the token value in storage or in tr ansit is able to
use the access token. While bearer tokens are inherently simpler, this simplicit y has been misapplied use the access token. While bearer tokens are inherently simpler, this simplicit y has been misapplied
and abused in making needlessly insecure systems. The downsides of bearer tokens have become more and abused in making needlessly insecure systems. The downsides of bearer tokens have become more
pertinent lately as stronger authentication systems have caused some attacks to shift to target pertinent lately as stronger authentication systems have caused some attacks to shift to target
tokens and APIs.</t> tokens and APIs.</t>
<t>In GNAP, key-bound access tokens are the default due to their higher
<t>In GNAP, key-bound access tokens are the default due to their higher security security properties. While
properties. While
bearer tokens can be used in GNAP, their use should be limited to cases where th e simplicity bearer tokens can be used in GNAP, their use should be limited to cases where th e simplicity
benefits outweigh the significant security downsides. One common deployment patt ern is to use a benefits outweigh the significant security downsides. One common deployment patt ern is to use a
gateway that takes in key-bound tokens on the outside, and verifies the signatur gateway that takes in key-bound tokens on the outside and verifies the signature
es on the incoming s on the incoming
requests, but translates the requests to a bearer token for use by trusted inter requests but translates the requests to a bearer token for use by trusted intern
nal systems. The al systems. The
bearer tokens are never issued or available outside of the internal systems, gre atly limiting the bearer tokens are never issued or available outside of the internal systems, gre atly limiting the
exposure of the less secure tokens but allowing the internal deployment to benef it from the exposure of the less-secure tokens but allowing the internal deployment to benef it from the
advantages of bearer tokens.</t> advantages of bearer tokens.</t>
</section>
</section> <section anchor="security-bound-tokens">
<section anchor="security-bound-tokens"><name>Key-Bound Access Tokens</name> <name>Key-Bound Access Tokens</name>
<t>Key-bound access tokens, as the name suggests, are bound to a specifi
<t>Key-bound access tokens, as the name suggests, are bound to a specific key an c key and must be
d must be
presented along with proof of that key during use. The key itself is not present ed at the same presented along with proof of that key during use. The key itself is not present ed at the same
time as the token, so even if a token value is captured, it cannot be used to ma ke a new request. This time as the token, so even if a token value is captured, it cannot be used to ma ke a new request. This
is particularly true for an RS, which will see the token value but will not see the keys used is particularly true for an RS, which will see the token value but will not see the keys used
to make the request (assuming asymmetric cryptography is in use, see <xref targe t="security-symmetric"/>).</t> to make the request (assuming asymmetric cryptography is in use, see <xref targe t="security-symmetric"/>).</t>
<t>Key-bound access tokens provide this additional layer of protection o
<t>Key-bound access tokens provide this additional layer of protection only when nly when the RS checks the
the RS checks the
signature of the message presented with the token. Acceptance of an invalid pres entation signature, signature of the message presented with the token. Acceptance of an invalid pres entation signature,
or failure to check the signature entirely, would allow an attacker to make call s with a captured or failure to check the signature entirely, would allow an attacker to make call s with a captured
access token without having access to the related signing key material.</t> access token without having access to the related signing key material.</t>
<t>In addition to validating the signature of the presentation message i
<t>In addition to validating the signature of the presentation message itself, tself,
the RS also needs to ensure that the signing key used is appropriate for the pre sented token. the RS also needs to ensure that the signing key used is appropriate for the pre sented token.
If an RS does not ensure that the right keys were used to sign a message with a specific If an RS does not ensure that the right keys were used to sign a message with a specific
token, an attacker would be able to capture an access token and sign the request with their own token, an attacker would be able to capture an access token and sign the request with their own
keys, thereby negating the benefits of using key-bound access tokens.</t> keys, thereby negating the benefits of using key-bound access tokens.</t>
<t>The RS also needs to ensure that sufficient portions of the message a
<t>The RS also needs to ensure that sufficient portions of the message are cover re covered by the
ed by the
signature. Any items outside the signature could still affect the API's processi ng decisions, signature. Any items outside the signature could still affect the API's processi ng decisions,
but these items would not be strongly bound to the token presentation. As such, an attacker but these items would not be strongly bound to the token presentation. As such, an attacker
could capture a valid request, then manipulate portions of the request outside o f the could capture a valid request and then manipulate portions of the request outsid e of the
signature envelope in order to cause unwanted actions at the protected API.</t> signature envelope in order to cause unwanted actions at the protected API.</t>
<t>Some key-bound tokens are susceptible to replay attacks, depending on
<t>Some key-bound tokens are susceptible to replay attacks, depending on the det the details of the signing method
ails of the signing method used. Therefore, key proofing mechanisms used with access tokens need
used. Key proofing mechanisms used with access tokens therefore need to use replay-protection mechanisms covered under the signature such as a per-me
to use replay protection mechanisms covered under the signature such as a per-me ssage nonce, a
ssage nonce, a
reasonably short time validity window, or other uniqueness constraints. The deta ils of using these reasonably short time validity window, or other uniqueness constraints. The deta ils of using these
will vary depending on the key proofing mechanism in use, but for example, HTTP will vary depending on the key proofing mechanism in use. For example, HTTP mess
Message Signatures age signatures
has both a <spanx style="verb">created</spanx> and <spanx style="verb">nonce</sp have both a <tt>created</tt> and <tt>nonce</tt> signature parameter as well as t
anx> signature parameter as well as the ability to cover significant he ability to cover significant
portions of the HTTP message. All of these can be used to limit the attack surfa ce.</t> portions of the HTTP message. All of these can be used to limit the attack surfa ce.</t>
</section>
</section> <section anchor="security-credentials">
<section anchor="security-credentials"><name>Exposure of End-user Credentials to <name>Exposure of End-User Credentials to Client Instance</name>
Client Instance</name> <t>As a delegation protocol, one of the main goals of GNAP is to prevent
the client software from being
<t>As a delegation protocol, one of the main goals of GNAP is to prevent the cli exposed to any credentials or information about the end user or RO as a requirem
ent software from being ent
exposed to any credentials or information about the end user or resource owner a of the delegation process. By using the variety of interaction mechanisms, the R
s a requirement O can
of the delegation process. By using the variety of interaction mechanisms, the r interact with the AS without ever authenticating to the client software and with
esource owner can out the client
interact with the AS without ever authenticating to the client software, and wit software having to impersonate the RO through replay of their credentials.</t>
hout the client <t>Consequently, no interaction methods defined in this specification re
software having to impersonate the resource owner through replay of their creden quire the end user to enter their
tials.</t>
<t>Consequently, no interaction methods defined in the GNAP core require the end
user to enter their
credentials, but it is technologically possible for an extension to be defined t o carry such values. credentials, but it is technologically possible for an extension to be defined t o carry such values.
Such an extension would be dangerous as it would allow rogue client software to directly collect, store, Such an extension would be dangerous as it would allow rogue client software to directly collect, store,
and replay the end user's credentials outside of any legitimate use within a GNA P request.</t> and replay the end user's credentials outside of any legitimate use within a GNA P request.</t>
<t>The concerns of such an extension could be mitigated through use of a
<t>The concerns of such an extension could be mitigated through use of a challen challenge and response
ge and response
unlocked by the end user's credentials. For example, the AS presents a challenge as part of unlocked by the end user's credentials. For example, the AS presents a challenge as part of
an interaction start method, and the client instance signs that challenge using a key derived an interaction start method, and the client instance signs that challenge using a key derived
from a password presented by the end user. It would be possible for the client s oftware to from a password presented by the end user. It would be possible for the client s oftware to
collect this password in a secure software enclave without exposing the password to the rest collect this password in a secure software enclave without exposing the password to the rest
of the client software or putting it across the wire to the AS. The AS can valid ate this challenge of the client software or putting it across the wire to the AS. The AS can valid ate this challenge
response against a known password for the identified end user. While an approach such as this does response against a known password for the identified end user. While an approach such as this does
not remove all of the concerns surrounding such a password-based scheme, it is a t least not remove all of the concerns surrounding such a password-based scheme, it is a t least
possible to implement in a more secure fashion than simply collecting and replay ing possible to implement in a more secure fashion than simply collecting and replay ing
the password. Even so, such schemes should only ever be used by trusted clients due to the password. Even so, such schemes should only ever be used by trusted clients due to
the ease of abusing them.</t> the ease of abusing them.</t>
</section>
</section> <section anchor="security-mixup">
<section anchor="security-mixup"><name>Mixing Up Authorization Servers</name> <name>Mixing Up Authorization Servers</name>
<t>If a client instance is able to work with multiple ASes simultaneousl
<t>If a client instance is able to work with multiple AS's simultaneously, it is y, it is possible
possible
for an attacker to add a compromised AS to the client instance's configuration a nd cause the for an attacker to add a compromised AS to the client instance's configuration a nd cause the
client software to start a request at the compromised AS. This AS could then pro xy the client's client software to start a request at the compromised AS. This AS could then pro xy the client's
request to a valid AS in order to attempt to get the resource owner to approve a ccess for request to a valid AS in order to attempt to get the RO to approve access for
the legitimate client instance.</t> the legitimate client instance.</t>
<t>A client instance needs to always be aware of which AS it is talking to throu ghout a grant process, and ensure <t>A client instance needs to always be aware of which AS it is talking to throughout a grant process and ensure
that any callback for one AS does not get conflated with the callback to differe nt AS. The interaction finish that any callback for one AS does not get conflated with the callback to differe nt AS. The interaction finish
hash calculation in <xref target="interaction-hash"/> allows a client instance t o protect against this kind of substitution, but only if hash calculation in <xref target="interaction-hash"/> allows a client instance t o protect against this kind of substitution, but only if
the client instance validates the hash. If the client instance does not use an i nteraction finish method the client instance validates the hash. If the client instance does not use an i nteraction finish method
or does not check the interaction finish hash value, the compromised AS can be g ranted a valid or does not check the interaction finish hash value, the compromised AS can be g ranted a valid
access token on behalf of the resource owner. See <xref target="AXELAND2021"/> f access token on behalf of the RO. See Sections 4.5.5 and 5.5 of <xref target="AX
or details ELAND2021"/> for details
of one such attack, which has been since addressed in this document by including of one such attack, which has been addressed in this document by including the g
the grant endpoint rant endpoint
in the interaction hash calculation. Note that the client instance still needs t o validate the hash for in the interaction hash calculation. Note that the client instance still needs t o validate the hash for
the attack to be prevented.</t> the attack to be prevented.</t>
</section>
</section> <section anchor="security-client-userinfo">
<section anchor="security-client-userinfo"><name>Processing of Client-Presented <name>Processing of Client-Presented User Information</name>
User Information</name> <t>GNAP allows the client instance to present assertions and identifiers
of the current user to the AS as
<t>GNAP allows the client instance to present assertions and identifiers of the
current user to the AS as
part of the initial request. This information should only ever be taken by the A S as a hint, since the part of the initial request. This information should only ever be taken by the A S as a hint, since the
AS has no way to tell if the represented person is present at the client softwar e, without using AS has no way to tell if the represented person is present at the client softwar e without using
an interaction mechanism. This information does not guarantee the given user is there, but it does an interaction mechanism. This information does not guarantee the given user is there, but it does
constitute a statement by the client software that the AS can take into account. </t> constitute a statement by the client software that the AS can take into account. </t>
<t>For example, if a specific user is claimed to be present prior to int
<t>For example, if a specific user is claimed to be present prior to interaction eraction, but a different user
, but a different user
is shown to be present during interaction, the AS can either determine this to b e an error or signal is shown to be present during interaction, the AS can either determine this to b e an error or signal
to the client instance through returned subject information that the current use r has changed from to the client instance through returned subject information that the current use r has changed from
what the client instance thought. This user information can also be used by the AS to streamline the what the client instance thought. This user information can also be used by the AS to streamline the
interaction process when the user is present. For example, instead of having the user type in their interaction process when the user is present. For example, instead of having the user type in their
account identifier during interaction at a redirected URI, the AS can immediatel y challenge the user account identifier during interaction at a redirected URI, the AS can immediatel y challenge the user
for their account credentials. Alternatively, if an existing session is detected , the AS can for their account credentials. Alternatively, if an existing session is detected , the AS can
determine that it matches the identifier provided by the client and subsequently skip an explicit determine that it matches the identifier provided by the client and subsequently skip an explicit
authentication event by the resource owner.</t> authentication event by the RO.</t>
<t>In cases where the AS trusts the client software more completely, due
<t>In cases where the AS trusts the client software more completely, due to poli to policy
cy or previous approval of a given client instance, the AS can take this user infor
or by previous approval of a given client instance, the AS can take this user in mation as a
formation as a
statement that the user is present and could issue access tokens and release sub ject information statement that the user is present and could issue access tokens and release sub ject information
without interaction. The AS should only take such action in very limited circums tances, as a without interaction. The AS should only take such action in very limited circums tances, as a
client instance could assert whatever it likes for the user's identifiers in its request. The AS client instance could assert whatever it likes for the user's identifiers in its request. The AS
can limit the possibility of this by issuing randomized opaque identifiers to cl ient instances to can limit the possibility of this by issuing randomized opaque identifiers to cl ient instances to
represent different end user accounts after an initial login.</t> represent different end-user accounts after an initial login.</t>
<t>When a client instance presents an assertion to the AS, the AS needs
<t>When a client instance presents an assertion to the AS, the AS needs to evalu to evaluate that assertion. Since
ate that assertion. Since
the AS is unlikely to be the intended audience of an assertion held by the clien t software, the AS will the AS is unlikely to be the intended audience of an assertion held by the clien t software, the AS will
need to evaluate the assertion in a different context. Even in this case, the AS can still evaluate need to evaluate the assertion in a different context. Even in this case, the AS can still evaluate
that the assertion was generated by a trusted party, was appropriately signed, a nd is within that the assertion was generated by a trusted party, was appropriately signed, a nd is within
any time validity windows stated by the assertion. If the client instance's audi ence identifier any time validity windows stated by the assertion. If the client instance's audi ence identifier
is known to the AS and can be associated with the client instance's presented ke y, the AS can also is known to the AS and can be associated with the client instance's presented ke y, the AS can also
evaluate that the appropriate client instance is presenting the claimed assertio n. All of this evaluate that the appropriate client instance is presenting the claimed assertio n. All of this
will prevent an attacker from presenting a manufactured assertion, or one captur ed from an will prevent an attacker from presenting a manufactured assertion or one capture d from an
untrusted system. However, without validating the audience of the assertion, a c aptured assertion untrusted system. However, without validating the audience of the assertion, a c aptured assertion
could be presented by the client instance to impersonate a given end user. In su ch cases, the assertion could be presented by the client instance to impersonate a given end user. In su ch cases, the assertion
offers little more protection than a simple identifier would.</t> offers little more protection than a simple identifier would.</t>
<t>A special case exists where the AS is the generator of the assertion
<t>A special case exists where the AS is the generator of the assertion being pr being presented by the
esented by the
client instance. In these cases, the AS can validate that it did issue the asser tion and client instance. In these cases, the AS can validate that it did issue the asser tion and
it is associated with the client instance presenting the assertion.</t> it is associated with the client instance presenting the assertion.</t>
</section>
</section> <section anchor="security-registration">
<section anchor="security-registration"><name>Client Instance Pre-registration</ <name>Client Instance Pre-registration</name>
name> <t>Each client instance is identified by its own unique key, and for som
e kinds of client software such as a
<t>Each client instance is identified by its own unique key, and for some kinds
of client software such as a
web server or backend system, this identification can be facilitated by register ing a single key for a piece web server or backend system, this identification can be facilitated by register ing a single key for a piece
of client software ahead of time. This registration can be associated with a set of display attributes to of client software ahead of time. This registration can be associated with a set of display attributes to
be used during the authorization process, identifying the client software to the user. In these cases, be used during the authorization process to identify the client software to the user. In these cases,
it can be assumed that only one instance of client software will exist, likely t o serve many different it can be assumed that only one instance of client software will exist, likely t o serve many different
users.</t> users.</t>
<t>A client's registration record needs to include its identifying key. Furtherm ore, it is the case that <t>A client's registration record needs to include its identifying key. Furtherm ore, it is the case that
any clients using symmetric cryptography for key proofing mechanisms need to hav e their keys pre-registered. any clients using symmetric cryptography for key proofing mechanisms need to hav e their keys pre-registered.
The registration should also include any information that would aid in the autho rization process, such as The registration should also include any information that would aid in the autho rization process, such as
a display name and logo. The registration record can also limit a given client t a display name and logo.
o ask for certain The registration record can also limit a given client to
kinds of information and access, or be limited to specific interaction mechanism ask for certain kinds of information or use
s at runtime.</t> specific interaction mechanisms at runtime.
</t>
<t>It also is sensible to pre-register client instances when the software is act ing autonomously, without <t>It also is sensible to pre-register client instances when the software is act ing autonomously, without
the need for a runtime approval by a resource owner or any interaction with an e the need for a runtime approval by an RO or any interaction with an end user. In
nd user. In these cases, these cases,
an AS needs to rest on the trust decisions that have been determined prior to ru an AS needs to rely on the trust decisions that have been determined prior to ru
ntime in determining ntime to determine
what rights and tokens to grant to a given client instance.</t> what rights and tokens to grant to a given client instance.</t>
<t>However, it does not make sense to pre-register many types of clients
<t>However, it does not make sense to pre-register many types of clients. Single . Single-page applications (SPAs) and
-page applications (SPAs) and
mobile/desktop applications in particular present problems with pre-registration . For SPAs, the instances mobile/desktop applications in particular present problems with pre-registration . For SPAs, the instances
are ephemeral in nature and long-term registration of a single instance leads to significant storage and are ephemeral in nature, and long-term registration of a single instance leads t o significant storage and
management overhead at the AS. For mobile applications, each installation of the client software is management overhead at the AS. For mobile applications, each installation of the client software is
a separate instance, and sharing a key among all instances would be detrimental to security as the a separate instance, and sharing a key among all instances would be detrimental to security as the
compromise of any single installation would compromise all copies for all users. </t> compromise of any single installation would compromise all copies for all users. </t>
<t>An AS can treat these classes of client software differently from eac
<t>An AS can treat these classes of client software differently from each other, h other, perhaps by allowing access
perhaps by allowing access to certain high-value APIs only to pre-registered known clients or by requiring
to certain high-value APIs only to pre-registered known clients, or by requiring an active end-user
an active end user
delegation of authority to any client software not pre-registered.</t> delegation of authority to any client software not pre-registered.</t>
<t>An AS can also provide warnings and caveats to ROs during the authori
<t>An AS can also provide warnings and caveats to resource owners during the aut zation process, allowing
horization process, allowing
the user to make an informed decision regarding the software they are authorizin g. For example, if the AS the user to make an informed decision regarding the software they are authorizin g. For example, if the AS
has done vetting of the client software and this specific instance, it can prese nt a different authorization has vetted the client software and this specific instance, it can present a diff erent authorization
screen compared to a client instance that is presenting all of its information a t runtime.</t> screen compared to a client instance that is presenting all of its information a t runtime.</t>
<t>Finally, an AS can use platform attestations and other signals from t
<t>Finally, an AS can use platform attestations and other signals from the clien he client instance at runtime
t instance at runtime to determine whether or not the software making the request is legitimate. The d
to determine whether the software making the request is legitimate or not. The d etails of such
etails of such attestations are outside the scope of this specification, but the <tt>client</tt
attestations are outside the scope of the core protocol, but the <spanx style="v > portion of a grant request
erb">client</spanx> portion of a grant request provides a natural extension point to such information through the "GNAP Client
provides a natural extension point to such information through the <xref target= Instance Fields" registry (<xref target="IANA-client-instance"> </xref>).</t>
"IANA-client-instance">Client Instance Fields registry</xref>.</t> </section>
<section anchor="security-impersonation">
</section> <name>Client Instance Impersonation</name>
<section anchor="security-impersonation"><name>Client Instance Impersonation</na <t>If client instances are allowed to set their own user-facing display
me> information, such as a display name and website
<t>If client instances are allowed to set their own user-facing display informat
ion, such as a display name and website
URL, a malicious client instance could impersonate legitimate client software fo r the purposes of tricking URL, a malicious client instance could impersonate legitimate client software fo r the purposes of tricking
users into authorizing the malicious client.</t> users into authorizing the malicious client.</t>
<t>Requiring clients to pre-register does not fully mitigate this proble
<t>Requiring clients to pre-register does not fully mitigate this problem since m since many pre-registration
many pre-registration
systems have self-service portals for management of client registration, allowin g authenticated developers systems have self-service portals for management of client registration, allowin g authenticated developers
to enter self-asserted information into the management portal.</t> to enter self-asserted information into the management portal.</t>
<t>An AS can mitigate this by actively filtering all self-asserted value
<t>An AS can mitigate this by actively filtering all self-asserted values presen s presented by client software,
ted by client software,
both dynamically as part of GNAP and through a registration portal, to limit the kinds of impersonation that both dynamically as part of GNAP and through a registration portal, to limit the kinds of impersonation that
would be done.</t> could be done.</t>
<t>An AS can also warn the RO about the provenance of the information it
<t>An AS can also warn the resource owner about the provenance of the informatio is displaying, allowing
n it is displaying, allowing the RO to make a more informed delegation decision. For example, an AS can visua
the resource owner to make a more informed delegation decision. For example, an lly differentiate
AS can visually differentiate
between a client instance that can be traced back to a specific developer's regi stration and an between a client instance that can be traced back to a specific developer's regi stration and an
instance that has self-asserted its own display information.</t> instance that has self-asserted its own display information.</t>
</section>
</section> <section anchor="security-client-hosted-logo">
<section anchor="security-client-hosted-logo"><name>Client-Hosted Logo URI</name <name>Client-Hosted Logo URI</name>
> <t>The <tt>logo_uri</tt> client display field defined in <xref target="r
equest-display"/> allows the client instance to specify
<t>The <spanx style="verb">logo_uri</spanx> client display field defined in <xre
f target="request-display"/> allows the client instance to specify
a URI from which an image can be fetched for display during authorization decisi ons. When the URI points to a URI from which an image can be fetched for display during authorization decisi ons. When the URI points to
an externally hosted resource (as opposed to a data: URI), the <spanx style="ver b">logo_uri</spanx> field presents challenges in addition to the an externally hosted resource (as opposed to a data: URI), the <tt>logo_uri</tt> field presents challenges in addition to the
considerations in <xref target="security-impersonation"/>.</t> considerations in <xref target="security-impersonation"/>.</t>
<t>When a <tt>logo_uri</tt> is externally hosted, the client software (o
<t>When a <spanx style="verb">logo_uri</spanx> is externally hosted, the client r the host of the asset) can change the contents of
software (or the host of the asset) can change the contents of
the logo without informing the AS. Since the logo is considered an aspect of the client software's identity, the logo without informing the AS. Since the logo is considered an aspect of the client software's identity,
this flexibility allows for a more dynamically-managed client instance that make this flexibility allows for a more dynamically managed client instance that make
s use of the distributed systems.</t> s use of the distributed systems.</t>
<t>However, this same flexibility allows the host of the asset to change the hos ted file in a malicious way, <t>However, this same flexibility allows the host of the asset to change the hos ted file in a malicious way,
such as replacing the image content with malicious software for download or imit ating a different piece such as replacing the image content with malicious software for download or imit ating a different piece
of client software. Additionally, the act of fetching the URI could accidentally leak information to the image host of client software. Additionally, the act of fetching the URI could accidentally leak information to the image host
in the HTTP Referer header field, if one is sent. Even though GNAP intentionally does not include security in the HTTP Referer header field, if one is sent. Even though GNAP intentionally does not include security
parameters in front-channel URI's wherever possible, the AS still should take st eps to ensure that parameters in front-channel URIs wherever possible, the AS still should take ste ps to ensure that
this information does not leak accidentally, such as setting a referrer policy o n image links or this information does not leak accidentally, such as setting a referrer policy o n image links or
displaying images only from paged served from a URI with no sensitive security o displaying images only from pages served from a URI with no sensitive security o
r identity information.</t> r identity information.</t>
<t>To avoid these issues, the AS can insist on the use of data: URIs, th
<t>To avoid these issues, the AS can insist on the use of data: URIs, though tha ough that might not be practical for all
t might not be practical for all
types of client software. Alternatively, the AS could pre-fetch the content of t he URI and present its own copy types of client software. Alternatively, the AS could pre-fetch the content of t he URI and present its own copy
to the resource owner instead. This practice opens the AS to potential SSRF atta to the RO instead. This practice opens the AS to potential SSRF attacks, as disc
cks, as discussed in <xref target="security-ssrf"/>.</t> ussed in <xref target="security-ssrf"/>.</t>
</section>
</section> <section anchor="security-browser-interception">
<section anchor="security-browser-interception"><name>Interception of Informatio <name>Interception of Information in the Browser</name>
n in the Browser</name> <t>Most information passed through the web browser is susceptible to int
erception and possible manipulation by
<t>Most information passed through the web-browser is susceptible to interceptio
n and possible manipulation by
elements within the browser such as scripts loaded within pages. Information in the URI is exposed elements within the browser such as scripts loaded within pages. Information in the URI is exposed
through browser and server logs, and can also leak to other parties through HTTP through browser and server logs, and it can also leak to other parties through H
<spanx style="verb">Referer</spanx> headers.</t> TTP <tt>Referer</tt> headers.</t>
<t>GNAP's design limits the information passed directly through the brow
<t>GNAP's design limits the information passed directly through the browser, all ser, allowing for opaque URIs in most circumstances.
owing for opaque URIs in most circumstances.
For the redirect-based interaction finish mechanism, named query parameters are used to carry For the redirect-based interaction finish mechanism, named query parameters are used to carry
unguessable opaque values. For these, GNAP requires creation and validation of a cryptographic unguessable opaque values. For these, GNAP requires creation and validation of a cryptographic
hash to protect the query parameters added to the URI and associate them with an ongoing grant hash to protect the query parameters added to the URI and associate them with an ongoing grant
process and values not passed in the URI. The client instance has to properly va lidate this hash to prevent an attacker from process and values not passed in the URI. The client instance has to properly va lidate this hash to prevent an attacker from
injecting an interaction reference intended for a different AS or client instanc e.</t> injecting an interaction reference intended for a different AS or client instanc e.</t>
<t>Several interaction start mechanisms use URIs created by the AS and p
<t>Several interaction start mechanisms use URIs created by the AS and passed to assed to the client instance.
the client instance.
While these URIs are opaque to the client instance, it's possible for the AS to include parameters, While these URIs are opaque to the client instance, it's possible for the AS to include parameters,
paths, and other pieces of information that could leak security data or be manip ulated by a party paths, and other pieces of information that could leak security data or be manip ulated by a party
in the middle of the transaction. An AS implementation can avoid this problem by creating URIs in the middle of the transaction. An AS implementation can avoid this problem by creating URIs
using unguessable values that are randomized for each new grant request.</t> using unguessable values that are randomized for each new grant request.</t>
</section>
</section> <section anchor="security-callback-uri">
<section anchor="security-callback-uri"><name>Callback URI Manipulation</name> <name>Callback URI Manipulation</name>
<t>The callback URI used in interaction finish mechanisms is defined by
<t>The callback URI used in interaction finish mechanisms is defined by the clie the client instance. This URI is
nt instance. This URI is opaque to the AS but can contain information relevant to the client instance's o
opaque to the AS, but can contain information relevant to the client instance's perations. In
operations. In
particular, the client instance can include state information to allow the callb ack request to particular, the client instance can include state information to allow the callb ack request to
be associated with an ongoing grant request.</t> be associated with an ongoing grant request.</t>
<t>Since this URI is exposed to the end user's browser, it is susceptibl
<t>Since this URI is exposed to the end user's browser, it is susceptible to bot e to both logging and manipulation
h logging and manipulation
in transit before the request is made to the client software. As such, a client instance should in transit before the request is made to the client software. As such, a client instance should
never put security-critical or private information into the callback URI in a cl eartext form. For example, never put security-critical or private information into the callback URI in a cl eartext form. For example,
if the client software includes a post-redirect target URI in its callback URI t o the AS, this target URI if the client software includes a post-redirect target URI in its callback URI t o the AS, this target URI
could be manipulated by an attacker, creating an open redirector at the client. Instead, could be manipulated by an attacker, creating an open redirector at the client. Instead,
a client instance can use an unguessable identifier in the URI that can then be used by the client a client instance can use an unguessable identifier in the URI that can then be used by the client
software to look up the details of the pending request. Since this approach requ ires some form of statefulness software to look up the details of the pending request. Since this approach requ ires some form of statefulness
by the client software during the redirection process, clients that are not capa ble of holding state by the client software during the redirection process, clients that are not capa ble of holding state
through a redirect should not use redirect-based interaction mechanisms.</t> through a redirect should not use redirect-based interaction mechanisms.</t>
</section>
<section anchor="security-redirect-status-codes">
<name>Redirection Status Codes</name>
</section> <t>As described in <xref
<section anchor="security-redirect-status-codes"><name>Redirection Status Codes< target="I-D.ietf-oauth-security-topics"/>, a server should never use
/name> HTTP status code 307 (Temporary Redirect) to redirect a request that pot
entially
<t>As already described in <xref target="I-D.ietf-oauth-security-topics"/>, a se contains user credentials. If an HTTP redirect is used for such a
rver should never use the HTTP 307 request, HTTP status code 303 (See Other) should be used
status code to redirect a request that potentially contains user credentials. If instead.</t>
an HTTP redirect <t>Status code 307 (Temporary Redirect), as defined in the HTTP
is used for such a request, the HTTP status code 303 "See Other" should be used standard <xref target="RFC9110"/>, requires the user agent to preserve
instead.</t> the method and content of a request, thus submitting the content of
the POST request to the redirect target. In the HTTP standard <xref
<t>The status code 307, as defined in the HTTP standard <xref target="HTTP"/>, r target="RFC9110"/>, only status code 303 (See Other) unambiguously
equires the user agent enforces rewriting the HTTP POST request to an HTTP GET request, which
to preserve the method and content of a request, thus submitting the content of eliminates the POST content from the redirected request. For all
the POST other status codes, including status code 302 (Found), user agents are
request to the redirect target. In the HTTP standard <xref target="HTTP"/>, only allowed to keep a redirected POST request as a POST and thus can
the status code 303 unambiguously enforces resubmit the content.
rewriting the HTTP POST request to an HTTP GET request, which eliminates the POS </t>
T content from the redirected request. For all other status codes, including
status code 302, user agents are allowed not to rewrite a POST request into a GE
T request and thus
to resubmit the contents.</t>
<t>The use of status code 307 results in a vulnerability when using the <t>The use of status code 307 (Temporary Redirect) results in a vulnerability wh
<xref target="response-interact-finish"><spanx style="verb">redirect</spanx> int en using the
eraction finish method</xref>. With this method, the AS <tt>redirect</tt> interaction finish method (<xref target="response-interact-fin
ish"> </xref>). With this method, the AS
potentially prompts the RO to enter their credentials in a form that is then sub mitted back to the potentially prompts the RO to enter their credentials in a form that is then sub mitted back to the
AS (using an HTTP POST request). The AS checks the credentials and, if successfu AS (using an HTTP POST request). The AS checks the credentials and, if successfu
l, may directly l, may immediately
redirect the RO to the client instance's redirect URI. Due to the use of status redirect the RO to the client instance's redirect URI. Due to the use of status
code 307, the RO's code 307 (Temporary Redirect), the RO's
user agent now transmits the RO's credentials to the client instance. A maliciou s client instance user agent now transmits the RO's credentials to the client instance. A maliciou s client instance
can then use the obtained credentials to impersonate the RO at the AS.</t> can then use the obtained credentials to impersonate the RO at the AS.</t>
<t>Redirection away from the initial URI in an interaction session could
<t>Redirection away from the initial URI in an interaction session could also le also leak information found in that
ak information found in that
initial URI through the HTTP Referer header field, which would be sent by the us er agent to the redirect initial URI through the HTTP Referer header field, which would be sent by the us er agent to the redirect
target. To avoid such leakage, a server can first redirect to an internal inters titial page without any identifying target. To avoid such leakage, a server can first redirect to an internal inters titial page without any identifying
or sensitive information on the URI before processing the request. When the user agent is ultimately or sensitive information on the URI before processing the request. When the user agent is ultimately
redirected from this page, no part of the original interaction URI will be found in the Referer header.</t> redirected from this page, no part of the original interaction URI will be found in the Referer header.</t>
</section>
</section> <section anchor="security-as-response">
<section anchor="security-as-response"><name>Interception of Responses from the <name>Interception of Responses from the AS</name>
AS</name> <t>Responses from the AS contain information vital to both the security
and privacy operations of
<t>Responses from the AS contain information vital to both the security and priv GNAP. This information includes nonces used in cryptographic calculations, Subje
acy operations of ct Identifiers,
GNAP. This information includes nonces used in cryptographic calculations, subje
ct identifiers,
assertions, public keys, and information about what client software is requestin g and was granted.</t> assertions, public keys, and information about what client software is requestin g and was granted.</t>
<t>In addition, if bearer tokens are used or keys are issued alongside a
<t>In addition, if bearer tokens are used or keys are issued alongside a bound a bound access token, the
ccess token, the
response from the AS contains all information necessary for use of the contained access token. Any response from the AS contains all information necessary for use of the contained access token. Any
party that is capable of viewing such a response, such as an intermediary proxy, would be able party that is capable of viewing such a response, such as an intermediary proxy, would be able
to exfiltrate and use this token. If the access token is instead bound to the cl ient instance's to exfiltrate and use this token. If the access token is instead bound to the cl ient instance's
presented key, intermediaries no longer have sufficient information to use the t oken. They can presented key, intermediaries no longer have sufficient information to use the t oken. They can
still, however, gain information about the end user as well as the actions of th e client software.</t> still, however, gain information about the end user as well as the actions of th e client software.</t>
</section>
</section> <section anchor="security-key-distribution">
<section anchor="security-key-distribution"><name>Key Distribution</name> <name>Key Distribution</name>
<t>GNAP does not define ways for the client instances keys to be provide
<t>GNAP does not define ways for the client instances keys to be provided to the d to the client instances,
client instances,
particularly in light of how those keys are made known to the AS. These keys cou ld be particularly in light of how those keys are made known to the AS. These keys cou ld be
generated dynamically on the client software or pre-registered at the AS in a st atic developer portal. generated dynamically on the client software or pre-registered at the AS in a st atic developer portal.
The keys for client instances could also be distributed as part of the deploymen t process of instances The keys for client instances could also be distributed as part of the deploymen t process of instances
of the client software. For example, an application installation framework could generate of the client software. For example, an application installation framework could generate
a keypair for each copy of client software, then both install it into the client a key pair for each copy of client software and then both install it into the cl
software ient software
upon installation and registering that instance with the AS.</t> upon installation and register that instance with the AS.</t>
<t>Alternatively, it's possible for the AS to generate keys to be used w
<t>Alternatively, it's possible for the AS to generate keys to be used with acce ith access tokens that
ss tokens that
are separate from the keys used by the client instance to request tokens. In thi s method, are separate from the keys used by the client instance to request tokens. In thi s method,
the AS would generate the asymmetric keypair or symmetric key and return the pub the AS would generate the asymmetric key pair or symmetric key and return the pu
lic key or key blic key or key
reference, to the client instance alongside the access reference to the client instance alongside the access
token itself. The means for the AS to return generated key values to the client instance token itself. The means for the AS to return generated key values to the client instance
are out of scope, since GNAP does not allow the transmission of private or share d key are out of scope, since GNAP does not allow the transmission of private or share d key
information within the protocol itself.</t> information within the protocol itself.</t>
<t>Additionally, if the token is bound to a key other than the client in
<t>Additionally, if the token is bound to a key other than the client instance's stance's presented key, this
presented key, this opens a possible attack surface for an attacker's AS to request an access token
opens a possible attack surface for an attacker's AS to request an access token and then substitute
then substitute
their own key material in the response to the client instance. The attacker's AS would need to their own key material in the response to the client instance. The attacker's AS would need to
be able to use the same key as the client instance, but this setup would allow a n attacker's AS be able to use the same key as the client instance, but this setup would allow a n attacker's AS
to make use of a compromised key within a system. This attack can be prevented b y only binding to make use of a compromised key within a system. This attack can be prevented b y only binding
access tokens to the client instance's presented keys, and by having client inst ances have a strong access tokens to the client instance's presented keys and by having client insta nces have a strong
association between which keys they expect to use and the AS they expect to use them on. association between which keys they expect to use and the AS they expect to use them on.
This attack is also only able to be propagated on client instances that talk to more than This attack is also only able to be propagated on client instances that talk to more than
one AS at runtime, which can be limited by the client software.</t> one AS at runtime, which can be limited by the client software.</t>
</section>
<section anchor="security-key-rotation">
<name>Key Rotation Policy</name>
<t>When keys are rotated, there could be a delay in the propagation of t
hat rotation to various components in the AS's ecosystem. The AS can define its
own policy regarding the timeout of the previously bound key, either making it i
mmediately obsolete or allowing for a limited grace period during which both the
previously bound key and the current key can be used for signing requests. Such
a grace period can be useful when there are multiple running copies of the clie
nt that are coordinated with each other. For example, the client software could
be deployed as a cloud service with multiple orchestrated nodes. Each of these c
opies is deployed using the same key; therefore, all the nodes represent the sam
e client instance to the AS. In such cases, it can be difficult, or even impossi
ble, to update the keys on all these copies in the same instant.</t>
</section> <t>The need to accommodate such known delays in the system needs to be b
<section anchor="security-key-rotation"><name>Key Rotation Policy</name> alanced with the risk of allowing an old key to still be used. Narrowly restrict
ing the exposure opportunities for exploit at the AS in terms of time, place, an
<t>When keys are rotated, there could be a delay in the propagation of that rota d method makes exploit significantly more difficult, especially if the exception
tion to various components in the AS's ecosystem. The AS can define its own poli happens only once. For example, the AS can reject requests from the previously
cy regarding the timeout of the previously-bound key, either making it immediate bound key (or any previous one before it) to cause rotation to a new key or at l
ly obsolete or allowing for a limited grace period during which both the previou east ensure that the rotation happens in an idempotent way to the same new key.<
sly-bound key and the current key can be used for signing requests. Such a grace /t>
period can be useful when there are multiple running copies of the client that <t>See also the related considerations for token values in <xref target=
are coordinated with each other. For example, the client software could be deplo "security-network-management"/>.</t>
yed as a cloud service with multiple orchestrated nodes. Each of these copies is </section>
deployed using the same key and therefore all the nodes represent the same clie <section anchor="security-polling">
nt instance to the AS. In such cases, it can be difficult, or even impossible, t <name>Interaction Finish Modes and Polling</name>
o update the keys on all these copies in the same instant.</t> <t>During the interaction process, the client instance usually hands con
trol of the user experience
<t>The need for accommodating such known delays in the system needs to be balanc
ed with the risk of allowing an old key to still be used. Narrowly restricting t
he exposure opportunities for exploit at the AS in terms of time, place, and met
hod makes exploit significantly more difficult, especially if the exception happ
ens only once. For example, the AS can reject requests from the previously-bound
key (or any previous one before it) to cause rotation to a new key, or at least
ensure that the rotation happens in an idempotent way to the same new key.</t>
<t>See also the related considerations for token values in <xref target="securit
y-network-management"/>.</t>
</section>
<section anchor="security-polling"><name>Interaction Finish Modes and Polling</n
ame>
<t>During the interaction process, the client instance usually hands control of
the user experience
over to another component, be it the system browser, another application, or som e action over to another component, be it the system browser, another application, or som e action
the resource owner is instructed to take on another device. By using an interact ion finish the RO is instructed to take on another device. By using an interaction finish
method, the client instance can be securely notified by the AS when the interact ion is completed method, the client instance can be securely notified by the AS when the interact ion is completed
and the next phase of the protocol should occur. This process includes informati on that the and the next phase of the protocol should occur. This process includes informati on that the
client instance can use to validate the finish call from the AS and prevent some injection, client instance can use to validate the finish call from the AS and prevent some injection,
session hijacking, and phishing attacks.</t> session hijacking, and phishing attacks.</t>
<t>Some types of client deployment are unable to receive an interaction
<t>Some types of client deployment are unable to receive an interaction finish m finish message.
essage.
Without an interaction finish method to notify it, the client instance will need to poll the Without an interaction finish method to notify it, the client instance will need to poll the
grant continuation API while waiting for the resource owner to approve or deny t he request. grant continuation API while waiting for the RO to approve or deny the request.
An attacker could take advantage of this situation by capturing the interaction start An attacker could take advantage of this situation by capturing the interaction start
parameters and phishing a legitimate user into authorizing the attacker's waitin g parameters and phishing a legitimate user into authorizing the attacker's waitin g
client instance, which would in turn have no way of associating the completed in teraction client instance, which would in turn have no way of associating the completed in teraction
from the targeted user with the start of the request from the attacker.</t> from the targeted user with the start of the request from the attacker.</t>
<t>However, it is important to note that this pattern is practically ind
<t>However, it is important to note that this pattern is practically indistingui istinguishable
shable
from some legitimate use cases. For example, a smart device emits a code for from some legitimate use cases. For example, a smart device emits a code for
the resource owner to enter on a separate device. The smart device has to poll the RO to enter on a separate device. The smart device has to poll
because the expected behavior is that the interaction will take place on the sep arate because the expected behavior is that the interaction will take place on the sep arate
device, without a way to return information to the original device's context.</t > device, without a way to return information to the original device's context.</t >
<t>As such, developers need to weigh the risks of forgoing an interactio
<t>As such, developers need to weigh the risks of forgoing an interaction finish n finish
method against the deployment capabilities of the client software and its method against the deployment capabilities of the client software and its
environment. Due to the increased security, an interaction finish method should environment. Due to the increased security, an interaction finish method should
be employed whenever possible.</t> be employed whenever possible.</t>
</section>
</section> <section anchor="security-sessions">
<section anchor="security-sessions"><name>Session Management for Interaction Fin <name>Session Management for Interaction Finish Methods</name>
ish Methods</name> <t>When using an interaction finish method such as <tt>redirect</tt> or
<tt>push</tt>, the client instance receives
<t>When using an interaction finish method such as <spanx style="verb">redirect<
/spanx> or <spanx style="verb">push</spanx>, the client instance receives
an unsolicited inbound request from an unknown party over HTTPS. The client an unsolicited inbound request from an unknown party over HTTPS. The client
instance needs to be able to successfully associate this incoming request with a specific pending instance needs to be able to successfully associate this incoming request with a specific pending
grant request being managed by the client instance. If the client instance is no t careful and precise about grant request being managed by the client instance. If the client instance is no t careful and precise about
this, an attacker could associate their own session at the client instance with a stolen interaction this, an attacker could associate their own session at the client instance with a stolen interaction
response. The means of preventing this varies by the type of client software and interaction methods in use. response. The means of preventing this vary by the type of client software and i nteraction methods in use.
Some common patterns are enumerated here.</t> Some common patterns are enumerated here.</t>
<t>If the end user interacts with the client instance through a web brow
<t>If the end user interacts with the client instance through a web browser and ser and the <tt>redirect</tt>
the <spanx style="verb">redirect</spanx>
interaction finish method is used, the client instance can ensure that the incom ing HTTP request interaction finish method is used, the client instance can ensure that the incom ing HTTP request
from the finish method is presented in the same browser session that the grant r equest was from the finish method is presented in the same browser session that the grant r equest was
started in. This technique is particularly useful when the <spanx style="verb">r started in. This technique is particularly useful when the <tt>redirect</tt> int
edirect</spanx> interaction start mode eraction start mode
is used as well, since in many cases the end user will follow the redirection wi is used as well, since in many cases, the end user will follow the redirection w
th the ith the
same browser that they are using to interact with the client instance. same browser that they are using to interact with the client instance.
The client instance can then store the relevant pending grant information in the The client instance can then store the relevant pending grant information in the
session, either in the browser storage directly (such as with a single-page appl ication) or session, either in the browser storage directly (such as with a single-page appl ication) or
in an associated session store on a back-end server. In both cases, when the inc oming request in an associated session store on a backend server. In both cases, when the inco ming request
reaches the client instance, the session information can be used to ensure that the same party reaches the client instance, the session information can be used to ensure that the same party
that started the request is present as the request finishes.</t> that started the request is present as the request finishes.</t>
<t>Ensuring that the same party that started a request is present when t
<t>Ensuring that the same party that started a request is present when that requ hat request finishes can
est finishes can
prevent phishing attacks, where an attacker starts a request at an honest client instance and prevent phishing attacks, where an attacker starts a request at an honest client instance and
tricks an honest RO into authorizing it. For example, if an honest end user (tha t also acts as the tricks an honest RO into authorizing it. For example, if an honest end user (tha t also acts as the
RO) wants to start a request through a client instance controlled by the attacke r, the attacker can RO) wants to start a request through a client instance controlled by the attacke r, the attacker can
start a request at an honest client instance and then redirect the honest end us er to the start a request at an honest client instance and then redirect the honest end us er to the
interaction URI from the attackers session with the honest client instance. If t he honest end user interaction URI from the attackers session with the honest client instance. If t he honest end user
then fails to realize that they are not authorizing the attacker-controlled clie nt instance (with which then fails to realize that they are not authorizing the attacker-controlled clie nt instance (with which
it started its request) but instead the honest client instance when interacting with the AS, the attacker's it started its request) but instead the honest client instance when interacting with the AS, the attacker's
session with the honest client instance would be authorized. This would give the attacker access to session with the honest client instance would be authorized. This would give the attacker access to
the honest end user's resources that the honest client instance is authorized to access. However, the honest end user's resources that the honest client instance is authorized to access. However,
if after the interaction the AS redirects the honest end user back to the client instance whose if after the interaction, the AS redirects the honest end user back to the clien t instance whose
grant request the end user just authorized, the honest end user is redirected to the honest client grant request the end user just authorized, the honest end user is redirected to the honest client
instance. The honest client instance can then detect that the end user is not th e party that started the instance. The honest client instance can then detect that the end user is not th e party that started the
request, since the request at the honest client instance was started by the request, since the request at the honest client instance was started by the
attacker. This detection can prevent the attack. This is related to the discussi on in <xref target="security-impersonation"/>, because again attacker. This detection can prevent the attack. This is related to the discussi on in <xref target="security-impersonation"/>, because again
the attack can be prevented by the AS informing the user as much as possible abo ut the client the attack can be prevented by the AS informing the user as much as possible abo ut the client
instance that is to be authorized.</t> instance that is to be authorized.</t>
<t>If the end user does not interact with the client instance through a
<t>If the end user does not interact with the client instance through a web brow web browser or the interaction
ser or the interaction
start method does not use the same browser or device that the end user is intera cting through start method does not use the same browser or device that the end user is intera cting through
(such as the launch of a second device through a scannable code or presentation of a user code) the (such as the launch of a second device through a scannable code or presentation of a user code), the
client instance will not be able to strongly associate an incoming HTTP request with an established client instance will not be able to strongly associate an incoming HTTP request with an established
session with the end user. This is also true when the <spanx style="verb">push</ spanx> interaction finish method is used, session with the end user. This is also true when the <tt>push</tt> interaction finish method is used,
since the HTTP request comes directly from the interaction component of the AS. In these since the HTTP request comes directly from the interaction component of the AS. In these
circumstances, the client instance can at least ensure that the incoming HTTP circumstances, the client instance can at least ensure that the incoming HTTP
request can be uniquely associated with an ongoing grant request by making the i nteraction finish request can be uniquely associated with an ongoing grant request by making the i nteraction finish
callback URI unique for the grant when making the <xref target="request-interact -finish">interaction request</xref>. callback URI unique for the grant when making the interaction request (<xref tar get="request-interact-finish"> </xref>).
Mobile applications and other client instances that generally serve only a singl e end user at a time Mobile applications and other client instances that generally serve only a singl e end user at a time
can use this unique incoming URL to differentiate between a legitimate incoming request and can use this unique incoming URL to differentiate between a legitimate incoming request and
an attacker's stolen request.</t> an attacker's stolen request.</t>
</section>
</section> <section anchor="security-interact-hash">
<section anchor="security-interact-hash"><name>Calculating Interaction Hash</nam <name>Calculating Interaction Hash</name>
e> <t>While the use of GNAP's signing mechanisms and token-protected grant
API provides
<t>While the use of GNAP's signing mechanisms and token-protected grant API prov
ides
significant security protections to the protocol, the interaction reference mech anism significant security protections to the protocol, the interaction reference mech anism
is susceptible to monitoring, capture, and injection by an attacker. To combat t his, GNAP is susceptible to monitoring, capture, and injection by an attacker. To combat t his, GNAP
requires the calculation and verification of an interaction hash. A client insta nce requires the calculation and verification of an interaction hash. A client insta nce
might be tempted to skip this step, but doing so leaves the client instance open to might be tempted to skip this step, but doing so leaves the client instance open to
injection and manipulation by an attacker that could lead to additional issues.< /t> injection and manipulation by an attacker that could lead to additional issues.< /t>
<t>The calculation of the interaction hash value provides defense in dep
<t>The calculation of the interaction hash value provides defense in depth, allo th, allowing a client
wing a client
instance to protect itself from spurious injection of interaction references whe n using an instance to protect itself from spurious injection of interaction references whe n using an
interaction finish method. The AS is protected during this attack through the interaction finish method. The AS is protected during this attack through the
continuation access token being bound to the expected interaction reference, continuation access token being bound to the expected interaction reference,
but without hash calculation, the attacker could cause the client to make an but without hash calculation, the attacker could cause the client to make an
HTTP request on command, which could itself be manipulated -- for example, by in cluding HTTP request on command, which could itself be manipulated -- for example, by in cluding
a malicious value in the interaction reference designed to attack the AS. a malicious value in the interaction reference designed to attack the AS.
With both of these in place, an attacker attempting to substitute the interactio n reference With both of these in place, an attacker attempting to substitute the interactio n reference
is stopped in several places.</t> is stopped in several places.</t>
<figure>
<figure title="Figure 11: Interaction hash attack"><artset><artwork type="svg"> <name>Interaction Hash Attack</name>
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" height="448" width="456" v <artset>
iewBox="0 0 456 448" class="diagram" text-anchor="middle" font-family="monospace <artwork type="svg"><svg xmlns="http://www.w3.org/2000/svg" version=
" font-size="13px" stroke-linecap="round"> "1.1" height="448" width="456" viewBox="0 0 456 448" class="diagram" text-anchor
<path d="M 8,48 L 8,416" fill="none" stroke="black"/> ="middle" font-family="monospace" font-size="13px" stroke-linecap="round">
<path d="M 64,48 L 64,416" fill="none" stroke="black"/> <path d="M 8,48 L 8,416" fill="none" stroke="black"/>
<path d="M 120,48 L 120,224" fill="none" stroke="black"/> <path d="M 64,48 L 64,416" fill="none" stroke="black"/>
<path d="M 120,256 L 120,272" fill="none" stroke="black"/> <path d="M 120,48 L 120,224" fill="none" stroke="black"/>
<path d="M 120,336 L 120,368" fill="none" stroke="black"/> <path d="M 120,256 L 120,272" fill="none" stroke="black"/>
<path d="M 120,400 L 120,416" fill="none" stroke="black"/> <path d="M 120,336 L 120,368" fill="none" stroke="black"/>
<path d="M 192,48 L 192,224" fill="none" stroke="black"/> <path d="M 120,400 L 120,416" fill="none" stroke="black"/>
<path d="M 192,256 L 192,272" fill="none" stroke="black"/> <path d="M 192,48 L 192,224" fill="none" stroke="black"/>
<path d="M 192,336 L 192,368" fill="none" stroke="black"/> <path d="M 192,256 L 192,272" fill="none" stroke="black"/>
<path d="M 192,400 L 192,416" fill="none" stroke="black"/> <path d="M 192,336 L 192,368" fill="none" stroke="black"/>
<path d="M 248,32 L 248,160" fill="none" stroke="black"/> <path d="M 192,400 L 192,416" fill="none" stroke="black"/>
<path d="M 248,224 L 248,304" fill="none" stroke="black"/> <path d="M 248,32 L 248,160" fill="none" stroke="black"/>
<path d="M 248,336 L 248,432" fill="none" stroke="black"/> <path d="M 248,224 L 248,304" fill="none" stroke="black"/>
<path d="M 320,32 L 320,160" fill="none" stroke="black"/> <path d="M 248,336 L 248,432" fill="none" stroke="black"/>
<path d="M 320,224 L 320,304" fill="none" stroke="black"/> <path d="M 320,32 L 320,160" fill="none" stroke="black"/>
<path d="M 320,336 L 320,432" fill="none" stroke="black"/> <path d="M 320,224 L 320,304" fill="none" stroke="black"/>
<path d="M 376,32 L 376,432" fill="none" stroke="black"/> <path d="M 320,336 L 320,432" fill="none" stroke="black"/>
<path d="M 448,32 L 448,432" fill="none" stroke="black"/> <path d="M 376,32 L 376,432" fill="none" stroke="black"/>
<path d="M 24,32 L 48,32" fill="none" stroke="black"/> <path d="M 448,32 L 448,432" fill="none" stroke="black"/>
<path d="M 136,32 L 176,32" fill="none" stroke="black"/> <path d="M 24,32 L 48,32" fill="none" stroke="black"/>
<path d="M 248,32 L 320,32" fill="none" stroke="black"/> <path d="M 136,32 L 176,32" fill="none" stroke="black"/>
<path d="M 376,32 L 448,32" fill="none" stroke="black"/> <path d="M 248,32 L 320,32" fill="none" stroke="black"/>
<path d="M 192,94 L 208,94" fill="none" stroke="black"/><path d="M 192,98 L 208, <path d="M 376,32 L 448,32" fill="none" stroke="black"/>
98" fill="none" stroke="black"/> <path d="M 192,94 L 208,94" fill="none" stroke="black"/>
<path d="M 224,94 L 240,94" fill="none" stroke="black"/><path d="M 224,98 L 240, <path d="M 192,98 L 208,98" fill="none" stroke="black"/>
98" fill="none" stroke="black"/> <path d="M 224,94 L 240,94" fill="none" stroke="black"/>
<path d="M 320,112 L 336,112" fill="none" stroke="black"/> <path d="M 224,98 L 240,98" fill="none" stroke="black"/>
<path d="M 352,112 L 368,112" fill="none" stroke="black"/> <path d="M 320,112 L 336,112" fill="none" stroke="black"/>
<path d="M 328,128 L 344,128" fill="none" stroke="black"/> <path d="M 352,112 L 368,112" fill="none" stroke="black"/>
<path d="M 360,128 L 376,128" fill="none" stroke="black"/> <path d="M 328,128 L 344,128" fill="none" stroke="black"/>
<path d="M 200,142 L 216,142" fill="none" stroke="black"/><path d="M 200,146 L 2 <path d="M 360,128 L 376,128" fill="none" stroke="black"/>
16,146" fill="none" stroke="black"/> <path d="M 200,142 L 216,142" fill="none" stroke="black"/>
<path d="M 232,142 L 248,142" fill="none" stroke="black"/><path d="M 232,146 L 2 <path d="M 200,146 L 216,146" fill="none" stroke="black"/>
48,146" fill="none" stroke="black"/> <path d="M 232,142 L 248,142" fill="none" stroke="black"/>
<path d="M 192,174 L 216,174" fill="none" stroke="black"/><path d="M 192,178 L 2 <path d="M 232,146 L 248,146" fill="none" stroke="black"/>
16,178" fill="none" stroke="black"/> <path d="M 192,174 L 216,174" fill="none" stroke="black"/>
<path d="M 232,174 L 368,174" fill="none" stroke="black"/><path d="M 232,178 L 3 <path d="M 192,178 L 216,178" fill="none" stroke="black"/>
68,178" fill="none" stroke="black"/> <path d="M 232,174 L 368,174" fill="none" stroke="black"/>
<path d="M 200,206 L 336,206" fill="none" stroke="black"/><path d="M 200,210 L 3 <path d="M 232,178 L 368,178" fill="none" stroke="black"/>
36,210" fill="none" stroke="black"/> <path d="M 200,206 L 336,206" fill="none" stroke="black"/>
<path d="M 352,206 L 376,206" fill="none" stroke="black"/><path d="M 352,210 L 3 <path d="M 200,210 L 336,210" fill="none" stroke="black"/>
76,210" fill="none" stroke="black"/> <path d="M 352,206 L 376,206" fill="none" stroke="black"/>
<path d="M 64,238 L 88,238" fill="none" stroke="black"/><path d="M 64,242 L 88,2 <path d="M 352,210 L 376,210" fill="none" stroke="black"/>
42" fill="none" stroke="black"/> <path d="M 64,238 L 88,238" fill="none" stroke="black"/>
<path d="M 104,238 L 240,238" fill="none" stroke="black"/><path d="M 104,242 L 2 <path d="M 64,242 L 88,242" fill="none" stroke="black"/>
40,242" fill="none" stroke="black"/> <path d="M 104,238 L 240,238" fill="none" stroke="black"/>
<path d="M 320,256 L 336,256" fill="none" stroke="black"/> <path d="M 104,242 L 240,242" fill="none" stroke="black"/>
<path d="M 352,256 L 368,256" fill="none" stroke="black"/> <path d="M 320,256 L 336,256" fill="none" stroke="black"/>
<path d="M 328,272 L 344,272" fill="none" stroke="black"/> <path d="M 352,256 L 368,256" fill="none" stroke="black"/>
<path d="M 360,272 L 376,272" fill="none" stroke="black"/> <path d="M 328,272 L 344,272" fill="none" stroke="black"/>
<path d="M 72,286 L 216,286" fill="none" stroke="black"/><path d="M 72,290 L 216 <path d="M 360,272 L 376,272" fill="none" stroke="black"/>
,290" fill="none" stroke="black"/> <path d="M 72,286 L 216,286" fill="none" stroke="black"/>
<path d="M 232,286 L 248,286" fill="none" stroke="black"/><path d="M 232,290 L 2 <path d="M 72,290 L 216,290" fill="none" stroke="black"/>
48,290" fill="none" stroke="black"/> <path d="M 232,286 L 248,286" fill="none" stroke="black"/>
<path d="M 64,318 L 88,318" fill="none" stroke="black"/><path d="M 64,322 L 88,3 <path d="M 232,290 L 248,290" fill="none" stroke="black"/>
22" fill="none" stroke="black"/> <path d="M 64,318 L 88,318" fill="none" stroke="black"/>
<path d="M 104,318 L 368,318" fill="none" stroke="black"/><path d="M 104,322 L 3 <path d="M 64,322 L 88,322" fill="none" stroke="black"/>
68,322" fill="none" stroke="black"/> <path d="M 104,318 L 368,318" fill="none" stroke="black"/>
<path d="M 72,350 L 88,350" fill="none" stroke="black"/><path d="M 72,354 L 88,3 <path d="M 104,322 L 368,322" fill="none" stroke="black"/>
54" fill="none" stroke="black"/> <path d="M 72,350 L 88,350" fill="none" stroke="black"/>
<path d="M 104,350 L 120,350" fill="none" stroke="black"/><path d="M 104,354 L 1 <path d="M 72,354 L 88,354" fill="none" stroke="black"/>
20,354" fill="none" stroke="black"/> <path d="M 104,350 L 120,350" fill="none" stroke="black"/>
<path d="M 64,382 L 88,382" fill="none" stroke="black"/><path d="M 64,386 L 88,3 <path d="M 104,354 L 120,354" fill="none" stroke="black"/>
86" fill="none" stroke="black"/> <path d="M 64,382 L 88,382" fill="none" stroke="black"/>
<path d="M 104,382 L 240,382" fill="none" stroke="black"/><path d="M 104,386 L 2 <path d="M 64,386 L 88,386" fill="none" stroke="black"/>
40,386" fill="none" stroke="black"/> <path d="M 104,382 L 240,382" fill="none" stroke="black"/>
<path d="M 320,400 L 336,400" fill="none" stroke="black"/> <path d="M 104,386 L 240,386" fill="none" stroke="black"/>
<path d="M 352,400 L 368,400" fill="none" stroke="black"/> <path d="M 320,400 L 336,400" fill="none" stroke="black"/>
<path d="M 24,432 L 48,432" fill="none" stroke="black"/> <path d="M 352,400 L 368,400" fill="none" stroke="black"/>
<path d="M 136,432 L 176,432" fill="none" stroke="black"/> <path d="M 24,432 L 48,432" fill="none" stroke="black"/>
<path d="M 248,432 L 320,432" fill="none" stroke="black"/> <path d="M 136,432 L 176,432" fill="none" stroke="black"/>
<path d="M 376,432 L 448,432" fill="none" stroke="black"/> <path d="M 248,432 L 320,432" fill="none" stroke="black"/>
<path d="M 24,32 C 15.16936,32 8,39.16936 8,48" fill="none" stroke="black"/> <path d="M 376,432 L 448,432" fill="none" stroke="black"/>
<path d="M 48,32 C 56.83064,32 64,39.16936 64,48" fill="none" stroke="black"/> <path d="M 24,32 C 15.16936,32 8,39.16936 8,48" fill="none" stro
<path d="M 136,32 C 127.16936,32 120,39.16936 120,48" fill="none" stroke="black" ke="black"/>
/> <path d="M 48,32 C 56.83064,32 64,39.16936 64,48" fill="none" st
<path d="M 176,32 C 184.83064,32 192,39.16936 192,48" fill="none" stroke="black" roke="black"/>
/> <path d="M 136,32 C 127.16936,32 120,39.16936 120,48" fill="none
<path d="M 24,432 C 15.16936,432 8,424.83064 8,416" fill="none" stroke="black"/> " stroke="black"/>
<path d="M 48,432 C 56.83064,432 64,424.83064 64,416" fill="none" stroke="black" <path d="M 176,32 C 184.83064,32 192,39.16936 192,48" fill="none
/> " stroke="black"/>
<path d="M 136,432 C 127.16936,432 120,424.83064 120,416" fill="none" stroke="bl <path d="M 24,432 C 15.16936,432 8,424.83064 8,416" fill="none"
ack"/> stroke="black"/>
<path d="M 176,432 C 184.83064,432 192,424.83064 192,416" fill="none" stroke="bl <path d="M 48,432 C 56.83064,432 64,424.83064 64,416" fill="none
ack"/> " stroke="black"/>
<polygon class="arrowhead" points="376,400 364,394.4 364,405.6" fill="black" tra <path d="M 136,432 C 127.16936,432 120,424.83064 120,416" fill="
nsform="rotate(0,368,400)"/> none" stroke="black"/>
<polygon class="arrowhead" points="376,320 364,314.4 364,325.6" fill="black" tra <path d="M 176,432 C 184.83064,432 192,424.83064 192,416" fill="
nsform="rotate(0,368,320)"/> none" stroke="black"/>
<polygon class="arrowhead" points="376,256 364,250.4 364,261.6" fill="black" tra <polygon class="arrowhead" points="376,400 364,394.4 364,405.6"
nsform="rotate(0,368,256)"/> fill="black" transform="rotate(0,368,400)"/>
<polygon class="arrowhead" points="376,176 364,170.4 364,181.6" fill="black" tra <polygon class="arrowhead" points="376,320 364,314.4 364,325.6"
nsform="rotate(0,368,176)"/> fill="black" transform="rotate(0,368,320)"/>
<polygon class="arrowhead" points="376,112 364,106.4 364,117.6" fill="black" tra <polygon class="arrowhead" points="376,256 364,250.4 364,261.6"
nsform="rotate(0,368,112)"/> fill="black" transform="rotate(0,368,256)"/>
<polygon class="arrowhead" points="336,272 324,266.4 324,277.6" fill="black" tra <polygon class="arrowhead" points="376,176 364,170.4 364,181.6"
nsform="rotate(180,328,272)"/> fill="black" transform="rotate(0,368,176)"/>
<polygon class="arrowhead" points="336,128 324,122.4 324,133.6" fill="black" tra <polygon class="arrowhead" points="376,112 364,106.4 364,117.6"
nsform="rotate(180,328,128)"/> fill="black" transform="rotate(0,368,112)"/>
<polygon class="arrowhead" points="248,384 236,378.4 236,389.6" fill="black" tra <polygon class="arrowhead" points="336,272 324,266.4 324,277.6"
nsform="rotate(0,240,384)"/> fill="black" transform="rotate(180,328,272)"/>
<polygon class="arrowhead" points="248,240 236,234.4 236,245.6" fill="black" tra <polygon class="arrowhead" points="336,128 324,122.4 324,133.6"
nsform="rotate(0,240,240)"/> fill="black" transform="rotate(180,328,128)"/>
<polygon class="arrowhead" points="248,96 236,90.4 236,101.6" fill="black" trans <polygon class="arrowhead" points="248,384 236,378.4 236,389.6"
form="rotate(0,240,96)"/> fill="black" transform="rotate(0,240,384)"/>
<polygon class="arrowhead" points="208,208 196,202.4 196,213.6" fill="black" tra <polygon class="arrowhead" points="248,240 236,234.4 236,245.6"
nsform="rotate(180,200,208)"/> fill="black" transform="rotate(0,240,240)"/>
<polygon class="arrowhead" points="208,144 196,138.4 196,149.6" fill="black" tra <polygon class="arrowhead" points="248,96 236,90.4 236,101.6" fi
nsform="rotate(180,200,144)"/> ll="black" transform="rotate(0,240,96)"/>
<polygon class="arrowhead" points="80,352 68,346.4 68,357.6" fill="black" transf <polygon class="arrowhead" points="208,208 196,202.4 196,213.6"
orm="rotate(180,72,352)"/> fill="black" transform="rotate(180,200,208)"/>
<polygon class="arrowhead" points="80,288 68,282.4 68,293.6" fill="black" transf <polygon class="arrowhead" points="208,144 196,138.4 196,149.6"
orm="rotate(180,72,288)"/> fill="black" transform="rotate(180,200,144)"/>
<g class="text"> <polygon class="arrowhead" points="80,352 68,346.4 68,357.6" fil
<text x="36" y="52">User</text> l="black" transform="rotate(180,72,352)"/>
<text x="156" y="52">Attacker</text> <polygon class="arrowhead" points="80,288 68,282.4 68,293.6" fil
<text x="284" y="52">Client</text> l="black" transform="rotate(180,72,288)"/>
<text x="412" y="52">AS</text> <g class="text">
<text x="284" y="68">Instance</text> <text x="36" y="52">User</text>
<text x="216" y="100">1</text> <text x="156" y="52">Attacker</text>
<text x="344" y="116">2</text> <text x="284" y="52">Client</text>
<text x="352" y="132">3</text> <text x="412" y="52">AS</text>
<text x="224" y="148">4</text> <text x="284" y="68">Instance</text>
<text x="224" y="180">5</text> <text x="216" y="100">1</text>
<text x="248" y="196">|</text> <text x="344" y="116">2</text>
<text x="320" y="196">|</text> <text x="352" y="132">3</text>
<text x="344" y="212">6</text> <text x="224" y="148">4</text>
<text x="96" y="244">A</text> <text x="224" y="180">5</text>
<text x="344" y="260">B</text> <text x="248" y="196">|</text>
<text x="352" y="276">C</text> <text x="320" y="196">|</text>
<text x="224" y="292">D</text> <text x="344" y="212">6</text>
<text x="120" y="308">|</text> <text x="96" y="244">A</text>
<text x="192" y="308">|</text> <text x="344" y="260">B</text>
<text x="96" y="324">E</text> <text x="352" y="276">C</text>
<text x="96" y="356">7</text> <text x="224" y="292">D</text>
<text x="96" y="388">F</text> <text x="120" y="308">|</text>
<text x="344" y="404">G</text> <text x="192" y="308">|</text>
</g> <text x="96" y="324">E</text>
</svg> <text x="96" y="356">7</text>
</artwork><artwork type="ascii-art"><![CDATA[ <text x="96" y="388">F</text>
<text x="344" y="404">G</text>
</g>
</svg>
</artwork>
<artwork type="ascii-art"><![CDATA[
.----. .------. +--------+ +--------+ .----. .------. +--------+ +--------+
| User | |Attacker| | Client | | AS | | User | |Attacker| | Client | | AS |
| | | | |Instance| | | | | | | |Instance| | |
| | | | | | | | | | | | | | | |
| | | +=(1)=>| | | | | | | +=(1)=>| | | |
| | | | | +-(2)->| | | | | | | +-(2)->| |
| | | | | |<-(3)-+ | | | | | | |<-(3)-+ |
| | | |<=(4)=+ | | | | | | |<=(4)=+ | | |
| | | | | | | | | | | | | | | |
| | | +==(5)================>| | | | | +==(5)================>| |
skipping to change at line 8734 skipping to change at line 8804
| |<=================(D)=+ | | | | |<=================(D)=+ | | |
| | | | | | | | | | | | | | | |
| +==(E)================================>| | | +==(E)================================>| |
| | | | | | | | | | | | | | | |
| |<=(7)=+ | | | | | | |<=(7)=+ | | | | |
| | | | | | | | | | | | | | | |
| +==(F)================>| | | | | +==(F)================>| | | |
| | | | | +-(G)->| | | | | | | +-(G)->| |
| | | | | | | | | | | | | | | |
`----` `------` +--------+ +--------+ `----` `------` +--------+ +--------+
]]></artwork></artset></figure> ]]></artwork>
</artset>
<t><list style="symbols"> </figure>
<t>Prerequisites: The client instance can allow multiple end users to <t>Prerequisites: The client instance can allow multiple end users t
o
access the same AS. The attacker is attempting to associate their rights access the same AS. The attacker is attempting to associate their rights
with the target user's session.</t> with the target user's session.</t>
<t>(1) The attacker starts a session at the client instance.</t>
<t>(2) The client instance creates a grant request with nonce CN1.</t> <ul spacing="normal">
<t>(3) The AS responds to the grant request with a <li>
<t>(1) The attacker starts a session at the client instance.</t>
</li>
<li>
<t>(2) The client instance creates a grant request with nonce CN1.</
t>
</li>
<li>
<t>(3) The AS responds to the grant request with a
need to interact, nonce SN1, and a continuation token, CT1.</t> need to interact, nonce SN1, and a continuation token, CT1.</t>
<t>(4) The client instructs the attacker to interact at the AS.</t> </li>
<t>(5) The attacker interacts at the AS.</t> <li>
<t>(6) The AS completes the interact finish with interact ref IR1 and <t>(4) The client instructs the attacker to interact at the AS.</t>
</li>
<li>
<t>(5) The attacker interacts at the AS.</t>
</li>
<li>
<t>(6) The AS completes the interact finish with interact reference
IR1 and
interact hash IH1 calculated from (CN1 + SN1 + IR1 + AS). interact hash IH1 calculated from (CN1 + SN1 + IR1 + AS).
The attacker prevents IR1 from returning to the client instance.</t> The attacker prevents IR1 from returning to the client instance.</t>
<t>(A) The target user starts a session at the client instance.</t> </li>
<t>(B) The client instance creates a grant request with nonce CN2.</t> <li>
<t>(C) The AS responds to the grant request with a <t>(A) The target user starts a session at the client instance.</t>
</li>
<li>
<t>(B) The client instance creates a grant request with nonce CN2.</
t>
</li>
<li>
<t>(C) The AS responds to the grant request with a
need to interact, nonce SN2, and a continuation token, CT2.</t> need to interact, nonce SN2, and a continuation token, CT2.</t>
<t>(D) The client instance instructs the user to interact at the AS.</t> </li>
<t>(E) The target user interacts at the AS.</t> <li>
<t>(7) Before the target user can complete their interaction, the attacker <t>(D) The client instance instructs the user to interact at the AS.
delivers their own interact ref IR1 into the user's session. The attacker </t>
</li>
<li>
<t>(E) The target user interacts at the AS.</t>
</li>
<li>
<t>(7) Before the target user can complete their interaction, the at
tacker
delivers their own interact reference IR1 into the user's session. The attacke
r
cannot calculate the appropriate hash because the attacker does not have cannot calculate the appropriate hash because the attacker does not have
access to CN2 and SN2.</t> access to CN2 and SN2.</t>
<t>(F) The target user triggers the interaction finish in their own session </li>
<li>
<t>(F) The target user triggers the interaction finish in their own
session
with the attacker's IR1.</t> with the attacker's IR1.</t>
<t>(G) If the client instance is checking the interaction hash, the attack </li>
<li>
<t>(G) If the client instance is checking the interaction hash, the
attack
stops here because the hash calculation of (CN2 + SN2 + IR1 + AS) will fail. stops here because the hash calculation of (CN2 + SN2 + IR1 + AS) will fail.
If the client instance does not check the interaction hash, the client instanc e If the client instance does not check the interaction hash, the client instanc e
will be tricked into submitting the interaction reference to the AS. Here, the AS will will be tricked into submitting the interaction reference to the AS. Here, the AS will
reject the interaction request because it is presented against CT2 and not reject the interaction request because it is presented against CT2 and not
CT1 as expected. However, an attacker who has potentially injected CT1 as CT1 as expected. However, an attacker who has potentially injected CT1 as
the value of CT2 would be able to continue the attack.</t> the value of CT2 would be able to continue the attack.</t>
</list></t> </li>
</ul>
<t>Even with additional checks in place, client instances using interaction fini <t>Even with additional checks in place, client instances using interact
sh mechanisms are responsible ion finish mechanisms are responsible
for checking the interaction hash to provide security to the overall system.</t> for checking the interaction hash to provide security to the overall system.</t>
</section>
</section> <section anchor="security-client-storage">
<section anchor="security-client-storage"><name>Storage of Information During In <name>Storage of Information during Interaction and Continuation</name>
teraction and Continuation</name> <t>When starting an interactive grant request, a client application has
a number of protocol elements
<t>When starting an interactive grant request, a client application has a number
of protocol elements
that it needs to manage, including nonces, references, keys, access tokens, and other elements. that it needs to manage, including nonces, references, keys, access tokens, and other elements.
During the interaction process, the client instance usually hands control of the user experience During the interaction process, the client instance usually hands control of the user experience
over to another component, be it the system browser, another application, or som e action over to another component, be it the system browser, another application, or som e action
the resource owner is instructed to take on another device. In order for the cli the RO is instructed to take on another device. In order for the client instance
ent instance to make its continuation call, it will need to recall all of these protocol elem
to make its continuation call, it will need to recall all of these protocol elem ents at a future time. Usually,
ents at a future time. Usually
this means the client instance will need to store these protocol elements in som e retrievable this means the client instance will need to store these protocol elements in som e retrievable
fashion.</t> fashion.</t>
<t>If the security protocol elements are stored on the end user's device
<t>If the security protocol elements are stored on the end user's device, such a , such as in browser
s in browser
storage or in local application data stores, capture and exfiltration of this in formation could storage or in local application data stores, capture and exfiltration of this in formation could
allow an attacker to continue a pending transaction instead of the client instan ce. Client allow an attacker to continue a pending transaction instead of the client instan ce. Client
software can make use of secure storage mechanisms, including hardware-based key and data software can make use of secure storage mechanisms, including hardware-based key and data
storage, to prevent such exfiltration.</t> storage, to prevent such exfiltration.</t>
<t>Note that in GNAP, the client instance has to choose its interaction
<t>Note that in GNAP, the client instance has to choose its interaction finish U finish URI prior to making
RI prior to making
the first call to the AS. As such, the interaction finish URI will often have a unique identifier the first call to the AS. As such, the interaction finish URI will often have a unique identifier
for the ongoing request, allowing the client instance to access the correct port ion of its for the ongoing request, allowing the client instance to access the correct port ion of its
storage. Since this URI is passed to other parties and often used through a brow ser, storage. Since this URI is passed to other parties and often used through a brow ser,
this URI should not contain any security-sensitive information that would be this URI should not contain any security-sensitive information that would be
valuable to an attacker, such as any token identifier, nonce, or user informatio n. Instead, a valuable to an attacker, such as any token identifier, nonce, or user informatio n. Instead, a
cryptographically random value is suggested, and that value should be used to in dex into cryptographically random value is suggested, and that value should be used to in dex into
a secure session or storage mechanism.</t> a secure session or storage mechanism.</t>
</section>
</section> <section anchor="security-continuation">
<section anchor="security-continuation"><name>Denial of Service (DoS) through Gr <name>Denial of Service (DoS) through Grant Continuation</name>
ant Continuation</name> <t>When a client instance starts off an interactive process, it will eve
ntually need to continue the grant
<t>When a client instance starts off an interactive process, it will eventually
need to continue the grant
request in a subsequent message to the AS. It's possible for a naive client impl ementation to continuously request in a subsequent message to the AS. It's possible for a naive client impl ementation to continuously
send continuation requests to the AS while waiting for approval, especially if n o interaction send continuation requests to the AS while waiting for approval, especially if n o interaction
finish method is used. Such constant requests could overwhelm the AS's ability t o respond to both finish method is used. Such constant requests could overwhelm the AS's ability t o respond to both
these and other requests.</t> these and other requests.</t>
<t>To mitigate this for well-behaved client software, the continuation r
<t>To mitigate this for well-behaved client software, the continuation response esponse contains a <tt>wait</tt> parameter
contains a <spanx style="verb">wait</spanx> parameter
that is intended to tell the client instance how long it should wait until makin g its next request. that is intended to tell the client instance how long it should wait until makin g its next request.
This value can be used to back off client software that is checking too quickly by returning increasing This value can be used to back off client software that is checking too quickly by returning increasing
wait times for a single client instance.</t> wait times for a single client instance.</t>
<t>If client software ignores the <tt>wait</tt> value and makes its cont
<t>If client software ignores the <spanx style="verb">wait</spanx> value and mak inuation calls too quickly or if the
es its continuation calls too quickly, or if the client software assumes the absence of the <tt>wait</tt> values means it should
client software assumes the absence of the <spanx style="verb">wait</spanx> valu poll immediately, the AS
es means it should poll immediately, the AS
can choose to return errors to the offending client instance, including possibly canceling the can choose to return errors to the offending client instance, including possibly canceling the
ongoing grant request. With well-meaning client software these errors can indica te a need to change ongoing grant request. With well-meaning client software, these errors can indic ate a need to change
the client software's programmed behavior.</t> the client software's programmed behavior.</t>
</section>
</section> <section anchor="security-random-exhaustion">
<section anchor="security-random-exhaustion"><name>Exhaustion of Random Value Sp <name>Exhaustion of Random Value Space</name>
ace</name> <t>Several parts of the GNAP process make use of unguessable randomized
values, such as nonces,
<t>Several parts of the GNAP process make use of unguessable randomized values,
such as nonces,
tokens, user codes, and randomized URIs. Since these values are intended to be u nique, a sufficiently tokens, user codes, and randomized URIs. Since these values are intended to be u nique, a sufficiently
powerful attacker could make a large number of requests to trigger generation of randomized powerful attacker could make a large number of requests to trigger generation of randomized
values in an attempt to exhaust the random number generation space. While this a ttack is values in an attempt to exhaust the random number generation space. While this a ttack is
particularly applicable to the AS, client software could likewise be targeted by an attacker particularly applicable to the AS, client software could likewise be targeted by an attacker
triggering new grant requests against an AS.</t> triggering new grant requests against an AS.</t>
<t>To mitigate this, software can ensure that its random values are chos
<t>To mitigate this, software can ensure that its random values are chosen from en from a significantly
a significantly large pool so that exhaustion of that pool is prohibitive for an attacker. Addit
large pool that exhaustion of that pool is prohibitive for an attacker. Addition ionally, the
ally, the random values can be time-boxed in such a way that their validity windows are re
random values can be time-boxed in such a way as their validity windows are reas asonably short.
onably short.
Since many of the random values used within GNAP are used within limited portion s of the protocol, Since many of the random values used within GNAP are used within limited portion s of the protocol,
it is reasonable for a particular random value to be valid for only a small amou nt of time. it is reasonable for a particular random value to be valid for only a small amou nt of time.
For example, the nonces used for interaction finish hash calculation need only t o be valid while For example, the nonces used for interaction finish hash calculation need only t o be valid while
the client instance is waiting for the finish callback and can be functionally e xpired the client instance is waiting for the finish callback and can be functionally e xpired
when the interaction has completed. Similarly, artifacts like access tokens and the interaction when the interaction has completed. Similarly, artifacts like access tokens and the interaction
reference can be limited to have lifetimes tied to their functional utility. Fin ally, each reference can be limited to have lifetimes tied to their functional utility. Fin ally, each
different category of artifact (nonce, token, reference, identifier, etc.) can b e different category of artifact (nonce, token, reference, identifier, etc.) can b e
generated from a separate random pool of values instead of a single global value space.</t> generated from a separate random pool of values instead of a single global value space.</t>
</section>
</section> <section anchor="security-front-channel">
<section anchor="security-front-channel"><name>Front-channel URIs</name> <name>Front-Channel URIs</name>
<t>Some interaction methods in GNAP make use of URIs accessed through th
<t>Some interaction methods in GNAP make use of URIs accessed through the end us e end user's browser,
er's browser,
known collectively as front-channel communication. These URIs are most notably p resent in known collectively as front-channel communication. These URIs are most notably p resent in
the <spanx style="verb">redirect</spanx> interaction <spanx style="verb">start</ spanx> method and the <spanx style="verb">redirect</spanx> interaction <spanx st yle="verb">finish</spanx> mode. Since the <tt>redirect</tt> interaction <tt>start</tt> method and the <tt>redirect</tt > interaction <tt>finish</tt> mode. Since
these URIs are intended to be given to the end user, the end user and their brow ser will be these URIs are intended to be given to the end user, the end user and their brow ser will be
subjected to anything hosted at that URI including viruses, malware, and phishin g scams. This subjected to anything hosted at that URI including viruses, malware, and phishin g scams. This
kind of risk is inherent to all redirection-based protocols, including GNAP when kind of risk is inherent to all redirection-based protocols, including GNAP, whe
used in this way.</t> n used in this way.</t>
<t>When talking to a new or unknown AS, a client instance might want to
<t>When talking to a new or unknown AS, a client instance might want to check th check the URI from the
e URI from the interaction <tt>start</tt> against a blocklist and warn the end user before redi
interaction <spanx style="verb">start</spanx> against a blocklist and warn the e recting them. Many
nd user before redirecting them. Many
client instances will provide an interstitial message prior to redirection in or der to prepare client instances will provide an interstitial message prior to redirection in or der to prepare
the user for control of the user experience being handed to the domain of the AS , and such a the user for control of the user experience being handed to the domain of the AS , and such a
method could be used to warn the user of potential threats. For instance, a rogu method could be used to warn the user of potential threats (for instance, a rogu
e AS impersonating e AS impersonating
a well-known service provider. Client software can also prevent this by managing a well-known service provider). Client software can also prevent this by managin
an allowlist g an allowlist
of known and trusted AS's.</t> of known and trusted ASes.</t>
<t>Alternatively, an attacker could start a GNAP request with a known an
<t>Alternatively, an attacker could start a GNAP request with a known and truste d trusted AS but include
d AS but include their own attack site URI as the callback for the redirect <tt>finish</tt> metho
their own attack site URI as the callback for the redirect <spanx style="verb">f d. The attacker would then send
inish</spanx> method. The attacker would then send the interaction <tt>start</tt> URI to the victim and get them to click on it. Si
the interaction <spanx style="verb">start</spanx> URI to the victim and get them nce the URI is at
to click on it. Since the URI is at
the known AS, the victim is inclined to do so. The victim will then be prompted to approve the the known AS, the victim is inclined to do so. The victim will then be prompted to approve the
attacker's application, and in most circumstances the victim will then be redire cted to the attacker's application, and in most circumstances, the victim will then be redir ected to the
attacker's site whether or not the user approved the request. The AS could mitig ate this partially attacker's site whether or not the user approved the request. The AS could mitig ate this partially
by using a blocklist and allowlist of interaction <spanx style="verb">finish</sp anx> URIs during the client instance's by using a blocklist and allowlist of interaction <tt>finish</tt> URIs during th e client instance's
initial request, but this approach can be especially difficult if the URI has a ny dynamic portion initial request, but this approach can be especially difficult if the URI has a ny dynamic portion
chosen by the client software. The AS can couple these checks with policies asso ciated with the chosen by the client software. The AS can couple these checks with policies asso ciated with the
client instance that has been authenticated in the request. If the AS has any do ubt about the client instance that has been authenticated in the request. If the AS has any do ubt about the
interaction finish URI, the AS can provide an interstitial warning to the end us er before interaction finish URI, the AS can provide an interstitial warning to the end us er before
processing the redirect.</t> processing the redirect.</t>
<t>Ultimately, all protocols that use redirect-based communication throu
<t>Ultimately, all protocols that use redirect-based communication through the u gh the user's browser are
ser's browser are
susceptible to having an attacker try to co-opt one or more of those URIs in ord er to harm the susceptible to having an attacker try to co-opt one or more of those URIs in ord er to harm the
user. It is the responsibility of the AS and the client software to provide appr opriate warnings, user. It is the responsibility of the AS and the client software to provide appr opriate warnings,
education, and mitigation to protect end users.</t> education, and mitigation to protect end users.</t>
</section>
</section> <section anchor="security-assertions">
<section anchor="security-assertions"><name>Processing Assertions</name> <name>Processing Assertions</name>
<t>Identity assertions can be used in GNAP to convey subject information
<t>Identity assertions can be used in GNAP to convey subject information, both f , both from the AS to the
rom the AS to the client instance in a response (<xref target="response-subject"> </xref>) and fro
client instance in a <xref target="response-subject">response</xref> and from th m the client instance to the AS in
e client instance to the AS in a request (<xref target="request-subject"> </xref>). In both of these circumstan
a <xref target="request-subject">request</xref>. In both of these circumstances, ces, when an assertion is passed in
when an assertion is passed in
GNAP, the receiver of the assertion needs to parse and process the assertion. As assertions are GNAP, the receiver of the assertion needs to parse and process the assertion. As assertions are
complex artifacts with their own syntax and security, special care needs to be t aken to prevent the complex artifacts with their own syntax and security, special care needs to be t aken to prevent the
assertion values from being used as an attack vector.</t> assertion values from being used as an attack vector.</t>
<t>All assertion processing needs to account for the security aspects of
<t>All assertion processing needs to account for the security aspects of the ass the assertion format in
ertion format in use. In particular, the processor needs to parse the assertion from a JSON strin
use. In particular, the processor needs to parse the assertion from a JSON strin g object
g object,
and apply the appropriate cryptographic processes to ensure the integrity of the assertion.</t> and apply the appropriate cryptographic processes to ensure the integrity of the assertion.</t>
<t>For example, when SAML 2 assertions are used, the receiver has to parse an XM L document. There are <t>For example, when SAML 2.0 assertions are used, the receiver has to parse an XML document. There are
many well-known security vulnerabilities in XML parsers, and the XML standard it self can be many well-known security vulnerabilities in XML parsers, and the XML standard it self can be
attacked through the use of processing instructions and entity expansions to cau se problems attacked through the use of processing instructions and entity expansions to cau se problems
with the processor. Therefore, any system capable of processing SAML 2 assertion with the processor. Therefore, any system capable of processing SAML 2.0 asserti
s also needs to ons also needs to
have a secure and correct XML parser. In addition to this, the SAML 2 specificat have a secure and correct XML parser. In addition to this, the SAML 2.0 specific
ion uses XML ation uses XML
Signatures, which have their own implementation problems that need to be account ed for. Similar Signatures, which have their own implementation problems that need to be account ed for. Similar
requirements exist for OpenID Connect's ID token, which is based on the JSON Web requirements exist for OpenID Connect ID Token, which is based on the JWT format
Token (JWT) format and the related JOSE cryptography suite.</t>
and the related JSON Object Signing And Encryption (JOSE) cryptography suite.</t </section>
> <section anchor="security-cuckoo">
<name>Stolen Token Replay</name>
</section> <t>If a client instance can request tokens at multiple ASes and the clie
<section anchor="security-cuckoo"><name>Stolen Token Replay</name> nt instance uses the same keys
to make its requests across those different ASes, then it is possible for an att
<t>If a client instance can request tokens at multiple AS's, and the client inst acker to replay a
ance uses the same keys
to make its requests across those different AS's, then it is possible for an att
acker to replay a
stolen token issued by an honest AS from a compromised AS, thereby binding the s tolen token to stolen token issued by an honest AS from a compromised AS, thereby binding the s tolen token to
the client instance's key in a different context. The attacker can manipulate th e client instance the client instance's key in a different context. The attacker can manipulate th e client instance
into using the stolen token at an RS, particularly at an RS that is expecting a token from the into using the stolen token at an RS, particularly at an RS that is expecting a token from the
honest AS. Since the honest AS issued the token and the client instance presents the token with honest AS. Since the honest AS issued the token and the client instance presents the token with
its expected bound key, the attack succeeds.</t> its expected bound key, the attack succeeds.</t>
<t>This attack has several preconditions. In this attack, the attacker d
<t>This attack has several preconditions. In this attack, the attacker does not oes not need access to the
need access to the
client instance's key and cannot use the stolen token directly at the RS, but th e attacker is able client instance's key and cannot use the stolen token directly at the RS, but th e attacker is able
to get the access token value in some fashion. The client instance also needs to be configured to to get the access token value in some fashion. The client instance also needs to be configured to
talk to multiple AS's, including the attacker's controlled AS. Finally, the clie nt instance needs talk to multiple ASes, including the attacker's controlled AS. Finally, the clie nt instance needs
to be able to be manipulated by the attacker to call the RS while using a token issued from the to be able to be manipulated by the attacker to call the RS while using a token issued from the
stolen AS. The RS does not need to be compromised or made to trust the attacker' s AS.</t> stolen AS. The RS does not need to be compromised or made to trust the attacker' s AS.</t>
<t>To protect against this attack, the client instance can use a differe
<t>To protect against this attack, the client instance can use a different key f nt key for each AS that it
or each AS that it
talks to. Since the replayed token will be bound to the key used at the honest A S, the talks to. Since the replayed token will be bound to the key used at the honest A S, the
uncompromised RS will reject the call since the client instance will be using th e key used at uncompromised RS will reject the call since the client instance will be using th e key used at
the attacker's AS instead with the same token. the attacker's AS instead with the same token.
When the MTLS key proofing method is used, a client instance can use self-signed When the MTLS key proofing method is used, a client instance can use self-signed
certificates to use a different key for each AS that it talks to, as discussed i n certificates to use a different key for each AS that it talks to, as discussed i n
<xref target="security-mtls-patterns"/>.</t> <xref target="security-mtls-patterns"/>.</t>
<t>Additionally, the client instance can keep a strong association betwe
<t>Additionally, the client instance can keep a strong association between the R en the RS and a specific AS
S and a specific AS
that it trusts to issue tokens for that RS. This strong binding also helps again st some forms of that it trusts to issue tokens for that RS. This strong binding also helps again st some forms of
<xref target="security-mixup">AS mix-up attacks</xref>. Managing this binding is outside the scope of GNAP core, AS mix-up attacks (<xref target="security-mixup"> </xref>). Managing this bindin g is outside the scope of this specification,
but it can be managed either as a configuration element for the client instance or dynamically but it can be managed either as a configuration element for the client instance or dynamically
through <xref target="rs-request-without-token">discovering the AS from the RS</ through discovering the AS from the RS (<xref target="rs-request-without-token">
xref>.</t> </xref>).</t>
<t>The details of this attack are available in <xref target="HELMSCHMIDT2022"/>
with additional discussion and considerations.</t>
</section>
<section anchor="security-stateless-tokens"><name>Self-contained Stateless Acces
s Tokens</name>
<t>The contents and format of the access token are at the discretion of the AS, <t>The details of this attack, with additional discussion and considerat
and are opaque ions, are available in Section 3.2 of <xref target="HELMSCHMIDT2022"/>.</t>
to the client instance within GNAP. As discussed in the companion document, </section>
<section anchor="security-stateless-tokens">
<name>Self-Contained Stateless Access Tokens</name>
<t>The contents and format of the access token are at the discretion of
the AS and are opaque
to the client instance within GNAP. As discussed in
<xref target="I-D.ietf-gnap-resource-servers"/>, the AS and RS can make use of s tateless access tokens <xref target="I-D.ietf-gnap-resource-servers"/>, the AS and RS can make use of s tateless access tokens
with an internal structure and format. These access tokens allow an RS to valida te the token without with an internal structure and format. These access tokens allow an RS to valida te the token without
having to make any external calls at runtime, allowing for benefits in some depl oyments, the having to make any external calls at runtime, allowing for benefits in some depl oyments, the
discussion of which are outside the scope of this specification.</t> discussion of which is outside the scope of this specification.</t>
<t>However, the use of such self-contained access tokens has an effect on the ab ility of the AS to <t>However, the use of such self-contained access tokens has an effect on the ab ility of the AS to
provide certain functionality defined within this specification. Specifically, s ince the access provide certain functionality defined within this specification. Specifically, s ince the access
token is self-contained, it is difficult or impossible for an AS to signal to al l RS's within an token is self-contained, it is difficult or impossible for an AS to signal to al l RSs within an
ecosystem when a specific access token has been revoked. Therefore, an AS in suc h an ecosystem ecosystem when a specific access token has been revoked. Therefore, an AS in suc h an ecosystem
should probably not offer token revocation functionality to client instances, si nce the client should probably not offer token revocation functionality to client instances, si nce the client
instance's calls to such an endpoint is effectively meaningless. However, a clie nt instance calling instance's calls to such an endpoint are effectively meaningless. However, a cli ent instance calling
the token revocation function will also throw out its copy of the token, so such a placebo endpoint the token revocation function will also throw out its copy of the token, so such a placebo endpoint
might not be completely meaningless. Token rotation similarly difficult because the AS has to might not be completely meaningless. Token rotation is similarly difficult becau se the AS has to
revoke the old access token after a rotation call has been made. If the access t okens are revoke the old access token after a rotation call has been made. If the access t okens are
completely self-contained and non-revocable, this means that there will be a per iod of time during completely self-contained and non-revocable, this means that there will be a per iod of time during
which both the old and new access tokens are valid and usable, which is an incre ased security risk which both the old and new access tokens are valid and usable, which is an incre ased security risk
for the environment.</t> for the environment.</t>
<t>These problems can be mitigated by keeping the validity time windows
<t>These problems can be mitigated by keeping the validity time windows of self- of self-contained access tokens
contained access tokens
reasonably short, limiting the time after a revocation event that a revoked toke n could be used. reasonably short, limiting the time after a revocation event that a revoked toke n could be used.
Additionally, the AS could proactively signal to RS's under its control identifi ers for revoked Additionally, the AS could proactively signal to RSs under its control identifie rs for revoked
tokens that have yet to expire. This type of information push would be expected to be relatively tokens that have yet to expire. This type of information push would be expected to be relatively
small and infrequent, and its implementation is outside the scope of this specif ication.</t> small and infrequent, and its implementation is outside the scope of this specif ication.</t>
</section>
</section> <section anchor="security-network-management">
<section anchor="security-network-management"><name>Network Problems and Token a <name>Network Problems and Token and Grant Management</name>
nd Grant Management</name> <t>If a client instance makes a call to rotate an access token but the n
etwork connection is dropped
<t>If a client instance makes a call to rotate an access token but the network c
onnection is dropped
before the client instance receives the response with the new access token, the system as a whole before the client instance receives the response with the new access token, the system as a whole
can end up in an inconsistent state, where the AS has already rotated the old ac cess token and can end up in an inconsistent state, where the AS has already rotated the old ac cess token and
invalidated it, but the client instance only has access to the invalidated acces s token and not the invalidated it, but the client instance only has access to the invalidated acces s token and not the
newly rotated token value. If the client instance retries the rotation request, it would fail newly rotated token value. If the client instance retries the rotation request, it would fail
because the client is no longer presenting a valid and current access token. A s imilar situation because the client is no longer presenting a valid and current access token. A s imilar situation
can occur during grant continuation, where the same client instance calls to con tinue or update can occur during grant continuation, where the same client instance calls to con tinue or update
a grant request without successfully receiving the results of the update.</t> a grant request without successfully receiving the results of the update.</t>
<t>To combat this, both
<t>To combat this, both grant management (<xref target="continue-request"> </xref>) and token management
<xref target="continue-request">grant Management</xref> and <xref target="token- (<xref target="token-management"> </xref>) can be designed to be
management">token management</xref> can be designed to be
idempotent, where subsequent calls to the same function with the same credential s are meant to idempotent, where subsequent calls to the same function with the same credential s are meant to
produce the same results. For example, multiple calls to rotate the same access token need to produce the same results. For example, multiple calls to rotate the same access token need to
result in the same rotated token value, within a reasonable time window.</t> result in the same rotated token value, within a reasonable time window.</t>
<t>In practice, an AS can hold onto an old token value for such limited
<t>In practice, an AS can hold on to an old token value for such limited purpose purposes. For example, to
s. For example, to
support rotating access tokens over unreliable networks, the AS receives the ini tial request to support rotating access tokens over unreliable networks, the AS receives the ini tial request to
rotate an access token and creates a new token value and returns it. The AS also marks the old rotate an access token and creates a new token value and returns it. The AS also marks the old
token value as having been used to create the newly-rotated token value. If the AS sees the old token value as having been used to create the newly rotated token value. If the AS sees the old
token value within a small enough time window, such as a few seconds since the f irst rotation token value within a small enough time window, such as a few seconds since the f irst rotation
attempt, the AS can return the same rotated access token value. Furthermore, onc e the system has seen the attempt, the AS can return the same rotated access token value. Furthermore, onc e the system has seen the
newly-rotated token in use, the original token can be discarded because the clie nt instance has newly rotated token in use, the original token can be discarded because the clie nt instance has
proved that it did receive the token. The result of this is a system that is proved that it did receive the token. The result of this is a system that is
eventually self-consistent without placing an undue complexity burden on the cli ent instance eventually self-consistent without placing an undue complexity burden on the cli ent instance
to manage problematic networks.</t> to manage problematic networks.</t>
</section>
</section> <section anchor="security-ssrf">
<section anchor="security-ssrf"><name>Server-side Request Forgery (SSRF)</name> <name>Server-Side Request Forgery (SSRF)</name>
<t>There are several places within GNAP where a URI can be given to a pa
<t>There are several places within GNAP where a URI can be given to a party caus rty, causing it to fetch that
ing it to fetch that
URI during normal operation of the protocol. If an attacker is able to control t he value of one of URI during normal operation of the protocol. If an attacker is able to control t he value of one of
these URIs within the protocol, the attacker could cause the target system to ex ecute a request on these URIs within the protocol, the attacker could cause the target system to ex ecute a request on
a URI that is within reach of the target system but normally unavailable to the a URI that is within reach of the target system but normally unavailable to the
attacker. For attacker.
example, an attacker sending a URL of <spanx style="verb">http://localhost/admin Examples include an attacker sending a URL of <tt>http://localhost/admin</tt> to
</spanx> to cause the server to access an cause the server to access an
internal function on itself, or <spanx style="verb">https://192.168.0.14/</spanx internal function on itself or <tt>https://192.168.0.14/</tt> to call a service
> to call a service behind a firewall. behind a firewall.
Even if the attacker does not gain access to the results of the call, the side e ffects of such Even if the attacker does not gain access to the results of the call, the side e ffects of such
requests coming from a trusted host can be problematic to the security and sanct ity of such requests coming from a trusted host can be problematic to the security and sanct ity of such
otherwise unexposed endpoints. This can be particularly problematic if such a UR I is used to otherwise unexposed endpoints. This can be particularly problematic if such a UR I is used to
call non-HTTP endpoints, such as remote code execution services local to the AS. </t> call non-HTTP endpoints, such as remote code execution services local to the AS. </t>
<t>The most vulnerable place in this specification is the
<t>In GNAP, the most vulnerable place in the core protocol is the push-based post-interaction finish method (<xref target="interaction-pushback">
<xref target="interaction-pushback">push-based post-interaction finish method</x </xref>), as the client instance is
ref>, as the client instance is
less trusted than the AS and can use this method to make the AS call an arbitrar y URI. While it is less trusted than the AS and can use this method to make the AS call an arbitrar y URI. While it is
not required by the protocol, the AS can fetch other client-instance provided UR Is such as the logo not required by the protocol, the AS can fetch other URIs provided by the client instance, such as the logo
image or home page, for verification or privacy-preserving purposes before displ aying them to the image or home page, for verification or privacy-preserving purposes before displ aying them to the
resource owner as part of a consent screen. Even if the AS does not fetch these URIs, their use in RO as part of a consent screen. Even if the AS does not fetch these URIs, their use in
GNAP's normal operation could cause an attack against the end user's browser as it fetches these GNAP's normal operation could cause an attack against the end user's browser as it fetches these
same attack URIs. Furthermore, extensions to GNAP that allow or require same attack URIs. Furthermore, extensions to GNAP that allow or require
URI fetch could also be similarly susceptible, such as a system for having the A S fetch a client URI fetch could also be similarly susceptible, such as a system for having the A S fetch a client
instance's keys from a presented URI instead of the client instance presenting t he key by value. instance's keys from a presented URI instead of the client instance presenting t he key by value.
Such extensions are outside the scope of this specification, but any system depl oying such an Such extensions are outside the scope of this specification, but any system depl oying such an
extension would need to be aware of this issue.</t> extension would need to be aware of this issue.</t>
<t>To help mitigate this problem, similar approaches to protecting parties again <t>To help mitigate this problem, similar approaches that protect parties agains
st t
<xref target="security-front-channel">malicious redirects</xref> can be used. Fo malicious redirects (<xref target="security-front-channel"> </xref>) can be used
r example, all URIs that can result . For example, all URIs that can result
in a direct request being made by a party in the protocol can be filtered throug h an allowlist or in a direct request being made by a party in the protocol can be filtered throug h an allowlist or
blocklist. For example, an AS that supports the <spanx style="verb">push</spanx> based interaction <spanx style="verb">finish</spanx> can compare the blocklist. For example, an AS that supports the <tt>push</tt>-based interaction <tt>finish</tt> method can compare the
callback URI in the interaction request to a known URI for a pre-registered clie nt instance, or it callback URI in the interaction request to a known URI for a pre-registered clie nt instance, or it
can ensure that the URI is not on a blocklist of sensitive URLs such as internal network addresses. can ensure that the URI is not on a blocklist of sensitive URLs such as internal network addresses.
However, note that because these types of calls happen outside of the view of hu man interaction, However, note that because these types of calls happen outside of the view of hu man interaction,
it is not usually feasible to provide notification and warning to someone before the request it is not usually feasible to provide notification and warning to someone before the request
needs to be executed, as is the case with redirection URLs. As such, SSRF is som ewhat more difficult needs to be executed, as is the case with redirection URLs. As such, SSRF is som ewhat more difficult
to manage at runtime, and systems should generally refuse to fetch a URI if unsu re.</t> to manage at runtime, and systems should generally refuse to fetch a URI if unsu re.</t>
</section>
<section anchor="security-multiple-key-formats">
<name>Multiple Key Formats</name>
</section> <t>All keys presented by value are only allowed to be in a single format.
<section anchor="security-multiple-key-formats"><name>Multiple Key Formats</name While it would seem
> beneficial to allow keys to be sent in multiple formats in case the receiver doe
sn't understand
<t>All keys presented by value are allowed to be in only a single format. While one or more of the formats used, there are security issues with such a feature.
it would seem If multiple keys formats are allowed,
beneficial to allow keys to be sent in multiple formats, in case the receiver do
esn't understand
one or more of the formats used, there would be security issues with such a feat
ure.
If multiple keys formats were allowed,
receivers of these key definitions would need to be able to make sure that it's the same receivers of these key definitions would need to be able to make sure that it's the same
key represented in each field and not simply use one of the key formats without checking for key represented in each field and not simply use one of the key formats without checking for
equivalence. If equivalence were not carefully checked, it is possible for an at tacker to insert equivalence. If equivalence is not carefully checked, it is possible for an atta cker to insert
their own key into one of the formats without needing to have control over the o ther formats. This their own key into one of the formats without needing to have control over the o ther formats. This
could potentially lead to a situation where one key is used by part of the syste m (such as could potentially lead to a situation where one key is used by part of the syste m (such as
identifying the client instance) and a different key in a different format in th e same message is identifying the client instance) and a different key in a different format in th e same message is
used for other things (such as calculating signature validity). However, in such cases, it is used for other things (such as calculating signature validity). However, in such cases, it is
impossible for the receiver to ensure that all formats contain the same key info rmation since it is impossible for the receiver to ensure that all formats contain the same key info rmation since it is
assumed that the receiver cannot understand all of the formats.</t> assumed that the receiver cannot understand all of the formats.</t>
<t>To combat this, all keys presented by value have to be in exactly one
<t>To combat this, all keys presented by value have to be in exactly one support supported format known
ed format known
by the receiver as discussed in <xref target="key-format"/>. In most cases, a cl ient instance is going to be configured with its keys in a by the receiver as discussed in <xref target="key-format"/>. In most cases, a cl ient instance is going to be configured with its keys in a
single format, and it will simply present that format as-is to the AS in its req single format, and it will simply present that format as is to the AS in its req
uest. A client uest. A client
instance capable of multiple formats can use <xref target="discovery">AS discove instance capable of multiple formats can use AS discovery (<xref target="discove
ry</xref> to determine which formats ry"> </xref>) to determine which formats
are supported, if desired. An AS should be generous in supporting many different key formats to are supported, if desired. An AS should be generous in supporting many different key formats to
allow different types of client software and client instance deployments. An AS implementation allow different types of client software and client instance deployments. An AS implementation
should try to support multiple formats to allow a variety of client software to connect.</t> should try to support multiple formats to allow a variety of client software to connect.</t>
</section>
</section> <section anchor="security-async">
<section anchor="security-async"><name>Asynchronous Interactions</name> <name>Asynchronous Interactions</name>
<t>GNAP allows the RO to be contacted by the AS asynchronously, outside
<t>GNAP allows the RO to be contacted by the AS asynchronously, outside the regu the regular flow of the
lar flow of the
protocol. This allows for some advanced use cases, such as cross-user authentica tion or information protocol. This allows for some advanced use cases, such as cross-user authentica tion or information
release, but such advanced use cases have some distinct issues that implementors need to be fully release, but such advanced use cases have some distinct issues that implementors need to be fully
aware of before using these features.</t> aware of before using these features.</t>
<t>First, in many applications, the return of subject information to the
<t>First, in many applications, the return of a subject information to the clien client instance could
t instance could indicate to the client instance that the end user is the party represented by th
indicate to the client instance that the end-user is the party represented by th at information,
at information, functionally allowing the end user to authenticate to the client application. Wh
functionally allowing the end-user to authenticate to the client application. Wh ile the details of
ile the details of
a fully functional authentication protocol are outside the scope of GNAP, it is a common a fully functional authentication protocol are outside the scope of GNAP, it is a common
exercise for a client instance to be requesting information about the end user. exercise for a client instance to request information about the end user. This i
This is facilitated s facilitated
by the several <xref target="interaction-start">interaction methods</xref> defin by several interaction methods (<xref target="interaction-start"> </xref>) defin
ed in GNAP that allow the end user ed in GNAP that allow the end user
to begin interaction directly with the AS. However, when the subject of the info rmation is to begin interaction directly with the AS. However, when the subject of the info rmation is
intentionally not the end-user, the client application will need some way to dif ferentiate between intentionally not the end user, the client application will need some way to dif ferentiate between
requests for authentication of the end user and requests for information about a different user. requests for authentication of the end user and requests for information about a different user.
Confusing these states could lead to an attacker having their account associated with a privileged Confusing these states could lead to an attacker having their account associated with a privileged
user. Client instances can mitigate this by having distinct code paths for prima user. Client instances can mitigate this by having distinct code paths for prima
ry end user ry end-user
authentication and requesting subject information about secondary users, such as authentication and for requesting subject information about secondary users, suc
in a call center. h as in a call center.
In such use cases, the client software used by the resource owner (the caller) a In such use cases, the client software used by the RO (the caller) and the end u
nd the end-user ser
(the agent) are generally distinct, allowing the AS to differentiate between the agent's corporate device (the agent) are generally distinct, allowing the AS to differentiate between the agent's corporate device
making the request and the caller's personal device approving the request.</t> making the request and the caller's personal device approving the request.</t>
<t>Second, ROs that interact asynchronously do not usually have the same
<t>Second, RO's interacting asynchronously do not usually have the same context context as an end user in an
as an end user in an
application attempting to perform the task needing authorization. As such, the a synchronous requests application attempting to perform the task needing authorization. As such, the a synchronous requests
for authorization coming to the RO from the AS might have very little to do with what the RO is for authorization coming to the RO from the AS might have very little to do with what the RO is
doing at the time. This situation can consequently lead to authorization fatigue on the part of the doing at the time. This situation can consequently lead to authorization fatigue on the part of the
RO, where any incoming authorization request is quickly approved and dispatched without the RO RO, where any incoming authorization request is quickly approved and dispatched without the RO
making a proper verification of the request. An attacker can exploit this fatigu e and get the RO making a proper verification of the request. An attacker can exploit this fatigu e and get the RO
to authorize the attacker's system for access. To mitigate this, AS systems depl oying asynchronous to authorize the attacker's system for access. To mitigate this, AS systems depl oying asynchronous
authorization should only prompt the RO when the RO is expecting such a request, and significant authorization should only prompt the RO when the RO is expecting such a request, and significant
user experience engineering efforts need to be employed to ensure the RO can cle user experience engineering efforts need to be employed to ensure that the RO ca
arly make the n clearly make the
appropriate security decision. Furthermore, audit capability, and the ability to appropriate security decision. Furthermore, audit capability and the ability to
undo access undo access
decisions that may be ongoing, is particularly important in the asynchronous cas decisions that may be ongoing are particularly important in the asynchronous cas
e.</t> e.</t>
</section>
</section> <section anchor="security-compromised-rs">
<section anchor="security-compromised-rs"><name>Compromised RS</name> <name>Compromised RS</name>
<t>An attacker may aim to gain access to confidential or sensitive resou
<t>An attacker may aim to gain access to confidential or sensitive resources. Th rces. The measures for hardening and monitoring RS systems (beyond protection wi
e measures for hardening and monitoring resource server systems (beyond protecti th access tokens) are out of the scope of this document, but the use of GNAP to
on with access tokens) is out of the scope of this document, but the use of GNAP protect a system does not absolve the RS of following best practices.
to protect a system does not absolve the resource server of following best prac GNAP generally considers that a breach can occur and therefore advises to prefer
tices. key-bound tokens whenever possible, which at least limits the impact of access
GNAP generally considers a breach can occur, and therefore advises to prefer key token leakage by a compromised or malicious RS.</t>
-bound tokens whenever possible, which at least limits the impact of access toke </section>
n leakage by a compromised or malicious RS.</t> <section anchor="security-as-keys">
<name>AS-Provided Token Keys</name>
</section> <t>While the most common token-issuance pattern is to bind the access to
<section anchor="security-as-keys"><name>AS-Provided Token Keys</name> ken to the client instance's
<t>While the most common token issuance pattern is to bind the access token to t
he client instance's
presented key, it is possible for the AS to provide a binding key along with an access token, as presented key, it is possible for the AS to provide a binding key along with an access token, as
shown by the <spanx style="verb">key</spanx> field of the token response in <xre f target="response-token-single"/>. This practice allows shown by the <tt>key</tt> field of the token response in <xref target="response- token-single"/>. This practice allows
for an AS to generate and manage the keys associated with tokens independently o f the keys known for an AS to generate and manage the keys associated with tokens independently o f the keys known
to client instances.</t> to client instances.</t>
<t>If the key material is returned by value from the AS, then the client
<t>If the key material is returned by value from the AS, then the client instanc instance will simply use this
e will simply use this
key value when presenting the token. This can be exploited by an attacker to iss ue a compromised token key value when presenting the token. This can be exploited by an attacker to iss ue a compromised token
to an unsuspecting client, assuming that the client instance trusts the attacker 's AS to issue tokens to an unsuspecting client, assuming that the client instance trusts the attacker 's AS to issue tokens
for the target RS. In this attack, the attacker first gets a token bound to a ke y under the attacker's for the target RS. In this attack, the attacker first gets a token bound to a ke y under the attacker's
control. This token is likely bound to an authorization or account controlled by the attacker. control. This token is likely bound to an authorization or account controlled by the attacker.
The attacker then re-issues that same token to the client instance, this time ac ting as an AS. The attacker The attacker then reissues that same token to the client instance, this time act ing as an AS. The attacker
can return their own key to the client instance, tricking the client instance in to using the attacker's can return their own key to the client instance, tricking the client instance in to using the attacker's
token. Such an attack is also possible when the key is returned by reference, if the attacker token. Such an attack is also possible when the key is returned by reference, if the attacker
is able to provide a reference meaningful to the client instance that references a key under the attacker's is able to provide a reference meaningful to the client instance that references a key under the attacker's
control. This substitution attack is similar to some of the main issues found wi th bearer tokens control. This substitution attack is similar to some of the main issues found wi th bearer tokens
as discussed in <xref target="security-bearer-tokens"/>.</t> as discussed in <xref target="security-bearer-tokens"/>.</t>
<t>Returning a key with an access token should be limited to only circumstances <t>Returning a key with an access token should be limited to circumstances where
where both the client and AS both the client and AS
can be verified to be honest, and further only when the tradeoff of not using a can be verified to be honest and when the trade-off of not using a client instan
client instance's own keys ce's own keys
is worth the additional risk.</t> is worth the additional risk.</t>
</section>
</section>
<section anchor="privacy">
<name>Privacy Considerations</name>
<t>The privacy considerations in this section are modeled after the list o
f privacy threats in "Privacy Considerations for Internet Protocols" <xref targe
t="RFC6973"/> and either explain how these threats are mitigated or advise how t
he threats relate to GNAP.</t>
<section anchor="surveillance">
<name>Surveillance</name>
<t>Surveillance is the observation or monitoring of an individual's comm
unications or activities. Surveillance can be conducted by observers or eavesdro
ppers at any point along the communications path.</t>
<t>GNAP assumes the TLS protection used throughout the spec is intact. W
ithout the protection of TLS, there are many points throughout the use of GNAP t
hat could lead to possible surveillance. Even with the proper use of TLS, survei
llance could occur by several parties outside of the TLS-protected channels, as
discussed in the subsections below.</t>
<section anchor="surveillance-by-the-client">
<name>Surveillance by the Client</name>
<t>The purpose of GNAP is to authorize clients to be able to access in
formation on behalf of a user. So while it is expected that the client may be aw
are of the user's identity as well as data being fetched for that user, in some
cases, the extent of the client may be beyond what the user is aware of. For exa
mple, a client may be implemented as multiple distinct pieces of software, such
as a logging service or a mobile application that reports usage data to an exter
nal backend service. Each of these pieces could gain information about the user
without the user being aware of this action.</t>
<t>When the client software uses a hosted asset for its components, su
ch as its logo image, the fetch of these assets can reveal user actions to the h
ost. If the AS presents the logo URI to the RO in a browser page, the browser wi
ll fetch the logo URL from the authorization screen. This fetch will tell the ho
st of the logo image that someone is accessing an instance of the client softwar
e and requesting access for it. This is particularly problematic when the host o
f the asset is not the client software itself, such as when a content delivery n
etwork is used.</t>
</section>
<section anchor="surveillance-by-the-authorization-server">
<name>Surveillance by the Authorization Server</name>
<t>The role of the AS is to manage the authorization of client instanc
es to protect access to the user's data. In this role, the AS is by definition a
ware of each authorization of a client instance by a user. When the AS shares us
er information with the client instance, it needs to make sure that it has the p
ermission from that user to do so.</t>
<t>Additionally, as part of the authorization grant process, the AS ma
y be aware of which RSs the client intends to use an access token at. However, i
t is possible to design a system using GNAP in which this knowledge is not made
available to the AS, such as by avoiding the use of the <tt>locations</tt> objec
t in the authorization request.</t>
<t>If the AS's implementation of access tokens is such that it require
s an RS callback to the AS to validate them, then the AS will be aware of which
RSs are actively in use and by which users and clients. To avoid this possibilit
y, the AS would need to structure access tokens in such a way that they can be v
alidated by the RS without notifying the AS that the token is being validated.</
t>
</section>
</section>
<section anchor="stored-data">
<name>Stored Data</name>
<t>Several parties in the GNAP process are expected to persist data at least
temporarily, if not semi-permanently, for the normal functioning of the
system. If compromised, this could lead to exposure of sensitive
information. This section documents the potentially sensitive information each
party in GNAP is expected to store for normal operation. Naturally, it is
possible for any party to store information related to protocol mechanics
(such as audit logs, etc.) for longer than is technically necessary.
</t>
<t>The AS is expected to store Subject Identifiers for users indefinitel
y, in order to be able to include them in the responses to clients. The AS is al
so expected to store client key identifiers associated with display information
about the client, such as its name and logo.</t>
<t>The client is expected to store its client instance key indefinitely,
in order to authenticate to the AS for the normal functioning of the GNAP flows
. Additionally, the client will be temporarily storing artifacts issued by the A
S during a flow, and these artifacts ought to be discarded by the client when th
e transaction is complete.</t>
<t>The RS is not required to store any state for its normal operation, a
s far as its part in implementing GNAP. Depending on the implementation of acces
s tokens, the RS may need to cache public keys from the AS in order to validate
access tokens.</t>
</section>
<section anchor="intrusion">
<name>Intrusion</name>
<t>Intrusion refers to the ability of various parties to send unsolicite
d messages or cause denial of service for unrelated parties.</t>
<t>If the RO is different from the end user, there is an opportunity for
the end user to cause unsolicited messages to be sent to the RO if the system p
rompts the RO for consent when an end user attempts to access their data.</t>
<t>The format and contents of Subject Identifiers are intentionally not
defined by GNAP. If the AS uses values for Subject Identifiers that are also ide
ntifiers for communication channels (e.g., an email address or phone number), th
is opens up the possibility for a client to learn this information when it was n
ot otherwise authorized to access this kind of data about the user.</t>
</section>
<section anchor="correlation">
<name>Correlation</name>
<t>The threat of correlation is the combination of various pieces of inf
ormation related to an individual in a way that defies their expectations of wha
t others know about them.</t>
<section anchor="privacy-correlation-client">
<name>Correlation by Clients</name>
<t>The biggest risk of correlation in GNAP is when an AS returns stabl
e, consistent user identifiers to multiple different applications. In this case,
applications created by different parties would be able to correlate these user
identifiers out of band in order to know which users they have in common.</t>
<t>The most common example of this in practice is tracking for adverti
sing purposes, such that a client shares their list of user IDs with an ad platf
orm that is then able to retarget ads to applications created by other parties.
In contrast, a positive example of correlation is a corporate acquisition where
two previously unrelated clients now do need to be able to identify the same use
r between the two clients, such as when software systems are intentionally conne
cted by the end user.</t>
<t>Another means of correlation comes from the use of RS-first discove
ry (<xref target="rs-request-without-token"> </xref>). A client instance that kn
ows nothing other than an RS's URL could make an unauthenticated call to the RS
and learn which AS protects the resources there. If the client instance knows so
mething about the AS, such as it being a single-user AS or belonging to a specif
ic organization, the client instance could, through association, learn things ab
out the resource without ever gaining access to the resource itself.</t>
</section>
<section anchor="correlation-by-resource-servers">
<name>Correlation by Resource Servers</name>
<t>Unrelated RSs also have an opportunity to correlate users if the AS
includes stable user identifiers in access tokens or in access token introspect
ion responses.</t>
<t>In some cases, an RS may not actually need to be able to identify u
sers (such as an RS providing access to a company cafeteria menu, which only nee
ds to validate whether the user is a current employee), so ASes should be though
tful of when user identifiers are actually necessary to communicate to RSs for t
he functioning of the system.</t>
<t>However, note that the lack of inclusion of a user identifier in an
access token may be a risk if there is a concern that two users may voluntarily
share access tokens between them in order to access protected resources. For exa
mple, if a website wants to limit access to only people over 18, and such does n
ot need to know any user identifiers, an access token may be issued by an AS con
tains only the claim "over 18". If the user is aware that this access token does
n't reference them individually, they may be willing to share the access token w
ith a user who is under 18 in order to let them get access to the website. (Note
that the binding of an access token to a non-extractable client instance key al
so prevents the access token from being voluntarily shared.)</t>
</section>
<section anchor="correlation-by-authorization-servers">
<name>Correlation by Authorization Servers</name>
<t>Clients are expected to be identified by their client instance key.
If a particular client instance key is used at more than one AS, this could ope
n up the possibility for multiple unrelated ASes to correlate client instances.
This is especially a problem in the common case where a client instance is used
by a single individual, as it would allow the ASes to correlate that individual
between them. If this is a concern of a client, the client should use distinct k
eys with each AS.</t>
</section>
</section>
<section anchor="disclosure-in-shared-references">
<name>Disclosure in Shared References</name>
<t>Throughout many parts of GNAP, the parties pass shared references bet
ween each other, sometimes in place of the values themselves (for example, the <
tt>interact_ref</tt> value used throughout the flow). These references are inten
ded to be random strings and should not contain any private or sensitive data th
at could potentially leak information between parties.</t>
</section>
</section>
</middle>
<back>
<displayreference target="RFC9110" to="HTTP"/>
<displayreference target="I-D.ietf-gnap-resource-servers" to="GNAP-RS"/>
<displayreference target="I-D.ietf-oauth-security-topics" to="OAUTH-SEC-TOPI
CS"/>
<references>
<name>References</name>
<references anchor="sec-normative-references">
<name>Normative References</name>
</section> <referencegroup anchor="BCP195" target="https://www.rfc-editor.org/info/
</section> bcp195">
<section anchor="privacy"><name>Privacy Considerations</name> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC
.8996.xml"/>
<t>The privacy considerations in this section are modeled after the list of priv <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC
acy threats in <xref target="RFC6973"/>, "Privacy Considerations for Internet Pr .9325.xml"/>
otocols", and either explain how these threats are mitigated or advise how the t </referencegroup>
hreats relate to GNAP.</t> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2
397.xml"/>
<section anchor="surveillance"><name>Surveillance</name> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3
339.xml"/>
<t>Surveillance is the observation or monitoring of an individual's communicatio <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3
ns or activities. Surveillance can be conducted by observers or eavesdroppers at 986.xml"/>
any point along the communications path.</t> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4
648.xml"/>
<t>GNAP assumes the TLS protection used throughout the spec is intact. Without t <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5
he protection of TLS, there are many points throughout the use of GNAP that woul 646.xml"/>
d lead to possible surveillance. Even with the proper use of TLS, surveillance c <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7
ould occur by several parties outside of the TLS-protected channels, as discusse 468.xml"/>
d in the sections below.</t> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7
515.xml"/>
<section anchor="surveillance-by-the-client"><name>Surveillance by the Client</n <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7
ame> 517.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
<t>The purpose of GNAP is to authorize clients to be able to access information 749.xml"/>
on behalf of a user. So while it is expected that the client may be aware of the <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
user's identity as well as data being fetched for that user, in some cases the 750.xml"/>
extent of the client may be beyond what the user is aware of. For example, a cli <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
ent may be implemented as multiple distinct pieces of software, such as a loggin 174.xml"/>
g service or a mobile app that reports usage data to an external backend service <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
. Each of these pieces could gain information about the user without the user be 259.xml"/>
ing aware of this action.</t> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
705.xml"/>
<t>When the client software uses a hosted asset for its components, such as its <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9
logo image, the fetch of these assets can reveal user actions to the host. If th 110.xml"/>
e AS presents the logo URI to the resource owner in a browser page, the browser <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9
will fetch the logo URL from the authorization screen. This fetch will tell the 111.xml"/>
host of the logo image that someone is accessing an instance of the client softw <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9
are and requesting access for it. This is particularly problematic when the host 421.xml"/>
of the asset is not the client software itself, such as when a content delivery <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9
network is used.</t> 530.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9
</section> 493.xml"/>
<section anchor="surveillance-by-the-authorization-server"><name>Surveillance by
the Authorization Server</name>
<t>The role of the authorization server is to manage the authorization of client
instances to protect access to the user's data. In this role, the authorization
server is by definition aware of each authorization of a client instance by a u
ser. When the authorization server shares user information with the client insta
nce, it needs to make sure that it has the permission from that user to do so.</
t>
<t>Additionally, as part of the authorization grant process, the authorization s
erver may be aware of which resource servers the client intends to use an access
token at. However, it is possible to design a system using GNAP in which this k
nowledge is not made available to the authorization server, such as by avoiding
the use of the <spanx style="verb">locations</spanx> object in the authorization
request.</t>
<t>If the authorization server's implementation of access tokens is such that it
requires a resource server call back to the authorization server to validate th
em, then the authorization server will be aware of which resource servers are ac
tively in use and by which users and which clients. To avoid this possibility, t
he authorization server would need to structure access tokens in such a way that
they can be validated by the resource server without notifying the authorizatio
n server that the token is being validated.</t>
</section>
</section>
<section anchor="stored-data"><name>Stored Data</name>
<t>Several parties in the GNAP process are expected to persist data at least tem
porarily, if not semi-permanently, for the normal functioning of the system. If
compromised, this could lead to exposure of sensitive information. This section
documents the potentially sensitive information each party in GNAP is expected t
o store for normal operation. Naturally it is possible that any party is storing
information for longer than technically necessary of the protocol mechanics (su
ch as audit logs, etc).</t>
<t>The authorization server is expected to store subject identifiers for users i
ndefinitely, in order to be able to include them in the responses to clients. Th
e authorization server is also expected to store client key identifiers associat
ed with display information about the client such as its name and logo.</t>
<t>The client is expected to store its client instance key indefinitely, in orde
r to authenticate to the authorization server for the normal functioning of the
GNAP flows. Additionally, the client will be temporarily storing artifacts issue
d by the authorization server during a flow, and these artifacts ought to be dis
carded by the client when the transaction is complete.</t>
<t>The resource server is not required to store any state for its normal operati
on, as far as its part in implementing GNAP. Depending on the implementation of
access tokens, the resource server may need to cache public keys from the author
ization server in order to validate access tokens.</t>
</section>
<section anchor="intrusion"><name>Intrusion</name>
<t>Intrusion refers to the ability of various parties to send unsolicited messag
es or cause denial of service for unrelated parties.</t>
<t>If the resource owner is different from the end user, there is an opportunity
for the end user to cause unsolicited messages to be sent to the resource owner
if the system prompts the resource owner for consent when an end user attempts
to access their data.</t>
<t>The format and contents of subject identifiers are intentionally not defined
by GNAP. If the authorization server uses values for subject identifiers that ar
e also identifiers for communication channels, (e.g. an email address or phone n
umber), this opens up the possibility for a client to learn this information whe
n it was not otherwise authorized to access this kind of data about the user.</t
>
</section>
<section anchor="correlation"><name>Correlation</name>
<t>The threat of correlation is the combination of various pieces of information
related to an individual in a way that defies their expectations of what others
know about them.</t>
<section anchor="privacy-correlation-client"><name>Correlation by Clients</name>
<t>The biggest risk of correlation in GNAP is when an authorization server retur
ns stable consistent user identifiers to multiple different applications. In thi
s case, applications created by different parties would be able to correlate the
se user identifiers out of band in order to know which users they have in common
.</t>
<t>The most common example of this in practice is tracking for advertising purpo
ses, such that a client shares their list of user IDs with an ad platform that i
s then able to retarget ads to applications created by other parties. In contras
t, a positive example of correlation is a corporate acquisition where two previo
usly unrelated clients now do need to be able to identify the same user between
the two clients, such as when software systems are intentionally connected by th
e end user.</t>
<t>Another means of correlation comes from the use of <xref target="rs-request-w
ithout-token">RS-first discovery</xref>. A client instance knowing nothing other
than an RS's URL could make an unauthenticated call to the RS and learn which A
S protects the resources there. If the client instance knows something about the
AS, such as it being a single-user AS or belonging to a specific organization,
the client instance could, through association, learn things about the resource
without ever gaining access to the resource itself.</t>
</section>
<section anchor="correlation-by-resource-servers"><name>Correlation by Resource
Servers</name>
<t>Unrelated resource servers also have an opportunity to correlate users if the
authorization server includes stable user identifiers in access tokens or in ac
cess token introspection responses.</t>
<t>In some cases a resource server may not actually need to be able to identify
users, (such as a resource server providing access to a company cafeteria menu w
hich only needs to validate whether the user is a current employee), so authoriz
ation servers should be thoughtful of when user identifiers are actually necessa
ry to communicate to resource servers for the functioning of the system.</t>
<t>However, note that the lack of inclusion of a user identifier in an access to
ken may be a risk if there is a concern that two users may voluntarily share acc
ess tokens between them in order to access protected resources. For example, if
a website wants to limit access to only people over 18, and such does not need t
o know any user identifiers, an access token may be issued by an AS contains onl
y the claim "over 18". If the user is aware that this access token doesn't refer
ence them individually, they may be willing to share the access token with a use
r who is under 18 in order to let them get access to the website. (Note that the
binding of an access token to a non-extractable client instance key also preven
ts the access token from being voluntarily shared.)</t>
</section>
<section anchor="correlation-by-authorization-servers"><name>Correlation by Auth
orization Servers</name>
<t>Clients are expected to be identified by their client instance key. If a part
icular client instance key is used at more than one authorization server, this c
ould open up the possibility for multiple unrelated authorization servers to cor
relate client instances. This is especially a problem in the common case where a
client instance is used by a single individual, as it would allow the authoriza
tion servers to correlate that individual between them. If this is a concern of
a client, the client should use distinct keys with each authorization server.</t
>
</section>
</section>
<section anchor="disclosure-in-shared-references"><name>Disclosure in Shared Ref
erences</name>
<t>Throughout many parts of GNAP, the parties pass shared references between eac <reference anchor="HASH-ALG" target="https://www.iana.org/assignments/na
h other, sometimes in place of the values themselves. For example the <spanx sty med-information/">
le="verb">interact_ref</spanx> value used throughout the flow. These references <front>
are intended to be random strings and should not contain any private or sensitiv <title>Named Information Hash Algorithm Registry</title>
e data that would potentially leak information between parties.</t> <author>
<organization>IANA</organization>
</author>
</front>
</reference>
</section> <reference anchor="OIDC" target="https://openid.net/specs/openid-connect
</section> -core-1_0.html">
<front>
<title>OpenID Connect Core 1.0 incorporating errata set 2</title>
<author initials="N." surname="Sakimura">
<organization/>
</author>
<author initials="J." surname="Bradley">
<organization/>
</author>
<author initials="M." surname="Jones">
<organization/>
</author>
<author initials="B." surname="de Medeiros">
<organization/>
</author>
<author initials="C." surname="Mortimore">
<organization/>
</author>
<date year="2023" month="December"/>
</front>
</reference>
</middle> <reference anchor="SAML2" target="https://docs.oasis-open.org/security/s
aml/v2.0/saml-core-2.0-os.pdf">
<front>
<title>Assertions and Protocol for the OASIS Security Assertion Mark
up Language (SAML) V2.0</title>
<author initials="S., Ed." surname="Cantor">
<organization/>
</author>
<author initials="J., Ed." surname="Kemp">
<organization/>
</author>
<author initials="R., Ed." surname="Philpott">
<organization/>
</author>
<author initials="E." surname="Maler, Ed.">
<organization/>
</author>
<date year="2005" month="March"/>
</front>
<refcontent>OASIS Standard</refcontent>
</reference>
<back> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2 119.xml"/>
<references title='Normative References' anchor="sec-normative-references"> </references>
<references anchor="sec-informative-references">
<name>Informative References</name>
<referencegroup anchor="BCP195" target="https://www.rfc-editor.org/info/bcp195"> <reference anchor="GNAP-REG" target="https://www.iana.org/assignments/gnap">
<reference anchor="RFC8996" target="https://www.rfc-editor.org/info/rfc8996">
<front> <front>
<title>Deprecating TLS 1.0 and TLS 1.1</title> <title>Grant Negotiation and Authorization Protocol (GNAP)</title>
<author fullname="K. Moriarty" initials="K." surname="Moriarty"/> <author>
<author fullname="S. Farrell" initials="S." surname="Farrell"/> <organization>IANA</organization>
<date month="March" year="2021"/> </author>
<abstract>
<t>This document formally deprecates Transport Layer Security (TLS) vers
ions 1.0 (RFC 2246) and 1.1 (RFC 4346). Accordingly, those documents have been m
oved to Historic status. These versions lack support for current and recommended
cryptographic algorithms and mechanisms, and various government and industry pr
ofiles of applications using TLS now mandate avoiding these old TLS versions. TL
S version 1.2 became the recommended version for IETF protocols in 2008 (subsequ
ently being obsoleted by TLS version 1.3 in 2018), providing sufficient time to
transition away from older versions. Removing support for older versions from im
plementations reduces the attack surface, reduces opportunity for misconfigurati
on, and streamlines library and product maintenance.</t>
<t>This document also deprecates Datagram TLS (DTLS) version 1.0 (RFC 43
47) but not DTLS version 1.2, and there is no DTLS version 1.1.</t>
<t>This document updates many RFCs that normatively refer to TLS version
1.0 or TLS version 1.1, as described herein. This document also updates the bes
t practices for TLS usage in RFC 7525; hence, it is part of BCP 195.</t>
</abstract>
</front> </front>
<seriesInfo name="BCP" value="195"/>
<seriesInfo name="RFC" value="8996"/>
<seriesInfo name="DOI" value="10.17487/RFC8996"/>
</reference> </reference>
<reference anchor="RFC9325" target="https://www.rfc-editor.org/info/rfc9325"> <reference anchor="Auth-Schemes" target="https://www.iana.org/assignments/http -authschemes">
<front> <front>
<title>Recommendations for Secure Use of Transport Layer Security (TLS) an <title>HTTP Authentication Schemes</title>
d Datagram Transport Layer Security (DTLS)</title> <author>
<author fullname="Y. Sheffer" initials="Y." surname="Sheffer"/> <organization>IANA</organization>
<author fullname="P. Saint-Andre" initials="P." surname="Saint-Andre"/> </author>
<author fullname="T. Fossati" initials="T." surname="Fossati"/>
<date month="November" year="2022"/>
<abstract>
<t>Transport Layer Security (TLS) and Datagram Transport Layer Security
(DTLS) are used to protect data exchanged over a wide range of application proto
cols and can also form the basis for secure transport protocols. Over the years,
the industry has witnessed several serious attacks on TLS and DTLS, including a
ttacks on the most commonly used cipher suites and their modes of operation. Thi
s document provides the latest recommendations for ensuring the security of depl
oyed services that use TLS and DTLS. These recommendations are applicable to the
majority of use cases.</t>
<t>RFC 7525, an earlier version of the TLS recommendations, was publishe
d when the industry was transitioning to TLS 1.2. Years later, this transition i
s largely complete, and TLS 1.3 is widely available. This document updates the g
uidance given the new environment and obsoletes RFC 7525. In addition, this docu
ment updates RFCs 5288 and 6066 in view of recent attacks.</t>
</abstract>
</front> </front>
<seriesInfo name="BCP" value="195"/>
<seriesInfo name="RFC" value="9325"/>
<seriesInfo name="DOI" value="10.17487/RFC9325"/>
</reference> </reference>
</referencegroup> <reference anchor="Subj-ID-Formats" target="https://www.iana.org/assignments/s
ecevent">
<reference anchor="RFC2397"> <front>
<front> <title>Subject Identifier Formats</title>
<title>The "data" URL scheme</title> <author>
<author fullname="L. Masinter" initials="L." surname="Masinter"/> <organization>IANA</organization>
<date month="August" year="1998"/>
<abstract>
<t>A new URL scheme, "data", is defined. It allows inclusion of small data
items as "immediate" data, as if it had been included externally. [STANDARDS-TR
ACK]</t>
</abstract>
</front>
<seriesInfo name="RFC" value="2397"/>
<seriesInfo name="DOI" value="10.17487/RFC2397"/>
</reference>
<reference anchor="RFC3339">
<front>
<title>Date and Time on the Internet: Timestamps</title>
<author fullname="G. Klyne" initials="G." surname="Klyne"/>
<author fullname="C. Newman" initials="C." surname="Newman"/>
<date month="July" year="2002"/>
<abstract>
<t>This document defines a date and time format for use in Internet protoc
ols that is a profile of the ISO 8601 standard for representation of dates and t
imes using the Gregorian calendar.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="3339"/>
<seriesInfo name="DOI" value="10.17487/RFC3339"/>
</reference>
<reference anchor="RFC3986">
<front>
<title>Uniform Resource Identifier (URI): Generic Syntax</title>
<author fullname="T. Berners-Lee" initials="T." surname="Berners-Lee"/>
<author fullname="R. Fielding" initials="R." surname="Fielding"/>
<author fullname="L. Masinter" initials="L." surname="Masinter"/>
<date month="January" year="2005"/>
<abstract>
<t>A Uniform Resource Identifier (URI) is a compact sequence of characters
that identifies an abstract or physical resource. This specification defines th
e generic URI syntax and a process for resolving URI references that might be in
relative form, along with guidelines and security considerations for the use of
URIs on the Internet. The URI syntax defines a grammar that is a superset of al
l valid URIs, allowing an implementation to parse the common components of a URI
reference without knowing the scheme-specific requirements of every possible id
entifier. This specification does not define a generative grammar for URIs; that
task is performed by the individual specifications of each URI scheme. [STANDAR
DS-TRACK]</t>
</abstract>
</front>
<seriesInfo name="STD" value="66"/>
<seriesInfo name="RFC" value="3986"/>
<seriesInfo name="DOI" value="10.17487/RFC3986"/>
</reference>
<reference anchor="RFC4648">
<front>
<title>The Base16, Base32, and Base64 Data Encodings</title>
<author fullname="S. Josefsson" initials="S." surname="Josefsson"/>
<date month="October" year="2006"/>
<abstract>
<t>This document describes the commonly used base 64, base 32, and base 16
encoding schemes. It also discusses the use of line-feeds in encoded data, use
of padding in encoded data, use of non-alphabet characters in encoded data, use
of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK]</t>
</abstract>
</front>
<seriesInfo name="RFC" value="4648"/>
<seriesInfo name="DOI" value="10.17487/RFC4648"/>
</reference>
<reference anchor="RFC5646">
<front>
<title>Tags for Identifying Languages</title>
<author fullname="A. Phillips" initials="A." role="editor" surname="Phillips
"/>
<author fullname="M. Davis" initials="M." role="editor" surname="Davis"/>
<date month="September" year="2009"/>
<abstract>
<t>This document describes the structure, content, construction, and seman
tics of language tags for use in cases where it is desirable to indicate the lan
guage used in an information object. It also describes how to register values fo
r use in language tags and the creation of user-defined extensions for private i
nterchange. This document specifies an Internet Best Current Practices for the I
nternet Community, and requests discussion and suggestions for improvements.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="47"/>
<seriesInfo name="RFC" value="5646"/>
<seriesInfo name="DOI" value="10.17487/RFC5646"/>
</reference>
<reference anchor="RFC7468">
<front>
<title>Textual Encodings of PKIX, PKCS, and CMS Structures</title>
<author fullname="S. Josefsson" initials="S." surname="Josefsson"/>
<author fullname="S. Leonard" initials="S." surname="Leonard"/>
<date month="April" year="2015"/>
<abstract>
<t>This document describes and discusses the textual encodings of the Publ
ic-Key Infrastructure X.509 (PKIX), Public-Key Cryptography Standards (PKCS), an
d Cryptographic Message Syntax (CMS). The textual encodings are well-known, are
implemented by several applications and libraries, and are widely deployed. This
document articulates the de facto rules by which existing implementations opera
te and defines them so that future implementations can interoperate.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="7468"/>
<seriesInfo name="DOI" value="10.17487/RFC7468"/>
</reference>
<reference anchor="RFC7515">
<front>
<title>JSON Web Signature (JWS)</title>
<author fullname="M. Jones" initials="M." surname="Jones"/>
<author fullname="J. Bradley" initials="J." surname="Bradley"/>
<author fullname="N. Sakimura" initials="N." surname="Sakimura"/>
<date month="May" year="2015"/>
<abstract>
<t>JSON Web Signature (JWS) represents content secured with digital signat
ures or Message Authentication Codes (MACs) using JSON-based data structures. Cr
yptographic algorithms and identifiers for use with this specification are descr
ibed in the separate JSON Web Algorithms (JWA) specification and an IANA registr
y defined by that specification. Related encryption capabilities are described i
n the separate JSON Web Encryption (JWE) specification.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="7515"/>
<seriesInfo name="DOI" value="10.17487/RFC7515"/>
</reference>
<reference anchor="RFC7517">
<front>
<title>JSON Web Key (JWK)</title>
<author fullname="M. Jones" initials="M." surname="Jones"/>
<date month="May" year="2015"/>
<abstract>
<t>A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data struct
ure that represents a cryptographic key. This specification also defines a JWK S
et JSON data structure that represents a set of JWKs. Cryptographic algorithms a
nd identifiers for use with this specification are described in the separate JSO
N Web Algorithms (JWA) specification and IANA registries established by that spe
cification.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="7517"/>
<seriesInfo name="DOI" value="10.17487/RFC7517"/>
</reference>
<reference anchor="RFC6749">
<front>
<title>The OAuth 2.0 Authorization Framework</title>
<author fullname="D. Hardt" initials="D." role="editor" surname="Hardt"/>
<date month="October" year="2012"/>
<abstract>
<t>The OAuth 2.0 authorization framework enables a third-party application
to obtain limited access to an HTTP service, either on behalf of a resource own
er by orchestrating an approval interaction between the resource owner and the H
TTP service, or by allowing the third-party application to obtain access on its
own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol des
cribed in RFC 5849. [STANDARDS-TRACK]</t>
</abstract>
</front>
<seriesInfo name="RFC" value="6749"/>
<seriesInfo name="DOI" value="10.17487/RFC6749"/>
</reference>
<reference anchor="RFC6750">
<front>
<title>The OAuth 2.0 Authorization Framework: Bearer Token Usage</title>
<author fullname="M. Jones" initials="M." surname="Jones"/>
<author fullname="D. Hardt" initials="D." surname="Hardt"/>
<date month="October" year="2012"/>
<abstract>
<t>This specification describes how to use bearer tokens in HTTP requests
to access OAuth 2.0 protected resources. Any party in possession of a bearer tok
en (a "bearer") can use it to get access to the associated resources (without de
monstrating possession of a cryptographic key). To prevent misuse, bearer tokens
need to be protected from disclosure in storage and in transport. [STANDARDS-TR
ACK]</t>
</abstract>
</front>
<seriesInfo name="RFC" value="6750"/>
<seriesInfo name="DOI" value="10.17487/RFC6750"/>
</reference>
<reference anchor="RFC8174">
<front>
<title>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</title>
<author fullname="B. Leiba" initials="B." surname="Leiba"/>
<date month="May" year="2017"/>
<abstract>
<t>RFC 2119 specifies common key words that may be used in protocol specif
ications. This document aims to reduce the ambiguity by clarifying that only UPP
ERCASE usage of the key words have the defined special meanings.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="8174"/>
<seriesInfo name="DOI" value="10.17487/RFC8174"/>
</reference>
<reference anchor="RFC8259">
<front>
<title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
<author fullname="T. Bray" initials="T." role="editor" surname="Bray"/>
<date month="December" year="2017"/>
<abstract>
<t>JavaScript Object Notation (JSON) is a lightweight, text-based, languag
e-independent data interchange format. It was derived from the ECMAScript Progra
mming Language Standard. JSON defines a small set of formatting rules for the po
rtable representation of structured data.</t>
<t>This document removes inconsistencies with other specifications of JSON
, repairs specification errors, and offers experience-based interoperability gui
dance.</t>
</abstract>
</front>
<seriesInfo name="STD" value="90"/>
<seriesInfo name="RFC" value="8259"/>
<seriesInfo name="DOI" value="10.17487/RFC8259"/>
</reference>
<reference anchor="RFC8705">
<front>
<title>OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Acce
ss Tokens</title>
<author fullname="B. Campbell" initials="B." surname="Campbell"/>
<author fullname="J. Bradley" initials="J." surname="Bradley"/>
<author fullname="N. Sakimura" initials="N." surname="Sakimura"/>
<author fullname="T. Lodderstedt" initials="T." surname="Lodderstedt"/>
<date month="February" year="2020"/>
<abstract>
<t>This document describes OAuth client authentication and certificate-bou
nd access and refresh tokens using mutual Transport Layer Security (TLS) authent
ication with X.509 certificates. OAuth clients are provided a mechanism for auth
entication to the authorization server using mutual TLS, based on either self-si
gned certificates or public key infrastructure (PKI). OAuth authorization server
s are provided a mechanism for binding access tokens to a client's mutual-TLS ce
rtificate, and OAuth protected resources are provided a method for ensuring that
such an access token presented to it was issued to the client presenting the to
ken.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="8705"/>
<seriesInfo name="DOI" value="10.17487/RFC8705"/>
</reference>
<reference anchor="HTTP">
<front>
<title>HTTP Semantics</title>
<author fullname="R. Fielding" initials="R." role="editor" surname="Fielding
"/>
<author fullname="M. Nottingham" initials="M." role="editor" surname="Nottin
gham"/>
<author fullname="J. Reschke" initials="J." role="editor" surname="Reschke"/
>
<date month="June" year="2022"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is a stateless application-level
protocol for distributed, collaborative, hypertext information systems. This do
cument describes the overall architecture of HTTP, establishes common terminolog
y, and defines aspects of the protocol that are shared by all versions. In this
definition are core protocol elements, extensibility mechanisms, and the "http"
and "https" Uniform Resource Identifier (URI) schemes.</t>
<t>This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 723
3, 7235, 7538, 7615, 7694, and portions of 7230.</t>
</abstract>
</front>
<seriesInfo name="STD" value="97"/>
<seriesInfo name="RFC" value="9110"/>
<seriesInfo name="DOI" value="10.17487/RFC9110"/>
</reference>
<reference anchor="RFC9111">
<front>
<title>HTTP Caching</title>
<author fullname="R. Fielding" initials="R." role="editor" surname="Fielding
"/>
<author fullname="M. Nottingham" initials="M." role="editor" surname="Nottin
gham"/>
<author fullname="J. Reschke" initials="J." role="editor" surname="Reschke"/
>
<date month="June" year="2022"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is a stateless application-level
protocol for distributed, collaborative, hypertext information systems. This do
cument defines HTTP caches and the associated header fields that control cache b
ehavior or indicate cacheable response messages.</t>
<t>This document obsoletes RFC 7234.</t>
</abstract>
</front>
<seriesInfo name="STD" value="98"/>
<seriesInfo name="RFC" value="9111"/>
<seriesInfo name="DOI" value="10.17487/RFC9111"/>
</reference>
<reference anchor="RFC9421">
<front>
<title>HTTP Message Signatures</title>
<author fullname="A. Backman" initials="A." role="editor" surname="Backman"/
>
<author fullname="J. Richer" initials="J." role="editor" surname="Richer"/>
<author fullname="M. Sporny" initials="M." surname="Sporny"/>
<date month="February" year="2024"/>
<abstract>
<t>This document describes a mechanism for creating, encoding, and verifyi
ng digital signatures or message authentication codes over components of an HTTP
message. This mechanism supports use cases where the full HTTP message may not
be known to the signer and where the message may be transformed (e.g., by interm
ediaries) before reaching the verifier. This document also describes a means for
requesting that a signature be applied to a subsequent HTTP message in an ongoi
ng HTTP exchange.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="9421"/>
<seriesInfo name="DOI" value="10.17487/RFC9421"/>
</reference>
<reference anchor="RFC9530">
<front>
<title>Digest Fields</title>
<author fullname="R. Polli" initials="R." surname="Polli"/>
<author fullname="L. Pardue" initials="L." surname="Pardue"/>
<date month="February" year="2024"/>
<abstract>
<t>This document defines HTTP fields that support integrity digests. The C
ontent-Digest field can be used for the integrity of HTTP message content. The R
epr-Digest field can be used for the integrity of HTTP representations. Want-Con
tent-Digest and Want-Repr-Digest can be used to indicate a sender's interest and
preferences for receiving the respective Integrity fields.</t>
<t>This document obsoletes RFC 3230 and the Digest and Want-Digest HTTP fi
elds.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="9530"/>
<seriesInfo name="DOI" value="10.17487/RFC9530"/>
</reference>
<reference anchor="RFC9493">
<front>
<title>Subject Identifiers for Security Event Tokens</title>
<author fullname="A. Backman" initials="A." role="editor" surname="Backman"/
>
<author fullname="M. Scurtescu" initials="M." surname="Scurtescu"/>
<author fullname="P. Jain" initials="P." surname="Jain"/>
<date month="December" year="2023"/>
<abstract>
<t>Security events communicated within Security Event Tokens may support a
variety of identifiers to identify subjects related to the event. This specific
ation formalizes the notion of Subject Identifiers as structured information tha
t describes a subject and named formats that define the syntax and semantics for
encoding Subject Identifiers as JSON objects. It also establishes a registry fo
r defining and allocating names for such formats as well as the JSON Web Token (
JWT) "sub_id" Claim.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="9493"/>
<seriesInfo name="DOI" value="10.17487/RFC9493"/>
</reference>
<reference anchor="HASH-ALG" target="https://www.iana.org/assignments/named-info
rmation/named-information.xhtml#hash-alg">
<front>
<title>Named Information Hash Algorithm Registry</title>
<author >
<organization>IANA</organization>
</author>
<date year="n.d."/>
</front>
</reference>
<reference anchor="OIDC" target="https://openid.net/specs/openid-connect-core-1_
0.html">
<front>
<title>OpenID Connect Core 1.0 incorporating errata set 1</title>
<author initials="N." surname="Sakimura">
<organization></organization>
</author>
<author initials="J." surname="Bradley">
<organization></organization>
</author>
<author initials="M." surname="Jones">
<organization></organization>
</author>
<author initials="B." surname="de Medeiros">
<organization></organization>
</author>
<author initials="C." surname="Mortimore">
<organization></organization>
</author>
<date year="2014" month="November"/>
</front>
</reference>
<reference anchor="SAML2" target="https://docs.oasis-open.org/security/saml/v2.0
/saml-core-2.0-os.pdf">
<front>
<title>Assertions and Protocol for the OASIS Security Assertion Markup Langu
age (SAML) V2.0</title>
<author initials="S." surname="Cantor">
<organization></organization>
</author>
<author initials="J." surname="Kemp">
<organization></organization>
</author>
<author initials="R." surname="Philpott">
<organization></organization>
</author>
<author initials="E." surname="Maler">
<organization></organization>
</author>
<date year="2005" month="March"/>
</front>
</reference>
<reference anchor="RFC2119">
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author fullname="S. Bradner" initials="S." surname="Bradner"/>
<date month="March" year="1997"/>
<abstract>
<t>In many standards track documents several words are used to signify the
requirements in the specification. These words are often capitalized. This docu
ment defines these words as they should be interpreted in IETF documents. This d
ocument specifies an Internet Best Current Practices for the Internet Community,
and requests discussion and suggestions for improvements.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="2119"/>
<seriesInfo name="DOI" value="10.17487/RFC2119"/>
</reference>
</references>
<references title='Informative References' anchor="sec-informative-reference
s">
<reference anchor="RFC2046">
<front>
<title>Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types</t
itle>
<author fullname="N. Freed" initials="N." surname="Freed"/>
<author fullname="N. Borenstein" initials="N." surname="Borenstein"/>
<date month="November" year="1996"/>
<abstract>
<t>This second document defines the general structure of the MIME media ty
ping system and defines an initial set of media types. [STANDARDS-TRACK]</t>
</abstract>
</front>
<seriesInfo name="RFC" value="2046"/>
<seriesInfo name="DOI" value="10.17487/RFC2046"/>
</reference>
<reference anchor="RFC4107">
<front>
<title>Guidelines for Cryptographic Key Management</title>
<author fullname="S. Bellovin" initials="S." surname="Bellovin"/>
<author fullname="R. Housley" initials="R." surname="Housley"/>
<date month="June" year="2005"/>
<abstract>
<t>The question often arises of whether a given security system requires s
ome form of automated key management, or whether manual keying is sufficient. Th
is memo provides guidelines for making such decisions. When symmetric cryptograp
hic mechanisms are used in a protocol, the presumption is that automated key man
agement is generally but not always needed. If manual keying is proposed, the bu
rden of proving that automated key management is not required falls to the propo
ser. This document specifies an Internet Best Current Practices for the Internet
Community, and requests discussion and suggestions for improvements.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="107"/>
<seriesInfo name="RFC" value="4107"/>
<seriesInfo name="DOI" value="10.17487/RFC4107"/>
</reference>
<reference anchor="RFC6202">
<front>
<title>Known Issues and Best Practices for the Use of Long Polling and Strea
ming in Bidirectional HTTP</title>
<author fullname="S. Loreto" initials="S." surname="Loreto"/>
<author fullname="P. Saint-Andre" initials="P." surname="Saint-Andre"/>
<author fullname="S. Salsano" initials="S." surname="Salsano"/>
<author fullname="G. Wilkins" initials="G." surname="Wilkins"/>
<date month="April" year="2011"/>
<abstract>
<t>On today's Internet, the Hypertext Transfer Protocol (HTTP) is often us
ed (some would say abused) to enable asynchronous, "server- initiated" communica
tion from a server to a client as well as communication from a client to a serve
r. This document describes known issues and best practices related to such "bidi
rectional HTTP" applications, focusing on the two most common mechanisms: HTTP l
ong polling and HTTP streaming. This document is not an Internet Standards Track
specification; it is published for informational purposes.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="6202"/>
<seriesInfo name="DOI" value="10.17487/RFC6202"/>
</reference>
<reference anchor="RFC6838">
<front>
<title>Media Type Specifications and Registration Procedures</title>
<author fullname="N. Freed" initials="N." surname="Freed"/>
<author fullname="J. Klensin" initials="J." surname="Klensin"/>
<author fullname="T. Hansen" initials="T." surname="Hansen"/>
<date month="January" year="2013"/>
<abstract>
<t>This document defines procedures for the specification and registration
of media types for use in HTTP, MIME, and other Internet protocols. This memo d
ocuments an Internet Best Current Practice.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="13"/>
<seriesInfo name="RFC" value="6838"/>
<seriesInfo name="DOI" value="10.17487/RFC6838"/>
</reference>
<reference anchor="RFC6973">
<front>
<title>Privacy Considerations for Internet Protocols</title>
<author fullname="A. Cooper" initials="A." surname="Cooper"/>
<author fullname="H. Tschofenig" initials="H." surname="Tschofenig"/>
<author fullname="B. Aboba" initials="B." surname="Aboba"/>
<author fullname="J. Peterson" initials="J." surname="Peterson"/>
<author fullname="J. Morris" initials="J." surname="Morris"/>
<author fullname="M. Hansen" initials="M." surname="Hansen"/>
<author fullname="R. Smith" initials="R." surname="Smith"/>
<date month="July" year="2013"/>
<abstract>
<t>This document offers guidance for developing privacy considerations for
inclusion in protocol specifications. It aims to make designers, implementers,
and users of Internet protocols aware of privacy-related design choices. It sugg
ests that whether any individual RFC warrants a specific privacy considerations
section will depend on the document's content.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="6973"/>
<seriesInfo name="DOI" value="10.17487/RFC6973"/>
</reference>
<reference anchor="RFC7518">
<front>
<title>JSON Web Algorithms (JWA)</title>
<author fullname="M. Jones" initials="M." surname="Jones"/>
<date month="May" year="2015"/>
<abstract>
<t>This specification registers cryptographic algorithms and identifiers t
o be used with the JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON
Web Key (JWK) specifications. It defines several IANA registries for these iden
tifiers.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="7518"/>
<seriesInfo name="DOI" value="10.17487/RFC7518"/>
</reference>
<reference anchor="RFC8264">
<front>
<title>PRECIS Framework: Preparation, Enforcement, and Comparison of Interna
tionalized Strings in Application Protocols</title>
<author fullname="P. Saint-Andre" initials="P." surname="Saint-Andre"/>
<author fullname="M. Blanchet" initials="M." surname="Blanchet"/>
<date month="October" year="2017"/>
<abstract>
<t>Application protocols using Unicode code points in protocol strings nee
d to properly handle such strings in order to enforce internationalization rules
for strings placed in various protocol slots (such as addresses and identifiers
) and to perform valid comparison operations (e.g., for purposes of authenticati
on or authorization). This document defines a framework enabling application pro
tocols to perform the preparation, enforcement, and comparison of internationali
zed strings ("PRECIS") in a way that depends on the properties of Unicode code p
oints and thus is more agile with respect to versions of Unicode. As a result, t
his framework provides a more sustainable approach to the handling of internatio
nalized strings than the previous framework, known as Stringprep (RFC 3454). Thi
s document obsoletes RFC 7564.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="8264"/>
<seriesInfo name="DOI" value="10.17487/RFC8264"/>
</reference>
<reference anchor="RFC8707">
<front>
<title>Resource Indicators for OAuth 2.0</title>
<author fullname="B. Campbell" initials="B." surname="Campbell"/>
<author fullname="J. Bradley" initials="J." surname="Bradley"/>
<author fullname="H. Tschofenig" initials="H." surname="Tschofenig"/>
<date month="February" year="2020"/>
<abstract>
<t>This document specifies an extension to the OAuth 2.0 Authorization Fra
mework defining request parameters that enable a client to explicitly signal to
an authorization server about the identity of the protected resource(s) to which
it is requesting access.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="8707"/>
<seriesInfo name="DOI" value="10.17487/RFC8707"/>
</reference>
<reference anchor="RFC8792">
<front>
<title>Handling Long Lines in Content of Internet-Drafts and RFCs</title>
<author fullname="K. Watsen" initials="K." surname="Watsen"/>
<author fullname="E. Auerswald" initials="E." surname="Auerswald"/>
<author fullname="A. Farrel" initials="A." surname="Farrel"/>
<author fullname="Q. Wu" initials="Q." surname="Wu"/>
<date month="June" year="2020"/>
<abstract>
<t>This document defines two strategies for handling long lines in width-b
ounded text content. One strategy, called the "single backslash" strategy, is ba
sed on the historical use of a single backslash ('\') character to indicate wher
e line-folding has occurred, with the continuation occurring with the first char
acter that is not a space character (' ') on the next line. The second strategy,
called the "double backslash" strategy, extends the first strategy by adding a
second backslash character to identify where the continuation begins and is ther
eby able to handle cases not supported by the first strategy. Both strategies us
e a self-describing header enabling automated reconstitution of the original con
tent.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="8792"/>
<seriesInfo name="DOI" value="10.17487/RFC8792"/>
</reference>
<reference anchor="RFC9396">
<front>
<title>OAuth 2.0 Rich Authorization Requests</title>
<author fullname="T. Lodderstedt" initials="T." surname="Lodderstedt"/>
<author fullname="J. Richer" initials="J." surname="Richer"/>
<author fullname="B. Campbell" initials="B." surname="Campbell"/>
<date month="May" year="2023"/>
<abstract>
<t>This document specifies a new parameter that is used to carry fine-grai
ned authorization data in OAuth messages.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="9396"/>
<seriesInfo name="DOI" value="10.17487/RFC9396"/>
</reference>
<reference anchor="RFC9440">
<front>
<title>Client-Cert HTTP Header Field</title>
<author fullname="B. Campbell" initials="B." surname="Campbell"/>
<author fullname="M. Bishop" initials="M." surname="Bishop"/>
<date month="July" year="2023"/>
<abstract>
<t>This document describes HTTP extension header fields that allow a TLS t
erminating reverse proxy (TTRP) to convey the client certificate information of
a mutually authenticated TLS connection to the origin server in a common and pre
dictable manner.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="9440"/>
<seriesInfo name="DOI" value="10.17487/RFC9440"/>
</reference>
<reference anchor="I-D.ietf-gnap-resource-servers">
<front>
<title>Grant Negotiation and Authorization Protocol Resource Server Connec
tions</title>
<author fullname="Justin Richer" initials="J." surname="Richer">
<organization>Bespoke Engineering</organization>
</author>
<author fullname="Fabien Imbault" initials="F." surname="Imbault">
<organization>acert.io</organization>
</author>
<date day="19" month="February" year="2024"/>
<abstract>
<t> GNAP defines a mechanism for delegating authorization to a piece o
f
software, and conveying that delegation to the software. This
extension defines methods for resource servers (RS) to connect with
authorization servers (AS) in an interoperable fashion.
</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-gnap-resource-servers-05"
/>
</reference>
<reference anchor="I-D.ietf-oauth-security-topics">
<front>
<title>OAuth 2.0 Security Best Current Practice</title>
<author fullname="Torsten Lodderstedt" initials="T." surname="Lodderstedt"
>
<organization>SPRIND</organization>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization>Yubico</organization>
</author>
<author fullname="Andrey Labunets" initials="A." surname="Labunets">
<organization>Independent Researcher</organization>
</author>
<author fullname="Daniel Fett" initials="D." surname="Fett">
<organization>Authlete</organization>
</author> </author>
<date day="8" month="February" year="2024"/> </front>
<abstract> </reference>
<t> This document describes best current security practice for OAuth 2
.0.
It updates and extends the threat model and security advice given in
[RFC6749], [RFC6750], and [RFC6819] to incorporate practical
experiences gathered since OAuth 2.0 was published and covers new
threats relevant due to the broader application of OAuth 2.0. It
further deprecates some modes of operation that are deemed less
secure or even insecure.
</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-oauth-security-topics-25"
/>
</reference> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2
046.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4
107.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
202.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
838.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
973.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7
518.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
264.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
707.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
792.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9
396.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9
440.xml"/>
<reference anchor="RFC9525"> <reference anchor="I-D.ietf-gnap-resource-servers" target="https://datatracker.i
<front> etf.org/doc/html/draft-ietf-gnap-resource-servers-09">
<title>Service Identity in TLS</title> <front>
<author fullname="P. Saint-Andre" initials="P." surname="Saint-Andre"/> <title>
<author fullname="R. Salz" initials="R." surname="Salz"/> Grant Negotiation and Authorization Protocol Resource Server Connections
<date month="November" year="2023"/> </title>
<abstract> <author initials="J." surname="Richer" fullname="Justin Richer" role="editor">
<t>Many application technologies enable secure communication between two e <organization>Bespoke Engineering</organization>
ntities by means of Transport Layer Security (TLS) with Internet Public Key Infr </author>
astructure using X.509 (PKIX) certificates. This document specifies procedures f <author initials="F." surname="Imbault" fullname="Fabien Imbault">
or representing and verifying the identity of application services in such inter <organization>acert.io</organization>
actions.</t> </author>
<t>This document obsoletes RFC 6125.</t> <date month="September" day="23" year="2024"/>
</abstract> </front>
</front> <seriesInfo name="Internet-Draft" value="draft-ietf-gnap-resource-servers-09"/>
<seriesInfo name="RFC" value="9525"/>
<seriesInfo name="DOI" value="10.17487/RFC9525"/>
</reference> </reference>
<reference anchor="promise-theory" target="http://markburgess.org/promises.html" <xi:include href="https://datatracker.ietf.org/doc/bibxml3/draft-ietf-oa
> uth-security-topics.xml"/>
<front>
<title>Promise theory</title>
<author initials="M." surname="Burgess">
<organization></organization>
</author>
<author initials="J." surname="Bergstra">
<organization></organization>
</author>
<date year="2014" month="January"/>
</front>
</reference>
<reference anchor="AXELAND2021" target="https://odr.chalmers.se/handle/20.500.12
380/304105">
<front>
<title>Security Analysis of Attack Surfaces on the Grant Negotiation and Aut
horization Protocol</title>
<author initials="Å." surname="Axeland">
<organization></organization>
</author>
<author initials="O." surname="Oueidat">
<organization></organization>
</author>
<date year="2021"/>
</front>
</reference>
<reference anchor="HELMSCHMIDT2022" target="http://dx.doi.org/10.18419/opus-1220
3">
<front>
<title>Security Analysis of the Grant Negotiation and Authorization Protocol
</title>
<author initials="F." surname="Helmschmidt">
<organization></organization>
</author>
<date year="2022"/>
</front>
</reference>
<reference anchor="SP80063C" target="https://doi.org/10.6028/NIST.SP.800-63c">
<front>
<title>Digital Identity Guidelines: Federation and Assertions</title>
<author initials="P." surname="Grassi">
<organization></organization>
</author>
<author initials="E." surname="Nadeau">
<organization></organization>
</author>
<author initials="J." surname="Richer">
<organization></organization>
</author>
<author initials="S." surname="Squire">
<organization></organization>
</author>
<author initials="J." surname="Fenton">
<organization></organization>
</author>
<author initials="N." surname="Lefkovitz">
<organization></organization>
</author>
<author initials="J." surname="Danker">
<organization></organization>
</author>
<author initials="Y." surname="Choong">
<organization></organization>
</author>
<author initials="K." surname="Greene">
<organization></organization>
</author>
<author initials="M." surname="Theofanos">
<organization></organization>
</author>
<date year="2017" month="June"/>
</front>
</reference>
<reference anchor="IANA.MediaTypes" target="https://www.iana.org/assignments/med
ia-types/media-types.xhtml">
<front>
<title>Media Types</title>
<author fullname="IANA">
<organization></organization>
</author>
<date year="n.d."/>
</front>
</reference>
<reference anchor="RFC8126"> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9
<front> 525.xml"/>
<title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
<author fullname="M. Cotton" initials="M." surname="Cotton"/>
<author fullname="B. Leiba" initials="B." surname="Leiba"/>
<author fullname="T. Narten" initials="T." surname="Narten"/>
<date month="June" year="2017"/>
<abstract>
<t>Many protocols make use of points of extensibility that use constants t
o identify various protocol parameters. To ensure that the values in these field
s do not have conflicting uses and to promote interoperability, their allocation
s are often coordinated by a central record keeper. For IETF protocols, that rol
e is filled by the Internet Assigned Numbers Authority (IANA).</t>
<t>To make assignments in a given registry prudently, guidance describing
the conditions under which new values should be assigned, as well as when and ho
w modifications to existing values can be made, is needed. This document defines
a framework for the documentation of these guidelines by specification authors,
in order to assure that the provided guidance for the IANA Considerations is cl
ear and addresses the various issues that are likely in the operation of a regis
try.</t>
<t>This is the third edition of this document; it obsoletes RFC 5226.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="26"/>
<seriesInfo name="RFC" value="8126"/>
<seriesInfo name="DOI" value="10.17487/RFC8126"/>
</reference>
</references> <reference anchor="promise-theory" target="http://markburgess.org/promis
es.html">
<front>
<title>Promise Theory: Principles and Applications</title>
<author initials="J." surname="Bergstra">
<organization/>
</author>
<author initials="M." surname="Burgess">
<organization/>
</author>
<date year="2019"/>
</front>
<refcontent>Second Edition, XtAxis Press</refcontent>
</reference>
<?line 7538?> <reference anchor="AXELAND2021" target="https://hdl.handle.net/20.500.12
380/304105">
<front>
<title>Security Analysis of Attack Surfaces on the Grant Negotiation
and Authorization Protocol</title>
<author initials="Å." surname="Axeland">
<organization/>
</author>
<author initials="O." surname="Oueidat">
<organization/>
</author>
<date year="2021"/>
</front>
<refcontent>Master's thesis, Department of Computer Science and Engine
ering, Chalmers University of Technology and University of Gothenburg</refconten
t>
</reference>
<section anchor="history"><name>Document History</name> <reference anchor="HELMSCHMIDT2022" target="http://dx.doi.org/10.18419/o
pus-12203">
<front>
<title>Security Analysis of the Grant Negotiation and Authorization
Protocol</title>
<author initials="F." surname="Helmschmidt">
<organization/>
</author>
<date year="2022"/>
</front>
<seriesInfo name="DOI" value="10.18419/opus-12203"/>
<refcontent>Master's thesis, Institute of Information Security, Univer
sity of Stuggart</refcontent>
</reference>
<ul empty="true"><li> <reference anchor="SP80063C" target="https://nvlpubs.nist.gov/nistpubs/S
<t>Note: To be removed by RFC editor before publication.</t> pecialPublications/NIST.SP.800-63c.pdf">
</li></ul> <front>
<title>Digital Identity Guidelines: Federation and Assertions</title
>
<author initials="P." surname="Grassi">
<organization/>
</author>
<author initials="J." surname="Richer">
<organization/>
</author>
<author initials="S." surname="Squire">
<organization/>
</author>
<author initials="J." surname="Fenton">
<organization/>
</author>
<author initials="E." surname="Nadeau">
<organization/>
</author>
<author initials="N." surname="Lefkovitz">
<organization/>
</author>
<author initials="J." surname="Danker">
<organization/>
</author>
<author initials="Y." surname="Choong">
<organization/>
</author>
<author initials="K." surname="Greene">
<organization/>
</author>
<author initials="M." surname="Theofanos">
<organization/>
</author>
<date year="2017" month="June"/>
</front>
<seriesInfo name="NIST SP" value="800-63C"/>
<seriesInfo name="DOI" value="10.6028/NIST.SP.800-63c"/>
</reference>
<t><list style="symbols"> <reference anchor="MediaTypes" target="https://www.iana.org/assignments/
<t>19 media-types">
<list style="symbols"> <front>
<t>Updates from IESG reviews.</t> <title>Media Types</title>
<t>Updated JOSE types to no longer use subtypes.</t> <author fullname="IANA">
<t>Added media type registrations.</t> <organization/>
</list></t> </author>
<t>18 </front>
<list style="symbols"> </reference>
<t>Updates from IESG reviews.</t>
</list></t>
<t>17
<list style="symbols">
<t>Updates from IESG reviews.</t>
</list></t>
<t>16
<list style="symbols">
<t>Updates from AD review.</t>
<t>Added security considerations on token substitution attack.</t>
</list></t>
<t>15
<list style="symbols">
<t>Editorial updates from shepherd review.</t>
<t>Clarify character set constraints of user codes.</t>
</list></t>
<t>14
<list style="symbols">
<t>Update token rotation to use URI + management token.</t>
<t>Fix key rotation with HTTP Signatures based on security analysis.</t>
</list></t>
<t>-13
<list style="symbols">
<t>Editoral changes from chair review.</t>
<t>Clarify that user codes are ungessable.</t>
<t>Fix user code examples.</t>
<t>Clarify expectations for extensions to interaction start and finish met
hods.</t>
<t>Fix references.</t>
<t>Add IANA designated expert instructions.</t>
<t>Clarify new vs. updated access tokens, and call out no need for refresh
tokens in OAuth 2 comparison section.</t>
<t>Add instructions on assertion processing.</t>
<t>Explicitly list user reference lifetime management.</t>
</list></t>
<t>-12
<list style="symbols">
<t>Make default hash algorithm SHA256 instead of SHA3-512.</t>
<t>Remove <spanx style="verb">previous_key</spanx> from key rotation.</t>
<t>Defined requirements for key rotation methods.</t>
<t>Add specificity to context of subject identifier being the AS.</t>
<t>Editorial updates and protocol clarification.</t>
</list></t>
<t>-11
<list style="symbols">
<t>Error as object or string, more complete set of error codes</t>
<t>Added key rotation in token management.</t>
<t>Restrict keys to a single format per message.</t>
<t>Discussed security issues of multiple key formats.</t>
<t>Make token character set more strict.</t>
<t>Add note on long-polling in continuation requests.</t>
<t>Removed "Models" section.</t>
<t>Rewrote guidance and requirements for extensions.</t>
<t>Require all URIs to be absolute throughout protocol.</t>
<t>Make response from RS a "<bcp14>SHOULD</bcp14>" instead of a "<bcp14>MA
Y</bcp14>".</t>
<t>Added a way for the client instance to ask for a specific user's inform
ation, separate from the end-user.</t>
<t>Added security considerations for asynchronous authorization.</t>
<t>Added security considerations for compromised RS.</t>
<t>Added interoperability profiles.</t>
<t>Added implementation status section.</t>
</list></t>
<t>-10
<list style="symbols">
<t>Added note on relating access rights sent as strings to rights sent as
objects.</t>
<t>Expand proofing methods to allow definition by object, with single stri
ng as optimization for common cases.</t>
<t>Removed "split_token" functionality.</t>
<t>Collapse "user_code" into a string instead of an object.</t>
<t>References hash algorithm identifiers from the existing IANA registry</
t>
<t>Allow interaction responses to time out.</t>
<t>Added explicit protocol state discussion.</t>
<t>Added RO policy use case.</t>
</list></t>
<t>-09
<list style="symbols">
<t>Added security considerations on redirection status codes.</t>
<t>Added security considerations on cuckoo token attack.</t>
<t>Made token management URL required on token rotation.</t>
<t>Added considerations on token rotation and self-contained tokens.</t>
<t>Added security considerations for SSRF.</t>
<t>Moved normative requirements about end user presence to security consid
erations.</t>
<t>Clarified default wait times for continuation requests (including polli
ng).</t>
<t>Clarified URI vs. URL.</t>
<t>Added "user_code_uri" mode, removed "uri" from "user_code" mode.</t>
<t>Consistently formatted all parameter lists.</t>
<t>Updated examples for HTTP Signatures.</t>
</list></t>
<t>-08
<list style="symbols">
<t>Update definition for "Client" to account for the case of no end user.<
/t>
<t>Change definition for "Subject".</t>
<t>Expanded security and privacy considerations for more situations.</t>
<t>Added cross-links from security and privacy considerations.</t>
<t>Editorial updates.</t>
</list></t>
<t>-07
<list style="symbols">
<t>Replace user handle by opaque identifier</t>
<t>Added trust relationships</t>
<t>Added privacy considerations section</t>
<t>Added security considerations.</t>
</list></t>
<t>-06
<list style="symbols">
<t>Removed "capabilities" and "existing_grant" protocol fields.</t>
<t>Removed separate "instance_id" field.</t>
<t>Split "interaction_methods_supported" into "interaction_start_modes_sup
ported" and "interaction_finish_methods_supported".</t>
<t>Added AS endpoint to hash calculation to fix mix-up attack.</t>
<t>Added "privileges" field to resource access request object.</t>
<t>Moved client-facing RS response back from GNAP-RS document.</t>
<t>Removed oauthpop key binding.</t>
<t>Removed dpop key binding.</t>
<t>Added example DID identifier.</t>
<t>Changed token response booleans to flag structure to match request.</t>
<t>Updated signature examples to use HTTP Message Signatures.</t>
</list></t>
<t>-05
<list style="symbols">
<t>Changed "interaction_methods" to "interaction_methods_supported".</t>
<t>Changed "key_proofs" to "key_proofs_supported".</t>
<t>Changed "assertions" to "assertions_supported".</t>
<t>Updated discovery and field names for subject formats.</t>
<t>Add an appendix to provide protocol rationale, compared to OAuth2.</t>
<t>Updated subject information definition.</t>
<t>Refactored the RS-centric components into a new document.</t>
<t>Updated cryptographic proof of possession methods to match current refe
rence syntax.</t>
<t>Updated proofing language to use "signer" and "verifier" generically.</
t>
<t>Updated cryptographic proof of possession examples.</t>
<t>Editorial cleanup and fixes.</t>
<t>Diagram cleanup and fixes.</t>
</list></t>
<t>-04
<list style="symbols">
<t>Updated terminology.</t>
<t>Refactored key presentation and binding.</t>
<t>Refactored "interact" request to group start and end modes.</t>
<t>Changed access token request and response syntax.</t>
<t>Changed DPoP digest field to 'htd' to match proposed FAPI profile.</t>
<t>Include the access token hash in the DPoP message.</t>
<t>Removed closed issue links.</t>
<t>Removed function to read state of grant request by client.</t>
<t>Closed issues related to reading and updating access tokens.</t>
</list></t>
<t>-03
<list style="symbols">
<t>Changed "resource client" terminology to separate "client instance" and
"client software".</t>
<t>Removed OpenID Connect "claims" parameter.</t>
<t>Dropped "short URI" redirect.</t>
<t>Access token is mandatory for continuation.</t>
<t>Removed closed issue links.</t>
<t>Editorial fixes.</t>
</list></t>
<t>-02
<list style="symbols">
<t>Moved all "editor's note" items to GitHub Issues.</t>
<t>Added JSON types to fields.</t>
<t>Changed "GNAP Protocol" to "GNAP".</t>
<t>Editorial fixes.</t>
</list></t>
<t>-01
<list style="symbols">
<t>"updated_at" subject info timestamp now in ISO 8601 string format.</t>
<t>Editorial fixes.</t>
<t>Added Aaron and Fabien as document authors.</t>
</list></t>
<t>-00
<list style="symbols">
<t>Initial working group draft.</t>
</list></t>
</list></t>
</section> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
<section anchor="vs-oauth2"><name>Compared to OAuth 2.0</name> 126.xml"/>
<t>GNAP's protocol design differs from OAuth 2.0's in several fundamental ways:< </references>
/t> </references>
<t><list style="numbers"> <section anchor="vs-oauth2">
<t><strong>Consent and authorization flexibility:</strong> <vspace blankLines <name>Comparison with OAuth 2.0</name>
='1'/> <t>GNAP's protocol design differs from OAuth 2.0's in several fundamental
OAuth 2.0 generally assumes the user has access to a web browser. The type of in ways:</t>
teraction available is fixed by the grant type, and the most common interactive <ol spacing="normal" type="1"><li>
grant types start in the browser. OAuth 2.0 assumes that the user using the clie <t><strong>Consent and authorization flexibility:</strong> </t>
nt software is the same user that will interact with the AS to approve access. <t>
<vspace blankLines='1'/> OAuth 2.0 generally assumes the user has access to a web browser. The type of in
GNAP allows various patterns to manage authorizations and consents required to f teraction available is fixed by the grant type, and the most common interactive
ulfill this requested delegation, including information sent by the client insta grant types start in the browser. OAuth 2.0 assumes that the user using the clie
nce, information supplied by external parties, and information gathered through nt software is the same user that will interact with the AS to approve access.
the interaction process. GNAP allows a client instance to list different ways th </t>
at it can start and finish an interaction, and these can be mixed together as ne <t>
eded for different use cases. GNAP interactions can use a browser, but don't hav GNAP allows various patterns to manage authorizations and consents required to f
e to. Methods can use inter-application messaging protocols, out-of-band data tr ulfill this requested delegation, including information sent by the client insta
ansfer, or anything else. GNAP allows extensions to define new ways to start and nce, information supplied by external parties, and information gathered through
finish an interaction, as new methods and platforms are expected to become avai the interaction process. GNAP allows a client instance to list different ways th
lable over time. GNAP is designed to allow the end user and the resource owner t at it can start and finish an interaction, and these can be mixed together as ne
o be two different people, but still works in the optimized case of them being t eded for different use cases. GNAP interactions can use a browser, but they don'
he same party.</t> t have to. Methods can use inter-application messaging protocols, out-of-band da
<t><strong>Intent registration and inline negotiation:</strong> <vspace blank ta transfer, or anything else. GNAP allows extensions to define new ways to star
Lines='1'/> t and finish an interaction, as new methods and platforms are expected to become
OAuth 2.0 uses different "grant types" that start at different endpoints for dif available over time. GNAP is designed to allow the end user and the RO to be tw
ferent purposes. Many of these require discovery of several interrelated paramet o different people, but it still works in the optimized case of them being the s
ers. <vspace blankLines='1'/> ame party.</t>
GNAP requests all start with the same type of request to the same endpoint at th </li>
e AS. Next steps are negotiated between the client instance and AS based on soft <li>
ware capabilities, policies surrounding requested access, and the overall contex <t><strong>Intent registration and inline negotiation:</strong> </t>
t of the ongoing request. GNAP defines a continuation API that allows the client <t>
instance and AS to request and send additional information from each other over OAuth 2.0 uses different "grant types" that start at different endpoints for dif
multiple steps. This continuation API uses the same access token protection tha ferent purposes. Many of these require discovery of several interrelated paramet
t other GNAP-protected APIs use. GNAP allows discovery to optimize the requests ers. </t>
but it isn't required thanks to the negotiation capabilities. <vspace blankLine <t>
s='1'/> GNAP requests all start with the same type of request to the same endpoint at th
GNAP is able to handle the life-cycle of an authorization request, and therefore e AS. Next steps are negotiated between the client instance and AS based on soft
simplifies the mental model surrounding OAuth2. For instance, there's no need f ware capabilities, policies surrounding requested access, and the overall contex
or refresh tokens when the API enables proper rotation of access tokens.</t> t of the ongoing request. GNAP defines a continuation API that allows the client
<t><strong>Client instances:</strong> <vspace blankLines='1'/> instance and AS to request and send additional information from each other over
OAuth 2.0 requires all clients to be registered at the AS and to use a client_id multiple steps. This continuation API uses the same access token protection tha
known to the AS as part of the protocol. This client_id is generally assumed to t other GNAP-protected APIs use. GNAP allows discovery to optimize the requests,
be assigned by a trusted authority during a registration process, and OAuth pla but it isn't required thanks to the negotiation capabilities. </t>
ces a lot of trust on the client_id as a result. Dynamic registration allows dif <t>
ferent classes of clients to get a client_id at runtime, even if they only ever GNAP is able to handle the life cycle of an authorization request and therefore
use it for one request. <vspace blankLines='1'/> simplifies the mental model surrounding OAuth2. For instance, there's no need fo
r refresh tokens when the API enables proper rotation of access tokens.</t>
</li>
<li>
<t><strong>Client instances:</strong> </t>
<t>
OAuth 2.0 requires all clients to be registered at the AS and to use a client_id
known to the AS as part of the protocol. This client_id is generally assumed to
be assigned by a trusted authority during a registration process, and OAuth pla
ces a lot of trust on the client_id as a result. Dynamic registration allows dif
ferent classes of clients to get a client_id at runtime, even if they only ever
use it for one request. </t>
<t>
GNAP allows the client instance to present an unknown key to the AS and use that key to protect the ongoing request. GNAP's client instance identifier mechanism allows for pre-registered clients and dynamically registered clients to exist a s an optimized case without requiring the identifier as part of the protocol at all times.</t> GNAP allows the client instance to present an unknown key to the AS and use that key to protect the ongoing request. GNAP's client instance identifier mechanism allows for pre-registered clients and dynamically registered clients to exist a s an optimized case without requiring the identifier as part of the protocol at all times.</t>
<t><strong>Expanded delegation:</strong> <vspace blankLines='1'/> </li>
OAuth 2.0 defines the "scope" parameter for controlling access to APIs. This par <li>
ameter has been coopted to mean a number of different things in different protoc <t><strong>Expanded delegation:</strong> </t>
ols, including flags for turning special behavior on and off, including the retu <t>
rn of data apart from the access token. The "resource" indicator (defined in <xr OAuth 2.0 defines the "scope" parameter for controlling access to API
ef target="RFC8707"/>) and RAR extensions (as defined in <xref target="RFC9396"/ s.
>) expand on the "scope" concept in similar but different ways. <vspace blankLi This parameter has been coopted to mean a number of
nes='1'/> different things in different protocols, including flags for
GNAP defines a rich structure for requesting access (analogous to RAR), with str turning special behavior on and off and the return of data
ing references as an optimization (analogous to scopes). GNAP defines methods fo apart from the access token.
r requesting directly-returned user information, separate from API access. This The "resource" indicator (defined in <xref target="RFC8707"/>) and Rich
information includes identifiers for the current user and structured assertions. Authorization Request (RAR) extensions (as defined in <xref target="RFC9396"/>)
The core GNAP protocol makes no assumptions or demands on the format or content expand on the "scope" concept in similar but different ways. </t>
s of the access token, but the RS extension allows a negotiation of token format <t>
s between the AS and RS.</t> GNAP defines a rich structure for requesting access (analogous to RAR), with str
<t><strong>Cryptography-based security:</strong> <vspace blankLines='1'/> ing references as an optimization (analogous to scopes). GNAP defines methods fo
OAuth 2.0 uses shared bearer secrets, including the client_secret and access tok r requesting directly returned user information, separate from API access. This
en, and advanced authentication and sender constraint have been built on after t information includes identifiers for the current user and structured assertions.
he fact in inconsistent ways. <vspace blankLines='1'/> GNAP makes no assumptions or demands on the format or contents of the access to
In GNAP, all communication between the client instance and AS is bound to a key ken, but the RS extension allows a negotiation of token formats between the AS a
held by the client instance. GNAP uses the same cryptographic mechanisms for bot nd RS.</t>
h authenticating the client (to the AS) and binding the access token (to the RS </li>
and the AS). GNAP allows extensions to define new cryptographic protection mecha <li>
nisms, as new methods are expected to become available over time. GNAP does not <t><strong>Cryptography-based security:</strong> </t>
have a notion of "public clients" because key information can always be sent and <t>
used dynamically.</t> OAuth 2.0 uses shared bearer secrets, including the client_secret and access tok
<t><strong>Privacy and usable security:</strong> <vspace blankLines='1'/> en, and advanced authentication and sender constraints have been built on after
OAuth 2.0's deployment model assumes a strong binding between the AS and the RS. the fact in inconsistent ways. </t>
<vspace blankLines='1'/> <t>
GNAP is designed to be interoperable with decentralized identity standards and t In GNAP, all communication between the client instance and AS is bound to a key
o provide a human-centric authorization layer. In addition to the core protocol, held by the client instance. GNAP uses the same cryptographic mechanisms for bot
GNAP supports various patterns of communication between RSs and ASs through ext h authenticating the client (to the AS) and binding the access token (to the RS
ensions. GNAP tries to limit the odds of a consolidation to just a handful of su and the AS). GNAP allows extensions to define new cryptographic protection mecha
per-popular AS services.</t> nisms, as new methods are expected to become available over time. GNAP does not
</list></t> have the notion of "public clients" because key information can always be sent a
nd used dynamically.</t>
</section> </li>
<section anchor="examples"><name>Example Protocol Flows</name> <li>
<t><strong>Privacy and usable security:</strong> </t>
<t>The protocol defined in this specification provides a number of <t>
OAuth 2.0's deployment model assumes a strong binding between the AS and the RS.
</t>
<t>
GNAP is designed to be interoperable with decentralized identity standards and t
o provide a human-centric authorization layer. In addition to this specification
, GNAP supports various patterns of communication between RSs and ASes through e
xtensions. GNAP tries to limit the odds of a consolidation to just a handful of
popular AS services.</t>
</li>
</ol>
</section>
<section anchor="examples">
<name>Example Protocol Flows</name>
<t>The protocol defined in this specification provides a number of
features that can be combined to solve many different kinds of features that can be combined to solve many different kinds of
authentication scenarios. This section seeks to show examples of how the authentication scenarios. This section seeks to show examples of how the
protocol would be applied for different situations.</t> protocol could be applied for different situations.</t>
<t>Some longer fields, particularly cryptographic information, have been
<t>Some longer fields, particularly cryptographic information, have been
truncated for display purposes in these examples.</t> truncated for display purposes in these examples.</t>
<section anchor="example-auth-code">
<section anchor="example-auth-code"><name>Redirect-Based User Interaction</name> <name>Redirect-Based User Interaction</name>
<t>In this scenario, the user is the RO and has access to a web
<t>In this scenario, the user is the RO and has access to a web
browser, and the client instance can take front-channel callbacks on the same browser, and the client instance can take front-channel callbacks on the same
device as the user. This combination is analogous to the OAuth 2.0 device as the user. This combination is analogous to the OAuth 2.0
Authorization Code grant type.</t> Authorization Code grant type.</t>
<t>The client instance initiates the request to the AS. Here, the client
<t>The client instance initiates the request to the AS. Here the client instance instance
identifies itself using its public key.</t> identifies itself using its public key.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
skipping to change at line 10197 skipping to change at line 9613
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS processes the request and determines that the RO needs to
<t>The AS processes the request and determines that the RO needs to interact. The AS returns the following response that gives the client instance t
interact. The AS returns the following response giving the client instance the he
information it needs to connect. The AS has also indicated to the information it needs to connect. The AS has also indicated to the
client instance that it can use the given instance identifier to identify itself in client instance that it can use the given instance identifier to identify itself in
<xref target="request-instance">future requests</xref>.</t> future requests (<xref target="request-instance"> </xref>).</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"interact": { "interact": {
"redirect": "redirect":
"https://server.example.com/interact/4CF492MLVMSW9MKM", "https://server.example.com/interact/4CF492MLVMSW9MKM",
"finish": "MBDOFXG4Y5CVJCX821LH" "finish": "MBDOFXG4Y5CVJCX821LH"
} }
"continue": { "continue": {
"access_token": { "access_token": {
"value": "80UPRY5NM33OMUKMKSKU" "value": "80UPRY5NM33OMUKMKSKU"
}, },
"uri": "https://server.example.com/continue" "uri": "https://server.example.com/continue"
}, },
"instance_id": "7C7C4AZ9KHRS6X63AJAO" "instance_id": "7C7C4AZ9KHRS6X63AJAO"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The client instance saves the response and redirects the user to the
<t>The client instance saves the response and redirects the user to the
interaction start mode's "redirect" URI by sending the following HTTP message to the user's interaction start mode's "redirect" URI by sending the following HTTP message to the user's
browser.</t> browser.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP 303 Found HTTP 303 Found
Location: https://server.example.com/interact/4CF492MLVMSW9MKM Location: https://server.example.com/interact/4CF492MLVMSW9MKM
]]></sourcecode></figure> ]]></sourcecode>
<t>The user's browser fetches the AS's interaction URI. The user logs
<t>The user's browser fetches the AS's interaction URI. The user logs
in, is identified as the RO for the resource being requested, and in, is identified as the RO for the resource being requested, and
approves the request. Since the AS has a callback parameter that was sent in the initial request's interaction finish method, the AS approves the request. Since the AS has a callback parameter that was sent in the initial request's interaction finish method, the AS
generates the interaction reference, calculates the hash, and generates the interaction reference, calculates the hash, and
redirects the user back to the client instance with these additional values redirects the user back to the client instance with these additional values
added as query parameters.</t> added as query parameters.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
HTTP 302 Found HTTP 302 Found
Location: https://client.example.net/return/123455\ Location: https://client.example.net/return/123455\
?hash=x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY\ ?hash=x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY\
&interact_ref=4IFWWIKYBC2PQ6U56NL1 &interact_ref=4IFWWIKYBC2PQ6U56NL1
]]></sourcecode></figure> ]]></sourcecode>
<t>The client instance receives this request from the user's browser. Th
<t>The client instance receives this request from the user's browser. The e
client instance ensures that this is the same user that was sent out by client instance ensures that this is the same user that was sent out by
validating session information and retrieves the stored pending validating session information and retrieves the stored pending
request. The client instance uses the values in this to validate the hash request. The client instance uses the values in this to validate the hash
parameter. The client instance then calls the continuation URI using the associa ted continuation access token and presents the parameter. The client instance then calls the continuation URI using the associa ted continuation access token and presents the
interaction reference in the request content. The client instance signs interaction reference in the request content. The client instance signs
the request as above.</t> the request as above.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /continue HTTP/1.1 POST /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"interact_ref": "4IFWWIKYBC2PQ6U56NL1" "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS retrieves the pending request by looking up the pending grant
<t>The AS retrieves the pending request by looking up the pending grant request request associated with the presented continuation access token. Seeing that the
associated with the presented continuation access token. Seeing that the grant i grant is approved, the AS issues
s approved, the AS issues
an access token and returns this to the client instance.</t> an access token and returns this to the client instance.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": "https://server.example.com/token/PRY5NM33O\ "manage": "https://server.example.com/token/PRY5NM33O\
skipping to change at line 10311 skipping to change at line 9717
] ]
}] }]
}, },
"continue": { "continue": {
"access_token": { "access_token": {
"value": "80UPRY5NM33OMUKMKSKU" "value": "80UPRY5NM33OMUKMKSKU"
}, },
"uri": "https://server.example.com/continue" "uri": "https://server.example.com/continue"
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
</section>
</section> <section anchor="example-device">
<section anchor="example-device"><name>Secondary Device Interaction</name> <name>Secondary Device Interaction</name>
<t>In this scenario, the user does not have access to a web browser on
<t>In this scenario, the user does not have access to a web browser on
the device and must use a secondary device to interact with the AS. the device and must use a secondary device to interact with the AS.
The client instance can display a user code or a printable QR code. The client instance can display a user code or a printable QR code.
The client instance is not able to accept callbacks from the AS and needs to pol l The client instance is not able to accept callbacks from the AS and needs to pol l
for updates while waiting for the user to authorize the request.</t> for updates while waiting for the user to authorize the request.</t>
<t>The client instance initiates the request to the AS.</t>
<t>The client instance initiates the request to the AS.</t> <sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
"dolphin-metadata", "some other thing" "dolphin-metadata", "some other thing"
], ],
}, },
"client": "7C7C4AZ9KHRS6X63AJAO", "client": "7C7C4AZ9KHRS6X63AJAO",
"interact": { "interact": {
"start": ["redirect", "user_code"] "start": ["redirect", "user_code"]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS processes this and determines that the RO needs to interact.
<t>The AS processes this and determines that the RO needs to interact.
The AS supports both redirect URIs and user codes for interaction, so The AS supports both redirect URIs and user codes for interaction, so
it includes both. Since there is no interaction finish mode, the AS does not inc lude it includes both. Since there is no interaction finish mode, the AS does not inc lude
a nonce, but does include a "wait" parameter on the continuation a nonce but does include a "wait" parameter on the continuation
section because it expects the client instance to poll for results.</t> section because it expects the client instance to poll for results.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"interact": { "interact": {
"redirect": "https://srv.ex/MXKHQ", "redirect": "https://srv.ex/MXKHQ",
"user_code": { "user_code": {
"code": "A1BC3DFF" "code": "A1BC3DFF"
} }
}, },
"continue": { "continue": {
"access_token": { "access_token": {
"value": "80UPRY5NM33OMUKMKSKU" "value": "80UPRY5NM33OMUKMKSKU"
}, },
"uri": "https://server.example.com/continue/VGJKPTKC50", "uri": "https://server.example.com/continue/VGJKPTKC50",
"wait": 60 "wait": 60
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The client instance saves the response and displays the user code vis
<t>The client instance saves the response and displays the user code visually ually
on its screen along with the static device URI. The client instance also on its screen along with the static device URI. The client instance also
displays the short interaction URI as a QR code to be scanned.</t> displays the short interaction URI as a QR code to be scanned.</t>
<t>If the user scans the code, they are taken to the interaction
<t>If the user scans the code, they are taken to the interaction endpoint, and the AS looks up the current pending request based on the
endpoint and the AS looks up the current pending request based on the
incoming URI. If the user instead goes to the static page and enters incoming URI. If the user instead goes to the static page and enters
the code manually, the AS looks up the current pending request based the code manually, the AS looks up the current pending request based
on the value of the user code. In both cases, the user logs in, is on the value of the user code. In both cases, the user logs in, is
identified as the RO for the resource being requested, and approves identified as the RO for the resource being requested, and approves
the request. Once the request has been approved, the AS displays to the request. Once the request has been approved, the AS displays to
the user a message to return to their device.</t> the user a message to return to their device.</t>
<t>Meanwhile, the client instance polls the AS every 60 seconds at
<t>Meanwhile, the client instance periodically polls the AS every 60 seconds at
the continuation URI. The client instance signs the request using the the continuation URI. The client instance signs the request using the
same key and method that it did in the first request.</t> same key and method that it did in the first request.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /continue/VGJKPTKC50 HTTP/1.1 POST /continue/VGJKPTKC50 HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS retrieves the pending request based on the pending grant reque
<t>The AS retrieves the pending request based on the pending grant request assoc st associated with the continuation access token and
iated with the continuation access token and
determines that it has not yet been authorized. The AS indicates to determines that it has not yet been authorized. The AS indicates to
the client instance that no access token has yet been issued but it can the client instance that no access token has yet been issued but it can
continue to call after another 60 second timeout.</t> continue to call after another 60-second timeout.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"continue": { "continue": {
"access_token": { "access_token": {
"value": "G7YQT4KQQ5TZY9SLSS5E" "value": "G7YQT4KQQ5TZY9SLSS5E"
}, },
"uri": "https://server.example.com/continue/ATWHO4Q1WV", "uri": "https://server.example.com/continue/ATWHO4Q1WV",
"wait": 60 "wait": 60
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Note that the continuation URI and access token have been rotated sin
<t>Note that the continuation URI and access token have been rotated since they ce they were
were
used by the client instance to make this call. The client instance polls the used by the client instance to make this call. The client instance polls the
continuation URI after a 60 second timeout using this new information.</t> continuation URI after a 60-second timeout using this new information.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /continue/ATWHO4Q1WV HTTP/1.1 POST /continue/ATWHO4Q1WV HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP G7YQT4KQQ5TZY9SLSS5E Authorization: GNAP G7YQT4KQQ5TZY9SLSS5E
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS retrieves the pending request based on the URI and access toke
<t>The AS retrieves the pending request based on the URI and access token, n,
determines that it has been approved, and issues an access determines that it has been approved, and issues an access
token for the client to use at the RS.</t> token for the client to use at the RS.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": "https://server.example.com/token/PRY5NM33O\ "manage": "https://server.example.com/token/PRY5NM33O\
M4TB8N6BW7OZB8CDFONP219RP1L", M4TB8N6BW7OZB8CDFONP219RP1L",
"access": [ "access": [
"dolphin-metadata", "some other thing" "dolphin-metadata", "some other thing"
] ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
</section>
</section> <section anchor="example-no-user">
<section anchor="example-no-user"><name>No User Involvement</name> <name>No User Involvement</name>
<t>In this scenario, the client instance is requesting access on its own
<t>In this scenario, the client instance is requesting access on its own
behalf, with no user to interact with.</t> behalf, with no user to interact with.</t>
<t>The client instance creates a request to the AS, identifying itself w
<t>The client instance creates a request to the AS, identifying itself with its ith its
public key and using MTLS to make the request.</t> public key and using MTLS to make the request.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
{ {
"access_token": { "access_token": {
"access": [ "access": [
"backend service", "nightly-routine-3" "backend service", "nightly-routine-3"
], ],
}, },
"client": { "client": {
"key": { "key": {
"proof": "mtls", "proof": "mtls",
"cert#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" "cert#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
} }
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS processes this, determines that the client instance can ask fo
<t>The AS processes this and determines that the client instance can ask for r
the requested resources and issues an access token.</t> the requested resources, and issues an access token.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": "https://server.example.com/token", "manage": "https://server.example.com/token",
"access": [ "access": [
"backend service", "nightly-routine-3" "backend service", "nightly-routine-3"
] ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
</section>
</section> <section anchor="example-async">
<section anchor="example-async"><name>Asynchronous Authorization</name> <name>Asynchronous Authorization</name>
<t>In this scenario, the client instance is requesting on behalf of a sp
<t>In this scenario, the client instance is requesting on behalf of a specific ecific
RO, but has no way to interact with the user. The AS can RO but has no way to interact with the user. The AS can
asynchronously reach out to the RO for approval in this scenario.</t> asynchronously reach out to the RO for approval in this scenario.</t>
<t>The client instance starts the request at the AS by requesting a set
<t>The client instance starts the request at the AS by requesting a set of of
resources. The client instance also identifies a particular user.</t> resources. The client instance also identifies a particular user.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
skipping to change at line 10561 skipping to change at line 9944
], ],
}, },
"client": "7C7C4AZ9KHRS6X63AJAO", "client": "7C7C4AZ9KHRS6X63AJAO",
"user": { "user": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
} ] } ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS processes this and determines that the RO needs to interact.
<t>The AS processes this and determines that the RO needs to interact.
The AS determines that it can reach the identified user asynchronously The AS determines that it can reach the identified user asynchronously
and that the identified user does have the ability to approve this and that the identified user does have the ability to approve this
request. The AS indicates to the client instance that it can poll for request. The AS indicates to the client instance that it can poll for
continuation.</t> continuation.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"continue": { "continue": {
"access_token": { "access_token": {
"value": "80UPRY5NM33OMUKMKSKU" "value": "80UPRY5NM33OMUKMKSKU"
}, },
"uri": "https://server.example.com/continue", "uri": "https://server.example.com/continue",
"wait": 60 "wait": 60
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS reaches out to the RO and prompts them for consent. In this
example scenario, the AS has an application that it can push notifications in
to for the specified account.</t>
<t>Meanwhile, the client instance periodically polls the AS every 60 seconds at <t>The AS reaches out to the RO and prompts them for consent. In this
example scenario, the AS has an application that it can push notifications to fo
r the specified account.</t>
<t>Meanwhile, the client instance periodically polls the AS every 60 sec
onds at
the continuation URI.</t> the continuation URI.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /continue HTTP/1.1 POST /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS retrieves the pending request based on the continuation access
<t>The AS retrieves the pending request based on the continuation access token a token and
nd
determines that it has not yet been authorized. The AS indicates to determines that it has not yet been authorized. The AS indicates to
the client instance that no access token has yet been issued but it can the client instance that no access token has yet been issued but it can
continue to call after another 60 second timeout.</t> continue to call after another 60-second timeout.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"continue": { "continue": {
"access_token": { "access_token": {
"value": "BI9QNW6V9W3XFJK4R02D" "value": "BI9QNW6V9W3XFJK4R02D"
}, },
"uri": "https://server.example.com/continue", "uri": "https://server.example.com/continue",
"wait": 60 "wait": 60
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>Note that the continuation access token value has been rotated since
<t>Note that the continuation access token value has been rotated since it was it was
used by the client instance to make this call. The client instance polls the used by the client instance to make this call. The client instance polls the
continuation URI after a 60 second timeout using the new token.</t> continuation URI after a 60-second timeout using the new token.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /continue HTTP/1.1 POST /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP BI9QNW6V9W3XFJK4R02D Authorization: GNAP BI9QNW6V9W3XFJK4R02D
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
]]></sourcecode></figure> ]]></sourcecode>
<t>The AS retrieves the pending request based on the handle,
<t>The AS retrieves the pending request based on the handle and determines that it has been approved, and issues an access
determines that it has been approved and it issues an access
token.</t> token.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": "https://server.example.com/token/PRY5NM33O\ "manage": "https://server.example.com/token/PRY5NM33O\
M4TB8N6BW7OZB8CDFONP219RP1L", M4TB8N6BW7OZB8CDFONP219RP1L",
"access": [ "access": [
"dolphin-metadata", "some other thing" "dolphin-metadata", "some other thing"
] ]
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
</section>
</section> <section anchor="example-oauth2">
<section anchor="example-oauth2"><name>Applying OAuth 2.0 Scopes and Client IDs< <name>Applying OAuth 2.0 Scopes and Client IDs</name>
/name> <t>While GNAP is not designed to be directly compatible with
<t>While GNAP is not designed to be directly compatible with
OAuth 2.0 <xref target="RFC6749"/>, considerations have been made to enable the use of OAuth 2.0 <xref target="RFC6749"/>, considerations have been made to enable the use of
OAuth 2.0 concepts and constructs more smoothly within GNAP.</t> OAuth 2.0 concepts and constructs more smoothly within GNAP.</t>
<t>In this scenario, the client developer has a <tt>client_id</tt> and s
<t>In this scenario, the client developer has a <spanx style="verb">client_id</s et of
panx> and set of <tt>scope</tt> values from their OAuth 2.0 system and wants to apply them to the
<spanx style="verb">scope</spanx> values from their OAuth 2.0 system and wants t new protocol. In OAuth 2.0, the client developer would put
o apply them to the their <tt>client_id</tt> and <tt>scope</tt> values as parameters into a redirect
new protocol. Traditionally, the OAuth 2.0 client developer would put request
their <spanx style="verb">client_id</spanx> and <spanx style="verb">scope</spanx
> values as parameters into a redirect request
to the authorization endpoint.</t> to the authorization endpoint.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
HTTP 302 Found HTTP 302 Found
Location: https://server.example.com/authorize\ Location: https://server.example.com/authorize\
?client_id=7C7C4AZ9KHRS6X63AJAO\ ?client_id=7C7C4AZ9KHRS6X63AJAO\
&scope=read%20write%20dolphin\ &scope=read%20write%20dolphin\
&redirect_uri=https://client.example.net/return\ &redirect_uri=https://client.example.net/return\
&response_type=code\ &response_type=code\
&state=123455 &state=123455
]]></sourcecode></figure> ]]></sourcecode>
<t>Now the developer wants to make an analogous request to the AS
<t>Now the developer wants to make an analogous request to the AS
using GNAP. To do so, the client instance makes an HTTP POST and using GNAP. To do so, the client instance makes an HTTP POST and
places the OAuth 2.0 values in the appropriate places.</t> places the OAuth 2.0 values in the appropriate places.</t>
<sourcecode type="http-message"><![CDATA[
<figure><sourcecode type="http-message"><![CDATA[
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Content-Digest: sha-256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
skipping to change at line 10710 skipping to change at line 10077
"client": "7C7C4AZ9KHRS6X63AJAO", "client": "7C7C4AZ9KHRS6X63AJAO",
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.example.net/return?state=123455", "uri": "https://client.example.net/return?state=123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
} }
} }
]]></sourcecode></figure> ]]></sourcecode>
<t>The <tt>client_id</tt> can be used to identify the client instance's
<t>The <spanx style="verb">client_id</spanx> can be used to identify the client keys that it
instance's keys that it
uses for authentication, the scopes represent resources that the uses for authentication, the scopes represent resources that the
client instance is requesting, and the <spanx style="verb">redirect_uri</spanx> client instance is requesting, and the <tt>redirect_uri</tt> and <tt>state</tt>
and <spanx style="verb">state</spanx> value are value are
pre-combined into a <spanx style="verb">finish</spanx> URI that can be unique pe pre-combined into a <tt>finish</tt> URI that can be unique per request. The
r request. The
client instance additionally creates a nonce to protect the callback, separate client instance additionally creates a nonce to protect the callback, separate
from the state parameter that it has added to its return URI.</t> from the state parameter that it has added to its return URI.</t>
<t>From here, the protocol continues as above.</t>
<t>From here, the protocol continues as above.</t> </section>
</section>
</section> <section anchor="interoperability-profiles">
</section> <name>Interoperability Profiles</name>
<section anchor="interoperability-profiles"><name>Interoperability Profiles</nam <t>The GNAP specification has many different modes, options, and mechanism
e> s, allowing it
<t>The GNAP specification has many different modes, options, and mechanisms, all
owing it
to solve a wide variety of problems in a wide variety of deployments. The wide a pplicability to solve a wide variety of problems in a wide variety of deployments. The wide a pplicability
of GNAP makes it difficult, if not impossible, to define a set of mandatory-to-i mplement of GNAP makes it difficult, if not impossible, to define a set of mandatory-to-i mplement
features, since one environment's required feature would be impossible to do in another environment. features, since one environment's required feature would be impossible to do in another environment.
While this is a large problem in many systems, GNAP's back-and-forth negotiation process While this is a large problem in many systems, GNAP's back-and-forth negotiation process
allows parties to declare at runtime everything that they support and then have the other party allows parties to declare at runtime everything that they support and then have the other party
select from that the subset of items that they also support, leading to function al compatibility select from that the subset of items that they also support, leading to function al compatibility
in many parts of the protocol even in an open world scenario.</t> in many parts of the protocol even in an open world scenario.</t>
<t>In addition, GNAP defines a set of interoperability profiles that gathe
<t>In addition, GNAP defines a set of interoperability profiles which gather tog r together core requirements
ether core requirements
to fix options into common configurations that are likely to be useful to large populations of to fix options into common configurations that are likely to be useful to large populations of
similar applications.</t> similar applications.</t>
<t>Conformant AS implementations of these profiles <bcp14>MUST</bcp14> imp
<t>Conformant AS implementations of these profiles <bcp14>MUST</bcp14> implement lement at least the features as specified
at least the features as specified
in the profile and <bcp14>MAY</bcp14> implement additional features or profiles. Conformant client implementations in the profile and <bcp14>MAY</bcp14> implement additional features or profiles. Conformant client implementations
of these profiles <bcp14>MUST</bcp14> implement at least the features as specifi ed, except where a subset of the of these profiles <bcp14>MUST</bcp14> implement at least the features as specifi ed, except where a subset of the
features allows the protocol to function (such as using polling instead of a pus h finish method for features allows the protocol to function (such as using polling instead of a pus h finish method for
the Secondary Device profile).</t> the Secondary Device profile).</t>
<section anchor="web-based-redirection">
<name>Web-Based Redirection</name>
<t>Implementations conformant to the web-based redirection profile of GN
AP <bcp14>MUST</bcp14> implement all of the following features:</t>
<ul spacing="normal">
<li>Interaction Start Methods: <tt>redirect</tt></li>
<section anchor="web-based-redirection"><name>Web-based Redirection</name> <li>Interaction Finish Methods: <tt>redirect</tt></li>
<t>Implementations conformant to the Web-based Redirection profile of GNAP <bcp1 4>MUST</bcp14> implement all of the following features:</t> <li>Interaction Hash Algorithms: <tt>sha-256</tt></li>
<t><list style="symbols"> <li>Key Proofing Methods: <tt>httpsig</tt> with no additional parameters</li>
<t><em>Interaction Start Methods</em>: <spanx style="verb">redirect</spanx></t
>
<t><em>Interaction Finish Methods</em>: <spanx style="verb">redirect</spanx></
t>
<t><em>Interaction Hash Algorithms</em>: <spanx style="verb">sha-256</spanx></
t>
<t><em>Key Proofing Methods</em>: <spanx style="verb">httpsig</spanx> with no
additional parameters</t>
<t><em>Key Formats</em>: <spanx style="verb">jwks</spanx> with signature algor
ithm included in the key's <spanx style="verb">alg</spanx> parameter</t>
<t><em>JOSE Signature Algorithm</em>: PS256</t>
<t><em>Subject Identifier Formats</em>: <spanx style="verb">opaque</spanx></t>
<t><em>Assertion Formats</em>: <spanx style="verb">id_token</spanx></t>
</list></t>
</section> <li>Key Formats: <tt>jwks</tt> with signature algorithm included in the key's <
<section anchor="secondary-device"><name>Secondary Device</name> tt>alg</tt> parameter</li>
<t>Implementations conformant to the Secondary Device profile of GNAP <bcp14>MUS T</bcp14> implement all of the following features:</t> <li>JOSE Signature Algorithm: PS256</li>
<t><list style="symbols"> <li>Subject Identifier Formats: <tt>opaque</tt></li>
<t><em>Interaction Start Methods</em>: <spanx style="verb">user_code</spanx> a
nd <spanx style="verb">user_code_uri</spanx></t>
<t><em>Interaction Finish Methods</em>: <spanx style="verb">push</spanx></t>
<t><em>Interaction Hash Algorithms</em>: <spanx style="verb">sha-256</spanx></
t>
<t><em>Key Proofing Methods</em>: <spanx style="verb">httpsig</spanx> with no
additional parameters</t>
<t><em>Key Formats</em>: <spanx style="verb">jwks</spanx> with signature algor
ithm included in the key's <spanx style="verb">alg</spanx> parameter</t>
<t><em>JOSE Signature Algorithm</em>: PS256</t>
<t><em>Subject Identifier Formats</em>: <spanx style="verb">opaque</spanx></t>
<t><em>Assertion Formats</em>: <spanx style="verb">id_token</spanx></t>
</list></t>
</section> <li>Assertion Formats: <tt>id_token</tt></li>
</section>
<section anchor="extensions"><name>Guidance for Extensions</name>
<t>Extensions to this specification have a variety of places to alter the protoc </ul>
ol, including many </section>
fields and objects that can have additional values in a registry <xref target="I <section anchor="secondary-device">
ANA">registry</xref> established by this <name>Secondary Device</name>
<t>Implementations conformant to the Secondary Device profile of GNAP <b
cp14>MUST</bcp14> implement all of the following features:</t>
<ul spacing="normal">
<li>Interaction Start Methods: <tt>user_code</tt> and <tt>user_code_
uri</tt></li>
<li>Interaction Finish Methods: <tt>push</tt></li>
<li>Interaction Hash Algorithms: <tt>sha-256</tt></li>
<li>Key Proofing Methods: <tt>httpsig</tt> with no additional parame
ters</li>
<li>Key Formats: <tt>jwks</tt> with signature algorithm included in
the key's <tt>alg</tt> parameter</li>
<li>JOSE Signature Algorithm: PS256</li>
<li>Subject Identifier Formats: <tt>opaque</tt></li>
<li>Assertion Formats: <tt>id_token</tt></li>
</ul>
</section>
</section>
<section anchor="extensions">
<name>Guidance for Extensions</name>
<t>Extensions to this specification have a variety of places to alter the
protocol, including many
fields and objects that can have additional values in a registry (<xref target="
IANA"> </xref>) established by this
specification. For interoperability and to preserve the security of the protocol , extensions should specification. For interoperability and to preserve the security of the protocol , extensions should
register new values with IANA by following the specified mechanism. While it may technically be register new values with IANA by following the specified mechanism. While it may technically be
possible to extend the protocol by adding elements to JSON objects that are not governed by an possible to extend the protocol by adding elements to JSON objects that are not governed by an
IANA registry, a recipient may ignore such values but is also allowed to reject them.</t> IANA registry, a recipient may ignore such values but is also allowed to reject them.</t>
<t>Most object fields in GNAP are specified with types, and those types ca
<t>Most object fields in GNAP are specified with types, and those types can allo n allow different but
w different but related behavior. For example, the <tt>access</tt> array can include either stri
related behavior. For example, the <spanx style="verb">access</spanx> array can ngs or objects, as
include either strings or objects, as discussed in <xref target="resource-access-rights"/>. The use of JSON polymorphi
discussed in <xref target="resource-access-rights"/>. The use of <xref target="p sm (<xref target="polymorphism"> </xref>)
olymorphism">JSON polymorphism</xref>
within GNAP allows extensions to define new fields by not only choosing a new na me but also by within GNAP allows extensions to define new fields by not only choosing a new na me but also by
using an existing name with a new type. However, the extension's definition using an existing name with a new type. However, the extension's definition
of a new type for a field needs to fit the same kind of item being extended. For example, a of a new type for a field needs to fit the same kind of item being extended. For example, a
hypothetical extension could define a string value for the <spanx style="verb">a ccess_token</spanx> request field, hypothetical extension could define a string value for the <tt>access_token</tt> request field,
with a URL to download a hosted access token request. Such an extension would be appropriate as with a URL to download a hosted access token request. Such an extension would be appropriate as
the <spanx style="verb">access_token</spanx> field still defines the access toke the <tt>access_token</tt> field still defines the access tokens being requested.
ns being requested. However, if an extension However, if an extension
were to define a string value for the <spanx style="verb">access_token</spanx> r were to define a string value for the <tt>access_token</tt> request field, with
equest field, with the value instead the value instead
being something unrelated to the access token request such as a value or key for mat, this would being something unrelated to the access token request such as a value or key for mat, this would
not be an appropriate means of extension. (Note that this specific extension exa mple would create not be an appropriate means of extension. (Note that this specific extension exa mple would create
another form of SSRF attack surface as discussed in <xref target="security-ssrf" />.)</t> another form of SSRF attack surface as discussed in <xref target="security-ssrf" />.)</t>
<t>As another example, both interaction start modes (<xref target="request
<t>For another example, both interaction <xref target="request-interact-start">i -interact-start"> </xref>) and
nteraction start modes</xref> and key proofing methods (<xref target="binding-keys"> </xref>) can be defined as ei
<xref target="binding-keys">key proofing methods</xref> can be defined as either ther strings or objects. An extension
strings or objects. An extension could take a method defined as a string, such as <tt>app</tt>, and define an obj
could take a method defined as a string, such as <spanx style="verb">app</spanx> ect-based version with
, and define an object-based version with
additional parameters. This extension should still define a method to launch an application on the additional parameters. This extension should still define a method to launch an application on the
end user's device, just like <spanx style="verb">app</spanx> does when specified end user's device, just like <tt>app</tt> does when specified as a string.</t>
as a string.</t> <t>Additionally, the ability to deal with different types for a field is n
ot expected to be equal
<t>Additionally, the ability to deal with different types for a field is not exp
ected to be equal
between an AS and client software, with the client software being assumed to be both more varied between an AS and client software, with the client software being assumed to be both more varied
and more simplified than the AS. Furthermore, the nature of the negotiation proc ess in GNAP allows and more simplified than the AS. Furthermore, the nature of the negotiation proc ess in GNAP allows
the AS more chance of recovery from unknown situations and parameters. As such, any extensions that the AS more chance of recovery from unknown situations and parameters. As such, any extensions that
change the type of any field returned to a client instance should only do so whe n the client change the type of any field returned to a client instance should only do so whe n the client
instance has indicated specific support for that extension through some kind of request parameter.</t> instance has indicated specific support for that extension through some kind of request parameter.</t>
</section>
</section> <section anchor="polymorphism">
<section anchor="polymorphism"><name>JSON Structures and Polymorphism</name> <name>JSON Structures and Polymorphism</name>
<t>GNAP makes use of polymorphism within the <xref target="RFC8259">JSON</
<t>GNAP makes use of polymorphism within the <xref target="RFC8259">JSON</xref> xref> structures used for
structures used for
the protocol. Each portion of this protocol is defined in terms of the JSON data type the protocol. Each portion of this protocol is defined in terms of the JSON data type
that its values can take, whether it's a string, object, array, boolean, or numb er. For some that its values can take, whether it's a string, object, array, boolean, or numb er. For some
fields, different data types offer different descriptive capabilities and are us ed in different fields, different data types offer different descriptive capabilities and are us ed in different
situations for the same field. Each data type provides a different syntax to exp ress situations for the same field. Each data type provides a different syntax to exp ress
the same underlying semantic protocol element, which allows for optimization and the same underlying semantic protocol element, which allows for optimization and
simplification in many common cases.</t> simplification in many common cases.</t>
<t>Even though JSON is often used to describe strongly typed structures, J
<t>Even though JSON is often used to describe strongly typed structures, JSON on SON on its own is naturally polymorphic.
its own is naturally polymorphic.
In JSON, the named members of an object have no type associated with them, and a ny In JSON, the named members of an object have no type associated with them, and a ny
data type can be used as the value for any member. In practice, each member data type can be used as the value for any member. In practice, each member
has a semantic type that needs to make sense to the parties creating and has a semantic type that needs to make sense to the parties creating and
consuming the object. Within this protocol, each object member is defined in ter ms consuming the object. Within this protocol, each object member is defined in ter ms
of its semantic content, and this semantic content might have expressions in of its semantic content, and this semantic content might have expressions in
different concrete data types for different specific purposes. Since each object different concrete data types for different specific purposes. Since each object
member has exactly one value in JSON, each data type for an object member field member has exactly one value in JSON, each data type for an object member field
is naturally mutually exclusive with other data types within a single JSON objec t.</t> is naturally mutually exclusive with other data types within a single JSON objec t.</t>
<t>For example, a resource request for a single access token is composed o
<t>For example, a resource request for a single access token is composed of an o f an object
bject of resource request descriptions, while a request for multiple access tokens is
of resource request descriptions while a request for multiple access tokens is
composed of an array whose member values are all objects. Both of these represen t requests composed of an array whose member values are all objects. Both of these represen t requests
for access, but the difference in syntax allows the client instance and AS to di fferentiate for access, but the difference in syntax allows the client instance and AS to di fferentiate
between the two request types in the same request.</t> between the two request types in the same request.</t>
<t>Another form of polymorphism in JSON comes from the fact that the value
<t>Another form of polymorphism in JSON comes from the fact that the values with s within JSON
in JSON
arrays need not all be of the same JSON data type. However, within this protocol , arrays need not all be of the same JSON data type. However, within this protocol ,
each element within the array needs to be of the same kind of semantic element f or each element within the array needs to be of the same kind of semantic element f or
the collection to make sense, even when the data types are different from each o ther.</t> the collection to make sense, even when the data types are different from each o ther.</t>
<t>For example, each aspect of a resource request can be described using a
<t>For example, each aspect of a resource request can be described using an obje n object with multiple
ct with multiple
dimensional components, or the aspect can be requested using a string. In both c ases, the resource dimensional components, or the aspect can be requested using a string. In both c ases, the resource
request is being described in a way that the AS needs to interpret, but with dif ferent request is being described in a way that the AS needs to interpret, but with dif ferent
levels of specificity and complexity for the client instance to deal with. An AP I designer levels of specificity and complexity for the client instance to deal with. An AP I designer
can provide a set of common access scopes as simple strings but still allow can provide a set of common access scopes as simple strings but still allow
client software developers to specify custom access when needed for more complex APIs.</t> client software developers to specify custom access when needed for more complex APIs.</t>
<t>Extensions to this specification can use different data types for defin
<t>Extensions to this specification can use different data types for defined fie ed fields, but
lds, but each extension needs to not only declare what the data type means but also provi
each extension needs to not only declare what the data type means, but also prov de
ide
justification for the data type representing the same basic kind of thing it ext ends. justification for the data type representing the same basic kind of thing it ext ends.
For example, an extension declaring an "array" representation for a field would need For example, an extension declaring an "array" representation for a field would need
to explain how the array represents something akin to the non-array element that it to explain how the array represents something akin to the non-array element that it
is replacing. See additional discussion in <xref target="extensions"/>.</t> is replacing. See additional discussion in <xref target="extensions"/>.</t>
</section>
</section> <section anchor="Acknowledgements" numbered="false">
<name>Acknowledgements</name>
</back> <t>The authors would like to thank the following
individuals for their reviews, implementations, and contributions:
<!-- ##markdown-source: <contact fullname="Åke Axeland" asciiFullname="Ake Axeland"/>, <contact
H4sIAAAAAAAAA+y9237bSJI3eI+nwKouLE2RtCWf9XXPNyofqlzlU0uq6e7x fullname="Aaron Parecki"/>, <contact fullname="Adam Omar Oueidat"/>,
9GeBJCShTQIcgJSscXnu9gH2Yu/3WXbfZJ9k45gZCSQoyYfq6t5R/X5liQTy <contact fullname="Andrii Deinega"/>, <contact fullname="Annabelle
GBkZ8Y/TcDhMlsVylu+mN76vs3KZvsxPqmWRLYuqTLNymu6tlqdVXfwnf/K6 Backman"/>, <contact fullname="Dick Hardt"/>, <contact fullname="Dmitri
rpbVpJrdSKbVpMzm8N60zo6XwyJfHg9PymwxnFR1PlzIc8Pth8kkW0Kb9cVu Zagidulin"/>, <contact fullname="Dmitry Barinov"/>, <contact fullname="Flo
2iynSVIs6t10Wa+a5c6tWw9v7SRZnWe76UE+WdXF8iI5r+p3J3W1Wuym37/c rian Helmschmidt"/>,
e528yy/go+lu+qxc5nWZL4ePscckaZYwvrfZrCphFBd5kyyK3fQNdDtI4X9F <contact fullname="Francis Pouatcha"/>, <contact fullname="George
Oc3L5SBtqnpZ58cN/HYxl1+WdTGBrybVfJHJL3N4GL4qyllR5oMUZjfPFoui Fletcher"/>, <contact fullname="Haardik Haardik"/>, <contact
PPlLkmS0BLtJmg7hgWY3/XGU7heT07yGj9KUl+FHmFBR2s+r+iQrZeF20+/y fullname="Hamid Massaoud"/>, <contact fullname="Jacky Yuan"/>, <contact
ZlG9y9Mn5Qn0kNfQND2Vz7Nitpvi+v3LX6mNUU1tjOB9egKWZTc9XS4Xze7N fullname="Joseph Heenan"/>,
m+Nm8W5UVDfpm7rCjcunxbKqEz+8p6P02XycrWZLM76n2bjIy+CLcIDZJK+X <contact fullname="Kathleen Moriarty"/>, <contact fullname="Leif
0LQd1TG9NCr4pX8JHgmGpd/cTJKyqufQ5Fm+S4999+j19sO7/Pv+00c7tx/e Johansson"/>, <contact fullname="Mike Jones"/>, <contact fullname="Mike
d3/cvn37of/j4YN77o879+48cH/cvXfHf3P/zj3/zf2723ftH77pe/fvPDR/ Varley"/>, <contact fullname="Nat Sakimura"/>, <contact
3L3l/niwff+O/2Pnrn/swf1b0toPh4evd/Gjh9vbt/Rr+H3bPfvwzo754+7t fullname="Takahiko Kawasaki"/>, <contact fullname="Takahiro Tsuchiya"/>, a
W+abh7ellb2DH4Z7z7/nv9JUDtrGS9iQKZDzMa8UHKsfsuY03ZvBKSmWp/N0 nd
Pz8pgEgvNvTFrD7Jl361z8/PR0VWZkgiN7OmKU5Kot+buNXTYeFb7n4yen+6 <contact fullname="Yaron Sheffer"/>.</t>
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
cwuNAo+jCbgQ96Ah9GZXK3oXTSOuJZygCWmXVtbJZbvpXpmeYtaHpd4Al+wt
0beLT8F0L4zcwKJK8EyNhNOIUstO8wTKkTUQ20WyrbRtonim2Gym+Gbd1tPQ
jti0vV8WGbojiFatjIGEa5aEzI13U8kgbSanOR1nQX7F1eAY+yTFkRJ9vAcp
UHj/6cWiomVsFDNFRBt2hM3abdvOKP1zvrQ3qg86IKNuKEei1bdZ+gNcLazF
m8Jo8NxgHA1jH7QADsNp2B0ZTs70QjSQQTrlRSHZVm22bQURR47iC5od3EFh
LsUtKxMmsX1Xr3J34RZLVVpY4PR6S+AbYyHYVekCAadOAHRaP36A1u+uw0TT
5zGB54/vSUFmazaAjDGagWIR0UvZKF7ezIsYPEWdoUDBzpvoH6w4LSnZQ9ZV
dnUv7ZOhVuEiOAMRkBQikaHkoLtz6IF0J4EYocQe14FxmEB5hcgicscwIjjJ
6VZ5LcJuizHAMWSsb7qaSDCmCJ6ZYwJkF66qIfIclJ5QdascEKG9NPLSqnRL
QpyUQFT4qELV163hgVtDRz8oOuCuRvcbvgTtGA4Yzrml8zTiM5IdLykKuK7J
S4WAAx9CRmdgCvL1SU5CiEHGRfNjZ2ARWtRh3p0+DfYzAWMULKgu5leIvNtL
T2bVGCMaUKpaLK2GoKIs49cB1hs60MU0mCan6J8zYbB21qBdNuRSTg5Zudoa
CElEXueJhduFSwSb+PBB2paBE44zE/Y3r6Y5WYrbSH/X54y9Csjw7uxNItgg
fdB9hAIZepE1zjqJvdsULRpz5LIBPcVz9uEb3SwFZjA4Gg56RqY8jidFbxwB
OulwRoK4JarehYYY50hvMI14Tg5kAhnHBqMId5IPGJs6Xs2caSFEXyUIuePt
EEZeet9NBmhOc2dawploMEW2OuGYglPBxFrxxH6a7B3Q+PQEEglKoN/swjhL
wDvsRzavzry9xBmmqRv293FTsB7w6WIGkhAi/21lfNe6taef9jMSH+pPe1ud
nH+57vvil/6tOOD/giGXIEyt8p6GcJgvc0qH5vj2MHSF/2XNQG6umcFrUWfQ
w/4o+vpNHsDTAnTA03AE3sE82vNN1/cm8ZCz/Cb6/G25JfjWesHH3+wdefet
y1/ClUadcdZ5Gd87W/9ueha+9e3QhBd8G3menfD5pzXJ/mgK+QlDAjAgADrZ
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
EWnTnaI192R0rcIMNZiHuMYiYS6kMEggjRgj20QVseb9iUdJsq8sglaa8aGx
STzISfrBZeRyOTMnX2SypevxjR8ufuH+FscJ+EDetZfimhBGZcP0viOHCOfW
AdDmMyOR7Xff8bBjCQFsGLWNVER7yUMXxtaNpnWZUl0MqBSUDgVPs6JKKstT
Xy06DG6NR7Py+glruWrCkZ4sFSCS3+o5059h/tsWOR80qHCfOjC6s6OWQboZ
Z09VjB6nDPoSJrssHbgtBUva4RKND86VlLFa0IkyVVA+TWliiNsG8tc0lxyW
35CSTp/0oe0rfeD6cLuUQ1So1eDaYe0qoKTlICGvtyFmCqanaEyyjQ5Qj+Ph
FBeXSoVujNxfJln6rsQkOk6coWdN0KA8CN2TGC5DtDcnFpuKQdTJVSFqCUro
mXYbwzdTHSQlR2AUwdsc60nRfCpt/XB4+NpFRPfB/aMkNjp0SXDVYM5NFNl5
VjDLNz5vlT/wlh9wy9Jbf+g0O11UEvYlJUuZOHz0tyxlwoNwbysr0yD8uKEF
Xf/8FekTS+hbvubxNOFrKCrkdUxjJpcDmQ7QgKSCdNSyAaTnpNlW/0Dm5yXZ
ipTRli5Xc/QIycJIQMLfhYmBkKdPgOK/DFQYh+J3fmNQ/O0tcgZ+XDSLWXbB
U3+E3KjPcvLFoPgvAFmjHeFzTTmvMNwQWd5v0MTweaYBb2KgD7pu/BHMGv2j
e89Fu50vZmLQ6ADkmlQP4HvJBLb5R2D/OCJ7Log8v6rJ7Lrzuv8lTSe/oXk9
+ALzeiQeLF/xfH2r4R0Rev5uDT13TEufNJ6YSXqITkfrzDQRPt8xLf3trTa3
f0NWmzvXsdp8thGsvS5f0mpzt2W1cTrNtcw2X9O4MhVpQMpF4dhilhD8Er/b
8iagL2yUcN1zGj0XIG71k6hBwQwNm/ob2RIY3IOr7W9gVIDuB75/ZzVaY1q4
BHza4eyWKy4y151dvyXBbJxRd8MttICl27yoNWHHGEq40pZBvovaaURWW6cO
RfsGGhRImAyfuUN1NN2JzUNwVmSWNtTV/UbjSuGK97IMsPWp88HvtIBmv3x2
rM53PXomCIC0z7o6ocetrbrV0WXjSIjLhaEx7ZkpiSdkPstW5URjZ4ytRrN0
4To6G4pXfD/djqIRK21AJNgJNt6EyT1pCSzIReF2U6Y9LQKZOUdJk/LFe3re
/9J2nAefY8cxTLlyeIcHUFu4p8/9RvDoizwrCTuJ7/0VYGbiBpSeQ7DmkO8F
sUR9gS7tS8DHzCkfkwvLZDMyTIwcQMkcgZlSOWRM0+MgXCoYcKsNXBIk64t8
2YaEfS4roiHgje5MUqJuvoL6cA/4+Opsn+kOSU7yL1EFeHdGTS6sCtNix1MJ
uqy1Jn+53FkchSD53ns3EXN75+gaHV5xdX6S1UTE6NBN2cb7LIDNKcWsIvam
+Uxdehg8VfGrpM4po5BuGVLS+vvNHSJXfNRNmrg8vhyamqRGnOYiiQRcSOow
SU1DKS878Yqc8skUSp9zodZj3i8PjbeQcY6JwSSNaxD9HnHNHKGKMzHKhCLJ
F5U7lPn5+gVEen6I1+H2zj+icaRHZPks48idvxfjCN/izjKyZ5P3hmk7jHmE
UvyuNY20gGrJWIQCicvWjwyzU4KLZMlETpiTIvRS6wWt3YVQY3ngnMui2UTE
swt/0yWmMJaSsUlaZnKzk1wSVoLriWy90YTmga9jePgtouGKHn4uGs7/fEU0
vBf0+wpo+O8E8v6SDtytdr7V3C+/Nrp6px9dvX/1df7toZBfwuFeUcjp15vX
Gk/wNSjkF0P9vGf45Zjjbwlj/Lv1DP9NY4z3QoyxbCX/D25OuWK5vHgrVPJX
QSJVnGCX6VzC64OUENXUq8Qc6T1QXVl9jBTBdMIJ+4tx+p62mMLZeeKZvQkl
5MwLjLdQMhhUH12R+Y7wAZoMZZcmP48BSlDOi5KFYpWGrfrIcKpPDqACNK19
90H8eMsF8YLAv7wh2aTbUbWSucbW5FIdHKZh/d8o8HdiIh5LrgaPCWXDZDzq
CSd5mK8P+XKEf0zHlhTGcZBLdwqzu/TixW0FJtaNNOsx3eviufe21FPb5JwU
pNom6ohNMaZRI76h4i4iHCsX2e1in0nZDhDsED/+POxYnC4D/Pg2QscEIt/t
uqdHIw/c8ZBKN3jOAm9so3aDADrweIgot/Mx1q8qfMXxtQdgcJ0zZR4OASPz
LKuKA1PkmEq9By7AgfejTFJBQ1cWyqOf8Pvcg9T4yCejiXevgSb6Ii6fiSXe
+8JY4s5vEEu8/w8EJcJCdGppOKCi8Her1hhRPEJrjeCdT5/j3HHe5CNXYy75
9VgkrDV8d4poJDzNif2a/wYg/5YAZI+P+VfBH9XJ/L+9s/8RvbMJS0T80Scp
R1LAeru1pHyhDIxWswiKW8yKd1LzrZPK6cMHjbQx/SDOeSD20SHFoPQCnWVF
0sBaqBMTHfJNTpnkmj6mjGks0UqI+9SpeDpItPQDnwgtVFuKxGNysyO7rjFH
1DxvJeIEPjEpGsrM4XKt1MKZU5dWXq/vXpttqMbQED7BDzfQxK+CMXp08Wpg
4vUD3vsUcvahisAZ19a97VN9UASltr4Eirg+AmGf6pvnHe55PfDwpeZ8bSqJ
Agz3W05MTXBuA+04AixQYighe4UJUkpJ9JvDGdYqupfcd62o1Kkkw6yOe7Na
zrN3bQuIpm5qaTD5tKPDBJpi9Ip16Z/wwever333JLblpaTr3r5GPJU0wrML
TYvlyl1imXOpeDGQ5HKOfwZJvfodnT7n0v67MRrqtai36T7L5xLi84QLrSmL
O6RhB6nM6OlrhVZJEoWmk6dt6Yo8Z/6I85FSNSahdI+0pJxQWr1y+nNs8anj
9RZ5+4DWh5rCq5dhphwLaqyQlpLORnG9uZ5eUI3HGic8bNVugvdBCaQMi4rv
Sf264KEbDc5rlXtHKBNWHSs++MkBNRGGfR3Tob0srnPJR65FbudaYHjn0ZgA
0Jfp5jOuxiv0vvaNYINir3fkCVf9IxQiPqn34LH1MsXBynXv5IpvL339M3uX
fzfTQxSFX2eUaXzruq9/Yu+48nfXrvzX7B1Xno2/T0hND+W5z1z5S6nuM2ke
l+4+n3fKICs3RJ8Y/IV7x6V7YHqf9nf/5c77Z3LaqGj8IBCNGV6qNHFrHdzI
9sr4QpKvFVffrBUCu1aUrAyw8r5swKuG/ab1Aub+OumSPQKpHvdZ9+pjZ+K/
L5kNXZ+Rsy2Ys6mA3iOw5B25yAxUTTwIuV9tuDEVJHiIM2WgROL1gf3L0WnF
FAheZHw8biBVf6nYVoa5nXe2XOQEp6SObWU0WXVvQME1KEIVB04T7CFpetls
9Lv8YiAaYW4mxiIe2jEkfyzSASx+VswaD7PutffLveaxXs04Tzol2gkRzxc8
fordNxqKL+t23yW2IfHTp/pYfzCHKGDOcpf/pnX6xFKJCa8xUbqxt3VozFnB
tYq6+hy391z0SKfhDcQaGCcwKimJWD464CNSrwMgUbkRphEQkNNjuHwmrOKB
6JXPDA79CjGHVpYIo8U0k7zM6qK6BF7z+aT5oCla0JOJGpMFgBqeTePNEg6i
fJvqn5IhRWZ3TS1ZqrQ6r8ykC1q0asO2Jt7QocdihHUusf+c5Kdk/WjcLAlZ
xLISUtbEWaOBxlHd/rsI+f9UZ652COdv1lnyN5Y6IH3qa7BcksP3t5XF987X
DbH/Yvt+nXa+bHbir57F9x5l7WbHmcvy9/4KWXzv/6pZfB987Sy+X9Kb8OF6
jcbdzSy1zPKs6as7nWE4AduNA7j5mspP37UZ0YG+XDiykRnbOVzfuFJUOPG2
72QsQnlNSK4va9Wkb3Cx1xW16tY2yzQg1gpRJl72kyM1737pSMl7nxMpqWqb
G8eavHzsnRd6y/WrOFdOx2fcmrxaxK6Xl2bYM7T64PNdJ5xN6Is6QGBbe+JO
RGXawzRS3lyjXgFAcRuz6uSEKG8jbFdUBVnjiGHsuMDgX3KmA7W6ZhHUJR11
MeA9Xjko/sLMlnUx4c9i3MeJ3ySO85DmWLGI5H9OO3ne58Lp1njgNEVVDcVh
JdZlqDWSMvOorkBLpZtszx/FloPDhB5aq8gEoVyhFZXE/OV5ZeO48gpzwyU/
wJ9xjSWbYbq7C/JhbqiejO0lKZoBeXRgxJaJOseknlgYNZyJteQk2sRAiguq
MtwawMB7JmNR+shqJlw/LSvFTxMIhqMgaTMuYHPmA+VX6nqJhEpZBNAZdrGo
6uWqLJYXCdXWwatKXFTspkkxx7LXt0UscYlhxOIqp1uUnpMHGxoyLwaSmE2n
ea5Mz6wt9XbCyyHOKMMJpxJs1+6RLaakhpMVaNRzaEE5hVtbVGa1AWrXG+SW
lCcB/mCvs1I+YIeXSJH5UVteuPKPU/NY/vvEVoyYzvLf7zqSIZeAeaZFduHx
K6gfnzGeeDvrZK7Id+12UKnaYfm9Xy2OqsHt8cD8nz2GX9aoxVdQP7qPfKl2
1DyGUvYovao6/fXGowYztNeMIraaLzKeXvXs2vPqUTu/4vqsa6c3s9snzSsS
e/g3nFc0s1ucfth29ZQqGQQZ63pjD7/u+fIZ/pCi//bniyP9EL4dXTG2l0p7
IWOPPIvw79XHs8/e1J89L7yG4s9erx0Z/ae2I/iF++Ka947CH1Fdf/tWoOx7
ObTj1Ec+WB1BFKNdyNtXBE/U7F/XlJyInIh3w7RBRRPoo335ZwctK1vipFbU
lTAqwekQGAbgMxsH49Nk8qgsyDMmoVBCApxpSKIQEFUvi/9YuZRVlBIBU+7X
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
FdIOOx1SM2BwyUMI5qHWwzi6DkwvOEq3rNPidwF1231rkmp3xtvezG6WjguA
MDvqN1BGQYdRGihMLnzH08mChRA58/Zo+ZQYc1xmOnvD8G1pAtGRtEsmS2x9
iJoyB5qLClItvhe8HYKT7TbYD9PubNHuSFE+sEdMILw7EZwiJe1aYyzyJwb3
e0YnTgZQNetkNOLNDY5+SHgSGzm9ISF/lDU5Z9ASvZFwBxQlU61MDCwnDYT1
rXX7jOEMuUygRSFiBiMqm2hFgmWADDqkDg7ky3KdfapP4l9BqMDWMxxNsObR
XUejosIO6BrJf4KDuUcpA2zzlMKh3tFCHGVs8gACwDX0wEDCWELDZBSQNMU5
AROE41nsdGFjnBFoUNBBiqk4AoKQcR+UcpQgsCnRM3KeA6GUvr1HtFg8oVIu
uMxILPb0H5iuRg4jNMouEgCVkgwKx+5zHuZrCuVzO4lazxChwes7debF7WRu
8JBvbe18pqRpPMfojMLf0cAU5Gg5JukbHgzo1lh3Rokl9+O2sRUWlH4P+dzK
TOgTZ6GS/yPYgXj90fl07FplnU1sMp2KpI1hT0YwnQdXh9cTmhKdIY4Kb8hv
fSmAgq8rDViLT7zmOADKIc0T4zixA5pwKWYKdjSwjVU4b+C8UgMw9+dEegNO
fA5Ch2KQykfIRy8Vg3wQfI1gkg2sLcQe0i5NyvHB/cmESVY8A0KYRnzrBKS4
AYeHDnsmJchP7cEuJzRUbHBmWKjnaKxFLKW8Wba5JDzdkVOZUMNg8r5l9Bit
Sqk7fFgDnTSDFcsalRW6v8NaVp2dL3ak46lwPq07hB2F4d7DFpnO6FWBnC3L
hwnPYJabuFY8N1euXw/OaEA8ixkIrk8YtU7IVwXqFVT1WHv514xWu2UB1ID8
sNm6ajvfMDsrhZxZSU9IYCYklbSSb25K1UjGtXr2zk6gmTxVdlOjNOknuUuM
exTemIIzPJUq8ktqSoRDDqUuvrXDPlkPvesoDSTaCa/o45eex1TSXfpY03s0
shzjn/FAZBYclppMIPh9RQfbm2eFr8lg2Gikg/I6QfwXMhjn572lUuUgi+2/
WJX759zS3MrKysLC8jxksMX1f06ptnvFfhJO/Rdizfxz6qh8vLm3NVfarJSm
/msQNumRqUz8//et0y+bj5ffa/Mrw4OttfF+uDj+Ulu4HF9fj9bPts8f4vrl
fqO/eDC3/hCubMUnmyPoysbL9nLnUs3u2kH169rSxUHj6Wav2zy5r7XG1WT1
cGM3Ke/ujXY6r63a3uPo6rJSajWe26XX+avlzae9nTY0ctNbqLbH+8fV+YXW
sBzvV+ZeRo350tH1Vre1075pfK3e79zsDS+fT4fVhfP5+fUva/fJ1evKYaO1
tTO38TCARna+rs9tLsalhYVm9b5+sH7y8lpeq309nT3auagedOe+h93h9e5z
5+VqbeX4bH5/uT26fEwOHua21xeft84e7qGR+avT+aX5/lJj9vikEi58v9x5
GN5Xvta/7n1tHR0/3q/VH7+vlveWVrvfj/a+lEtXZ19u1vsXYbK5tzl7vPa8
AY2Ew9NuPB493K+sHa4tfznZ3D1KTp4Wv66cP4dHL/ejf/7zdyfVwhVkLL+S
rADzCKBMiJIAL3NEwp2zSTUizA4JA+Tf01lslscQna5Ly4uz6GXPHKfUzl+j
3rwXisGUyd6BL7K4Cd5R9d21bl2pqHJ1MmUMJCKcDqO+84uwIStxZPVUq2La
pwCiCI+lBy3nBFzfwBbvZFmHqCez0DP4OY6Ig7zAMSl/b3ItmJC16kqlqpfJ
qn5MAtvatziSNW3xGJUx/S1yoEq4nLsWkE7t83TyHWOUkkz4zpNpD/axk2BJ
GiFbFqp1jjGjXUReB2NAmUp8k1ekWgp4o3VAheiSJtAdcZXoOK+uQBfz0mG5
o0buoL5A/5NLDLDd1Ect5c74lsmRbkX0dtWsPcd1wPuT4cpxAOIB7FKCLhD6
s+3nsMoDQjDpgEIu0f4EfYtfMG1KVwA3qPOFFCiKa7xxvNe62+60gzUv1ooX
ZpWz1UwGPSkA7KoxGei8fyicNtUetJIpNyxyOEQYxLODquMWflaGkTYxuU14
mxt6HCX1VENlDLLWwJreu6xmeiaNyENF1YRpLN3WwGqpF45b3bAuDYSDVAOW
hZXaEm6ohA+MCZWcyNOH/LQvZoJNFrk9UFZPnFMjZaNmN0mqkKigWCbEjrts
LYIJVIizgLwe5iSikyCwjw1GPM2ujF7AcRIPMExba4FrTPthPLjy4sm3QhYG
Js+Tzs7BiKhWT8Jib35loZg8hOp/7GfcVP4iv8KZ9KkIxJlv1OijpUnEoxlC
Ctp99BA+x2rG0DSmpFW2wTGyy8cDhNp0YJkweueFEr61ppN3gZUgAXkR2lWr
USK5qJpGRCxLOkhI3+LhseWoXmjEzWFfyn9pFaOWWjVlGJneWWBKD5AM0OF0
gAkrpVdFB3EoXUQuB70ZTZVyRtBYlTdgnwMXyTOkVUFCAtEcpah87Cz3MRgu
TbL9SC+3kuXdSh8Te2HPARoM7OjhazHLHDSjjh53KIR+ow1JsVJ4CrQESjys
UaKysYd4/0haYsRcN3p8+BDLRrSLKJ/E1CrZANB61dUJi1oNTkNBSWjuVc5w
E2XJBSJCFKVuWxn16Hr0vgJTY0MUAUY2XPE6+3Og5AMy71AIHamfk0E8GGoK
vFE4fms1Amd69zO7hU4bcajT7og6w3aE5BUP5PBJCJnB8OH2MWTdiGENZjh8
F6bvYjGMHfeMrxoSd3BEeZmiZ0nMSBvdb8GlZEgDbQMa97s6fXzmjWBwyely
Xf6+M5ZK3pILQI4e+bKtLdAOn2TjAvqLjv2Qc1Tc5YOHyPiBE5czoFLVEAN2
8l2AgB+WTr9b3JiJo0GjSCYj27RFyjjH3KGzbqER1sBDTQkQWIbGkfkh41QH
gvGmRoV8iW6yQVMJLHCOQuhL728sv4r6zDYhB2ZKfnYx1nfZ19zF3aThBNkh
bQS1THS9Wxu2tQ9Lfyr2hkj1fjC9CGKdAPsJZJEDKpN8Zs0df5I5M79idoEV
2pNdr+0PQNxs6gCyzmRO0puHNxYvrRRGpCSB9rK/aXj4ya2ZsxI45Qb9bkvv
bwxrwt5hcc6XUHHYY1YGg/IjI09tloDDXFoa0Gp8S707iYfKsOR4vUFsSn3L
xrzVjGCLduj8swHSwYme6GEMTEwc0SRBhLZa/nEHnyxqNv4j1rOfpXPodT66
eiMDBfnzM9lTcTtWClmLXWUQgLOK5FJlV1AdSjVz07K+UmhhOwQSb6r8b1J1
vCvV1mnMRs2AodkB4eaRy/SuQhlTe8fVTeOGK+gEuMInR9ZUWfrNz8xD/yip
bgWGTRA/qnN+padSpezKT2aLI7mNahUS8chA/fz7H0UU4Ywa7TTjLJUeptlU
F4rX96ez1WY/adfKyy8brzf7w4ujl71ovrd+PaqXo6WoUR0vPNQ3mlurxeeH
9cXmY1h5MnWm8dzocrhZqR5eLpw9Lyy0FneO+gfFtfvH28763kv/dqd8HEbJ
RnzSKZ10xqPRZqM5f/S8unjUKZpGorj18P2qEl4WB3v7m4ePGzvD20Z7by2K
2jtHN7sLc6XmWueqvv26cdEtlerP192X+tL2oYwlk1809R0Bri/qtbPb4bi4
vjG7vX9xsN3b3K5Ulp8W9o6Xzp4GtZXDzZ2n9aWj3a2r+OHpdum5vHu8/rq+
sWQ6dnDYfT6MO8fXSt2sdOr73e2zo/pe47K1sbVRrZWTlfXFTmk8Vz1bPz2p
vMTttevi/Wh+tRjefDeN7F0dvhwfjE8eX4cXzfjseH1t9/lgY6m4Umw/bz1e
3TzdRlFjYzYcLLVPF79fzJ/PPd4MVlZkLLh8Wzuth/rZ1mz39awVb7wcrjUa
Z0vh3sX+zX77/n5r7/jiSN1aq7X51tX+2vzwZf6ofH+7UaqvmW4sx53e6uZF
ab572d9IeluD5/XnjdX6Tf+qWdk/3Ok2njZ73dtq9XntptEc7BSPz57ur2/P
vg9OtkwjWwcn++XR7N7VYm3rpNNZOC29bC50ivXTZTVB6/utxdXnm4Odtf5O
9aG/Ovv6/XWrN1vevzpfbDyaRu7nmuurByejZKtc2qov71+1d+fq/dPTzYvv
q5Vid24FWl7bPj06PXo8vr14qu2dxWvtzd2Ls1vTyP5e5aTeu9grt++bnevL
sHFw+1BuRPe39f2V3srieNjfvNha6azvL3aP5zdP+t/XlncPFs6/h5sd08hi
tTU/nH1ceVns9osv/X65e/RabNaPn5ePjxo310tHW92wON9Y+b46WivvnA9P
ZVHSyWtT3xFIp9vsHW0+bew3S6XK42pt4+K2eLK3dhNeHT4tLW31FheXK2dz
g7CxO/y+V9nZHDaqx9dKXHWtubk82Ztt7rw8zzUv9kbzzXbx9fr5ojg6Ozxq
9kuji2StGr1W9x5Pqo8vlzeD9lnpdWnlcm5j+LxvGnm6Gc8tPr8u79VXFh/a
G61+vF27Olrvbm2eJ9sHl0+9nZ3Vyuhk97U5PN+5bJ8NVsaz3avxrt5yKB3q
z+v727ul7eXKwcP85fixu3e70V96uJk/eLgaRWvz17Xr+e/1jdW1zsvN8ly7
fxAfnjYXatYaba51Rt/XN8+ObheT6qBTqlVqpb2rzvPByfz2ymB5d2tfKUK3
8e1Z9Sys7S0Pz2YXDqvh7OL89bxppNIY3T8fPFaOTiqz5/vlzfmbl8rxeXc3
vDgant8uFU8PGyvFUtw6fy5t7x73149WlpsnatfIYDypg1N1FBDx4U178yDc
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
DCD8C/VnUa1W7EEyF1oifiNDevP789HC7v51stcqVQ62oi+D6832Qn3ncKGy
sHbW/f6yuFHaauwsNKPFy+On5gsm4tV3S6eV/uPaSn+cPHerm9vP5UZ8sXd8
mWzXTjbmWudL86vl9sjWq3+BVvgfyoZiBUVQdurAMh5Uc6jMETTcSPVszktA
zhtUElDisNwwDRFG0v8Wn417ZD3emw+fNdhew68fPWupQ5IvCzKsQFp4FX6/
rm/sPW50StXvK1uVlVK0uFs7PrhstxtLo92DbjJSennt9Qvmxh5+iVZeHrc2
epfV0nU7Prze+H5e78el83gvuXlZmj+be10uJ6v7raWds+0n6qKfbsh8P1cs
OF4IEQ3vEAu2GyIrGmyx8Cs8Xm/RL8lAs7xL0k/zTHY0K7MyEjrMjlzja9Z2
hzl3FR47dZYiXTHC19PfN9ZfcWP9gjvLubWmsVUlFH9FXz66Mf/Q1vRuzl90
937k9nVn7veLy/PNl6vT2WZ0GZ2d7z+sNzbOli/3xmdfvhzvVC/uGyflueHT
5Wx3ud1OBvX7593X1fh4uEOf3ahsvVbW2rOHpydbF4e9g42tq9P65vxzXKoe
zN88vtauSt8PRq/lwbiytvqlklyUamG5vDJbXrzZPuxy35vnyf7J08LW1sbR
8n7l/Gb2+Wz1sLs6rr2sbnz/urq6dHZ8OSi3vy++zl6fX2+ORp0vZ0tfjmqX
K/2tQTuhRpK5m8bV9uxmt9y4WHqOSou9Ly8Ls9dz/eeNnaTxFD6dVdYW9lYe
Ly82xvfVaH518Li7f7rWnR/GtY2LETUyGEWjtcOjuL4bfllairfme5ePK6PV
SvV+ttapbTaf7592muXq9/Amumq/vGwvNA9XenM7O6vPX4+/n55RI8fNZnux
eXbZXj9NFrovm+3LpHF2/BI1hp3Gw/zVl9O/daAcR4vOkULoA8vuZ55oC6Hf
znhqMF+FxdAJJrsFSPHjHwg58dF0XXjpLpX7OCmjEFExPCqeBqUFFwQCZJDT
ysbJYE4V+NViKLFSk3imPpjq4CA0g6+p3R52eMyCt2UCMIHwBGHQEjtZBEx5
FxUMjeEQu9qHfJgEV+YFKUg0FPvqwsIsIKNBDAohcPOjUKkUPd8F/KviS90k
ysSX5haXlgNrsBRe/P1wd3d96XF9vVzfFyDq7fLV42h54eXksDy7vV79vl3d
vZ/fON1cWx+dlw83rl+ONsrjtebRxVr58BAa2Z9d3Ls8n1s8bfdeK9u9xdOn
w8XzjfPXo9nTUvWishTOr20eby7Onrd7veOr1kNt8/9n702320ayNdH/eAou
51qddhUpa/CQzr6n+8oabMnWYFGDpcxaFkiCJCwSYAKgKDrLP/vJ7ovd2FPE
DgCUJaerOuuk1+rTlRaBQAw79ry/ffrs3afz1c7p1uz1sLuPauXHrdn+5s5s
7+P6zcHmyfKZ+fveR/j31rL928f11b3jd7O9wfnm6bt3m5sbxUH7dLQfnexi
RV13+eg389+bB6frK3ufelv7V6OTaFzMjjaHB73t3d/C49HT8/cvt6OrvdX9
8cqRWfvLnY8OdBtDNwi8vbW9vn6wsf7up3V4ZmPwxvz31jp4yv+uPOWPazzl
MEZtLc09POU4RqmKRnvKH7On/PEtnnIYo+Qtv6+nHANIJW/541pP+ePFnnKM
qVlv+d/vWCmzswn8XOgPxtA0uP7E0Om7l8n59pvl6Pz1/O/D0/7q5tOfpvnH
tRej4dunn5LO499evFp7+upl7/H7/Ky/gQ762evp24P2Rftk/Or5SueiyA66
N8uTYhS96ExWr96MnrwetY+P+51iMn31NE3a4Vo+O9ofFm+Kk/nT/dcvYIyz
x9tvT+M3Z/30sL12NUu3Jhsr7397c/5s9Dy6To83ivbfr47fHbWzjejJdWd/
km2sXxzdfHr2aSXZijYGGNnb37ta+2l+fHR981M8vJicHkxP/r4z/HvvoDiN
Hkc3T3fWD89vRu/y66I/zE8ufus+35lvdOfPV89eJ0evRycwRj9ZM2S03H66
+nz57+ejfG3n+tlwLX25frjyIn6x/OzkY3xyvP96bbB8s3f299Mn07c3g3n3
qngy23yyN5pfwxgfk/Dd84u1/OjZVv5+L+2ud96/3lnfHc7e9IqTx/23g97s
7dPr4sawqu8xwn99jBDlqi5ucL0C7smiMbjmsemvYNEwiMemv4ZFI0SiYtNf
xaKRVsu9Ee7LomGQL5Q7fplFo7RbVOh4VxaNrLk+oHl3Fg2DMJv+ehaNjKQU
0Lw3i4ZBKjR4XxaNrNWw6T/EopG3vn7xx1g0JtBM/yCLhkFO/p0s2oZ5/+0B
ZWZ0+RTziP3vcY8b5N+xERvmoQfNxgPqzvDgH7cYShDKCjMOAi6wJVz+OVkV
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
Xr7tbk2K06viSfukdxAdv0z2R+mn87N387NtQ1mbw7edtV4enV48PdgaZWcf
hwfH73vH3fH+aftkNzxaGZ3/GoRXw1lvdfKsN7543TMn/P7T6dv2+GZ68tHc
rtPd0+7mUbi/ffpb+Gk3fre6/fbirLfV+bh1c/pxdzXaOlneOxv+Gtycn748
7YyH7bNkONp7NWkfnR5dXbyefDo63i96x9vH7U/Dq9Ot/baZ/drp2exm/9XK
6fH4pyfh6dH89NXycsfQycubo1fbV9HH4Ua48vL67fvT1f2t3c29V7srnZGR
pp/243enP306PeuddTd7z96Nb46Oxi9eda5uTo4/7a6crr3sd34N3p/uHZ32
Xnc2z9culndvDk5WDvdWd+ftleH4aHU42VstDqNktBYlvXenr09v3p7tn52c
HD09Onmydn4ym52sDTd/Dc4/7u+cfzravXi9vXV+spIcvN7eOX0/OjxPXr4L
3x9tnbR3FF28fGFPX24C04m5r2sv8/P3VzXc6emwc3aCt+D4/dXgndyXLfvO
4Hj8a7BdGHr0qSs5nYdEo2nv9dGs+ymFe52HZ6fT3sbTcWf1p2t3O1++eGuY
UoWHfeqd7f6GXKlyp3bHnbXd4vz90Sf47Wy+OwE+a/jJ2mls7oOZ+YvZ+fvt
lYv2bo/mZdafLL9Z2pvtp6d77yZPh6c3O8vjjfzF29HBSW+7uNp8H66vfIiO
fw2uD97/9nzz4FVWbL55/fy3J9eHqzcnv631X69+PFq/+C1JO+nyWe/wcC3a
W9t//fTdyceznybhsw/vJrPeztnVm+dZ69dg+uHp6mS6tTw6fDl5vvvkZHX2
ZPRisNMZ/BRfJfn4bPw+On+6/WwWvzr+aVL0p1vnrwbjUbq+23vxdifav95c
M3fn7dnqcLX3aeUwWY02k878evBy+WQQRssv04uXT/rPXvTfnH386eLF7Pp4
5+PVytuL3f2Vw+7b5x8+Hf/0NjMy9oVhSofzT8fP371Ir696K3nryWy49fw4
S16dfNruPh0Pzk6SD4P8YJIfPh3v7Iw+pltb163t3w7OVo/m++fT0cHFaPnd
r8FPW0my+fr0w/Xhp+z16CTMOq8GT877/UExu3o37L15vtraPbg5f/fFmCM4
ibRz2rnH/v0xx79gAO97/O7PFL/7xrE7HfW5LXann/vq2N29wErvHqhrLA7U
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
/6uHXz28ufPnu8+f7u7d/uH2jZ1vdl5vpFshF56WsNc1gcYCzOVAQiwfbSOR
vm4/GnkvwZ+JC4UCaCCUR/cxbhQUBCqB79ID5apxtU7QBjeu3Rg8Ife4eCHH
3L3BrxEFPyHSnaIgzYwK3ool5JnYGhDE8/7EhBB+YpgOEDq5rvPSbMjIGCyp
SU4lWj4KRmQh2f1EMW0N9mpRGKYLzIR0YUuuHShbo/7mLDmXiMizsm9IOgeH
8oZC6WvaTp7dEWxoKa1cRZVb/Ak90uIhX7uUM5xAbBMeB26JLkruMyJSNco2
JVnJjlS8ev328b3Blf+6MkC+9Sw4GSdIhYcRUKvwna/ubhcqO9trZedzZ9F/
hd32f+hz738cHR6unn//9qc7i2+nX02+qm+c3fju6K+nq29uHZy8nj0/35n9
6eTFxwfT6Y900//2Pdz3bz578v33z57/+ODh9ptvb3936/arF9cv2pvCudwm
RRkJ5pCTXAhm52xgKjQ72bjbvq/+RGWIgvgH54WArDC4PFdKJiCZUBHkeavg
tlyeKPiIhclx33dZwEq64NVVXqYowBCwIla09T6LXF/sDIVpc9lQUkOOdyaC
fyZXpYjP6A+IkO9F71bQnaZLIgHV/hFSTKYtEqsDjSun1Xo3SbX93+8sJe7h
PY6Y9J1Lv4NX5WWfTqc+8d/oGGqpWCnepqvdnDUNKt8UXEOuSGs8O4xbCNEo
5dja9Q96t6oS1il+LLngwu2oKlPKRYsOZjhvDbEQIw15Hrv9u7TZb2hyrfd9
zY55vXf35fabl0+ff7d7++bbB3de3X7w/Vev//zgzsNHT16/erN9/e7um+sv
3l7z7hKXn33GqMFLvzRZ/K/Ejnq5/lX+RdFDz8ywixzydc74Wke83wnPHN3P
ON+/0PH+BU53Po6Lne2LHO1eJzs62J/+krrU/6LWcVQqQDc3ZuJHHG7rDxFy
LO7i+GCWVeivTh2EXUd3aHCPavFXDFJAsX0bjfzdYTwk5Nm9JgH5eBodLR24
BDquTxZEaUTB/m938ev+Z9RKjBkZeU6WLkDp6Xlp8OaiUscj2PQUTIAZeqhx
UhEuvbeQUtDGmolfE5H8nx5QVP0yintzsMEkcUvGuAszHHfHutBWvwf4S+M9
Q99/+pdLBFTq9jKRFBPzLX2GpYSQl9T3M6hBqQWejLDC7OuuzrRtCio207w6
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
<t>The authors would also like to thank the GNAP Working Group design
team (<contact fullname="Kathleen Moriarty"/>, <contact fullname="Dick Har
dt"/>, <contact
fullname="Mike Jones"/>, and the authors), who
incorporated elements from the XAuth and XYZ proposals to create the
first draft version of this document.</t>
<t>In addition, the authors would like to thank <contact fullname="Aaron
Parecki"/> and <contact fullname="Mike Jones"/> for insights into how to
integrate identity and authentication systems into the core
protocol. Both <contact fullname="Justin Richer"/> and
<contact fullname="Dick Hardt"/> developed the use cases, diagrams, and
insights provided in the XYZ and XAuth proposals that have been
incorporated here. The authors would like to especially thank <contact
fullname="Mike Varley"/> and the team at SecureKey for feedback and
development of early versions of the XYZ protocol that fed into this
standards work.</t>
<t>Finally, the authors want to acknowledge the immense contributions of
<contact fullname="Aaron Parecki"/> to the content of this document. We
thank him for his insight, input, and hard work, without which GNAP
would not have grown to what it is.</t>
</section>
</back>
</rfc> </rfc>
 End of changes. 1108 change blocks. 
11574 lines changed or deleted 8155 lines changed or added

This html diff was produced by rfcdiff 1.48.