draft-ietf-ace-oauth-authz-12.txt   draft-ietf-ace-oauth-authz-13.txt 
ACE Working Group L. Seitz ACE Working Group L. Seitz
Internet-Draft RISE SICS Internet-Draft RISE SICS
Intended status: Standards Track G. Selander Intended status: Standards Track G. Selander
Expires: November 22, 2018 Ericsson Expires: January 3, 2019 Ericsson
E. Wahlstroem E. Wahlstroem
S. Erdtman S. Erdtman
Spotify AB Spotify AB
H. Tschofenig H. Tschofenig
ARM Ltd. Arm Ltd.
May 21, 2018 July 2, 2018
Authentication and Authorization for Constrained Environments (ACE) Authentication and Authorization for Constrained Environments (ACE)
using the OAuth 2.0 Framework (ACE-OAuth) using the OAuth 2.0 Framework (ACE-OAuth)
draft-ietf-ace-oauth-authz-12 draft-ietf-ace-oauth-authz-13
Abstract Abstract
This specification defines a framework for authentication and This specification defines a framework for authentication and
authorization in Internet of Things (IoT) environments called ACE- authorization in Internet of Things (IoT) environments called ACE-
OAuth. The framework is based on a set of building blocks including OAuth. The framework is based on a set of building blocks including
OAuth 2.0 and CoAP, thus making a well-known and widely used OAuth 2.0 and CoAP, thus making a well-known and widely used
authorization solution suitable for IoT devices. Existing authorization solution suitable for IoT devices. Existing
specifications are used where possible, but where the constraints of specifications are used where possible, but where the constraints of
IoT devices require it, extensions are added and profiles are IoT devices require it, extensions are added and profiles are
skipping to change at page 1, line 45 skipping to change at page 1, line 45
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 22, 2018. This Internet-Draft will expire on January 3, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 33 skipping to change at page 2, line 33
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10
5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.1. Discovering Authorization Servers . . . . . . . . . . . . 15 5.1. Discovering Authorization Servers . . . . . . . . . . . . 15
5.1.1. Unauthorized Resource Request Message . . . . . . . . 15 5.1.1. Unauthorized Resource Request Message . . . . . . . . 15
5.1.2. AS Information . . . . . . . . . . . . . . . . . . . 16 5.1.2. AS Information . . . . . . . . . . . . . . . . . . . 16
5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17
5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 18 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 17
5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18
5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18
5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 18 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 18
5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 19 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 19
5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 22 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 22
5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 24 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 24
5.6.4. Request and Response Parameters . . . . . . . . . . . 25 5.6.4. Request and Response Parameters . . . . . . . . . . . 25
5.6.4.1. Audience . . . . . . . . . . . . . . . . . . . . 25 5.6.4.1. Audience . . . . . . . . . . . . . . . . . . . . 25
5.6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 25 5.6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 25
5.6.4.3. Token Type . . . . . . . . . . . . . . . . . . . 26 5.6.4.3. Token Type . . . . . . . . . . . . . . . . . . . 26
5.6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 26 5.6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 26
5.6.4.5. Confirmation . . . . . . . . . . . . . . . . . . 27 5.6.4.5. Confirmation . . . . . . . . . . . . . . . . . . 27
5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 27 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 27
5.7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 28 5.7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 28
5.7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 29 5.7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 29
5.7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 29 5.7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 30
5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 30 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 31
5.7.4. Mapping Introspection parameters to CBOR . . . . . . 31 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 31
5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 32 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 32
5.8.1. The 'Authorization Information' Endpoint . . . . . . 33 5.8.1. The 'Authorization Information' Endpoint . . . . . . 33
5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 34 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 34
5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 34 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 34
6. Security Considerations . . . . . . . . . . . . . . . . . . . 35 6. Security Considerations . . . . . . . . . . . . . . . . . . . 35
6.1. Unprotected AS Information . . . . . . . . . . . . . . . 36 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 36
6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 37 6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 37
6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 37 6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 37
6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 37 6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 37
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
8.1. Authorization Server Information . . . . . . . . . . . . 38 8.1. Authorization Server Information . . . . . . . . . . . . 38
8.2. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 39 8.2. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 39
8.3. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 39 8.3. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 39
8.4. OAuth Access Token Types . . . . . . . . . . . . . . . . 40 8.4. OAuth Access Token Types . . . . . . . . . . . . . . . . 40
8.5. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 40 8.5. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 40
8.5.1. Initial Registry Contents . . . . . . . . . . . . . . 40 8.5.1. Initial Registry Contents . . . . . . . . . . . . . . 41
8.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 41 8.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 41
8.7. OAuth Parameter Registration . . . . . . . . . . . . . . 41 8.7. OAuth Parameter Registration . . . . . . . . . . . . . . 41
8.8. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 42 8.8. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 42
8.9. OAuth Introspection Response Parameter Registration . . . 42 8.9. OAuth Introspection Response Parameter Registration . . . 43
8.10. Introspection Endpoint CBOR Mappings Registry . . . . . . 43 8.10. Introspection Endpoint CBOR Mappings Registry . . . . . . 43
8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 43 8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 44
8.12. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 44 8.12. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 44
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 45
10.1. Normative References . . . . . . . . . . . . . . . . . . 44 10.1. Normative References . . . . . . . . . . . . . . . . . . 45
10.2. Informative References . . . . . . . . . . . . . . . . . 46 10.2. Informative References . . . . . . . . . . . . . . . . . 46
Appendix A. Design Justification . . . . . . . . . . . . . . . . 48 Appendix A. Design Justification . . . . . . . . . . . . . . . . 49
Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 52 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 52
Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 54 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 54
Appendix D. Assumptions on AS knowledge about C and RS . . . . . 55 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 55
Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 55 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 55
E.1. Local Token Validation . . . . . . . . . . . . . . . . . 55 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 56
E.2. Introspection Aided Token Validation . . . . . . . . . . 59 E.2. Introspection Aided Token Validation . . . . . . . . . . 60
Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 63 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 64
F.1. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 63 F.1. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 64
F.2. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 63 F.2. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 64
F.3. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 64 F.3. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 65
F.4. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 64 F.4. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 65
F.5. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 64 F.5. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 65
F.6. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 65 F.6. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 65
F.7. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 65 F.7. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 66
F.8. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 65 F.8. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 66
F.9. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 65 F.9. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 66
F.10. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 65 F.10. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 66
F.11. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 66 F.11. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 66
F.12. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 66 F.12. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 67
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 67 F.13. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 67
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 68
1. Introduction 1. Introduction
Authorization is the process for granting approval to an entity to Authorization is the process for granting approval to an entity to
access a resource [RFC4949]. The authorization task itself can best access a resource [RFC4949]. The authorization task itself can best
be described as granting access to a requesting client, for a be described as granting access to a requesting client, for a
resource hosted on a device, the resource server (RS). This exchange resource hosted on a device, the resource server (RS). This exchange
is mediated by one or multiple authorization servers (AS). Managing is mediated by one or multiple authorization servers (AS). Managing
authorization for a large number of devices and users can be a authorization for a large number of devices and users can be a
complex task. complex task.
skipping to change at page 5, line 43 skipping to change at page 5, line 43
authorization server (CAS) functionality is not stand-alone but authorization server (CAS) functionality is not stand-alone but
subsumed by either the authorization server or the client (see subsumed by either the authorization server or the client (see
Section 2.2 in [I-D.ietf-ace-actors]). Section 2.2 in [I-D.ietf-ace-actors]).
The specifications in this document is called the "framework" or "ACE The specifications in this document is called the "framework" or "ACE
framework". When referring to "profiles of this framework" it refers framework". When referring to "profiles of this framework" it refers
to additional specifications that define the use of this to additional specifications that define the use of this
specification with concrete transport, and communication security specification with concrete transport, and communication security
protocols (e.g., CoAP over DTLS). protocols (e.g., CoAP over DTLS).
We use the term "RS Information" for parameters describing We use the term "Access Information" for parameters other than the
characteristics of the RS (e.g. public key) that the AS provides to access token provided to the client by the AS to enable it to access
the client. the RS (e.g. public key of the RS, profile supported by RS).
3. Overview 3. Overview
This specification defines the ACE framework for authorization in the This specification defines the ACE framework for authorization in the
Internet of Things environment. It consists of a set of building Internet of Things environment. It consists of a set of building
blocks. blocks.
The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys
widespread deployment. Many IoT devices can support OAuth 2.0 widespread deployment. Many IoT devices can support OAuth 2.0
without any additional extensions, but for certain constrained without any additional extensions, but for certain constrained
skipping to change at page 8, line 29 skipping to change at page 8, line 29
public key is sent to the AS (if it does not already have public key is sent to the AS (if it does not already have
knowledge of the client's public key). Information about the knowledge of the client's public key). Information about the
public key, which is the PoP key in this case, is either stored public key, which is the PoP key in this case, is either stored
to be returned on introspection calls or included inside the to be returned on introspection calls or included inside the
access token and sent back to the requesting client. The RS access token and sent back to the requesting client. The RS
can identify the client's public key from the information in can identify the client's public key from the information in
the token, which allows the client to use the corresponding the token, which allows the client to use the corresponding
private key for the proof of possession. private key for the proof of possession.
The access token is either a simple reference, or a structured The access token is either a simple reference, or a structured
information object (e.g., CWT [RFC8392]), protected by a information object (e.g., CWT [RFC8392]) protected by a
cryptographic wrapper (e.g., COSE [RFC8152]). The choice of PoP cryptographic wrapper (e.g., COSE [RFC8152]). The choice of PoP
key does not necessarily imply a specific credential type for the key does not necessarily imply a specific credential type for the
integrity protection of the token. integrity protection of the token.
Scopes and Permissions: Scopes and Permissions:
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 scope parameter) in the access token
request. In turn, the AS may use the scope response parameter to request. In turn, the AS may use the scope 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
skipping to change at page 10, line 14 skipping to change at page 10, line 14
different transport in a uniform way, is to provide security at the different transport in a uniform way, is to provide security at the
application layer using an object-based security mechanism such as application layer using an object-based security mechanism such as
COSE [RFC8152]. COSE [RFC8152].
One application of COSE is OSCORE [I-D.ietf-core-object-security], One application of COSE is OSCORE [I-D.ietf-core-object-security],
which provides end-to-end confidentiality, integrity and replay which provides end-to-end confidentiality, integrity and replay
protection, and a secure binding between CoAP request and response protection, and a secure binding between CoAP request and response
messages. In OSCORE, the CoAP messages are wrapped in COSE objects messages. In OSCORE, the CoAP messages are wrapped in COSE objects
and sent using CoAP. and sent using CoAP.
This framework RECOMMENDS the use of CoAP as replacement for HTTP. This framework RECOMMENDS the use of CoAP as replacement for HTTP for
use in constrained environments.
4. Protocol Interactions 4. Protocol Interactions
The ACE framework is based on the OAuth 2.0 protocol interactions The ACE framework is based on the OAuth 2.0 protocol interactions
using the token endpoint and optionally the introspection endpoint. using the token endpoint and optionally the introspection endpoint.
A client obtains an access token from an AS using the token endpoint A client obtains an access token from an AS using the token endpoint
and subsequently presents the access token to a RS to gain access to and subsequently presents the access token to a RS to gain access to
a protected resource. In most deployments the RS can process the a protected resource. In most deployments the RS can process the
access token locally, however in some cases the RS may present it to access token locally, however in some cases the RS may present it to
the AS via the introspection endpoint to get fresh information. the AS via the introspection endpoint to get fresh information.
skipping to change at page 12, line 9 skipping to change at page 12, line 9
In Bluetooth Low Energy, for example, advertisements are broadcasted In Bluetooth Low Energy, for example, advertisements are broadcasted
by a peripheral, including information about the primary services. by a peripheral, including information about the primary services.
In CoAP, as a second example, a client can make a request to "/.well- In CoAP, as a second example, a client can make a request to "/.well-
known/core" to obtain information about available resources, which known/core" to obtain information about available resources, which
are returned in a standardized format as described in [RFC6690]. are returned in a standardized format as described in [RFC6690].
+--------+ +---------------+ +--------+ +---------------+
| |---(A)-- Token Request ------->| | | |---(A)-- Token Request ------->| |
| | | Authorization | | | | Authorization |
| |<--(B)-- Access Token ---------| Server | | |<--(B)-- Access Token ---------| Server |
| | + RS Information | | | | + Access Information | |
| | +---------------+ | | +---------------+
| | ^ | | | ^ |
| | Introspection Request (D)| | | | Introspection Request (D)| |
| Client | (optional) | | | Client | (optional) | |
| | Response | |(E) | | Response | |(E)
| | (optional) | v | | (optional) | v
| | +--------------+ | | +--------------+
| |---(C)-- Token + Request ----->| | | |---(C)-- Token + Request ----->| |
| | | Resource | | | | Resource |
| |<--(F)-- Protected Resource ---| Server | | |<--(F)-- Protected Resource ---| Server |
skipping to change at page 12, line 37 skipping to change at page 12, line 37
the AS. This framework assumes the use of PoP access tokens (see the AS. This framework assumes the use of PoP access tokens (see
Section 3.1 for a short description) wherein the AS binds a key to Section 3.1 for a short description) wherein the AS binds a key to
an access token. The client may include permissions it seeks to an access token. The client may include permissions it seeks to
obtain, and information about the credentials it wants to use obtain, and information about the credentials it wants to use
(e.g., symmetric/asymmetric cryptography or a reference to a (e.g., symmetric/asymmetric cryptography or a reference to a
specific credential). specific credential).
Access Token Response (B): Access Token Response (B):
If the AS successfully processes the request from the client, it If the AS successfully processes the request from the client, it
returns an access token. It can also return additional returns an access token. It can also return additional
parameters, referred to as "RS Information". In addition to the parameters, referred to as "Access Information". In addition to
response parameters defined by OAuth 2.0 and the PoP access token the response parameters defined by OAuth 2.0 and the PoP access
extension, this framework defines parameters that can be used to token extension, this framework defines parameters that can be
inform the client about capabilities of the RS. More information used to inform the client about capabilities of the RS. More
about these parameters can be found in Section 5.6.4. information about these parameters can be found in Section 5.6.4.
Resource Request (C): Resource Request (C):
The client interacts with the RS to request access to the The client interacts with the RS to request access to the
protected resource and provides the access token. The protocol to protected resource and provides the access token. The protocol to
use between the client and the RS is not restricted to CoAP. use between the client and the RS is not restricted to CoAP.
HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also
viable candidates. viable candidates.
Depending on the device limitations and the selected protocol, Depending on the device limitations and the selected protocol,
this exchange may be split up into two parts: this exchange may be split up into two parts:
(1) the client sends the access token containing, or (1) the client sends the access token containing, or
referencing, the authorization information to the RS, that may referencing, the authorization information to the RS, that may
be used for subsequent resource requests by the client, and be used for subsequent resource requests by the client, and
(2) the client makes the resource access request, using the (2) the client makes the resource access request, using the
communication security protocol and other RS Information communication security protocol and other Access Information
obtained from the AS. obtained from the AS.
The Client and the RS mutually authenticate using the security The Client and the RS mutually authenticate using the security
protocol specified in the profile (see step B) and the keys protocol specified in the profile (see step B) and the keys
obtained in the access token or the RS Information. The RS obtained in the access token or the Access Information. The RS
verifies that the token is integrity protected by the AS and verifies that the token is integrity protected by the AS and
compares the claims contained in the access token with the compares the claims contained in the access token with the
resource request. If the RS is online, validation can be handed resource request. If the RS is online, validation can be handed
over to the AS using token introspection (see messages D and E) over to the AS using token introspection (see messages D and E)
over HTTP or CoAP. over HTTP or CoAP.
Token Introspection Request (D): Token Introspection Request (D):
A resource server may be configured to introspect the access token A resource server may be configured to introspect the access token
by including it in a request to the introspection endpoint at that by including it in a request to the introspection endpoint at that
AS. Token introspection over CoAP is defined in Section 5.7 and AS. Token introspection over CoAP is defined in Section 5.7 and
skipping to change at page 14, line 25 skipping to change at page 14, line 25
credentials need to be provided to the parties before or during credentials need to be provided to the parties before or during
the authentication protocol is executed, and may be re-used for the authentication protocol is executed, and may be re-used for
subsequent token requests. subsequent token requests.
Proof-of-Possession Proof-of-Possession
The ACE framework, by default, implements proof-of-possession for The ACE framework, by default, implements proof-of-possession for
access tokens, i.e., that the token holder can prove being a 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 holder of the key bound to the token. The binding is provided by
the "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession] indicating the "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession] indicating
what key is used for proof-of-possession. If a client needs to what key is used for proof-of-possession. If a client needs to
submit a new access token e.g., to obtain additional access submit a new access token, e.g., to obtain additional access
rights, they can request that the AS binds this token to the same rights, they can request that the AS binds this token to the same
key as the previous one. key as the previous one.
ACE Profiles ACE Profiles
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 client and RS are defined in an ACE
profile. In ACE framework the AS is expected to manage the profile. In ACE framework the AS is expected to manage the
matching of compatible profile choices between a client and an RS. matching of compatible profile choices between a client and an RS.
The AS informs the client of the selected profile using the The AS informs the client of the selected profile using the
skipping to change at page 15, line 28 skipping to change at page 15, line 28
profile, the CBOR payload MAY be enclosed in a non-CBOR cryptographic profile, the CBOR payload MAY be enclosed in a non-CBOR cryptographic
wrapper. wrapper.
5.1. Discovering Authorization Servers 5.1. Discovering Authorization Servers
In order to determine the AS in charge of a resource hosted at the In order to determine the AS in charge of a resource hosted at the
RS, C MAY send an initial Unauthorized Resource Request message to RS, C MAY send an initial Unauthorized Resource Request message to
RS. RS then denies the request and sends the address of its AS back RS. RS then denies the request and sends the address of its AS back
to C. to C.
Instead of the initial Unauthorized Resource Request message, C MAY Instead of the initial Unauthorized Resource Request message, other
look up the desired resource in a resource directory (cf. discovery methods may be used, or the client may be pre-provisioned
[I-D.ietf-core-resource-directory]). with the address of the AS.
5.1.1. Unauthorized Resource Request Message 5.1.1. Unauthorized Resource Request Message
The optional Unauthorized Resource Request message is a request for a The optional Unauthorized Resource Request message is a request for a
resource hosted by RS for which no proper authorization is granted. resource hosted by RS for which no proper authorization is granted.
RS MUST treat any request for a protected resource as Unauthorized RS MUST treat any request for a protected resource as Unauthorized
Resource Request message when any of the following holds: Resource Request message when any of the following holds:
o The request has been received on an unprotected channel. o The request has been received on an unprotected channel.
o RS has no valid access token for the sender of the request o RS has no valid access token for the sender of the request
skipping to change at page 17, line 5 skipping to change at page 17, line 5
Figure 3: AS Information payload example Figure 3: AS Information payload example
In this example, the attribute AS points the receiver of this message In this example, the attribute AS points the receiver of this message
to the URI "coaps://as.example.com/token" to request access to the URI "coaps://as.example.com/token" to request access
permissions. The originator of the AS Information payload (i.e., RS) permissions. The originator of the AS Information payload (i.e., RS)
uses a local clock that is loosely synchronized with a time scale uses a local clock that is loosely synchronized with a time scale
common between RS and AS (e.g., wall clock time). Therefore, it has common between RS and AS (e.g., wall clock time). Therefore, it has
included a parameter "nonce" for replay attack prevention. included a parameter "nonce" for replay attack prevention.
Note: There is an ongoing discussion how freshness of access
tokens
can be achieved in constrained environments. This specification
for now assumes that RS and AS do not have a common understanding
of time that allows RS to achieve its security objectives without
explicitly adding a nonce.
Figure 4 illustrates the mandatory to use binary encoding of the Figure 4 illustrates the mandatory to use binary encoding of the
message payload shown in Figure 3. message payload shown in Figure 3.
a2 # map(2) a2 # map(2)
00 # unsigned(0) (=AS) 00 # unsigned(0) (=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) (=nonce) 05 # unsigned(5) (=nonce)
45 # bytes(5) 45 # bytes(5)
e0a156bb3f e0a156bb3f
Figure 4: AS Information example encoded in CBOR Figure 4: AS Information example encoded in CBOR
5.2. Authorization Grants 5.2. Authorization Grants
To request an access token, the client obtains authorization from the To request an access token, the client obtains authorization from the
resource owner or uses its client credentials as grant. The resource owner or uses its client credentials as grant. The
authorization is expressed in the form of an authorization grant. authorization is expressed in the form of an authorization grant.
The OAuth framework defines four grant types. The grant types can be The OAuth framework [RFC6749] defines four grant types. The grant
split up into two groups, those granted on behalf of the resource types can be split up into two groups, those granted on behalf of the
owner (password, authorization code, implicit) and those for the resource owner (password, authorization code, implicit) and those for
client (client credentials). the client (client credentials). Further grant types have been added
later, such as [RFC7521] defining an assertion-based authorization
grant.
The grant type is selected depending on the use case. In cases where The grant type is selected depending on the use case. In cases where
the client acts on behalf of the resource owner, authorization code the client acts on behalf of the resource owner, authorization code
grant is recommended. If the client acts on behalf of the resource grant is recommended. If the client acts on behalf of the resource
owner, but does not have any display or very limited interaction owner, but does not have any display or very limited interaction
possibilities it is recommended to use the device code grant defined possibilities it is recommended to use the device code grant defined
in [I-D.ietf-oauth-device-flow]. In cases where the client does not in [I-D.ietf-oauth-device-flow]. In cases where the client does not
act on behalf of the resource owner, client credentials grant is act on behalf of the resource owner, client credentials grant is
recommended. recommended.
skipping to change at page 22, line 39 skipping to change at page 22, line 39
response code equivalent to the CoAP response code 2.01 (Created). response code equivalent to the CoAP response code 2.01 (Created).
If client request was invalid, or not authorized, the AS returns an If client request was invalid, or not authorized, the AS returns an
error response as described in Section 5.6.3. error response as described in Section 5.6.3.
Note that the AS decides which token type and profile to use when 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 issuing a successful response. It is assumed that the AS has prior
knowledge of the capabilities of the client and the RS (see knowledge of the capabilities of the client and the RS (see
Appendix D. This prior knowledge may, for example, be set by the use Appendix D. This prior knowledge may, for example, be set by the use
of a dynamic client registration protocol exchange [RFC7591]. of a dynamic client registration protocol exchange [RFC7591].
The content of the successful reply is the RS Information. When The content of the successful reply is the Access Information. When
using CBOR payloads, the content MUST be encoded as CBOR map, using CBOR payloads, the content MUST be encoded as CBOR map,
containing parameters as specified in Section 5.1 of [RFC6749]. In containing parameters as specified in Section 5.1 of [RFC6749]. In
addition to these parameters, the following parameters are also part addition to these parameters, the following parameters are also part
of a successful response: of a successful response:
profile: profile:
OPTIONAL. This indicates the profile that the client MUST use OPTIONAL. This indicates the profile that the client MUST use
towards the RS. See Section 5.6.4.4 for the formatting of this towards the RS. See Section 5.6.4.4 for the formatting of this
parameter. If this parameter is absent, the AS assumes that the parameter. If this parameter is absent, the AS assumes that the
client implicitly knows which profile to use towards the RS. client implicitly knows which profile to use towards the RS.
skipping to change at page 23, line 23 skipping to change at page 23, line 23
token_type: token_type:
OPTIONAL. By default implementations of this framework SHOULD OPTIONAL. By default implementations of this framework SHOULD
assume that the token_type is "pop". If a specific use case assume that the token_type is "pop". If a specific use case
requires another token_type (e.g., "Bearer") to be used then this requires another token_type (e.g., "Bearer") to be used then this
parameter is REQUIRED. parameter is REQUIRED.
Note that if CBOR Web Tokens [RFC8392] are used, the access token Note that if CBOR Web Tokens [RFC8392] are used, the access token
also contains a "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession]. also contains a "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession].
This claim is however consumed by a different party. The access This claim is however consumed by a different party. The access
token is created by the AS and processed by the RS (and opaque to the token is created by the AS and processed by the RS (and opaque to the
client) whereas the RS Information is created by the AS and processed client) whereas the Access Information is created by the AS and
by the client; it is never forwarded to the resource server. processed by the client; it is never forwarded to the resource
server.
Figure 8 summarizes the parameters that may be part of the RS Figure 8 summarizes the parameters that may be part of the Access
Information. Information.
/-------------------+-----------------\ /-------------------+-----------------\
| Parameter name | Specified in | | Parameter name | Specified in |
|-------------------+-----------------| |-------------------+-----------------|
| access_token | RFC 6749 | | access_token | RFC 6749 |
| token_type | RFC 6749 | | token_type | RFC 6749 |
| expires_in | RFC 6749 | | expires_in | RFC 6749 |
| refresh_token | RFC 6749 | | refresh_token | RFC 6749 |
| scope | RFC 6749 | | scope | RFC 6749 |
| state | RFC 6749 | | state | RFC 6749 |
| error | RFC 6749 | | error | RFC 6749 |
| error_description | RFC 6749 | | error_description | RFC 6749 |
| error_uri | RFC 6749 | | error_uri | RFC 6749 |
| profile | [this document] | | profile | [this document] |
| cnf | [this document] | | cnf | [this document] |
| rs_cnf | [this document] | | rs_cnf | [this document] |
\-------------------+-----------------/ \-------------------+-----------------/
Figure 8: RS Information parameters Figure 8: Access Information parameters
Figure 9 shows a response containing a token and a "cnf" parameter Figure 9 shows a response containing a token and a "cnf" parameter
with a symmetric proof-of-possession key. Note that transport layer with a symmetric proof-of-possession key. Note that transport layer
security with CBOR encoding is assumed in this example, therefore the security with CBOR encoding is assumed in this example, therefore the
Content-Type is "application/cbor". Content-Type is "application/cbor".
Header: Created (Code=2.01) Header: Created (Code=2.01)
Content-Type: "application/cbor" Content-Type: "application/cbor"
Payload: Payload:
{ {
skipping to change at page 26, line 18 skipping to change at page 26, line 18
| password | 0 | RFC6749 | | password | 0 | RFC6749 |
| authorization_code | 1 | RFC6749 | | authorization_code | 1 | RFC6749 |
| client_credentials | 2 | RFC6749 | | client_credentials | 2 | RFC6749 |
| refresh_token | 3 | RFC6749 | | refresh_token | 3 | RFC6749 |
\--------------------+------------+------------------------/ \--------------------+------------+------------------------/
Figure 11: CBOR abbreviations for common grant types Figure 11: CBOR abbreviations for common grant types
5.6.4.3. Token Type 5.6.4.3. Token Type
The token_type parameter is defined in [RFC6749], allowing the AS to The "token_type" parameter, defined in [RFC6749], allows the AS to
indicate to the client which type of access token it is receiving indicate to the client which type of access token it is receiving
(e.g., a bearer token). (e.g., a bearer token).
This document registers the new value "pop" for the OAuth Access This document registers the new value "pop" for the OAuth Access
Token Types registry, specifying a Proof-of-Possession token. How Token Types registry, specifying a proof-of-possession token. How
the proof-of-possession is performed MUST be specified by the the proof-of-possession by the client to the RS is performed MUST be
profiles. specified by the profiles.
The values in the "token_type" parameter MUST be CBOR text strings, The values in the "token_type" parameter MUST be CBOR text strings,
if a CBOR encoding is used. if a CBOR encoding is used.
In this framework token type "pop" MUST be assumed by default if the In this framework the "pop" value for the "token_type" parameter is
AS does not provide a different value. the default. The AS may, however, provide a different value.
5.6.4.4. Profile 5.6.4.4. Profile
Profiles of this framework MUST define the communication protocol and Profiles of this framework MUST define the communication protocol and
the communication security protocol between the client and the RS. the communication security protocol between the client and the RS.
The security protocol MUST provide encryption, integrity and replay The security protocol MUST provide encryption, integrity and replay
protection. Furthermore profiles MUST define proof-of-possession protection. Furthermore profiles MUST define proof-of-possession
methods, if they support proof-of-possession tokens. methods, if they support proof-of-possession tokens.
A profile MUST specify an identifier that MUST be used to uniquely A profile MUST specify an identifier that MUST be used to uniquely
identify itself in the "profile" parameter. The textual identify itself in the "profile" parameter. The textual
representation of the profile identifier is just intended for human representation of the profile identifier is just intended for human
readability and MUST NOT be used in parameters and claims.. readability and MUST NOT be used in parameters and claims..
Profiles MAY define additional parameters for both the token request Profiles MAY define additional parameters for both the token request
and the RS 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.
5.6.4.5. Confirmation 5.6.4.5. Confirmation
The "cnf" parameter identifies or provides the key used for proof-of- The "cnf" parameter identifies or provides the key used for proof-of-
possession, while the "rs_cnf" parameter provides the raw public key possession, while the "rs_cnf" parameter provides the raw public key
of the RS. Both parameters use the same formatting and semantics as of the RS. Both parameters use the same formatting and semantics as
the "cnf" claim specified in [I-D.ietf-ace-cwt-proof-of-possession] the "cnf" claim specified in [I-D.ietf-ace-cwt-proof-of-possession]
when used with a CBOR encoding. When these parameters are used in when used with a CBOR encoding. When these parameters are used in
JSON then the formatting and semantics of the "cnf" claim specified JSON then the formatting and semantics of the "cnf" claim specified
skipping to change at page 27, line 36 skipping to change at page 27, line 36
Note that the COSE_Key structure in a "cnf" claim or parameter may Note that the COSE_Key structure in a "cnf" claim or parameter may
contain an "alg" or "key_ops" parameter. If such parameters are contain an "alg" or "key_ops" parameter. If such parameters are
present, a client MUST NOT use a key that is not compatible with the present, a client MUST NOT use a key that is not compatible with the
profile or proof-of-possession algorithm according to those profile or proof-of-possession algorithm according to those
parameters. An RS MUST reject a proof-of-possession using such a parameters. An RS MUST reject a proof-of-possession using such a
key. key.
Also note that the "rs_cnf" parameter is supposed to indicate the key Also note that the "rs_cnf" parameter is supposed to indicate the key
that the RS uses to authenticate. If the access token is issued for that the RS uses to authenticate. If the access token is issued for
an audience that includes several RS, this parameter MUST NOT be an audience that includes several RS, this parameter MUST NOT be
used, since it is them impossible to determine for which RS the key used, since the client cannot determine for which RS the key applies.
applies. This framework recommends to specify a different endpoint This framework recommends to specify a different endpoint that the
that the client can use to acquire RS authentication keys in such client can use to acquire RS authentication keys in such cases. The
cases. The specification of such an endpoint is out of scope for specification of such an endpoint is out of scope for this framework.
this framework.
5.6.5. Mapping Parameters to CBOR 5.6.5. Mapping Parameters to CBOR
If CBOR encoding is used, all OAuth parameters in access token If CBOR encoding is used, all OAuth parameters in access token
requests and responses MUST be mapped to CBOR types as specified in requests and responses MUST be mapped to CBOR types as specified in
Figure 12, using the given integer abbreviation for the map keys. Figure 12, using the given integer abbreviation for the map keys.
Note that we have aligned these abbreviations with the claim Note that we have aligned these abbreviations with the claim
abbreviations defined in [RFC8392]. abbreviations defined in [RFC8392].
skipping to change at page 28, line 37 skipping to change at page 28, line 37
| profile | 26 | unsigned integer | | profile | 26 | unsigned integer |
| rs_cnf | 31 | map | | rs_cnf | 31 | map |
\-------------------+----------+---------------------/ \-------------------+----------+---------------------/
Figure 12: CBOR mappings used in token requests Figure 12: CBOR mappings used in token requests
5.7. The 'Introspect' Endpoint 5.7. The 'Introspect' Endpoint
Token introspection [RFC7662] can be OPTIONALLY provided by the AS, Token introspection [RFC7662] can be OPTIONALLY provided by the AS,
and is then used by the RS and potentially the client to query the AS and is then used by the RS and potentially the client to query the AS
for metadata about a given token e.g., validity or scope. Analogous for metadata about a given token, e.g., validity or scope. Analogous
to the protocol defined in RFC 7662 [RFC7662] for HTTP and JSON, this to the protocol defined in RFC 7662 [RFC7662] for HTTP and JSON, this
section defines adaptations to more constrained environments using section defines adaptations to more constrained environments using
CBOR and leaving the choice of the application protocol to the CBOR and leaving the choice of the application protocol to the
profile. profile.
Communication between the RS and the introspection endpoint at the AS Communication between the RS and the introspection endpoint at the AS
MUST be integrity protected and encrypted. Furthermore AS and RS MUST be integrity protected and encrypted. Furthermore AS and RS
MUST perform mutual authentication. Finally the AS SHOULD verify MUST perform mutual authentication. Finally the AS SHOULD verify
that the RS has the right to access introspection information about that the RS has the right to access introspection information about
the provided token. Profiles of this framework that support the provided token. Profiles of this framework that support
skipping to change at page 29, line 33 skipping to change at page 29, line 33
representing additional context that is known by the RS to aid the AS representing additional context that is known by the RS to aid the AS
in its response MAY be included. in its response MAY be included.
The same parameters are required and optional as in Section 2.1 of The same parameters are required and optional as in Section 2.1 of
RFC 7662 [RFC7662]. RFC 7662 [RFC7662].
For example, Figure 13 shows a RS calling the token introspection For example, Figure 13 shows a RS calling the token introspection
endpoint at the AS to query about an OAuth 2.0 proof-of-possession endpoint at the AS to query about an OAuth 2.0 proof-of-possession
token. Note that object security based on COSE is assumed in this token. Note that object security based on COSE is assumed in this
example, therefore the Content-Type is "application/cose+cbor". example, therefore the Content-Type is "application/cose+cbor".
Figure 14 shows the decoded payload.
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"
Content-Type: "application/cose+cbor" Content-Type: "application/cose+cbor"
Payload: Payload:
... COSE content ...
Figure 13: Example introspection request.
{ {
"token" : b64'7gj0dXJQ43U', "token" : b64'7gj0dXJQ43U',
"token_type_hint" : "pop" "token_type_hint" : "pop"
} }
Figure 13: Example introspection request. Figure 14: Decoded token.
5.7.2. AS-to-RS Response 5.7.2. AS-to-RS Response
If the introspection request is authorized and successfully If the introspection request is authorized and successfully
processed, the AS sends a response with the response code equivalent processed, the AS sends a response with the response code equivalent
to the CoAP code 2.01 (Created). If the introspection request was to the CoAP code 2.01 (Created). If the introspection request was
invalid, not authorized or couldn't be processed the AS returns an invalid, not authorized or couldn't be processed the AS returns an
error response as described in Section 5.7.3. error response as described in Section 5.7.3.
In a successful response, the AS encodes the response parameters in a In a successful response, the AS encodes the response parameters in a
map including with the same required and optional parameters as in map including with the same required and optional parameters as in
Section 2.2. of RFC 7662 [RFC7662] with the following additions: Section 2.2 of RFC 7662 [RFC7662] with the following additions:
cnf OPTIONAL. This field contains information about the proof-of- cnf OPTIONAL. This field contains information about the proof-of-
possession key that binds the client to the access token. See possession key that binds the client to the access token. See
Section 5.6.4.5 for more details on the use of the "cnf" Section 5.6.4.5 for more details on the use of the "cnf"
parameter. parameter.
profile OPTIONAL. This indicates the profile that the RS MUST use profile OPTIONAL. This indicates the profile that the RS MUST use
with the client. See Section 5.6.4.4 for more details on the with the client. See Section 5.6.4.4 for more details on the
formatting of this parameter. formatting of this parameter.
rs_cnf OPTIONAL. If the RS has several keys it can use to rs_cnf OPTIONAL. If the RS has several keys it can use to
authenticate towards the client, the AS can give the RS a hint authenticate towards the client, the AS can give the RS a hint
using this parameter, as to which key it should use (e.g. if the using this parameter, as to which key it should use (e.g., if the
AS previously informed the client about a public key the RS is AS previously informed the client about a public key the RS is
holding). See Section 5.6.4.5 for more details on the use of this holding). See Section 5.6.4.5 for more details on the use of this
parameter. parameter.
For example, Figure 14 shows an AS response to the introspection For example, Figure 15 shows an AS response to the introspection
request in Figure 13. Note that transport layer security is assumed request in Figure 13. Note that transport layer security is assumed
in this example, therefore the Content-Type is "application/cbor". in this example, therefore the Content-Type is "application/cbor".
Header: Created Code=2.01) Header: Created Code=2.01)
Content-Type: "application/cbor" Content-Type: "application/cbor"
Payload: Payload:
{ {
"active" : true, "active" : true,
"scope" : "read", "scope" : "read",
"profile" : "coap_dtls", "profile" : "coap_dtls",
"cnf" : { "cnf" : {
"COSE_Key" : { "COSE_Key" : {
"kty" : "Symmetric", "kty" : "Symmetric",
"kid" : b64'39Gqlw', "kid" : b64'39Gqlw',
"k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh'
} }
} }
} }
Figure 14: Example introspection response. Figure 15: Example introspection response.
5.7.3. Error Response 5.7.3. Error Response
The error responses for CoAP-based interactions with the AS are The error responses for CoAP-based interactions with the AS are
equivalent to the ones for HTTP-based interactions as defined in equivalent to the ones for HTTP-based interactions as defined in
Section 2.3 of [RFC7662], with the following differences: Section 2.3 of [RFC7662], with the following differences:
o If content is sent, the Content-Type MUST be set according to the o If content is sent, the Content-Type MUST be set according to the
specification of the communication security profile. If CoAP is specification of the communication security profile. If CoAP is
used the payload MUST be encoded as a CBOR map. used the payload MUST be encoded as a CBOR map.
skipping to change at page 31, line 30 skipping to change at page 31, line 36
Note that a properly formed and authorized query for an inactive or 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 MUST instead
respond with an introspection response with the "active" field set to respond with an introspection response with the "active" field set to
"false". "false".
5.7.4. Mapping Introspection parameters to CBOR 5.7.4. Mapping Introspection parameters to CBOR
If CBOR is used, the introspection request and response parameters If CBOR is used, the introspection request and response parameters
MUST be mapped to CBOR types as specified in Figure 15, using the MUST be mapped to CBOR types as specified in Figure 16, using the
given integer abbreviation for the map key. given integer abbreviation for the map key.
Note that we have aligned these abbreviations with the claim Note that we have aligned these abbreviations with the claim
abbreviations defined in [RFC8392]. abbreviations defined in [RFC8392].
/-----------------+----------+----------------------------------\ /-----------------+----------+----------------------------------\
| Parameter name | CBOR Key | Value Type | | Parameter name | CBOR Key | Value Type |
|-----------------+----------+----------------------------------| |-----------------+----------+----------------------------------|
| iss | 1 | text string | | iss | 1 | text string |
| sub | 2 | text string | | sub | 2 | text string |
skipping to change at page 32, line 27 skipping to change at page 32, line 27
| token_type | 20 | text string | | token_type | 20 | text string |
| username | 22 | text string | | username | 22 | text string |
| cnf | 25 | map | | cnf | 25 | map |
| profile | 26 | unsigned integer | | profile | 26 | unsigned integer |
| token | 27 | byte string | | token | 27 | byte string |
| token_type_hint | 28 | text string | | token_type_hint | 28 | text string |
| active | 29 | True or False | | active | 29 | True or False |
| rs_cnf | 30 | map | | rs_cnf | 30 | map |
\-----------------+----------+----------------------------------/ \-----------------+----------+----------------------------------/
Figure 15: CBOR Mappings to Token Introspection Parameters. Figure 16: CBOR Mappings to Token Introspection Parameters.
5.8. The Access Token 5.8. The Access Token
This framework RECOMMENDS the use of CBOR web token (CWT) as This framework RECOMMENDS the use of CBOR web token (CWT) as
specified in [RFC8392]. specified in [RFC8392].
In order to facilitate offline processing of access tokens, this In order to facilitate offline processing of access tokens, this
draft uses the "cnf" claim from draft uses the "cnf" claim from
[I-D.ietf-ace-cwt-proof-of-possession] and specifies the "scope" [I-D.ietf-ace-cwt-proof-of-possession] and specifies the "scope"
claim for both JSON and CBOR web tokens. claim for both JSON and CBOR web tokens.
skipping to change at page 33, line 32 skipping to change at page 33, line 32
token is valid, the RS MUST respond to the POST request with 2.01 token is valid, the RS MUST respond to the POST request with 2.01
(Created). This response MAY contain an identifier of the token (Created). This response MAY contain an identifier of the token
(e.g., the cti for a CWT) as a payload, in order to allow the client (e.g., the cti for a CWT) as a payload, in order to allow the client
to refer to the token. to refer to the token.
The RS MUST be prepared to store at least one access token for future The RS MUST be prepared to store at least one access token for future
use. This is a difference to how access tokens are handled in OAuth use. This is a difference to how access tokens are handled in OAuth
2.0, where the access token is typically sent along with each 2.0, where the access token is typically sent along with each
request, and therefore not stored at the RS. request, and therefore not stored at the RS.
If the token is not valid, the RS MUST respond with a response code If the payload sent to the authz-info endpoint does not parse to a
equivalent to the CoAP code 4.01 (Unauthorized). If the token is token, the RS MUST respond with a response code equivalent to the
valid but the audience of the token does not match the RS, the RS CoAP code 4.00 (Bad Request). If the token is not valid, the RS MUST
MUST respond with a response code equivalent to the CoAP code 4.03 respond with a response code equivalent to the CoAP code 4.01
(Forbidden). If the token is valid but is associated to claims that (Unauthorized). If the token is valid but the audience of the token
the RS cannot process (e.g., an unknown scope) the RS MUST respond does not match the RS, the RS MUST respond with a response code
with a response code equivalent to the CoAP code 4.00 (Bad Request). equivalent to the CoAP code 4.03 (Forbidden). If the token is valid
In the latter case the RS MAY provide additional information in the but is associated to claims that the RS cannot process (e.g., an
error response, in order to clarify what went wrong. unknown scope) the RS MUST respond with a response code equivalent to
the CoAP code 4.00 (Bad Request). In the latter case the RS MAY
provide additional information in the error response, in order to
clarify what went wrong.
The RS MAY make an introspection request to validate the token before The RS MAY make an introspection request to validate the token before
responding to the POST request to the authz-info endpoint. responding to the POST request to the authz-info endpoint.
Profiles MUST specify how the authz-info endpoint is protected, Profiles MUST specify how the authz-info endpoint is protected,
including how error responses from this endpoint are protected. Note including how error responses from this endpoint are protected. Note
that since the token contains information that allow the client and that since the token contains information that allow the client and
the RS to establish a security context in the first place, mutual the RS to establish a security context in the first place, mutual
authentication may not be possible at this point. authentication may not be possible at this point.
skipping to change at page 34, line 34 skipping to change at page 34, line 36
prevent infinite loops where a dumb Client optimistically tries to prevent infinite loops where a dumb Client optimistically tries to
access a requested resource with any access token received from AS. access a requested resource with any access token received from AS.
As malicious clients could pretend to be C to determine C's As malicious clients could pretend to be C to determine C's
privileges, these detailed response codes must be used only when a privileges, these detailed response codes must be used only when a
certain level of security is already available which can be achieved certain level of security is already available which can be achieved
only when the Client is authenticated. only when the Client is authenticated.
Note: The RS MAY use introspection for timely validation of an access Note: The RS MAY use introspection for timely validation of an access
token, at the time when a request is presented. token, at the time when a request is presented.
Note: Matching the claims of the access token (e.g. scope) to a Note: Matching the claims of the access token (e.g., scope) to a
specific request is application specific. specific request is application specific.
If the request matches a valid token and the client has performed the If the request matches a valid token and the client has performed the
proof-of-possession for that token, the RS continues to process the proof-of-possession for that token, the RS continues to process the
request as specified by the underlying application. request as specified by the underlying application.
5.8.3. Token Expiration 5.8.3. Token Expiration
Depending on the capabilities of the RS, there are various ways in Depending on the capabilities of the RS, there are various ways in
which it can verify the validity of a received access token. Here which it can verify the validity of a received access token. Here
skipping to change at page 36, line 47 skipping to change at page 36, line 51
possession SHOULD NOT be targeted at an audience that contains more possession SHOULD NOT be targeted at an audience that contains more
than one RS, since otherwise any RS in the audience that receives than one RS, since otherwise any RS in the audience that receives
that access token can impersonate the client towards the other that access token can impersonate the client towards the other
members of the audience. members of the audience.
6.1. Unprotected AS Information 6.1. Unprotected AS Information
Initially, no secure channel exists to protect the communication Initially, no secure channel exists to protect the communication
between C and RS. Thus, C cannot determine if the AS information between C and RS. Thus, C cannot determine if the AS information
contained in an unprotected response from RS to an unauthorized contained in an unprotected response from RS to an unauthorized
request (c.f. Section 5.1.2) is authentic. It is therefore request (see Section 5.1.2) is authentic. It is therefore advisable
advisable to provide C with a (possibly hard-coded) list of to provide C with a (possibly hard-coded) list of trustworthy
trustworthy authorization servers. AS information responses authorization servers. AS information responses referring to a URI
referring to a URI not listed there would be ignored. not listed there would be ignored.
6.2. Use of Nonces for Replay Protection 6.2. Use of Nonces for Replay Protection
RS may add a nonce to the AS Information message sent as a response The RS may add a nonce to the AS Information message sent as a
to an unauthorized request to ensure freshness of an Access Token response to an unauthorized request to ensure freshness of an Access
subsequently presented to RS. While a time-stamp of some granularity Token subsequently presented to RS. While a time-stamp of some
would be sufficient to protect against replay attacks, using granularity would be sufficient to protect against replay attacks,
randomized nonce is preferred to prevent disclosure of information using randomized nonce is preferred to prevent disclosure of
about RS's internal clock characteristics. information about RS's internal clock characteristics.
6.3. Combining profiles 6.3. Combining profiles
There may exist reasonable use cases where implementers want to There may be use cases were different profiles of this framework are
combine different profiles of this framework, e.g., using an MQTT combined. For example, an MQTT-TLS profile is used between the
profile between client and RS, while using a DTLS profile for client and the RS in combination with a CoAP-DTLS profile for
interactions between client and AS. Profiles should be designed in a interactions between the client and the AS. Ideally, profiles should
way that the security of a protocol interaction does not depend on be designed in a way that the security of system should not depend on
the specific security mechanisms used in other protocol interactions. the specific security mechanisms used in individual protocol
interactions.
6.4. Error responses 6.4. Error responses
The various error responses defined in this framework may leak The various error responses defined in this framework may leak
information to an adversary. For example errors responses for information to an adversary. For example errors responses for
requests to the Authorization Information endpoint can reveal requests to the Authorization Information endpoint can reveal
information about an otherwise opaque access token to an adversary information about an otherwise opaque access token to an adversary
who has intercepted this token. This framework is written under the who has intercepted this token. This framework is written under the
assumption that, in general, the benefits of detailed error messages assumption that, in general, the benefits of detailed error messages
outweigh the risk due to information leakage. For particular use outweigh the risk due to information leakage. For particular use
skipping to change at page 37, line 52 skipping to change at page 38, line 8
the client credentials grant is used, the AS can track what kind of the client credentials grant is used, the AS can track what kind of
access the client intends to perform. With other grants this can be access the client intends to perform. With other grants this can be
prevented by the Resource Owner. To do so, the resource owner needs prevented by the Resource Owner. To do so, the resource owner needs
to bind the grants it issues to anonymous, ephemeral credentials that to bind the grants it issues to anonymous, ephemeral credentials that
do not allow the AS to link different grants and thus different do not allow the AS to link different grants and thus different
access token requests by the same client. access token requests by the same client.
If access tokens are only integrity protected and not encrypted, they If access 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 able to
acquire the access tokens in some other way. In the case of CWTs the 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 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). not a machine-to-machine interaction).
Clients using asymmetric keys for proof-of-possession should be aware Clients using asymmetric keys for proof-of-possession should be aware
of the consequences of using the same key pair for proof-of- of the consequences of using the same key pair for proof-of-
possession towards different RSs. A set of colluding RSs or an possession towards different RSs. A set of colluding RSs or an
attacker able to obtain the access tokens will be able to link the attacker able to obtain the access tokens will be able to link the
requests, or even to determine the client's identity. requests, or even to determine the client's identity.
An unprotected response to an unauthorized request (c.f. An unprotected response to an unauthorized request (see
Section 5.1.2) may disclose information about RS and/or its existing Section 5.1.2) may disclose information about RS and/or its existing
relationship with C. It is advisable to include as little relationship with C. It is advisable to include as little
information as possible in an unencrypted response. Means of information as possible in an unencrypted response. Means of
encrypting communication between C and RS already exist, more encrypting communication between C and RS already exist, more
detailed information may be included with an error response to detailed information may be included with an error response to
provide C with sufficient information to react on that particular provide C with sufficient information to react on that particular
error. error.
8. IANA Considerations 8. IANA Considerations
skipping to change at page 39, line 17 skipping to change at page 39, line 23
This section establish the IANA "OAuth Error Code CBOR Mappings" This section establish the IANA "OAuth Error Code CBOR Mappings"
registry. The registry has been created to use the "Expert Review registry. The registry has been created to use the "Expert Review
Required" registration procedure [RFC8126]. It should be noted that, Required" registration procedure [RFC8126]. It should be noted that,
in addition to the expert review, some portions of the registry in addition to the expert review, some portions of the registry
require a specification, potentially a Standards Track RFC, be require a specification, potentially a Standards Track RFC, be
supplied as well. supplied as well.
The columns of the registry are: The columns of the registry are:
Name The OAuth Error Code name, refers to the name in Section 5.2. Name The OAuth Error Code name, refers to the name in Section 5.2.
of [RFC6749] e.g., "invalid_request". of [RFC6749], e.g., "invalid_request".
CBOR Value CBOR abbreviation for this error code. Different ranges CBOR Value CBOR abbreviation for this error code. Different ranges
of values use different registration policies [RFC8126]. Integer of values use different registration policies [RFC8126]. Integer
values from -256 to 255 are designated as Standards Action. values from -256 to 255 are designated as Standards Action.
Integer values from -65536 to -257 and from 256 to 65535 are Integer values from -65536 to -257 and from 256 to 65535 are
designated as Specification Required. Integer values greater than designated as Specification Required. Integer values greater than
65535 are designated as Expert Review. Integer values less than 65535 are designated as Expert Review. Integer values less than
-65536 are marked as Private Use. -65536 are marked as Private Use.
Reference This contains a pointer to the public specification of the Reference This contains a pointer to the public specification of the
grant type abbreviation, if one exists. grant type abbreviation, if one exists.
skipping to change at page 40, line 32 skipping to change at page 40, line 38
This section eatables the IANA "Token Type CBOR Mappings" registry. This section eatables the IANA "Token Type CBOR Mappings" registry.
The registry has been created to use the "Expert Review Required" The registry has been created to use the "Expert Review Required"
registration procedure [RFC8126]. It should be noted that, in registration procedure [RFC8126]. It should be noted that, in
addition to the expert review, some portions of the registry require addition to the expert review, some portions of the registry require
a specification, potentially a Standards Track RFC, be supplied as a specification, potentially a Standards Track RFC, be supplied as
well. well.
The columns of this registry are: The columns of this registry are:
Name The name of token type as registered in the OAuth Access Token Name The name of token type as registered in the OAuth Access Token
Types registry e.g., "Bearer". Types registry, e.g., "Bearer".
CBOR Value CBOR abbreviation for this token type. Different ranges CBOR Value CBOR abbreviation for this token type. Different ranges
of values use different registration policies [RFC8126]. Integer of values use different registration policies [RFC8126]. Integer
values from -256 to 255 are designated as Standards Action. values from -256 to 255 are designated as Standards Action.
Integer values from -65536 to -257 and from 256 to 65535 are Integer values from -65536 to -257 and from 256 to 65535 are
designated as Specification Required. Integer values greater than designated as Specification Required. Integer values greater than
65535 are designated as Expert Review. Integer values less than 65535 are designated as Expert Review. Integer values less than
-65536 are marked as Private Use. -65536 are marked as Private Use.
Reference This contains a pointer to the public specification of the Reference This contains a pointer to the public specification of the
OAuth token type abbreviation, if one exists. OAuth token type abbreviation, if one exists.
Original Specification This contains a pointer to the public Original Specification This contains a pointer to the public
skipping to change at page 42, line 21 skipping to change at page 42, line 30
This section establishes the IANA "Token Endpoint CBOR Mappings" This section establishes the IANA "Token Endpoint CBOR Mappings"
registry. The registry has been created to use the "Expert Review registry. The registry has been created to use the "Expert Review
Required" registration procedure [RFC8126]. It should be noted that, Required" registration procedure [RFC8126]. It should be noted that,
in addition to the expert review, some portions of the registry in addition to the expert review, some portions of the registry
require a specification, potentially a Standards Track RFC, be require a specification, potentially a Standards Track RFC, be
supplied as well. supplied as well.
The columns of this registry are: The columns of this registry are:
Name The OAuth Parameter name, refers to the name in the OAuth Name The OAuth Parameter name, refers to the name in the OAuth
parameter registry e.g., "client_id". parameter registry, e.g., "client_id".
CBOR Key CBOR map key for this parameter. Different ranges of CBOR Key CBOR map key for this parameter. Different ranges of
values use different registration policies [RFC8126]. Integer values use different registration policies [RFC8126]. Integer
values from -256 to 255 are designated as Standards Action. values from -256 to 255 are designated as Standards Action.
Integer values from -65536 to -257 and from 256 to 65535 are Integer values from -65536 to -257 and from 256 to 65535 are
designated as Specification Required. Integer values greater than designated as Specification Required. Integer values greater than
65535 are designated as Expert Review. Integer values less than 65535 are designated as Expert Review. Integer values less than
-65536 are marked as Private Use. -65536 are marked as Private Use.
Value Type The allowable CBOR data types for values of this Value Type The allowable CBOR data types for values of this
parameter. parameter.
Reference This contains a pointer to the public specification of the Reference This contains a pointer to the public specification of the
skipping to change at page 43, line 21 skipping to change at page 43, line 33
This section establishes the IANA "Introspection Endpoint CBOR This section establishes the IANA "Introspection Endpoint CBOR
Mappings" registry. The registry has been created to use the "Expert Mappings" registry. The registry has been created to use the "Expert
Review Required" registration procedure [RFC8126]. It should be Review Required" registration procedure [RFC8126]. It should be
noted that, in addition to the expert review, some portions of the noted that, in addition to the expert review, some portions of the
registry require a specification, potentially a Standards Track RFC, registry require a specification, potentially a Standards Track RFC,
be supplied as well. be supplied as well.
The columns of this registry are: The columns of this registry are:
Name The OAuth Parameter name, refers to the name in the OAuth Name The OAuth Parameter name, refers to the name in the OAuth
parameter registry e.g., "client_id". parameter registry, e.g., "client_id".
CBOR Key CBOR map key for this parameter. Different ranges of CBOR Key CBOR map key for this parameter. Different ranges of
values use different registration policies [RFC8126]. Integer values use different registration policies [RFC8126]. Integer
values from -256 to 255 are designated as Standards Action. values from -256 to 255 are designated as Standards Action.
Integer values from -65536 to -257 and from 256 to 65535 are Integer values from -65536 to -257 and from 256 to 65535 are
designated as Specification Required. Integer values greater than designated as Specification Required. Integer values greater than
65535 are designated as Expert Review. Integer values less than 65535 are designated as Expert Review. Integer values less than
-65536 are marked as Private Use. -65536 are marked as Private Use.
Value Type The allowable CBOR data types for values of this Value Type The allowable CBOR data types for values of this
parameter. parameter.
Reference This contains a pointer to the public specification of the Reference This contains a pointer to the public specification of the
grant type abbreviation, if one exists. grant type abbreviation, if one exists.
This registry will be initially populated by the values in Figure 15. This registry will be initially populated by the values in Figure 16.
The Reference column for all of these entries will be this document. The Reference column for all of these entries will be this document.
8.11. JSON Web Token Claims 8.11. JSON Web Token Claims
This specification registers the following new claims in the JSON Web This specification registers the following new claims in the JSON Web
Token (JWT) registry of JSON Web Token Claims Token (JWT) registry of JSON Web Token Claims
[IANA.JsonWebTokenClaims]: [IANA.JsonWebTokenClaims]:
o Claim Name: "scope" o Claim Name: "scope"
o Claim Description: The scope of an access token as defined in o Claim Description: The scope of an access token as defined in
skipping to change at page 46, line 41 skipping to change at page 47, line 11
architecture for authorization in constrained architecture for authorization in constrained
environments", draft-ietf-ace-actors-06 (work in environments", draft-ietf-ace-actors-06 (work in
progress), November 2017. progress), November 2017.
[I-D.ietf-core-object-security] [I-D.ietf-core-object-security]
Selander, G., Mattsson, J., Palombini, F., and L. Seitz, Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security for Constrained RESTful Environments "Object Security for Constrained RESTful Environments
(OSCORE)", draft-ietf-core-object-security-12 (work in (OSCORE)", draft-ietf-core-object-security-12 (work in
progress), March 2018. progress), March 2018.
[I-D.ietf-core-resource-directory]
Shelby, Z., Koster, M., Bormann, C., Stok, P., and C.
Amsuess, "CoRE Resource Directory", draft-ietf-core-
resource-directory-13 (work in progress), March 2018.
[I-D.ietf-oauth-device-flow] [I-D.ietf-oauth-device-flow]
Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, Denniss, W., Bradley, J., Jones, M., and H. Tschofenig,
"OAuth 2.0 Device Flow for Browserless and Input "OAuth 2.0 Device Flow for Browserless and Input
Constrained Devices", draft-ietf-oauth-device-flow-09 Constrained Devices", draft-ietf-oauth-device-flow-10
(work in progress), April 2018. (work in progress), June 2018.
[I-D.ietf-oauth-discovery]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", draft-ietf-oauth-
discovery-10 (work in progress), March 2018.
[Margi10impact] [Margi10impact]
Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr, Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr,
M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold, M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold,
"Impact of Operating Systems on Wireless Sensor Networks "Impact of Operating Systems on Wireless Sensor Networks
(Security) Applications and Testbeds", Proceedings of (Security) Applications and Testbeds", Proceedings of
the 19th International Conference on Computer the 19th International Conference on Computer
Communications and Networks (ICCCN), 2010 August. Communications and Networks (ICCCN), 2010 August.
[RFC4949] Shirey, R., "Internet Security Glossary, Version 2", [RFC4949] Shirey, R., "Internet Security Glossary, Version 2",
skipping to change at page 48, line 44 skipping to change at page 49, line 5
[RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,
<https://www.rfc-editor.org/info/rfc8252>. <https://www.rfc-editor.org/info/rfc8252>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, <https://www.rfc- DOI 10.17487/RFC8259, December 2017, <https://www.rfc-
editor.org/info/rfc8259>. editor.org/info/rfc8259>.
[RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", RFC 8414,
DOI 10.17487/RFC8414, June 2018, <https://www.rfc-
editor.org/info/rfc8414>.
Appendix A. Design Justification Appendix A. Design Justification
This section provides further insight into the design decisions of This section provides further insight into the design decisions of
the solution documented in this document. Section 3 lists several the solution documented in this document. Section 3 lists several
building blocks and briefly summarizes their importance. The building blocks and briefly summarizes their importance. The
justification for offering some of those building blocks, as opposed justification for offering some of those building blocks, as opposed
to using OAuth 2.0 as is, is given below. to using OAuth 2.0 as is, is given below.
Common IoT constraints are: Common IoT constraints are:
Low Power Radio: Low Power Radio:
Many IoT devices are equipped with a small battery which needs to Many IoT devices are equipped with a small battery which needs to
last for a long time. For many constrained wireless devices, the 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 e.g. AES) messages (roughly by a factor of 10 compared to AES)
[Margi10impact]. It is therefore important to keep the total [Margi10impact]. It is therefore important to keep the total
communication overhead low, including minimizing the number and communication overhead low, including minimizing the number and
size of messages sent and received, which has an impact of choice size of messages sent and received, which has an impact of choice
on the message format and protocol. By using CoAP over UDP and on the message format and protocol. By using CoAP over UDP and
CBOR encoded messages, some of these aspects are addressed. CBOR encoded messages, some of these aspects are addressed.
Security protocols contribute to the communication overhead and Security protocols contribute to the communication overhead and
can, in some cases, be optimized. For example, authentication and can, in some cases, be optimized. For example, authentication and
key establishment may, in certain cases where security key establishment may, in certain cases where security
requirements allow, be replaced by provisioning of security requirements allow, be replaced by provisioning of security
context by a trusted third party, using transport or application context by a trusted third party, using transport or application
layer security. layer security.
Low CPU Speed: Low CPU Speed:
Some IoT devices are equipped with processors that are Some IoT devices are equipped with processors that are
significantly slower than those found in most current devices on significantly slower than those found in most current devices on
the Internet. This typically has implications on what timely the Internet. This typically has implications on what timely
cryptographic operations a device is capable of performing, which cryptographic operations a device is capable of performing, which
in turn impacts e.g., protocol latency. Symmetric key in turn impacts, e.g., protocol latency. Symmetric key
cryptography may be used instead of the computationally more cryptography may be used instead of the computationally more
expensive public key cryptography where the security requirements expensive public key cryptography where the security requirements
so allows, but this may also require support for trusted third so allows, but this may also require support for trusted third
party assisted secret key establishment using transport or party assisted secret key establishment using transport or
application layer security. application layer security.
Small Amount of Memory: Small Amount of Memory:
Microcontrollers embedded in IoT devices are often equipped with Microcontrollers embedded in IoT devices are often equipped with
small amount of RAM and flash memory, which places limitations small amount of RAM and flash memory, which places limitations
what kind of processing can be performed and how much code can be what kind of processing can be performed and how much code can be
skipping to change at page 50, line 47 skipping to change at page 51, line 17
is RECOMMENDED. Furthermore where self-contained tokens are is RECOMMENDED. Furthermore where self-contained tokens are
needed, this framework RECOMMENDS the use of CWT [RFC8392]. These needed, this framework RECOMMENDS the use of CWT [RFC8392]. These
measures aim at reducing the size of messages sent over the wire, measures aim 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 RAM size of data objects that need to be kept in memory and
the size of libraries that devices need to support. the size of libraries that devices need to support.
CoAP: CoAP:
This framework RECOMMENDS the use of CoAP [RFC7252] instead of This framework RECOMMENDS the use of CoAP [RFC7252] instead of
HTTP. This does not preclude the use of other protocols HTTP. This does not preclude the use of other protocols
specifically aimed at constrained devices, like e.g. Bluetooth specifically aimed at constrained devices, like, e.g., Bluetooth
Low energy (see Section 3.2). This aims again at reducing the Low Energy (see Section 3.2). This aims again at reducing the
size of messages sent over the wire, the RAM size of data objects 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 that need to be kept in memory and the size of libraries that
devices need to support. devices need to support.
RS Information: Access Information:
This framework defines the name "RS 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 Section 5.6.2). This includes the "profile" token response (see Section 5.6.2). This includes the "profile"
and the "rs_cnf" parameters. This aims at enabling scenarios, and the "rs_cnf" parameters. This aims at enabling scenarios,
where a powerful client, supporting multiple profiles, needs to where a powerful client, supporting multiple profiles, needs to
interact with a RS for which it does not know the supported interact with a RS for which it does not know the supported
profiles and the raw public key. profiles and the raw public key.
Proof-of-Possession: Proof-of-Possession:
This framework makes use of proof-of-possession tokens, using the This framework makes use of proof-of-possession tokens, using the
skipping to change at page 51, line 34 skipping to change at page 52, line 4
could be able to steal bearer tokens and use them to gain could be able to steal bearer tokens and use them to gain
unauthorized access. unauthorized access.
Auth-Info endpoint: Auth-Info endpoint:
This framework introduces a new way of providing access tokens to This framework introduces a new way of providing access tokens to
a RS by exposing a authz-info endpoint, to which access tokens can a RS by exposing a authz-info endpoint, to which access tokens can
be POSTed. This aims at reducing the size of the request message be POSTed. This aims at reducing the size of the request message
and the code complexity at the RS. The size of the request and the code complexity at the RS. The size of the request
message is problematic, since many constrained protocols have message is problematic, since many constrained protocols have
severe message size limitations at the physical layer (e.g. in the severe message size limitations at the physical layer (e.g., in
order of 100 bytes). This means that larger packets get the order of 100 bytes). This means that larger packets get
fragmented, which in turn combines badly with the high rate of fragmented, which in turn combines badly with the high rate of
packet loss, and the need to retransmit the whole message if one packet loss, and the need to retransmit the whole message if one
packet gets lost. Thus separating sending of the request and packet gets lost. Thus separating sending of the request and
sending of the access tokens helps to reduce fragmentation. sending of the access tokens helps to reduce fragmentation.
Client Credentials Grant: Client Credentials Grant:
This framework RECOMMENDS the use of the client credentials grant This framework RECOMMENDS the use of the client credentials grant
for machine-to-machine communication use cases, where manual for machine-to-machine communication use cases, where manual
intervention of the resource owner to produce a grant token is not intervention of the resource owner to produce a grant token is not
skipping to change at page 53, line 15 skipping to change at page 53, line 34
* Authenticate clients that wish to request a token. * Authenticate clients that wish to request a token.
* Process a token request using the authorization policies * Process a token request using the authorization policies
configured for the RS. configured for the RS.
* Optionally: Expose the introspection endpoint that allows RS's * Optionally: Expose the introspection endpoint that allows RS's
to submit token introspection requests. to submit token introspection requests.
* If providing an introspection endpoint: Authenticate RSs that * If providing an introspection endpoint: Authenticate RSs that
wish to get an introspection response. wish to get an introspection response.
* If providing an introspection endpoint: Process token * If providing an introspection endpoint: Process token
introspection requests. introspection requests.
* Optionally: Handle token revocation. * Optionally: Handle token revocation.
* Optionally: Provide discovery metadata. See * Optionally: Provide discovery metadata. See [RFC8414]
[I-D.ietf-oauth-discovery]
Client Client
* Discover the AS in charge of the RS that is to be targeted with * Discover the AS in charge of the RS that is to be targeted with
a request. a request.
* Submit the token request (see step (A) of Figure 1). * Submit the token request (see step (A) of Figure 1).
+ Authenticate to the AS. + Authenticate to the AS.
+ Optionally (if not pre-configured): Specify which RS, which + Optionally (if not pre-configured): Specify which RS, which
resource(s), and which action(s) the request(s) will target. resource(s), and which action(s) the request(s) will target.
+ If raw public keys (rpk) or certificates are used, make sure + If raw public keys (rpk) or certificates are used, make sure
the AS has the right rpk or certificate for this client. the AS has the right rpk or certificate for this client.
* Process the access token and RS Information (see step (B) of * Process the access token and Access Information (see step (B)
Figure 1). of Figure 1).
+ Check that the RS Information provides the necessary + Check that the Access Information provides the necessary
security parameters (e.g., PoP key, information on security parameters (e.g., PoP key, information on
communication security protocols supported by the RS). communication security protocols supported by the RS).
* Send the token and request to the RS (see step (C) of * Send the token and request to the RS (see step (C) of
Figure 1). Figure 1).
+ Authenticate towards the RS (this could coincide with the + Authenticate towards the RS (this could coincide with the
proof of possession process). proof of possession process).
+ Transmit the token as specified by the AS (default is to the + Transmit the token as specified by the AS (default is to the
authz-info endpoint, alternative options are specified by authz-info endpoint, alternative options are specified by
profiles). profiles).
+ Perform the proof-of-possession procedure as specified by + Perform the proof-of-possession procedure as specified by
the profile in use (this may already have been taken care of the profile in use (this may already have been taken care of
skipping to change at page 56, line 7 skipping to change at page 56, line 27
In this scenario, the case where the resource server is offline is In this scenario, the case where the resource server is offline is
considered, i.e., it is not connected to the AS at the time of the considered, 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 access request. This access procedure involves steps A, B, C, and F
of Figure 1. of Figure 1.
Since the resource server must be able to verify the access token Since the resource server must be able to verify the access token
locally, self-contained access tokens must be used. locally, self-contained access tokens must be used.
This example shows the interactions between a client, the This example shows the interactions between a client, the
authorization server and a temperature sensor acting as a resource authorization server and a temperature sensor acting as a resource
server. Message exchanges A and B are shown in Figure 16. server. Message exchanges A and B are shown in Figure 17.
A: The client first generates a public-private key pair used for A: The client first generates a public-private key pair used for
communication security with the RS. communication security with the RS.
The client sends the POST request to the token endpoint at the AS. The client sends the POST request to the token endpoint at the AS.
The security of this request can be transport or application The security of this request can be transport or application
layer. It is up the the communication security profile to define. layer. It is up the the communication security profile to define.
In the example transport layer identification of the AS is done In the example transport layer identification of the AS is done
and the client identifies with client_id and client_secret as in and the client identifies with client_id and client_secret as in
classic OAuth. The request contains the public key of the client classic OAuth. The request contains the public key of the client
and the Audience parameter set to "tempSensorInLivingRoom", a and the Audience parameter set to "tempSensorInLivingRoom", a
value that the temperature sensor identifies itself with. The AS value that the temperature sensor identifies itself with. The AS
evaluates the request and authorizes the client to access the evaluates the request and authorizes the client to access the
resource. resource.
B: The AS responds with a PoP access token and RS Information. B: The AS responds with a PoP access token and Access Information.
The PoP access token contains the public key of the client, and The PoP access token contains the public key of the client, and
the RS Information contains the public key of the RS. For the Access Information contains the public key of the RS. For
communication security this example uses DTLS RawPublicKey between communication security this example uses DTLS RawPublicKey between
the client and the RS. The issued token will have a short the client and the RS. The issued token will have a short
validity time, i.e., "exp" close to "iat", to protect the RS from validity time, i.e., "exp" close to "iat", to protect the RS from
replay attacks. The token includes the claim such as "scope" with replay attacks. The token includes the claim such as "scope" with
the authorized access that an owner of the temperature device can the authorized access that an owner of the temperature device can
enjoy. In this example, the "scope" claim, issued by the AS, enjoy. In this example, the "scope" claim, issued by the AS,
informs the RS that the owner of the token, that can prove the 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 possession of a key is authorized to make a GET request against
the /temperature resource and a POST request on the /firmware the /temperature resource and a POST request on the /firmware
resource. Note that the syntax and semantics of the scope claim resource. Note that the syntax and semantics of the scope claim
skipping to change at page 57, line 21 skipping to change at page 57, line 26
A: +-------->| Header: POST (Code=0.02) A: +-------->| Header: POST (Code=0.02)
| POST | Uri-Path:"token" | POST | Uri-Path:"token"
| | Content-Type: application/cbor | | Content-Type: application/cbor
| | Payload: <Request-Payload> | | Payload: <Request-Payload>
| | | |
B: |<--------+ Header: 2.05 Content B: |<--------+ Header: 2.05 Content
| 2.05 | Content-Type: application/cbor | 2.05 | Content-Type: application/cbor
| | Payload: <Response-Payload> | | Payload: <Response-Payload>
| | | |
Figure 16: Token Request and Response Using Client Credentials. Figure 17: Token Request and Response Using Client Credentials.
The information contained in the Request-Payload and the Response- The information contained in the Request-Payload and the Response-
Payload is shown in Figure 17. Note that a transport layer security Payload is shown in Figure 18. Note that a TLS/DTLS-based
based communication security profile is used in this example, communication security profile is used in this example. Hence, the
therefore the Content-Type is "application/cbor". Content-Type is "application/cbor".
Request-Payload : Request-Payload :
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"aud" : "tempSensorInLivingRoom", "aud" : "tempSensorInLivingRoom",
"client_id" : "myclient", "client_id" : "myclient",
"client_secret" : "qwerty" "client_secret" : "qwerty"
} }
Response-Payload : Response-Payload :
skipping to change at page 57, line 52 skipping to change at page 58, line 29
"COSE_Key" : { "COSE_Key" : {
"kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk',
"kty" : "EC", "kty" : "EC",
"crv" : "P-256", "crv" : "P-256",
"x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4',
"y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM'
} }
} }
} }
Figure 17: Request and Response Payload Details. Figure 18: Request and Response Payload Details.
The content of the access token is shown in Figure 18. The content of the access token is shown in Figure 19.
{ {
"aud" : "tempSensorInLivingRoom", "aud" : "tempSensorInLivingRoom",
"iat" : "1360189224", "iat" : "1360189224",
"exp" : "1360289224", "exp" : "1360289224",
"scope" : "temperature_g firmware_p", "scope" : "temperature_g firmware_p",
"cnf" : { "cnf" : {
"COSE_Key" : { "COSE_Key" : {
"kid" : b64'1Bg8vub9tLe1gHMzV76e8', "kid" : b64'1Bg8vub9tLe1gHMzV76e8',
"kty" : "EC", "kty" : "EC",
"crv" : "P-256", "crv" : "P-256",
"x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU',
"y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0'
} }
} }
} }
Figure 18: Access Token including Public Key of the Client. Figure 19: Access Token including Public Key of the Client.
Messages C and F are shown in Figure 19 - Figure 20. Messages C and F are shown in Figure 20 - Figure 21.
C: The client then sends the PoP access token to the authz-info C: The client then sends the PoP access token to the authz-info
endpoint at the RS. This is a plain CoAP request, i.e., no endpoint at the RS. This is a plain CoAP request, i.e., no
transport or application layer security between client and RS, transport or application layer security is used between client and
since the token is integrity protected between the AS and RS. The RS since the token is integrity protected between the AS and RS.
RS verifies that the PoP access token was created by a known and The RS verifies that the PoP access token was created by a known
trusted AS, is valid, and responds to the client. The RS caches and trusted AS, is valid, and has been issued to the client. The
the security context together with authorization information about RS caches the security context together with authorization
this client contained in the PoP access token. information about this client contained in the PoP access token.
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: SlAV32hkKG ... | | Payload: SlAV32hkKG ...
| | | |
|<--------+ Header: 2.04 Changed |<--------+ Header: 2.04 Changed
| 2.04 | | 2.04 |
| | | |
Figure 19: Access Token provisioning to RS Figure 20: Access Token provisioning to RS
The client and the RS runs the DTLS handshake using the raw public The client and the RS runs the DTLS handshake using the raw public
keys established in step B and C. keys established in step B and C.
The client sends the CoAP request GET to /temperature on RS over The client sends the CoAP request GET to /temperature on RS over
DTLS. The RS verifies that the request is authorized, based on DTLS. The RS verifies that the request is authorized, based on
previously established security context. previously established security context.
F: The RS responds with a resource representation over DTLS. F: The RS responds with a resource representation over DTLS.
Resource Resource
Client Server Client Server
| | | |
|<=======>| DTLS Connection Establishment |<=======>| DTLS Connection Establishment
| | using Raw Public Keys | | using Raw Public Keys
skipping to change at page 59, line 25 skipping to change at page 59, line 48
| | | |
+-------->| 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>
| | | |
Figure 20: Resource Request and Response protected by DTLS. Figure 21: Resource Request and Response protected by DTLS.
E.2. Introspection Aided Token Validation E.2. Introspection Aided Token Validation
In this deployment scenario it is assumed that a client is not able 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 to 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 assumed to be connected to the back-end infrastructure. Thus the RS
can make use of token introspection. This access procedure involves can make use of token introspection. This access procedure involves
steps A-F of Figure 1, but assumes steps A and B have been carried steps A-F of Figure 1, but assumes steps A and B have been carried
out during a phase when the client had connectivity to AS. out during a phase when the client had connectivity to AS.
skipping to change at page 59, line 48 skipping to change at page 60, line 26
Since the client is constrained, the token will not be self contained 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 (i.e. not a CWT) but instead just a reference. The resource server
uses its connectivity to learn about the claims associated to the uses its connectivity to learn about the claims associated to the
access token by using introspection, which is shown in the example access token by using introspection, which is shown in the example
below. below.
In the example interactions between an offline client (key fob), a RS In the example interactions between an offline client (key fob), a RS
(online lock), and an AS is shown. It is assumed that there is a (online lock), and an AS is shown. It is assumed that there is a
provisioning step where the client has access to the AS. This provisioning step where the client has access to the AS. This
corresponds to message exchanges A and B which are shown in corresponds to message exchanges A and B which are shown in
Figure 21. Figure 22.
Authorization consent from the resource owner can be pre-configured, Authorization consent from the resource owner can be pre-configured,
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, he buys a generic key that he
wants to use with the car. To authorize the key fob he connects it wants to use with the car. To authorize the key fob he connects it
to his computer that then provides the UI for the device. After that to his computer that then provides the UI for the device. After that
OAuth 2.0 implicit flow can used to authorize the key for his car at OAuth 2.0 implicit flow can used to authorize the key for his car at
the the car manufacturers AS. the the car manufacturers AS.
skipping to change at page 60, line 26 skipping to change at page 61, line 4
A: The client sends the request using POST to the token endpoint A: The client sends the request using POST to the token endpoint
at AS. The request contains the Audience parameter set to at AS. The request contains the Audience parameter set to
"PACS1337" (PACS, Physical Access System), a value the that the "PACS1337" (PACS, Physical Access System), a value the that the
online door in question identifies itself with. The AS generates online door in question identifies itself with. The AS generates
an access token as an opaque string, which it can match to the an access token as an opaque string, which it can match to the
specific client, a targeted audience and a symmetric key. The specific client, a targeted audience and a symmetric key. The
security is provided by identifying the AS on transport layer security is provided by identifying the AS on transport layer
using a pre shared security context (psk, rpk or certificate) and using a pre shared security context (psk, rpk or certificate) and
then the client is identified using client_id and client_secret as then the client is identified using client_id and client_secret as
in classic OAuth. in classic OAuth.
B: The AS responds with the an access token and RS Information,
the latter containing a symmetric key. Communication security B: The AS responds with the an access token and Access
between C and RS will be DTLS and PreSharedKey. The PoP key is Information, the latter containing a symmetric key. Communication
used as the PreSharedKey. security between C and RS will be DTLS and PreSharedKey. The PoP
key is used as the PreSharedKey.
Authorization Authorization
Client Server Client Server
| | | |
| | | |
A: +-------->| Header: POST (Code=0.02) A: +-------->| Header: POST (Code=0.02)
| POST | Uri-Path:"token" | POST | Uri-Path:"token"
| | Content-Type: application/cbor | | Content-Type: application/cbor
| | Payload: <Request-Payload> | | Payload: <Request-Payload>
| | | |
B: |<--------+ Header: 2.05 Content B: |<--------+ Header: 2.05 Content
| | Content-Type: application/cbor | | Content-Type: application/cbor
| 2.05 | Payload: <Response-Payload> | 2.05 | Payload: <Response-Payload>
| | | |
Figure 21: Token Request and Response using Client Credentials. Figure 22: Token Request and Response using Client Credentials.
The information contained in the Request-Payload and the Response- The information contained in the Request-Payload and the Response-
Payload is shown in Figure 22. Payload is shown in Figure 23.
Request-Payload: Request-Payload:
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"aud" : "lockOfDoor4711", "aud" : "lockOfDoor4711",
"client_id" : "keyfob", "client_id" : "keyfob",
"client_secret" : "qwerty" "client_secret" : "qwerty"
} }
Response-Payload: Response-Payload:
skipping to change at page 61, line 28 skipping to change at page 62, line 28
"cnf" : { "cnf" : {
"COSE_Key" : { "COSE_Key" : {
"kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk',
"kty" : "oct", "kty" : "oct",
"alg" : "HS256", "alg" : "HS256",
"k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE'
} }
} }
} }
Figure 22: Request and Response Payload for C offline Figure 23: Request and Response Payload for C offline
The access token in this case is just an opaque string referencing The access token in this case is just an opaque string referencing
the authorization information at the AS. the authorization information at the AS.
C: Next, the client POSTs the access token to the authz-info C: Next, the client POSTs the access token to the authz-info
endpoint in the RS. This is a plain CoAP request, i.e., no DTLS 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, the between client and RS. Since the token is an opaque string, the
RS cannot verify it on its own, and thus defers to respond the RS cannot verify it on its own, and thus defers to respond the
client with a status code until after step E. client with a status code until after step E.
D: The RS forwards the token to the introspection endpoint on the D: The RS forwards the token to the introspection endpoint on the
skipping to change at page 62, line 30 skipping to change at page 63, line 30
| | | | | |
| E: |<---------+ Header: 2.05 Content | E: |<---------+ Header: 2.05 Content
| | 2.05 | Content-Type: "application/cbor" | | 2.05 | Content-Type: "application/cbor"
| | | Payload: <Response-Payload> | | | Payload: <Response-Payload>
| | | | | |
| | | |
|<--------+ Header: 2.01 Created |<--------+ Header: 2.01 Created
| 2.01 | | 2.01 |
| | | |
Figure 23: Token Introspection for C offline Figure 24: Token Introspection for C offline
The information contained in the Request-Payload and the Response- The information contained in the Request-Payload and the Response-
Payload is shown in Figure 24. Payload is shown in Figure 25.
Request-Payload: Request-Payload:
{ {
"token" : b64'SlAV32hkKG...', "token" : b64'SlAV32hkKG...',
"client_id" : "FrontDoor", "client_id" : "FrontDoor",
"client_secret" : "ytrewq" "client_secret" : "ytrewq"
} }
Response-Payload: Response-Payload:
{ {
"active" : true, "active" : true,
"aud" : "lockOfDoor4711", "aud" : "lockOfDoor4711",
"scope" : "open, close", "scope" : "open, close",
"iat" : 1311280970, "iat" : 1311280970,
"cnf" : { "cnf" : {
"kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' "kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...'
} }
} }
Figure 24: Request and Response Payload for Introspection Figure 25: Request and Response Payload for Introspection
The client uses the symmetric PoP key to establish a DTLS 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 sent to the uri-path /state on the RS, changing the state of the
door to locked. door to locked.
F: The RS responds with a appropriate over the secure DTLS F: The RS responds with a appropriate over the secure DTLS
channel. channel.
Resource Resource
Client Server Client Server
skipping to change at page 63, line 26 skipping to change at page 64, line 26
| | 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>
| | | |
Figure 25: Resource request and response protected by OSCORE Figure 26: Resource request and response protected by OSCORE
Appendix F. Document Updates Appendix F. Document Updates
RFC EDITOR: PLEASE REMOVE THIS SECTION. RFC EDITOR: PLEASE REMOVE THIS SECTION.
F.1. Version -11 to -12 F.1. Version -12 to -13
o Changed "Resource Information" to "Access Information" to avoid
confusion.
o Clarified section about AS discovery.
o Editorial changes
F.2. Version -11 to -12
o Moved the Request error handling to a section of its own. o Moved the Request error handling to a section of its own.
o Require the use of the abbreviation for profile identifiers. o Require the use of the abbreviation for profile identifiers.
o Added rs_cnf parameter in the introspection response, to inform o Added rs_cnf parameter in the introspection response, to inform
RS' with several RPKs on which key to use. RS' with several RPKs on which key to use.
o Allowed use of rs_cnf as claim in the access token in order to o Allowed use of rs_cnf as claim in the access token in order to
inform an RS with several RPKs on which key to use. inform an RS with several RPKs on which key to use.
o Clarified that profiles must specify if/how error responses are o Clarified that profiles must specify if/how error responses are
protected. protected.
o Fixed label number range to align with COSE/CWT. o Fixed label number range to align with COSE/CWT.
o Clarified the requirements language in order to allow profiles to o Clarified the requirements language in order to allow profiles to
specify other payload formats than CBOR if they do not use CoAP. specify other payload formats than CBOR if they do not use CoAP.
F.2. Version -10 to -11 F.3. Version -10 to -11
o Fixed some CBOR data type errors. o Fixed some CBOR data type errors.
o Updated boilerplate text o Updated boilerplate text
F.3. Version -09 to -10 F.4. Version -09 to -10
o Removed CBOR major type numbers. o Removed CBOR major type numbers.
o Removed the client token design. o Removed the client token design.
o Rephrased to clarify that other protocols than CoAP can be used. o Rephrased to clarify that other protocols than CoAP can be used.
o Clarifications regarding the use of HTTP o Clarifications regarding the use of HTTP
F.4. Version -08 to -09 F.5. Version -08 to -09
o Allowed scope to be byte arrays. o Allowed scope to be byte arrays.
o Defined default names for endpoints. o Defined default names for endpoints.
o Refactored the IANA section for briefness and consistency. o Refactored the IANA section for briefness and consistency.
o Refactored tables that define IANA registry contents for o Refactored tables that define IANA registry contents for
consistency. consistency.
o Created IANA registry for CBOR mappings of error codes, grant o Created IANA registry for CBOR mappings of error codes, grant
types and Authorization Server Information. types and Authorization Server Information.
o Added references to other document sections defining IANA entries o Added references to other document sections defining IANA entries
in the IANA section. in the IANA section.
F.5. Version -07 to -08 F.6. Version -07 to -08
o Moved AS discovery from the DTLS profile to the framework, see o Moved AS discovery from the DTLS profile to the framework, see
Section 5.1. Section 5.1.
o Made the use of CBOR mandatory. If you use JSON you can use o Made the use of CBOR mandatory. If you use JSON you can use
vanilla OAuth. vanilla OAuth.
o Made it mandatory for profiles to specify C-AS security and RS-AS o Made it mandatory for profiles to specify C-AS security and RS-AS
security (the latter only if introspection is supported). security (the latter only if introspection is supported).
o Made the use of CBOR abbreviations mandatory. o Made the use of CBOR abbreviations mandatory.
o Added text to clarify the use of token references as an o Added text to clarify the use of token references as an
alternative to CWTs. alternative to CWTs.
skipping to change at page 64, line 48 skipping to change at page 66, line 4
discovery information, combining profiles and leakage through discovery information, combining profiles and leakage through
error responses. error responses.
o Added privacy considerations about leakage through unprotected AS o Added privacy considerations about leakage through unprotected AS
discovery. discovery.
o Added text that clarifies that introspection is optional. o Added text that clarifies that introspection is optional.
o Made profile parameter optional since it can be implicit. o Made profile parameter optional since it can be implicit.
o Clarified that CoAP is not mandatory and other protocols can be o Clarified that CoAP is not mandatory and other protocols can be
used. used.
o Clarified the design justification for specific features of the o Clarified the design justification for specific features of the
framework in appendix A. framework in appendix A.
o Clarified appendix E.2. o Clarified appendix E.2.
o Removed specification of the "cnf" claim for CBOR/COSE, and o Removed specification of the "cnf" claim for CBOR/COSE, and
replaced with references to [I-D.ietf-ace-cwt-proof-of-possession] replaced with references to [I-D.ietf-ace-cwt-proof-of-possession]
F.6. Version -06 to -07 F.7. Version -06 to -07
o Various clarifications added. o Various clarifications added.
o Fixed erroneous author email. o Fixed erroneous author email.
F.7. Version -05 to -06 F.8. Version -05 to -06
o Moved sections that define the ACE framework into a subsection of o Moved sections that define the ACE framework into a subsection of
the framework Section 5. the framework Section 5.
o Split section on client credentials and grant into two separate o Split section on client credentials and grant into two separate
sections, Section 5.2, and Section 5.3. sections, Section 5.2, and Section 5.3.
o Added Section 5.4 on AS authentication. o Added Section 5.4 on AS authentication.
o Added Section 5.5 on the Authorization endpoint. o Added Section 5.5 on the Authorization endpoint.
F.8. Version -04 to -05 F.9. Version -04 to -05
o Added RFC 2119 language to the specification of the required o Added RFC 2119 language to the specification of the required
behavior of profile specifications. behavior of profile specifications.
o Added Section 5.3 on the relation to the OAuth2 grant types. o Added Section 5.3 on the relation to the OAuth2 grant types.
o Added CBOR abbreviations for error and the error codes defined in o Added CBOR abbreviations for error and the error codes defined in
OAuth2. OAuth2.
o Added clarification about token expiration and long-running o Added clarification about token expiration and long-running
requests in Section 5.8.3 requests in Section 5.8.3
o Added security considerations about tokens with symmetric pop keys o Added security considerations about tokens with symmetric pop keys
valid for more than one RS. valid for more than one RS.
o Added privacy considerations section. o Added privacy considerations section.
o Added IANA registry mapping the confirmation types from RFC 7800 o Added IANA registry mapping the confirmation types from RFC 7800
to equivalent COSE types. to equivalent COSE types.
o Added appendix D, describing assumptions about what the AS knows o Added appendix D, describing assumptions about what the AS knows
about the client and the RS. about the client and the RS.
F.9. Version -03 to -04 F.10. Version -03 to -04
o Added a description of the terms "framework" and "profiles" as o Added a description of the terms "framework" and "profiles" as
used in this document. used in this document.
o Clarified protection of access tokens in section 3.1. o Clarified protection of access tokens in section 3.1.
o Clarified uses of the "cnf" parameter in section 6.4.5. o Clarified uses of the "cnf" parameter in section 6.4.5.
o Clarified intended use of Client Token in section 7.4. o Clarified intended use of Client Token in section 7.4.
F.10. Version -02 to -03 F.11. Version -02 to -03
o Removed references to draft-ietf-oauth-pop-key-distribution since o Removed references to draft-ietf-oauth-pop-key-distribution since
the status of this draft is unclear. the status of this draft is unclear.
o Copied and adapted security considerations from draft-ietf-oauth- o Copied and adapted security considerations from draft-ietf-oauth-
pop-key-distribution. pop-key-distribution.
o Renamed "client information" to "RS information" since it is o Renamed "client information" to "RS information" since it is
information about the RS. information about the RS.
o Clarified the requirements on profiles of this framework. o Clarified the requirements on profiles of this framework.
o Clarified the token endpoint protocol and removed negotiation of o Clarified the token endpoint protocol and removed negotiation of
"profile" and "alg" (section 6). "profile" and "alg" (section 6).
o Renumbered the abbreviations for claims and parameters to get a o Renumbered the abbreviations for claims and parameters to get a
consistent numbering across different endpoints. consistent numbering across different endpoints.
o Clarified the introspection endpoint. o Clarified the introspection endpoint.
o Renamed token, introspection and authz-info to "endpoint" instead o Renamed token, introspection and authz-info to "endpoint" instead
of "resource" to mirror the OAuth 2.0 terminology. of "resource" to mirror the OAuth 2.0 terminology.
o Updated the examples in the appendices. o Updated the examples in the appendices.
F.11. Version -01 to -02 F.12. Version -01 to -02
o Restructured to remove communication security parts. These shall o Restructured to remove communication security parts. These shall
now be defined in profiles. now be defined in profiles.
o Restructured section 5 to create new sections on the OAuth o Restructured section 5 to create new sections on the OAuth
endpoints token, introspection and authz-info. endpoints token, introspection and authz-info.
o Pulled in material from draft-ietf-oauth-pop-key-distribution in o Pulled in material from draft-ietf-oauth-pop-key-distribution in
order to define proof-of-possession key distribution. order to define proof-of-possession key distribution.
o Introduced the "cnf" parameter as defined in RFC7800 to reference o Introduced the "cnf" parameter as defined in RFC7800 to reference
or transport keys used for proof of possession. or transport keys used for proof of possession.
o Introduced the "client-token" to transport client information from o Introduced the "client-token" to transport client information from
the AS to the client via the RS in conjunction with introspection. the AS to the client via the RS in conjunction with introspection.
o Expanded the IANA section to define parameters for token request, o Expanded the IANA section to define parameters for token request,
introspection and CWT claims. introspection and CWT claims.
o Moved deployment scenarios to the appendix as examples. o Moved deployment scenarios to the appendix as examples.
F.12. Version -00 to -01 F.13. Version -00 to -01
o Changed 5.1. from "Communication Security Protocol" to "Client o Changed 5.1. from "Communication Security Protocol" to "Client
Information". Information".
o Major rewrite of 5.1 to clarify the information exchanged between o Major rewrite of 5.1 to clarify the information exchanged between
C and AS in the PoP access token request profile for IoT. C and AS in the PoP access token request profile for IoT.
* Allow the client to indicate preferences for the communication * Allow the client to indicate preferences for the communication
security protocol. security protocol.
* Defined the term "Client Information" for the additional * Defined the term "Client Information" for the additional
information returned to the client in addition to the access information returned to the client in addition to the access
skipping to change at page 68, line 5 skipping to change at page 69, line 5
Email: erik@wahlstromstekniska.se Email: erik@wahlstromstekniska.se
Samuel Erdtman Samuel Erdtman
Spotify AB Spotify AB
Birger Jarlsgatan 61, 4tr Birger Jarlsgatan 61, 4tr
Stockholm 113 56 Stockholm 113 56
Sweden Sweden
Email: erdtman@spotify.com Email: erdtman@spotify.com
Hannes Tschofenig Hannes Tschofenig
ARM Ltd. Arm Ltd.
Hall in Tirol 6060 Absam 6067
Austria Austria
Email: Hannes.Tschofenig@arm.com Email: Hannes.Tschofenig@arm.com
 End of changes. 105 change blocks. 
188 lines changed or deleted 198 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/