rfc9200xml2.original.xml | rfc9200.xml | |||
---|---|---|---|---|
<?xml version="1.0" encoding="utf-8"?> | <?xml version="1.0" encoding="UTF-8"?> | |||
<!-- This template is for creating an Internet Draft using xml2rfc, | <!DOCTYPE rfc [ | |||
which is available here: http://xml.resource.org. --> | <!ENTITY nbsp " "> | |||
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [ | <!ENTITY zwsp "​"> | |||
<!-- One method to get references from the online citation libraries. | <!ENTITY nbhy "‑"> | |||
There has to be one entity for each item to be referenced. | <!ENTITY wj "⁠"> | |||
An alternate method (rfc include) is described in the references. --> | ||||
<!ENTITY RFC2119 SYSTEM | ||||
"http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"> | ||||
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.3986.xml"> | ||||
<!ENTITY RFC4949 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.4949.xml"> | ||||
<!ENTITY RFC6347 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.6347.xml"> | ||||
<!ENTITY RFC6690 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.6690.xml"> | ||||
<!ENTITY RFC6749 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.6749.xml"> | ||||
<!ENTITY RFC6750 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.6750.xml"> | ||||
<!ENTITY RFC6819 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.6819.xml"> | ||||
<!ENTITY RFC6838 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.6838.xml"> | ||||
<!ENTITY RFC6920 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.6920.xml"> | ||||
<!ENTITY RFC7009 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7009.xml"> | ||||
<!ENTITY RFC8949 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8949.xml"> | ||||
<!ENTITY RFC7228 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7228.xml"> | ||||
<!ENTITY RFC7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7231.xml"> | ||||
<!ENTITY RFC7252 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7252.xml"> | ||||
<!ENTITY RFC7519 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7519.xml"> | ||||
<!ENTITY RFC7521 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7521.xml"> | ||||
<!ENTITY RFC7540 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7540.xml"> | ||||
<!ENTITY RFC7591 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7591.xml"> | ||||
<!ENTITY RFC7641 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7641.xml"> | ||||
<!ENTITY RFC7662 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7662.xml"> | ||||
<!ENTITY RFC7744 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7744.xml"> | ||||
<!ENTITY RFC7959 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.7959.xml"> | ||||
<!ENTITY RFC8126 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8126.xml"> | ||||
<!ENTITY RFC8152 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8152.xml"> | ||||
<!ENTITY RFC8174 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8174.xml"> | ||||
<!ENTITY RFC8252 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8252.xml"> | ||||
<!ENTITY RFC8259 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8259.xml"> | ||||
<!ENTITY RFC8392 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8392.xml"> | ||||
<!ENTITY RFC8414 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8414.xml"> | ||||
<!ENTITY RFC8446 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8446.xml"> | ||||
<!ENTITY RFC8516 SYSTEM | ||||
"http://xml.resource.org/public/rfc/bibxml/reference.RFC.8516.xml"> | ||||
<!ENTITY RFC8613 SYSTEM | ||||
"http://xml.resource.org/public/rfc/bibxml/reference.RFC.8613.xml"> | ||||
<!ENTITY RFC8628 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8628.xml"> | ||||
<!ENTITY RFC8693 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC | ||||
.8693.xml"> | ||||
<!ENTITY RFC8747 SYSTEM | ||||
"http://xml.resource.org/public/rfc/bibxml/reference.RFC.8747.xml"> | ||||
<!ENTITY I-D.ietf-ace-oauth-params SYSTEM "http://xml.resource.org/public/rfc/bi | ||||
bxml3/reference.I-D.ietf-ace-oauth-params.xml"> | ||||
<!ENTITY I-D.erdtman-ace-rpcc SYSTEM "http://xml.resource.org/public/rfc/bibxml3 | ||||
/reference.I-D.erdtman-ace-rpcc.xml"> | ||||
<!ENTITY I-D.ietf-tls-dtls13 SYSTEM "http://xml.resource.org/public/rfc/bibxml3/ | ||||
reference.I-D.ietf-tls-dtls13.xml"> | ||||
<!ENTITY I-D.ietf-quic-transport SYSTEM "http://xml.resource.org/public/rfc/bibx | ||||
ml3/reference.I-D.ietf-quic-transport.xml"> | ||||
<!ENTITY I-D.ietf-ace-dtls-authorize SYSTEM "http://xml.resource.org/public/rfc/ | ||||
bibxml3/reference.I-D.ietf-ace-dtls-authorize.xml"> | ||||
<!ENTITY I-D.ietf-ace-oscore-profile SYSTEM "http://xml.resource.org/public/rfc/ | ||||
bibxml3/reference.I-D.ietf-ace-oscore-profile.xml"> | ||||
]> | ]> | |||
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?> | <rfc xmlns:xi="http://www.w3.org/2001/XInclude" docName="draft-ietf-ace-oauth-au | |||
<!-- used by XSLT processors --> | thz-45" number="9200" ipr="trust200902" obsoletes="" updates="" submissionType=" | |||
<!-- For a complete list and description of processing instructions (PIs), | IETF" category="std" consensus="true" xml:lang="en" tocInclude="true" tocDepth=" | |||
please see http://xml.resource.org/authoring/README.html. --> | 4" symRefs="true" sortRefs="true" version="3"> | |||
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds | <!-- xml2rfc v2v3 conversion 3.9.1 --> | |||
might want to use. | ||||
(Here they are set differently than their defaults in xml2rfc v1.32) --> | ||||
<?rfc strict="yes" ?> | ||||
<!-- give errors regarding ID-nits and DTD validation --> | ||||
<!-- control the table of contents (ToC) --> | ||||
<?rfc toc="yes"?> | ||||
<!-- generate a ToC --> | ||||
<?rfc tocdepth="4"?> | ||||
<!-- the number of levels of subsections in ToC. default: 3 --> | ||||
<!-- control references --> | ||||
<?rfc symrefs="yes"?> | ||||
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] --> | ||||
<?rfc sortrefs="yes" ?> | ||||
<!-- sort the reference entries alphabetically --> | ||||
<!-- control vertical white space | ||||
(using these PIs as follows is recommended by the RFC Editor) --> | ||||
<?rfc compact="yes" ?> | ||||
<!-- do not start each main section on a new page --> | ||||
<?rfc subcompact="no" ?> | ||||
<!-- keep one blank line between list items --> | ||||
<!-- end of list of popular I-D processing instructions --> | ||||
<rfc category="std" docName="draft-ietf-ace-oauth-authz-43" ipr="trust200902"> | ||||
<!-- category values: std, bcp, info, exp, and historic | ||||
ipr values: full3667, noModification3667, noDerivatives3667 | ||||
you can add the attributes updates="NNNN" and obsoletes="NNNN" | ||||
they will automatically be output with "(if approved)" --> | ||||
<!-- ***** FRONT MATTER ***** --> | ||||
<front> | <front> | |||
<!-- The abbreviated title is used in the page header - it is only necessary | <title abbrev="ACE-OAuth">Authentication and Authorization for Constrained Envir | |||
if the | onments Using the OAuth 2.0 Framework (ACE-OAuth)</title> | |||
full title is longer than 39 characters --> | <seriesInfo name="RFC" value="9200"/> | |||
<title abbrev="ACE-OAuth">Authentication and Authorization for Constrained Envir | ||||
onments (ACE) using the OAuth 2.0 Framework (ACE-OAuth)</title> | ||||
<!-- add 'role="editor"' below for the editors if appropriate --> | ||||
<!-- Another author who claims to be an editor --> | ||||
<author fullname="Ludwig Seitz" initials="L." surname="Seitz"> | <author fullname="Ludwig Seitz" initials="L." surname="Seitz"> | |||
<organization>Combitech</organization> | <organization>Combitech</organization> | |||
<address> | <address> | |||
<postal> | <postal> | |||
<street>Djäknegatan 31</street> | <street>Djäknegatan 31</street> | |||
<code>211 35</code> <city>Malmö</city> | <code>211 35</code> | |||
<city>Malmö</city> | ||||
<country>Sweden</country> | <country>Sweden</country> | |||
</postal> | </postal> | |||
<email>ludwig.seitz@combitech.com</email> | <email>ludwig.seitz@combitech.com</email> | |||
<!-- uri and facsimile elements may also be added --> | ||||
</address> | </address> | |||
</author> | </author> | |||
<author fullname="Göran Selander" initials="G." surname="Selander"> | ||||
<author fullname="Goeran Selander" initials="G." surname="Selander"> | ||||
<organization>Ericsson</organization> | <organization>Ericsson</organization> | |||
<address> | <address> | |||
<postal> | <postal> | |||
<street>Faroegatan 6</street> | <code>164 80</code> | |||
<code>164 80</code> <city>Kista</city> | <city>Kista</city> | |||
<country>Sweden</country> | <country>Sweden</country> | |||
</postal> | </postal> | |||
<email>goran.selander@ericsson.com</email> | <email>goran.selander@ericsson.com</email> | |||
<!-- uri and facsimile elements may also be added --> | ||||
</address> | </address> | |||
</author> | </author> | |||
<author fullname="Erik Wahlstroem" initials="E." surname="Wahlstroem"> | <author fullname="Erik Wahlstroem" initials="E." surname="Wahlstroem"> | |||
<organization/> | <organization/> | |||
<address> | <address> | |||
<postal> | <postal> | |||
<street></street> | <street/> | |||
<code></code> <city></city> | <code/> | |||
<city/> | ||||
<country>Sweden</country> | <country>Sweden</country> | |||
</postal> | </postal> | |||
<email>erik@wahlstromstekniska.se</email> | <email>erik@wahlstromstekniska.se</email> | |||
</address> | </address> | |||
</author> | </author> | |||
<author fullname="Samuel Erdtman" initials="S." surname="Erdtman"> | <author fullname="Samuel Erdtman" initials="S." surname="Erdtman"> | |||
<organization>Spotify AB</organization> | <organization>Spotify AB</organization> | |||
<address> | <address> | |||
<postal> | <postal> | |||
<street>Birger Jarlsgatan 61, 4tr</street> | <street>Birger Jarlsgatan 61, 4tr</street> | |||
<code>113 56</code> <city>Stockholm</city> | <code>113 56</code> | |||
<city>Stockholm</city> | ||||
<country>Sweden</country> | <country>Sweden</country> | |||
</postal> | </postal> | |||
<email>erdtman@spotify.com</email> | <email>erdtman@spotify.com</email> | |||
<!-- uri and facsimile elements may also be added --> | ||||
</address> | </address> | |||
</author> | </author> | |||
<author fullname="Hannes Tschofenig" initials="H." surname="Tschofenig"> | <author fullname="Hannes Tschofenig" initials="H." surname="Tschofenig"> | |||
<organization>Arm Ltd.</organization> | <organization>Arm Ltd.</organization> | |||
<address> | <address> | |||
<postal> | <postal> | |||
<street></street> | <street/> | |||
<code>6067</code> <city>Absam</city> | <code>6067</code> | |||
<city>Absam</city> | ||||
<country>Austria</country> | <country>Austria</country> | |||
</postal> | </postal> | |||
<email>Hannes.Tschofenig@arm.com</email> | <email>Hannes.Tschofenig@arm.com</email> | |||
<!-- uri and facsimile elements may also be added --> | ||||
</address> | </address> | |||
</author> | </author> | |||
<date year="2021" /> | <date year="2022" month="August"/> | |||
<!-- If the month and year are both specified and are the current ones, xml2 | ||||
rfc will fill | ||||
in the current day for you. If only the current year is specified, xml2 | ||||
rfc will fill | ||||
in the current day and month for you. If the year is not the current one | ||||
, it is necessary to specify at least a month (xml2rfc assumes day="1" if not sp | ||||
ecified for the purpose of calculating the expiry date). With drafts it is norm | ||||
ally sufficient to specify just the year. --> | ||||
<!-- Meta-data Declarations --> | ||||
<area>Security</area> | <area>Security</area> | |||
<workgroup>ACE</workgroup> | ||||
<workgroup>ACE Working Group</workgroup> | <keyword>CoAP</keyword> | |||
<keyword>OAuth 2.0</keyword> | ||||
<!-- WG name at the upperleft corner of the doc, | <keyword>Access Control</keyword> | |||
IETF is fine for individual submissions. | <keyword>Authorization</keyword> | |||
If this element is not present, the default is "Network Working Group", | <keyword>Internet of Things</keyword> | |||
which is used by the RFC Editor as a nod to the history of the IETF. -- | ||||
> | ||||
<keyword>CoAP, OAuth 2.0, Access Control, Authorization, Internet of Things< | ||||
/keyword> | ||||
<!-- Keywords will be incorporated into HTML output | ||||
files in a meta tag but they have no effect on text or nroff | ||||
output. If you submit your draft to the RFC Editor, the | ||||
keywords will be used for the search engine. --> | ||||
<abstract> | <abstract> | |||
<t>This specification defines a framework for authentication and | <t>This specification defines a framework for authentication and | |||
authorization in Internet of Things (IoT) environments called ACE-OAuth. | authorization in Internet of Things (IoT) environments called ACE&nbhy;OAu th. | |||
The framework is based on a set of building blocks including OAuth 2.0 | The framework is based on a set of building blocks including OAuth 2.0 | |||
and the Constrained Application Protocol (CoAP), thus transforming a | and the Constrained Application Protocol (CoAP), thus transforming a | |||
well-known and widely used authorization solution into a form suitable | well-known and widely used authorization solution into a form suitable | |||
for IoT devices. Existing specifications are used where possible, but | for IoT devices. Existing specifications are used where possible, but | |||
extensions are added and profiles are defined to better serve the IoT use | extensions are added and profiles are defined to better serve the IoT use | |||
cases. | cases. | |||
</t> | </t> | |||
</abstract> | </abstract> | |||
</front> | </front> | |||
<middle> | ||||
<middle> | <section anchor="intro" numbered="true" toc="default"> | |||
<name>Introduction</name> | ||||
<!-- ***************************************************** --> | <t>Authorization is the process for granting approval to an entity to | |||
access a generic resource <xref target="RFC4949" format="default"/>. The auth | ||||
<section anchor="intro" title="Introduction"> | orization | |||
task itself can best be described as granting access to a requesting client f | ||||
<t>Authorization is the process for granting approval to an entity to | or | |||
access a generic resource <xref target="RFC4949"/>. The authorization task | a resource hosted on a device, i.e., the resource server (RS). This exchange | |||
itself can best be described as granting access to a requesting client, for | is | |||
a resource hosted on a device, the resource server (RS). This exchange is | mediated by one or multiple authorization servers (ASes). Managing | |||
mediated by one or multiple authorization servers (AS). Managing | ||||
authorization for a large number of devices and users can be a complex task. | authorization for a large number of devices and users can be a complex task. | |||
</t> | </t> | |||
<t>While prior work on authorization solutions for the Web and for the mob | ||||
<t>While prior work on authorization solutions for the Web and for the mobile | ile | |||
environment also applies to the Internet of Things (IoT) environment, many | environment also applies to the Internet of Things (IoT) environment, many | |||
IoT devices are constrained, for example, in terms of processing | IoT devices are constrained, for example, in terms of processing | |||
capabilities, available memory, etc. For such devices the Constrained | capabilities, available memory, etc. For such devices, the Constrained | |||
Application Protocol (CoAP) <xref target="RFC7252"/> can alleviate some | Application Protocol (CoAP) <xref target="RFC7252" format="default"/> can all | |||
eviate some | ||||
resource concerns when used instead of HTTP to implement the communication | resource concerns when used instead of HTTP to implement the communication | |||
flows of this specification.</t> | flows of this specification.</t> | |||
<t><xref target="constraints" format="default"/> gives an overview of the | ||||
<t><xref target="constraints"/> gives an overview of the constraints | constraints | |||
considered in this design, and a more detailed treatment of constraints can | considered in this design, and a more detailed treatment of constraints can | |||
be found in <xref target="RFC7228"/>. This design aims to accommodate | be found in <xref target="RFC7228" format="default"/>. This design aims to a | |||
different IoT deployments and thus a continuous range of device and network | ccommodate | |||
capabilities. Taking energy consumption as an example: At one end there are | different IoT deployments as well as a continuous range of device and network | |||
energy-harvesting or battery powered devices which have a tight power | capabilities. Taking energy consumption as an example, at one end, there are | |||
budget, on the other end there are mains-powered devices, and all levels in | energy-harvesting or battery-powered devices that have a tight power | |||
budget; on the other end, there are mains-powered devices; and all levels exi | ||||
st in | ||||
between.</t> | between.</t> | |||
<t>Hence, IoT devices may be very different in terms of available processi | ||||
<t>Hence, IoT devices may be very different in terms of available processing | ng | |||
and message exchange capabilities and there is a need to support many | and message exchange capabilities, and there is a need to support many | |||
different authorization use cases <xref target="RFC7744"/>.</t> | different authorization use cases <xref target="RFC7744" format="default"/> | |||
.</t> | ||||
<t>This specification describes a framework for authentication and authorizat | <t>This specification describes a framework for Authentication and Authori | |||
ion | zation | |||
in constrained environments (ACE) built on re-use of OAuth 2.0 | for Constrained Environments (ACE) built on reuse of OAuth 2.0 | |||
<xref target="RFC6749"/>, thereby extending authorization to Internet of Thin | <xref target="RFC6749" format="default"/>, thereby extending authorization to | |||
gs | Internet of Things | |||
devices. This specification contains the necessary building blocks | devices. This specification contains the necessary building blocks | |||
for adjusting OAuth 2.0 to IoT environments.</t> | for adjusting OAuth 2.0 to IoT environments.</t> | |||
<t>Profiles of this framework are available in separate specifications, su | ||||
<t>Profiles of this framework are available in separate specifications, such | ch as | |||
as | <xref target="RFC9202" format="default"/> or <xref target="RFC9203" format="d | |||
<xref target="I-D.ietf-ace-dtls-authorize"/> or <xref target="I-D.ietf-ace-os | efault"/>. | |||
core-profile"/>. | ||||
Such profiles may specify the use of the framework for a specific secu rity protocol | Such profiles may specify the use of the framework for a specific secu rity protocol | |||
and the underlying transports for use in a specific deployment environ ment to improve interoperability. | and the underlying transports for use in a specific deployment environ ment to improve interoperability. | |||
Implementations may claim conformance with a specific profile, whereby | Implementations may claim conformance with a specific profile, whereby | |||
implementations utilizing the same profile interoperate, while | implementations utilizing the same profile interoperate, while | |||
implementations of different profiles are not expected to be interoperable. | implementations of different profiles are not expected to be interoperable. | |||
More powerful devices, such as mobile phones and tablets, may implement multi ple | More powerful devices, such as mobile phones and tablets, may implement multi ple | |||
profiles and will therefore be able to interact with a wider range of constra ined devices. | profiles and will therefore be able to interact with a wider range of constra ined devices. | |||
Requirements on profiles are described at contextually | Requirements on profiles are described at contextually | |||
appropriate places throughout this specification, and also summarized in | appropriate places throughout this specification and also summarized in | |||
<xref target="app:profileRequirements"/>. | <xref target="app_profileRequirements" format="default"/>. | |||
</t> | </t> | |||
</section> | ||||
</section> | ||||
<!-- ***************************************************** --> | ||||
<section anchor="terminology" title="Terminology"> | ||||
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL | ||||
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | ||||
"OPTIONAL" in this document are to be interpreted as described in BCP 14 <xref | ||||
target="RFC2119"/> <xref target="RFC8174"/> when, and only when, they appear in | ||||
all capitals, as shown here.</t> | ||||
<t>Certain security-related terms such as "authentication", | <section anchor="terminology" numbered="true" toc="default"> | |||
<name>Terminology</name> | ||||
<t>The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14 | ||||
>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL | ||||
NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECO | ||||
MMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and | ||||
"<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as described in | ||||
BCP 14 <xref target="RFC2119" format="default"/> <xref target="RFC8174" fo | ||||
rmat="default"/> when, and only when, they appear in all capitals, as shown here | ||||
.</t> | ||||
<t>Certain security-related terms, such as "authentication", | ||||
"authorization", "confidentiality", "(data) integrity", "message | "authorization", "confidentiality", "(data) integrity", "message | |||
authentication code", and "verify" are taken from <xref | authentication code", and "verify", are taken from <xref target="RFC4949" format | |||
target="RFC4949"/>. | ="default"/>. | |||
</t> | </t> | |||
<t>Since exchanges in this specification are described as RESTful protocol | ||||
<t>Since exchanges in this specification are described as RESTful protocol | interactions, HTTP <xref target="RFC9110" format="default"/> offers useful t | |||
interactions, HTTP <xref target="RFC7231"/> offers useful terminology. | erminology. | |||
</t> | (Note that "RESTful" refers to the Representational State Transfer (REST) ar | |||
chitecture.) | ||||
<t>Terminology for entities in the architecture is defined in OAuth | </t> | |||
2.0 <xref target="RFC6749"/> such as client (C), resource server (RS), | <t>Terminology for entities in the architecture is defined in OAuth | |||
2.0 <xref target="RFC6749" format="default"/>, such as client (C), resource se | ||||
rver (RS), | ||||
and authorization server (AS).</t> | and authorization server (AS).</t> | |||
<t>Note that the term "endpoint" is used here following its OAuth | ||||
<t>Note that the term "endpoint" is used here following its OAuth | definition, which is to denote resources, such as token and | |||
definition, which is to denote resources such as token and | introspection at the AS and authz-info at the RS (see <xref target="tokenAuthInf | |||
introspection at the AS and authz-info at the RS (see <xref target="tokenAuthInf | oEndpoint" format="default"/> for a definition of the authz-info endpoint). | |||
oEndpoint"/> for a definition of the authz-info endpoint). | The CoAP definition, which is "[a]n entity | |||
The CoAP <xref target="RFC7252"/> definition, which is "An entity | participating in the CoAP protocol" <xref target="RFC7252" format="default"/>, i | |||
participating in the CoAP protocol" is not used in this specification.</t> | s not used in this specification.</t> | |||
<t>The specification in this document is called the "framework" or "ACE fr | ||||
<t>The specifications in this document is called the "framework" or "ACE framewo | amework". | |||
rk". | When referring to "profiles of this framework", it refers to additional specific | |||
When referring to "profiles of this framework" it refers to additional specifica | ations that | |||
tions that | ||||
define the use of this specification with concrete transport and communication | define the use of this specification with concrete transport and communication | |||
security protocols (e.g., CoAP over DTLS). | security protocols (e.g., CoAP over DTLS). | |||
</t> | </t> | |||
<t>The term "Access Information" is used for parameters, other than the ac | ||||
cess token, provided to the client by the AS to enable it to access the RS | ||||
(e.g., public key of the RS or profile supported by RS).</t> | ||||
<t>The term "authorization information" is used to denote all information, | ||||
including the claims of relevant access tokens, that an RS uses to determi | ||||
ne whether an access request should be granted.</t> | ||||
<t>Throughout this document, examples for CBOR data items are expre | ||||
ssed in CBOR extended diagnostic notation as defined in <xref section="8" sectio | ||||
nFormat="of" target="RFC8949"/> and <xref section="G" sectionFormat="of" target= | ||||
"RFC8610"/> ("diagnostic notation"), unless noted otherwise. We often use diagno | ||||
stic notation comments to provide a textual representation of the numeric parame | ||||
ter names and values.</t> | ||||
</section> | ||||
<t>The term "Access Information" is used for parameters, other than the access t | <section anchor="overview" numbered="true" toc="default"> | |||
oken, provided to the client by the AS to enable it to access the RS | <name>Overview</name> | |||
(e.g. public key of the RS, profile supported by RS).</t> | <t>This specification defines the ACE framework for authorization in the I | |||
nternet | ||||
<t>The term "Authorization Information" is used to denote all information, | ||||
including the claims of relevant access tokens, that an RS uses to determine whe | ||||
ther an access request should be granted.</t> | ||||
</section> | ||||
<!-- ***************************************************** --> | ||||
<section anchor="overview" title="Overview"> | ||||
<t>This specification defines the ACE framework for authorization in the Inter | ||||
net | ||||
of Things environment. It consists of a set of building blocks.</t> | of Things environment. It consists of a set of building blocks.</t> | |||
<t> | ||||
<t> | The basic block is the OAuth 2.0 <xref target="RFC6749" format="default"/> | |||
The basic block is the OAuth 2.0 <xref target="RFC6749"/> | ||||
framework, which enjoys widespread deployment. Many IoT devices can support | framework, which enjoys widespread deployment. Many IoT devices can support | |||
OAuth 2.0 without any additional extensions, but for certain constrained | OAuth 2.0 without any additional extensions, but for certain constrained | |||
settings additional profiling is needed. | settings, additional profiling is needed. | |||
</t> | </t> | |||
<t>Another building block is the lightweight web transfer protocol CoAP | ||||
<t>Another building block is the lightweight web transfer protocol CoAP | <xref target="RFC7252" format="default"/>, for those communication environment | |||
<xref target="RFC7252"/>, for those communication environments where HTTP is | s where HTTP is | |||
not appropriate. CoAP typically runs on top of UDP, which further reduces | not appropriate. CoAP typically runs on top of UDP, which further reduces | |||
overhead and message exchanges. While this specification defines extensions | overhead and message exchanges. While this specification defines extensions | |||
for the use of OAuth over CoAP, other underlying protocols are not prohibited | for the use of OAuth over CoAP, other underlying protocols are not prohibited | |||
from being supported in the future, such as HTTP/2 <xref target="RFC7540"/>, | from being supported in the future, such as HTTP/2 <xref target="RFC9113" form | |||
Message Queuing Telemetry Transport (MQTT) <xref target="MQTT5.0"/>, | at="default"/>, | |||
Bluetooth Low Energy (BLE) <xref target="BLE"/> and QUIC <xref | Message Queuing Telemetry Transport (MQTT) <xref target="MQTT5.0" format="defa | |||
target="I-D.ietf-quic-transport"/>. Note that this document specifies | ult"/>, | |||
protocol exchanges in terms of RESTful verbs such as GET and POST. | Bluetooth Low Energy (BLE) <xref target="BLE" format="default"/>, and QUIC <xr | |||
Future profiles using protocols that do not support these verbs MUST | ef target="RFC9000" format="default"/>. Note that this document specifies | |||
protocol exchanges in terms of RESTful verbs, such as GET and POST. | ||||
Future profiles using protocols that do not support these verbs <bcp14>MUST</b | ||||
cp14> | ||||
specify how the corresponding protocol messages are transmitted instead.</t> | specify how the corresponding protocol messages are transmitted instead.</t> | |||
<t>A third building block is the Concise Binary Object Representation | ||||
<t>A third building block is the Concise Binary Object Representation | (CBOR) <xref target="RFC8949" format="default"/>, for encodings where JSON | |||
(CBOR) <xref target="RFC8949"/>, for encodings where JSON | <xref target="RFC8259" format="default"/> is not sufficiently compact. CBOR i | |||
<xref target="RFC8259"/> is not sufficiently compact. CBOR is a binary | s a binary | |||
encoding designed for small code and message size. Self-contained tokens | encoding designed for small code and message size. Self-contained tokens | |||
and protocol message payloads are encoded in CBOR when CoAP is used. When CoAP | and protocol message payloads are encoded in CBOR when CoAP is used. When CoAP | |||
is not used, the use of CBOR remains RECOMMENDED. | is not used, the use of CBOR remains <bcp14>RECOMMENDED</bcp14>. | |||
</t> | </t> | |||
<t>A fourth building block is CBOR Object Signing and Encryption (COSE) | ||||
<t>A fourth building block is CBOR Object Signing and Encryption (COSE) | <xref target="RFC8152" format="default"/>, which enables object-level layer se | |||
<xref target="RFC8152"/>, which enables object-level layer security as an | curity as an | |||
alternative or complement to transport layer security (DTLS | alternative or complement to transport layer security (DTLS | |||
<xref target="RFC6347"/> or TLS <xref target="RFC8446"/>). COSE is used to | <xref target="RFC6347" format="default"/> <xref target="RFC9147"/> or TLS <x | |||
secure self-contained tokens such as proof-of-possession (PoP) tokens, | ref target="RFC8446" format="default"/>). COSE is used to | |||
secure self-contained tokens, such as proof-of-possession (PoP) tokens, | ||||
which are an extension to the OAuth bearer tokens. The default token format | which are an extension to the OAuth bearer tokens. The default token format | |||
is defined in CBOR Web Token (CWT) <xref target="RFC8392"/>. | is defined in CBOR Web Token (CWT) <xref target="RFC8392" format="default"/> | |||
Application-layer security for CoAP using COSE can be provided with OSCORE | . | |||
<xref target="RFC8613"/>.</t> | Application-layer security for CoAP using COSE can be provided with Object S | |||
ecurity for | ||||
<t>With the building blocks listed above, solutions satisfying various | Constrained RESTful Environments (OSCORE) | |||
<xref target="RFC8613" format="default"/>.</t> | ||||
<t>With the building blocks listed above, solutions satisfying various | ||||
IoT device and network constraints are possible. A list of constraints is | IoT device and network constraints are possible. A list of constraints is | |||
described in detail in <xref target="RFC7228"/> and a description | described in detail in <xref target="RFC7228" format="default"/>, and a descri ption | |||
of how the building blocks mentioned above relate to the various constraints | of how the building blocks mentioned above relate to the various constraints | |||
can be found in <xref target="constraints"/>.</t> | can be found in <xref target="constraints" format="default"/>.</t> | |||
<t>Luckily, not every IoT device suffers from all constraints. Neverthele | ||||
<t>Luckily, not every IoT device suffers from all constraints. The ACE | ss, the ACE | |||
framework nevertheless takes all these aspects into account and allows | framework takes all these aspects into account and allows | |||
several different deployment variants to co-exist, rather than mandating a | several different deployment variants to coexist, rather than mandating a | |||
one-size-fits-all solution. It is important to cover the wide | one-size-fits-all solution. It is important to cover the wide | |||
range of possible interworking use cases and the different requirements from | range of possible interworking use cases and the different requirements from | |||
a security point of view. Once IoT deployments mature, popular deployment | a security point of view. Once IoT deployments mature, popular deployment | |||
variants will be documented in the form of ACE profiles.</t> | variants will be documented in the form of ACE profiles.</t> | |||
<section anchor="oauth2Overview" numbered="true" toc="default"> | ||||
<section anchor="oauth2Overview" title="OAuth 2.0"> | <name>OAuth 2.0</name> | |||
<t>The OAuth 2.0 authorization framework enables a client to obtain | <t>The OAuth 2.0 authorization framework enables a client to obtain | |||
scoped access to a resource with the permission of a resource | scoped access to a resource with the permission of a resource | |||
owner. Authorization information, or references to it, is passed between th e nodes | owner. Authorization information, or references to it, is passed between th e nodes | |||
using access tokens. These access tokens are issued to clients by an | using access tokens. These access tokens are issued to clients by an | |||
authorization server with the approval of the resource owner. The client | authorization server with the approval of the resource owner. The client | |||
uses the access token to access the protected resources hosted by the | uses the access token to access the protected resources hosted by the | |||
resource server.</t> | resource server.</t> | |||
<t>A number of OAuth 2.0 terms are used within this specification: | ||||
<t>A number of OAuth 2.0 terms are used within this specification: | </t> | |||
<dl newline="true" spacing="normal"> | ||||
<list style="hanging"> | <dt>Access Tokens:</dt> | |||
<dd> | ||||
<t hangText="Access Tokens:"><vspace blankLines="0"/> | <t> | |||
Access tokens are credentials needed to access protected resources. An | Access tokens are credentials needed to access protected resources. An | |||
access token is a data structure representing authorization permissions | access token is a data structure representing authorization permissions | |||
issued by the AS to the client. Access tokens are generated by the AS | issued by the AS to the client. Access tokens are generated by the AS | |||
and consumed by the RS. The access token content is opaque | and consumed by the RS. The access token content is opaque | |||
to the client. | to the client. | |||
<vspace blankLines="1"/> | </t> | |||
Access tokens can have different formats, and various methods | <t> | |||
of utilization e.g., cryptographic properties) based on the security | Access tokens can have different formats and various methods | |||
of utilization (e.g., cryptographic properties) based on the security | ||||
requirements of the given deployment. | requirements of the given deployment. | |||
<vspace blankLines="1"/> | </t> | |||
</t> | </dd> | |||
<dt>Introspection:</dt> | ||||
<t hangText="Introspection:"><vspace blankLines="0"/> | <dd> | |||
Introspection is a method for a resource server or potentially a client, | Introspection is a method for a resource server, or potentially a client, | |||
to query the authorization server for the active state and content of a | to query the authorization server for the active state and content of a | |||
received access token. This is particularly useful in those cases where | received access token. This is particularly useful in those cases where | |||
the authorization decisions are very dynamic and/or where the received | the authorization decisions are very dynamic and/or where the received | |||
access token itself is an opaque reference rather than a self-contained | access token itself is an opaque reference, rather than a self-contained | |||
token. More information about introspection in OAuth 2.0 can be | token. More information about introspection in OAuth 2.0 can be | |||
found in <xref target="RFC7662"/>. | found in <xref target="RFC7662" format="default"/>. | |||
</t> | </dd> | |||
<dt>Refresh Tokens:</dt> | ||||
<t hangText="Refresh Tokens:"><vspace blankLines="0"/> | <dd> | |||
<t> | ||||
Refresh tokens are credentials used to obtain access tokens. | Refresh tokens are credentials used to obtain access tokens. | |||
Refresh tokens are issued to the client by the authorization | Refresh tokens are issued to the client by the authorization | |||
server and are used to obtain a new access token when the current | server and are used to obtain a new access token when the current | |||
access token expires, or to obtain additional access tokens with | access token expires or to obtain additional access tokens with | |||
identical or narrower scope (such access tokens may have a shorter | identical or narrower scope (such access tokens may have a shorter | |||
lifetime and fewer permissions than authorized by the resource owner). | lifetime and fewer permissions than authorized by the resource owner). | |||
Issuing a refresh token is optional at the discretion of the | Issuing a refresh token is optional at the discretion of the | |||
authorization server. If the authorization server issues a refresh | authorization server. If the authorization server issues a refresh | |||
token, it is included when issuing an access token (i.e., step (B) in | token, it is included when issuing an access token (i.e., step (B) in | |||
<xref target="fig:protocolFlow"/>). | <xref target="fig_protocolFlow" format="default"/>). | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
A refresh token in OAuth 2.0 is a string representing the authorization | A refresh token in OAuth 2.0 is a string representing the authorization | |||
granted to the client by the resource owner. The string is usually | granted to the client by the resource owner. The string is usually | |||
opaque to the client. The token denotes an identifier used to retrieve | opaque to the client. The token denotes an identifier used to retrieve | |||
the authorization information. Unlike access tokens, refresh | the authorization information. Unlike access tokens, refresh | |||
tokens are intended for use only with authorization servers and | tokens are intended for use only with authorization servers and | |||
are never sent to resource servers. In this framework, refresh | are never sent to resource servers. In this framework, refresh | |||
tokens are encoded in binary instead of strings, if used. | tokens are encoded in binary instead of strings, if used. | |||
<vspace blankLines="1"/></t> | </t> | |||
</dd> | ||||
<t hangText="Proof of Possession Tokens:"><vspace blankLines="0"/> | <dt>Proof-of-Possession Tokens:</dt> | |||
<dd> | ||||
<t> | ||||
A token may be bound to a cryptographic key, which is then used | A token may be bound to a cryptographic key, which is then used | |||
to bind the token to a request authorized by the token. Such tokens | to bind the token to a request authorized by the token. Such tokens | |||
are called proof-of-possession tokens (or PoP tokens). | are called proof-of-possession tokens (or PoP tokens). | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
The proof-of-possession security concept used here assumes that | The proof-of-possession security concept used here assumes that | |||
the AS acts as a trusted third party that binds keys to tokens. | the AS acts as a trusted third party that binds keys to tokens. | |||
In the case of access tokens, these so called PoP keys are then used by | In the case of access tokens, these so-called PoP keys are then used by | |||
the client to demonstrate the possession of the secret to the RS when | the client to demonstrate the possession of the secret to the RS when | |||
accessing the resource. The RS, when receiving an access token, needs | accessing the resource. The RS, when receiving an access token, needs | |||
to verify that the key used by the client matches the one bound to the | to verify that the key used by the client matches the one bound to the | |||
access token. When this specification uses the term "access token" it | access token. When this specification uses the term "access token", it | |||
is assumed to be a PoP access token unless specifically stated | is assumed to be a PoP access token unless specifically stated | |||
otherwise. | otherwise. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
The key bound to the token (the PoP key) may use either symmetric or | The key bound to the token (the PoP key) may use either symmetric or | |||
asymmetric cryptography. The appropriate choice of the kind of | asymmetric cryptography. The appropriate choice of the kind of | |||
cryptography depends on the constraints of the IoT devices as well as | cryptography depends on the constraints of the IoT devices as well as | |||
on the security requirements of the use case. | on the security requirements of the use case. | |||
<vspace blankLines="1"/> | </t> | |||
<list style="hanging"> | <dl newline="true" spacing="normal"> | |||
<dt>Symmetric PoP key:</dt> | ||||
<t hangText="Symmetric PoP key:"><vspace blankLines="0"/> | <dd> | |||
The AS generates a random symmetric PoP key. The key is either | <t> | |||
The AS generates a random, symmetric PoP key. The key is either | ||||
stored to be returned on introspection calls or included in the | stored to be returned on introspection calls or included in the | |||
token. Either the whole token or only the key MUST be encrypted | token. Either the whole token or only the key <bcp14>MUST</bcp14> be encrypted | |||
in the latter case. The PoP key is also returned to | in the latter case. The PoP key is also returned to | |||
client together with the token.<vspace blankLines="1"/> | client together with the token, protected by the secure channel.</t | |||
> | ||||
</t> | </dd> | |||
<t hangText="Asymmetric PoP key:"><vspace blankLines="0"/> | <dt>Asymmetric PoP key:</dt> | |||
<dd> | ||||
An asymmetric key pair is generated by the client and the public key | An asymmetric key pair is generated by the client and the public key | |||
is sent to the AS (if it does not already have knowledge of the | is sent to the AS (if it does not already have knowledge of the | |||
client's public key). Information about the public key, which is the | client's public key). Information about the public key, which is the | |||
PoP key in this case, is either stored to be returned on | PoP key in this case, is either stored to be returned on | |||
introspection calls or included inside the token and sent | introspection calls or included inside the token and sent | |||
back to the client. The resource server consuming the token can | back to the client. The resource server consuming the token can | |||
identify the public key from the information in the token, which | identify the public key from the information in the token, which | |||
allows the client to use the corresponding private key for the | allows the client to use the corresponding private key for the | |||
proof of possession. | proof of possession. | |||
</t> | </dd> | |||
</list> | </dl> | |||
<t> The token is either a simple reference | ||||
<vspace blankLines="1"/> The token is either a simple reference, | or a structured information object (e.g., CWT <xref target="RFC8392" form | |||
or a structured information object (e.g., CWT <xref target="RFC8392"/>) | at="default"/>) | |||
protected by a cryptographic wrapper (e.g., COSE <xref | protected by a cryptographic wrapper (e.g., COSE <xref target="RFC8152" f | |||
target="RFC8152"/>). The choice of PoP key does not necessarily imply | ormat="default"/>). The choice of PoP key does not necessarily imply | |||
a specific credential type for the integrity protection of the | a specific credential type for the integrity protection of the | |||
token.<vspace blankLines="1"/> | token.</t> | |||
</t> | </dd> | |||
<dt>Scopes and Permissions:</dt> | ||||
<t hangText="Scopes and Permissions:"><vspace blankLines="0"/> | <dd> | |||
<t> | ||||
In OAuth 2.0, the client specifies the type of permissions it is | In OAuth 2.0, the client specifies the type of permissions it is | |||
seeking to obtain (via the scope parameter) in the access token | seeking to obtain (via the <tt>scope</tt> parameter) in the access toke | |||
request. In turn, the AS may use the scope response parameter to | n | |||
request. In turn, the AS may use the <tt>scope</tt> response parameter | ||||
to | ||||
inform the client of the scope of the access token issued. As the | inform the client of the scope of the access token issued. As the | |||
client could be a constrained device as well, this specification | client could be a constrained device as well, this specification | |||
defines the use of CBOR encoding, see <xref | defines the use of CBOR encoding (see <xref target="oauthProfile" format | |||
target="oauthProfile"/>, for such requests and responses. | ="default"/>) for such requests and responses. | |||
<vspace blankLines="1"/> | </t> | |||
The values of the scope parameter in OAuth 2.0 are expressed as a list | <t> | |||
of space-delimited, case-sensitive strings, with a semantic that is | The values of the <tt>scope</tt> parameter in OAuth 2.0 are expressed a | |||
well-known to the AS and the RS. | s a list | |||
<!-- <vspace blankLines="1"/> | of space-delimited, case-sensitive strings with a semantic that is | |||
A common misconception is that the requested scopes must | well known to the AS and the RS. | |||
also be included in the returned access token, but the requested scopes | More details about the concept of scopes are found under | |||
are only metadata about the token. They could also be packaged in the | <xref target="RFC6749" sectionFormat="of" section="3.3"/>.</t> | |||
token as a separate attribute, but it's more common to assert the | </dd> | |||
requested and authorized access using claims within the access token. | <dt>Claims:</dt> | |||
<vspace blankLines="1"/>--> | <dd> | |||
More details about the concept of scopes is found under Section 3.3 in | <t> | |||
<xref target="RFC6749" />.<vspace blankLines="1"/> | ||||
</t> | ||||
<t hangText="Claims:"><vspace blankLines="0"/> | ||||
Information carried in the access token or returned from introspection, ca lled claims, is in the form of | Information carried in the access token or returned from introspection, ca lled claims, is in the form of | |||
name-value pairs. An access token may, for example, include a claim | name-value pairs. An access token may, for example, include a claim | |||
identifying the AS that issued the token (via the "iss" claim) and | identifying the AS that issued the token (via the <tt>iss</tt> claim) and | |||
what audience the access token is intended for (via the "aud" claim). | what audience the access token is intended for (via the <tt>aud</tt> claim | |||
The audience of an access token can be a specific resource or one or | ). | |||
The audience of an access token can be a specific resource, one resource, | ||||
or | ||||
many resource servers. The resource owner policies influence what | many resource servers. The resource owner policies influence what | |||
claims are put into the access token by the authorization server. | claims are put into the access token by the authorization server. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
While the structure and encoding of the access token varies throughout | While the structure and encoding of the access token varies throughout | |||
deployments, a standardized format has been defined with the JSON Web | deployments, a standardized format has been defined with the JSON Web | |||
Token (JWT) <xref target="RFC7519"/> where claims are encoded as a | Token (JWT) <xref target="RFC7519" format="default"/>, where claims are | |||
JSON object. In <xref target="RFC8392"/> the CBOR Web Token (CWT) | encoded as a | |||
JSON object. In <xref target="RFC8392" format="default"/>, the CBOR Web | ||||
Token (CWT) | ||||
has been defined as an equivalent format using CBOR encoding. | has been defined as an equivalent format using CBOR encoding. | |||
<vspace blankLines="1"/> | </t> | |||
</t> | </dd> | |||
<dt>Token and Introspection Endpoints:</dt> | ||||
<t hangText="The token and introspection Endpoints:"><vspace blankLines="0 | <dd> | |||
"/> | <t> | |||
The AS hosts the token endpoint that allows a client to request access | The AS hosts the token endpoint that allows a client to request access | |||
tokens. The client makes a POST request to the token endpoint on the AS | tokens. The client makes a POST request to the token endpoint on the AS | |||
and receives the access token in the response (if the request was | and receives the access token in the response (if the request was | |||
successful). | successful). | |||
<vspace blankLines="0"/> | </t> | |||
<t> | ||||
In some deployments, a token introspection endpoint is provided by | In some deployments, a token introspection endpoint is provided by | |||
the AS, which can be used by the RS and potentially the client, if they | the AS, which can be used by the RS and potentially the client, if they | |||
need to request additional information regarding a received access | need to request additional information regarding a received access | |||
token. The requesting entity makes a POST request to the introspection | token. The requesting entity makes a POST request to the introspection | |||
endpoint on the AS and receives information about the access token in | endpoint on the AS and receives information about the access token in | |||
the response. (See "Introspection" above.) | the response. (See "Introspection" above.) | |||
<vspace blankLines="1"/> | </t> | |||
</t> | </dd> | |||
</dl> | ||||
</list> | </section> | |||
</t> | <section anchor="coap" numbered="true" toc="default"> | |||
</section> | <name>CoAP</name> | |||
<t> | ||||
<section anchor="coap" title="CoAP"> | CoAP is an application-layer protocol similar to HTTP but specifically | |||
<t> | ||||
CoAP is an application-layer protocol similar to HTTP, but specifically | ||||
designed for constrained environments. CoAP typically uses | designed for constrained environments. CoAP typically uses | |||
datagram-oriented transport, such as UDP, where reordering and loss | datagram-oriented transport, such as UDP, where reordering and loss | |||
of packets can occur. A security solution needs to take the latter aspects | of packets can occur. A security solution needs to take the latter aspects | |||
into account.</t> | into account.</t> | |||
<t>While HTTP uses headers and query strings to convey additional | ||||
<t>While HTTP uses headers and query strings to convey additional | ||||
information about a request, CoAP encodes such information into header | information about a request, CoAP encodes such information into header | |||
parameters called 'options'.</t> | parameters called 'options'.</t> | |||
<t>CoAP supports application-layer fragmentation of the CoAP payloads | ||||
<t>CoAP supports application-layer fragmentation of the CoAP payloads | through block-wise transfers <xref target="RFC7959" format="default"/>. How | |||
through blockwise transfers <xref target="RFC7959"/>. However, | ever, | |||
blockwise transfer does not increase the size limits of CoAP options, | block-wise transfer does not increase the size limits of CoAP options; | |||
therefore data encoded in options has to be kept small. | therefore, data encoded in options has to be kept small. | |||
</t> | </t> | |||
<t>Transport layer security for CoAP can be provided by DTLS or TLS | ||||
<t>Transport layer security for CoAP can be provided by DTLS or TLS | <xref target="RFC6347" format="default"/> <xref target="RFC8446" format="defau | |||
<xref target="RFC6347"/><xref target="RFC8446"/> | lt"/> | |||
<xref target="I-D.ietf-tls-dtls13"/>. | <xref target="RFC9147" format="default"/>. | |||
CoAP defines a number of proxy operations that require transport layer | CoAP defines a number of proxy operations that require transport layer | |||
security to be terminated at the proxy. One approach for protecting CoAP com munication | security to be terminated at the proxy. One approach for protecting CoAP com munication | |||
end-to-end through proxies, and also to support security for CoAP over | end-to-end through proxies, and also to support security for CoAP over | |||
a different transport in a uniform way, is to provide security at the applic ation | a different transport in a uniform way, is to provide security at the applic ation | |||
layer using an object-based security mechanism such as COSE <xref target="RF | layer using an object-based security mechanism, such as COSE <xref target="R | |||
C8152"/>. | FC8152" format="default"/>. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
One application of COSE is OSCORE | One application of COSE is OSCORE | |||
<xref target="RFC8613"/>, which provides end-to-end confidentiality, | <xref target="RFC8613" format="default"/>, which provides end-to-end confide ntiality, | |||
integrity and replay protection, and a secure binding between CoAP request | integrity and replay protection, and a secure binding between CoAP request | |||
and response messages. In OSCORE, the CoAP messages are wrapped in COSE | and response messages. In OSCORE, the CoAP messages are wrapped in COSE | |||
objects and sent using CoAP. | objects and sent using CoAP. | |||
</t> | </t> | |||
<t>In this framework, the use of CoAP as replacement for HTTP is <bcp14> | ||||
<t>In this framework the use of CoAP as replacement for HTTP is RECOMMENDED | RECOMMENDED</bcp14> | |||
for use in constrained environments. For communication security this | for use in constrained environments. For communication security, this | |||
framework does not make an explicit protocol recommendation, since the choice | framework does not make an explicit protocol recommendation, since the choice | |||
depends on the requirements of the specific application. DTLS | depends on the requirements of the specific application. DTLS | |||
<xref target="RFC6347"/>, <xref target="I-D.ietf-tls-dtls13"/> and OSCORE | <xref target="RFC6347" format="default"/> <xref target="RFC9147" format="defau | |||
<xref target="RFC8613"/> are mentioned as examples, other protocols fulfilling | lt"/> and OSCORE | |||
the requirements from <xref target="minimalCommSecReq"/> are also | <xref target="RFC8613" format="default"/> are mentioned as examples; other pro | |||
tocols fulfilling | ||||
the requirements from <xref target="minimalCommSecReq" format="default"/> are | ||||
also | ||||
applicable.</t> | applicable.</t> | |||
</section> | ||||
</section> | </section> | |||
</section> | <section anchor="specs" numbered="true" toc="default"> | |||
<name>Protocol Interactions</name> | ||||
<!-- ***************************************************** --> | <t> | |||
<section anchor="specs" title="Protocol Interactions"> | ||||
<t> | ||||
The ACE framework is based on the OAuth 2.0 protocol interactions using | The ACE framework is based on the OAuth 2.0 protocol interactions using | |||
the token endpoint and optionally the introspection endpoint. | the token endpoint and optionally the introspection endpoint. | |||
A client obtains an access token, and optionally a refresh token, from an | A client obtains an access token, and optionally a refresh token, from an | |||
AS using the token endpoint and subsequently presents the access token to | AS using the token endpoint and subsequently presents the access token to | |||
an RS to gain access to a protected resource. In most deployments the RS can | an RS to gain access to a protected resource. In most deployments, the RS ca | |||
process the access token locally, however in some cases the RS may present | n | |||
process the access token locally; however, in some cases, the RS may present | ||||
it to the AS via the introspection endpoint to get fresh information. | it to the AS via the introspection endpoint to get fresh information. | |||
These interactions are shown in <xref target="fig:protocolFlow"/>. An | These interactions are shown in <xref target="fig_protocolFlow" format="defa | |||
overview of various OAuth concepts is provided in <xref | ult"/>. An | |||
target="oauth2Overview"/>. | overview of various OAuth concepts is provided in <xref target="oauth2Overvi | |||
ew" format="default"/>. | ||||
</t> | </t> | |||
<figure anchor="fig_protocolFlow"> | ||||
<t><figure align="center" anchor="fig:protocolFlow" | <name>Basic Protocol Flow</name> | |||
title="Basic Protocol Flow."> | <artwork align="left" name="" type="" alt=""><![CDATA[ | |||
<artwork align="left"><![CDATA[ | ||||
+--------+ +---------------+ | +--------+ +---------------+ | |||
| |---(A)-- Token Request ------->| | | | |---(A)-- Token Request ------->| | | |||
| | | Authorization | | | | | Authorization | | |||
| |<--(B)-- Access Token ---------| Server | | | |<--(B)-- Access Token ---------| Server | | |||
| | + Access Information | | | | | + Access Information | | | |||
| | + Refresh Token (optional) +---------------+ | | | + Refresh Token (optional) +---------------+ | |||
| | ^ | | | | ^ | | |||
| | Introspection Request (D)| | | | | Introspection Request (D)| | | |||
| Client | Response | |(E) | | Client | Response | |(E) | |||
| | (optional exchange) | | | | | (optional exchange) | | | |||
| | | v | | | | v | |||
| | +--------------+ | | | +--------------+ | |||
| |---(C)-- Token + Request ----->| | | | |---(C)-- Token + Request ----->| | | |||
| | | Resource | | | | | Resource | | |||
| |<--(F)-- Protected Resource ---| Server | | | |<--(F)-- Protected Resource ---| Server | | |||
| | | | | | | | | | |||
+--------+ +--------------+ | +--------+ +--------------+ | |||
]]></artwork> | ]]></artwork> | |||
</figure></t> | </figure> | |||
<dl newline="true" spacing="normal"> | ||||
<t> | <dt>Requesting an Access Token (A):</dt> | |||
<list style="hanging"> | <dd> | |||
<t hangText="Requesting an Access Token (A):"><vspace blankLines="0"/> | <t> | |||
The client makes an access token request to the token endpoint at the AS. | The client makes an access token request to the token endpoint at the AS. | |||
This framework assumes the use of PoP access tokens (see <xref | This framework assumes the use of PoP access tokens (see <xref target="oau | |||
target="oauth2Overview"/> for a short description) wherein the AS binds a | th2Overview" format="default"/> for a short description) wherein the AS binds a | |||
key to an access token. The client may include permissions it seeks to | key to an access token. The client may include permissions it seeks to | |||
obtain, and information about the credentials it wants to use for | obtain and information about the credentials it wants to use for | |||
proof-of-possession (e.g., symmetric/asymmetric cryptography or a | proof of possession (e.g., symmetric/asymmetric cryptography or a | |||
reference to a specific key) of the access token.<vspace blankLines="1"/> | reference to a specific key) of the access token.</t> | |||
</t> | </dd> | |||
<dt>Access Token Response (B):</dt> | ||||
<t hangText="Access Token Response (B):"><vspace blankLines="0"/> | <dd> | |||
<t> | ||||
If the request from the client has been successfully verified, | If the request from the client has been successfully verified, | |||
authenticated, and authorized, the AS returns an access token and optional ly a refresh | authenticated, and authorized, the AS returns an access token and optional ly a refresh | |||
token. Note that only certain grant types support refresh tokens. The AS | token. Note that only certain grant types support refresh tokens. The AS | |||
can also return additional parameters, referred to as "Access | can also return additional parameters, referred to as "Access | |||
Information". In addition to the response parameters defined by OAuth | Information". In addition to the response parameters defined by OAuth | |||
2.0 and the PoP access token extension, this framework defines parameters | 2.0 and the PoP access token extension, this framework defines parameters | |||
that can be used to inform the client about capabilities of the RS, e.g. | that can be used to inform the client about capabilities of the RS, e.g., | |||
the profile the RS supports. More information about these parameters | the profile the RS supports. More information about these parameters | |||
can be found in <xref target="tokenParams"/>. | can be found in <xref target="tokenParams" format="default"/>. | |||
<vspace blankLines="1"/> | </t> | |||
</t> | </dd> | |||
<dt>Resource Request (C):</dt> | ||||
<t hangText="Resource Request (C):"><vspace blankLines="0"/> | <dd> | |||
<t> | ||||
The client interacts with the RS to request access to the protected | The client interacts with the RS to request access to the protected | |||
resource and provides the access token. The protocol to use | resource and provides the access token. The protocol to use | |||
between the client and the RS is not restricted to CoAP. HTTP, HTTP/2 | between the client and the RS is not restricted to CoAP. HTTP, HTTP/2 | |||
<xref target="RFC7540"/>, QUIC <xref target="I-D.ietf-quic-transport"/>, | <xref target="RFC9113" format="default"/>, QUIC <xref target="RFC9000" for | |||
MQTT <xref target="MQTT5.0"/>, Bluetooth Low Energy <xref target="BLE"/>, | mat="default"/>, | |||
MQTT <xref target="MQTT5.0" format="default"/>, Bluetooth Low Energy <xref | ||||
target="BLE" format="default"/>, | ||||
etc., are also viable candidates. | etc., are also viable candidates. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
Depending on the device limitations and the selected protocol, this | Depending on the device limitations and the selected protocol, this | |||
exchange may be split up into two parts: | exchange may be split up into two parts:</t> | |||
<ol type="(%d)" spacing="normal"> | ||||
<list style="empty"> | <li>the client sends the access token containing, or referencing, th | |||
<t>(1) the client sends the access token containing, or referencing, the | e | |||
authorization information to the RS, that will be used for subsequent | authorization information to the RS that will be used for subsequent | |||
resource requests by the client, and </t> | resource requests by the client, and </li> | |||
<li>the client makes the resource access request using the communica | ||||
<t>(2) the client makes the resource access request, using the communication | tion | |||
security protocol and other Access Information obtained from the AS.</t> | security protocol and other Access Information obtained from the AS.</li> | |||
</list> | </ol> | |||
<t> | ||||
<vspace blankLines="1"/> | ||||
The client and the RS mutually authenticate using the security protocol | The client and the RS mutually authenticate using the security protocol | |||
specified in the profile (see step B) and the keys obtained in the access | specified in the profile (see step (B)) and the keys obtained in the acces s | |||
token or the Access Information. The RS verifies that the token is | token or the Access Information. The RS verifies that the token is | |||
integrity protected and originated by the AS. It then compares the claims | integrity protected and originated by the AS. It then compares the claims | |||
contained in the access token with the resource request. If the RS is | contained in the access token with the resource request. If the RS is | |||
online, validation can be handed over to the AS using token introspection | online, validation can be handed over to the AS using token introspection | |||
(see messages D and E) over HTTP or CoAP.<vspace blankLines="1"/> | (see messages (D) and (E)) over HTTP or CoAP.</t> | |||
</t> | </dd> | |||
<dt>Token Introspection Request (D):</dt> | ||||
<t hangText="Token Introspection Request (D):"><vspace blankLines="0"/> | <dd> | |||
<t> | ||||
A resource server may be configured to introspect the access token by | A resource server may be configured to introspect the access token by | |||
including it in a request to the introspection endpoint at that AS. | including it in a request to the introspection endpoint at that AS. | |||
Token introspection over | Token introspection over | |||
CoAP is defined in <xref target="introspectionEndpoint"/> and for HTTP in | CoAP is defined in <xref target="introspectionEndpoint" format="default"/> | |||
<xref target="RFC7662"/>. | and for HTTP in | |||
<vspace blankLines="1"/> | <xref target="RFC7662" format="default"/>. | |||
</t> | ||||
<t> | ||||
Note that token introspection is an optional step and can be omitted if | Note that token introspection is an optional step and can be omitted if | |||
the token is self-contained and the resource server is prepared to | the token is self-contained and the resource server is prepared to | |||
perform the token validation on its own.<vspace blankLines="1"/> | perform the token validation on its own.</t> | |||
</t> | </dd> | |||
<dt>Token Introspection Response (E):</dt> | ||||
<t hangText="Token Introspection Response (E):"><vspace blankLines="0"/> | <dd> | |||
<t> | ||||
The AS validates the token and returns the most recent parameters, such | The AS validates the token and returns the most recent parameters, such | |||
as scope, audience, validity etc. associated with it back to the RS. The | as <tt>scope</tt>, <tt>audience</tt>, validity, etc., associated with it b ack to the RS. The | |||
RS then uses the received parameters to process the request to either | RS then uses the received parameters to process the request to either | |||
accept or to deny it.<vspace blankLines="1"/> | accept or to deny it.</t> | |||
</t> | </dd> | |||
<dt>Protected Resource (F):</dt> | ||||
<t hangText="Protected Resource (F):"><vspace blankLines="0"/> | <dd> | |||
If the request from the client is authorized, the RS fulfills the request | If the request from the client is authorized, the RS fulfills the request | |||
and returns a response with the appropriate response code. The RS uses | and returns a response with the appropriate response code. The RS uses | |||
the dynamically established keys to protect the response, according to | the dynamically established keys to protect the response according to | |||
the communication security protocol used. | the communication security protocol used. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t>The OAuth 2.0 framework defines a number of "protocol flows" via grant | |||
types, | ||||
<t>The OAuth 2.0 framework defines a number of "protocol flows" via grant types, | which have been extended | |||
which have been extended | further with extensions to OAuth 2.0 (such as <xref target="RFC7521" | |||
further with extensions to OAuth 2.0 (such as <xref target="RFC7521"/> and <xref | format="default"/> and <xref target="RFC8628" format="default"/>). | |||
target="RFC8628"/>). | What grant type works best depends on the usage scenario; <xref | |||
What grant type works best depends on the usage scenario and <xref target="RFC77 | target="RFC7744" format="default"/> describes many different IoT use cases | |||
44"/> describes many different IoT use cases but there are two grant types that | , but | |||
cover a majority of these scenarios, namely the Authorization Code Grant (descri | there are two grant types that cover a majority of these scenarios, namely | |||
bed in Section 4.1 of <xref target="RFC7521"/>) and the Client Credentials Grant | the | |||
(described in Section 4.4 of <xref target="RFC7521"/>). The Authorization Code | authorization code grant (described in <xref target="RFC6749" format="defa | |||
Grant is a good fit for use with apps running on smart phones and tablets that r | ult" | |||
equest access to IoT devices, a common scenario in the smart home environment, w | sectionFormat="of" section="4.1"/>) and | |||
here users need to go through an authentication and authorization phase (at leas | the client credentials grant (described | |||
t during the initial setup phase). The native apps guidelines described in <xref | in <xref target="RFC6749" sectionFormat="of" section="4.4"/>). The authori | |||
target="RFC8252"/> are applicable to this use case. The Client Credential Grant | zation | |||
is a good fit for use with IoT devices where the OAuth client itself is constra | code grant is a good fit for use with apps running on smartphones and tabl | |||
ined. In such a case, the resource owner has pre-arranged access rights for the | ets that request access to IoT devices, a common scenario in the smart home envi | |||
client with the authorization server, which is often accomplished using a commis | ronment, where users need to go through an authentication and authorization phas | |||
sioning tool.</t> | e (at least during the initial setup phase). The native apps guidelines describe | |||
d in <xref target="RFC8252" format="default"/> are applicable to this use case. | ||||
<t> | The client credentials grant is a good fit for use with IoT devices where the OA | |||
uth client itself is constrained. In such a case, the resource owner has prearra | ||||
nged access rights for the client with the authorization server, which is often | ||||
accomplished using a commissioning tool.</t> | ||||
<t> | ||||
The consent of the resource owner, for giving a client access to a protected | The consent of the resource owner, for giving a client access to a protected | |||
resource, can be provided dynamically as in the traditional OAuth flows, or | resource, can be provided dynamically as in the classical OAuth flows, or it | |||
it | could be preconfigured by the resource owner as authorization policies at | |||
could be pre-configured by the resource owner as authorization policies at | ||||
the AS, which the AS evaluates when a token request arrives. The resource | the AS, which the AS evaluates when a token request arrives. The resource | |||
owner and the requesting party (i.e., client owner) are not shown in <xref | owner and the requesting party (i.e., client owner) are not shown in <xref t | |||
target="fig:protocolFlow"/>. | arget="fig_protocolFlow" format="default"/>. | |||
</t> | </t> | |||
<t> | ||||
<t> | This framework supports a wide variety of communication security mechanis | |||
This framework supports a wide variety of communication security mechanisms | ms | |||
between the ACE entities, such as client, | between the ACE entities, such as the client, | |||
AS, and RS. It is assumed that the client has been | AS, and RS. It is assumed that the client has been | |||
registered (also called enrolled or onboarded) to an AS using a mechanism defi | registered (also called enrolled or onboarded) to an AS using a mechanism | |||
ned outside the scope of this document. | defined | |||
In practice, various techniques for onboarding have been used, such as factory | outside the scope of this document. | |||
-based provisioning or the use of | In practice, various techniques for onboarding have been used, such as | |||
commissioning tools. Regardless of the onboarding technique, this provisioning | factory-based provisioning or the use of | |||
procedure implies that the client and the AS exchange credentials and | commissioning tools. Regardless of the onboarding technique, this provisi | |||
configuration parameters. These credentials are used to mutually authenticate | oning | |||
each other and to protect messages exchanged between the client and the AS.</t> | procedure implies that the client and the AS exchange credentials and | |||
configuration parameters. These credentials are used to mutually authent | ||||
<t>It is also assumed that the RS has been registered with the AS, potentially | icate each | |||
in a similar way as the client has been registered with the AS. | other and to protect messages exchanged between the client and the AS.</ | |||
t> | ||||
<t>It is also assumed that the RS has been registered with the AS, potenti | ||||
ally in a similar way as the client has been registered with the AS. | ||||
Established keying material between the AS and the RS allows the AS to apply | Established keying material between the AS and the RS allows the AS to apply | |||
cryptographic protection to the access token to ensure that its content cannot | cryptographic protection to the access token to ensure that its content cannot | |||
be modified, and if needed, that the content is confidentiality protected. Conf identiality protection of the access token content would be provided on top of | be modified and, if needed, that the content is confidentiality protected. Conf identiality protection of the access token content would be provided on top of | |||
confidentiality protection via a communication security protocol. </t> | confidentiality protection via a communication security protocol. </t> | |||
<t>The keying material necessary for establishing communication security | ||||
<t>The keying material necessary for establishing communication security | between the C and RS is dynamically established as part of the protocol descri | |||
between C and RS is dynamically established as part of the protocol described | bed | |||
in this document. | in this document. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
At the start of the protocol, there is an optional discovery step where the | At the start of the protocol, there is an optional discovery step where the | |||
client discovers the resource server and the resources this server hosts. | client discovers the resource server and the resources this server hosts. | |||
In this step, the client might also determine what permissions are needed to | In this step, the client might also determine what permissions are needed to | |||
access the protected resource. A generic procedure is described in <xref | access the protected resource. A generic procedure is described in <xref ta | |||
target="asDiscovery"/>; profiles MAY define other procedures for | rget="asDiscovery" format="default"/>; profiles <bcp14>MAY</bcp14> define other | |||
procedures for | ||||
discovery.</t> | discovery.</t> | |||
<t>In Bluetooth Low Energy, for example, advertisements are broadcast by | ||||
<t>In Bluetooth Low Energy, for example, advertisements are broadcast by | ||||
a peripheral, including information about the primary services. In CoAP, | a peripheral, including information about the primary services. In CoAP, | |||
as a second example, a client can make a request to "/.well-known/core" to | as a second example, a client can make a request to "/.well-known/core" to | |||
obtain information about available resources, which are returned in a | obtain information about available resources, which are returned in a | |||
standardized format as described in <xref target="RFC6690"/>. | standardized format, as described in <xref target="RFC6690" format="default" />. | |||
</t> | </t> | |||
</section> | </section> | |||
<!-- ***************************************************** --> | ||||
<section anchor="oauthProfile" title="Framework"> | ||||
<t>The following sections detail the profiling and extensions of OAuth 2.0 | <section anchor="oauthProfile" numbered="true" toc="default"> | |||
<name>Framework</name> | ||||
<t>The following sections detail the profiling and extensions of OAuth 2.0 | ||||
for constrained environments, which constitutes the ACE framework. | for constrained environments, which constitutes the ACE framework. | |||
</t> | </t> | |||
<dl newline="true" spacing="normal"> | ||||
<t> | <dt>Credential Provisioning</dt> | |||
<list style="hanging"> | <dd> | |||
<t hangText="Credential Provisioning"><vspace blankLines="0"/> | <t> | |||
In constrained environments it cannot be assumed that the client and the | In constrained environments, it cannot be assumed that the client and th | |||
RS | e RS | |||
are part of a common key infrastructure. Therefore, the AS provisions | are part of a common key infrastructure. Therefore, the AS provisions | |||
credentials and associated information to allow mutual authentication | credentials and associated information to allow mutual authentication | |||
between the client and the RS. The resulting security association between the client | between the client and the RS. The resulting security association between the client | |||
and the RS may then also be used to bind these credentials to the | and the RS may then also be used to bind these credentials to the | |||
access tokens the client uses. | access tokens the client uses. | |||
<vspace blankLines="1"/> | </t> | |||
</t> | </dd> | |||
<dt>Proof of Possession</dt> | ||||
<t hangText="Proof-of-Possession"><vspace blankLines="0"/> | <dd> | |||
The ACE framework, by default, implements proof-of-possession for | <t> | |||
The ACE framework, by default, implements proof of possession for | ||||
access tokens, i.e., that the token holder can prove being a holder of | access tokens, i.e., that the token holder can prove being a holder of | |||
the key bound to the token. The binding is provided by the "cnf" claim | the key bound to the token. The binding is provided by the <tt>cnf</tt> | |||
<xref target="RFC8747"/> indicating what key is used for | (confirmation) | |||
proof-of-possession. If a client needs to submit a new access token, | claim | |||
<xref target="RFC8747" format="default"/>, indicating what key is used fo | ||||
r | ||||
proof of possession. If a client needs to submit a new access token, | ||||
e.g., to obtain additional access rights, they can request | e.g., to obtain additional access rights, they can request | |||
that the AS binds this token to the same key as the previous one. | that the AS binds this token to the same key as the previous one. | |||
<vspace blankLines="1"/> | </t> | |||
</t> | </dd> | |||
<dt>ACE Profiles</dt> | ||||
<t hangText="ACE Profiles"><vspace blankLines="0"/> | <dd> | |||
The client or RS may be limited in the encodings or protocols it | The client or RS may be limited in the encodings or protocols it | |||
supports. To support a variety of different deployment settings, | supports. To support a variety of different deployment settings, | |||
specific interactions between client and RS are defined in an ACE | specific interactions between the client and RS are defined in an ACE | |||
profile. In ACE framework the AS is expected to manage the matching | profile. In the ACE framework, the AS is expected to manage the matchin | |||
g | ||||
of compatible profile choices between a client and an RS. The AS | of compatible profile choices between a client and an RS. The AS | |||
informs the client of the selected profile using the "ace_profile" | informs the client of the selected profile using the <tt>ace_profile</tt> | |||
parameter in the token response. | parameter in the token response. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t>OAuth 2.0 requires the use of TLS to protect the communication | |||
between the AS and client when requesting an access token between the client a | ||||
<t>OAuth 2.0 requires the use of TLS both to protect the communication | nd RS | |||
between AS and client when requesting an access token; between client and RS | when accessing a resource and between the AS and RS if introspection is used. | |||
when accessing a resource and between AS and RS if introspection is used. | In constrained settings, TLS is not always feasible or desirable. | |||
In constrained settings TLS is not always feasible, or desirable. | Nevertheless, it is <bcp14>REQUIRED</bcp14> that the communications named abov | |||
Nevertheless it is REQUIRED that the communications named above are | e are | |||
encrypted, integrity protected and protected against message replay. It is | encrypted, integrity protected, and protected against message replay. It is | |||
also REQUIRED that the communicating endpoints perform mutual authentication. | also <bcp14>REQUIRED</bcp14> that the communicating endpoints perform mutual a | |||
Furthermore it MUST be assured that responses are bound to the requests in | uthentication. | |||
Furthermore, it <bcp14>MUST</bcp14> be assured that responses are bound to the | ||||
requests in | ||||
the sense that the receiver of a response can be certain that the response | the sense that the receiver of a response can be certain that the response | |||
actually belongs to a certain request. Note that setting up such a secure | actually belongs to a certain request. Note that setting up such a secure | |||
communication may require some unprotected messages to be exchanged first | communication may require some unprotected messages to be exchanged first | |||
(e.g. sending the token from the client to the RS).</t> | (e.g., sending the token from the client to the RS).</t> | |||
<t>Profiles <bcp14>MUST</bcp14> specify a communication security protocol | ||||
<t>Profiles MUST specify a communication security protocol between client | between the | |||
and RS that provides the features required above. Profiles MUST specify a | client and RS that provides the features required above. Profiles | |||
communication security protocol RECOMMENDED to be used between client and AS | <bcp14>MUST</bcp14> specify a | |||
that provides the features required above. Profiles MUST specify for | communication security protocol <bcp14>RECOMMENDED</bcp14> to be used betw | |||
introspection a communication security protocol RECOMMENDED to be used | een the | |||
between RS and AS that provides the features required above. These | client and AS that provides the features required above. Profiles <bcp14> | |||
recommendations enable interoperability between different implementations | MUST</bcp14> | |||
without the need to define a new profile if the communication between C and | specify, for introspection, a communication security protocol | |||
AS, or between RS and AS, is protected with a different security protocol | <bcp14>RECOMMENDED</bcp14> to be used | |||
complying with the security requirements above.</t> | between the RS and AS that provides the features required above. These | |||
recommendations enable interoperability between different implementations | ||||
<t>In OAuth 2.0 the communication with the Token and the Introspection | without the need to define a new profile if the communication between the | |||
C and | ||||
AS, or between the RS and AS, is protected with a different security proto | ||||
col | ||||
complying with the security requirements above.</t> | ||||
<t>In OAuth 2.0, the communication with the Token and the Introspection | ||||
endpoints at the AS is assumed to be via HTTP and may use Uri-query | endpoints at the AS is assumed to be via HTTP and may use Uri-query | |||
parameters. When profiles of this framework use CoAP instead, it is | parameters. When profiles of this framework use CoAP instead, it is | |||
REQUIRED to use of the following alternative instead of Uri-query | <bcp14>REQUIRED</bcp14> to use of the following alternative instead of Uri-que ry | |||
parameters: The sender (client or RS) encodes the parameters of its request | parameters: The sender (client or RS) encodes the parameters of its request | |||
as a CBOR map and submits that map as the payload of the POST request. | as a CBOR map and submits that map as the payload of the POST request. | |||
The CBOR encoding for a number of OAuth 2.0 parameters is specified in this | The CBOR encoding for a number of OAuth 2.0 parameters is specified in this | |||
document, if a profile needs to use other OAuth 2.0 parameters with CoAP it | document; if a profile needs to use other OAuth 2.0 parameters with CoAP, it | |||
MUST specify their CBOR encoding.</t> | <bcp14>MUST</bcp14> specify their CBOR encoding.</t> | |||
<t>Profiles that use CBOR encoding of protocol message parameters at the | ||||
<t>Profiles that use CBOR encoding of protocol message parameters at the | outermost encoding layer <bcp14>MUST</bcp14> use the Content-Format "applicati | |||
outermost encoding layer MUST use the content format 'application/ace+cbor'. | on/ace+cbor". | |||
If CoAP is used for communication, the Content-Format MUST be abbreviated | If CoAP is used for communication, the Content-Format <bcp14>MUST</bcp14> be a | |||
with the ID: 19 (see <xref target="IANAcoapContentFormat"/>).</t> | bbreviated | |||
with the ID: 19 (see <xref target="IANAcoapContentFormat" format="default"/>). | ||||
<t>The OAuth 2.0 AS uses a JSON structure in the payload of its responses | </t> | |||
both to client and RS. If CoAP is used, it is REQUIRED to use | <t>The OAuth 2.0 AS uses a JSON structure in the payload of its responses | |||
CBOR <xref target="RFC8949"/> instead of JSON. Depending on the profile, | both to the client and RS. If CoAP is used, it is <bcp14>REQUIRED</bcp14> to | |||
the CBOR payload MAY be enclosed in a non-CBOR cryptographic wrapper.</t> | use | |||
CBOR <xref target="RFC8949" format="default"/> instead of JSON. Depending on | ||||
<section anchor="asDiscovery" title="Discovering Authorization Servers"> | the profile, | |||
<t>C must discover the AS in charge of RS to determine where to request the | the CBOR payload <bcp14>MAY</bcp14> be enclosed in a non-CBOR cryptographic wr | |||
access token. To do so, C must 1. find out the AS URI to which the token | apper.</t> | |||
request message must be sent and 2. MUST validate that the AS with this | <section anchor="asDiscovery" numbered="true" toc="default"> | |||
<name>Discovering Authorization Servers</name> | ||||
<t>The C must discover the AS in charge of the RS to determine where to | ||||
request the | ||||
access token. To do so, the C 1) must find out the AS URI to which the token | ||||
request message must be sent and 2) <bcp14>MUST</bcp14> validate that the AS wit | ||||
h this | ||||
URI is authorized to provide access tokens for this RS. | URI is authorized to provide access tokens for this RS. | |||
</t> | </t> | |||
<t> In order to determine the AS URI, the C <bcp14>MAY</bcp14> send an i | ||||
<t> In order to determine the AS URI, C MAY send an initial Unauthorized | nitial Unauthorized | |||
Resource Request message to RS. RS then denies the request and sends | Resource Request message to the RS. The RS then denies the request and sends | |||
the address of its AS back to C (see <xref target="rreq"/>). How C validates the | the address of its AS back to the C (see <xref target="rreq" format="default"/>) | |||
AS authorization is not in scope for this document. C may, e.g., ask | . How the C validates the | |||
its owner if this AS is authorized for this RS. C may also use a | AS authorization is not in scope for this document. The C may, for example, ask | |||
mechanism that addresses both problems at once (e.g. by querying a dedicated sec | its owner if this AS is authorized for this RS. The C may also use a | |||
ure service provided by the client owner) .</t> | mechanism that addresses both problems at once (e.g., by querying a dedicated se | |||
cure service provided by the client owner) .</t> | ||||
</section><!--AS Discovery --> | </section> | |||
<section anchor="rreq" title="Unauthorized Resource Request Message"> | ||||
<t>An Unauthorized Resource Request message is a request for any | ||||
resource hosted by RS for which the client does not have authorization grant | ||||
ed. RSes MUST | ||||
treat any request for a protected resource as an Unauthorized Resource | ||||
Request message when any of the following hold: | ||||
<list style="symbols"> | ||||
<t>The request has been received on an unsecured channel.</t> | ||||
<t>The RS has no valid access token for the sender of the request | ||||
regarding the requested action on that resource.</t> | ||||
<t>The RS has a valid access token for the sender of the request, but | ||||
that token does not authorize the requested action on the requested | ||||
resource.</t> | ||||
</list> | ||||
</t> | ||||
<t>Note: These conditions ensure that the RS can handle requests autonomousl | ||||
y | ||||
once access was granted and a secure channel has been established between C | ||||
and RS. The authz-info endpoint, as part of the process for authorizing | ||||
to protected resources, is not itself a protected resource and MUST NOT be | ||||
protected as specified above (cf. <xref | ||||
target="tokenAuthInfoEndpoint"/>).</t> | ||||
<t>Unauthorized Resource Request messages MUST be denied with an "unauthoriz | ||||
ed_client" | ||||
error response. In this response, the Resource Server SHOULD provide proper | ||||
"AS Request Creation Hints" to enable the client to request an access token | ||||
from RS's AS as described in <xref target="asInfo"/>.</t> | ||||
<t>The handling of all client requests (including unauthorized ones) | ||||
by the RS is described in <xref target="requestC2RS"/>.</t> | ||||
</section><!-- Unauthorized Request --> | ||||
<section anchor="asInfo" title="AS Request Creation Hints"> | <section anchor="rreq" numbered="true" toc="default"> | |||
<t>The "AS Request Creation Hints" message is sent by an RS as a response to | <name>Unauthorized Resource Request Message</name> | |||
an Unauthorized Resource Request message (see <xref target="rreq"/>) to help | <t>An Unauthorized Resource Request message is a request for any | |||
the sender of the Unauthorized Resource Request message acquire a valid | resource hosted by the RS for which the client does not have authorizatio | |||
access token. The "AS Request Creation Hints" message is a CBOR or JSON map, | n granted. | |||
with an OPTIONAL element "AS" specifying an absolute URI (see Section 4.3 | The RSs <bcp14>MUST</bcp14> | |||
of <xref target="RFC3986"/>) that identifies the appropriate AS for the | treat any request for a protected resource as an Unauthorized Resource | |||
RS.</t> | Request message when any of the following hold: | |||
</t> | ||||
<ul spacing="normal"> | ||||
<li>The request has been received on an unsecured channel.</li> | ||||
<li>The RS has no valid access token for the sender of the request | ||||
regarding the requested action on that resource.</li> | ||||
<li>The RS has a valid access token for the sender of the request, but | ||||
that token does not authorize the requested action on the requested | ||||
resource.</li> | ||||
</ul> | ||||
<t>Note: These conditions ensure that the RS can handle requests autonom | ||||
ously | ||||
once access was granted and a secure channel has been established between | ||||
the C | ||||
and RS. The authz-info endpoint, as part of the process for authorizing | ||||
to protected resources, is not itself a protected resource and <bcp14>MUS | ||||
T | ||||
NOT</bcp14> be protected as specified above (cf. <xref | ||||
target="tokenAuthInfoEndpoint" format="default"/>).</t> | ||||
<t>Unauthorized Resource Request messages <bcp14>MUST</bcp14> be denied | ||||
with an | ||||
"unauthorized_client" error response. In this response, the resource serv | ||||
er | ||||
<bcp14>SHOULD</bcp14> provide proper | ||||
AS Request Creation Hints to enable the client to request an access token | ||||
from the RS's AS, as described in <xref target="asInfo" format="default"/ | ||||
>.</t> | ||||
<t>The handling of all client requests (including unauthorized ones) | ||||
by the RS is described in <xref target="requestC2RS" format="default"/>.</t> | ||||
</section> | ||||
<t>The message can also contain the following OPTIONAL parameters: | <section anchor="asInfo" numbered="true" toc="default"> | |||
<list style="symbols"> | <name>AS Request Creation Hints</name> | |||
<t>A "audience" element contains an identifier the client | <t>The AS Request Creation Hints are sent by an RS as a response to | |||
an Unauthorized Resource Request message (see <xref target="rreq" | ||||
format="default"/>) to help | ||||
the sender of the Unauthorized Resource Request message acquire a valid | ||||
access token. The AS Request Creation Hints are a CBOR or JSON map, | ||||
with an <bcp14>OPTIONAL</bcp14> element <tt>AS</tt> specifying an absolut | ||||
e URI (see | ||||
<xref target="RFC3986" sectionFormat="of" section="4.3"/>) that identifie | ||||
s the | ||||
appropriate AS for the RS.</t> | ||||
<t>The message can also contain the following <bcp14>OPTIONAL</bcp14> | ||||
parameters:</t> | ||||
<ul spacing="normal"> | ||||
<li>An <tt>audience</tt> element contains an identifier the client | ||||
should request at the AS, as suggested by the RS. With this parameter, | should request at the AS, as suggested by the RS. With this parameter, | |||
when included in the access token request to the AS, the AS is able to | when included in the access token request to the AS, the AS is able to | |||
restrict the use of access token to specific RSs. See | restrict the use of the access token to specific RSs. See | |||
<xref target="audience"/> for a discussion of this parameter.</t> | <xref target="audience" format="default"/> for a discussion of this parame | |||
<t>A "kid" element containing the key identifier of a key used in | ter.</li> | |||
an existing security association between the client and the RS. | <li>A <tt>kid</tt> (key identifier) element contains the key identifie | |||
The RS expects the client to request an access token bound to this | r of a key used in | |||
key, in order to avoid having to re-establish the security | an existing security association between the client and the RS. | |||
association.</t> | The RS expects the client to request an access token bound to this | |||
<t>A "cnonce" element containing a client-nonce. See <xref | key in order to avoid having to reestablish the security | |||
target="cnonceParam"/>.</t> | association.</li> | |||
<t>A "scope" element containing the suggested scope that the client | <li>A <tt>cnonce</tt> element contains a client-nonce. See <xref targe | |||
should request towards the AS.</t> | t="cnonceParam" | |||
</list></t> | format="default"/>.</li> | |||
<li>A <tt>scope</tt> element contains the suggested scope that the cli | ||||
<t><xref target="fig:asinfo"/> summarizes the parameters that may be | ent | |||
part of the "AS Request Creation Hints". | should request towards the AS.</li> | |||
</ul> | ||||
<figure align="center" anchor="fig:asinfo" | <t><xref target="table_asinfo" format="default"/> summarizes the paramet | |||
title="AS Request Creation Hints"> | ers that may | |||
<artwork align="left"><![CDATA[ | be part of the AS Request Creation Hints.</t> | |||
/-----------+----------+---------------------\ | <table anchor="table_asinfo"> | |||
| Name | CBOR Key | Value Type | | <name>AS Request Creation Hints</name> | |||
|-----------+----------+---------------------| | <thead> | |||
| AS | 1 | text string | | <tr> | |||
| kid | 2 | byte string | | <th>Name</th> | |||
| audience | 5 | text string | | <th>CBOR Key</th> | |||
| scope | 9 | text or byte string | | <th>Value Type</th> | |||
| cnonce | 39 | byte string | | </tr> | |||
\-----------+----------+---------------------/ | </thead> | |||
]]></artwork></figure></t> | <tbody> | |||
<tr> | ||||
<t>Note that the schema part of the AS parameter may need to be | <td>AS</td> | |||
<td>1</td> | ||||
<td>text string</td> | ||||
</tr> | ||||
<tr> | ||||
<td>kid</td> | ||||
<td>2</td> | ||||
<td>byte string</td> | ||||
</tr> | ||||
<tr> | ||||
<td>audience</td> | ||||
<td>5</td> | ||||
<td>text string</td> | ||||
</tr> | ||||
<tr> | ||||
<td>scope</td> | ||||
<td>9</td> | ||||
<td>text or byte string</td> | ||||
</tr> | ||||
<tr> | ||||
<td>cnonce</td> | ||||
<td>39</td> | ||||
<td>byte string</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t>Note that the schema part of the AS parameter may need to be | ||||
adapted to the security protocol that is used between the client | adapted to the security protocol that is used between the client | |||
and the AS. Thus the example AS value "coap://as.example.com/token" | and the AS. Thus, the example AS value "coap://as.example.com/token" | |||
might need to be transformed to "coaps://as.example.com/token". | might need to be transformed to "coaps://as.example.com/token". | |||
It is assumed that the client can determine the correct schema part on | It is assumed that the client can determine the correct schema part on | |||
its own depending on the way it communicates with the AS.</t> | its own depending on the way it communicates with the AS.</t> | |||
<t><xref target="fig_as-info-payload" format="default"/> shows an exampl | ||||
<t><xref target="fig:as-info-payload"/> shows an example for an "AS | e for an AS | |||
Request Creation Hints" message payload using CBOR <xref target="RFC8949"/> | Request Creation Hints payload using | |||
diagnostic notation, using the parameter names instead of the CBOR keys for | diagnostic notation.</t> | |||
better human readability.</t> | <figure anchor="fig_as-info-payload"> | |||
<name>AS Request Creation Hints Payload Example</name> | ||||
<figure title="AS Request Creation Hints payload example" | <sourcecode type="cbor-diag"><![CDATA[ | |||
anchor="fig:as-info-payload"><artwork><![CDATA[ | ||||
4.01 Unauthorized | 4.01 Unauthorized | |||
Content-Format: application/ace+cbor | Content-Format: application/ace+cbor | |||
Payload : | Payload : | |||
{ | { | |||
"AS" : "coaps://as.example.com/token", | / AS / 1 : "coaps://as.example.com/token", | |||
"audience" : "coaps://rs.example.com" | / audience / 5 : "coaps://rs.example.com", | |||
"scope" : "rTempC", | / scope / 9 : "rTempC", | |||
"cnonce" : h'e0a156bb3f' | / cnonce / 39 : h'e0a156bb3f' | |||
} | } | |||
]]></artwork></figure> | ]]></sourcecode> | |||
</figure> | ||||
<t>In the example above, the response parameter "AS" points the receiver of | <t>In the example above, the response parameter <tt>AS</tt> points the r | |||
eceiver of | ||||
this message to the URI "coaps://as.example.com/token" to request access | this message to the URI "coaps://as.example.com/token" to request access | |||
tokens. The RS sending this response uses an internal clock | tokens. The RS sending this response uses an internal clock | |||
that is not synchronized with the clock of the AS. Therefore, it | that is not synchronized with the clock of the AS. Therefore, it | |||
can not reliably verify the expiration time of access tokens it receives. | cannot reliably verify the expiration time of access tokens it receives. | |||
To ensure a certain level of access token freshness nevertheless, the RS has | Nevertheless, to ensure a certain level of access token freshness, the RS ha | |||
included a <spanx style="verb">cnonce</spanx> parameter (see <xref | s | |||
target="cnonceParam"/>) in the response. (The hex-sequence of the cnonce par | included a <tt>cnonce</tt> parameter (see <xref target="cnonceParam" format= | |||
ameter | "default"/>) in the response. (The hex sequence of the <tt>cnonce</tt> parameter | |||
is encoded in CBOR-based notation in this example.)</t> | is encoded in CBOR-based notation in this example.)</t> | |||
<t><xref target="fig_as-info-cbor" format="default"/> illustrates the ma | ||||
<t><xref target="fig:as-info-cbor"/> illustrates the mandatory to use | ndatory use | |||
binary encoding of the message payload shown in | of binary encoding of the message payload shown in | |||
<xref target="fig:as-info-payload"/>.</t> | <xref target="fig_as-info-payload" format="default"/>.</t> | |||
<figure anchor="fig_as-info-cbor"> | ||||
<figure title="AS Request Creation Hints example encoded in CBOR" | <name>AS Request Creation Hints Example Encoded in CBOR</name> | |||
anchor="fig:as-info-cbor"><artwork><![CDATA[ | <sourcecode name="" type="cbor-pretty"><![CDATA[ | |||
a4 # map(4) | a4 # map(4) | |||
01 # unsigned(1) (=AS) | 01 # unsigned(1) (=AS) | |||
78 1c # text(28) | 78 1c # text(28) | |||
636f6170733a2f2f61732e657861 | 636f6170733a2f2f61732e657861 | |||
6d706c652e636f6d2f746f6b656e # "coaps://as.example.com/token" | 6d706c652e636f6d2f746f6b656e # "coaps://as.example.com/token" | |||
05 # unsigned(5) (=audience) | 05 # unsigned(5) (=audience) | |||
76 # text(22) | 76 # text(22) | |||
636f6170733a2f2f72732e657861 | 636f6170733a2f2f72732e657861 | |||
6d706c652e636f6d # "coaps://rs.example.com" | 6d706c652e636f6d # "coaps://rs.example.com" | |||
09 # unsigned(9) (=scope) | 09 # unsigned(9) (=scope) | |||
66 # text(6) | 66 # text(6) | |||
7254656d7043 # "rTempC" | 7254656d7043 # "rTempC" | |||
18 27 # unsigned(39) (=cnonce) | 18 27 # unsigned(39) (=cnonce) | |||
45 # bytes(5) | 45 # bytes(5) | |||
e0a156bb3f # | e0a156bb3f # | |||
]]></artwork></figure> | ]]></sourcecode> | |||
</figure> | ||||
<section anchor="cnonceParam" title="The Client-Nonce Parameter"> | <section anchor="cnonceParam" numbered="true" toc="default"> | |||
<t>If the RS does not synchronize its clock with the AS, it could be | <name>The Client-Nonce Parameter</name> | |||
tricked into accepting old access tokens, that are either expired or have | <t>If the RS does not synchronize its clock with the AS, it could be | |||
tricked into accepting old access tokens that are either expired or have | ||||
been compromised. In order to ensure some level of token freshness | been compromised. In order to ensure some level of token freshness | |||
in that case, the RS can use the "cnonce" (client-nonce) parameter. | in that case, the RS can use the <tt>cnonce</tt> (client-nonce) parameter. | |||
The processing requirements for this parameter are as follows: | The processing requirements for this parameter are as follows: | |||
<list style="symbols"> | </t> | |||
<t>An RS sending a "cnonce" parameter in an "AS Request Creation | <ul spacing="normal"> | |||
Hints" message MUST store information to validate that a given | <li>An RS sending a <tt>cnonce</tt> parameter in an AS Request Creat | |||
cnonce is fresh. How this is implemented internally is out of scope | ion | |||
for this specification. Expiration of client-nonces should be based | Hints message <bcp14>MUST</bcp14> store information to validate that | |||
roughly on the time it would take a client to obtain an access token | a given | |||
after receiving the "AS Request Creation Hints" message, with some | cnonce is fresh. How this is implemented internally is out of scope | |||
allowance for unexpected delays.</t> | for this specification. Expiration of client-nonces should be based | |||
roughly on the time it would take a client to obtain an access token | ||||
<t>A client receiving a "cnonce" parameter in an "AS Request Creation | after receiving the AS Request Creation Hints, with some | |||
Hints" message MUST include this in the parameters when requesting | allowance for unexpected delays.</li> | |||
an access token at the AS, using the "cnonce" parameter from | <li>A client receiving a <tt>cnonce</tt> parameter in an AS Request | |||
<xref target="cnonceParamToken"/>.</t> | Creation | |||
Hints message <bcp14>MUST</bcp14> include this in the parameters when | ||||
<t>If an AS grants an access token request containing a "cnonce" | requesting an access token at the AS, using the <tt>cnonce</tt> param | |||
parameter, it MUST include this value in the access token, using the | eter from | |||
"cnonce" claim specified in <xref target="accessToken"/>.</t> | <xref target="cnonceParamToken" format="default"/>.</li> | |||
<li>If an AS grants an access token request containing a <tt>cnonce< | ||||
<t>An RS that is using the client-nonce mechanism and that receives an | /tt> | |||
access token MUST verify that this token contains a cnonce claim, with | parameter, it <bcp14>MUST</bcp14> include this value in the access to | |||
a client-nonce value that is fresh according to the information stored | ken, using | |||
at the first step above. If the cnonce claim is not present or if the | the <tt>cnonce</tt> claim specified in <xref target="accessToken" | |||
cnonce claim value is not fresh, the RS MUST discard the access token. | format="default"/>.</li> | |||
If this was an interaction with the authz-info endpoint the RS MUST also | <li>An RS that is using the client-nonce mechanism and that receives | |||
respond with an error message using a response code equivalent to the | an | |||
CoAP code 4.01 (Unauthorized).</t> | access token <bcp14>MUST</bcp14> verify that this token contains a <t | |||
</list> | t>cnonce</tt> | |||
</t> | claim, with | |||
</section> | a client-nonce value that is fresh according to the information store | |||
</section><!--AS information--> | d | |||
at the first step above. If the <tt>cnonce</tt> claim is not present | ||||
or if the | ||||
<tt>cnonce</tt> claim value is not fresh, the RS <bcp14>MUST</bcp14> | ||||
discard the access | ||||
token. If this was an interaction with the authz-info endpoint, the R | ||||
S | ||||
<bcp14>MUST</bcp14> also | ||||
respond with an error message using a response code equivalent to the | ||||
CoAP code 4.01 (Unauthorized).</li> | ||||
</ul> | ||||
</section> | ||||
</section> | ||||
<section anchor="authorizationGrants" title="Authorization Grants"> | <section anchor="authorizationGrants" numbered="true" toc="default"> | |||
<t>To request an access token, the client obtains authorization from the | <name>Authorization Grants</name> | |||
<t>To request an access token, the client obtains authorization from the | ||||
resource owner or uses its client credentials as a grant. The authorization | resource owner or uses its client credentials as a grant. The authorization | |||
is expressed in the form of an authorization grant.</t> | is expressed in the form of an authorization grant.</t> | |||
<t>The OAuth framework <xref target="RFC6749" format="default"/> defines | ||||
<t>The OAuth framework <xref target="RFC6749"/> defines four grant types. The | four grant types. The grant types can | |||
grant types can | be split up into two groups: those granted on behalf of the resource | |||
be split up into two groups, those granted on behalf of the resource | ||||
owner (password, authorization code, implicit) and those for the client | owner (password, authorization code, implicit) and those for the client | |||
(client credentials). Further grant types have been added later, such as <xref | (client credentials). Further grant types have been added later, such as an as | |||
target="RFC7521"/> defining an assertion-based authorization grant.</t> | sertion-based authorization grant defined in <xref target="RFC7521" format="defa | |||
ult"/>.</t> | ||||
<t>The grant type is selected depending on the use case. In cases where | <t>The grant type is selected depending on the use case. In cases where | |||
the client acts on behalf of the resource owner, the authorization code | the client acts on behalf of the resource owner, the authorization code | |||
grant is recommended. If the client acts on behalf of the resource owner, | grant is recommended. If the client acts on behalf of the resource owner | |||
but does not have any display or has very limited interaction possibilities, i t is | but does not have any display or has very limited interaction possibilities, i t is | |||
recommended to use the device code grant defined in | recommended to use the device code grant defined in | |||
<xref target="RFC8628"/>. In cases where the client | <xref target="RFC8628" format="default"/>. In cases where the client | |||
acts autonomously the client credentials grant is recommended.</t> | acts autonomously, the client credentials grant is recommended.</t> | |||
<t>For details on the different grant types, see <xref target="RFC6749" | ||||
<t>For details on the different grant types, see section 1.3 of <xref | sectionFormat="of" section="1.3"/>. The OAuth 2.0 framework provides an extensio | |||
target="RFC6749"/>. The OAuth 2.0 framework provides an extension | n | |||
mechanism for defining additional grant types, so profiles of this framework | mechanism for defining additional grant types, so profiles of this framework | |||
MAY define additional grant types, if needed.</t> | <bcp14>MAY</bcp14> define additional grant types, if needed.</t> | |||
</section> <!--Grants--> | </section> | |||
<section anchor="clientCredentials" title="Client Credentials"> | <section anchor="clientCredentials" numbered="true" toc="default"> | |||
<t>Authentication of the client is mandatory independent of the grant type | <name>Client Credentials</name> | |||
<t>Authentication of the client is mandatory independent of the grant ty | ||||
pe | ||||
when requesting an access token from the token endpoint. In the case of | when requesting an access token from the token endpoint. In the case of | |||
the client credentials grant type, the authentication and grant coincide.</t> | the client credentials grant type, the authentication and grant coincide.</t> | |||
<t>Client registration and provisioning of client credentials to the cli | ||||
<t>Client registration and provisioning of client credentials to the client | ent | |||
is out of scope for this specification.</t> | is out of scope for this specification.</t> | |||
<t>The OAuth framework defines one client credential type in | ||||
<t>The OAuth framework defines one client credential type in section 2.3.1 of | <xref target="RFC6749" sectionFormat="of" section="2.3.1"/> that comprises the | |||
<xref target="RFC6749"/>: client id and client secret. <xref | client_id and client_secret values. <xref target="I-D.erdtman-oauth-rpcc" forma | |||
target="I-D.erdtman-ace-rpcc"/> adds raw-public-key and pre-shared-key to the | t="default"/> adds raw public key and pre-shared key to the | |||
client credentials types. Profiles of this framework MAY extend with | client credentials type. Profiles of this framework <bcp14>MAY</bcp14> extend | |||
it with | ||||
an additional client credentials type using client certificates.</t> | an additional client credentials type using client certificates.</t> | |||
</section> <!--Client Credentials--> | </section> | |||
<section anchor="ASAuthentication" title="AS Authentication"> | <section anchor="ASAuthentication" numbered="true" toc="default"> | |||
<t>The client credential grant does not, by default, authenticate the AS that | <name>AS Authentication</name> | |||
the client | <t>The client credentials grant does not, by default, authenticate the A | |||
S that the client | ||||
connects to. In classic OAuth, the AS is authenticated with a TLS server | connects to. In classic OAuth, the AS is authenticated with a TLS server | |||
certificate.</t> | certificate.</t> | |||
<t>Profiles of this framework <bcp14>MUST</bcp14> specify how clients au | ||||
<t>Profiles of this framework MUST specify how clients authenticate the AS | thenticate the AS | |||
and how communication security is implemented. By default, server side TLS | and how communication security is implemented. By default, server side TLS | |||
certificates, as defined by OAuth 2.0, are required.</t> | certificates, as defined by OAuth 2.0, are required.</t> | |||
</section> <!--AS Authentication--> | </section> | |||
<section anchor="authorizeEndpoint" title="The Authorization Endpoint"> | <section anchor="authorizeEndpoint" numbered="true" toc="default"> | |||
<t>The OAuth 2.0 authorization endpoint is used to interact with the resource | <name>The Authorization Endpoint</name> | |||
owner | <t>The OAuth 2.0 authorization endpoint is used to interact with the res | |||
and obtain an authorization grant, in certain grant flows. The primary use | ource owner | |||
and obtain an authorization grant in certain grant flows. The primary use | ||||
case for the ACE-OAuth framework is for machine-to-machine interactions that d o not involve | case for the ACE-OAuth framework is for machine-to-machine interactions that d o not involve | |||
the resource owner in the authorization flow; therefore, this endpoint is | the resource owner in the authorization flow; therefore, this endpoint is | |||
out of scope here. Future profiles may define constrained adaptation | out of scope here. Future profiles may define constrained adaptation | |||
mechanisms for this endpoint as well. Non-constrained clients interacting | mechanisms for this endpoint as well. Nonconstrained clients interacting | |||
with constrained resource servers can use the specification in section 3.1 | with constrained resource servers can use the specification in | |||
of <xref target="RFC6749"/> and the attack countermeasures suggested in | <xref target="RFC6749" sectionFormat="of" section="3.1"/> and the attack count | |||
section 4.2 of <xref target="RFC6819"/>.</t> | ermeasures suggested in | |||
</section> <!--The 'Authorize' Endpoint--> | <xref target="RFC6819" sectionFormat="of" section="4.2"/>.</t> | |||
</section> | ||||
<section anchor="tokenEndpoint" title="The Token Endpoint"> | <section anchor="tokenEndpoint" numbered="true" toc="default"> | |||
<t>In standard OAuth 2.0, the AS provides the token endpoint for submitting | <name>The Token Endpoint</name> | |||
<t>In standard OAuth 2.0, the AS provides the token endpoint for submitt | ||||
ing | ||||
access token requests. This framework extends the functionality of the | access token requests. This framework extends the functionality of the | |||
token endpoint, giving the AS the possibility to help the client and RS to | token endpoint, giving the AS the possibility to help the client and RS | |||
establish shared keys or to exchange their public keys. Furthermore, | establish shared keys or exchange their public keys. Furthermore, | |||
this framework defines encodings using CBOR, as a substitute for JSON.</t> | this framework defines encodings using CBOR as a substitute for JSON.</t> | |||
<t>The endpoint may also be exposed over HTTPS, as in classical OAuth or | ||||
<t>The endpoint may also be exposed over HTTPS as in classical OAuth or | even other transports. A profile <bcp14>MUST</bcp14> define the details of th | |||
even other transports. A profile MUST define the details of the mapping | e mapping | |||
between the fields described below, and these transports. If HTTPS is used, | between the fields described below and these transports. | |||
the semantics of Sections 4.1.3 and 4.1.4 of the OAuth 2.0 specification MUST | If HTTPS with JSON is used, | |||
be followed (with additions as described below). If the CoAP is some other | the semantics of Sections <xref target="RFC6749" section="4.1.3" sectionFormat | |||
transport with CBOR payload format is supported, the semantics described in | ="bare"/> and <xref target="RFC6749" section="4.1.4" sectionFormat="bare"/> of t | |||
this section MUST be followed.</t> | he OAuth 2.0 specification <xref target="RFC6749" format="default"/> <bcp14>MUST | |||
</bcp14> | ||||
<t>For the AS to be able to issue a token, the client MUST be authenticated | be followed (with additions as described below). If CBOR is used as the paylo | |||
ad format, the semantics described in this | ||||
section <bcp14>MUST</bcp14> be followed.</t> | ||||
<t>For the AS to be able to issue a token, the client <bcp14>MUST</bcp14 | ||||
> be authenticated | ||||
and present a valid grant for the scopes requested. Profiles of this | and present a valid grant for the scopes requested. Profiles of this | |||
framework MUST specify how the AS authenticates the client and how the | framework <bcp14>MUST</bcp14> specify how the AS authenticates the client and | |||
communication between client and AS is protected, fulfilling the | how the | |||
requirements specified in <xref target="oauthProfile"/>.</t> | communication between the client and AS is protected, fulfilling the | |||
requirements specified in <xref target="oauthProfile" format="default"/>.</t> | ||||
<t>The default name of this endpoint in an url-path SHOULD be '/token'. | <t>The default name of this endpoint in a url-path <bcp14>SHOULD</bcp14> | |||
be '/token'. | ||||
However, implementations are not required to use this name and can define | However, implementations are not required to use this name and can define | |||
their own instead.</t> | their own instead.</t> | |||
<section anchor="tokenRequest" numbered="true" toc="default"> | ||||
<t>The figures of this section use CBOR diagnostic | <name>Client-to-AS Request</name> | |||
notation without the integer abbreviations for the parameters or their | <t>The client sends a POST request to the token endpoint | |||
values for illustrative purposes. Note that implementations MUST use the | at the AS. The profile <bcp14>MUST</bcp14> specify how the communication is | |||
integer abbreviations and the binary CBOR encoding, if the CBOR encoding is us | protected. | |||
ed.</t> | ||||
<section anchor="tokenRequest" title="Client-to-AS Request"> | ||||
<t>The client sends a POST request to the token endpoint | ||||
at the AS. The profile MUST specify how the communication is protected. | ||||
The content of the request consists of the parameters specified | The content of the request consists of the parameters specified | |||
in the relevant subsection of section 4 of the OAuth 2.0 specification | in the relevant subsection of Section <xref target="RFC6749" section="4" sec | |||
<xref target="RFC6749"/>, depending on the grant type, with the following | tionFormat="bare"/> of the OAuth 2.0 specification | |||
<xref target="RFC6749" format="default"/>, depending on the grant type, with | ||||
the following | ||||
exceptions and additions: | exceptions and additions: | |||
</t> | ||||
<list style="symbols"> | <ul spacing="normal"> | |||
<t>The parameter "grant_type" is OPTIONAL in the context of this | <li>The <tt>grant_type</tt> parameter is <bcp14>OPTIONAL</bcp14> in | |||
framework (as opposed to REQUIRED in RFC6749). If that parameter is | the context | |||
missing, the default value "client_credentials" is implied.</t> | of this framework (as opposed to <bcp14>REQUIRED</bcp14> in <xref | |||
<t>The "audience" parameter from <xref target="RFC8693"/> is OPTIONAL to | target="RFC6749" format="default"/>). If that parameter is | |||
request an access token bound to a specific audience.</t> | missing, the default value "client_credentials" is implied.</li> | |||
<t>The "cnonce" parameter defined in <xref target="cnonceParamToken"/> is | <li>The <tt>audience</tt> parameter from <xref target="RFC8693" | |||
REQUIRED if the RS provided a client-nonce in the "AS Request Creation | format="default"/> is <bcp14>OPTIONAL</bcp14> to | |||
Hints" message <xref target="asInfo"/></t> | request an access token bound to a specific audience.</li> | |||
<t>The "scope" parameter MAY be encoded as a byte string instead of | <li>The <tt>cnonce</tt> parameter defined in <xref target="cnoncePar | |||
the string encoding specified in section 3.3 of <xref target="RFC6749"/>, | amToken" | |||
in order allow compact encoding of complex scopes. The syntax of | format="default"/> is | |||
such a binary encoding is explicitly not specified here and left | <bcp14>REQUIRED</bcp14> if the RS provided a client-nonce in the AS | |||
to profiles or applications. Note specifically that a binary encoded | Request Creation Hints message (<xref target="asInfo" format="default | |||
scope does not necessarily use the space character '0x20' to delimit | "/>).</li> | |||
scope-tokens.</t> | <li>The <tt>scope</tt> parameter <bcp14>MAY</bcp14> be encoded as a | |||
<t>The client can send an empty (null value) "ace_profile" parameter to | byte string | |||
indicate that it wants the AS to include the "ace_profile" parameter in | instead of the string encoding specified in <xref target="RFC6749" se | |||
the response. See <xref target="paramProfile"/>.</t> | ctionFormat="of" | |||
<t>A client MUST be able to use the parameters from <xref | section="3.3"/> or | |||
target="I-D.ietf-ace-oauth-params"/> in an access token request to the | in order to allow compact encoding of complex scopes. The syntax of | |||
token endpoint and the AS MUST be able to process these additional | such a binary encoding is explicitly not specified here and left | |||
parameters.</t> | to profiles or applications. Note specifically that a binary encoded | |||
</list></t> | scope does not necessarily use the space character '0x20' to delimit | |||
scope-tokens.</li> | ||||
<t>The default behavior, is that the AS generates a symmetric | <li>The client can send an empty (null value) <tt>ace_profile</tt> p | |||
arameter to | ||||
indicate that it wants the AS to include the <tt>ace_profile</tt> par | ||||
ameter in | ||||
the response. See <xref target="paramProfile" format="default"/>.</li> | ||||
<li>A client <bcp14>MUST</bcp14> be able to use the parameters from | ||||
<xref target="RFC9201" format="default"/> in an access token request to the | ||||
token endpoint, and the AS <bcp14>MUST</bcp14> be able to process these ad | ||||
ditional | ||||
parameters.</li> | ||||
</ul> | ||||
<t>The default behavior is that the AS generates a symmetric | ||||
proof-of-possession key for the client. In order to use an asymmetric key | proof-of-possession key for the client. In order to use an asymmetric key | |||
pair or to re-use a key previously established with the RS, the client is | pair or to reuse a key previously established with the RS, the client is | |||
supposed to use the "req_cnf" parameter from <xref | supposed to use the <tt>req_cnf</tt> parameter from <xref target="RFC9201" f | |||
target="I-D.ietf-ace-oauth-params"/>. | ormat="default"/>. | |||
</t> | </t> | |||
<t>If CoAP is used, then these parameters <bcp14>MUST</bcp14> be provi | ||||
<t>If CoAP is used then these parameters MUST be provided in a CBOR map, | ded in a CBOR map | |||
see <xref target="fig:cborTokenParameters"/>.</t> | (see <xref target="table_cborTokenParameters" format="default"/>).</t> | |||
<t>When HTTP is used as a transport, then the client makes a | ||||
<t>When HTTP is used as a transport then the client makes a | request to the token endpoint; the parameters <bcp14>MUST</bcp14> be encoded | |||
request to the token endpoint, the parameters MUST be encoded as defined | as defined | |||
in Appendix B of <xref target="RFC6749"/>.</t> | in <xref target="RFC6749" sectionFormat="of" section="B"/>.</t> | |||
<t>The following examples illustrate different types of requests | ||||
<t>The following examples illustrate different types of requests | ||||
for proof-of-possession tokens. </t> | for proof-of-possession tokens. </t> | |||
<t><xref target="fig_symmATreq" format="default"/> shows a request for | ||||
<t><xref target="fig:symmATreq"/> shows a request for a token | a token | |||
with a symmetric proof-of-possession key. The content is displayed in | with a symmetric proof-of-possession key, using diagnostic notation.</t> | |||
CBOR diagnostic notation, without abbreviations for better readability. | <figure anchor="fig_symmATreq"> | |||
<name>Example Request for an Access Token Bound to a Symmetric Key</ | ||||
<figure align="center" anchor="fig:symmATreq" | name> | |||
title="Example request for an access token bound to a | <sourcecode name="" type="cbor-diag"><![CDATA[ | |||
symmetric key."> | ||||
<artwork align="left"><![CDATA[ | ||||
Header: POST (Code=0.02) | Header: POST (Code=0.02) | |||
Uri-Host: "as.example.com" | Uri-Host: "as.example.com" | |||
Uri-Path: "token" | Uri-Path: "token" | |||
Content-Format: "application/ace+cbor" | Content-Format: application/ace+cbor | |||
Payload: | Payload: | |||
{ | { | |||
"client_id" : "myclient", | / client_id / 24 : "myclient", | |||
"audience" : "tempSensor4711" | / audience / 5 : "tempSensor4711" | |||
} | } | |||
]]></artwork> | ]]></sourcecode> | |||
</figure></t> | </figure> | |||
<t><xref target="fig_asymmATreq" format="default"/> shows a request fo | ||||
<t><xref target="fig:asymmATreq"/> shows a request for a token with an | r a token | |||
asymmetric proof-of-possession key. Note that in this example OSCORE | with an | |||
<xref target="RFC8613"/> is used | asymmetric proof-of-possession key. Note that, in this example, OSCORE | |||
to provide object-security, therefore the Content-Format is | <xref target="RFC8613" format="default"/> is used | |||
"application/oscore" wrapping the "application/ace+cbor" type content. | to provide object-security; therefore, the Content-Format is | |||
The OSCORE option has a decoded interpretation appended in parentheses | "application/oscore" wrapping the "application/ace+cbor" type content. | |||
for the reader's convenience. Also note that in this example the audience | The OSCORE option has a decoded interpretation appended in parentheses | |||
is implicitly known by both client and AS. Furthermore note that this | for the reader's convenience. Also note that, in this example, the aud | |||
example uses the "req_cnf" parameter from <xref | ience | |||
target="I-D.ietf-ace-oauth-params"/>. | is implicitly known by both the client and AS. Furthermore, note that t | |||
his | ||||
<figure align="center" anchor="fig:asymmATreq" | example uses the <tt>req_cnf</tt> parameter from <xref target="RFC9201" | |||
title="Example token request bound to an asymmetric key."> | format="default"/>. | |||
<artwork align="left"><![CDATA[ | </t> | |||
<figure anchor="fig_asymmATreq"> | ||||
<name>Example Token Request Bound to an Asymmetric Key</name> | ||||
<sourcecode name="" type="cbor-diag"><![CDATA[ | ||||
Header: POST (Code=0.02) | Header: POST (Code=0.02) | |||
Uri-Host: "as.example.com" | Uri-Host: "as.example.com" | |||
Uri-Path: "token" | Uri-Path: "token" | |||
OSCORE: 0x09, 0x05, 0x44, 0x6C | OSCORE: 0x09, 0x05, 0x44, 0x6C | |||
(h=0, k=1, n=001, partialIV= 0x05, kid=[0x44, 0x6C]) | (h=0, k=1, n=001, partialIV= 0x05, kid=[0x44, 0x6C]) | |||
Content-Format: "application/oscore" | Content-Format: application/oscore | |||
Payload: | Payload: | |||
0x44025d1 ... (full payload omitted for brevity) ... 68b3825e | 0x44025d1/ ... (full payload omitted for brevity) ... /68b3825e | |||
Decrypted payload: | Decrypted payload: | |||
{ | { | |||
"client_id" : "myclient", | / client_id / 24 : "myclient", | |||
"req_cnf" : { | / req_cnf / 4 : { | |||
"COSE_Key" : { | / COSE_Key / 1 : { | |||
"kty" : "EC", | / kty / 1 : 2 / EC2 /, | |||
"kid" : h'11', | / kid / 2 : h'11', | |||
"crv" : "P-256", | / crv / -1 : 1 / P-256 /, | |||
"x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', | / x / -2 : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', | |||
"y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' | / y / -3 : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' | |||
} | } | |||
} | } | |||
} | } | |||
]]></artwork> | ]]></sourcecode> | |||
</figure></t> | </figure> | |||
<t><xref target="fig_kidATreq" format="default"/> shows a request for | ||||
<t><xref target="fig:kidATreq"/> shows a request for a token | a token | |||
where a previously communicated proof-of-possession key is only | where a previously communicated proof-of-possession key is only | |||
referenced using the "req_cnf" parameter from | referenced using the <tt>req_cnf</tt> parameter from | |||
<xref target="I-D.ietf-ace-oauth-params"/>. | <xref target="RFC9201" format="default"/>. | |||
<figure align="center" anchor="fig:kidATreq" | </t> | |||
title="Example request for an access token bound to a | <figure anchor="fig_kidATreq"> | |||
key reference."> | <name>Example Request for an Access Token Bound to a Key Reference</ | |||
<artwork align="left"><![CDATA[ | name> | |||
<sourcecode name="" type="cbor-diag"><![CDATA[ | ||||
Header: POST (Code=0.02) | Header: POST (Code=0.02) | |||
Uri-Host: "as.example.com" | Uri-Host: "as.example.com" | |||
Uri-Path: "token" | Uri-Path: "token" | |||
Content-Format: "application/ace+cbor" | Content-Format: application/ace+cbor | |||
Payload: | Payload: | |||
{ | { | |||
"client_id" : "myclient", | / client_id / 24 : "myclient", | |||
"audience" : "valve424", | / audience / 5 : "valve424", | |||
"scope" : "read", | / scope / 9 : "read", | |||
"req_cnf" : { | / req_cnf / 4 : { | |||
"kid" : b64'6kg0dXJM13U' | / kid / 3 : b64'6kg0dXJM13U' | |||
} | } | |||
} | } | |||
]]></artwork> | ]]></sourcecode> | |||
</figure></t> | </figure> | |||
<t>Refresh tokens are typically not stored as securely as | ||||
<t>Refresh tokens are typically not stored as securely as | proof-of-possession keys in requesting clients. Proof-of-possession-ba | |||
proof-of-possession keys in requesting clients. Proof-of-possession based | sed | |||
refresh token requests MUST NOT request different proof-of-possession keys | refresh token requests <bcp14>MUST NOT</bcp14> request different | |||
or different audiences in token requests. Refresh token requests can only | proof-of-possession keys | |||
use to request access tokens bound to the same proof-of-possession key and | or different audiences in token requests. Refresh token requests can o | |||
the same audience as access tokens issued in the initial token request.</t> | nly be | |||
</section> | used to request access tokens bound to the same proof-of-possession key | |||
and | ||||
<section anchor="tokenResponse" title="AS-to-Client Response"> | the same audience as access tokens issued in the initial token request. | |||
<t>If the access token request has been successfully verified by the | </t> | |||
</section> | ||||
<section anchor="tokenResponse" numbered="true" toc="default"> | ||||
<name>AS-to-Client Response</name> | ||||
<t>If the access token request has been successfully verified by the | ||||
AS and the client is authorized to obtain an access token corresponding | AS and the client is authorized to obtain an access token corresponding | |||
to its access token request, the AS sends a response with the response | to its access token request, the AS sends a response with the response | |||
code equivalent to the CoAP response code 2.01 (Created). If client | code equivalent to the CoAP response code 2.01 (Created). If the client | |||
request was invalid, or not authorized, the AS returns an error response as | request was invalid, or not authorized, the AS returns an error response, as | |||
described in <xref | described in <xref target="errorsToken" format="default"/>.</t> | |||
target="errorsToken"/>.</t> | <t>Note that the AS decides which token type and profile to use when | |||
issuing a successful response. It is assumed that the AS has prior | ||||
<t>Note that the AS decides which token type and profile to use when | knowledge of the capabilities of the client and the RS (see <xref | |||
issuing a successful response. It is assumed that the AS has prior | target="app_registration" format="default"/>). This prior knowledge ma | |||
knowledge of the capabilities of the client and the RS (see <xref | y, | |||
target="app:registration"/>). This prior knowledge may, for example, be set | for example, be set | |||
by the use of a dynamic client registration protocol exchange | by the use of a dynamic client registration protocol exchange | |||
<xref target="RFC7591"/>. If the client has requested a specific | <xref target="RFC7591" format="default"/>. If the client has requested | |||
proof-of-possession key using the "req_cnf" parameter from | a | |||
<xref target="I-D.ietf-ace-oauth-params"/>, this may also influence which | specific | |||
profile the AS selects, as it needs to support the use of the key type | proof-of-possession key using the <tt>req_cnf</tt> parameter from | |||
requested the client.</t> | <xref target="RFC9201" format="default"/>, this may also influence whic | |||
h | ||||
<t>The content of the successful reply is the Access Information. | profile the AS selects, as it needs to support the use of the key type | |||
When using CoAP, the payload MUST be encoded as a CBOR map, when using | requested by the client.</t> | |||
HTTP the encoding is a JSON map as specified in section 5.1 of <xref | <t>The content of the successful reply is the Access Information. | |||
target="RFC6749"/>. In both cases the parameters specified in Section 5.1 | When using CoAP, the payload <bcp14>MUST</bcp14> be encoded as a CBOR m | |||
of <xref target="RFC6749"/> are used, with the following additions and | ap; | |||
changes: | when using | |||
HTTP, the encoding is a JSON map, as specified in <xref target="RFC6749 | ||||
<list style="hanging"> | " | |||
<t hangText="ace_profile:"><vspace blankLines="0"/> | sectionFormat="of" section="5.1"/>. In both cases, the parameters spec | |||
OPTIONAL unless the request included an empty ace_profile parameter | ified | |||
in which case it is MANDATORY. This indicates the profile that the | in <xref target="RFC6749" sectionFormat="of" section="5.1"/> are used, | |||
client MUST use towards the RS. See <xref target="paramProfile"/> for | with | |||
the formatting of this parameter. If this parameter is absent, the AS | the following additions and changes:</t> | |||
assumes that the client implicitly knows which profile to use towards | <dl newline="true" spacing="normal" indent="6"> | |||
the RS.</t> | <dt>ace_profile:</dt> | |||
<dd>This parameter is <bcp14>OPTIONAL</bcp14> unless the request inc | ||||
<t hangText="token_type:"><vspace blankLines="0"/> | luded an | |||
This parameter is OPTIONAL, as opposed to 'required' in | empty <tt>ace_profile</tt> parameter, | |||
<xref target="RFC6749"/>. By default implementations of this framework | in which case it is MANDATORY. This indicates the profile that the | |||
SHOULD assume that the token_type is "PoP". If a specific use case | client <bcp14>MUST</bcp14> use towards the RS. See <xref | |||
requires another token_type (e.g., "Bearer") to be used then this | target="paramProfile" format="default"/> for | |||
parameter is REQUIRED. | the formatting of this parameter. If this parameter is absent, the A | |||
</t> | S | |||
</list> | assumes that the client implicitly knows which profile to use towards | |||
</t> | the RS.</dd> | |||
<dt><tt>token_type</tt>:</dt> | ||||
<t>Furthermore <xref target="I-D.ietf-ace-oauth-params"/> defines | <dd>This parameter is <bcp14>OPTIONAL</bcp14>, as opposed to | |||
additional parameters that the AS MUST be able to use when responding to a | <bcp14>REQUIRED</bcp14> in | |||
request to the token endpoint.</t> | <xref target="RFC6749" format="default"/>. By default, implementation | |||
s of | ||||
<t><xref target="fig:rsinfo"/> summarizes the parameters that | this framework | |||
can currently be part of the Access Information. Future extensions | <bcp14>SHOULD</bcp14> assume that the <tt>token_type</tt> is "PoP". | |||
may define additional parameters. | If a specific | |||
use case | ||||
<figure align="center" anchor="fig:rsinfo" | requires another <tt>token_type</tt> (e.g., "Bearer") to be used, the | |||
title="Access Information parameters"> | n this | |||
<artwork align="left"><![CDATA[ | parameter is <bcp14>REQUIRED</bcp14>. | |||
/-------------------+-------------------------------\ | </dd> | |||
| Parameter name | Specified in | | </dl> | |||
|-------------------+-------------------------------| | <t>Furthermore, <xref target="RFC9201" format="default"/> defines | |||
| access_token | RFC 6749 | | additional parameters that the AS <bcp14>MUST</bcp14> be able to use wh | |||
| token_type | RFC 6749 | | en | |||
| expires_in | RFC 6749 | | responding to a request to the token endpoint.</t> | |||
| refresh_token | RFC 6749 | | <t><xref target="table_rsinfo" format="default"/> summarizes the param | |||
| scope | RFC 6749 | | eters that | |||
| state | RFC 6749 | | can currently be part of the Access Information. Future extensions | |||
| error | RFC 6749 | | may define additional parameters.</t> | |||
| error_description | RFC 6749 | | <table anchor="table_rsinfo"> | |||
| error_uri | RFC 6749 | | <name>Access Information Parameters</name> | |||
| ace_profile | [this document] | | <thead> | |||
| cnf | [I-D.ietf-ace-oauth-params] | | <tr> | |||
| rs_cnf | [I-D.ietf-ace-oauth-params] | | <th>Parameter name</th> | |||
\-------------------+-------------------------------/ | <th>Specified in</th> | |||
]]></artwork></figure> | </tr> | |||
</thead> | ||||
</t> | <tbody> | |||
<tr> | ||||
<t><xref target="fig:symmATres"/> shows a response containing a token | <td><tt>access_token</tt></td> | |||
and a "cnf" parameter with a symmetric proof-of-possession key, which | <td><xref target="RFC6749" format="default"/></td> | |||
is defined in <xref target="I-D.ietf-ace-oauth-params"/>. Note that | </tr> | |||
the key identifier 'kid' is only used to simplify indexing and | <tr> | |||
<td><tt>token_type</tt></td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>expires_in</tt></td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>refresh_token</tt></td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>scope</tt></td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>state</tt></td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>error</tt></td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>error_description</tt></td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>error_uri</tt></td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>ace_profile</tt></td> | ||||
<td>RFC 9200</td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>cnf</tt></td> | ||||
<td><xref target="RFC9201" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>rs_cnf</tt></td> | ||||
<td><xref target="RFC9201" format="default"/></td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t><xref target="fig_symmATres" format="default"/> shows a response co | ||||
ntaining a token | ||||
and a <tt>cnf</tt> parameter with a symmetric proof-of-possession key, which | ||||
is defined in <xref target="RFC9201" format="default"/>. Note that | ||||
the key identifier <tt>kid</tt> is only used to simplify indexing and | ||||
retrieving the key, and no assumptions should be made that it is | retrieving the key, and no assumptions should be made that it is | |||
unique in the domains of either the client or the RS. | unique in the domains of either the client or the RS. | |||
<figure align="center" anchor="fig:symmATres" | </t> | |||
title="Example AS response with an access token bound to a | <figure anchor="fig_symmATres"> | |||
symmetric key."> | <name>Example AS Response with an Access Token Bound to a Symmetric | |||
<artwork align="left"><![CDATA[ | Key</name> | |||
<sourcecode name="" type="cbor-diag"><![CDATA[ | ||||
Header: Created (Code=2.01) | Header: Created (Code=2.01) | |||
Content-Format: "application/ace+cbor" | Content-Format: application/ace+cbor | |||
Payload: | Payload: | |||
{ | { | |||
"access_token" : b64'SlAV32hkKG ... | / access_token / 1 : b64'SlAV32hk'/ ... | |||
(remainder of CWT omitted for brevity; | (remainder of CWT omitted for brevity; | |||
CWT contains COSE_Key in the "cnf" claim)', | CWT contains COSE_Key in the cnf claim)/, | |||
"ace_profile" : "coap_dtls", | / ace_profile / 38 : "coap_dtls", | |||
"expires_in" : "3600", | / expires_in / 2 : 3600, | |||
"cnf" : { | / cnf / 8 : { | |||
"COSE_Key" : { | / COSE_Key / 1 : { | |||
"kty" : "Symmetric", | / kty / 1 : 4 / Symmetric /, | |||
"kid" : b64'39Gqlw', | / kid / 2 : b64'39Gqlw', | |||
"k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' | / k / -1 : b64'hJtXhkV8FJG+Onbc6mxC' | |||
} | } | |||
} | } | |||
} | } | |||
]]></artwork> | ]]></sourcecode> | |||
</figure></t> | </figure> | |||
</section> | </section> | |||
<section anchor="errorsToken" numbered="true" toc="default"> | ||||
<section anchor="errorsToken" title="Error Response"> | <name>Error Response</name> | |||
<t>The error responses for interactions with the AS are generally | <t>The error responses for interactions with the AS are generally | |||
equivalent to the ones defined in Section 5.2 of <xref target="RFC6749"/>, | equivalent to the ones defined in <xref target="RFC6749" sectionFormat="of" | |||
section="5.2"/>, | ||||
with the following exceptions: | with the following exceptions: | |||
<list style="symbols"> | </t> | |||
<t>When using CoAP the payload MUST be encoded as a CBOR map, with | <ul spacing="normal"> | |||
the Content-Format "application/ace+cbor". When using HTTP the | <li>When using CoAP, the payload <bcp14>MUST</bcp14> be encoded as a | |||
payload is encoded in JSON as specified in section 5.2 of <xref | CBOR | |||
target="RFC6749"/>.</t> | map, with | |||
the Content-Format "application/ace+cbor". When using HTTP, the | ||||
<t>A response code equivalent to the CoAP code 4.00 (Bad Request) MUST | payload is encoded in JSON, as specified in <xref target="RFC6749" | |||
be used for all error responses, except for invalid_client where a | sectionFormat="of" section="5.2"/>.</li> | |||
response code equivalent to the CoAP code 4.01 (Unauthorized) MAY be | <li>A response code equivalent to the CoAP code 4.00 (Bad Request) | |||
used under the same conditions as specified in Section 5.2 of | <bcp14>MUST</bcp14> | |||
<xref target="RFC6749"/>.</t> | be used for all error responses, except for invalid_client, where a | |||
response code equivalent to the CoAP code 4.01 (Unauthorized) | ||||
<t>The parameters "error", "error_description" and "error_uri" MUST | <bcp14>MAY</bcp14> be | |||
be abbreviated using the codes specified in <xref | used under the same conditions as specified in | |||
target="fig:cborTokenParameters"/>, when a CBOR encoding is used.</t> | <xref target="RFC6749" sectionFormat="of" section="5.2"/>.</li> | |||
<li>The parameters <tt>error</tt>, <tt>error_description</tt>, and < | ||||
<t>The error code (i.e., value of the "error" parameter) MUST be | tt>error_uri</tt> <bcp14>MUST</bcp14> | |||
abbreviated as specified in <xref | be abbreviated using the codes specified in <xref target="table_cborToken | |||
target="fig:cborErrorCodes"/>, when a CBOR encoding is used.</t> | Parameters" format="default"/>, when a CBOR encoding is used.</li> | |||
</list> | <li>The error code (i.e., value of the <tt>error</tt> parameter) <bc | |||
p14>MUST</bcp14> be | ||||
<figure align="center" anchor="fig:cborErrorCodes" | abbreviated, as specified in <xref target="table_cborErrorCodes" format=" | |||
title="CBOR abbreviations for common error codes"> | default"/>, when a CBOR encoding is used.</li> | |||
<artwork align="left"><![CDATA[ | </ul> | |||
/---------------------------+-------------\ | <table anchor="table_cborErrorCodes"> | |||
| Name | CBOR Values | | <name>CBOR Abbreviations for Common Error Codes</name> | |||
|---------------------------+-------------| | <thead> | |||
| invalid_request | 1 | | <tr> | |||
| invalid_client | 2 | | <th>Name</th> | |||
| invalid_grant | 3 | | <th>CBOR Values</th> | |||
| unauthorized_client | 4 | | <th>Original Specification</th> | |||
| unsupported_grant_type | 5 | | </tr> | |||
| invalid_scope | 6 | | </thead> | |||
| unsupported_pop_key | 7 | | <tbody> | |||
| incompatible_ace_profiles | 8 | | <tr> | |||
\---------------------------+-------------/ | <td><tt>invalid_request</tt></td> | |||
]]></artwork> | <td>1</td> | |||
</figure> | <td><xref target="RFC6749" sectionFormat="of" section="5.2"/></td | |||
</t> | > | |||
</tr> | ||||
<t>In addition to the error responses defined in OAuth 2.0, the following | <tr> | |||
behavior MUST be implemented by the AS: | <td><tt>invalid_client</tt></td> | |||
<td>2</td> | ||||
<list style="symbols"> | <td><xref target="RFC6749" sectionFormat="of" section="5.2"/></td | |||
<t>If the client submits an asymmetric key in the token request that the | > | |||
RS cannot process, the AS MUST reject that request with a response code | </tr> | |||
equivalent to the CoAP code 4.00 (Bad Request) including the error code | <tr> | |||
"unsupported_pop_key" specified in | <td><tt>invalid_grant</tt></td> | |||
<xref target="fig:cborErrorCodes"/>.</t> | <td>3</td> | |||
<td><xref target="RFC6749" sectionFormat="of" section="5.2"/></td | ||||
<t>If the client and the RS it has requested an access token for do | > | |||
not share a common profile, the AS MUST reject that request with a | </tr> | |||
response code equivalent to the CoAP code 4.00 (Bad Request) including | <tr> | |||
the error code "incompatible_ace_profiles" specified in | <td><tt>unauthorized_client</tt></td> | |||
<xref target="fig:cborErrorCodes"/>.</t> | <td>4</td> | |||
</list></t> | <td><xref target="RFC6749" sectionFormat="of" section="5.2"/></td | |||
</section> | > | |||
</tr> | ||||
<section anchor="tokenParams" | <tr> | |||
title="Request and Response Parameters"> | <td><tt>unsupported_grant_type</tt></td> | |||
<t>This section provides more detail about the new parameters that can be | <td>5</td> | |||
used in access token requests and responses, as well as abbreviations for | <td><xref target="RFC6749" sectionFormat="of" section="5.2"/></td | |||
more compact encoding of existing parameters and common parameter | > | |||
values.</t> | </tr> | |||
<tr> | ||||
<section anchor="paramGrantType" title="Grant Type"> | <td><tt>invalid_scope</tt></td> | |||
<t>The abbreviations specified in the registry defined in | <td>6</td> | |||
<xref target="IANAGrantTypeMappings"/> MUST be | <td><xref target="RFC6749" sectionFormat="of" section="5.2"/></td | |||
> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>unsupported_pop_key</tt></td> | ||||
<td>7</td> | ||||
<td>RFC 9200</td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>incompatible_ace_profiles</tt></td> | ||||
<td>8</td> | ||||
<td>RFC 9200</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t>In addition to the error responses defined in OAuth 2.0, the follow | ||||
ing | ||||
behavior <bcp14>MUST</bcp14> be implemented by the AS: | ||||
</t> | ||||
<ul spacing="normal"> | ||||
<li>If the client submits an asymmetric key in the token request tha | ||||
t the | ||||
RS cannot process, the AS <bcp14>MUST</bcp14> reject that request wit | ||||
h a | ||||
response code equivalent to the CoAP code 4.00 (Bad Request), includi | ||||
ng the | ||||
error code "unsupported_pop_key" specified in | ||||
<xref target="table_cborErrorCodes" format="default"/>.</li> | ||||
<li>If the client and the RS it has requested an access token for do | ||||
not share a common profile, the AS <bcp14>MUST</bcp14> reject that re | ||||
quest with | ||||
a response code equivalent to the CoAP code 4.00 (Bad Request), inclu | ||||
ding | ||||
the error code "incompatible_ace_profiles" specified in | ||||
<xref target="table_cborErrorCodes" format="default"/>.</li> | ||||
</ul> | ||||
</section> | ||||
<section anchor="tokenParams" numbered="true" toc="default"> | ||||
<name>Request and Response Parameters</name> | ||||
<t>This section provides more detail about the new parameters that can | ||||
be | ||||
used in access token requests and responses, as well as abbreviations f | ||||
or | ||||
more compact encoding of existing parameters and common parameter | ||||
values.</t> | ||||
<section anchor="paramGrantType" numbered="true" toc="default"> | ||||
<name>Grant Type</name> | ||||
<t>The abbreviations specified in the registry defined in | ||||
<xref target="IANAGrantTypeMappings" format="default"/> <bcp14>MUST</bcp14 | ||||
> be | ||||
used in CBOR encodings instead of the string values defined | used in CBOR encodings instead of the string values defined | |||
in <xref target="RFC6749"/>, if CBOR payloads are used. | in <xref target="RFC6749" format="default"/> if CBOR payloads are used. | |||
<figure align="center" anchor="fig:grant_types" | ||||
title="CBOR abbreviations for common grant types "> | ||||
<artwork align="left"><![CDATA[ | ||||
/--------------------+------------+------------------------\ | ||||
| Name | CBOR Value | Original Specification | | ||||
|--------------------+------------+------------------------| | ||||
| password | 0 | s. 4.3.2 of [RFC6749] | | ||||
| authorization_code | 1 | s. 4.1.3 of [RFC6749] | | ||||
| client_credentials | 2 | s. 4.4.2 of [RFC6749] | | ||||
| refresh_token | 3 | s. 6 of [RFC6749] | | ||||
\--------------------+------------+------------------------/ | ||||
]]></artwork> | ||||
</figure></t> | ||||
</section> | ||||
<section anchor="paramTokenType" title="Token Type"> | ||||
<t>The "token_type" parameter, defined in section 5.1 of <xref | ||||
target="RFC6749"/>, allows the AS to indicate to the client which type of | ||||
access token it is receiving (e.g., a bearer token). </t> | ||||
<t>This document registers the new value "PoP" for the OAuth Access | ||||
Token Types registry, specifying a proof-of-possession token. How the | ||||
proof-of-possession by the client to the RS is performed MUST be specified | ||||
by the profiles.</t> | ||||
<t>The values in the "token_type" parameter MUST use the CBOR | ||||
abbreviations defined in the registry specified by | ||||
<xref target="IANATokenTypeMappings"/>, if a CBOR encoding is used. </t> | ||||
<t>In this framework the "pop" value for the "token_type" parameter is | ||||
the default. The AS may, however, provide a different value from those | ||||
registered in <xref target="IANA.OAuthAccessTokenTypes"/>.</t> | ||||
</section> | ||||
<section anchor="paramProfile" title="Profile"> | ||||
<t>Profiles of this framework MUST define the communication | </t> | |||
protocol and the communication security protocol between the client | <table anchor="table_grant_types"> | |||
and the RS. The security protocol MUST provide encryption, integrity and | <name>CBOR Abbreviations for Common Grant Types</name> | |||
replay protection. It MUST also provide a binding between requests and | <thead> | |||
responses. Furthermore profiles MUST define a list of | <tr> | |||
allowed proof-of-possession methods, if they support proof-of-possession | <th>Name</th> | |||
tokens.</t> | <th>CBOR Value</th> | |||
<th>Original Specification</th> | ||||
</tr> | ||||
</thead> | ||||
<tbody> | ||||
<tr> | ||||
<td><tt>password</tt></td> | ||||
<td>0</td> | ||||
<td><xref target="RFC6749" sectionFormat="of" section="4.3.2"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>authorization_code</tt></td> | ||||
<td>1</td> | ||||
<td><xref target="RFC6749" sectionFormat="of" section="4.1.3"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>client_credentials</tt></td> | ||||
<td>2</td> | ||||
<td><xref target="RFC6749" sectionFormat="of" section="4.4.2"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>refresh_token</tt></td> | ||||
<td>3</td> | ||||
<td><xref target="RFC6749" sectionFormat="of" section="6"/></td | ||||
> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
<section anchor="paramTokenType" numbered="true" toc="default"> | ||||
<name>Token Type</name> | ||||
<t>The <tt>token_type</tt> parameter, defined in <xref target="RFC67 | ||||
49" | ||||
sectionFormat="of" section="5.1"/>, allows the AS to indicate to the | ||||
client which type of | ||||
access token it is receiving (e.g., a bearer token). </t> | ||||
<t>A profile MUST specify an identifier that MUST be used to uniquely | <t>This document registers the new value "PoP" for the "OAuth Access | |||
identify itself in the "ace_profile" parameter. The textual | Token Types" registry, specifying a proof-of-possession token. How | |||
the | ||||
proof of possession by the client to the RS is performed | ||||
<bcp14>MUST</bcp14> be specified by the profiles.</t> | ||||
<t>The values in the <tt>token_type</tt> parameter <bcp14>MUST</bcp1 | ||||
4> use the | ||||
CBOR abbreviations defined in the registry specified by | ||||
<xref target="IANATokenTypeMappings" format="default"/> if a CBOR | ||||
encoding is used.</t> | ||||
<t>In this framework, the "pop" value for the <tt>token_type</tt> pa | ||||
rameter is | ||||
the default. The AS may, however, provide a different value from thos | ||||
e | ||||
registered in <xref target="IANA.OAuthAccessTokenTypes" format="defau | ||||
lt"/>.</t> | ||||
</section> | ||||
<section anchor="paramProfile" numbered="true" toc="default"> | ||||
<name>Profile</name> | ||||
<t>Profiles of this framework <bcp14>MUST</bcp14> define the communi | ||||
cation | ||||
protocol and the communication security protocol between the client | ||||
and the RS. The security protocol <bcp14>MUST</bcp14> provide encryp | ||||
tion, | ||||
integrity, and | ||||
replay protection. It <bcp14>MUST</bcp14> also provide a binding betw | ||||
een | ||||
requests and | ||||
responses. Furthermore, profiles <bcp14>MUST</bcp14> define a list o | ||||
f | ||||
allowed proof-of-possession methods if they support proof-of-possessi | ||||
on | ||||
tokens.</t> | ||||
<t>A profile <bcp14>MUST</bcp14> specify an identifier that <bcp14>M | ||||
UST</bcp14> be used to uniquely | ||||
identify itself in the <tt>ace_profile</tt> parameter. The textual | ||||
representation of the profile identifier is intended for human | representation of the profile identifier is intended for human | |||
readability and for JSON-based interactions, it MUST NOT be used for | readability and for JSON-based interactions; it <bcp14>MUST NOT</bcp14> be | |||
CBOR-based interactions. Profiles MUST register their identifier in the | used for | |||
registry defined in <xref target="IANAProfile"/>. | CBOR-based interactions. Profiles <bcp14>MUST</bcp14> register their iden | |||
</t> | tifier in the | |||
registry defined in <xref target="IANAProfile" format="default"/>. | ||||
<t>Profiles MAY define additional parameters for both the token request | </t> | |||
<t>Profiles <bcp14>MAY</bcp14> define additional parameters for both | ||||
the token request | ||||
and the Access Information in the access token response in order to | and the Access Information in the access token response in order to | |||
support negotiation or signaling of profile specific parameters. | support negotiation or signaling of profile-specific parameters. | |||
</t> | </t> | |||
<t>Clients that want the AS to provide them with the <tt>ace_profile | ||||
<t>Clients that want the AS to provide them with the "ace_profile" | </tt> | |||
parameter in the access token response can indicate that by sending a | parameter in the access token response can indicate that by sending a | |||
ace_profile parameter with a null value for CBOR-based interactions, | n | |||
or an empty string if CBOR is not used, in the access token | <tt>ace_profile</tt> parameter with a null value for CBOR-based inter | |||
request.</t> | actions, | |||
</section> | or an empty string if CBOR is not used, in the access token | |||
request.</t> | ||||
<section anchor="cnonceParamToken" title="Client-Nonce"> | </section> | |||
<t>This parameter MUST be sent from the client to the AS, | <section anchor="cnonceParamToken" numbered="true" toc="default"> | |||
if it previously received a "cnonce" parameter in the "AS Request | <name>Client-Nonce</name> | |||
Creation Hints" <xref target="asInfo"/>. The parameter | <t>This parameter <bcp14>MUST</bcp14> be sent from the client to the | |||
is encoded as a byte string for CBOR-based interactions, and as a | AS | |||
string (Base64 encoded binary) if CBOR is not used. | if it previously received a <tt>cnonce</tt> parameter in the AS Reque | |||
It MUST copy the value from the cnonce parameter in the "AS Request | st | |||
Creation Hints".</t> | Creation Hints (<xref target="asInfo" format="default"/>). The param | |||
</section> | eter | |||
</section> <!--Parameters --> | is encoded as a byte string for CBOR-based interactions and as a | |||
string (base64url without padding encoded binary <xref target="RFC464 | ||||
8" | ||||
format="default"/>) if CBOR is not used. | ||||
It <bcp14>MUST</bcp14> copy the value from the <tt>cnonce</tt> parame | ||||
ter in the AS | ||||
Request Creation Hints.</t> | ||||
</section> | ||||
</section> | ||||
<section anchor="tokenCborParams" title="Mapping Parameters to CBOR"> | <section anchor="tokenCborParams" numbered="true" toc="default"> | |||
<t>If CBOR encoding is used, all OAuth parameters in access token requests | <name>Mapping Parameters to CBOR</name> | |||
and responses MUST be mapped to CBOR types as specified in the registry | <t>If CBOR encoding is used, all OAuth parameters in access token requ | |||
defined by <xref target="IANAOAuthParameterMappingsRegistry"/>, using the | ests | |||
and responses <bcp14>MUST</bcp14> be mapped to CBOR types, as specified in t | ||||
he registry | ||||
defined by <xref target="IANAOAuthParameterMappingsRegistry" format="default | ||||
"/>, using the | ||||
given integer abbreviation for the map keys.</t> | given integer abbreviation for the map keys.</t> | |||
<t>Note that we have aligned the abbreviations corresponding to claims | <t>Note that we have aligned the abbreviations corresponding to claims | |||
with the abbreviations defined in <xref target="RFC8392"/>.</t> | with the abbreviations defined in <xref target="RFC8392" format="default"/>. | |||
</t> | ||||
<t>Note also that abbreviations from -24 to 23 have a 1 byte encoding | <t>Note also that abbreviations from -24 to 23 have a 1-byte encoding | |||
size in CBOR. We have thus chosen to assign abbreviations in that | size in CBOR. We have thus chosen to assign abbreviations in that | |||
range to parameters we expect to be used most frequently in constrained | range to parameters we expect to be used most frequently in constrained | |||
scenarios.</t> | scenarios.</t> | |||
<table anchor="table_cborTokenParameters"> | ||||
<name>CBOR Mappings Used in Token Requests and Responses</name> | ||||
<thead> | ||||
<tr> | ||||
<th>Name</th> | ||||
<th>CBOR Key</th> | ||||
<th>Value Type</th> | ||||
<th>Original Specification</th> | ||||
</tr> | ||||
</thead> | ||||
<tbody> | ||||
<tr> | ||||
<td><tt>access_token</tt></td> | ||||
<td>1</td> | ||||
<td>byte string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>expires_in</tt></td> | ||||
<td>2</td> | ||||
<td>unsigned integer</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>audience</tt></td> | ||||
<td>5</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC8693" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>scope</tt></td> | ||||
<td>9</td> | ||||
<td>text or byte string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>client_id</tt></td> | ||||
<td>24</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>client_secret</tt></td> | ||||
<td>25</td> | ||||
<td>byte string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>response_type</tt></td> | ||||
<td>26</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>redirect_uri</tt></td> | ||||
<td>27</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>state</tt></td> | ||||
<td>28</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>code</tt></td> | ||||
<td>29</td> | ||||
<td>byte string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>error</tt></td> | ||||
<td>30</td> | ||||
<td>integer</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>error_description</tt></td> | ||||
<td>31</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>error_uri</tt></td> | ||||
<td>32</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>grant_type</tt></td> | ||||
<td>33</td> | ||||
<td>unsigned integer</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>token_type</tt></td> | ||||
<td>34</td> | ||||
<td>integer</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>username</tt></td> | ||||
<td>35</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>password</tt></td> | ||||
<td>36</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>refresh_token</tt></td> | ||||
<td>37</td> | ||||
<td>byte string</td> | ||||
<td><xref target="RFC6749" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>ace_profile</tt></td> | ||||
<td>38</td> | ||||
<td>integer</td> | ||||
<td>RFC 9200</td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>cnonce</tt></td> | ||||
<td>39</td> | ||||
<td>byte string</td> | ||||
<td>RFC 9200</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
</section> | ||||
<t> | <section anchor="introspectionEndpoint" numbered="true" toc="default"> | |||
<figure align="center" anchor="fig:cborTokenParameters" | <name>The Introspection Endpoint</name> | |||
title="CBOR mappings used in token requests and responses"> | <t>Token introspection <xref target="RFC7662" format="default"/> <bcp14> | |||
<artwork align="left"><![CDATA[ | MAY</bcp14> | |||
/-------------------+----------+---------------------\ | be implemented by the AS and the RS. When implemented, it <bcp14>MAY</bcp | |||
| Name | CBOR Key | Value Type | | 14> be | |||
|-------------------+----------+---------------------| | used by the RS and to query the | |||
| access_token | 1 | byte string | | AS for metadata about a given token, e.g., validity or scope. Analogous t | |||
| expires_in | 2 | unsigned integer | | o the | |||
| audience | 5 | text string | | protocol defined in <xref target="RFC7662" format="default"/> for HTTP an | |||
| scope | 9 | text or byte string | | d JSON, | |||
| client_id | 24 | text string | | this section defines adaptations to more constrained environments using | |||
| client_secret | 25 | byte string | | CBOR and | |||
| response_type | 26 | text string | | leaving the choice of the application protocol to the profile. The clien | |||
| redirect_uri | 27 | text string | | t MAY also implement and use introspection analogously to the RS to obtain infor | |||
| state | 28 | text string | | mation about a given token.</t> | |||
| code | 29 | byte string | | <t>Communication between the requesting entity and the introspection end | |||
| error | 30 | integer | | point | |||
| error_description | 31 | text string | | at the AS <bcp14>MUST</bcp14> be integrity protected and encrypted. The commu | |||
| error_uri | 32 | text string | | nication | |||
| grant_type | 33 | unsigned integer | | security protocol <bcp14>MUST</bcp14> also provide a binding between requests | |||
| token_type | 34 | integer | | and | |||
| username | 35 | text string | | responses. Furthermore, the two interacting parties <bcp14>MUST</bcp14> perfo | |||
| password | 36 | text string | | rm mutual | |||
| refresh_token | 37 | byte string | | authentication. Finally, the AS <bcp14>SHOULD</bcp14> verify that the request | |||
| ace_profile | 38 | integer | | ing entity has | |||
| cnonce | 39 | byte string | | ||||
\-------------------+----------+---------------------/ | ||||
]]></artwork> | ||||
</figure> | ||||
</t> | ||||
</section> | ||||
</section><!-- Token endpoint --> | ||||
<section anchor="introspectionEndpoint" title="The Introspection Endpoint"> | ||||
<t>Token introspection <xref target="RFC7662"/> MAY be implemented by the AS, | ||||
and the RS. When implemented, it MAY be used by the RS and to query the AS | ||||
for metadata about a given token, e.g., validity or scope. Analogous to the | ||||
protocol defined in <xref target="RFC7662"/> for HTTP and JSON, this | ||||
section defines adaptations to more constrained environments using CBOR and | ||||
leaving the choice of the application protocol to the profile.</t> | ||||
<t>Communication between the requesting entity and the introspection endpoint | ||||
at the AS MUST be integrity protected and encrypted. The communication | ||||
security protocol MUST also provide a binding between requests and | ||||
responses. Furthermore, the two interacting parties MUST perform mutual | ||||
authentication. Finally, the AS SHOULD verify that the requesting entity has | ||||
the right to access introspection information about the provided token. | the right to access introspection information about the provided token. | |||
Profiles of this framework that support introspection MUST specify how | Profiles of this framework that support introspection <bcp14>MUST</bcp14> spec ify how | |||
authentication and communication security between the requesting | authentication and communication security between the requesting | |||
entity and the AS is implemented.</t> | entity and the AS is implemented.</t> | |||
<t> The default name of this endpoint in a url-path <bcp14>SHOULD</bcp14 | ||||
<t> The default name of this endpoint in an url-path SHOULD be '/introspect'. | > be '/introspect'. | |||
However, implementations are not required to use this name and can define | However, implementations are not required to use this name and can define | |||
their own instead.</t> | their own instead.</t> | |||
<section anchor="introReq" numbered="true" toc="default"> | ||||
<t>The figures of this section use the CBOR diagnostic | <name>Introspection Request</name> | |||
notation without the integer abbreviations for the parameters and their | <t>The requesting entity sends a POST request to the introspection end | |||
values for better readability. | point | |||
</t> | at the AS. The profile <bcp14>MUST</bcp14> specify how the communication is | |||
protected. | ||||
<section anchor="introReq" title="Introspection Request"> | If CoAP is used, the payload <bcp14>MUST</bcp14> be encoded as a CBOR map wi | |||
<t>The requesting entity sends a POST request to the introspection endpoint | th a <tt>token</tt> | |||
at the AS. The profile MUST specify how the communication is protected. | ||||
If CoAP is used, the payload MUST be encoded as a CBOR map with a "token" | ||||
entry containing the access token. Further optional parameters | entry containing the access token. Further optional parameters | |||
representing additional context that is known by the requesting entity to | representing additional context that is known by the requesting entity to | |||
aid the AS in its response MAY be included.</t> | aid the AS in its response <bcp14>MAY</bcp14> be included.</t> | |||
<t>For CoAP-based interaction, all messages <bcp14>MUST</bcp14> use th | ||||
<t>For CoAP-based interaction, all messages MUST use the content type | e content | |||
"application/ace+cbor". For HTTP the encoding defined in section 2.1 | type "application/ace+cbor". For HTTP, the encoding defined in | |||
of <xref target="RFC7662"/> is used.</t> | <xref target="RFC7662" sectionFormat="of" section="2.1"/> is used.</t> | |||
<t>The same parameters are required and optional as in | ||||
<t>The same parameters are required and optional as in Section 2.1 | <xref target="RFC7662" sectionFormat="of" section="2.1"/>.</t> | |||
of <xref target="RFC7662"/>.</t> | <t>For example, <xref target="fig_introReq" format="default"/> shows a | |||
n RS | ||||
<t>For example, <xref target="fig:introReq"/> shows an RS calling the token | calling the token | |||
introspection endpoint at the AS to query about an OAuth 2.0 | introspection endpoint at the AS to query about an OAuth 2.0 | |||
proof-of-possession token. Note that object security based on OSCORE | proof-of-possession token. Note that object security based on OSCORE | |||
<xref target="RFC8613"/> is assumed in this example, | <xref target="RFC8613" format="default"/> is assumed in this example; | |||
therefore the Content-Format is "application/oscore". <xref | therefore, the Content-Format is "application/oscore". <xref | |||
target="fig:introReq-payl"/> shows the decoded payload. | target="fig_introReq-payl" format="default"/> shows the decoded payload | |||
.</t> | ||||
<figure align="center" anchor="fig:introReq" | <figure anchor="fig_introReq"> | |||
title="Example introspection request."> | <name>Example Introspection Request</name> | |||
<artwork align="left"><![CDATA[ | <sourcecode name="" type=""><![CDATA[ | |||
Header: POST (Code=0.02) | Header: POST (Code=0.02) | |||
Uri-Host: "as.example.com" | Uri-Host: "as.example.com" | |||
Uri-Path: "introspect" | Uri-Path: "introspect" | |||
OSCORE: 0x09, 0x05, 0x25 | OSCORE: 0x09, 0x05, 0x25 | |||
Content-Format: "application/oscore" | Content-Format: application/oscore | |||
Payload: | Payload: | |||
... COSE content ... | ... COSE content ... | |||
]]></artwork> | ]]></sourcecode> | |||
</figure> | </figure> | |||
<figure align="center" anchor="fig:introReq-payl" | <figure anchor="fig_introReq-payl"> | |||
title="Decoded payload."> | <name>Decoded Payload</name> | |||
<artwork align="left"><![CDATA[ | <sourcecode name="" type="cbor-diag"><![CDATA[ | |||
{ | { | |||
"token" : b64'7gj0dXJQ43U', | / token / 11 : b64'7gj0dXJQ43U', | |||
"token_type_hint" : "PoP" | / token_type_hint / 33 : 2 / PoP / | |||
} | } | |||
]]></artwork> | ]]></sourcecode> | |||
</figure></t> | </figure> | |||
</section> | ||||
</section> | <section anchor="introRes" numbered="true" toc="default"> | |||
<name>Introspection Response</name> | ||||
<section anchor="introRes" title="Introspection Response"> | <t>If the introspection request is authorized and successfully process | |||
<t>If the introspection request is authorized and successfully processed, | ed, | |||
the AS sends a response with the response code equivalent to the CoAP code | the AS sends a response with the response code equivalent to the CoAP c | |||
2.01 (Created). If the introspection request was invalid, not authorized | ode | |||
or couldn't be processed the AS returns an error response as described in | 2.01 (Created). If the introspection request was invalid, not authoriz | |||
<xref target="errorsIntro"/>.</t> | ed, | |||
or couldn't be processed, the AS returns an error response, as describe | ||||
<t>In a successful response, the AS encodes the response parameters in | d in | |||
a map. If CoAP is used, this MUST be encoded as a CBOR map, if HTTP is | <xref target="errorsIntro" format="default"/>.</t> | |||
used the JSON encoding specified in section 2.2 of <xref target="RFC7662"/> | <t>In a successful response, the AS encodes the response parameters in | |||
is used. The map containing the response payload includes the same | a map. If CoAP is used, this <bcp14>MUST</bcp14> be encoded as a CBOR | |||
required and optional parameters as in Section 2.2 of | map; if | |||
<xref target="RFC7662"/> with the following additions: | HTTP is used, the JSON encoding specified in <xref target="RFC7662" | |||
sectionFormat="of" section="2.2"/> | ||||
<list style="hanging"> | is used. The map containing the response payload includes the same | |||
<t hangText="ace_profile"> | required and optional parameters as in | |||
OPTIONAL. This indicates the profile that the RS MUST use with the | <xref target="RFC7662" sectionFormat="of" section="2.2"/>, with the fol | |||
client. See <xref target="paramProfile"/> for more details on the | lowing | |||
formatting of this parameter. If this parameter is absent, the AS | additions:</t> | |||
assumes that the RS implicitly knows which profile to use towards | <dl newline="true" spacing="normal"> | |||
the client.</t> | <dt><tt>ace_profile</tt></dt> | |||
<t hangText="cnonce"> | <dd>This parameter is <bcp14>OPTIONAL</bcp14>. This indicates the p | |||
OPTIONAL. A client-nonce provided to the AS by the client. | rofile that | |||
The RS MUST verify that this corresponds to the client-nonce | the RS <bcp14>MUST</bcp14> use with the | |||
previously provided to the client in the "AS Request Creation | client. See <xref target="paramProfile" format="default"/> for more | |||
Hints". See <xref target="asInfo"/> and | details on | |||
<xref target="cnonceParamToken"/>. | the formatting of this parameter. If this parameter is absent, the AS | |||
</t> | assumes that the RS implicitly knows which profile to use towards | |||
<t hangText="exi"> | the client.</dd> | |||
OPTIONAL. The "expires-in" claim associated to this access token. | <dt><tt>cnonce</tt></dt> | |||
See <xref target="tokenExpiration"/>. | <dd>This parameter is <bcp14>OPTIONAL</bcp14>. This is a | |||
</t> | client-nonce provided to the AS by the client. | |||
</list> | The RS <bcp14>MUST</bcp14> verify that this corresponds to the | |||
</t> | client-nonce | |||
previously provided to the client in the AS Request Creation | ||||
<t>Furthermore <xref target="I-D.ietf-ace-oauth-params"/> defines | Hints. See Sections <xref target="asInfo" format="counter"/> and | |||
more parameters that the AS MUST be able to use when responding to a | <xref target="cnonceParamToken" format="counter"/>. Its value is a | |||
byte string when encoded in CBOR and is the base64url encoding of thi | ||||
s | ||||
byte string without padding when encoded in JSON <xref | ||||
target="RFC4648" format="default"/>. | ||||
</dd> | ||||
<dt><tt>cti</tt></dt> | ||||
<dd>This parameter is <bcp14>OPTIONAL</bcp14>. This is the <tt>cti</ | ||||
tt> claim | ||||
associated to this access token. | ||||
This parameter has the same meaning and processing rules as the | ||||
<tt>jti</tt> parameter defined in <xref target="RFC7662" sectionForma | ||||
t="of" | ||||
section="3.1.2"/> except that its value is a byte string when encoded | ||||
in CBOR and is the base64url encoding of this byte string without | ||||
padding when encoded in JSON <xref target="RFC4648" | ||||
format="default"/>.</dd> | ||||
<dt><tt>exi</tt></dt> | ||||
<dd>This parameter is <bcp14>OPTIONAL</bcp14>. This is the | ||||
<tt>expires_in</tt> claim associated to this access token. | ||||
See <xref target="tokenExpiration" format="default"/>. | ||||
</dd> | ||||
</dl> | ||||
<t>Furthermore, <xref target="RFC9201" format="default"/> defines | ||||
more parameters that the AS <bcp14>MUST</bcp14> be able to use when respondi | ||||
ng to a | ||||
request to the introspection endpoint.</t> | request to the introspection endpoint.</t> | |||
<t>For example, <xref target="fig_introRes" format="default"/> shows a | ||||
n AS | ||||
response to the introspection request in <xref target="fig_introReq" format= | ||||
"default"/>. | ||||
Note that this example contains the <tt>cnf</tt> parameter defined in | ||||
<xref target="RFC9201" format="default"/>. | ||||
<t>For example, <xref target="fig:introRes"/> shows an AS | </t> | |||
response to the introspection request in <xref target="fig:introReq"/>. | <figure anchor="fig_introRes"> | |||
Note that this example contains the "cnf" parameter defined in | <name>Example Introspection Response</name> | |||
<xref target="I-D.ietf-ace-oauth-params"/>. | <sourcecode name="" type="cbor-diag"><![CDATA[ | |||
<figure align="center" anchor="fig:introRes" | ||||
title="Example introspection response."> | ||||
<artwork align="left"><![CDATA[ | ||||
Header: Created (Code=2.01) | Header: Created (Code=2.01) | |||
Content-Format: "application/ace+cbor" | Content-Format: application/ace+cbor | |||
Payload: | Payload: | |||
{ | { | |||
"active" : true, | / active / 10 : true, | |||
"scope" : "read", | / scope / 9 : "read", | |||
"ace_profile" : "coap_dtls", | / ace_profile / 38 : 1 / coap_dtls /, | |||
"cnf" : { | / cnf / 8 : { | |||
"COSE_Key" : { | / COSE_Key / 1 : { | |||
"kty" : "Symmetric", | / kty / 1 : 4 / Symmetric /, | |||
"kid" : b64'39Gqlw', | / kid / 2 : b64'39Gqlw', | |||
"k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' | / k / -1 : b64'hJtXhkV8FJG+Onbc6mxC' | |||
} | } | |||
} | } | |||
} | } | |||
]]></artwork> | ]]></sourcecode> | |||
</figure></t> | </figure> | |||
</section> | </section> | |||
<section anchor="errorsIntro" numbered="true" toc="default"> | ||||
<section anchor="errorsIntro" title="Error Response"> | <name>Error Response</name> | |||
<t>The error responses for CoAP-based interactions with the AS | <t>The error responses for CoAP-based interactions with the AS | |||
are equivalent to the ones for HTTP-based interactions as defined in | are equivalent to the ones for HTTP-based interactions, as defined in | |||
Section 2.3 of <xref target="RFC7662"/>, with the following differences: | <xref target="RFC7662" sectionFormat="of" section="2.3"/>, with the | |||
following differences:</t> | ||||
<list style="symbols"> | <ul spacing="normal"> | |||
<t>If content is sent and CoAP is used the payload MUST be encoded as a | <li>If content is sent and CoAP is used, the payload <bcp14>MUST</bc | |||
CBOR map and the Content-Format "application/ace+cbor" MUST be used. | p14> be | |||
For HTTP the encoding defined in section 2.3 of <xref target="RFC6749"/> | encoded as a | |||
is used.</t> | CBOR map and the Content-Format "application/ace+cbor" <bcp14>MUST</b | |||
cp14> | ||||
<t>If the credentials used by the requesting entity (usually the RS) | be used. | |||
are invalid the AS MUST respond with the response code equivalent to the | For HTTP, the encoding defined in <xref target="RFC6749" sectionForma | |||
CoAP code 4.01 (Unauthorized) and use the required and optional | t="of" | |||
parameters from Section 2.3 in <xref target="RFC7662"/>.</t> | section="2.3"/> is used.</li> | |||
<li>If the credentials used by the requesting entity (usually the RS | ||||
<t>If the requesting entity does not have the right to perform this | ) | |||
introspection request, the AS MUST respond with a response code | are invalid, the AS <bcp14>MUST</bcp14> respond with the response cod | |||
equivalent to the CoAP code 4.03 (Forbidden). In this case no payload is | e | |||
returned.</t> | equivalent to the | |||
CoAP code 4.01 (Unauthorized) and use the required and optional | ||||
<t>The parameters "error", "error_description" and "error_uri" MUST | parameters from <xref target="RFC7662" sectionFormat="of" | |||
be abbreviated using the codes specified in <xref | section="2.3"/>.</li> | |||
target="fig:cborTokenParameters"/>.</t> | <li>If the requesting entity does not have the right to perform this | |||
introspection request, the AS <bcp14>MUST</bcp14> respond with a response | ||||
<t>The error codes MUST be abbreviated using the codes specified in | code | |||
the registry defined by <xref target="IANAErrorCBORMappings"/>.</t> | equivalent to the CoAP code 4.03 (Forbidden). In this case, no payload is | |||
</list> | returned.</li> | |||
</t> | <li>The parameters <tt>error</tt>, <tt>error_description</tt>, and < | |||
tt>error_uri</tt> <bcp14>MUST</bcp14> | ||||
<t>Note that a properly formed and authorized query for an inactive or | be abbreviated using the codes specified in <xref target="table_cborTokenP | |||
arameters" format="default"/>.</li> | ||||
<li>The error codes <bcp14>MUST</bcp14> be abbreviated using the cod | ||||
es specified in | ||||
the registry defined by <xref target="IANAErrorCBORMappings" format="defau | ||||
lt"/>.</li> | ||||
</ul> | ||||
<t>Note that a properly formed and authorized query for an inactive or | ||||
otherwise invalid token does not warrant an error response by this | otherwise invalid token does not warrant an error response by this | |||
specification. In these cases, the authorization server MUST instead | specification. In these cases, the authorization server <bcp14>MUST</bcp14> | |||
respond with an introspection response with the "active" field set to | instead | |||
respond with an introspection response with the <tt>active</tt> field set to | ||||
"false".</t> | "false".</t> | |||
</section> | </section> | |||
<section anchor="introParamsCbor" numbered="true" toc="default"> | ||||
<section anchor="introParamsCbor" | <name>Mapping Introspection Parameters to CBOR</name> | |||
title="Mapping Introspection Parameters to CBOR"> | <t>If CBOR is used, the introspection request and response parameters | |||
<t>If CBOR is used, the introspection request and response parameters MUST | <bcp14>MUST</bcp14> | |||
be mapped to CBOR types as specified in the registry defined by <xref | be mapped to CBOR types, as specified in the registry defined by <xref targe | |||
target="IANAIntrospectionEndpointCBORMappingsRegistry"/>, using the given | t="IANAIntrospectionEndpointCBORMappingsRegistry" format="default"/>, using the | |||
given | ||||
integer abbreviation for the map key.</t> | integer abbreviation for the map key.</t> | |||
<t>Note that we have aligned abbreviations that correspond to a | ||||
<t>Note that we have aligned abbreviations that correspond to a | claim with the abbreviations defined in <xref target="RFC8392" format="defau | |||
claim with the abbreviations defined in <xref target="RFC8392"/> | lt"/> | |||
and the abbreviations of parameters with the same name from | and the abbreviations of parameters with the same name from | |||
<xref target="tokenCborParams"/>. | <xref target="tokenCborParams" format="default"/>. | |||
</t> | ||||
<figure align="center" anchor="fig:cborIntrospectionParameters" | <table anchor="table_cborIntrospectionParameters"> | |||
title="CBOR Mappings to Token Introspection Parameters."> | <name>CBOR Mappings for Token Introspection Parameters</name> | |||
<artwork align="left"><![CDATA[ | <thead> | |||
/-------------------+----------+-------------------------\ | <tr> | |||
| Parameter name | CBOR Key | Value Type | | <th>Parameter name</th> | |||
|-------------------+----------+-------------------------| | <th>CBOR Key</th> | |||
| iss | 1 | text string | | <th>Value Type</th> | |||
| sub | 2 | text string | | <th>Original Specification</th> | |||
| aud | 3 | text string | | </tr> | |||
| exp | 4 | integer or | | </thead> | |||
| | | floating-point number | | <tbody> | |||
| nbf | 5 | integer or | | <tr> | |||
| | | floating-point number | | <td><tt>iss</tt></td> | |||
| iat | 6 | integer or | | <td>1</td> | |||
| | | floating-point number | | <td>text string</td> | |||
| cti | 7 | byte string | | <td><xref target="RFC7662" format="default"/></td> | |||
| scope | 9 | text or byte string | | </tr> | |||
| active | 10 | True or False | | <tr> | |||
| token | 11 | byte string | | <td><tt>sub</tt></td> | |||
| client_id | 24 | text string | | <td>2</td> | |||
| error | 30 | integer | | <td>text string</td> | |||
| error_description | 31 | text string | | <td><xref target="RFC7662" format="default"/></td> | |||
| error_uri | 32 | text string | | </tr> | |||
| token_type_hint | 33 | text string | | <tr> | |||
| token_type | 34 | integer | | <td><tt>aud</tt></td> | |||
| username | 35 | text string | | <td>3</td> | |||
| ace_profile | 38 | integer | | <td>text string</td> | |||
| cnonce | 39 | byte string | | <td><xref target="RFC7662" format="default"/></td> | |||
| exi | 40 | unsigned integer | | </tr> | |||
\-------------------+----------+-------------------------/ | <tr> | |||
]]></artwork> | <td><tt>exp</tt></td> | |||
</figure> | <td>4</td> | |||
</t> | <td>integer or floating-point number</td> | |||
</section> | <td><xref target="RFC7662" format="default"/></td> | |||
</tr> | ||||
</section><!-- introspection endpoint --> | <tr> | |||
<td><tt>nbf</tt></td> | ||||
<section anchor="accessToken" title="The Access Token"> | <td>5</td> | |||
<t>In this framework the use of CBOR Web Token (CWT) as | <td>integer or floating-point number</td> | |||
specified in <xref target="RFC8392"/> is RECOMMENDED. | <td><xref target="RFC7662" format="default"/></td> | |||
</t> | </tr> | |||
<tr> | ||||
<td><tt>iat</tt></td> | ||||
<td>6</td> | ||||
<td>integer or floating-point number</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>cti</tt></td> | ||||
<td>7</td> | ||||
<td>byte string</td> | ||||
<td>RFC 9200</td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>scope</tt></td> | ||||
<td>9</td> | ||||
<td>text or byte string</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>active</tt></td> | ||||
<td>10</td> | ||||
<td>True or False</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>token</tt></td> | ||||
<td>11</td> | ||||
<td>byte string</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>client_id</tt></td> | ||||
<td>24</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>error</tt></td> | ||||
<td>30</td> | ||||
<td>integer</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>error_description</tt></td> | ||||
<td>31</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>error_uri</tt></td> | ||||
<td>32</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>token_type_hint</tt></td> | ||||
<td>33</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>token_type</tt></td> | ||||
<td>34</td> | ||||
<td>integer</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>username</tt></td> | ||||
<td>35</td> | ||||
<td>text string</td> | ||||
<td><xref target="RFC7662" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>ace_profile</tt></td> | ||||
<td>38</td> | ||||
<td>integer</td> | ||||
<td>RFC 9200</td> | ||||
</tr> | ||||
<tr> | ||||
<td><tt>cnonce</tt></td> | ||||
<td>39</td> | ||||
<td>byte string</td> | ||||
<td>RFC 9200</td> | ||||
</tr> | ||||
<tr> | ||||
<td>exi</td> | ||||
<td>40</td> | ||||
<td>unsigned integer</td> | ||||
<td>RFC 9200</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
</section> | ||||
<t>In order to facilitate offline processing of access tokens, | <section anchor="accessToken" numbered="true" toc="default"> | |||
this document uses the "cnf" claim from <xref | <name>The Access Token</name> | |||
target="RFC8747"/> and the "scope" claim from <xref target="RFC8693"/> for | <t>In this framework, the use of CBOR Web Token (CWT) as | |||
specified in <xref target="RFC8392" format="default"/> is <bcp14>RECOMMENDED | ||||
</bcp14>. | ||||
</t> | ||||
<t>In order to facilitate offline processing of access tokens, | ||||
this document uses the <tt>cnf</tt> claim from <xref target="RFC8747" format=" | ||||
default"/> | ||||
and the <tt>scope</tt> claim from <xref target="RFC8693" format="default"/> fo | ||||
r | ||||
JWT- and CWT-encoded tokens. In addition to string encoding specified for | JWT- and CWT-encoded tokens. In addition to string encoding specified for | |||
the "scope" claim, a binary encoding MAY be used. The syntax of such an | the <tt>scope</tt> claim, a binary encoding <bcp14>MAY</bcp14> be used. The s yntax of such an | |||
encoding is explicitly not specified here and left to profiles or | encoding is explicitly not specified here and left to profiles or | |||
applications, specifically note that a binary encoded scope does not | applications, specifically note that a binary encoded scope does not | |||
necessarily use the space character '0x20' to delimit scope-tokens.</t> | necessarily use the space character '0x20' to delimit scope-tokens.</t> | |||
<t>If the AS needs to convey a hint to the RS about which profile it | ||||
<t>If the AS needs to convey a hint to the RS about which profile it | should use to communicate with the client, the AS <bcp14>MAY</bcp14> include a | |||
should use to communicate with the client, the AS MAY include an | n | |||
"ace_profile" claim in the access token, with the same syntax and semantics | <tt>ace_profile</tt> claim in the access token, with the same syntax and seman | |||
as defined in <xref target="paramProfile"/>.</t> | tics | |||
as defined in <xref target="paramProfile" format="default"/>.</t> | ||||
<t>If the client submitted a client-nonce parameter in the access token | <t>If the client submitted a <tt>cnonce</tt> parameter in the access tok | |||
request <xref target="cnonceParamToken"/>, the AS MUST include the value of | en | |||
this parameter in the "cnonce" claim specified here. The "cnonce" claim | request (<xref target="cnonceParamToken" format="default"/>), the AS | |||
uses binary encoding.</t> | <bcp14>MUST</bcp14> include the value of | |||
this parameter in the <tt>cnonce</tt> claim specified here. The <tt>cnon | ||||
<section anchor="tokenAuthInfoEndpoint" | ce</tt> claim | |||
title="The Authorization Information Endpoint"> | uses binary encoding.</t> | |||
<t>The access token, containing authorization information and information | <section anchor="tokenAuthInfoEndpoint" numbered="true" toc="default"> | |||
<name>The Authorization Information Endpoint</name> | ||||
<t>The access token, containing authorization information and informat | ||||
ion | ||||
about the proof-of-possession method used by the client, needs to be | about the proof-of-possession method used by the client, needs to be | |||
transported to the RS so that the RS can authenticate and authorize the | transported to the RS so that the RS can authenticate and authorize the | |||
client request.</t> | client request.</t> | |||
<t>This section defines a method for transporting the access token to | ||||
<t>This section defines a method for transporting the access token to the RS | the RS | |||
using a RESTful protocol such as CoAP. Profiles of this framework MAY define | using a RESTful protocol, such as CoAP. Profiles of this framework <bcp14>MAY< | |||
/bcp14> define | ||||
other methods for token transport. | other methods for token transport. | |||
</t> | </t> | |||
<t>The method consists of an authz-info endpoint, implemented by the | ||||
<t>The method consists of an authz-info endpoint, implemented by the | RS. A client using this method <bcp14>MUST</bcp14> make a POST request to the | |||
RS. A client using this method MUST make a POST request to the authz-info | authz-info | |||
endpoint at the RS with the access token in the payload. The CoAP | endpoint at the RS with the access token in the payload. The CoAP | |||
Content-Format or HTTP Media Type MUST reflect the format of the token, | Content-Format or HTTP media type <bcp14>MUST</bcp14> reflect the format of th | |||
e.g. application/cwt for CBOR Web Tokens, if no Content-Format or Media | e token, | |||
Type is defined for the token format, application/octet-stream MUST be | e.g., "application/cwt", for CBOR Web Tokens; if no Content-Format or media | |||
type is defined for the token format, "application/octet-stream" <bcp14>MUST</ | ||||
bcp14> be | ||||
used.</t> | used.</t> | |||
<t>The RS receiving the token <bcp14>MUST</bcp14> verify the validity | ||||
<t>The RS receiving the token MUST verify the validity of the token. If the | of the | |||
token is valid, the RS MUST respond to the POST request with a response code | token. If the | |||
equivalent to CoAP's 2.01 (Created). | token is valid, the RS <bcp14>MUST</bcp14> respond to the POST request | |||
<xref target="verifyToken"/> outlines how an RS MUST proceed to verify the | with a | |||
response code equivalent to CoAP code 2.01 (Created). | ||||
<xref target="verifyToken" format="default"/> outlines how an RS <bcp14>MUST</ | ||||
bcp14> proceed to verify the | ||||
validity of an access token.</t> | validity of an access token.</t> | |||
<t>The RS <bcp14>MUST</bcp14> be prepared to store at least one access | ||||
<t>The RS MUST be prepared to store at least one access token for future | token for future | |||
use. This is a difference to how access tokens are handled in OAuth 2.0, | use. This is a difference as to how access tokens are handled in OAuth 2.0, | |||
where the access token is typically sent along with each request, and | where the access token is typically sent along with each request and | |||
therefore not stored at the RS.</t> | therefore not stored at the RS.</t> | |||
<t>When using this framework, it is <bcp14>RECOMMENDED</bcp14> that an | ||||
<t>When using this framework it is RECOMMENDED that an RS stores only one | RS stores | |||
token per proof-of-possession key. This means that an additional token linked | only one token per proof-of-possession key. This means that an additio | |||
to the same key will supersede any existing token at the RS, by replacing | nal token | |||
the corresponding authorization information. The reason is that | linked to the same key will supersede any existing token at the RS by r | |||
this greatly simplifies (constrained) implementations, with respect to | eplacing | |||
required storage and resolving a request to the applicable token. The use of | the corresponding authorization information. The reason is that | |||
multiple access tokens for a single client increases the strain on the | this greatly simplifies (constrained) implementations, with respect to | |||
resource server as it must consider every access token and calculate the | required storage and resolving a request to the applicable token. The | |||
actual permissions of the client. Also, tokens may contradict each other | use of | |||
which may lead the server to enforce wrong permissions. If one of the access | multiple access tokens for a single client increases the strain on the | |||
tokens expires earlier than others, the resulting permissions may offer | resource server, as it must consider every access token and calculate t | |||
insufficient protection. | he | |||
</t> | actual permissions of the client. Also, tokens may contradict each oth | |||
er, | ||||
<t>If the payload sent to the authz-info endpoint does not parse | which may lead the server to enforce wrong permissions. If one of the | |||
to a token, the RS MUST respond with a response code equivalent to the CoAP | access | |||
tokens expires earlier than others, the resulting permissions may offer | ||||
insufficient protection. | ||||
</t> | ||||
<t>If the payload sent to the authz-info endpoint does not parse | ||||
to a token, the RS <bcp14>MUST</bcp14> respond with a response code equivalent | ||||
to the CoAP | ||||
code 4.00 (Bad Request).</t> | code 4.00 (Bad Request).</t> | |||
<t>The RS <bcp14>MAY</bcp14> make an introspection request to validate | ||||
<t>The RS MAY make an introspection request to validate the token before | the token before | |||
responding to the POST request to the authz-info endpoint, e.g. if the | responding to the POST request to the authz-info endpoint, e.g., if the | |||
token is an opaque reference. Some transport protocols may provide a way to | token is an opaque reference. Some transport protocols may provide a way to | |||
indicate that the RS is busy and the client should retry after an interval; | indicate that the RS is busy and the client should retry after an interval; | |||
this type of status update would be appropriate while the RS is waiting for | this type of status update would be appropriate while the RS is waiting for | |||
an introspection response. | an introspection response. | |||
</t> | </t> | |||
<t>Profiles <bcp14>MUST</bcp14> specify whether the authz-info endpoin | ||||
<t>Profiles MUST specify whether the authz-info endpoint is protected, | t is protected, | |||
including whether error responses from this endpoint are protected. Note that | including whether error responses from this endpoint are protected. Note that | |||
since the token contains information that allow the client and the RS to | since the token contains information that allows the client and the RS to | |||
establish a security context in the first place, mutual authentication may | establish a security context in the first place, mutual authentication may | |||
not be possible at this point.</t> | not be possible at this point.</t> | |||
<t>The default name of this endpoint in a url-path is '/authz-info'; | ||||
<t>The default name of this endpoint in an url-path is '/authz-info', | however, implementations are not required to use this name and can defi | |||
however implementations are not required to use this name and can define | ne | |||
their own instead.</t> | their own instead.</t> | |||
<section anchor="verifyToken" numbered="true" toc="default"> | ||||
<section anchor="verifyToken" title="Verifying an Access Token"> | <name>Verifying an Access Token</name> | |||
<t>When an RS receives an access token, it MUST verify it before storing | <t>When an RS receives an access token, it <bcp14>MUST</bcp14> verif | |||
y it before storing | ||||
it. The details of token verification depends on various aspects, including | it. The details of token verification depends on various aspects, including | |||
the token encoding, the type of token, the security protection applied to | the token encoding, the type of token, the security protection applied to | |||
the token, and the claims. The token encoding matters since the security | the token, and the claims. The token encoding matters since the security | |||
protection differs between the token encodings. For example, a CWT token | protection differs between the token encodings. For example, a CWT token | |||
uses COSE while a JWT token uses JOSE. The type of token also has an | uses COSE, while a JWT token uses JSON Object Signing and Encryption (JOSE). | |||
influence on the verification procedure since tokens may be self-contained | The type of token also has an | |||
whereby token verification may happen locally at the RS while a | influence on the verification procedure since tokens may be self-contained, | |||
token-by-reference requires further interaction with the authorization | whereby token verification may happen locally at the RS, while a | |||
server, for example using token introspection, to obtain the claims | reference token requires further interaction with the authorization | |||
associated with the token reference. Self-contained tokens MUST, at | server, for example, using token introspection, to obtain the claims | |||
least be integrity protected but they MAY also be encrypted.</t> | associated with the token reference. Self-contained tokens <bcp14>MUST</bcp | |||
14> at | ||||
<t>For self-contained tokens the RS MUST process the security | least be integrity protected, but they <bcp14>MAY</bcp14> also be encrypted. | |||
protection of the token first, as specified by the respective token format. | </t> | |||
For CWT the description can be found in <xref target="RFC8392"/> and for | <t>For self-contained tokens, the RS <bcp14>MUST</bcp14> process the | |||
JWT the relevant specification is <xref target="RFC7519"/>. This MUST | security | |||
include a verification that security protection (and thus the token) was | protection of the token first, as specified by the respective token f | |||
generated by an AS that has the right to issue access tokens for this | ormat. | |||
RS.</t> | For CWT, the description can be found in <xref target="RFC8392" | |||
format="default"/>; for | ||||
<t>In case the token is communicated by reference the RS needs to obtain | JWT, the relevant specification is <xref target="RFC7519" format="def | |||
the claims first. When the RS uses token introspection the relevant | ault"/>. | |||
specification is <xref target="RFC7662"/> with CoAP transport specified in | This <bcp14>MUST</bcp14> | |||
<xref target="introspectionEndpoint"/>. </t> | include a verification that security protection (and thus the token) | |||
was | ||||
<t>Errors may happen during this initial processing stage: | generated by an AS that has the right to issue access tokens for this | |||
<list style="symbols"> | RS.</t> | |||
<t>In case the token is communicated by reference, the RS needs to o | ||||
<t>If the verification of the security wrapper fails, or the token | btain | |||
the claims first. When the RS uses token introspection, the relevant | ||||
specification is <xref target="RFC7662" format="default"/> with CoAP transpo | ||||
rt specified in | ||||
<xref target="introspectionEndpoint" format="default"/>. </t> | ||||
<t>Errors may happen during this initial processing stage: | ||||
</t> | ||||
<ul spacing="normal"> | ||||
<li>If the verification of the security wrapper fails, or the toke | ||||
n | ||||
was issued by an AS that does not have the right to issue tokens | was issued by an AS that does not have the right to issue tokens | |||
for the receiving RS, the RS MUST discard the token | for the receiving RS, the RS <bcp14>MUST</bcp14> discard the token | |||
and, if this was an interaction with authz-info, return an error | and, if this was an interaction with authz-info, return an error | |||
message with a response code equivalent to the CoAP code 4.01 | message with a response code equivalent to the CoAP code 4.01 | |||
(Unauthorized).</t> | (Unauthorized).</li> | |||
<li>If the claims cannot be obtained, the RS <bcp14>MUST</bcp14> d | ||||
<t>If the claims cannot be obtained the RS MUST discard the token and, | iscard the token and, | |||
in case of an interaction via the authz-info endpoint, return an error | in case of an interaction via the authz-info endpoint, return an error | |||
message with a response code equivalent to the CoAP code 4.00 (Bad | message with a response code equivalent to the CoAP code 4.00 (Bad | |||
Request).</t> | Request).</li> | |||
</list> | </ul> | |||
</t> | <t>Next, the RS <bcp14>MUST</bcp14> verify claims, if present, conta | |||
ined in the | ||||
<t>Next, the RS MUST verify claims, if present, contained in the access | access | |||
token. Errors are returned when claim checks fail, in the order of | token. Errors are returned when claim checks fail, in the order of | |||
priority of this list: | priority of this list: | |||
</t> | ||||
<list style="hanging"> | <dl newline="true" spacing="normal"> | |||
<t hangText="iss">The issuer claim (if present) must identify the AS that | <dt><tt>iss</tt></dt> | |||
has produced the security protection for the access token. If that is | <dd>The <tt>iss</tt> claim (if present) must identify the AS that | |||
not the case the RS MUST discard the token. If this was an interaction | has produced the security protection for the access token. If that | |||
with authz-info, the RS MUST also respond with a response code equivalent | is | |||
to the CoAP code 4.01 (Unauthorized).</t> | not the case, the RS <bcp14>MUST</bcp14> discard the token. If thi | |||
<t hangText="exp">The expiration date must be in the future. | s was an | |||
If that is not the case the RS MUST discard the token. If this was an | interaction with authz-info, the RS <bcp14>MUST</bcp14> also respon | |||
interaction with authz-info the RS MUST also respond with a response code | d with a | |||
equivalent to the CoAP code 4.01 (Unauthorized). Note that the RS has to | response code equivalent | |||
terminate access rights to the protected resources at the time when the | to the CoAP code 4.01 (Unauthorized).</dd> | |||
tokens expire. </t> | <dt><tt>exp</tt></dt> | |||
<t hangText="aud">The audience claim must refer to an audience that | <dd>The expiration date must be in the future. | |||
the RS identifies with. If that is not the case the RS MUST discard the | If that is not the case, the RS <bcp14>MUST</bcp14> discard the tok | |||
token. If this was an interaction with authz-info, the RS MUST also | en. If | |||
respond with a response code equivalent to the CoAP code 4.03 | this was an | |||
(Forbidden).</t> | interaction with authz-info, the RS <bcp14>MUST</bcp14> also respon | |||
<t hangText="scope">The RS must recognize value of the scope claim. | d with a | |||
If that is not the case the RS MUST discard the token. If this was an | response code | |||
interaction with authz-info, the RS MUST also respond with a response code | equivalent to the CoAP code 4.01 (Unauthorized). Note that the RS h | |||
equivalent to the CoAP code 4.00 (Bad Request). The RS MAY provide | as to | |||
additional information in the error response, to clarify what | terminate access rights to the protected resources at the time when | |||
went wrong.</t> | the | |||
</list></t> | tokens expire. </dd> | |||
<dt><tt>aud</tt></dt> | ||||
<t>Additional processing may be needed for other claims in a way | <dd>The <tt>aud</tt> claim must refer to an audience that | |||
the RS identifies with. If that is not the case, the RS <bcp14>MUST | ||||
</bcp14> | ||||
discard the | ||||
token. If this was an interaction with authz-info, the RS | ||||
<bcp14>MUST</bcp14> also | ||||
respond with a response code equivalent to the CoAP code 4.03 | ||||
(Forbidden).</dd> | ||||
<dt><tt>scope</tt></dt> | ||||
<dd>The RS must recognize value of the <tt>scope</tt> claim. | ||||
If that is not the case, the RS <bcp14>MUST</bcp14> discard the tok | ||||
en. If | ||||
this was an | ||||
interaction with authz-info, the RS <bcp14>MUST</bcp14> also respon | ||||
d with a | ||||
response code | ||||
equivalent to the CoAP code 4.00 (Bad Request). The RS <bcp14>MAY< | ||||
/bcp14> | ||||
provide | ||||
additional information in the error response to clarify what | ||||
went wrong.</dd> | ||||
</dl> | ||||
<t>Additional processing may be needed for other claims in a way | ||||
specific to a profile or the underlying application.</t> | specific to a profile or the underlying application.</t> | |||
<t>Note that the <tt>sub</tt> (Subject) claim cannot always be verif | ||||
<t>Note that the Subject (sub) claim cannot always be verified when | ied when | |||
the token is submitted to the RS since the client may not have | the token is submitted to the RS since the client may not have | |||
authenticated yet. Also note that a counter for the expires_in (exi) claim | authenticated yet. Also note that a counter for the <tt>exi</tt> (expires in | |||
MUST be initialized when the RS first verifies this token.</t> | ) claim | |||
<bcp14>MUST</bcp14> be initialized when the RS first verifies this token.</t | ||||
<t>Also note that profiles of this framework may define access token | > | |||
transport mechanisms that do not allow for error responses. Therefore the | <t>Also note that profiles of this framework may define access token | |||
transport mechanisms that do not allow for error responses. Therefore, the | ||||
error messages specified here only apply if the token was sent to the | error messages specified here only apply if the token was sent to the | |||
authz-info endpoint.</t> | authz-info endpoint.</t> | |||
<t>When sending error responses, the RS <bcp14>MAY</bcp14> use the e | ||||
<t>When sending error responses, the RS MAY use the error codes from | rror | |||
Section 3.1 of <xref target="RFC6750"/>, to provide additional | codes from <xref target="RFC6750" sectionFormat="of" section="3.1"/> | |||
details to the client.</t> | to | |||
</section> | provide additional details to the client.</t> | |||
</section> | ||||
<section anchor="protAuthzInfo" title="Protecting the Authorization | <section anchor="protAuthzInfo" numbered="true" toc="default"> | |||
Information Endpoint"> | <name>Protecting the Authorization Information Endpoint</name> | |||
<t>As this framework can be used in RESTful environments, it is important | <t>As this framework can be used in RESTful environments, it is impo | |||
to make sure that attackers cannot perform unauthorized requests on the | rtant | |||
authz-info endpoints, other than submitting access tokens.</t> | to make sure that attackers cannot perform unauthorized requests on t | |||
he | ||||
<t>Specifically it SHOULD NOT be possible to perform GET, DELETE or | authz-info endpoints, other than submitting access tokens.</t> | |||
PUT on the authz-info endpoint.</t> | <t>Specifically, it <bcp14>SHOULD NOT</bcp14> be possible to perform | |||
GET, | ||||
<t>The RS SHOULD implement rate limiting measures to mitigate attacks aiming | DELETE, or PUT on the authz-info endpoint.</t> | |||
to overload the processing capacity of the RS by repeatedly submitting | <t>The RS <bcp14>SHOULD</bcp14> implement rate-limiting measures to | |||
tokens. For CoAP-based communication the RS could use the mechanisms from | mitigate | |||
<xref target="RFC8516"/> to indicate that it is overloaded.</t> | attacks aiming | |||
</section> | to overload the processing capacity of the RS by repeatedly submittin | |||
g | ||||
</section> | tokens. For CoAP-based communication, the RS could use the mechanisms | |||
from | ||||
<section anchor="requestC2RS" title="Client Requests to the RS"> | <xref target="RFC8516" format="default"/> to indicate that it is over | |||
<t>Before sending a request to an RS, the client MUST verify that the keys | loaded.</t> | |||
used to protect this communication are still valid. See <xref | </section> | |||
target="keyExpiration"/> for details on how the client determines the | </section> | |||
<section anchor="requestC2RS" numbered="true" toc="default"> | ||||
<name>Client Requests to the RS</name> | ||||
<t>Before sending a request to an RS, the client <bcp14>MUST</bcp14> v | ||||
erify that the keys | ||||
used to protect this communication are still valid. See <xref target="keyExpir | ||||
ation" format="default"/> for details on how the client determines the | ||||
validity of the keys used.</t> | validity of the keys used.</t> | |||
<t>If an RS receives a request from a client and the target resource | ||||
<t>If an RS receives a request from a client, and the target resource | requires authorization, the RS <bcp14>MUST</bcp14> first verify that it has an | |||
requires authorization, the RS MUST first verify that it has an access token | access token | |||
that authorizes this request, and that the client has performed the | that authorizes this request and that the client has performed the | |||
proof-of-possession binding that token to the request.</t> | proof-of-possession binding for that token to the request.</t> | |||
<t>The response code <bcp14>MUST</bcp14> be 4.01 (Unauthorized) in cas | ||||
<t>The response code MUST be 4.01 (Unauthorized) in case the client has | e the client has | |||
not performed the proof-of-possession, or if RS has no valid access token for | not performed the proof of possession or if the RS has no valid access token f | |||
the client. If RS has an access token for the client but the token does not | or | |||
authorize access for the resource that was requested, RS MUST reject the | the client. If the RS has an access token for the client but the token does no | |||
request with a 4.03 (Forbidden). If RS has an access token for the client but | t | |||
it does not cover the action that was requested on the resource, RS MUST | authorize access for the resource that was requested, the RS <bcp14>MUST</bcp1 | |||
4> reject the | ||||
request with a 4.03 (Forbidden). If the RS has an access token for the client | ||||
but | ||||
it does not cover the action that was requested on the resource, the RS <bcp14 | ||||
>MUST</bcp14> | ||||
reject the request with a 4.05 (Method Not Allowed).</t> | reject the request with a 4.05 (Method Not Allowed).</t> | |||
<t>Note: The use of the response codes 4.03 and 4.05 is intended to pr | ||||
<t>Note: The use of the response codes 4.03 and 4.05 is intended to prevent | event | |||
infinite loops where a dumb client optimistically tries to access a | infinite loops where a client optimistically tries to access a | |||
requested resource with any access token received from AS. As malicious | requested resource with any access token received from AS. As malicious | |||
clients could pretend to be C to determine C's privileges, these detailed | clients could pretend to be the C to determine the C's privileges, these detai led | |||
response codes must be used only when a certain level of security is | response codes must be used only when a certain level of security is | |||
already available which can be achieved only when the client is | already available, which can be achieved only when the client is | |||
authenticated.</t> | authenticated.</t> | |||
<t>Note: The RS <bcp14>MAY</bcp14> use introspection for timely valida | ||||
<t>Note: The RS MAY use introspection for timely validation of an | tion of an | |||
access token, at the time when a request is presented.</t> | access token at the time when a request is presented.</t> | |||
<t>Note: Matching the claims of the access token (e.g., <tt>scope</tt> | ||||
<t>Note: Matching the claims of the access token (e.g., scope) to a specific | ) to a specific | |||
request is application specific.</t> | request is application specific.</t> | |||
<t>If the request matches a valid token and the client has performed t | ||||
<t>If the request matches a valid token and the client has performed the | he | |||
proof-of-possession for that token, the RS continues to process the request | proof of possession for that token, the RS continues to process the request | |||
as specified by the underlying application.</t> | as specified by the underlying application.</t> | |||
</section> | </section> | |||
<section anchor="tokenExpiration" numbered="true" toc="default"> | ||||
<section anchor="tokenExpiration" title="Token Expiration"> | <name>Token Expiration</name> | |||
<t>Depending on the capabilities of the RS, there are various ways in | <t>Depending on the capabilities of the RS, there are various ways in | |||
which it can verify the expiration of a received access token. Here follows | which it can verify the expiration of a received access token. The fol | |||
a list of the possibilities including what functionality they require of the | lowing is | |||
RS.</t> | a list of the possibilities including what functionality they require o | |||
f the | ||||
<t><list style="symbols"> | RS.</t> | |||
<t>The token is a CWT and includes an "exp" claim and possibly the | <ul spacing="normal"> | |||
"nbf" claim. The RS verifies these by comparing them to values from | <li>The token is a CWT and includes an <tt>exp</tt> claim and possib | |||
its internal clock as defined in <xref target="RFC7519"/>. In this | ly the | |||
case the RS's internal clock must reflect the current date and time, or | <tt>nbf</tt> claim. The RS verifies these by comparing them to value | |||
at least be synchronized with the AS's clock. How this clock | s from | |||
synchronization would be performed is out of scope for this | its internal clock, as defined in <xref target="RFC7519" format="defa | |||
specification.</t> | ult"/>. In | |||
this case, the RS's internal clock must reflect the current date and | ||||
<t>The RS verifies the validity of the token by performing an | time or | |||
introspection request as specified in <xref | at least be synchronized with the AS's clock. How this clock | |||
target="introspectionEndpoint"/>. This requires the RS to have a | synchronization would be performed is out of scope for this | |||
reliable network connection to the AS and to be able to handle two | specification.</li> | |||
secure sessions in parallel (C to RS and RS to AS).</t> | <li>The RS verifies the validity of the token by performing an | |||
introspection request, as specified in <xref target="introspectionEnd | ||||
<t>In order to support token expiration for devices that have no reliable | point" | |||
way of synchronizing their internal clocks, this specification defines the | format="default"/>. This requires the RS to have a | |||
following approach: The claim "exi" ("expires in") can be used, to provide | reliable network connection to the AS and to be able to handle two | |||
the RS with the lifetime of the token in seconds from the time the RS first | secure sessions in parallel (C to RS and RS to AS).</li> | |||
receives the token. This mechanism only works for self-contained tokens, | <li>In order to support token expiration for devices that have no re | |||
i.e. CWTs and JWTs. For CWTs this parameter is encoded as unsigned integer, | liable | |||
while JWTs encode this as JSON number.</t> | way of synchronizing their internal clocks, this specification define | |||
s the | ||||
<t> Processing this claim requires that the RS does the following: | following approach: The claim <tt>exi</tt> (expires in) can be used t | |||
<list style="symbols"> | o provide | |||
<t>For each token the RS receives, that contains an "exi" claim: | the RS with the lifetime of the token in seconds from the time the RS | |||
Keep track of the time it received that token and revisit that list | first | |||
regularly to expunge expired tokens.</t> | receives the token. This mechanism only works for self-contained tok | |||
<t>Keep track of the identifiers of tokens containing the "exi" | ens, | |||
i.e., CWTs and JWTs. For CWTs, this parameter is encoded as an unsign | ||||
ed integer, | ||||
while JWTs encode this as JSON number.</li> | ||||
<li> | ||||
<t> Processing this claim requires that the RS does the following: | ||||
</t> | ||||
<ul spacing="normal"> | ||||
<li>For each token the RS receives that contains an <tt>exi</tt> | ||||
claim, | ||||
keep track of the time it received that token and revisit that li | ||||
st | ||||
regularly to expunge expired tokens.</li> | ||||
<li> | ||||
<t>Keep track of the identifiers of tokens containing the <tt> | ||||
exi</tt> | ||||
claim that have expired (in order to avoid accepting them again). | claim that have expired (in order to avoid accepting them again). | |||
In order to avoid an unbounded memory usage growth, this MUST be | In order to avoid an unbounded memory usage growth, this <bcp14>MUST</bcp1 | |||
implemented in the following way when the "exi" claim is used: | 4> be | |||
<list style="symbols"> | implemented in the following way when the <tt>exi</tt> claim is used: | |||
<t>When creating the token, the AS MUST add a 'cti' claim ( | </t> | |||
or 'jti' for JWTs) to the access token. The value of this claim | <ul spacing="normal"> | |||
MUST be created as the binary representation of the concatenation | <li>When creating the token, the AS <bcp14>MUST</bcp14> add | |||
a <tt>cti</tt> claim (or <tt>jti</tt> for JWTs) to the access token. The value | ||||
of this claim | ||||
<bcp14>MUST</bcp14> be created as the binary representation of the concat | ||||
enation | ||||
of the identifier of the RS with a sequence number counting the | of the identifier of the RS with a sequence number counting the | |||
tokens containing an 'exi' claim, issued by this AS for the | tokens containing an <tt>exi</tt> claim, issued by this AS for the | |||
RS.</t> | RS.</li> | |||
<t>The RS MUST store the highest sequence number of an expired | <li>The RS <bcp14>MUST</bcp14> store the highest sequence nu | |||
token containing the "exi" claim that it has seen, and treat | mber of an expired | |||
token containing the <tt>exi</tt> claim that it has seen and treat | ||||
tokens with lower sequence numbers as expired. Note that | tokens with lower sequence numbers as expired. Note that | |||
this could lead to discarding valid tokens with lower sequence numbers, | this could lead to discarding valid tokens with lower sequence numbers | |||
if the AS where to issue tokens of different validity time for the same | if the AS where to issue tokens of different validity time for the same | |||
RS. The assumption is that typically tokens in such a scenario would | RS. The assumption is that typically tokens in such a scenario would | |||
all have the same validity time.</t> | all have the same validity time.</li> | |||
</list></t> | </ul> | |||
</list></t> | </li> | |||
</list></t> | </ul> | |||
</li> | ||||
<t>If a token that authorizes a long running request such as a CoAP | </ul> | |||
Observe <xref target="RFC7641"/> expires, the RS MUST send an error | <t>If a token that authorizes a long-running request, such as a CoAP | |||
Observe <xref target="RFC7641" format="default"/>, expires, the RS <bcp14>MUST | ||||
</bcp14> send an error | ||||
response with the response code equivalent to the CoAP code 4.01 | response with the response code equivalent to the CoAP code 4.01 | |||
(Unauthorized) to the client and then terminate processing the long running | (Unauthorized) to the client and then terminate processing the long-running | |||
request.</t> | request.</t> | |||
</section> | </section> | |||
<section anchor="keyExpiration" numbered="true" toc="default"> | ||||
<section anchor="keyExpiration" title="Key Expiration"> | <name>Key Expiration</name> | |||
<t>The AS provides the client with key material that the RS uses. This can | <t>The AS provides the client with key material that the RS uses. This | |||
either be a common symmetric PoP-key, or an asymmetric key used by the RS to | can | |||
either be a common symmetric PoP key or an asymmetric key used by the RS to | ||||
authenticate towards the client. Since there is currently no expiration | authenticate towards the client. Since there is currently no expiration | |||
metadata associated to those keys, the client has no way of knowing if these | metadata associated to those keys, the client has no way of knowing if these | |||
keys are still valid. This may lead to situations where the client sends | keys are still valid. This may lead to situations where the client sends | |||
requests containing sensitive information to the RS using a key that is | requests containing sensitive information to the RS using a key that is | |||
expired and possibly in the hands of an attacker, or accepts responses from | expired and possibly in the hands of an attacker or where the client accepts r esponses from | |||
the RS that are not properly protected and could possibly have been forged by | the RS that are not properly protected and could possibly have been forged by | |||
an attacker. | an attacker. | |||
</t> | </t> | |||
<t>In order to prevent this, the client must assume that those keys ar | ||||
<t>In order to prevent this, the client must assume that those keys are | e | |||
only valid as long as the related access token is. Since the access token | only valid as long as the related access token is. Since the access token | |||
is opaque to the client, one of the following methods MUST be used to | is opaque to the client, one of the following methods <bcp14>MUST</bcp14> be u sed to | |||
inform the client about the validity of an access token: | inform the client about the validity of an access token: | |||
<list style="symbols"> | </t> | |||
<t>The client knows a default validity time for all tokens it is | <ul spacing="normal"> | |||
using (i.e. how long a token is valid after being issued). This | <li>The client knows a default validity time for all tokens it is | |||
using (i.e., how long a token is valid after being issued). This | ||||
information could be provisioned to the client when it is registered at the | information could be provisioned to the client when it is registered at the | |||
AS, or published by the AS in a way that the client can query.</t> | AS or published by the AS in a way that the client can query.</li> | |||
<t>The AS informs the client about the token validity using the | <li>The AS informs the client about the token validity using the | |||
"expires_in" parameter in the Access Information.</t> | <tt>expires_in</tt> parameter in the Access Information.</li> | |||
</list> | </ul> | |||
</t> | <t>A client that is not able to obtain information about the expiratio | |||
n of a | ||||
<t>A client that is not able to obtain information about the expiration of a | token <bcp14>MUST NOT</bcp14> use this token.</t> | |||
token MUST NOT use this token.</t> | </section> | |||
</section> | ||||
</section> | </section> | |||
</section><!-- access token --> | <section anchor="security" numbered="true" toc="default"> | |||
<name>Security Considerations</name> | ||||
</section> <!--Framework--> | <t>Security considerations applicable to authentication and authorization | |||
in RESTful environments provided in OAuth 2.0 <xref target="RFC6749" format="d | ||||
<section anchor="security" title="Security Considerations"> | efault"/> apply | |||
to this work. Furthermore, <xref target="RFC6819" format="default"/> | ||||
<t>Security considerations applicable to authentication and authorization | provides additional security considerations for OAuth, which apply to IoT | |||
in RESTful environments provided in OAuth 2.0 <xref target="RFC6749"/> apply | ||||
to this work. Furthermore <xref target="RFC6819"/> | ||||
provides additional security considerations for OAuth which apply to IoT | ||||
deployments as well. If the introspection endpoint is used, | deployments as well. If the introspection endpoint is used, | |||
the security considerations from <xref target="RFC7662"/> also apply.</t> | the security considerations from <xref target="RFC7662" format="default"/> als | |||
o apply.</t> | ||||
<t>The following subsections address issues specific to this document and | <t>The following subsections address issues specific to this document and | |||
it's use in constrained environments.</t> | its use in constrained environments.</t> | |||
<section anchor="tokenProtection" numbered="true" toc="default"> | ||||
<section anchor="tokenProtection" title="Protecting Tokens"> | <name>Protecting Tokens</name> | |||
<t>A large range of threats can be mitigated by protecting the contents | <t>A large range of threats can be mitigated by protecting the contents | |||
of the access token by using a digital signature or a keyed message | of the access token by using a digital signature or a keyed message | |||
digest (MAC) or an Authenticated Encryption with Associated Data (AEAD) | digest, e.g., a Message Authentication Code (MAC) or an Authenticated | |||
algorithm. Consequently, the token integrity protection MUST be applied | Encryption with Associated Data (AEAD) | |||
to prevent the token from being modified, particularly since it contains | algorithm. Consequently, the token integrity protection <bcp14>MUST</bcp | |||
a reference to the symmetric key or the asymmetric key used for | 14> be | |||
proof-of-possession. If the access token contains the symmetric key, | applied to prevent the token from being modified, particularly since it c | |||
this symmetric key MUST be encrypted by the authorization server so that | ontains | |||
only the resource server can decrypt it. Note that using an AEAD | a reference to the symmetric key or the asymmetric key used for | |||
algorithm is preferable over using a MAC unless the token needs to be | proof of possession. If the access token contains the symmetric key, | |||
publicly readable.</t> | this symmetric key <bcp14>MUST</bcp14> be encrypted by the authorization | |||
server so | ||||
<t>If the token is intended for multiple recipients (i.e. an audience | that only the resource server can decrypt it. Note that using an AEAD | |||
algorithm is preferable over using a MAC unless the token needs to be | ||||
publicly readable.</t> | ||||
<t>If the token is intended for multiple recipients (i.e., an audience | ||||
that is a group), integrity protection of the token with a symmetric key, | that is a group), integrity protection of the token with a symmetric key, | |||
shared between the AS and the recipients, is not sufficient, since any of | shared between the AS and the recipients, is not sufficient, since any of | |||
the recipients could modify the token undetected by the other recipients. | the recipients could modify the token undetected by the other recipients. | |||
Therefore a token with a multi-recipient audience MUST be protected with | Therefore, a token with a multirecipient audience <bcp14>MUST</bcp14> be p | |||
an asymmetric signature. | rotected | |||
</t> | with an asymmetric signature.</t> | |||
<t>It is important for the authorization server to include the identity | ||||
<t>It is important for the authorization server to include the identity | ||||
of the intended recipient (the audience), typically a single resource | of the intended recipient (the audience), typically a single resource | |||
server (or a list of resource servers), in the token. The same | server (or a list of resource servers), in the token. The same | |||
shared secret MUST NOT be used as proof-of-possession key with multiple | shared secret <bcp14>MUST NOT</bcp14> be used as a proof-of-possession key | |||
resource servers since the benefit from using the proof-of-possession | with | |||
multiple resource servers, since the benefit from using the proof-of-posse | ||||
ssion | ||||
concept is then significantly reduced.</t> | concept is then significantly reduced.</t> | |||
<t>If clients are capable of doing so, they should frequently request | ||||
<t>If clients are capable of doing so, they should frequently request | ||||
fresh access tokens, as this allows the AS to keep the lifetime of the | fresh access tokens, as this allows the AS to keep the lifetime of the | |||
tokens short. This allows the AS to use shorter proof-of-possession key | tokens short. This allows the AS to use shorter proof-of-possession key | |||
sizes, which translate to a performance benefit for the client and for | sizes, which translate to a performance benefit for the client and for | |||
the resource server. Shorter keys also lead to shorter messages | the resource server. Shorter keys also lead to shorter messages | |||
(particularly with asymmetric keying material).</t> | (particularly with asymmetric keying material).</t> | |||
<t>When authorization servers bind symmetric keys to access tokens, | ||||
they <bcp14>SHOULD</bcp14> scope these access tokens to a specific permiss | ||||
ion.</t> | ||||
<t>In certain situations, it may be necessary to revoke an access | ||||
token that is still valid. Client-initiated revocation is specified | ||||
in <xref target="RFC7009" format="default"/> for OAuth 2.0. Other revoca | ||||
tion | ||||
mechanisms | ||||
are currently not specified, as the underlying assumption in OAuth | ||||
is that access tokens are issued with a relatively short lifetime. | ||||
This may not hold true for disconnected constrained devices needing | ||||
access tokens with relatively long lifetimes and would therefore | ||||
necessitate further standardization work that is out of scope for | ||||
this document.</t> | ||||
</section> | ||||
<t>When authorization servers bind symmetric keys to access tokens, | <section anchor="commSec" numbered="true" toc="default"> | |||
they SHOULD scope these access tokens to a specific permission.</t> | <name>Communication Security</name> | |||
<t>Communication with the authorization server <bcp14>MUST</bcp14> use c | ||||
<t>In certain situations it may be necessary to revoke an access | onfidentiality | |||
token that is still valid. Client-initiated revocation is specified | ||||
in <xref target="RFC7009"/> for OAuth 2.0. Other revocation mechanisms | ||||
are currently not specified, as the underlying assumption in OAuth | ||||
is that access tokens are issued with a relatively short lifetime. | ||||
This may not hold true for disconnected constrained devices, needing | ||||
access tokens with relatively long lifetimes, and would therefore | ||||
necessitate further standardization work that is out of scope for | ||||
this document.</t> | ||||
</section><!--token protection--> | ||||
<section anchor="commSec" title="Communication Security"> | ||||
<t>Communication with the authorization server MUST use confidentiality | ||||
protection. This step is extremely important since the client or the | protection. This step is extremely important since the client or the | |||
RS may obtain the proof-of-possession key from the authorization server | RS may obtain the proof-of-possession key from the authorization server | |||
for use with a specific access token. Not using confidentiality | for use with a specific access token. Not using confidentiality | |||
protection exposes this secret (and the access token) to an eavesdropper | protection exposes this secret (and the access token) to an eavesdropper, | |||
thereby completely negating proof-of-possession security. | thereby completely negating proof-of-possession security. | |||
The requirements for communication security of profiles are specified | The requirements for communication security of profiles are specified | |||
in <xref target="oauthProfile"/>.</t> | in <xref target="oauthProfile" format="default"/>.</t> | |||
<t>Additional protection for the access token can be applied by | ||||
<t>Additional protection for the access token can be applied by | encrypting it, for example, encryption of CWTs is specified in | |||
encrypting it, for example encryption of CWTs is specified in Section 5.1 | <xref target="RFC8392" sectionFormat="of" section="7.1"/>. Such addition | |||
of <xref target="RFC8392"/>. Such additional protection can be necessary | al | |||
if the token is later transferred over an insecure connection | protection can be necessary | |||
(e.g. when it is sent to the authz-info endpoint).</t> | if the token is later transferred over an insecure connection | |||
(e.g., when it is sent to the authz-info endpoint).</t> | ||||
<t>Care must by taken by developers to prevent leakage of the PoP | <t>Care must be taken by developers to prevent leakage of the PoP | |||
credentials (i.e., the private key or the symmetric key). An | credentials (i.e., the private key or the symmetric key). An | |||
adversary in possession of the PoP credentials bound to the access | adversary in possession of the PoP credentials bound to the access | |||
token will be able to impersonate the client. Be aware that this is a | token will be able to impersonate the client. Be aware that this is a | |||
real risk with many constrained environments, since adversaries may | real risk with many constrained environments, since adversaries may | |||
get physical access to the devices and can therefore use physical | get physical access to the devices and can therefore use physical | |||
extraction techniques to gain access to memory contents. This risk can | extraction techniques to gain access to memory contents. This risk can | |||
be mitigated to some extent by making sure that keys are refreshed | be mitigated to some extent by making sure that keys are refreshed | |||
frequently, by using software isolation techniques and by using hardware s | frequently, by using software isolation techniques, and by using hardware | |||
ecurity.</t> | security.</t> | |||
</section><!--communication security--> | </section> | |||
<section anchor="keys" title="Long-Term Credentials"> | <section anchor="keys" numbered="true" toc="default"> | |||
<t>Both clients and RSs have long-term credentials that are used to | <name>Long-Term Credentials</name> | |||
secure communications, and authenticate to the AS. These credentials | <t>Both the clients and RSs have long-term credentials that are used to | |||
secure communications and authenticate to the AS. These credentials | ||||
need to be protected against unauthorized access. In constrained | need to be protected against unauthorized access. In constrained | |||
devices, deployed in publicly accessible places, such protection can | devices deployed in publicly accessible places, such protection can | |||
be difficult to achieve without specialized hardware (e.g. secure | be difficult to achieve without specialized hardware (e.g., secure | |||
key storage memory).</t> | key storage memory).</t> | |||
<t>If credentials are lost or compromised, the operator of the affected | ||||
<t>If credentials are lost or compromised, the operator of the affected | ||||
devices needs to have procedures to invalidate any access these | devices needs to have procedures to invalidate any access these | |||
credentials give and to revoke tokens linked to such credentials. The | credentials give and needs to revoke tokens linked to such credentials. T | |||
loss of a credential linked to a specific device MUST NOT lead to a | he | |||
compromise of other credentials not linked to that device, therefore | loss of a credential linked to a specific device <bcp14>MUST NOT</bcp14> l | |||
secret keys used for authentication MUST NOT be shared between more than | ead to a | |||
compromise of other credentials not linked to that device; therefore, | ||||
secret keys used for authentication <bcp14>MUST NOT</bcp14> be shared betw | ||||
een more than | ||||
two parties.</t> | two parties.</t> | |||
<t>Operators of the clients or RSs <bcp14>SHOULD</bcp14> have procedures | ||||
<t>Operators of clients or RS SHOULD have procedures in place to | in place to | |||
replace credentials that are suspected to have been compromised or that | replace credentials that are suspected to have been compromised or that | |||
have been lost.</t> | have been lost.</t> | |||
<t>Operators also <bcp14>SHOULD</bcp14> have procedures for decommission | ||||
<t>Operators also SHOULD have procedures for decommissioning devices, | ing devices | |||
that include securely erasing credentials and other security critical | that include securely erasing credentials and other security-critical | |||
material in the devices being decommissioned.</t> | material in the devices being decommissioned.</t> | |||
</section><!--credential livecycle--> | </section> | |||
<section anchor="unprotected-as-information" | ||||
title="Unprotected AS Request Creation Hints"> | ||||
<t>Initially, no secure channel exists to protect the communication | <section anchor="unprotected-as-information" numbered="true" toc="default"> | |||
between C and RS. Thus, C cannot determine if the "AS Request | <name>Unprotected AS Request Creation Hints</name> | |||
Creation Hints" contained in an unprotected response from RS to an | <t>Initially, no secure channel exists to protect the communication | |||
unauthorized request (see <xref target="asInfo"/>) are authentic. C | between the C and RS. Thus, the C cannot determine if the AS Request | |||
therefore MUST determine if an AS is authorized to provide access | Creation Hints contained in an unprotected response from the RS to an | |||
unauthorized request (see <xref target="asInfo" format="default"/>) are | ||||
authentic. Therefore, the C | ||||
<bcp14>MUST</bcp14> determine if an AS is authorized to provide | ||||
access | ||||
tokens for a certain RS. How this determination is implemented is out | tokens for a certain RS. How this determination is implemented is out | |||
of scope for this document and left to the applications.</t> | of scope for this document and left to the applications.</t> | |||
</section> | </section> | |||
<section anchor="minimalCommSecReq" numbered="true" toc="default"> | ||||
<section anchor="minimalCommSecReq" title="Minimal Security Requirements | <name>Minimal Security Requirements for Communication</name> | |||
for Communication"> | <t>This section summarizes the minimal requirements for the | |||
<t>This section summarizes the minimal requirements for the | ||||
communication security of the different protocol interactions. | communication security of the different protocol interactions. | |||
</t> | ||||
<list style="hanging"> | <dl newline="true" spacing="normal"> | |||
<t hangText="C-AS">All communication between the client and the | <dt>C-AS</dt> | |||
Authorization Server MUST be encrypted, integrity and replay | <dd>All communication between the client and the | |||
protected. Furthermore responses from the AS to the client MUST be | authorization server <bcp14>MUST</bcp14> be encrypted and integrity and | |||
replay | ||||
protected. Furthermore, responses from the AS to the client <bcp14>MUST | ||||
</bcp14> be | ||||
bound to the client's request to avoid attacks where the attacker | bound to the client's request to avoid attacks where the attacker | |||
swaps the intended response for an older one valid for a previous | swaps the intended response for an older one valid for a previous | |||
request. This requires that the client and the Authorization Server | request. This requires that the client and the authorization server | |||
have previously exchanged either a shared secret or their public | have previously exchanged either a shared secret or their public | |||
keys in order to negotiate a secure communication. Furthermore the | keys in order to negotiate a secure communication. Furthermore, the | |||
client MUST be able to determine whether an AS has the authority | client <bcp14>MUST</bcp14> be able to determine whether an AS has the a | |||
to issue access tokens for a certain RS. This can for example be | uthority | |||
done through pre-configured lists, or through an online lookup | to issue access tokens for a certain RS. This can, for example, be | |||
done through preconfigured lists or through an online lookup | ||||
mechanism that in turn also must be secured. | mechanism that in turn also must be secured. | |||
</t> | </dd> | |||
<dt>RS-AS</dt> | ||||
<t hangText="RS-AS">The communication between the Resource | <dd>The communication between the resource | |||
Server and the Authorization Server via the introspection endpoint | server and the authorization server via the introspection endpoint | |||
MUST be encrypted, integrity and replay protected. Furthermore | <bcp14>MUST</bcp14> be encrypted and integrity and replay protected. Fu | |||
responses from the AS to the RS MUST be bound to the RS's request. | rthermore, | |||
This requires that the RS and the Authorization Server | responses from the AS to the RS <bcp14>MUST</bcp14> be bound to the RS' | |||
have previously exchanged either a shared secret, or their public | s request. | |||
keys in order to negotiate a secure communication. Furthermore the | This requires that the RS and the authorization server | |||
RS MUST be able to determine whether an AS has the authority | have previously exchanged either a shared secret or their public | |||
keys in order to negotiate a secure communication. Furthermore, the | ||||
RS <bcp14>MUST</bcp14> be able to determine whether an AS has the autho | ||||
rity | ||||
to issue access tokens itself. This is usually configured out of | to issue access tokens itself. This is usually configured out of | |||
band, but could also be performed through an online lookup mechanism | band but could also be performed through an online lookup mechanism, | |||
provided that it is also secured in the same way.</t> | provided that it is also secured in the same way.</dd> | |||
<dt>C-RS</dt> | ||||
<t hangText="C-RS">The initial communication between the client | <dd>The initial communication between the client | |||
and the Resource Server can not be secured in general, since | and the resource server cannot be secured in general, since | |||
the RS is not in possession of on access token for that client, | the RS is not in possession of on access token for that client, | |||
which would carry the necessary parameters. If both parties | which would carry the necessary parameters. If both parties | |||
support DTLS without client authentication it is RECOMMEND to use | support DTLS without client authentication, it is <bcp14>RECOMMENDED</b cp14> to use | |||
this mechanism for protecting the initial communication. | this mechanism for protecting the initial communication. | |||
After the client has successfully transmitted the access token to the | After the client has successfully transmitted the access token to the | |||
RS, a secure communication protocol MUST be established between | RS, a secure communication protocol <bcp14>MUST</bcp14> be established | |||
client and RS for the actual resource request. This protocol MUST | between the | |||
provide confidentiality, integrity and replay protection as well as a | client and RS for the actual resource request. This protocol <bcp14>MU | |||
ST</bcp14> | ||||
provide confidentiality, integrity, and replay protection, as well as a | ||||
binding between requests and responses. This requires that the | binding between requests and responses. This requires that the | |||
client learned either the RS's public key or received a symmetric | client learned either the RS's public key or received a symmetric | |||
proof-of-possession key bound to the access token from the AS. | proof-of-possession key bound to the access token from the AS. | |||
The RS must have learned either the client's public key or a shared | The RS must have learned either the client's public key, a shared | |||
symmetric key from the claims in the token or an introspection | symmetric key from the claims in the token, or an introspection | |||
request. Since ACE does not provide profile negotiation between | request. Since ACE does not provide profile negotiation between the | |||
C and RS, the client MUST have learned what profile the RS | C and RS, the client <bcp14>MUST</bcp14> have learned what profile the | |||
supports (e.g. from the AS or pre-configured) and initiate the | RS | |||
communication accordingly.</t> | supports (e.g., from the AS or preconfigured) and initiated the | |||
</list></t> | communication accordingly.</dd> | |||
</section> | </dl> | |||
<section anchor="nonce" title="Token Freshness and Expiration"> | </section> | |||
<t>An RS that is offline faces the problem of clock drift. Since it | <section anchor="nonce" numbered="true" toc="default"> | |||
<name>Token Freshness and Expiration</name> | ||||
<t>An RS that is offline faces the problem of clock drift. Since it | ||||
cannot synchronize its clock with the AS, it may be tricked | cannot synchronize its clock with the AS, it may be tricked | |||
into accepting old access tokens that are no longer valid or have been | into accepting old access tokens that are no longer valid or have been | |||
compromised. In order to prevent this, an RS may use the nonce-based | compromised. In order to prevent this, an RS may use the nonce-based | |||
mechanism (cnonce) defined in <xref target="asInfo"/> to ensure | mechanism (<tt>cnonce</tt>) defined in <xref target="asInfo" format="defa ult"/> to ensure | |||
freshness of an Access Token subsequently presented to this RS.</t> | freshness of an Access Token subsequently presented to this RS.</t> | |||
<t>Another problem with clock drift is that evaluating the | ||||
<t>Another problem with clock drift is that evaluating the | standard token expiration claim <tt>exp</tt> can give unpredictable resul | |||
standard token expiration claim "exp" can give unpredictable results. | ts. | |||
</t> | </t> | |||
<t>Acceptable ranges of clock drift are highly dependent on the | ||||
<t>Acceptable ranges of clock drift are highly dependent on the | ||||
concrete application. Important factors are how long access tokens | concrete application. Important factors are how long access tokens | |||
are valid, and how critical timely expiration of access token is.</t> | are valid and how critical timely expiration of the access token is.</t> | |||
<t>The expiration mechanism implemented by the <tt>exi</tt> claim, based | ||||
<t>The expiration mechanism implemented by the "exi" claim, based on | on | |||
the first time the RS sees the token was defined to provide a more | the first time the RS sees the token, was defined to provide a more | |||
predictable alternative. The "exi" approach has some drawbacks that | predictable alternative. The <tt>exi</tt> approach has some drawbacks th | |||
at | ||||
need to be considered: | need to be considered: | |||
<list> | </t> | |||
<t>A malicious client may hold back tokens with the "exi" claim in | <ul spacing="normal"> | |||
order to prolong their lifespan.</t> | <li>A malicious client may hold back tokens with the <tt>exi</tt> clai | |||
<t>If an RS loses state (e.g. due to an unscheduled reboot), it | m in | |||
may lose the current values of counters tracking the "exi" claims of | order to prolong their lifespan.</li> | |||
tokens it is storing.</t> | <li> | |||
</list> | If an RS loses state (e.g., due to an unscheduled reboot), it | |||
The first drawback is inherent to the deployment scenario and the "exi" | may lose the current values of counters tracking the <tt>exi</tt> claim | |||
s of | ||||
tokens it is storing.</li> | ||||
</ul> | ||||
<t> | ||||
The first drawback is inherent to the deployment scenario and the <tt>exi | ||||
</tt> | ||||
solution. It can therefore not be mitigated without requiring the | solution. It can therefore not be mitigated without requiring the | |||
RS be online at times. The second drawback can be mitigated by | RS be online at times. The second drawback can be mitigated by | |||
regularly storing the value of "exi" counters to persistent memory.</t> | regularly storing the value of <tt>exi</tt> counters to persistent memory | |||
</section> | .</t> | |||
</section> | ||||
<section anchor="mixnmatch" title="Combining Profiles"> | <section anchor="mixnmatch" numbered="true" toc="default"> | |||
<t>There may be use cases where different transport and security | <name>Combining Profiles</name> | |||
<t>There may be use cases where different transport and security | ||||
protocols are allowed for the different interactions, and, if that is | protocols are allowed for the different interactions, and, if that is | |||
not explicitly covered by an existing profile, it corresponds to | not explicitly covered by an existing profile, it corresponds to | |||
combining profiles into a new one. For example, a new profile could | combining profiles into a new one. For example, a new profile could | |||
specify that a previously-defined MQTT-TLS profile is used between | specify that a previously defined MQTT-TLS profile is used between | |||
the client and the RS in combination with a previously-defined | the client and the RS in combination with a previously defined | |||
CoAP-DTLS profile for interactions between the client and the AS. The | CoAP-DTLS profile for interactions between the client and the AS. The | |||
new profile that combines existing profiles MUST specify how the | new profile that combines existing profiles <bcp14>MUST</bcp14> specify ho | |||
existing profiles' security properties are achieved. Any profile | w the | |||
therefore MUST clearly specify its security requirements and MUST | existing profiles' security requirements remain satisfied. Therefore, any | |||
profile | ||||
<bcp14>MUST</bcp14> clearly specify its security requirements and <bcp14>M | ||||
UST</bcp14> | ||||
document if its security depends on the combination of various | document if its security depends on the combination of various | |||
protocol interactions.</t> | protocol interactions.</t> | |||
</section> | </section> | |||
<section anchor="infoLeak" numbered="true" toc="default"> | ||||
<section anchor="infoLeak" title="Unprotected Information"> | <name>Unprotected Information</name> | |||
<t>Communication with the authz-info endpoint, as well as the | <t>Communication with the authz-info endpoint, as well as the | |||
various error responses defined in this framework, all potentially | various error responses defined in this framework, potentially | |||
include sending information over an unprotected channel. | includes sending information over an unprotected channel. | |||
These messages may leak information to an adversary, or may be | These messages may leak information to an adversary or may be | |||
manipulated by active attackers to induce incorrect behavior. For | manipulated by active attackers to induce incorrect behavior. For | |||
example error responses for requests to the Authorization Information | example, error responses for requests to the authorization information | |||
endpoint can reveal information about an otherwise opaque access token | endpoint can reveal information about an otherwise opaque access token | |||
to an adversary who has intercepted this token.</t> | to an adversary who has intercepted this token.</t> | |||
<t>As far as error messages are concerned, this framework is written | ||||
<t>As far as error messages are concerned, this framework is written | ||||
under the assumption that, in general, the benefits of detailed error | under the assumption that, in general, the benefits of detailed error | |||
messages outweigh the risk due to information leakage. For particular | messages outweigh the risk due to information leakage. For particular | |||
use cases, where this assessment does not apply, detailed error | use cases where this assessment does not apply, detailed error | |||
messages can be replaced by more generic ones.</t> | messages can be replaced by more generic ones.</t> | |||
<t>In some scenarios, it may be possible to protect the | ||||
<t>In some scenarios it may be possible to protect the | communication with the authz-info endpoint (e.g., through | |||
communication with the authz-info endpoint (e.g. through | ||||
DTLS with only server-side authentication). In cases where | DTLS with only server-side authentication). In cases where | |||
this is not possible, it is RECOMMENDED to use encrypted | this is not possible, it is <bcp14>RECOMMENDED</bcp14> to use encrypted | |||
CWTs or tokens that are opaque references and need to be subjected to | CWTs or tokens that are opaque references and need to be subjected to | |||
introspection by the RS.</t> | introspection by the RS.</t> | |||
<t>If the initial Unauthorized Resource Request message (see <xref targe | ||||
<t>If the initial unauthorized resource request message (see <xref | t="rreq" format="default"/>) is used, the client <bcp14>MUST</bcp14> make sure t | |||
target="rreq"/>) is used, the client MUST make sure that it is | hat it is | |||
not sending sensitive content in this request. While GET and DELETE | not sending sensitive content in this request. While GET and DELETE | |||
requests only reveal the target URI of the resource, POST and PUT | requests only reveal the target URI of the resource, POST and PUT | |||
requests would reveal the whole payload of the intended operation.</t> | requests would reveal the whole payload of the intended operation.</t> | |||
<t>Since the client is not authenticated at the point when | ||||
<t>Since the client is not authenticated at the point when | ||||
it is submitting an access token to the authz-info endpoint, | it is submitting an access token to the authz-info endpoint, | |||
attackers may be pretending to be a client and trying to trick | attackers may be pretending to be a client and trying to trick | |||
an RS to use an obsolete profile that in turn specifies a | an RS to use an obsolete profile that in turn specifies a | |||
vulnerable security mechanism via the authz-info endpoint. Such an | vulnerable security mechanism via the authz-info endpoint. Such an | |||
attack would require a valid access token containing an "ace_profile" | attack would require a valid access token containing an <tt>ace_profile</ | |||
claim requesting the use of said obsolete profile. Resource Owners | tt> | |||
should update the configuration of their RS's to prevent them from | claim requesting the use of said obsolete profile. Resource owners | |||
should update the configuration of their RSs to prevent them from | ||||
using such obsolete profiles.</t> | using such obsolete profiles.</t> | |||
</section> | </section> | |||
<section anchor="audience" numbered="true" toc="default"> | ||||
<section anchor="audience" title="Identifying Audiences"> | <name>Identifying Audiences</name> | |||
<t>The audience claim as defined in <xref target="RFC7519"/> | <t>The <tt>aud</tt> claim, as defined in <xref target="RFC7519" format=" | |||
and the equivalent "audience" parameter from | default"/>, | |||
<xref target="RFC8693"/> are intentionally vague | and the equivalent <tt>audience</tt> parameter from | |||
<xref target="RFC8693" format="default"/> are intentionally vague | ||||
on how to match the audience value to a specific RS. This is intended | on how to match the audience value to a specific RS. This is intended | |||
to allow application specific semantics to be used. This section | to allow application-specific semantics to be used. This section | |||
attempts to give some general guidance for the use of audiences in | attempts to give some general guidance for the use of audiences in | |||
constrained environments.</t> | constrained environments.</t> | |||
<t>URLs are not a good way of identifying mobile devices that can | ||||
<t>URLs are not a good way of identifying mobile devices that can | ||||
switch networks and thus be associated with new URLs. If the | switch networks and thus be associated with new URLs. If the | |||
audience represents a single RS, and asymmetric keys are used, | audience represents a single RS and asymmetric keys are used, | |||
the RS can be uniquely identified by a hash of its public key. | the RS can be uniquely identified by a hash of its public key. | |||
If this approach is used it is RECOMMENDED to apply the | If this approach is used, it is <bcp14>RECOMMENDED</bcp14> to apply the | |||
procedure from section 3 of <xref target="RFC6920"/>.</t> | procedure from <xref target="RFC6920" sectionFormat="of" section="3"/>.</ | |||
t> | ||||
<t>If the audience addresses a group of resource servers, the mapping | <t>If the audience addresses a group of resource servers, the mapping | |||
of group identifier to individual RS has to be provisioned to each RS | of a group identifier to an individual RS has to be provisioned to each R | |||
S | ||||
before the group-audience is usable. Managing dynamic groups could be | before the group-audience is usable. Managing dynamic groups could be | |||
an issue, if any RS is not always reachable when the groups' memberships | an issue if any RS is not always reachable when the groups' memberships | |||
change. Furthermore, issuing access tokens bound to symmetric | change. Furthermore, issuing access tokens bound to symmetric | |||
proof-of-possession keys that apply to a group-audience is problematic, | proof-of-possession keys that apply to a group-audience is problematic, | |||
as an RS that is in possession of the access token can impersonate the | as an RS that is in possession of the access token can impersonate the | |||
client towards the other RSs that are part of the group. It is | client towards the other RSs that are part of the group. It is | |||
therefore NOT RECOMMENDED to issue access tokens bound to a group | therefore <bcp14>NOT RECOMMENDED</bcp14> to issue access tokens bound | |||
audience and symmetric proof-of possession keys.</t> | to a group-audience and symmetric proof-of possession keys.</t> | |||
<t>Even the client must be able to determine the correct values to put | ||||
<t>Even the client must be able to determine the correct values to put | into the <tt>audience</tt> parameter in order to obtain a token for the | |||
into the "audience" parameter, in order to obtain a token for the | ||||
intended RS. Errors in this process can lead to the client | intended RS. Errors in this process can lead to the client | |||
inadvertently obtaining a token for the wrong RS. The correct values | inadvertently obtaining a token for the wrong RS. The correct values | |||
for "audience" can either be provisioned to the client as part of its | for <tt>audience</tt> can either be provisioned to the client as part of | |||
configuration, or dynamically looked up by the client in some | its | |||
directory. In the latter case the integrity and correctness of the | configuration or dynamically looked up by the client in some | |||
directory data must be assured. Note that the "audience" hint | directory. In the latter case, the integrity and correctness of th | |||
provided by the RS as part of the "AS Request Creation Hints" <xref | e | |||
target="asInfo"/> is not typically source authenticated and integrity | directory data must be assured. Note that the <tt>audience</tt> hint | |||
protected, and should therefore not be treated a trusted value.</t> | provided by the RS as part of the AS Request Creation Hints (<xref | |||
</section> | target="asInfo" format="default"/>) is not typically source authenticated | |||
and | ||||
<section anchor="introDos" title="Denial of Service Against or with | integrity protected and should therefore not be treated a trusted value.< | |||
Introspection"> | /t> | |||
<t> | </section> | |||
<section anchor="introDos" numbered="true" toc="default"> | ||||
<name>Denial of Service Against or with Introspection</name> | ||||
<t> | ||||
The optional introspection mechanism provided by OAuth and supported | The optional introspection mechanism provided by OAuth and supported | |||
in the ACE framework allows for two types of attacks that need | in the ACE framework allows for two types of attacks that need | |||
to be considered by implementers.</t> | to be considered by implementers.</t> | |||
<t>First, an attacker could perform a denial-of-service attack against | ||||
<t>First, an attacker could perform a denial of service attack against | ||||
the introspection endpoint at the AS in order to prevent validation of | the introspection endpoint at the AS in order to prevent validation of | |||
access tokens. To maintain the security of the system, an RS that is | access tokens. To maintain the security of the system, an RS that is | |||
configured to use introspection MUST NOT allow access based on a token | configured to use introspection <bcp14>MUST NOT</bcp14> allow access base d on a token | |||
for which it couldn't reach the introspection endpoint.</t> | for which it couldn't reach the introspection endpoint.</t> | |||
<t>Second, an attacker could use the fact that an RS performs | ||||
<t>Second, an attacker could use the fact that an RS performs | introspection to perform a denial-of-service attack against that RS by | |||
introspection to perform a denial of service attack against that RS by | ||||
repeatedly sending tokens to its authz-info endpoint that require an | repeatedly sending tokens to its authz-info endpoint that require an | |||
introspection call. RS can mitigate such attacks by implementing rate | introspection call. The RS can mitigate such attacks by implementing rate | |||
limits on how many introspection requests they perform in a given time | limits on how many introspection requests they perform in a given time | |||
interval for a certain client IP address submitting tokens to | interval for a certain client IP address submitting tokens to | |||
/authz-info. When that limit has been reached, incoming requests from | /authz-info. When that limit has been reached, incoming requests from | |||
that address are rejected for a certain amount of time. A general rate | that address are rejected for a certain amount of time. A general rate | |||
limit on the introspection requests should also be considered, to | limit on the introspection requests should also be considered in order to | |||
mitigate distributed attacks.</t> | mitigate distributed attacks.</t> | |||
</section> | ||||
</section> | </section> | |||
</section> | <section anchor="privacy" numbered="true" toc="default"> | |||
<name>Privacy Considerations</name> | ||||
<section anchor="privacy" title="Privacy Considerations"> | ||||
<t>Implementers and users should be aware of the privacy implications | <t>Implementers and users should be aware of the privacy implications | |||
of the different possible deployments of this framework.</t> | of the different possible deployments of this framework.</t> | |||
<t>The AS is in a very central position and can potentially learn sensitiv e | <t>The AS is in a very central position and can potentially learn sensitiv e | |||
information about the clients requesting access tokens. If the client | information about the clients requesting access tokens. If the client | |||
credentials grant is used, the AS can track what kind of access | credentials grant is used, the AS can track what kind of access | |||
the client intends to perform. With other grants this can be prevented | the client intends to perform. With other grants, this can be prevented | |||
by the Resource Owner. To do so, the resource owner needs to bind the | by the resource owner. To do so, the resource owner needs to bind the | |||
grants it issues to anonymous, ephemeral credentials that do not allow | grants it issues to anonymous, ephemeral credentials that do not allow | |||
the AS to link different grants and thus different access token requests | the AS to link different grants and thus different access token requests | |||
by the same client.</t> | by the same client.</t> | |||
<t>The claims contained in a token can reveal privacy-sensitive | ||||
<t>The claims contained in a token can reveal privacy sensitive | ||||
information about the client and the RS to any party having access to | information about the client and the RS to any party having access to | |||
them (whether by processing the content of a self-contained token or by | them (whether by processing the content of a self-contained token or by | |||
introspection). The AS SHOULD be configured to minimize the information | introspection). The AS <bcp14>SHOULD</bcp14> be configured to minimize th e information | |||
about clients and RSs disclosed in the tokens it issues.</t> | about clients and RSs disclosed in the tokens it issues.</t> | |||
<t>If tokens are only integrity protected and not encrypted, they | <t>If tokens are only integrity protected and not encrypted, they | |||
may reveal information to attackers listening on the wire, or able to | may reveal information to attackers listening on the wire or be able to | |||
acquire the access tokens in some other way. In the case of CWTs | acquire the access tokens in some other way. In the case of CWTs, | |||
the token may, e.g., reveal the audience, the scope and the confirmation | the token may, e.g., reveal the audience, the scope, and the confirmation | |||
method used by the client. The latter may reveal the identity of the | method used by the client. The latter may reveal the identity of the | |||
device or application running the client. This may be linkable to | device or application running the client. This may be linkable to | |||
the identity of the person using the client (if there is a person and | the identity of the person using the client (if there is a person and | |||
not a machine-to-machine interaction).</t> | not a machine-to-machine interaction).</t> | |||
<t>Clients using asymmetric keys for proof of possession should be aware | ||||
<t>Clients using asymmetric keys for proof-of-possession should be aware | of the consequences of using the same key pair for proof of possession | |||
of the consequences of using the same key pair for proof-of-possession | ||||
towards different RSs. A set of colluding RSs or an attacker able to | towards different RSs. A set of colluding RSs or an attacker able to | |||
obtain the access tokens will be able to link the requests, or even | obtain the access tokens will be able to link the requests or even | |||
to determine the client's identity.</t> | to determine the client's identity.</t> | |||
<t>An unprotected response to an unauthorized request (see | <t>An unprotected response to an unauthorized request (see | |||
<xref target="asInfo"/>) may disclose information about RS and/or its | <xref target="asInfo" format="default"/>) may disclose information about t | |||
existing relationship with C. It is advisable to include as little | he RS | |||
information as possible in an unencrypted response. Even the absolute URI | and/or its | |||
of the AS may reveal sensitive information about the service that RS provides. D | existing relationship with the C. It is advisable to include as little | |||
evelopers must ensure that the RS does not disclose information that has an impa | information as possible in an unencrypted response. Even the absolute URI | |||
ct on the privacy of the stakeholders in the "AS Request Creation Hints". They m | of the AS may reveal sensitive information about the service that the RS provide | |||
ay choose to use a different mechanism for the discovery of the AS if necessary. | s. Developers must ensure that the RS does not disclose information that has an | |||
If means of encrypting | impact on the privacy of the stakeholders in the AS Request Creation Hints. They | |||
communication between C and RS already exist, more detailed information | may choose to use a different mechanism for the discovery of the AS if necessar | |||
may be included with an error response to provide C with sufficient | y. If means of encrypting | |||
communication between the C and RS already exist, more detailed informatio | ||||
n | ||||
may be included with an error response to provide the C with sufficient | ||||
information to react on that particular error.</t> | information to react on that particular error.</t> | |||
</section> | ||||
<section anchor="iana" numbered="true" toc="default"> | ||||
<name>IANA Considerations</name> | ||||
</section> | <t>This document creates several registries with a registration policy of | |||
Expert Review; guidelines to the experts are given in | ||||
<section anchor="iana" title="IANA Considerations"> | <xref target="IANAinstructions" format="default"/>.</t> | |||
<t>This document creates several registries with a registration policy of | <section anchor="IANAASInformation" numbered="true" toc="default"> | |||
"Expert Review"; guidelines to the experts are given in | <name>ACE Authorization Server Request Creation Hints</name> | |||
<xref target="IANAinstructions"/>.</t> | <t>This specification establishes the IANA "ACE Authorization Server | |||
Request Creation Hints" registry.</t> | ||||
<section anchor="IANAASInformation" | <t>The columns of the registry are:</t> | |||
title="ACE Authorization Server Request Creation Hints"> | <dl newline="false"> | |||
<t>This specification establishes the IANA "ACE Authorization Server | <dt>Name:</dt> | |||
Request Creation Hints" registry. The registry has been created to use the | <dd>The name of the parameter.</dd> | |||
"Expert Review" registration procedure <xref target="RFC8126"/>. | <dt>CBOR Key:</dt> | |||
It should be noted that, in addition to the expert review, some portions of | <dd>CBOR map key for the parameter. Different ranges | |||
the registry require a specification, potentially a Standards Track RFC, be | of values use different registration policies <xref target="RFC8126" forma | |||
supplied as well.</t> | t="default"/>. | |||
<t>The columns of the registry are: | ||||
<list style='hanging'> | ||||
<t hangText='Name'>The name of the parameter</t> | ||||
<t hangText='CBOR Key'>CBOR map key for the parameter. Different ranges | ||||
of values use different registration policies <xref target="RFC8126"/>. | ||||
Integer values from -256 to 255 are designated as Standards | Integer values from -256 to 255 are designated as Standards | |||
Action. Integer values from -65536 to -257 and from 256 to 65535 | Action. Integer values from -65536 to -257 and from 256 to 65535 | |||
are designated as Specification Required. Integer values greater than | are designated as Specification Required. Integer values greater than | |||
65535 are designated as Expert Review. Integer values less than -65536 | 65535 are designated as Expert Review. Integer values less than -65536 | |||
are marked as Private Use.</t> | are marked as Private Use.</dd> | |||
<dt>Value Type:</dt> | ||||
<t hangText='Value Type'>The CBOR data types allowable for the values of | <dd>The CBOR data types allowable for the values of | |||
this parameter.</t> | this parameter.</dd> | |||
<dt>Reference:</dt> | ||||
<t hangText='Reference'>This contains a pointer to the public | <dd>This contains a pointer to the public | |||
specification of the request creation hint abbreviation, if one | specification of the Request Creation Hint abbreviation, if one | |||
exists.</t> | exists.</dd> | |||
</list></t> | </dl> | |||
<t>This registry has been initially populated by the values in <xref targ | ||||
<t>This registry will be initially populated by the values in | et="table_asinfo"/>. The Reference column for all of these entries is this docum | |||
<xref target="fig:asinfo"/>. The Reference column for all of | ent.</t> | |||
these entries will be this document.</t> | </section> | |||
</section> | <section anchor="IANAcoreRT" numbered="true" toc="default"> | |||
<name>CoRE Resource Types</name> | ||||
<section anchor="IANAcoreRT" title="CoRE Resource Type Registry"> | <t>IANA has registered a new Resource Type (rt=) Link Target | |||
<t>IANA is requested to register a new Resource Type (rt=) Link Target | ||||
Attribute in the "Resource Type (rt=) Link Target Attribute Values" | Attribute in the "Resource Type (rt=) Link Target Attribute Values" | |||
subregistry under the "Constrained RESTful Environments (CoRE) | subregistry under the "Constrained RESTful Environments (CoRE) | |||
Parameters" <xref target="IANA.CoreParameters"/> registry:</t> | Parameters" <xref target="IANA.CoreParameters" format="default"/> registry:< | |||
/t> | ||||
<t><?rfc subcompact="yes"?> | <dl newline="false" spacing="compact"> | |||
<list style='symbols'> | <dt>Value:</dt> | |||
<t>Value: <spanx style="verb">ace.ai</spanx></t> | <dd><tt>ace.ai</tt></dd> | |||
<t>Description: ACE-OAuth authz-info endpoint resource.</t> | <dt>Description:</dt> | |||
<t>Reference: [this document]</t> | <dd>ACE-OAuth authz-info endpoint resource.</dd> | |||
</list></t> | <dt>Reference:</dt> | |||
<t>Specific ACE-OAuth profiles can use this common resource type for | <dd>RFC 9200</dd> | |||
</dl> | ||||
<t>Specific ACE-OAuth profiles can use this common resource type for | ||||
defining their profile-specific discovery processes.</t> | defining their profile-specific discovery processes.</t> | |||
</section> | </section> | |||
<section anchor="IANAOAuthErrorCodes" numbered="true" toc="default"> | ||||
<section anchor="IANAOAuthErrorCodes" | <name>OAuth Extensions Errors</name> | |||
title="OAuth Extensions Error Registration"> | <t>This specification registers the following error values in the | |||
<t>This specification registers the following error values in the OAuth | "OAuth Extensions Error Registry" | |||
Extensions Error registry | <xref target="IANA.OAuthExtensionsErrorRegistry" format="default"/>.</t> | |||
<xref target="IANA.OAuthExtensionsErrorRegistry"/>.</t> | <dl newline="false" spacing="compact"> | |||
<dt>Name:</dt> | ||||
<t><?rfc subcompact="yes"?> | <dd><tt>unsupported_pop_key</tt></dd> | |||
<list style='symbols'> | <dt>Usage Location:</dt> | |||
<t>Error name: <spanx style="verb">unsupported_pop_key</spanx></t> | <dd>token error response</dd> | |||
<t>Error usage location: token error response</t> | <dt>Protocol Extension:</dt> | |||
<t>Related protocol extension: [this document]</t> | <dd>RFC 9200</dd> | |||
<t>Change Controller: IESG</t> | <dt>Change Controller:</dt> | |||
<t>Specification document(s): <xref target="errorsToken"/> of | <dd>IETF</dd> | |||
[this document]</t> | <dt>Reference:</dt> | |||
</list></t> | <dd><xref target="errorsToken" format="default"/> of RFC 9200</dd> | |||
</dl> | ||||
<t><?rfc subcompact="yes"?> | <dl newline="false" spacing="compact"> | |||
<list style='symbols'> | <dt>Name:</dt> | |||
<t>Error name: <spanx style="verb">incompatible_ace_profiles</spanx></t> | <dd><tt>incompatible_ace_profiles</tt></dd> | |||
<t>Error usage location: token error response</t> | <dt>Usage Location:</dt> | |||
<t>Related protocol extension: [this document]</t> | <dd>token error response</dd> | |||
<t>Change Controller: IESG</t> | <dt>Protocol Extension:</dt> | |||
<t>Specification document(s): <xref target="errorsToken"/> of | <dd>RFC 9200</dd> | |||
[this document]</t> | <dt>Change Controller:</dt> | |||
</list></t> | <dd>IETF</dd> | |||
</section> | <dt>Reference:</dt> | |||
<section anchor="IANAErrorCBORMappings" | <dd><xref target="errorsToken" format="default"/> of RFC 9200</dd> | |||
title="OAuth Error Code CBOR Mappings Registry"> | </dl> | |||
<t>This specification establishes the IANA "OAuth Error Code | </section> | |||
CBOR Mappings" registry. The registry has been created to use the "Expert | <section anchor="IANAErrorCBORMappings" numbered="true" toc="default"> | |||
Review" registration procedure <xref target="RFC8126"/>, except | <name>OAuth Error Code CBOR Mappings</name> | |||
for the value range designated for private use.</t> | <t>This specification establishes the IANA "OAuth Error Code | |||
CBOR Mappings" registry.</t> | ||||
<t>The columns of the registry are: | <t>The columns of the registry are:</t> | |||
<dl newline="false"> | ||||
<list style='hanging'> | <dt>Name:</dt> | |||
<t hangText='Name'>The OAuth Error Code name, refers to the name in | <dd>The OAuth Error Code name, refers to the name in | |||
Section 5.2. of <xref target="RFC6749"/>, e.g., "invalid_request".</t> | <xref target="RFC6749" sectionFormat="of" section="5.2"/>, e.g., | |||
"invalid_request".</dd> | ||||
<t hangText='CBOR Value'>CBOR abbreviation for this error code. Integer | <dt>CBOR Value:</dt> | |||
values less than -65536 are marked as "Private Use", all other values use | <dd>CBOR abbreviation for this error code. | |||
the registration policy "Expert Review" <xref target="RFC8126"/>.</t> | Integer values less than -65536 are marked as Private Use; all other values use | |||
the registration policy Expert Review <xref target="RFC8126" format="default"/>. | ||||
<t hangText='Reference'>This contains a pointer to the public | </dd> | |||
specification of the error code abbreviation, if one exists.</t> | <dt>Reference:</dt> | |||
</list></t> | <dd>This contains a pointer to the public | |||
specification of the error code abbreviation, if one exists.</dd> | ||||
<t>This registry will be initially populated by the values in | <dt>Original Specification:</dt> | |||
<xref target="fig:cborErrorCodes"/>. The Reference column for all of | <dd>This contains a pointer to the public | |||
these entries will be this document.</t> | specification of the error code, if one exists.</dd> | |||
</section> | </dl> | |||
<section anchor="IANAGrantTypeMappings" | ||||
title="OAuth Grant Type CBOR Mappings"> | ||||
<t>This specification establishes the IANA "OAuth Grant Type CBOR Mappings" | ||||
registry. The registry has been created to use the "Expert Review" | ||||
registration procedure <xref target="RFC8126"/>, except for the value range | ||||
designated for private use. </t> | ||||
<t>The columns of this registry are: | ||||
<list style='hanging'> | ||||
<t hangText='Name'>The name of the grant type as specified in | ||||
Section 1.3 of <xref target="RFC6749"/>.</t> | ||||
<t hangText='CBOR Value'>CBOR abbreviation for this grant type. Integer | ||||
values less than -65536 are marked as "Private Use", all other values use | ||||
the registration policy "Expert Review" <xref target="RFC8126"/>.</t> | ||||
<t hangText='Reference'>This contains a pointer to the public | ||||
specification of the grant type abbreviation, if one exists.</t> | ||||
<t hangText='Original Specification'>This contains a pointer to | ||||
the public specification of the grant type, if one exists.</t> | ||||
</list></t> | ||||
<t>This registry will be initially populated by the values in | ||||
<xref target="fig:grant_types"/>. The Reference column for all of | ||||
these entries will be this document.</t> | ||||
</section> | ||||
<section anchor="IANAOAuthTokenType" title="OAuth Access Token Types"> | ||||
<t>This section registers the following new token type in the | ||||
"OAuth Access Token Types" registry <xref | ||||
target="IANA.OAuthAccessTokenTypes"/>.</t> | ||||
<t><?rfc subcompact="yes"?> | ||||
<list style='symbols'> | ||||
<t>Type name: <spanx style="verb">PoP</spanx></t> | ||||
<t>Additional Token Endpoint Response Parameters: "cnf", "rs_cnf" | ||||
see section 3.3 of <xref target="I-D.ietf-ace-oauth-params"/>.</t> | ||||
<t>HTTP Authentication Scheme(s): N/A</t> | ||||
<t>Change Controller: IETF</t> | ||||
<t>Specification document(s): [this document]</t> | ||||
</list></t> | ||||
</section> | ||||
<section anchor="IANATokenTypeMappings" | ||||
title="OAuth Access Token Type CBOR Mappings"> | ||||
<t>This specification established the IANA "OAuth Access Token Type CBOR | ||||
Mappings" registry. The registry has been created to use the "Expert | ||||
Review" registration procedure <xref target="RFC8126"/>, except for the | ||||
value range designated for private use. </t> | ||||
<t>The columns of this registry are: | ||||
<list style='hanging'> | ||||
<t hangText='Name'>The name of token type as registered in the | ||||
OAuth Access Token Types registry, e.g., "Bearer".</t> | ||||
<t hangText='CBOR Value'>CBOR abbreviation for this token type. Integer | ||||
values less than -65536 are marked as "Private Use", all other values use | ||||
the registration policy "Expert Review" <xref target="RFC8126"/>.</t> | ||||
<t hangText='Reference'>This contains a pointer to the public | ||||
specification of the OAuth token type abbreviation, if one exists.</t> | ||||
<t hangText='Original Specification'>This contains a pointer to | ||||
the public specification of the OAuth token type, if one exists.</t> | ||||
</list></t> | ||||
<section anchor="IANATokenTypeMappingsInitial" title="Initial Registry Conte | ||||
nts"> | ||||
<t> | ||||
<?rfc subcompact="yes"?> | ||||
<list style='symbols'> | ||||
<t>Name: <spanx style="verb">Bearer</spanx></t> | ||||
<t>Value: 1</t> | ||||
<t>Reference: [this document]</t> | ||||
<t>Original Specification: <xref target="RFC6749"/></t> | ||||
</list> | ||||
</t> | ||||
<t> | ||||
<?rfc subcompact="yes"?> | ||||
<list style='symbols'> | ||||
<t>Name: <spanx style="verb">PoP</spanx></t> | ||||
<t>Value: 2</t> | ||||
<t>Reference: [this document]</t> | ||||
<t>Original Specification: [this document]</t> | ||||
</list> | ||||
</t> | ||||
</section> | ||||
</section> | ||||
<section anchor="IANAProfile" | ||||
title="ACE Profile Registry"> | ||||
<t>This specification establishes the IANA "ACE Profile" registry. The | ||||
registry has been created to use the "Expert Review" registration | ||||
procedure <xref target="RFC8126"/>. It should be noted that, in addition to | ||||
the expert review, some portions of the registry require a specification, | ||||
potentially a Standards Track RFC, be supplied as well.</t> | ||||
<t>The columns of this registry are: | ||||
<list style='hanging'> | ||||
<t hangText='Name'> The name of the profile, to be used as value of | ||||
the profile attribute.</t> | ||||
<t hangText='Description'> Text giving an overview of the profile and | ||||
the context it is developed for.</t> | ||||
<t hangText='CBOR Value'>CBOR abbreviation for this profile name. | ||||
Different ranges of values use different registration policies <xref | ||||
target="RFC8126"/>. Integer values from -256 to 255 are designated as | ||||
Standards Action. Integer values from -65536 to -257 and from 256 to | ||||
65535 are designated as Specification Required. Integer values greater | ||||
than 65535 are designated as "Expert Review". Integer values less than | ||||
-65536 are marked as Private Use.</t> | ||||
<t hangText='Reference'>This contains a pointer to the public | ||||
specification of the profile abbreviation, if one exists.</t> | ||||
</list></t> | ||||
<t>This registry will be initially empty and will be populated by the | ||||
registrations from the ACE framework profiles.</t> | ||||
</section> | ||||
<section anchor="IANAOAuthParameter" | ||||
title="OAuth Parameter Registration"> | ||||
<t>This specification registers the following parameter in the "OAuth | ||||
Parameters" registry <xref target="IANA.OAuthParameters"/>:</t> | ||||
<t><?rfc subcompact="yes"?> | ||||
<list style='symbols'> | ||||
<t>Name: <spanx style="verb">ace_profile</spanx></t> | ||||
<t>Parameter Usage Location: token response</t> | ||||
<t>Change Controller: IESG</t> | ||||
<t>Reference: <xref target="tokenResponse"/> and | ||||
<xref target="paramProfile"/> of [this document]</t> | ||||
</list></t> | ||||
</section> | ||||
<section anchor="IANAOAuthParameterMappingsRegistry" | ||||
title="OAuth Parameters CBOR Mappings Registry"> | ||||
<t>This specification establishes the IANA "OAuth Parameters CBOR Mappings" | ||||
registry. The registry has been created to use the "Expert Review" | ||||
registration procedure <xref target="RFC8126"/>, except for the value range | ||||
designated for private use.</t> | ||||
<t>The columns of this registry are: | ||||
<list style='hanging'> | <t>This registry has been initially populated by the values in <xref targ | |||
<t hangText='Name'>The OAuth Parameter name, refers to the name in | et="table_cborErrorCodes"/>. The Reference column for all of these entries is th | |||
the OAuth parameter registry, e.g., "client_id".</t> | is document.</t> | |||
<t hangText='CBOR Key'>CBOR map key for this parameter. Integer | </section> | |||
values less than -65536 are marked as "Private Use", all other values use | <section anchor="IANAGrantTypeMappings" numbered="true" toc="default"> | |||
the registration policy "Expert Review" <xref target="RFC8126"/>.</t> | <name>OAuth Grant Type CBOR Mappings</name> | |||
<t>This specification establishes the IANA "OAuth Grant Type CBOR Mappin | ||||
gs" | ||||
registry.</t> | ||||
<t>The columns of this registry are:</t> | ||||
<dl newline="false"> | ||||
<dt>Name:</dt> | ||||
<dd>The name of the grant type, as specified in | ||||
<xref target="RFC6749" sectionFormat="of" section="1.3"/>.</dd> | ||||
<dt>CBOR Value:</dt> | ||||
<dd>CBOR abbreviation for this grant type. Integer | ||||
values less than -65536 are marked as Private Use; all other values use | ||||
the registration policy Expert Review <xref target="RFC8126" format="defau | ||||
lt"/>.</dd> | ||||
<dt>Reference:</dt> | ||||
<dd>This contains a pointer to the public | ||||
specification of the grant type abbreviation, if one exists.</dd> | ||||
<dt>Original Specification:</dt> | ||||
<dd>This contains a pointer to | ||||
the public specification of the grant type, if one exists.</dd> | ||||
</dl> | ||||
<t hangText='Value Type'>The allowable CBOR data types for values | <t>This registry has been initially populated by the values in <xref targ | |||
of this parameter.</t> | et="table_grant_types"/>. The Reference column for all of these entries is this | |||
document.</t> | ||||
<t hangText='Reference'>This contains a pointer to the public | </section> | |||
specification of the OAuth parameter abbreviation, if one exists.</t> | <section anchor="IANAOAuthTokenType" numbered="true" toc="default"> | |||
</list></t> | <name>OAuth Access Token Types</name> | |||
<t>This section registers the following new token type in the | ||||
"OAuth Access Token Types" registry <xref target="IANA.OAuthAccessTokenTypes | ||||
" format="default"/>.</t> | ||||
<dl newline="false" spacing="compact"> | ||||
<dt>Name:</dt> | ||||
<dd><tt>PoP</tt></dd> | ||||
<dt>Additional Token Endpoint Response Parameters:</dt> | ||||
<dd><tt>cnf</tt>, <tt>rs_cnf</tt> (see <xref target="RFC8747" sectionFo | ||||
rmat="of" section="3.1"/> and <xref target="RFC9201" | ||||
sectionFormat="of" section="3.2"/>).</dd> | ||||
<dt>HTTP Authentication Scheme(s):</dt> | ||||
<dd>N/A</dd> | ||||
<dt>Change Controller:</dt> | ||||
<dd>IETF</dd> | ||||
<dt>Reference:</dt> | ||||
<dd>RFC 9200</dd> | ||||
</dl> | ||||
</section> | ||||
<section anchor="IANATokenTypeMappings" numbered="true" toc="default"> | ||||
<name>OAuth Access Token Type CBOR Mappings</name> | ||||
<t>This specification establishes the IANA "OAuth Access Token Type CBOR | ||||
Mappings" registry.</t> | ||||
<t>The columns of this registry are:</t> | ||||
<dl newline="false"> | ||||
<dt>Name:</dt> | ||||
<dd>The name of the token type, as registered in the | ||||
"OAuth Access Token Types" registry, e.g., "Bearer".</dd> | ||||
<dt>CBOR Value:</dt> | ||||
<dd>CBOR abbreviation for this token type. Integer | ||||
values less than -65536 are marked as Private Use; all other values use | ||||
the registration policy Expert Review <xref target="RFC8126" format="defau | ||||
lt"/>.</dd> | ||||
<dt>Reference:</dt> | ||||
<dd>This contains a pointer to the public | ||||
specification of the OAuth token type abbreviation, if one exists.</dd> | ||||
<dt>Original Specification:</dt> | ||||
<dd>This contains a pointer to | ||||
the public specification of the OAuth token type, if one exists.</dd> | ||||
</dl> | ||||
<section anchor="IANATokenTypeMappingsInitial" numbered="true" toc="defa | ||||
ult"> | ||||
<name>Initial Registry Contents</name> | ||||
<dl newline="false" spacing="compact"> | ||||
<dt>Name:</dt> | ||||
<dd><tt>Bearer</tt></dd> | ||||
<dt>CBOR Value:</dt> | ||||
<dd>1</dd> | ||||
<dt>Reference:</dt> | ||||
<dd>RFC 9200</dd> | ||||
<dt>Original Specification:</dt> | ||||
<dd><xref target="RFC6749" format="default"/></dd> | ||||
</dl> | ||||
<dl newline="false" spacing="compact"> | ||||
<dt>Name:</dt> | ||||
<dd><tt>PoP</tt></dd> | ||||
<dt>CBOR Value:</dt> | ||||
<dd>2</dd> | ||||
<dt>Reference:</dt> | ||||
<dd>RFC 9200</dd> | ||||
<dt>Original Specification:</dt> | ||||
<dd>RFC 9200</dd> | ||||
</dl> | ||||
</section> | ||||
</section> | ||||
<section anchor="IANAProfile" numbered="true" toc="default"> | ||||
<name>ACE Profiles</name> | ||||
<t>This specification establishes the IANA "ACE Profile" registry. </t> | ||||
<t>The columns of this registry are:</t> | ||||
<dl newline="false"> | ||||
<dt>Name:</dt> | ||||
<dd> The name of the profile to be used as the value of | ||||
the profile attribute.</dd> | ||||
<dt>Description:</dt> | ||||
<dd> Text giving an overview of the profile and | ||||
the context it is developed for.</dd> | ||||
<dt>CBOR Value:</dt> | ||||
<dd>CBOR abbreviation for this profile name. Different ranges of value | ||||
s use different registration policies <xref | ||||
target="RFC8126" format="default"/>. Integer values from -256 to 255 a | ||||
re | ||||
designated as Standards Action. Integer values from -65536 to -257 and | ||||
from 256 | ||||
to 65535 are designated as Specification Required. Integer values grea | ||||
ter | ||||
than 65535 are designated as Expert Review. Integer values less than | ||||
-65536 are marked as Private Use.</dd> | ||||
<dt>Reference:</dt> | ||||
<dd>This contains a pointer to the public | ||||
specification of the profile abbreviation, if one exists.</dd> | ||||
</dl> | ||||
</section> | ||||
<section anchor="IANAOAuthParameter" numbered="true" toc="default"> | ||||
<name>OAuth Parameters</name> | ||||
<t>This specification registers the following parameter in the "OAuth | ||||
Parameters" registry <xref target="IANA.OAuthParameters" format="default"/>: | ||||
</t> | ||||
<dl newline="false" spacing="compact"> | ||||
<dt>Name:</dt> | ||||
<dd><tt>ace_profile</tt></dd> | ||||
<dt>Parameter Usage Location:</dt> | ||||
<dd>token response</dd> | ||||
<dt>Change Controller:</dt> | ||||
<dd>IETF</dd> | ||||
<dt>Reference:</dt> | ||||
<dd>Sections <xref target="tokenResponse" format="counter"/> and | ||||
<xref target="paramProfile" format="counter"/> of RFC 9200</dd> | ||||
</dl> | ||||
</section> | ||||
<section anchor="IANAOAuthParameterMappingsRegistry" numbered="true" toc=" | ||||
default"> | ||||
<name>OAuth Parameters CBOR Mappings</name> | ||||
<t>This specification establishes the IANA "OAuth Parameters CBOR Mappin | ||||
gs" | ||||
registry.</t> | ||||
<t>The columns of this registry are:</t> | ||||
<dl newline="false"> | ||||
<dt>Name:</dt> | ||||
<dd>The OAuth Parameter name, refers to the name in | ||||
the OAuth parameter registry, e.g., <tt>client_id</tt>.</dd> | ||||
<dt>CBOR Key:</dt> | ||||
<dd>CBOR map key for this parameter. Integer | ||||
values less than -65536 are marked as Private Use; all other values use | ||||
the registration policy Expert Review <xref target="RFC8126" format="defau | ||||
lt"/>.</dd> | ||||
<dt>Value Type:</dt> | ||||
<dd>The allowable CBOR data types for values | ||||
of this parameter.</dd> | ||||
<dt>Reference:</dt> | ||||
<dd>This contains a pointer to the public | ||||
specification of the OAuth parameter abbreviation, if one exists.</dd> | ||||
<dt>Original Specification</dt> | ||||
<dd>This contains a pointer to the public | ||||
specification of the OAuth parameter, if one exists.</dd> | ||||
</dl> | ||||
<t>This registry will be initially populated by the values in | <t>This registry has been initially populated by the values in <xref targ | |||
<xref target="fig:cborTokenParameters"/>. The Reference column for all of | et="table_cborTokenParameters"/>. The Reference column for all of these entries | |||
these entries will be this document.</t> | is this document.</t> | |||
</section> | ||||
<section anchor="IANAOAuthIntrospectionResponseParameterRegistration" | </section> | |||
title="OAuth Introspection Response Parameter Registration"> | <section anchor="IANAOAuthIntrospectionResponseParameterRegistration" numb | |||
<t>This specification registers the following parameters in the OAuth | ered="true" toc="default"> | |||
Token Introspection Response registry <xref | <name>OAuth Introspection Response Parameters</name> | |||
target="IANA.TokenIntrospectionResponse"/>.</t> | <t>This specification registers the following parameters in the "OAuth | |||
<t> | Token Introspection Response" registry <xref target="IANA.TokenIntrospection | |||
<?rfc subcompact="yes"?> | Response" format="default"/>.</t> | |||
<list style='symbols'> | <dl newline="false" spacing="compact"> | |||
<t>Name: <spanx style="verb">ace_profile</spanx></t> | <dt>Name:</dt> | |||
<t>Description: The ACE profile used between client and RS.</t> | <dd><tt>ace_profile</tt></dd> | |||
<t>Change Controller: IESG</t> | <dt>Description:</dt> | |||
<t>Reference: <xref target="introRes"/> of [this document]</t> | <dd>The ACE profile used between the client and RS.</dd> | |||
</list> | <dt>Change Controller:</dt> | |||
</t> | <dd>IETF</dd> | |||
<t> | <dt>Reference:</dt> | |||
<?rfc subcompact="yes"?> | <dd> <xref target="introRes" format="default"/> of RFC 9200</dd> | |||
<list style='symbols'> | </dl> | |||
<t>Name: <spanx style="verb">cnonce</spanx></t> | <dl newline="false" spacing="compact"> | |||
<t>Description: "client-nonce". A nonce previously provided | <dt>Name:</dt> | |||
<dd><tt>cnonce</tt></dd> | ||||
<dt>Description:</dt> | ||||
<dd>"client-nonce". A nonce previously provided | ||||
to the AS by the RS via the client. Used to verify token freshness | to the AS by the RS via the client. Used to verify token freshness | |||
when the RS cannot synchronize its clock with the AS.</t> | when the RS cannot synchronize its clock with the AS.</dd> | |||
<t>Change Controller: IESG</t> | <dt>Change Controller:</dt> | |||
<t>Reference: <xref target="introRes"/> of [this document]</t> | <dd>IETF</dd> | |||
</list> | <dt>Reference:</dt> | |||
</t> | <dd><xref target="introRes" format="default"/> of RFC 9200</dd> | |||
<t> | </dl> | |||
<?rfc subcompact="yes"?> | <dl newline="false" spacing="compact"> | |||
<list style='symbols'> | <dt>Name</dt> | |||
<t>Name: <spanx style="verb">exi</spanx></t> | <dd><tt>cti</tt></dd> | |||
<t>Description: "Expires in". Lifetime of the token in seconds | <dt>Description</dt> | |||
from the time the RS first sees it. Used to implement a weaker from of | <dd>"CWT ID". The identifier of a CWT as defined in | |||
<xref target="RFC8392" format="default"/>.</dd> | ||||
<dt>Change Controller</dt> | ||||
<dd>IETF</dd> | ||||
<dt>Reference</dt> | ||||
<dd><xref target="introRes" format="default"/> of RFC 9200</dd> | ||||
</dl> | ||||
<dl newline="false" spacing="compact"> | ||||
<dt>Name:</dt> | ||||
<dd><tt>exi</tt></dd> | ||||
<dt>Description:</dt> | ||||
<dd>"Expires in". Lifetime of the token in seconds | ||||
from the time the RS first sees it. Used to implement a weaker form of | ||||
token expiration for devices that cannot synchronize their internal | token expiration for devices that cannot synchronize their internal | |||
clocks.</t> | clocks.</dd> | |||
<t>Change Controller: IESG</t> | <dt>Change Controller:</dt> | |||
<t>Reference: <xref target="introRes"/> of [this document]</t> | <dd>IETF</dd> | |||
</list> | <dt>Reference:</dt> | |||
</t> | <dd><xref target="introRes" format="default"/> of RFC 9200</dd> | |||
</section> | </dl> | |||
</section> | ||||
<section anchor="IANAIntrospectionEndpointCBORMappingsRegistry" | <section anchor="IANAIntrospectionEndpointCBORMappingsRegistry" numbered=" | |||
title="OAuth Token Introspection Response CBOR Mappings Registry"> | true" toc="default"> | |||
<t>This specification establishes the IANA "OAuth Token Introspection | <name>OAuth Token Introspection Response CBOR Mappings</name> | |||
Response CBOR Mappings" registry. The registry has been created to use the | <t>This specification establishes the IANA "OAuth Token Introspection | |||
"Expert Review" registration procedure <xref target="RFC8126"/>, except for | Response CBOR Mappings" registry.</t> | |||
the value range designated for private use.</t> | <t>The columns of this registry are:</t> | |||
<dl newline="false"> | ||||
<t>The columns of this registry are: | <dt>Name:</dt> | |||
<dd>The OAuth Parameter name, refers to the name in | ||||
<list style='hanging'> | the OAuth parameter registry, e.g., <tt>client_id</tt>.</dd> | |||
<t hangText='Name'>The OAuth Parameter name, refers to the name in | <dt>CBOR Key:</dt> | |||
the OAuth parameter registry, e.g., "client_id".</t> | <dd>CBOR map key for this parameter. Integer | |||
values less than -65536 are marked as Private Use; all other values use | ||||
<t hangText='CBOR Key'>CBOR map key for this parameter. Integer | the registration policy Expert Review <xref target="RFC8126" format="defau | |||
values less than -65536 are marked as "Private Use", all other values use | lt"/>.</dd> | |||
the registration policy "Expert Review" <xref target="RFC8126"/>.</t> | <dt>Value Type:</dt> | |||
<dd>The allowable CBOR data types for values | ||||
<t hangText='Value Type'>The allowable CBOR data types for values | of this parameter.</dd> | |||
of this parameter.</t> | <dt>Reference:</dt> | |||
<dd>This contains a pointer to the public | ||||
<t hangText='Reference'>This contains a pointer to the public | specification of the introspection response parameter abbreviation, if | |||
specification of the introspection response parameter abbreviation, if | one exists.</dd> | |||
one exists.</t> | <dt>Original Specification</dt> | |||
</list></t> | <dd>This contains a pointer to the public | |||
specification of the OAuth Token Introspection parameter, if one | ||||
<t>This registry will be initially populated by the values in | exists.</dd> | |||
<xref target="fig:cborIntrospectionParameters"/>. The Reference column for | </dl> | |||
all of these entries will be this document.</t> | <t> | |||
This registry has been initially populated by the values in <xref | ||||
<t>Note that the mappings of parameters corresponding to claim names | target="table_cborIntrospectionParameters"/>. The Reference column for all of th | |||
intentionally coincide with the CWT claim name mappings from <xref | ese entries is this document.</t> | |||
target="RFC8392"/>.</t> | ||||
</section> | ||||
<section anchor="IANAJWTClaims" title="JSON Web Token Claims"> | ||||
<t>This specification registers the following new claims in the JSON | ||||
Web Token (JWT) registry of JSON Web Token Claims <xref | ||||
target="IANA.JsonWebTokenClaims"/>:</t> | ||||
<t><?rfc subcompact="yes"?> | ||||
<list style='symbols'> | ||||
<t>Claim Name: <spanx style="verb">ace_profile</spanx></t> | ||||
<t>Claim Description: The ACE profile a token is supposed to be used | ||||
with.</t> | ||||
<t>Change Controller: IESG</t> | ||||
<t>Reference: <xref target="accessToken"/> of [this document]</t> | ||||
</list></t> | ||||
<t><?rfc subcompact="yes"?> | <t>Note that the mappings of parameters corresponding to claim names | |||
<list style='symbols'> | intentionally coincide with the CWT claim name mappings from <xref target="R | |||
<t>Claim Name: <spanx style="verb">cnonce</spanx></t> | FC8392" format="default"/>.</t> | |||
<t>Claim Description: "client-nonce". A nonce previously provided | </section> | |||
<section anchor="IANAJWTClaims" numbered="true" toc="default"> | ||||
<name>JSON Web Token Claims</name> | ||||
<t>This specification registers the following new claims in the "JSON | ||||
Web Token Claims" subregistry under the "JSON | ||||
Web Token (JWT)" registry <xref target="IANA.JsonWebTokenClaims" format="defa | ||||
ult"/>:</t> | ||||
<dl newline="false" spacing="compact"> | ||||
<dt>Claim Name:</dt> | ||||
<dd><tt>ace_profile</tt></dd> | ||||
<dt>Claim Description:</dt> | ||||
<dd>The ACE profile a token is supposed to be used with.</dd> | ||||
<dt>Change Controller:</dt> | ||||
<dd>IETF</dd> | ||||
<dt>Reference:</dt> | ||||
<dd><xref target="accessToken" format="default"/> of RFC 9200</dd> | ||||
</dl> | ||||
<dl newline="false" spacing="compact"> | ||||
<dt>Claim Name:</dt> | ||||
<dd><tt>cnonce</tt></dd> | ||||
<dt>Claim Description:</dt> | ||||
<dd>"client-nonce". A nonce previously provided | ||||
to the AS by the RS via the client. Used to verify token freshness | to the AS by the RS via the client. Used to verify token freshness | |||
when the RS cannot synchronize its clock with the AS.</t> | when the RS cannot synchronize its clock with the AS.</dd> | |||
<t>Change Controller: IESG</t> | <dt>Change Controller:</dt> | |||
<t>Reference: <xref target="accessToken"/> of [this document]</t> | <dd>IETF</dd> | |||
</list></t> | <dt>Reference:</dt> | |||
<dd><xref target="accessToken" format="default"/> of RFC 9200</dd> | ||||
<t><?rfc subcompact="yes"?> | </dl> | |||
<list style='symbols'> | <dl newline="false" spacing="compact"> | |||
<t>Claim Name: <spanx style="verb">exi</spanx></t> | <dt>Claim Name:</dt> | |||
<t>Claim Description: "Expires in". Lifetime of the token in seconds | <dd><tt>exi</tt></dd> | |||
from the time the RS first sees it. Used to implement a weaker from of | <dt>Claim Description:</dt> | |||
<dd>"Expires in". Lifetime of the token in seconds | ||||
from the time the RS first sees it. Used to implement a weaker form of | ||||
token expiration for devices that cannot synchronize their internal | token expiration for devices that cannot synchronize their internal | |||
clocks.</t> | clocks.</dd> | |||
<t>Change Controller: IESG</t> | <dt>Change Controller:</dt> | |||
<t>Reference: <xref target="tokenExpiration"/> of [this document]</t> | <dd>IETF</dd> | |||
</list></t> | <dt>Reference:</dt> | |||
<dd><xref target="tokenExpiration" format="default"/> of RFC 9200</dd> | ||||
</section> | </dl> | |||
</section> | ||||
<section anchor="IANACWTClaims" title="CBOR Web Token Claims"> | <section anchor="IANACWTClaims" numbered="true" toc="default"> | |||
<t>This specification registers the following new claims in the "CBOR | <name>CBOR Web Token Claims</name> | |||
Web Token (CWT) Claims" registry <xref | <t>This specification registers the following new claims in the "CBOR | |||
target="IANA.CborWebTokenClaims"/>.</t> | Web Token (CWT) Claims" registry <xref target="IANA.CborWebTokenClaims" form | |||
at="default"/>.</t> | ||||
<t><?rfc subcompact="yes"?> | <dl newline="false" spacing="compact"> | |||
<list style='symbols'> | <dt>Claim Name:</dt> | |||
<t>Claim Name: <spanx style="verb">ace_profile</spanx></t> | <dd><tt>ace_profile</tt></dd> | |||
<t>Claim Description: The ACE profile a token is supposed to be used | <dt>Claim Description:</dt> | |||
with.</t> | <dd>The ACE profile a token is supposed to be used with.</dd> | |||
<t>JWT Claim Name: ace_profile</t> | <dt>JWT Claim Name:</dt> | |||
<t>Claim Key: TBD (suggested: 38)</t> | <dd><tt>ace_profile</tt></dd> | |||
<t>Claim Value Type(s): integer</t> | <dt>Claim Key:</dt> | |||
<t>Change Controller: IESG</t> | <dd>38</dd> | |||
<t>Specification Document(s): <xref target="accessToken"/> of [this | <dt>Claim Value Type:</dt> | |||
document]</t> | <dd>integer</dd> | |||
</list></t> | <dt>Change Controller:</dt> | |||
<dd>IETF</dd> | ||||
<t><?rfc subcompact="yes"?> | <dt>Reference:</dt> | |||
<list style='symbols'> | <dd><xref target="accessToken" format="default"/> of RFC 9200</dd> | |||
<t>Claim Name: <spanx style="verb">cnonce</spanx></t> | </dl> | |||
<t>Claim Description: The client-nonce sent to the AS by the | <dl newline="false" spacing="compact"> | |||
RS via the client.</t> | <dt>Claim Name:</dt> | |||
<t>JWT Claim Name: cnonce</t> | <dd><tt>cnonce</tt></dd> | |||
<t>Claim Key: TBD (suggested: 39)</t> | <dt>Claim Description:</dt> | |||
<t>Claim Value Type(s): byte string</t> | <dd>The client-nonce sent to the AS by the RS via the client.</dd> | |||
<t>Change Controller: IESG</t> | <dt>JWT Claim Name:</dt> | |||
<t>Specification Document(s): <xref target="accessToken"/> of [this | <dd><tt>cnonce</tt></dd> | |||
document]</t> | <dt>Claim Key:</dt> | |||
</list></t> | <dd>39</dd> | |||
<dt>Claim Value Type:</dt> | ||||
<t><?rfc subcompact="yes"?> | <dd>byte string</dd> | |||
<list style='symbols'> | <dt>Change Controller:</dt> | |||
<t>Claim Name: <spanx style="verb">exi</spanx></t> | <dd>IETF</dd> | |||
<t>Claim Description: The expiration time of a token measured from | <dt>Reference:</dt> | |||
when it was received at the RS in seconds.</t> | <dd><xref target="accessToken" format="default"/> of RFC 9200</dd> | |||
<t>JWT Claim Name: exi</t> | </dl> | |||
<t>Claim Key: TBD (suggested: 40)</t> | <dl newline="false" spacing="compact"> | |||
<t>Claim Value Type(s): integer</t> | <dt>Claim Name:</dt> | |||
<t>Change Controller: IESG</t> | <dd><tt>exi</tt></dd> | |||
<t>Specification Document(s): <xref target="tokenExpiration"/> of [this | <dt>Claim Description:</dt> | |||
document]</t> | <dd>The expiration time of a token measured from when it was received a | |||
</list></t> | t the RS | |||
in seconds.</dd> | ||||
<t><?rfc subcompact="yes"?> | <dt>JWT Claim Name:</dt> | |||
<list style='symbols'> | <dd><tt>exi</tt></dd> | |||
<t>Claim Name: <spanx style="verb">scope</spanx></t> | <dt>Claim Key:</dt> | |||
<t>Claim Description: The scope of an access token as | <dd>40</dd> | |||
defined in <xref target="RFC6749"/>.</t> | <dt>Claim Value Type:</dt> | |||
<t>JWT Claim Name: scope</t> | <dd>unsigned integer</dd> | |||
<t>Claim Key: TBD (suggested: 9)</t> | <dt>Change Controller:</dt> | |||
<t>Claim Value Type(s): byte string or text string</t> | <dd>IETF</dd> | |||
<t>Change Controller: IESG</t> | <dt>Reference:</dt> | |||
<t>Specification Document(s): Section 4.2 of | <dd><xref target="tokenExpiration" format="default"/> of RFC 9200</dd> | |||
<xref target="RFC8693"/></t> | </dl> | |||
</list></t> | <dl newline="false" spacing="compact"> | |||
<dt>Claim Name:</dt> | ||||
</section> | <dd><tt>scope</tt></dd> | |||
<dt>Claim Description:</dt> | ||||
<section anchor="IANAmediaType" title="Media Type Registrations"> | <dd>The scope of an access token, as defined in <xref target="RFC6749" | |||
<t>This specification registers the 'application/ace+cbor' media type for | format="default"/>.</dd> | |||
<dt>JWT Claim Name:</dt> | ||||
<dd><tt>scope</tt></dd> | ||||
<dt>Claim Key:</dt> | ||||
<dd>9</dd> | ||||
<dt>Claim Value Type:</dt> | ||||
<dd>byte string or text string</dd> | ||||
<dt>Change Controller:</dt> | ||||
<dd>IETF</dd> | ||||
<dt>Reference:</dt> | ||||
<dd><xref target="RFC8693" sectionFormat="of" section="4.2"/></dd> | ||||
</dl> | ||||
</section> | ||||
<section anchor="IANAmediaType" numbered="true" toc="default"> | ||||
<name>Media Type Registration</name> | ||||
<t>This specification registers the "application/ace+cbor" media type fo | ||||
r | ||||
messages of the protocols defined in this document carrying parameters | messages of the protocols defined in this document carrying parameters | |||
encoded in CBOR. This registration follows the procedures specified in | encoded in CBOR. This registration follows the procedures specified in | |||
<xref target="RFC6838"/>.</t> | <xref target="RFC6838" format="default"/>.</t> | |||
<dl newline="false"> | ||||
<t>Type name: application</t> | <dt>Type name:</dt> | |||
<dd>application</dd> | ||||
<t>Subtype name: ace+cbor</t> | <dt>Subtype name:</dt> | |||
<dd>ace+cbor</dd> | ||||
<t>Required parameters: N/A</t> | <dt>Required parameters:</dt> | |||
<dd>N/A</dd> | ||||
<t>Optional parameters: N/A</t> | <dt>Optional parameters:</dt> | |||
<dd>N/A</dd> | ||||
<t>Encoding considerations: Must be encoded as CBOR map containing | <dt>Encoding considerations:</dt> | |||
the protocol parameters defined in [this document].</t> | <dd>Must be encoded as a CBOR map containing | |||
the protocol parameters defined in RFC 9200.</dd> | ||||
<t>Security considerations: See <xref target="security"/> of [this | <dt>Security considerations:</dt> | |||
document]</t> | <dd>See <xref target="security" format="default"/> of RFC 9200</dd> | |||
<dt>Interoperability considerations:</dt> | ||||
<t>Interoperability considerations: N/A</t> | <dd>N/A</dd> | |||
<dt>Published specification:</dt> | ||||
<t>Published specification: [this document]</t> | <dd>RFC 9200</dd> | |||
<dt>Applications that use this media type:</dt> | ||||
<t>Applications that use this media type: The type is used by | <dd>The type is used by | |||
authorization servers, clients and resource servers that support the ACE | authorization servers, clients, and resource servers that support the ACE | |||
framework with CBOR encoding as specified in [this document].</t> | framework with CBOR encoding, as specified in RFC 9200.</dd> | |||
<dt>Fragment identifier considerations:</dt> | ||||
<t>Fragment identifier considerations: N/A </t> | <dd>N/A</dd> | |||
<dt>Additional information:</dt> | ||||
<t>Additional information: N/A</t> | <dd>N/A</dd> | |||
<dt>Person & email address to contact for further information:</dt> | ||||
<t>Person & email address to contact for further information: | <dd><br/>IESG <iesg@ietf.org></dd> | |||
<iesg@ietf.org></t> | <dt>Intended usage:</dt> | |||
<dd>COMMON</dd> | ||||
<t>Intended usage: COMMON</t> | <dt>Restrictions on usage:</dt> | |||
<dd>none</dd> | ||||
<t>Restrictions on usage: none</t> | <dt>Author:</dt> | |||
<dd>Ludwig Seitz <ludwig.seitz@combitech.se></dd> | ||||
<t>Author: Ludwig Seitz <ludwig.seitz@combitech.se></t> | <dt>Change controller:</dt> | |||
<dd>IETF</dd> | ||||
<t>Change controller: IESG</t> | </dl> | |||
</section> | </section> | |||
<section anchor="IANAcoapContentFormat" numbered="true" toc="default"> | ||||
<section anchor="IANAcoapContentFormat" title="CoAP Content-Format Registry"> | <name>CoAP Content-Formats</name> | |||
<t>This specification registers the following entry to the "CoAP | <t>The following entry has been registered in the "CoAP | |||
Content-Formats" | Content-Formats" registry:</t> | |||
registry:</t> | <dl newline="false" spacing="compact"> | |||
<t>Media Type: application/ace+cbor</t> | <dt>Media Type:</dt> | |||
<t>Encoding: -</t> | <dd>application/ace+cbor</dd> | |||
<t>ID: TBD (suggested: 19)</t> | <dt>Encoding:</dt> | |||
<t>Reference: [this document]</t> | <dd>-</dd> | |||
</section> | <dt>ID:</dt> | |||
<dd>19</dd> | ||||
<section anchor="IANAinstructions" title="Expert Review Instructions"> | <dt>Reference:</dt> | |||
<t>All of the IANA registries established in this document are defined | <dd>RFC 9200</dd> | |||
</dl> | ||||
</section> | ||||
<section anchor="IANAinstructions" numbered="true" toc="default"> | ||||
<name>Expert Review Instructions</name> | ||||
<t>All of the IANA registries established in this document are defined | ||||
to use a registration policy of Expert Review. This section gives some gener al guidelines for | to use a registration policy of Expert Review. This section gives some gener al guidelines for | |||
what the experts should be looking for, but they are being designated | what the experts should be looking for, but they are being designated | |||
as experts for a reason, so they should be given substantial | as experts for a reason, so they should be given substantial | |||
latitude.</t> | latitude.</t> | |||
<t>Expert Reviewers should take into consideration the following points: | ||||
<t>Expert reviewers should take into consideration the following points: | </t> | |||
<list style="symbols"> | <ul spacing="normal"> | |||
<t>Point squatting should be discouraged. Reviewers are encouraged | <li>Point squatting should be discouraged. Reviewers are encouraged | |||
to get sufficient information for registration requests to ensure | to get sufficient information for registration requests to ensure | |||
that the usage is not going to duplicate one that is already | that the usage is not going to duplicate one that is already | |||
registered, and that the point is likely to be used in deployments. The | registered and that the point is likely to be used in deployments. The | |||
zones tagged as private use are intended for testing purposes and closed | zones tagged as Private Use are intended for testing purposes and closed | |||
environments; code points in other ranges should not be assigned for | environments; code points in other ranges should not be assigned for | |||
testing.</t> | testing.</li> | |||
<li>Specifications are needed for the first-come, first-serve range if | ||||
<t>Specifications are needed for the first-come, first-serve range if | ||||
they are expected to be used outside of closed environments in an | they are expected to be used outside of closed environments in an | |||
interoperable way. When specifications are not provided, the description | interoperable way. When specifications are not provided, the description | |||
provided needs to have sufficient information to identify what the point | provided needs to have sufficient information to identify what the point | |||
is being used for.</t> | is being used for.</li> | |||
<li>Experts should take into account the expected usage of fields when | ||||
<t>Experts should take into account the expected usage of fields when | ||||
approving point assignment. The fact that there is a range for | approving point assignment. The fact that there is a range for | |||
standards track documents does not mean that a standards track | Standards Track documents does not mean that a Standards Track | |||
document cannot have points assigned outside of that range. The | document cannot have points assigned outside of that range. The | |||
length of the encoded value should be weighed against how many | length of the encoded value should be weighed against how many | |||
code points of that length are left, the size of device it will be | code points of that length are left, i.e., the size of device it will be | |||
used on.</t> | used on.</li> | |||
<li>Since a high degree of overlap is expected between these registrie | ||||
<t>Since a high degree of overlap is expected between these registries | s | |||
and the contents of the OAuth parameters <xref | and the contents of the OAuth parameters <xref target="IANA.OAuthParameter | |||
target="IANA.OAuthParameters"/> registries, experts should require new | s" format="default"/> registries, experts should require new | |||
registrations to maintain alignment with parameters from OAuth that have | registrations to maintain alignment with parameters from OAuth that have | |||
comparable functionality. Deviation from this alignment should only | comparable functionality. Deviation from this alignment should only | |||
be allowed if there are functional differences, that are motivated by | be allowed if there are functional differences that are motivated by | |||
the use case and that cannot be easily or efficiently addressed by | the use case and that cannot be easily or efficiently addressed by | |||
comparable OAuth parameters.</t> | comparable OAuth parameters.</li> | |||
</list></t> | </ul> | |||
</section> | </section> | |||
</section> | ||||
</section><!-- IANA considerations --> | </middle> | |||
<section anchor="Acknowledgments" title="Acknowledgments"> | ||||
<t>This document is a product of the ACE working group of the IETF.</t> | ||||
<t>Thanks to Eve Maler for her contributions to the use of | ||||
OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion | ||||
input, and Malisa Vucinic for his input on the predecessors of this | ||||
proposal.</t> | ||||
<t>Thanks to the authors of draft-ietf-oauth-pop-key-distribution, from where | ||||
parts of the security considerations where copied.</t> | ||||
<t>Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten | ||||
Bormann for contributing their work on AS discovery from | ||||
draft-gerdes-ace-dcaf-authorize (see <xref target="asDiscovery"/>) and | ||||
the considerations on multiple access tokens.</t> | ||||
<t>Thanks to Jim Schaad and Mike Jones for their comprehensive reviews.</t> | ||||
<t>Thanks to Benjamin Kaduk for his input on various questions related to | ||||
this work.</t> | ||||
<t>Thanks to Cigdem Sengul for some very useful review comments.</t> | <back> | |||
<t>Thanks to Carsten Bormann for contributing the text for the CoRE Resource | <displayreference target="I-D.erdtman-oauth-rpcc" to="OAUTH-RPCC"/> | |||
Type registry.</t> | <displayreference target="I-D.gerdes-ace-dcaf-authorize" to="DCAF"/> | |||
<displayreference target="I-D.ietf-oauth-pop-key-distribution" to="POP-KEY-DIST" | ||||
/> | ||||
<t>Thanks to Roman Danyliw for suggesting the <xref target="app:diffOAuth"/> | <references> | |||
(including its contents).</t> | <name>References</name> | |||
<references> | ||||
<name>Normative References</name> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3986. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6347. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6749. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6750. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6838. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6920. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8949. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7252. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7519. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7662. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8126. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8152. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8392. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8693. | ||||
xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8747. | ||||
xml"/> | ||||
<xi:include | ||||
href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8610.xml"/> | ||||
<t>Ludwig Seitz and Goeran Selander worked on this document as part of | <reference anchor='RFC9201' target="https://www.rfc-editor.org/info/rfc9201"> | |||
the CelticPlus project CyberWI, with funding from Vinnova. Ludwig Seitz | <front> | |||
was also received further funding for this work by Vinnova in the context of | <title>Additional OAuth Parameters for Authentication and Authorization in Const | |||
the CelticNext project Critisec.</t> | rained Environments (ACE)</title> | |||
</section> | <author initials='L' surname='Seitz' fullname='Ludwig Seitz'> | |||
<organization /> | ||||
</author> | ||||
<date year='2022' month='August'/> | ||||
</front> | ||||
<seriesInfo name="RFC" value="9201"/> | ||||
<seriesInfo name="DOI" value="10.17487/RFC9201"/> | ||||
</reference> | ||||
<!-- Possibly a 'Contributors' section ... --> | <reference anchor="IANA.OAuthAccessTokenTypes" target="https://www.iana. | |||
</middle> | org/assignments/oauth-parameters"> | |||
<front> | ||||
<title>OAuth Access Token Types</title> | ||||
<author> | ||||
<organization>IANA</organization> | ||||
</author> | ||||
</front> | ||||
</reference> | ||||
<!-- *****BACK MATTER ***** --> | <reference anchor="IANA.OAuthParameters" target="https://www.iana.org/as | |||
signments/oauth-parameters"> | ||||
<front> | ||||
<title>OAuth Parameters</title> | ||||
<author> | ||||
<organization>IANA</organization> | ||||
</author> | ||||
</front> | ||||
</reference> | ||||
<back> | <reference anchor="IANA.TokenIntrospectionResponse" target="https://www. | |||
<!-- References split into informative and normative --> | iana.org/assignments/oauth-parameters"> | |||
<front> | ||||
<title>OAuth Token Introspection Response</title> | ||||
<author> | ||||
<organization>IANA</organization> | ||||
</author> | ||||
</front> | ||||
</reference> | ||||
<!-- There are 2 ways to insert reference entries from the citation librarie | <reference anchor="IANA.JsonWebTokenClaims" target="https://www.iana.org | |||
s: | /assignments/jwt"> | |||
1. define an ENTITY at the top, and use "ampersand character"RFC2629; here | <front> | |||
(as shown) | <title>JSON Web Token Claims</title> | |||
2. simply use a PI "less than character"?rfc include="reference.RFC.2119.xm | <author> | |||
l"?> here | <organization>IANA</organization> | |||
(for I-Ds: include="reference.I-D.narten-iana-considerations-rfc2434bis. | </author> | |||
xml") | </front> | |||
</reference> | ||||
Both are cited textually in the same manner: by using xref elements. | <reference anchor="IANA.CborWebTokenClaims" target="https://www.iana.org | |||
If you use the PI option, xml2rfc will, by default, try to find included fi | /assignments/cwt"> | |||
les in the same | <front> | |||
directory as the including file. You can also define the XML_LIBRARY enviro | <title>CBOR Web Token (CWT) Claims</title> | |||
nment variable | <author> | |||
with a value containing a set of directories to search. These can be eithe | <organization>IANA</organization> | |||
r in the local | </author> | |||
filing system or remote ones accessed by http (http://domain/dir/... ).--> | </front> | |||
</reference> | ||||
<references title="Normative References"> | <reference anchor="IANA.OAuthExtensionsErrorRegistry" target="https://ww | |||
<!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC. | w.iana.org/assignments/oauth-parameters"> | |||
2119.xml"?--> | <front> | |||
&RFC2119; | <title>OAuth Extensions Error Registry</title> | |||
&RFC3986; | <author> | |||
&RFC6347; | <organization>IANA</organization> | |||
&RFC6749; | </author> | |||
&RFC6750; | </front> | |||
&RFC6838; | </reference> | |||
&RFC6920; | ||||
&RFC8949; | ||||
&RFC7252; | ||||
&RFC7519; | ||||
&RFC7662; | ||||
&RFC8126; | ||||
&RFC8152; | ||||
&RFC8174; | ||||
&RFC8392; | ||||
&RFC8693; | ||||
&RFC8747; | ||||
&I-D.ietf-ace-oauth-params; | ||||
<reference anchor="IANA.OAuthAccessTokenTypes" target="https://www.iana.or | <reference anchor="IANA.CoreParameters" target="https://www.iana.org/ass | |||
g/assignments/oauth-parameters/oauth-parameters.xhtml#token-types"> | ignments/core-parameters"> | |||
<front> | <front> | |||
<title>OAuth Access Token Types</title> | <title>Constrained RESTful Environments (CoRE) Parameters</title> | |||
<author> | <author> | |||
<organization>IANA</organization> | <organization>IANA</organization> | |||
</author> | </author> | |||
<date/> | </front> | |||
</front> | </reference> | |||
</reference> | <xi:include | |||
href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4648.xml"/> | ||||
</references> | ||||
<reference anchor="IANA.OAuthParameters" target="https://www.iana.org/assi | <references> | |||
gnments/oauth-parameters/oauth-parameters.xhtml#parameters"> | <name>Informative References</name> | |||
<front> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<title>OAuth Parameters</title> | FC.4949.xml"/> | |||
<author> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<organization>IANA</organization> | FC.6690.xml"/> | |||
</author> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<date/> | FC.6819.xml"/> | |||
</front> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
</reference> | FC.7009.xml"/> | |||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.7228.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.9110.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.7521.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.9113.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.7591.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.7641.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.7744.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.7959.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8252.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8259.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8414.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8446.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8516.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8613.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8628.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/refe | ||||
rence.RFC.9147.xml"/> | ||||
<reference anchor="IANA.TokenIntrospectionResponse" target="https://www.ia | <xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.erdtman | |||
na.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-introspection-r | -oauth-rpcc-00.xml"/> | |||
esponse"> | ||||
<front> | ||||
<title>OAuth Token Introspection Response</title> | ||||
<author> | ||||
<organization>IANA</organization> | ||||
</author> | ||||
<date/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor="IANA.JsonWebTokenClaims" target="https://www.iana.org/a | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
ssignments/jwt/jwt.xhtml#claims"> | FC.9000.xml"/> | |||
<front> | ||||
<title>JSON Web Token Claims</title> | ||||
<author> | ||||
<organization>IANA</organization> | ||||
</author> | ||||
<date/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor="IANA.CborWebTokenClaims" target="https://www.iana.org/a | <reference anchor='RFC9203' target='https://www.rfc-editor.org/info/rfc9203'> | |||
ssignments/cwt/cwt.xhtml#claims-registry"> | <front> | |||
<front> | <title>The Object Security for Constrained RESTful Environments (OSCORE) Profile | |||
<title>CBOR Web Token (CWT) Claims</title> | of the Authentication and Authorization for Constrained Environments (ACE) Fram | |||
<author> | ework</title> | |||
<organization>IANA</organization> | <author initials='F' surname='Palombini' fullname='Francesca Palombini'> | |||
</author> | <organization /> | |||
<date/> | </author> | |||
</front> | <author initials='L' surname='Seitz' fullname='Ludwig Seitz'> | |||
</reference> | <organization /> | |||
</author> | ||||
<author initials='G' surname='Selander' fullname='Goeran Selander'> | ||||
<organization /> | ||||
</author> | ||||
<author initials='M' surname='Gunnarsson' fullname='Martin Gunnarsson'> | ||||
<organization /> | ||||
</author> | ||||
<date year="2022" month="August" /> | ||||
</front> | ||||
<seriesInfo name="RFC" value="9203"/> | ||||
<seriesInfo name="DOI" value="10.17487/RFC9203"/> | ||||
</reference> | ||||
<reference anchor="IANA.OAuthExtensionsErrorRegistry" target="https://www. | <reference anchor='RFC9202' target='https://www.rfc-editor.org/info/rfc9202'> | |||
iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#extensions-error"> | <front> | |||
<front> | <title>Datagram Transport Layer Security (DTLS) Profile for Authentication and A | |||
<title>OAuth Extensions Error Registry</title> | uthorization for Constrained Environments (ACE)</title> | |||
<author> | <author initials='S' surname='Gerdes' fullname='Stefanie Gerdes'> | |||
<organization>IANA</organization> | <organization /> | |||
</author> | </author> | |||
<date/> | <author initials='O' surname='Bergmann' fullname='Olaf Bergmann'> | |||
</front> | <organization /> | |||
</reference> | </author> | |||
<author initials='C' surname='Bormann' fullname='Carsten Bormann'> | ||||
<organization /> | ||||
</author> | ||||
<author initials='G' surname='Selander' fullname='Goeran Selander'> | ||||
<organization /> | ||||
</author> | ||||
<author initials='L' surname='Seitz' fullname='Ludwig Seitz'> | ||||
<organization /> | ||||
</author> | ||||
<date year="2022" month="August"/> | ||||
</front> | ||||
<seriesInfo name="RFC" value="9202"/> | ||||
<seriesInfo name="DOI" value="10.17487/RFC9202"/> | ||||
</reference> | ||||
<reference anchor="IANA.CoreParameters" | <xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.ietf-oa | |||
target="https://www.iana.org/assignments/core-parameters/core-pa | uth-pop-key-distribution-07.xml"/> | |||
rameters.xhtml"> | ||||
<front> | ||||
<title>Constrained RESTful Environments (CoRE) Parameters</title> | ||||
<author> | ||||
<organization>IANA</organization> | ||||
</author> | ||||
<date/> | ||||
</front> | ||||
</reference> | ||||
</references> | <xi:include | |||
href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D.gerdes-ace-dcaf-aut | ||||
horize-04.xml"/> | ||||
<references title="Informative References"> | <reference anchor="Margi10impact"> | |||
&RFC4949; | <front> | |||
&RFC6690; | <title>Impact of Operating Systems on Wireless Sensor Networks | |||
&RFC6819; | ||||
&RFC7009; | ||||
&RFC7228; | ||||
&RFC7231; | ||||
&RFC7521; | ||||
&RFC7540; | ||||
&RFC7591; | ||||
&RFC7641; | ||||
&RFC7744; | ||||
&RFC7959; | ||||
&RFC8252; | ||||
&RFC8259; | ||||
&RFC8414; | ||||
&RFC8446; | ||||
&RFC8516; | ||||
&RFC8613; | ||||
&RFC8628; | ||||
&I-D.ietf-tls-dtls13; | ||||
&I-D.erdtman-ace-rpcc; | ||||
&I-D.ietf-quic-transport; | ||||
&I-D.ietf-ace-oscore-profile; | ||||
&I-D.ietf-ace-dtls-authorize; | ||||
<reference anchor="Margi10impact"> | ||||
<front> | ||||
<title>Impact of Operating Systems on Wireless Sensor Networks | ||||
(Security) Applications and Testbeds</title> | (Security) Applications and Testbeds</title> | |||
<author initials="C. B." surname="Margi"/> | <author initials="C." surname="Margi"/> | |||
<author initials="B.T." surname="de Oliveira"/> | <author initials="B." surname="de Oliveira"/> | |||
<author initials="G.T." surname="de Sousa"/> | <author initials="G." surname="de Sousa"/> | |||
<author initials="M.A." surname="Simplicio Jr"/> | <author initials="M." surname="Simplicio Jr"/> | |||
<author initials="P.S.L.M." surname="Barreto"/> | <author initials="P." surname="Barreto"/> | |||
<author initials="T.C.M.B." surname="Carvalho"/> | <author initials="T." surname="Carvalho"/> | |||
<author initials="M." surname="Naeslund"/> | <author initials="M." surname="Naeslund"/> | |||
<author initials="R." surname="Gold"/> | <author initials="R." surname="Gold"/> | |||
<date year="2010" month="August" /> | <date year="2010" month="August"/> | |||
</front> | </front> | |||
<seriesInfo name="Proceedings of the" value="19th International Conferen | <seriesInfo name="DOI" value="10.1109/ICCCN.2010.5560028"/> | |||
ce on Computer Communications and Networks (ICCCN)"/> | <refcontent>Proceedings of the 19th International Conference on Comput | |||
</reference> | er | |||
<reference anchor="MQTT5.0" target="https://docs.oasis-open.org/mqtt/mqtt/ | Communications and Networks</refcontent> | |||
v5.0/mqtt-v5.0.html"> | </reference> | |||
<front> | ||||
<title>MQTT Version 5.0</title> | <reference anchor="MQTT5.0" target="https://docs.oasis-open.org/mqtt/mqt | |||
t/v5.0/mqtt-v5.0.html"> | ||||
<front> | ||||
<title>MQTT Version 5.0</title> | ||||
<author initials="A." surname="Banks"/> | <author initials="A." surname="Banks"/> | |||
<author initials="E." surname="Briggs"/> | <author initials="E." surname="Briggs"/> | |||
<author initials="K." surname="Borgendale"/> | <author initials="K." surname="Borgendale"/> | |||
<author initials="R." surname="Gupta"/> | <author initials="R." surname="Gupta"/> | |||
<date year="2019" month="March"/> | <date year="2019" month="March"/> | |||
</front> | </front> | |||
<seriesInfo name="OASIS" value="Standard"/> | <refcontent>OASIS Standard</refcontent> | |||
</reference> | </reference> | |||
<reference anchor="BLE" target="https://www.bluetooth.com/specifications/b | ||||
luetooth-core-specification/"> | ||||
<front> | ||||
<title>Bluetooth Core Specification v5.1</title> | ||||
<author initials="" surname="Bluetooth SIG"/> | ||||
<date year="2019" month="January"/> | ||||
</front> | ||||
<seriesInfo name="Section" value="4.4"/> | ||||
</reference> | ||||
<reference anchor="BLE" target="https://www.bluetooth.com/specifications | ||||
/bluetooth-core-specification/"> | ||||
<front> | ||||
<title>Core Specification 5.3</title> | ||||
<author> | ||||
<organization>Bluetooth Special Interest Group</organization> | ||||
</author> | ||||
<date year="2021" month="July"/> | ||||
</front> | ||||
<seriesInfo name="Section" value="4.4"/> | ||||
</reference> | ||||
</references> | ||||
</references> | </references> | |||
<section anchor="constraints" numbered="true" toc="default"> | ||||
<section title="Design Justification" anchor="constraints"> | <name>Design Justification</name> | |||
<t>This section provides further insight into the design decisions | <t>This section provides further insight into the design decisions | |||
of the solution documented in this document. <xref target="overview"/> | of the solution documented in this document. <xref target="overview" forma | |||
t="default"/> | ||||
lists several building blocks and briefly summarizes their importance. | lists several building blocks and briefly summarizes their importance. | |||
The justification for offering some of those building blocks, as opposed | The justification for offering some of those building blocks, as opposed | |||
to using OAuth 2.0 as is, is given below.</t> | to using OAuth 2.0 as is, is given below.</t> | |||
<t>Common IoT constraints are: | ||||
<t>Common IoT constraints are: | </t> | |||
<dl newline="true" spacing="normal"> | ||||
<list style="hanging"> | <dt>Low Power Radio:</dt> | |||
<dd> | ||||
<t hangText="Low Power Radio:"><vspace blankLines="1"/> | Many IoT devices are equipped with a small battery that needs | |||
Many IoT devices are equipped with a small battery which needs | ||||
to last for a long time. For many constrained wireless devices, the | to last for a long time. For many constrained wireless devices, the | |||
highest energy cost is associated to transmitting or receiving | highest energy cost is associated to transmitting or receiving | |||
messages (roughly by a factor of 10 compared to AES) | messages (roughly by a factor of 10 compared to AES) | |||
<xref target="Margi10impact"/>. It is therefore important to keep | <xref target="Margi10impact" format="default"/>. It is therefore impor | |||
tant | ||||
to keep | ||||
the total communication overhead low, including minimizing the number | the total communication overhead low, including minimizing the number | |||
and size of messages sent and received, which has an impact of choice | and size of messages sent and received, which has an impact of choice | |||
on the message format and protocol. By using CoAP over UDP and CBOR | on the message format and protocol. By using CoAP over UDP and | |||
encoded messages, some of these aspects are addressed. Security | CBOR-encoded messages, some of these aspects are addressed. Security | |||
protocols contribute to the communication overhead and can, in some | protocols contribute to the communication overhead and can, in some | |||
cases, be optimized. For example, authentication and key | cases, be optimized. For example, authentication and key | |||
establishment may, in certain cases where security requirements | establishment may, in certain cases where security requirements | |||
allow, be replaced by provisioning of security context by a trusted | allow, be replaced by the provisioning of security context by a trusted | |||
third party, using transport or application-layer security. | third party, using transport or application-layer security. | |||
<vspace blankLines="0"/> | </dd> | |||
</t> | <dt>Low CPU Speed:</dt> | |||
<dd> | ||||
<t hangText="Low CPU Speed:"><vspace blankLines="1"/> | ||||
Some IoT devices are equipped with processors that are significantly | Some IoT devices are equipped with processors that are significantly | |||
slower than those found in most current devices on the Internet. | slower than those found in most current devices on the Internet. | |||
This typically has implications on what timely cryptographic | This typically has implications on what timely cryptographic | |||
operations a device is capable of performing, which in turn impacts, | operations a device is capable of performing, which in turn impacts, | |||
e.g., protocol latency. Symmetric key cryptography may be used | e.g., protocol latency. Symmetric key cryptography may be used | |||
instead of the computationally more expensive public key cryptography | instead of the computationally more expensive public key cryptography | |||
where the security requirements so allow, but this may also require | where the security requirements so allow, but this may also require | |||
support for trusted-third-party-assisted secret key establishment | support for trusted, third-party-assisted secret key establishment | |||
using transport- or application-layer security. | using transport- or application-layer security. | |||
<vspace blankLines="0"/></t> | </dd> | |||
<dt>Small Amount of Memory:</dt> | ||||
<t hangText="Small Amount of Memory:"> <vspace blankLines="1"/> | <dd> | |||
Microcontrollers embedded in IoT devices are often equipped with | Microcontrollers embedded in IoT devices are often equipped with | |||
only a small amount of RAM and flash memory, which places limitations on what | only a small amount of RAM and flash memory, which places limitations on what | |||
kind of processing can be performed and how much code can be put on | kind of processing can be performed and how much code can be put on | |||
those devices. To reduce code size, fewer and smaller protocol | those devices. To reduce code size, fewer and smaller protocol | |||
implementations can be put on the firmware of such a device. In | implementations can be put on the firmware of such a device. In | |||
this case, CoAP may be used instead of HTTP, symmetric-key | this case, CoAP may be used instead of HTTP, symmetric-key | |||
cryptography instead of public-key cryptography, and CBOR instead of | cryptography may be used instead of public-key cryptography, and CBOR | |||
may be used | ||||
instead of | ||||
JSON. An authentication and key establishment protocol, e.g., the DTL S | JSON. An authentication and key establishment protocol, e.g., the DTL S | |||
handshake, in comparison with assisted key establishment, also has | handshake, in comparison with assisted key establishment, also has | |||
an impact on memory and code footprints.<vspace blankLines="0"/> | an impact on memory and code footprints. | |||
</t> | </dd> | |||
<dt>User Interface Limitations:</dt> | ||||
<t hangText="User Interface Limitations:"> <vspace blankLines="1"/> | <dd> | |||
Protecting access to resources is both an important security as well | Protecting access to resources is both an important security as well | |||
as privacy feature. End users and enterprise customers may not want | as privacy feature. End users and enterprise customers may not want | |||
to give access to the data collected by their IoT device or to | to give access to the data collected by their IoT device or to | |||
functions it may offer to third parties. Since the classical | functions it may offer to third parties. Since the classical | |||
approach of requesting permissions from end users via a rich user | approach of requesting permissions from end users via a rich user | |||
interface does not work in many IoT deployment scenarios, these | interface does not work in many IoT deployment scenarios, these | |||
functions need to be delegated to user-controlled devices that are | functions need to be delegated to user-controlled devices that are | |||
better suitable for such tasks, such as smart phones and tablets. | better suitable for such tasks, such as smartphones and tablets. | |||
<vspace blankLines="1"/></t> | </dd> | |||
<dt>Communication Constraints:</dt> | ||||
<t hangText="Communication Constraints:"> <vspace blankLines="1"/> | <dd> | |||
In certain constrained settings an IoT device may not be able to | <t> | |||
In certain constrained settings, an IoT device may not be able to | ||||
communicate with a given device at all times. Devices may be | communicate with a given device at all times. Devices may be | |||
sleeping, or just disconnected from the Internet because of general | sleeping or just disconnected from the Internet because of general | |||
lack of connectivity in the area, for cost reasons, or for security | lack of connectivity in the area, cost reasons, or security | |||
reasons, e.g., to avoid an entry point for Denial-of-Service attacks. | reasons, e.g., to avoid an entry point for denial-of-service attacks. | |||
</t> | ||||
<vspace blankLines="1"/> | <t> | |||
The communication interactions this framework builds upon (as shown | The communication interactions this framework builds upon (as shown | |||
graphically in <xref target="fig:protocolFlow"/>) may be accomplished | graphically in <xref target="fig_protocolFlow" format="default"/>) may | |||
be | ||||
accomplished | ||||
using a variety of different protocols, and not all parts of the | using a variety of different protocols, and not all parts of the | |||
message flow are used in all applications due to the communication | message flow are used in all applications due to the communication | |||
constraints. Deployments making use of CoAP are expected, but this fr | constraints. Deployments making use of CoAP are expected, but this | |||
amework is not | framework is not | |||
limited to them. Other protocols such as HTTP, or even protocols | limited to them. Other protocols, such as HTTP or | |||
such as Bluetooth Smart communication that do not | Bluetooth Smart communication, that do not | |||
necessarily use IP, could also be used. The latter raises the need | necessarily use IP could also be used. The latter raises the need | |||
for application-layer security over the various interfaces.</t> | for application-layer security over the various interfaces.</t> | |||
</list> | </dd> | |||
</t> | </dl> | |||
<t>In the light of these constraints, we have made the following design | ||||
<t>In the light of these constraints we have made the following design | decisions:</t> | |||
decisions: | <dl newline="true" spacing="normal"> | |||
<dt>CBOR, COSE, CWT:</dt> | ||||
<list style="hanging"> | <dd> | |||
When using this framework, it is <bcp14>RECOMMENDED</bcp14> to use CBOR | ||||
<t hangText="CBOR, COSE, CWT:"><vspace blankLines="1"/> | <xref target="RFC8949" format="default"/> as the data format. Where CB | |||
When using this framework, it is RECOMMENDED to use CBOR | OR data | |||
<xref target="RFC8949"/> as data format. Where CBOR data needs to be | needs to be | |||
protected, the use of COSE <xref target="RFC8152"/> is RECOMMENDED. | protected, the use of COSE <xref target="RFC8152" format="default"/> is | |||
Furthermore, where self-contained tokens are needed, it is RECOMMENDED | <bcp14>RECOMMENDED</bcp14>. | |||
to use of CWT <xref target="RFC8392"/>. These measures aim at reducing | Furthermore, where self-contained tokens are needed, it is | |||
<bcp14>RECOMMENDED</bcp14> | ||||
to use CWT <xref target="RFC8392" format="default"/>. These measures a | ||||
im | ||||
at reducing | ||||
the size of messages sent over the wire, the RAM size of data objects | the size of messages sent over the wire, the RAM size of data objects | |||
that need to be kept in memory and the size of libraries that devices | that need to be kept in memory, and the size of libraries that devices | |||
need to support. | need to support. | |||
<vspace blankLines="1"/></t> | </dd> | |||
<dt>CoAP:</dt> | ||||
<t hangText="CoAP:"><vspace blankLines="1"/> | <dd> | |||
When using this framework, it is RECOMMENDED to use of CoAP | When using this framework, it is <bcp14>RECOMMENDED</bcp14> to use CoAP | |||
<xref target="RFC7252"/> instead of HTTP. This does not preclude the | <xref target="RFC7252" format="default"/> instead of HTTP. This does n | |||
use of other protocols specifically aimed at constrained devices, like, | ot | |||
e.g., Bluetooth Low Energy (see <xref target="coap"/>). This aims | preclude the | |||
use of other protocols specifically aimed at constrained devices, | ||||
e.g., Bluetooth Low Energy (see <xref target="coap" format="default"/>) | ||||
. | ||||
This aims | ||||
again at reducing the size of messages sent over the wire, the RAM size | again at reducing the size of messages sent over the wire, the RAM size | |||
of data objects that need to be kept in memory and the size of | of data objects that need to be kept in memory, and the size of | |||
libraries that devices need to support. | libraries that devices need to support. | |||
<vspace blankLines="1"/></t> | </dd> | |||
<dt>Access Information:</dt> | ||||
<t hangText="Access Information:"><vspace blankLines="1"/> | <dd> | |||
This framework defines the name "Access Information" for data | This framework defines the name "Access Information" for data | |||
concerning the RS that the AS returns to the client in an access | concerning the RS that the AS returns to the client in an access | |||
token response (see <xref target="tokenResponse"/>). This aims at | token response (see <xref target="tokenResponse" format="default"/>). | |||
enabling scenarios where a powerful client, supporting multiple | This | |||
profiles, needs to interact with an RS for which it does not know the | aims at | |||
enabling scenarios where a powerful client supporting multiple | ||||
profiles needs to interact with an RS for which it does not know the | ||||
supported profiles and the raw public key. | supported profiles and the raw public key. | |||
<vspace blankLines="1"/></t> | </dd> | |||
<dt>Proof of Possession:</dt> | ||||
<t hangText="Proof-of-Possession:"><vspace blankLines="1"/> | <dd> | |||
This framework makes use of proof-of-possession tokens, using | This framework makes use of proof-of-possession tokens, using | |||
the "cnf" claim <xref target="RFC8747"/>. A request | the <tt>cnf</tt> claim <xref target="RFC8747" format="default"/>. A re | |||
parameter "cnf" and a Response parameter "cnf", both having a | quest | |||
value space semantically and syntactically identical to the "cnf" | parameter <tt>cnf</tt> and a Response parameter <tt>cnf</tt>, both havi | |||
claim, are defined for the token endpoint, to allow requesting and | ng a | |||
value space semantically and syntactically identical to the <tt>cnf</tt | ||||
> | ||||
claim, are defined for the token endpoint to allow requesting and | ||||
stating confirmation keys. This aims at making token theft harder. | stating confirmation keys. This aims at making token theft harder. | |||
Token theft is specifically relevant in constrained use cases, as | Token theft is specifically relevant in constrained use cases, as | |||
communication often passes through middle-boxes, which could be able | communication often passes through middleboxes, which could be able | |||
to steal bearer tokens and use them to gain unauthorized access. | to steal bearer tokens and use them to gain unauthorized access. | |||
<vspace blankLines="1"/> </t> | </dd> | |||
<dt>Authz-Info endpoint:</dt> | ||||
<t hangText="Authz-Info endpoint:"><vspace blankLines="1"/> | <dd> | |||
This framework introduces a new way of providing access tokens | This framework introduces a new way of providing access tokens | |||
to an RS by exposing a authz-info endpoint, to which access tokens | to an RS by exposing an authz-info endpoint to which access tokens | |||
can be POSTed. This aims at reducing the size of the request | can be POSTed. This aims at reducing the size of the request | |||
message and the code complexity at the RS. The size of the request | message and the code complexity at the RS. The size of the request | |||
message is problematic, since many constrained protocols have severe | message is problematic, since many constrained protocols have severe | |||
message size limitations at the physical layer (e.g., in the order of | message size limitations at the physical layer (e.g., in the order of | |||
100 bytes). This means that larger packets get fragmented, which in | 100 bytes). This means that larger packets get fragmented, which in | |||
turn combines badly with the high rate of packet loss, and the | turn combines badly with the high rate of packet loss and the | |||
need to retransmit the whole message if one packet gets lost. | need to retransmit the whole message if one packet gets lost. | |||
Thus separating sending of the request and sending of the access | Thus, separating sending of the request and sending of the access | |||
tokens helps to reduce fragmentation. | tokens helps to reduce fragmentation. | |||
<vspace blankLines="1"/></t> | </dd> | |||
<dt>Client Credentials Grant:</dt> | ||||
<t hangText="Client Credentials Grant:"><vspace blankLines="1"/> | <dd> | |||
In this framework the use of the client credentials grant is | In this framework, the use of the client credentials grant is | |||
RECOMMENDED for machine-to-machine communication use cases, where | <bcp14>RECOMMENDED</bcp14> for machine-to-machine communication use cas | |||
es, | ||||
where | ||||
manual intervention of the resource owner to produce a grant token is | manual intervention of the resource owner to produce a grant token is | |||
not feasible. The intention is that the resource owner would instead | not feasible. The intention is that the resource owner would instead | |||
pre-arrange authorization with the AS, based on the client's own | prearrange authorization with the AS based on the client's own | |||
credentials. The client can then (without manual intervention) obtain | credentials. The client can then (without manual intervention) obtain | |||
access tokens from the AS. | access tokens from the AS. | |||
<vspace blankLines="1"/></t> | </dd> | |||
<dt>Introspection:</dt> | ||||
<t hangText="Introspection:"><vspace blankLines="1"/> | <dd> | |||
In this framework the use of access token introspection is RECOMMENDED | In this framework, the use of access token introspection is | |||
in cases where the client is constrained in a way that it can not | <bcp14>RECOMMENDED</bcp14> | |||
easily obtain new access tokens (i.e. it has connectivity issues | in cases where the client is constrained in a way that it cannot | |||
that prevent it from communicating with the AS). In that case | easily obtain new access tokens (i.e., it has connectivity issues | |||
it is RECOMMENDED to use a long-term token, that could be a simple | that prevent it from communicating with the AS). In that case, | |||
reference. The RS is assumed to be able to communicate | it is <bcp14>RECOMMENDED</bcp14> to use a long-term token that could be | |||
with the AS, and can therefore perform introspection, in order to | a | |||
simple reference. The RS is assumed to be able to communicate | ||||
with the AS and can therefore perform introspection in order to | ||||
learn the claims associated with the token reference. The advantage | learn the claims associated with the token reference. The advantage | |||
of such an approach is that the resource owner can change the claims | of such an approach is that the resource owner can change the claims | |||
associated to the token reference without having to be in contact | associated to the token reference without having to be in contact | |||
with the client, thus granting or revoking access rights. | with the client, thus granting or revoking access rights. | |||
<vspace blankLines="1"/></t> | </dd> | |||
</dl> | ||||
</list> | ||||
</t> | ||||
</section> | </section> | |||
<section anchor="app_rolesAndResponsibilities" numbered="true" toc="default" | ||||
<section anchor="app:rolesAndResponsibilities" title="Roles and Responsibili | > | |||
ties"> | <name>Roles and Responsibilities</name> | |||
<t><list style="hanging"> | <dl newline="true" spacing="normal"> | |||
<t hangText="Resource Owner"> | <dt>Resource Owner</dt> | |||
<list style="symbols"> | <dd> | |||
<t>Make sure that the RS is registered at the AS. This includes | <ul spacing="normal"> | |||
<li>Make sure that the RS is registered at the AS. This includes | ||||
making known to the AS which profiles, token_type, scopes, and | making known to the AS which profiles, token_type, scopes, and | |||
key types (symmetric/asymmetric) the RS supports. Also making | key types (symmetric/asymmetric) the RS supports. Also making | |||
it known to the AS which audience(s) the RS identifies itself | it known to the AS which audience(s) the RS identifies itself | |||
with.</t> | with.</li> | |||
<t>Make sure that clients can discover the AS that is in charge | <li>Make sure that clients can discover the AS that is in charge | |||
of the RS.</t> | of the RS.</li> | |||
<t>If the client-credentials grant is used, make sure that the AS | <li>If the client-credentials grant is used, make sure that the AS | |||
has the necessary, up-to-date, access control policies for the | has the necessary, up-to-date access control policies for the | |||
RS.</t> | RS.</li> | |||
</list> | </ul> | |||
<vspace blankLines="0"/> | </dd> | |||
</t> | <dt>Requesting Party</dt> | |||
<t hangText="Requesting Party"> | <dd> | |||
<list style="symbols"> | <ul spacing="normal"> | |||
<t>Make sure that the client is provisioned the necessary | <li>Make sure that the client is provisioned the necessary | |||
credentials to authenticate to the AS.</t> | credentials to authenticate to the AS.</li> | |||
<t>Make sure that the client is configured to follow the security | <li>Make sure that the client is configured to follow the security | |||
requirements of the Requesting Party when issuing requests | requirements of the requesting party when issuing requests | |||
(e.g., minimum communication security requirements, trust | (e.g., minimum communication security requirements or trust | |||
anchors).</t> | anchors).</li> | |||
<t>Register the client at the AS. This includes making known to | <li>Register the client at the AS. This includes making known to | |||
the AS which profiles, token_types, and key types | the AS which profiles, token_types, and key types | |||
(symmetric/asymmetric) the client.</t> | (symmetric/asymmetric) for the client.</li> | |||
</list> | </ul> | |||
<vspace blankLines="0"/> | </dd> | |||
</t> | <dt>Authorization Server</dt> | |||
<t hangText="Authorization Server"> | <dd> | |||
<list style="symbols"> | <ul spacing="normal"> | |||
<t>Register the RS and manage corresponding security contexts.</t> | <li>Register the RS and manage corresponding security contexts.</li> | |||
<t>Register clients and authentication credentials.</t> | <li>Register clients and authentication credentials.</li> | |||
<t>Allow Resource Owners to configure and update access control | <li>Allow resource owners to configure and update access control | |||
policies related to their registered RSs.</t> | policies related to their registered RSs.</li> | |||
<t>Expose the token endpoint to allow clients to request | <li>Expose the token endpoint to allow clients to request | |||
tokens.</t> | tokens.</li> | |||
<t>Authenticate clients that wish to request a token.</t> | <li>Authenticate clients that wish to request a token.</li> | |||
<t>Process a token request using the authorization | <li>Process a token request using the authorization | |||
policies configured for the RS.</t> | policies configured for the RS.</li> | |||
<t>Optionally: Expose the introspection endpoint that allows | <li>Optionally, expose the introspection endpoint that allows | |||
RS's to submit token introspection requests.</t> | RSs to submit token introspection requests.</li> | |||
<t>If providing an introspection endpoint: Authenticate RSs that | <li>If providing an introspection endpoint, authenticate RSs that | |||
wish to get an introspection response.</t> | wish to get an introspection response.</li> | |||
<t>If providing an introspection endpoint: Process token | <li>If providing an introspection endpoint, process token | |||
introspection requests.</t> | introspection requests.</li> | |||
<t>Optionally: Handle token revocation.</t> | <li>Optionally, handle token revocation.</li> | |||
<t>Optionally: Provide discovery metadata. See <xref | <li>Optionally, provide discovery metadata. See <xref target="RFC841 | |||
target="RFC8414"/></t> | 4" format="default"/>.</li> | |||
<t>Optionally: Handle refresh tokens.</t> | <li>Optionally, handle refresh tokens.</li> | |||
</list><vspace blankLines="0"/> | </ul> | |||
</t> | </dd> | |||
<t hangText="Client"> | <dt>Client</dt> | |||
<list style="symbols"> | <dd> | |||
<t>Discover the AS in charge of the RS that is to be targeted with | <ul spacing="normal"> | |||
a request.</t> | <li>Discover the AS in charge of the RS that is to be targeted with | |||
<t>Submit the token request (see step (A) of | a request.</li> | |||
<xref target="fig:protocolFlow"/>). | <li> | |||
<list style="symbols"> | <t>Submit the token request (see step (A) of | |||
<t>Authenticate to the AS.</t> | <xref target="fig_protocolFlow" format="default"/>). | |||
<t>Optionally (if not pre-configured): Specify which RS, which | </t> | |||
<ul spacing="normal"> | ||||
<li>Authenticate to the AS.</li> | ||||
<li>Optionally (if not preconfigured), specify which RS, which | ||||
resource(s), and which action(s) the request(s) will | resource(s), and which action(s) the request(s) will | |||
target.</t> | target.</li> | |||
<t>If raw public keys (rpk) or certificates are used, make sure | <li>If raw public keys (RPKs) or certificates are used, make sur | |||
the AS has the right rpk or certificate for this client.</t> | e | |||
</list> | the AS has the right RPK or certificate for this client.</li> | |||
</t> | </ul> | |||
<t>Process the access token and Access Information (see step (B) | </li> | |||
of <xref target="fig:protocolFlow"/>). | <li> | |||
<list style="symbols"> | <t>Process the access token and Access Information (see step (B) | |||
<t>Check that the Access Information provides the necessary | of <xref target="fig_protocolFlow" format="default"/>). | |||
security parameters (e.g., PoP key, information on | </t> | |||
communication security protocols supported by the RS).</t> | <ul spacing="normal"> | |||
<t>Safely store the proof-of-possession key.</t> | <li>Check that the Access Information provides the necessary | |||
<t>If provided by the AS: Safely store the refresh token.</t> | security parameters (e.g., PoP key or information on | |||
</list> | communication security protocols supported by the RS).</li> | |||
</t> | <li>Safely store the proof-of-possession key.</li> | |||
<t>Send the token and request to the RS (see step (C) of | <li>If provided by the AS, safely store the refresh token.</li> | |||
<xref target="fig:protocolFlow"/>). | </ul> | |||
<list style="symbols"> | </li> | |||
<t>Authenticate towards the RS (this could coincide with the | <li> | |||
proof of possession process).</t> | <t>Send the token and request to the RS (see step (C) of | |||
<t>Transmit the token as specified by the AS (default is to the | <xref target="fig_protocolFlow" format="default"/>). | |||
authz-info endpoint, alternative options are specified by | </t> | |||
profiles).</t> | <ul spacing="normal"> | |||
<t>Perform the proof-of-possession procedure as specified by | <li>Authenticate towards the RS (this could coincide with the | |||
proof-of-possession process).</li> | ||||
<li>Transmit the token as specified by the AS (default is to the | ||||
authz-info endpoint; alternative options are specified by | ||||
profiles).</li> | ||||
<li>Perform the proof-of-possession procedure as specified by | ||||
the profile in use (this may already have been taken care | the profile in use (this may already have been taken care | |||
of through the authentication procedure).</t> | of through the authentication procedure).</li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<t>Process the RS response (see step (F) of | <li>Process the RS response (see step (F) of | |||
<xref target="fig:protocolFlow"/>) of the RS.</t> | <xref target="fig_protocolFlow" format="default"/>) of the RS.</li> | |||
</list><vspace blankLines="0"/> | </ul> | |||
</t> | </dd> | |||
<t hangText="Resource Server"> | <dt>Resource Server</dt> | |||
<list style="symbols"> | <dd> | |||
<t>Expose a way to submit access tokens. By default this is | <ul spacing="normal"> | |||
the authz-info endpoint.</t> | <li>Expose a way to submit access tokens. By default, this is | |||
<t>Process an access token. | the authz-info endpoint.</li> | |||
<list style="symbols"> | <li> | |||
<t>Verify the token is from a recognized AS.</t> | <t>Process an access token. | |||
<t>Check the token's integrity.</t> | </t> | |||
<t>Verify that the token applies to this RS.</t> | <ul spacing="normal"> | |||
<t>Check that the token has not expired (if the token provides | <li>Verify the token is from a recognized AS.</li> | |||
expiration information).</t> | <li>Check the token's integrity.</li> | |||
<t>Store the token so that it can be retrieved in the context | <li>Verify that the token applies to this RS.</li> | |||
of a matching request.</t> | <li>Check that the token has not expired (if the token provides | |||
</list> | expiration information).</li> | |||
Note: The order proposed here is not normative, any process | <li>Store the token so that it can be retrieved in the context | |||
of a matching request.</li> | ||||
</ul> | ||||
<t> | ||||
Note: The order proposed here is not normative; any process | ||||
that arrives at an equivalent result can be used. A noteworthy | that arrives at an equivalent result can be used. A noteworthy | |||
consideration is whether one can use cheap operations early on to | consideration is whether one can use cheap operations early on to | |||
quickly discard non-applicable or invalid tokens, before | quickly discard nonapplicable or invalid tokens before | |||
performing expensive cryptographic operations (e.g. doing an | performing expensive cryptographic operations (e.g., doing an | |||
expiration check before verifying a signature). | expiration check before verifying a signature). | |||
<vspace blankLines="0"/> | </t> | |||
</t> | </li> | |||
<t>Process a request. | <li> | |||
<list style="symbols"> | <t>Process a request. | |||
<t>Set up communication security with the client.</t> | </t> | |||
<t>Authenticate the client.</t> | <ul spacing="normal"> | |||
<t>Match the client against existing tokens.</t> | <li>Set up communication security with the client.</li> | |||
<t>Check that tokens belonging to the client actually | <li>Authenticate the client.</li> | |||
authorize the requested action.</t> | <li>Match the client against existing tokens.</li> | |||
<t>Optionally: Check that the matching tokens are still valid, | <li>Check that tokens belonging to the client actually | |||
using introspection (if this is possible.)</t> | authorize the requested action.</li> | |||
</list> | <li>Optionally, check that the matching tokens are still valid, | |||
</t> | using introspection (if this is possible.)</li> | |||
<t>Send a response following the agreed upon communication | </ul> | |||
security mechanism(s).</t> | </li> | |||
<t>Safely store credentials such as raw public keys for | <li>Send a response following the agreed upon communication | |||
security mechanism(s).</li> | ||||
<li>Safely store credentials, such as raw public keys, for | ||||
authentication or proof-of-possession keys linked to access | authentication or proof-of-possession keys linked to access | |||
tokens.</t> | tokens.</li> | |||
</list> | </ul> | |||
</t> | </dd> | |||
</list></t> | </dl> | |||
</section> | </section> | |||
<section anchor="app_profileRequirements" numbered="true" toc="default"> | ||||
<!-- ***************************************************** --> | <name>Requirements on Profiles</name> | |||
<section anchor="app:profileRequirements" title="Requirements on Profiles"> | <t>This section lists the requirements on profiles of this framework | |||
<t>This section lists the requirements on profiles of this framework, | for the convenience of profile designers.</t> | |||
for the convenience of profile designers. | <ul spacing="normal"> | |||
<li>Optionally, define new methods for the client to discover the | ||||
<list style="symbols"> | necessary permissions and AS for accessing a resource different from | |||
<t>Optionally define new methods for the client to discover the | the one proposed in Sections <xref target="asDiscovery" format="counter"/ | |||
necessary permissions and AS for accessing a resource, different from | > and <xref | |||
the one proposed in <xref target="asDiscovery"/>. <xref target="specs"/> | target="specs" format="counter"/></li> | |||
</t> | <li>Optionally, specify new grant types | |||
(<xref target="authorizationGrants" format="default"/>).</li> | ||||
<t>Optionally specify new grant types. | <li>Optionally, define the use of client certificates as client credenti | |||
<xref target="authorizationGrants"/></t> | al | |||
type (<xref target="clientCredentials" format="default"/>).</li> | ||||
<t>Optionally define the use of client certificates as client credential | <li>Specify the communication protocol the client and RS must use | |||
type. <xref target="clientCredentials"/></t> | (e.g., CoAP) (Sections <xref target="oauthProfile" format="counter"/> and | |||
<xref | ||||
<t>Specify the communication protocol the client and RS the must use | target="paramProfile" format="counter"/>).</li> | |||
(e.g., CoAP). <xref target="oauthProfile"/> and <xref | <li>Specify the security protocol the client and RS must use to protect | |||
target="paramProfile"/></t> | their communication (e.g., OSCORE or DTLS). This must provide | |||
encryption and integrity and replay protection (<xref target="paramProfil | ||||
<t>Specify the security protocol the client and RS must use to protect | e" | |||
their communication (e.g., OSCORE or DTLS). This must provide | format="default"/>).</li> | |||
encryption, integrity and replay protection. <xref | <li>Specify how the client and the RS mutually authenticate (<xref targe | |||
target="paramProfile"/></t> | t="specs" | |||
format="default"/>).</li> | ||||
<t>Specify how the client and the RS mutually authenticate. <xref | <li>Specify the proof-of-possession protocol(s) and how to select one | |||
target="specs"/></t> | if several are available. Also specify which key types | |||
(e.g., symmetric/asymmetric) are supported by a specific proof-of-possess | ||||
<t>Specify the proof-of-possession protocol(s) and how to select one, | ion | |||
if several are available. Also specify which key types | protocol (<xref target="paramTokenType" format="default"/>).</li> | |||
(e.g., symmetric/asymmetric) are supported by a specific proof-of-possession | <li>Specify a unique <tt>ace_profile</tt> identifier (<xref target="para | |||
protocol. <xref target="paramTokenType"/></t> | mProfile" | |||
format="default"/>).</li> | ||||
<t>Specify a unique ace_profile identifier. <xref | <li>If introspection is supported, specify the communication and securit | |||
target="paramProfile"/></t> | y | |||
protocol for introspection (<xref target="introspectionEndpoint" | ||||
<t>If introspection is supported: Specify the communication and security | format="default"/>).</li> | |||
protocol for introspection. <xref target="introspectionEndpoint"/></t> | <li>Specify the communication and security protocol for interactions bet | |||
ween | ||||
<t>Specify the communication and security protocol for interactions between | the client and AS. This must provide encryption, integrity protection, | |||
client and AS. This must provide encryption, integrity protection, | replay protection, and a binding between requests and responses (Section | |||
replay protection and a binding between requests and responses. <xref | s <xref | |||
target="oauthProfile"/> and <xref target="tokenEndpoint"/></t> | target="oauthProfile" format="counter"/> and <xref target="tokenEndpoint" | |||
format="counter"/>).</li> | ||||
<t>Specify how/if the authz-info endpoint is protected, including | <li>Specify how/if the authz-info endpoint is protected, including | |||
how error responses are protected. <xref | how error responses are protected (<xref target="tokenAuthInfoEndpoint" | |||
target="tokenAuthInfoEndpoint"/></t> | format="default"/>).</li> | |||
<li>Optionally, define other methods of token transport than the authz-i | ||||
<t>Optionally define other methods of token transport than the authz-info | nfo | |||
endpoint. <xref target="tokenAuthInfoEndpoint"/></t> | endpoint (<xref target="tokenAuthInfoEndpoint" format="default"/>).</li> | |||
</ul> | ||||
</list> | </section> | |||
<section anchor="app_registration" numbered="true" toc="default"> | ||||
</t> | <name>Assumptions on AS Knowledge about the C and RS</name> | |||
<t>This section lists the assumptions on what an AS should know about a | ||||
</section> | ||||
<section anchor="app:registration" | ||||
title="Assumptions on AS Knowledge about C and RS"> | ||||
<t>This section lists the assumptions on what an AS should know about a | ||||
client and an RS in order to be able to respond to requests to the token | client and an RS in order to be able to respond to requests to the token | |||
and introspection endpoints. How this information is established is out of | and introspection endpoints. How this information is established is out of | |||
scope for this document. | scope for this document. | |||
<list style="symbols"> | </t> | |||
<t>The identifier of the client or RS.</t> | <ul spacing="normal"> | |||
<t>The profiles that the client or RS supports.</t> | <li>The identifier of the client or RS.</li> | |||
<t>The scopes that the RS supports.</t> | <li>The profiles that the client or RS supports.</li> | |||
<t>The audiences that the RS identifies with.</t> | <li>The scopes that the RS supports.</li> | |||
<t>The key types (e.g., pre-shared symmetric key, raw public key, | <li>The audiences that the RS identifies with.</li> | |||
key length, other key parameters) that the client or RS supports.</t> | <li>The key types (e.g., pre-shared symmetric key, raw public key, | |||
<t>The types of access tokens the RS supports (e.g., CWT).</t> | key length, and other key parameters) that the client or RS supports.</li | |||
<t>If the RS supports CWTs, the COSE parameters for the crypto wrapper | > | |||
(e.g., algorithm, key-wrap algorithm, key-length) that the RS supports.</t> | <li>The types of access tokens the RS supports (e.g., CWT).</li> | |||
<t>The expiration time for access tokens issued to this RS | <li>If the RS supports CWTs, the COSE parameters for the crypto wrapper | |||
(unless the RS accepts a default time chosen by the AS).</t> | (e.g., algorithm, key-wrap algorithm, and key-length) that the RS support | |||
<t>The symmetric key shared between client and AS (if any).</t> | s.</li> | |||
<t>The symmetric key shared between RS and AS (if any).</t> | <li>The expiration time for access tokens issued to this RS | |||
<t>The raw public key of the client or RS (if any).</t> | (unless the RS accepts a default time chosen by the AS).</li> | |||
<t>Whether the RS has synchronized time (and thus is able to use the 'exp' | <li>The symmetric key shared between the client and AS (if any).</li> | |||
claim) or not.</t> | <li>The symmetric key shared between the RS and AS (if any).</li> | |||
</list> | <li>The raw public key of the client or RS (if any).</li> | |||
</t> | <li>Whether the RS has synchronized time (and thus is able to use the <t | |||
</section> | t>exp</tt> | |||
claim) or not.</li> | ||||
<section anchor="app:diffOAuth" title="Differences to OAuth 2.0"> | </ul> | |||
<t>This document adapts OAuth 2.0 to be suitable for constrained environments. | </section> | |||
This sections lists the main differences from the normative requirements of | <section anchor="app_diffOAuth" numbered="true" toc="default"> | |||
OAuth 2.0. | <name>Differences to OAuth 2.0</name> | |||
<t>This document adapts OAuth 2.0 to be suitable for constrained environme | ||||
<list style="symbols"> | nts. | |||
<t>Use of TLS -- OAuth 2.0 requires the use of TLS both to protect the | This section lists the main differences from the normative requirements of | |||
communication between AS and client when requesting an access token; | OAuth 2.0.</t> | |||
between client and RS when accessing a resource and between AS and RS if | <dl newline="true" spacing="normal"> | |||
<dt>Use of TLS</dt> | ||||
<dd>OAuth 2.0 requires the use of TLS to protect the | ||||
communication between the AS and client when requesting an access token, | ||||
between the client and RS when accessing a resource, and between the AS a | ||||
nd RS if | ||||
introspection is used. This framework requires similar security | introspection is used. This framework requires similar security | |||
properties, but does not require that they be realized with TLS. | properties but does not require that they be realized with TLS. | |||
See <xref target="oauthProfile"/>.</t> | See <xref target="oauthProfile" format="default"/>.</dd> | |||
<dt>Cardinality of <tt>grant_type</tt> parameter</dt> | ||||
<t>Cardinality of "grant_type" parameter -- In client-to-AS requests | <dd>In client-to-AS requests | |||
using OAuth 2.0, the "grant_type" parameter is required (per | using OAuth 2.0, the <tt>grant_type</tt> parameter is required (per | |||
<xref target="RFC6749"/>). In this framework, this parameter is | <xref target="RFC6749" format="default"/>). In this framework, this para | |||
optional. See <xref target="tokenRequest"/>.</t> | meter | |||
is optional. See <xref target="tokenRequest" format="default"/>.</dd> | ||||
<t>Encoding of "scope" parameter -- In client-to-AS requests using OAuth | <dt>Encoding of <tt>scope</tt> parameter</dt> | |||
2.0, the "scope" parameter is string encoded (per | <dd>In client-to-AS requests using OAuth | |||
<xref target="RFC6749"/>). In this framework, this parameter may also be | 2.0, the <tt>scope</tt> parameter is string encoded (per | |||
encoded as a byte string. See <xref target="tokenRequest"/>.</t> | <xref target="RFC6749" format="default"/>). In this framework, this para | |||
meter | ||||
<t>Cardinality of "token_type" parameter -- in AS-to-client responses | may also be | |||
using OAuth 2.0, the token_type parameter is required (per | encoded as a byte string. See <xref target="tokenRequest" | |||
<xref target="RFC6749"/>). In this framework, this parameter is | format="default"/>.</dd> | |||
optional. See <xref target="tokenResponse"/>.</t> | <dt>Cardinality of <tt>token_type</tt> parameter</dt> | |||
<dd>In AS-to-client responses | ||||
<t>Access token retention -- in OAuth 2.0, the access token may be sent w | using OAuth 2.0, the <tt>token_type</tt> parameter is required (per | |||
ith | <xref target="RFC6749" format="default"/>). In this framework, this para | |||
every request to the RS. The exact use of access tokens depends on the se | meter | |||
mantics | is | |||
of the application and the session management concept it uses. In this fr | optional. See <xref target="tokenResponse" format="default"/>.</dd> | |||
amework, | <dt>Access token retention</dt> | |||
<dd>In OAuth 2.0, the access token may be sent with | ||||
every request to the RS. The exact use of access tokens depends on the | ||||
semantics | ||||
of the application and the session management concept it uses. In this | ||||
framework, | ||||
the RS must be able to store these tokens for later use. See | the RS must be able to store these tokens for later use. See | |||
<xref target="tokenAuthInfoEndpoint"/>.</t> | <xref target="tokenAuthInfoEndpoint" format="default"/>.</dd> | |||
</list> | </dl> | |||
</t> | </section> | |||
</section> | <section anchor="app_options" numbered="true" toc="default"> | |||
<name>Deployment Examples</name> | ||||
<!-- ***************************************************** --> | <t>There is a large variety of IoT deployments, as is indicated in | |||
<section anchor="app:options" title="Deployment Examples"> | <xref target="constraints" format="default"/>, and this section highligh | |||
<t>There is a large variety of IoT deployments, as is indicated in | ts a few common | |||
<xref target="constraints"/>, and this section highlights a few common | ||||
variants. This section is not normative but illustrates how the | variants. This section is not normative but illustrates how the | |||
framework can be applied. | framework can be applied. | |||
</t> | </t> | |||
<t>For each of the deployment variants, there are a number of possible | ||||
<t>For each of the deployment variants, there are a number of possible | security setups between clients, resource servers, and authorization | |||
security setups between clients, resource servers and authorization | ||||
servers. The main focus in the following subsections is on how | servers. The main focus in the following subsections is on how | |||
authorization of a client request for a resource hosted by an RS is | authorization of a client request for a resource hosted by an RS is | |||
performed. This requires the security of the requests and | performed. This requires the security of the requests and | |||
responses between the clients and the RS to be considered. | responses between the clients and the RS to be considered. | |||
</t> | </t> | |||
<t>Note: CBOR diagnostic notation is used for examples of requests | ||||
<t>Note: CBOR diagnostic notation is used for examples of requests | ||||
and responses.</t> | and responses.</t> | |||
<section anchor="localTokenValidation" numbered="true" toc="default"> | ||||
<name>Local Token Validation</name> | ||||
<t>In this scenario, the case where the resource server is offline is co | ||||
nsidered, | ||||
i.e., it is not connected to the AS at the time of the access request. | ||||
This access procedure involves steps (A), (B), (C), and (F) of <xref | ||||
target="fig_protocolFlow" format="default"/>.</t> | ||||
<t>Since the resource server must be able to verify the access token loc | ||||
ally, | ||||
self-contained access tokens must be used.</t> | ||||
<t>This example shows the interactions between a client, the | ||||
authorization server, and a temperature sensor acting as a resource serve | ||||
r. Message | ||||
exchanges A and B are shown in <xref target="fig_RSOffline" format="defau | ||||
lt"/>.</t> | ||||
<dl newline="false" spacing="normal" indent="4"> | ||||
<dt>A:</dt> | ||||
<dd> | ||||
<t>The client first generates a public-private key pair used for | ||||
communication security with the RS.</t> | ||||
<t>The client sends a CoAP POST request to the token endpoint at the | ||||
AS. | ||||
The security | ||||
of this request can be transport or application layer. It is up the | ||||
communication security profile to define. In the example, it is | ||||
assumed that both the client and AS have performed mutual authenticat | ||||
ion, | ||||
e.g., via DTLS. The request contains the public key of the client an | ||||
d | ||||
the <tt>audience</tt> parameter set to "tempSensorInLivingRoom", a va | ||||
lue that | ||||
the temperature sensor identifies itself with. The AS evaluates the | ||||
request and authorizes the client to access the resource.</t> | ||||
</dd> | ||||
<dt>B:</dt> | ||||
<dd> | ||||
<t>The AS responds with a 2.05 (Content) response containing the | ||||
Access Information, including the access token. | ||||
The PoP access token contains the public key of the client, and the | ||||
Access Information contains the public key of the RS. For communica | ||||
tion | ||||
security, this example uses DTLS RawPublicKey between the client and | ||||
the | ||||
RS. The issued token will have a short validity time, i.e., <tt>exp</ | ||||
tt> close | ||||
to <tt>iat</tt>, in order to mitigate attacks using stolen client cre | ||||
dentials. | ||||
The token includes claims, such as <tt>scope</tt>, with the authorize | ||||
d access | ||||
that an owner of the temperature device can enjoy. In this example, | ||||
the | ||||
<tt>scope</tt> claim issued by the AS informs the RS that the owner o | ||||
f the | ||||
token that can prove the possession of a key is authorized to make a | ||||
GET | ||||
request against the /temperature resource and a POST request on the | ||||
/firmware resource. Note that the syntax and semantics of the <tt>sc | ||||
ope</tt> claim | ||||
are application specific.</t> | ||||
<t>Note: In this example, it is assumed that the client knows what r | ||||
esource | ||||
it wants to access and is therefore able to request specific | ||||
<tt>audience</tt> and <tt>scope</tt> claims for the access token.</t> | ||||
</dd> | ||||
</dl> | ||||
<!-- ************************** --> | <figure anchor="fig_RSOffline"> | |||
<name>Token Request and Response Using Client Credentials</name> | ||||
<!-- ************************** --> | <artwork align="left" name="" type="" alt=""><![CDATA[ | |||
<section anchor="localTokenValidation" title="Local Token Validation"> | ||||
<t>In this scenario, the case where the resource server is offline is consider | ||||
ed, | ||||
i.e., it is not connected to the AS at the time of the access request. | ||||
This access procedure involves steps A, B, C, and F of <xref target="fig:protoco | ||||
lFlow"/>. | ||||
</t> | ||||
<t>Since the resource server must be able to verify the access token locally, | ||||
self-contained access tokens must be used.</t> | ||||
<t>This example shows the interactions between a client, the | ||||
authorization server and a temperature sensor acting as a resource server. | ||||
Message | ||||
exchanges A and B are shown in <xref target="fig:RSOffline"/>.</t> | ||||
<t><list style="hanging"> | ||||
<t>A: The client first generates a public-private key pair used for | ||||
communication security with the RS.</t> | ||||
<t>The client sends a CoAP POST request to the token endpoint at the AS. | ||||
The security | ||||
of this request can be transport or application layer. It is up the | ||||
communication security profile to define. In the example it is | ||||
assumed that both client and AS have performed mutual authentication | ||||
e.g. via DTLS. The request contains the public key of the client and | ||||
the Audience parameter set to "tempSensorInLivingRoom", a value that | ||||
the temperature sensor identifies itself with. The AS evaluates the | ||||
request and authorizes the client to access the resource.</t> | ||||
<t>B: The AS responds with a 2.05 Content response containing the | ||||
Access Information, including the access token. | ||||
The PoP access token contains the public key of the client, and the | ||||
Access Information contains the public key of the RS. For communication | ||||
security this example uses DTLS RawPublicKey between the client and the | ||||
RS. The issued token will have a short validity time, i.e., "exp" close | ||||
to "iat", in order to mitigate attacks using stolen client credentials. | ||||
The token includes the claim such as "scope" with the authorized access | ||||
that an owner of the temperature device can enjoy. In this example, the | ||||
"scope" claim, issued by the AS, informs the RS that the owner of the | ||||
token, that can prove the possession of a key is authorized to make a GET | ||||
request against the /temperature resource and a POST request on the | ||||
/firmware resource. Note that the syntax and semantics of the scope claim | ||||
are application specific.</t> | ||||
<t>Note: In this example it is assumed that the client knows what resource | ||||
it | ||||
wants to access, and is therefore able to request specific | ||||
audience and scope claims for the access token.</t> | ||||
</list></t> | ||||
<t><figure align="center" anchor="fig:RSOffline" | ||||
title="Token Request and Response Using Client Credentials."> | ||||
<artwork align="left"><![CDATA[ | ||||
Authorization | Authorization | |||
Client Server | Client Server | |||
| | | | | | |||
|<=======>| DTLS Connection Establishment | |<=======>| DTLS Connection Establishment | |||
| | and mutual authentication | | | and mutual authentication | |||
| | | | | | |||
A: +-------->| Header: POST (Code=0.02) | A: +-------->| Header: POST (Code=0.02) | |||
| POST | Uri-Path:"token" | | POST | Uri-Path:"token" | |||
| | Content-Format: application/ace+cbor | | | Content-Format: application/ace+cbor | |||
| | Payload: <Request-Payload> | | | Payload: <Request-Payload> | |||
| | | | | | |||
B: |<--------+ Header: 2.05 Content | B: |<--------+ Header: 2.05 Content | |||
| 2.05 | Content-Format: application/ace+cbor | | 2.05 | Content-Format: application/ace+cbor | |||
| | Payload: <Response-Payload> | | | Payload: <Response-Payload> | |||
| | | | | | |||
]]></artwork> | ]]></artwork> | |||
</figure></t> | </figure> | |||
<t>The information contained in the Request-Payload and the | ||||
<t>The information contained in the Request-Payload and the | Response-Payload is shown in <xref target="fig_RSOfflineReq" format="default | |||
Response-Payload is shown in <xref target="fig:RSOfflineReq"/> | "/>. | |||
Note that the parameter "rs_cnf" from | Note that the parameter <tt>rs_cnf</tt> from | |||
<xref target="I-D.ietf-ace-oauth-params"/> is used to inform | <xref target="RFC9201" format="default"/> is used to inform | |||
the client about the resource server's public key. | the client about the resource server's public key. | |||
<figure align="center" anchor="fig:RSOfflineReq" | </t> | |||
title="Request and Response Payload Details."> | <figure anchor="fig_RSOfflineReq"> | |||
<artwork align="left"><![CDATA[ | <name>Request and Response Payload Details</name> | |||
<sourcecode name="" type="cbor-diag"><![CDATA[ | ||||
Request-Payload : | Request-Payload : | |||
{ | { | |||
"audience" : "tempSensorInLivingRoom", | / audience / 5 : "tempSensorInLivingRoom", | |||
"client_id" : "myclient", | / client_id / 24 : "myclient", | |||
"req_cnf" : { | / req_cnf / 4 : { | |||
"COSE_Key" : { | / COSE_Key / 1 : { | |||
"kid" : b64'1Bg8vub9tLe1gHMzV76e8', | / kid / 2 : b64'1Bg8vub9tLe1gHMzV76e', | |||
"kty" : "EC", | / kty / 1 : 2 / EC2 /, | |||
"crv" : "P-256", | / crv / -1 : 1 / P-256 /, | |||
"x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', | / x / -2 : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', | |||
"y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' | / y / -3 : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' | |||
} | } | |||
} | } | |||
} | } | |||
Response-Payload : | Response-Payload : | |||
{ | { | |||
"access_token" : b64'0INDoQEKoQVNKkXfb7xaWqMTf6 ...', | / access_token / 1 : b64'0INDoQEKoQVNKkXfb7xaWqMT'/ .../, | |||
"rs_cnf" : { | / rs_cnf / 41 : { | |||
"COSE_Key" : { | / COSE_Key / 1 : { | |||
"kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', | / kid / 2 : b64'c29tZSBwdWJsaWMga2V5IGlk', | |||
"kty" : "EC", | / kty / 1 : 2 / EC2 /, | |||
"crv" : "P-256", | / crv / -1 : 1 / P-256 /, | |||
"x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', | / x / -2 : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', | |||
"y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' | / y / -3 : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' | |||
} | } | |||
} | } | |||
} | } | |||
]]></artwork> | ]]></sourcecode> | |||
</figure></t> | </figure> | |||
<t>The content of the access token is shown | ||||
<t>The content of the access token is shown | in <xref target="fig_BothcborMappingValueAsymmetricCWT" format="default"/>.< | |||
in <xref target="fig:BothcborMappingValueAsymmetricCWT"/>.</t> | /t> | |||
<figure anchor="fig_BothcborMappingValueAsymmetricCWT"> | ||||
<t><figure align="center" | <name>Access Token Including Public Key of the Client</name> | |||
anchor="fig:BothcborMappingValueAsymmetricCWT" | <sourcecode name="" type="cbor-diag"><![CDATA[ | |||
title="Access Token including Public Key of the client."> | ||||
<artwork align="left"><![CDATA[ | ||||
{ | { | |||
"aud" : "tempSensorInLivingRoom", | / aud / 3 : "tempSensorInLivingRoom", | |||
"iat" : "1563451500", | / iat / 6 : 1563451500, | |||
"exp" : "1563453000", | / exp / 4 : 1563453000, | |||
"scope" : "temperature_g firmware_p", | / scope / 9 : "temperature_g firmware_p", | |||
"cnf" : { | / cnf / 8 : { | |||
"COSE_Key" : { | / COSE_Key / 1 : { | |||
"kid" : b64'1Bg8vub9tLe1gHMzV76e8', | / kid / 2 : b64'1Bg8vub9tLe1gHMzV76e', | |||
"kty" : "EC", | / kty / 1 : 2 / EC2 /, | |||
"crv" : "P-256", | / crv / -1 : 1 / P-256 /, | |||
"x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', | / x / -2 : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', | |||
"y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' | / y / -3 : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' | |||
} | } | |||
} | } | |||
} | } | |||
]]></artwork> | ]]></sourcecode> | |||
</figure></t> | </figure> | |||
<t>Messages C and F are shown in Figures | ||||
<t>Messages C and F are shown in | <xref target="fig_RSOfflinePostAccessTokenAsymmetric" format="counter"/> and | |||
<xref target="fig:RSOfflinePostAccessTokenAsymmetric"/> - | <xref target="fig_RSOfflineDTLSRequestAndResponse" format="counter"/>.</t> | |||
<xref target="fig:RSOfflineDTLSRequestAndResponse"/>. | <dl newline="false" spacing="normal" indent="4"> | |||
<dt>C:</dt> | ||||
<list style="hanging"> | <dd> | |||
<t>C: The client then sends the PoP access token to the authz-info endpoin | The client then sends the PoP access token to the authz-info endpoint | |||
t at | at | |||
the RS. This is a plain CoAP POST request, i.e., no transport or applicat | the RS. This is a plain CoAP POST request, i.e., no transport or | |||
ion-layer security is used between client and RS since the token is integrity pr | application-layer security is used between the client and RS since th | |||
otected | e token is | |||
between the AS and RS. The RS verifies that the PoP access token was crea | integrity protected | |||
ted by a | between the AS and RS. The RS verifies that the PoP access token was | |||
known and trusted AS, that it applies to this RS, and that it is valid. T | created by a | |||
he RS caches | known and trusted AS, which it applies to this RS, and that it is val | |||
the security context together with authorization information about this cl | id. | |||
ient | The RS caches | |||
contained in the PoP access token.</t> | the security context together with authorization information about th | |||
is | ||||
<t><figure align="center" anchor="fig:RSOfflinePostAccessTokenAsymmetric" | client contained in the PoP access token.</dd> | |||
title="Access Token provisioning to RS"> | </dl> | |||
<artwork align="left"><![CDATA[ | <figure anchor="fig_RSOfflinePostAccessTokenAsymmetric"> | |||
<name>Access Token Provisioning to the RS</name> | ||||
<artwork align="left" name="" type="" alt=""><![CDATA[ | ||||
Resource | Resource | |||
Client Server | Client Server | |||
| | | | | | |||
C: +-------->| Header: POST (Code=0.02) | C: +-------->| Header: POST (Code=0.02) | |||
| POST | Uri-Path:"authz-info" | | POST | Uri-Path:"authz-info" | |||
| | Payload: 0INDoQEKoQVN ... | | | Payload: 0INDoQEKoQVN ... | |||
| | | | | | |||
|<--------+ Header: 2.04 Changed | |<--------+ Header: 2.04 Changed | |||
| 2.04 | | | 2.04 | | |||
| | | | | | |||
]]></artwork> | ]]></artwork> | |||
</figure></t> | </figure> | |||
<t>The client and the RS runs the DTLS handshake using the raw | ||||
<t>The client and the RS runs the DTLS handshake using the raw | public keys established in steps B and C.</t> | |||
public keys established in step B and C.</t> | <t>The client sends a CoAP GET request to /temperature on the RS over | |||
DTLS. The RS verifies that the request is authorized based on | ||||
<t>The client sends a CoAP GET request to /temperature on RS over | ||||
DTLS. The RS verifies that the request is authorized, based on | ||||
previously established security context.</t> | previously established security context.</t> | |||
<dl newline="false" spacing="normal" indent="3"> | ||||
<t>F: The RS responds over the same DTLS channel with a CoAP 2.05 Content | <dt>F:</dt> | |||
response, containing a resource representation as payload.</t> | <dd>The RS responds over the same DTLS channel with a CoAP 2.05 Content | |||
</list></t> | response | |||
containing a resource representation as payload.</dd> | ||||
<t><figure align="center" anchor="fig:RSOfflineDTLSRequestAndResponse" | </dl> | |||
title="Resource Request and Response protected by DTLS."> | <figure anchor="fig_RSOfflineDTLSRequestAndResponse"> | |||
<artwork align="left"><![CDATA[ | <name>Resource Request and Response Protected by DTLS</name> | |||
<artwork align="left" name="" type="" alt=""><![CDATA[ | ||||
Resource | Resource | |||
Client Server | Client Server | |||
| | | | | | |||
|<=======>| DTLS Connection Establishment | |<=======>| DTLS Connection Establishment | |||
| | using Raw Public Keys | | | using Raw Public Keys | |||
| | | | | | |||
+-------->| Header: GET (Code=0.01) | +-------->| Header: GET (Code=0.01) | |||
| GET | Uri-Path: "temperature" | | GET | Uri-Path: "temperature" | |||
| | | | | | |||
| | | | | | |||
| | | | | | |||
F: |<--------+ Header: 2.05 Content | F: |<--------+ Header: 2.05 Content | |||
| 2.05 | Payload: <sensor value> | | 2.05 | Payload: <sensor value> | |||
| | | | | | |||
]]></artwork> | ]]></artwork> | |||
</figure></t> | </figure> | |||
</section> | </section> | |||
<!-- ************************** --> | ||||
<section anchor="introspectionAidedTokenValidation" title="Introspection Aided T | ||||
oken Validation"> | ||||
<t>In this deployment scenario it is assumed that a client is not able to | <section anchor="introspectionAidedTokenValidation" numbered="true" toc="default | |||
"> | ||||
<name>Introspection Aided Token Validation</name> | ||||
<t>In this deployment scenario, it is assumed that a client is not able | ||||
to | ||||
access the AS at the time of the access request, whereas the RS is assumed | access the AS at the time of the access request, whereas the RS is assumed | |||
to be connected to the back-end infrastructure. Thus the RS can make use of | to be connected to the back-end infrastructure. Thus, the RS can make use of | |||
token introspection. This access procedure involves steps A-F of | token introspection. This access procedure involves steps (A)-(F) of | |||
<xref target="fig:protocolFlow"/>, but assumes steps A and B have been | <xref target="fig_protocolFlow" format="default"/> but assumes steps (A) and ( | |||
carried out during a phase when the client had connectivity to AS. | B) have been | |||
</t> | carried out during a phase when the client had connectivity to the AS. | |||
</t> | ||||
<t>Since the client is assumed to be offline, at least for a certain period of | <t>Since the client is assumed to be offline, at least for a certain per | |||
time, a pre-provisioned access token has to be long-lived. Since the client | iod of | |||
is constrained, the token will not be self contained (i.e. not a CWT) but | time, a preprovisioned access token has to be long lived. Since the client | |||
is constrained, the token will not be self-contained (i.e., not a CWT) but | ||||
instead just a reference. The resource server uses its connectivity to | instead just a reference. The resource server uses its connectivity to | |||
learn about the claims associated to the access token by using introspection, | learn about the claims associated to the access token by using introspection, | |||
which is shown in the example below.</t> | which is shown in the example below.</t> | |||
<t>In the example, interactions between an offline client | ||||
<t>In the example interactions between an offline client | ||||
(key fob), an RS (online lock), and an AS is shown. It is | (key fob), an RS (online lock), and an AS is shown. It is | |||
assumed that there is a provisioning step where the client has access to the | assumed that there is a provisioning step where the client has access to the | |||
AS. This corresponds to message exchanges A and B which are shown in | AS. This corresponds to message exchanges A and B, which are shown in | |||
<xref target="fig:cOffline"/>. | <xref target="fig_cOffline" format="default"/>. | |||
</t> | </t> | |||
<t>Authorization consent from the resource owner can be pre-configured, | <t>Authorization consent from the resource owner can be preconfigured, | |||
but it can also be provided via an interactive flow with the resource | but it can also be provided via an interactive flow with the resource | |||
owner. An example of this for the key fob case could be that the | owner. An example of this for the key fob case could be that the | |||
resource owner has a connected car, he buys a generic key that he | resource owner has a connected car and buys a generic key to use with the | |||
wants to use with the car. To authorize the key fob he connects it | car. To authorize the key fob, the owner connects it to a computer that | |||
to his computer that then provides the UI for the device. After | then provides the UI for the device. After that, OAuth 2.0 implicit flow | |||
that OAuth 2.0 implicit flow can used to authorize the key for | can be used to authorize the key for the car at the car manufacturer's | |||
his car at the car manufacturers AS.</t> | AS.</t> | |||
<t>Note: In this example, the client does not know the exact door it | ||||
<t>Note: In this example the client does not know the exact door it | will be used to access since the token request is not sent at the | |||
will be used to access since the token request is not send at the | time of access. So the <tt>scope</tt> and <tt>audience</tt> parameters are s | |||
time of access. So the scope and audience parameters are set quite | et quite | |||
wide to start with, while tailored values narrowing down the claims to | wide to start with, while tailored values narrowing down the claims to | |||
the specific RS being accessed can be provided to that RS during | the specific RS being accessed can be provided to that RS during | |||
an introspection step.</t> | an introspection step.</t> | |||
<dl newline="false" spacing="normal" indent="4"> | ||||
<t> | <dt>A:</dt> | |||
<list style="hanging"> | <dd>The client sends a CoAP POST request to the token endpoint at the | |||
<t>A: The client sends a CoAP POST request to the token endpoint at | AS. The request contains the <tt>audience</tt> parameter set to "PACS13 | |||
AS. The request contains the Audience parameter set to "PACS1337" | 37" | |||
(PACS, Physical Access System), a value the that identifies the | (Physical Access System (PACS)), a value that identifies the | |||
physical access control system to which the individual doors are | physical access control system to which the individual doors are | |||
connected. The AS generates an access token as an opaque string, which | connected. The AS generates an access token as an opaque string, which | |||
it can match to the specific client and the targeted audience. It | it can match to the specific client and the targeted audience. It | |||
furthermore generates a symmetric proof-of-possession key. The | furthermore generates a symmetric proof-of-possession key. The | |||
communication security and authentication between client and AS | communication security and authentication between the client and AS | |||
is assumed to have been provided at transport layer (e.g. via DTLS) | is assumed to have been provided at the transport layer (e.g., via DTLS) | |||
using a pre-shared security context (psk, rpk or certificate).</t> | using a pre-shared security context (pre-shared key (PSK), RPK, or | |||
certificate).</dd> | ||||
<t>B: The AS responds with a CoAP 2.05 Content response, containing as | <dt>B:</dt> | |||
<dd>The AS responds with a CoAP 2.05 Content response, containing as | ||||
payload the Access Information, including the access token and the | payload the Access Information, including the access token and the | |||
symmetric proof-of-possession key. Communication security between C | symmetric proof-of-possession key. Communication security between the C | |||
and RS will be DTLS and PreSharedKey. The PoP key is used as the | and RS will be DTLS and PreSharedKey. The PoP key is used as the | |||
PreSharedKey. | PreSharedKey. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t>Note: In this example, we are using a symmetric key for a multi-RS | |||
audience, which is not recommended normally (see <xref target="audience" | ||||
<t>Note: In this example we are using a symmetric key for a multi-RS | format="default"/>). | |||
audience, which is not recommended normally (see <xref target="audience"/>). | However, in this case, the risk is deemed to be acceptable, since | |||
However in this case the risk is deemed to be acceptable, since | all the doors are part of the same physical access control system; | |||
all the doors are part of the same physical access control system, | therefore, the risk of a malicious RS impersonating the client towards | |||
and therefore the risk of a malicious RS impersonating the client towards | another RS is low.</t> | |||
another RS is low.</t> | <figure anchor="fig_cOffline"> | |||
<name>Token Request and Response Using Client Credentials</name> | ||||
<t><figure align="center" anchor="fig:cOffline" | <artwork align="left" name="" type="" alt=""><![CDATA[ | |||
title="Token Request and Response using Client Credentials."> | ||||
<artwork align="left"><![CDATA[ | ||||
Authorization | Authorization | |||
Client Server | Client Server | |||
| | | | | | |||
|<=======>| DTLS Connection Establishment | |<=======>| DTLS Connection Establishment | |||
| | and mutual authentication | | | and mutual authentication | |||
| | | | | | |||
A: +-------->| Header: POST (Code=0.02) | A: +-------->| Header: POST (Code=0.02) | |||
| POST | Uri-Path:"token" | | POST | Uri-Path:"token" | |||
| | Content-Format: application/ace+cbor | | | Content-Format: application/ace+cbor | |||
| | Payload: <Request-Payload> | | | Payload: <Request-Payload> | |||
| | | | | | |||
B: |<--------+ Header: 2.05 Content | B: |<--------+ Header: 2.05 Content | |||
| | Content-Format: application/ace+cbor | | | Content-Format: application/ace+cbor | |||
| 2.05 | Payload: <Response-Payload> | | 2.05 | Payload: <Response-Payload> | |||
| | | | | | |||
]]></artwork> | ]]></artwork> | |||
</figure></t> | </figure> | |||
<t>The information contained in the Request-Payload and the | ||||
<t>The information contained in the Request-Payload and the | Response-Payload is shown in <xref target="fig_cOfflineReq" format="defau | |||
Response-Payload is shown in <xref target="fig:cOfflineReq"/>. | lt"/>. | |||
</t> | ||||
<figure align="center" anchor="fig:cOfflineReq" | <figure anchor="fig_cOfflineReq"> | |||
title="Request and Response Payload for C offline"> | <name>Request and Response Payload for the C Offline</name> | |||
<artwork align="left"><![CDATA[ | <sourcecode name="" type="cbor-diag"><![CDATA[ | |||
Request-Payload: | Request-Payload: | |||
{ | { | |||
"client_id" : "keyfob", | / client_id / 24 : "keyfob", | |||
"audience" : "PACS1337" | / audience / 5 : "PACS1337" | |||
} | } | |||
Response-Payload: | Response-Payload: | |||
{ | { | |||
"access_token" : b64'VGVzdCB0b2tlbg==', | / access_token / 1 : b64'VGVzdCB0b2tlbg', | |||
"cnf" : { | / cnf / 8 : { | |||
"COSE_Key" : { | / COSE_Key / 1 : { | |||
"kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', | / kid / 2 : b64'c29tZSBwdWJsaWMga2V5IGlk', | |||
"kty" : "oct", | / kty / 1 : 4 / Symmetric /, | |||
"alg" : "HS256", | / k / -1 : b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' | |||
"k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' | ||||
} | } | |||
} | } | |||
} | } | |||
]]></artwork> | ]]></sourcecode> | |||
</figure></t> | </figure> | |||
<t>In this case, the access token is just an opaque byte string referenc | ||||
<t>The access token in this case is just an opaque byte string referencing | ing | |||
the authorization information at the AS.</t> | the authorization information at the AS.</t> | |||
<dl newline="false" spacing="normal" indent="4"> | ||||
<t><list style="hanging"> | <dt>C:</dt> | |||
<t>C: Next, the client POSTs the access token to the authz-info | <dd>Next, the client POSTs the access token to the authz-info | |||
endpoint in the RS. This is a plain CoAP request, i.e., no | endpoint in the RS. This is a plain CoAP request, i.e., no | |||
DTLS between client and RS. Since the token is an opaque string, | DTLS between the client and RS. Since the token is an opaque string, | |||
the RS cannot verify it on its own, and thus defers to respond the | the RS cannot verify it on its own, and thus defers to respond to the | |||
client with a status code until after step E.</t> | client with a status code until after step E.</dd> | |||
<dt>D:</dt> | ||||
<t>D: The RS sends the token to the introspection | <dd>The RS sends the token to the introspection | |||
endpoint on the AS using a CoAP POST request. In this example RS and | endpoint on the AS using a CoAP POST request. In this example, the RS | |||
AS are assumed to have performed mutual authentication using a pre | and | |||
shared security context (psk, rpk or certificate) with the RS acting as | AS are assumed to have performed mutual authentication using a pre-shar | |||
DTLS client. | ed security | |||
</t> | context (PSK, RPK, or certificate) with the RS acting as the DTLS clien | |||
t.</dd> | ||||
<t>E: The AS provides the introspection response (2.05 Content) | <dt>E:</dt> | |||
<dd> | ||||
<t>The AS provides the introspection response (2.05 Content) | ||||
containing parameters about the token. This includes the confirmation | containing parameters about the token. This includes the confirmation | |||
key (cnf) parameter that allows the RS to verify the client's proof of | key (<tt>cnf</tt>) parameter that allows the RS to verify the client's pr oof of | |||
possession in step F. Note that our example in <xref | possession in step F. Note that our example in <xref | |||
target="fig:cOfflineIntroReq"/> assumes a pre-established key (e.g. one | target="fig_cOfflineIntroReq" format="default"/> assumes a preestablished | |||
key | ||||
(e.g., one | ||||
used by the client and the RS for a previous token) that is now only | used by the client and the RS for a previous token) that is now only | |||
referenced by its key-identifier 'kid'. | referenced by its key identifier <tt>kid</tt>.</t> | |||
</t> | <t>After receiving message E, the RS responds to the client's POST in | |||
<t>After receiving message E, the RS responds to the client's POST in | ||||
step C with the CoAP response code 2.01 (Created).</t> | step C with the CoAP response code 2.01 (Created).</t> | |||
</dd> | ||||
<t><figure align="center" anchor="fig:cOfflineIntrospection" | </dl> | |||
title="Token Introspection for C offline"> | <figure anchor="fig_cOfflineIntrospection"> | |||
<artwork align="left"><![CDATA[ | <name>Token Introspection for the C Offline</name> | |||
<artwork align="left" name="" type="" alt=""><![CDATA[ | ||||
Resource | Resource | |||
Client Server | Client Server | |||
| | | | | | |||
C: +-------->| Header: POST (T=CON, Code=0.02) | C: +-------->| Header: POST (T=CON, Code=0.02) | |||
| POST | Uri-Path:"authz-info" | | POST | Uri-Path:"authz-info" | |||
| | Payload: b64'VGVzdCB0b2tlbg==' | | | Payload: b64'VGVzdCB0b2tlbg' | |||
| | | | | | |||
| | Authorization | | | Authorization | |||
| | Server | | | Server | |||
| | | | | | | | |||
| D: +--------->| Header: POST (Code=0.02) | | D: +--------->| Header: POST (Code=0.02) | |||
| | POST | Uri-Path: "introspect" | | | POST | Uri-Path: "introspect" | |||
| | | Content-Format: "application/ace+cbor" | | | | Content-Format: application/ace+cbor | |||
| | | Payload: <Request-Payload> | | | | Payload: <Request-Payload> | |||
| | | | | | | | |||
| E: |<---------+ Header: 2.05 Content | | E: |<---------+ Header: 2.05 Content | |||
| | 2.05 | Content-Format: "application/ace+cbor" | | | 2.05 | Content-Format: application/ace+cbor | |||
| | | Payload: <Response-Payload> | | | | Payload: <Response-Payload> | |||
| | | | | | | | |||
| | | | | | |||
|<--------+ Header: 2.01 Created | |<--------+ Header: 2.01 Created | |||
| 2.01 | | | 2.01 | | |||
| | | | | | |||
]]></artwork> | ]]></artwork> | |||
</figure></t> | </figure> | |||
<t>The information contained in the Request-Payload and the | ||||
<t>The information contained in the Request-Payload and the | Response-Payload is shown in <xref target="fig_cOfflineIntroReq" format= | |||
Response-Payload is shown in <xref target="fig:cOfflineIntroReq"/>. | "default"/>. | |||
<figure align="center" anchor="fig:cOfflineIntroReq" | </t> | |||
title="Request and Response Payload for Introspection"> | <figure anchor="fig_cOfflineIntroReq"> | |||
<artwork align="left"><![CDATA[ | <name>Request and Response Payload for Introspection</name> | |||
<sourcecode name="" type="cbor-diag"><![CDATA[ | ||||
Request-Payload: | Request-Payload: | |||
{ | { | |||
"token" : b64'VGVzdCB0b2tlbg==', | / token / 11 : b64'VGVzdCB0b2tlbg', | |||
"client_id" : "FrontDoor", | / client_id / 24 : "FrontDoor" | |||
} | } | |||
Response-Payload: | Response-Payload: | |||
{ | { | |||
"active" : true, | / active / 10 : true, | |||
"aud" : "lockOfDoor4711", | / aud / 3 : "lockOfDoor4711", | |||
"scope" : "open, close", | / scope / 9 : "open close", | |||
"iat" : 1563454000, | / iat / 6 : 1563454000, | |||
"cnf" : { | / cnf / 8 : { | |||
"kid" : b64'c29tZSBwdWJsaWMga2V5IGlk' | / kid / 3 : b64'c29tZSBwdWJsaWMga2V5IGlk' | |||
} | } | |||
} | } | |||
]]></artwork> | ]]></sourcecode> | |||
</figure></t> | </figure> | |||
</list> | <t>The client uses the symmetric PoP key to establish a DTLS | |||
</t> | ||||
<t> | ||||
<list style="hanging"> | ||||
<t> | ||||
The client uses the symmetric PoP key to establish a DTLS | ||||
PreSharedKey secure connection to the RS. The CoAP request PUT is | PreSharedKey secure connection to the RS. The CoAP request PUT is | |||
sent to the uri-path /state on the RS, changing the state of the doo | sent to the uri-path /state on the RS, changing the state of the doo | |||
r to locked. | r to | |||
</t> | locked.</t> | |||
<t> | <dl newline="false" spacing="normal" indent="4"> | |||
F: The RS responds with a appropriate over the secure DTLS channel. | <dt>F:</dt> | |||
</t> | <dd>The RS responds with an appropriate response over the secure DTLS | |||
</list> | channel.</dd> | |||
</t> | </dl> | |||
<t><figure align="center" anchor="fig:cOfflineDTLSRequestAndResponse" | <figure anchor="fig_cOfflineDTLSRequestAndResponse"> | |||
title="Resource request and response protected by OSCORE"> | <name>Resource Request and Response Protected by OSCORE</name> | |||
<artwork align="left"><![CDATA[ | <artwork align="left" name="" type="" alt=""><![CDATA[ | |||
Resource | Resource | |||
Client Server | Client Server | |||
| | | | | | |||
|<=======>| DTLS Connection Establishment | |<=======>| DTLS Connection Establishment | |||
| | using Pre Shared Key | | | using Pre Shared Key | |||
| | | | | | |||
+-------->| Header: PUT (Code=0.03) | +-------->| Header: PUT (Code=0.03) | |||
| PUT | Uri-Path: "state" | | PUT | Uri-Path: "state" | |||
| | Payload: <new state for the lock> | | | Payload: <new state for the lock> | |||
| | | | | | |||
F: |<--------+ Header: 2.04 Changed | F: |<--------+ Header: 2.04 Changed | |||
| 2.04 | Payload: <new state for the lock> | | 2.04 | Payload: <new state for the lock> | |||
| | | | | | |||
]]></artwork> | ]]></artwork> | |||
</figure></t> | </figure> | |||
</section> | ||||
</section> | ||||
<section anchor="Acknowledgments" numbered="false" toc="default"> | ||||
<name>Acknowledgments</name> | ||||
<t>This document is a product of the ACE Working Group of the IETF.</t> | ||||
<t>Thanks to <contact fullname="Eve Maler"/> for her contributions to the | ||||
use of | ||||
OAuth 2.0 and Unlicensed Mobile Access (UMA) in IoT scenarios, | ||||
<contact fullname="Robert Taylor"/> for his | ||||
discussion input, and <contact fullname="Mališa Vučinić"/> for his input o | ||||
n the | ||||
predecessors of this proposal.</t> | ||||
<t>Thanks to the authors of "<xref target="I-D.ietf-oauth-pop-key-distribu | ||||
tion" format="default"/><xref target="I-D.ietf-oauth-pop-key-distribution" forma | ||||
t="title"/>" <xref target="I-D.ietf-oauth-pop-key-distribution" format="default" | ||||
/>, from where | ||||
parts of the security considerations where copied.</t> | ||||
<t>Thanks to <contact fullname="Stefanie Gerdes"/>, <contact fullname="Ola | ||||
f | ||||
Bergmann"/>, and <contact fullname="Carsten | ||||
Bormann"/> for contributing their work on AS discovery from | ||||
"<xref target="I-D.gerdes-ace-dcaf-authorize" format="title"/>" <xref targ | ||||
et="I-D.gerdes-ace-dcaf-authorize" format="default"/> (see <xref target="asDisco | ||||
very" | ||||
format="default"/>) and the considerations on multiple access tokens.</t> | ||||
<t>Thanks to <contact fullname="Jim Schaad"/> and <contact fullname="Mike | ||||
Jones"/> for their comprehensive reviews.</t> | ||||
<t>Thanks to <contact fullname="Benjamin Kaduk"/> for his input on various | ||||
questions related to this work.</t> | ||||
<t>Thanks to <contact fullname="Cigdem Sengul"/> for some very useful revi | ||||
ew | ||||
comments.</t> | ||||
<t>Thanks to <contact fullname="Carsten Bormann"/> for contributing the te | ||||
xt for | ||||
the CoRE Resource Type registry.</t> | ||||
<t>Thanks to <contact fullname="Roman Danyliw"/> for suggesting <xref | ||||
target="app_diffOAuth" format="default"/> | ||||
(including its contents).</t> | ||||
<t><contact fullname="Ludwig Seitz"/> and <contact fullname="Göran Selande | ||||
r"/> | ||||
worked on this document as part of the CelticPlus project CyberWI, with fu | ||||
nding | ||||
from Vinnova. <contact fullname="Ludwig Seitz"/> | ||||
has also received further funding for this work by Vinnova in the context | ||||
of | ||||
the CelticNext project CRITISEC.</t> | ||||
</section> | </section> | |||
</section> | ||||
</back> | </back> | |||
</rfc> | </rfc> | |||
End of changes. 446 change blocks. | ||||
3350 lines changed or deleted | 4007 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. |