draft-ietf-ace-oauth-authz-09.txt   draft-ietf-ace-oauth-authz-10.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: May 20, 2018 Ericsson Expires: August 17, 2018 Ericsson
E. Wahlstroem E. Wahlstroem
(no affiliation)
S. Erdtman S. Erdtman
Spotify AB Spotify AB
H. Tschofenig H. Tschofenig
ARM Ltd. ARM Ltd.
November 16, 2017 February 13, 2018
Authentication and Authorization for Constrained Environments (ACE) Authentication and Authorization for Constrained Environments (ACE)
draft-ietf-ace-oauth-authz-09 draft-ietf-ace-oauth-authz-10
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. The authorization in Internet of Things (IoT) environments. The
framework is based on a set of building blocks including OAuth 2.0 framework is based on a set of building blocks including OAuth 2.0
and CoAP, thus making a well-known and widely used authorization and CoAP, thus making a well-known and widely used authorization
solution suitable for IoT devices. Existing specifications are used solution suitable for IoT devices. Existing specifications are used
where possible, but where the constraints of IoT devices require it, where possible, but where the constraints of IoT devices require it,
extensions are added and profiles are defined. extensions are added and profiles are defined.
skipping to change at page 1, line 43 skipping to change at page 1, line 43
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 May 20, 2018. This Internet-Draft will expire on August 17, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 26 skipping to change at page 2, line 26
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
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 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.1. Discovering Authorization Servers . . . . . . . . . . . . 14 5.1. Discovering Authorization Servers . . . . . . . . . . . . 14
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 . . . . . . . . . . . . . . . . . . . 15
5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17
5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 17 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 . . . . . . . . . . . . . . . . 21 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 . . . . . . . . . . . 24 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 . . . . . . . . . . . . . . . . . . . 25 5.6.4.3. Token Type . . . . . . . . . . . . . . . . . . . 26
5.6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 25 5.6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 26
5.6.4.5. Confirmation . . . . . . . . . . . . . . . . . . 26 5.6.4.5. Confirmation . . . . . . . . . . . . . . . . . . 26
5.6.5. Mapping parameters to CBOR . . . . . . . . . . . . . 26 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 27
5.7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 27 5.7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 28
5.7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 28 5.7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 29
5.7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 28 5.7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 29
5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 29 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 30
5.7.4. Client Token . . . . . . . . . . . . . . . . . . . . 30 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 31
5.7.5. Mapping Introspection parameters to CBOR . . . . . . 32
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 . . . . . . 32
5.8.2. Token Expiration . . . . . . . . . . . . . . . . . . 34 5.8.2. Token Expiration . . . . . . . . . . . . . . . . . . 33
6. Security Considerations . . . . . . . . . . . . . . . . . . . 34 6. Security Considerations . . . . . . . . . . . . . . . . . . . 34
6.1. Unprotected AS Information . . . . . . . . . . . . . . . 36 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 35
6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 36 6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 35
6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 36 6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 35
6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 36 6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 36
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 36
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37
8.1. Authorization Server Information . . . . . . . . . . . . 37 8.1. Authorization Server Information . . . . . . . . . . . . 37
8.2. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 38 8.2. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 37
8.3. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 38 8.3. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 38
8.4. OAuth Access Token Types . . . . . . . . . . . . . . . . 39 8.4. OAuth Access Token Types . . . . . . . . . . . . . . . . 38
8.5. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 39 8.5. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 38
8.5.1. Initial Registry Contents . . . . . . . . . . . . . . 40 8.5.1. Initial Registry Contents . . . . . . . . . . . . . . 39
8.6. ACE OAuth Profile Registry . . . . . . . . . . . . . . . 40 8.6. ACE OAuth Profile Registry . . . . . . . . . . . . . . . 39
8.7. OAuth Parameter Registration . . . . . . . . . . . . . . 40 8.7. OAuth Parameter Registration . . . . . . . . . . . . . . 39
8.8. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 41 8.8. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 40
8.9. OAuth Introspection Response Parameter Registration . . . 41 8.9. OAuth Introspection Response Parameter Registration . . . 41
8.10. Introspection Endpoint CBOR Mappings Registry . . . . . . 42 8.10. Introspection Endpoint CBOR Mappings Registry . . . . . . 41
8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 42 8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 42
8.12. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 42 8.12. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 42
8.13. CoAP Option Number Registration . . . . . . . . . . . . . 43 8.13. CoAP Option Number Registration . . . . . . . . . . . . . 42
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 43
10.1. Normative References . . . . . . . . . . . . . . . . . . 44 10.1. Normative References . . . . . . . . . . . . . . . . . . 43
10.2. Informative References . . . . . . . . . . . . . . . . . 44 10.2. Informative References . . . . . . . . . . . . . . . . . 44
Appendix A. Design Justification . . . . . . . . . . . . . . . . 47 Appendix A. Design Justification . . . . . . . . . . . . . . . . 46
Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 51 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 50
Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 53 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 52
Appendix D. Assumptions on AS knowledge about C and RS . . . . . 54 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 53
Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 54 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 53
E.1. Local Token Validation . . . . . . . . . . . . . . . . . 54 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 53
E.2. Introspection Aided Token Validation . . . . . . . . . . 58 E.2. Introspection Aided Token Validation . . . . . . . . . . 57
Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 62 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 61
F.1. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 62 F.1. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 61
F.2. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 62 F.2. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 61
F.3. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 63 F.3. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 62
F.4. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 63 F.4. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 62
F.5. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 63 F.5. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 62
F.6. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 64 F.6. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 62
F.7. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 64 F.7. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 63
F.8. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 64 F.8. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 63
F.9. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 64 F.9. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 63
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 65 F.10. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 64
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64
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 23 skipping to change at page 5, line 23
definition, which is to denote resources such as token and definition, which is to denote resources such as token and
introspection at the AS and authz-info at the RS (see Section 5.8.1 introspection at the AS and authz-info at the RS (see Section 5.8.1
for a definition of the authz-info endpoint). The CoAP [RFC7252] for a definition of the authz-info endpoint). The CoAP [RFC7252]
definition, which is "An entity participating in the CoAP protocol" definition, which is "An entity participating in the CoAP protocol"
is not used in this specification. is not used in this specification.
Since this specification focuses on the problem of access control to Since this specification focuses on the problem of access control to
resources, the actors has been simplified by assuming that the client resources, the actors has been simplified by assuming that the client
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 "RS Information" for parameters describing
characteristics of the RS (e.g. public key) that the AS provides to characteristics of the RS (e.g. public key) that the AS provides to
the client. the client.
skipping to change at page 6, line 16 skipping to change at page 6, line 16
[RFC7159] is not sufficiently compact. CBOR is a binary encoding [RFC7159] is not sufficiently compact. CBOR is a binary encoding
designed for small code and message size, which may be used for designed for small code and message size, which may be used for
encoding of self contained tokens, and also for encoding payload encoding of self contained tokens, and also for encoding payload
transferred in protocol messages. transferred in protocol messages.
A fourth building block is the compact CBOR-based secure message A fourth building block is the compact CBOR-based secure message
format COSE [RFC8152], which enables application layer security as an format COSE [RFC8152], which enables application layer security as an
alternative or complement to transport layer security (DTLS [RFC6347] alternative or complement to transport layer security (DTLS [RFC6347]
or TLS [RFC5246]). COSE is used to secure self-contained tokens such or TLS [RFC5246]). COSE is used to secure self-contained tokens such
as proof-of-possession (PoP) tokens, which is an extension to the as proof-of-possession (PoP) tokens, which is an extension to the
OAuth tokens, and "client tokens" which are defined in this framework OAuth tokens. The default token format is defined in CBOR web token
(see Section 5.7.4). The default token format is defined in CBOR web (CWT) [I-D.ietf-ace-cbor-web-token]. Application layer security for
token (CWT) [I-D.ietf-ace-cbor-web-token]. Application layer CoAP using COSE can be provided with OSCOAP
security for CoAP using COSE can be provided with OSCOAP
[I-D.ietf-core-object-security]. [I-D.ietf-core-object-security].
With the building blocks listed above, solutions satisfying various With the building blocks listed above, solutions satisfying various
IoT device and network constraints are possible. A list of IoT device and network constraints are possible. A list of
constraints is described in detail in RFC 7228 [RFC7228] and a constraints is described in detail in RFC 7228 [RFC7228] and a
description of how the building blocks mentioned above relate to the description of how the building blocks mentioned above relate to the
various constraints can be found in Appendix A. various constraints can be found in Appendix A.
Luckily, not every IoT device suffers from all constraints. The ACE Luckily, not every IoT device suffers from all constraints. The ACE
framework nevertheless takes all these aspects into account and framework nevertheless takes all these aspects into account and
skipping to change at page 10, line 32 skipping to change at page 10, line 32
[I-D.ietf-oauth-device-flow]). What grant types works best depends [I-D.ietf-oauth-device-flow]). What grant types works best depends
on the usage scenario and RFC 7744 [RFC7744] describes many different on the usage scenario and RFC 7744 [RFC7744] describes many different
IoT use cases but there are two preferred grant types, namely the IoT use cases but there are two preferred grant types, namely the
Authorization Code Grant (described in Section 4.1 of [RFC7521]) and Authorization Code Grant (described in Section 4.1 of [RFC7521]) and
the Client Credentials Grant (described in Section 4.4 of [RFC7521]). the Client Credentials Grant (described in Section 4.4 of [RFC7521]).
The Authorization Code Grant is a good fit for use with apps running The Authorization Code Grant is a good fit for use with apps running
on smart phones and tablets that request access to IoT devices, a on smart phones and tablets that request access to IoT devices, a
common scenario in the smart home environment, where users need to go common scenario in the smart home environment, where users need to go
through an authentication and authorization phase (at least during through an authentication and authorization phase (at least during
the initial setup phase). The native apps guidelines described in the initial setup phase). The native apps guidelines described in
[I-D.ietf-oauth-native-apps] are applicable to this use case. The [RFC8252] are applicable to this use case. The Client Credential
Client Credential Grant is a good fit for use with IoT devices where Grant is a good fit for use with IoT devices where the OAuth client
the OAuth client itself is constrained. In such a case, the resource itself is constrained. In such a case, the resource owner has pre-
owner has pre-arranged access rights for the client with the arranged access rights for the client with the authorization server,
authorization server, which is often accomplished using a which is often accomplished using a commissioning tool.
commissioning tool.
The consent of the resource owner, for giving a client access to a The consent of the resource owner, for giving a client access to a
protected resource, can be provided dynamically as in the traditional protected resource, can be provided dynamically as in the traditional
OAuth flows, or it could be pre-configured by the resource owner as OAuth flows, or it could be pre-configured by the resource owner as
authorization policies at the AS, which the AS evaluates when a token authorization policies at the AS, which the AS evaluates when a token
request arrives. The resource owner and the requesting party (i.e., request arrives. The resource owner and the requesting party (i.e.,
client owner) are not shown in Figure 1. client owner) are not shown in Figure 1.
This framework supports a wide variety of communication security This framework supports a wide variety of communication security
mechanisms between the ACE entities, such as client, AS, and RS. It mechanisms between the ACE entities, such as client, AS, and RS. It
skipping to change at page 11, line 42 skipping to change at page 11, line 41
+--------+ +---------------+ +--------+ +---------------+
| |---(A)-- Token Request ------->| | | |---(A)-- Token Request ------->| |
| | | Authorization | | | | Authorization |
| |<--(B)-- Access Token ---------| Server | | |<--(B)-- Access Token ---------| Server |
| | + RS Information | | | | + RS Information | |
| | +---------------+ | | +---------------+
| | ^ | | | ^ |
| | Introspection Request (D)| | | | Introspection Request (D)| |
| Client | (optional) | | | Client | (optional) | |
| | Response + Client Token | |(E) | | Response | |(E)
| | (optional) | v | | (optional) | v
| | +--------------+ | | +--------------+
| |---(C)-- Token + Request ----->| | | |---(C)-- Token + Request ----->| |
| | | Resource | | | | Resource |
| |<--(F)-- Protected Resource ---| Server | | |<--(F)-- Protected Resource ---| Server |
| | | | | | | |
+--------+ +--------------+ +--------+ +--------------+
Figure 1: Basic Protocol Flow. Figure 1: Basic Protocol Flow.
Requesting an Access Token (A): Requesting an Access Token (A):
skipping to change at page 12, line 42 skipping to change at page 12, line 42
(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 RS 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 or the client obtained in the access token or the RS Information. The RS
token. The RS verifies that the token is integrity protected by verifies that the token is integrity protected by the AS and
the AS and compares the claims contained in the access token with compares the claims contained in the access token with the
the resource request. If the RS is online, validation can be resource request. If the RS is online, validation can be handed
handed over to the AS using token introspection (see messages D over to the AS using token introspection (see messages D and E)
and E) over HTTP or CoAP, in which case the different parts of over HTTP or CoAP.
step C may be interleaved with introspection.
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
for HTTP in [RFC7662]. for HTTP in [RFC7662].
Note that token introspection is an optional step and can be Note that token introspection is an optional step and can be
omitted if the token is self-contained and the resource server is omitted if the token is self-contained and the resource server is
prepared to perform the token validation on its own. prepared to perform the token validation on its own.
Token Introspection Response (E): Token Introspection Response (E):
skipping to change at page 13, line 19 skipping to change at page 13, line 18
for HTTP in [RFC7662]. for HTTP in [RFC7662].
Note that token introspection is an optional step and can be Note that token introspection is an optional step and can be
omitted if the token is self-contained and the resource server is omitted if the token is self-contained and the resource server is
prepared to perform the token validation on its own. prepared to perform the token validation on its own.
Token Introspection Response (E): Token Introspection Response (E):
The AS validates the token and returns the most recent parameters, The AS validates the token and returns the most recent parameters,
such as scope, audience, validity etc. associated with it back to such as scope, audience, validity etc. associated with it back to
the RS. The RS then uses the received parameters to process the the RS. The RS then uses the received parameters to process the
request to either accept or to deny it. The AS can additionally request to either accept or to deny it.
return information that the RS needs to pass on to the client in
the form of a client token. The latter is used to establish keys
for mutual authentication between client and RS, when the client
has no direct connectivity to the AS, see Section 5.7.4 for
details.
Protected Resource (F): Protected Resource (F):
If the request from the client is authorized, the RS fulfills the If the request from the client is authorized, the RS fulfills the
request and returns a response with the appropriate response code. request and returns a response with the appropriate response code.
The RS uses the dynamically established keys to protect the The RS uses the dynamically established keys to protect the
response, according to used communication security protocol. response, according to used communication security protocol.
5. Framework 5. Framework
The following sections detail the profiling and extensions of OAuth The following sections detail the profiling and extensions of OAuth
skipping to change at page 16, line 19 skipping to change at page 16, line 11
the Unauthorized Resource Request message to RS's AS. The AS the Unauthorized Resource Request message to RS's AS. The AS
information is a set of attributes containing an absolute URI (see information is a set of attributes containing an absolute URI (see
Section 4.3 of [RFC3986]) that specifies the AS in charge of RS. Section 4.3 of [RFC3986]) that specifies the AS in charge of RS.
The message MAY also contain a nonce generated by RS to ensure The message MAY also contain a nonce generated by RS to ensure
freshness in case that the RS and AS do not have synchronized clocks. freshness in case that the RS and AS do not have synchronized clocks.
Figure 2 summarizes the parameters that may be part of the AS Figure 2 summarizes the parameters that may be part of the AS
Information. Information.
/-------+----------+-----------------\ /-------+----------+-------------\
| Name | CBOR Key | Major Type | | Name | CBOR Key | Value Type |
|-------+----------+-----------------| |-------+----------+-------------|
| AS | 0 | 3 (text string) | | AS | 0 | text string |
| nonce | 5 | 2 (byte string) | | nonce | 5 | byte string |
\-------+----------+-----------------/ \-------+----------+-------------/
Figure 2: AS Information parameters Figure 2: AS Information parameters
Figure 3 shows an example for an AS Information message payload using Figure 3 shows an example for an AS Information message payload using
CBOR [RFC7049] diagnostic notation, using the parameter names instead CBOR [RFC7049] diagnostic notation, using the parameter names instead
of the CBOR keys for better human readability. of the CBOR keys for better human readability.
4.01 Unauthorized 4.01 Unauthorized
Content-Format: application/ace+cbor Content-Format: application/ace+cbor
{AS: "coaps://as.example.com/token", {AS: "coaps://as.example.com/token",
skipping to change at page 18, line 43 skipping to change at page 18, line 40
5.6. The Token Endpoint 5.6. The Token Endpoint
In standard OAuth 2.0, the AS provides the token endpoint for In standard OAuth 2.0, the AS provides the token endpoint for
submitting access token requests. This framework extends the submitting access token requests. This framework extends the
functionality of the token endpoint, giving the AS the possibility to functionality of the token endpoint, giving the AS the possibility to
help the client and RS to establish shared keys or to exchange their help the client and RS to establish shared keys or to exchange their
public keys. Furthermore, this framework defines encodings using public keys. Furthermore, this framework defines encodings using
CBOR, as a substitute for JSON. CBOR, as a substitute for JSON.
The endpoint may, however, be exposed over HTTPS as in classical
OAuth or even other transports. A profile MUST define the details of
the mapping between the fields described below, and these transports.
If HTTPS is used, JSON or CBOR payloads may be supported. If JSON
payloads are used, the semantics of Section 4 of the OAuth 2.0
specification MUST be followed (with additions as described below).
If CBOR payload is supported, the semantics described below MUST be
followed.
For the AS to be able to issue a token, the client MUST be For the AS to be able to issue a token, the client MUST be
authenticated and present a valid grant for the scopes requested. authenticated and present a valid grant for the scopes requested.
Profiles of this framework MUST specify how the AS authenticates the Profiles of this framework MUST specify how the AS authenticates the
client and how the communication between client and AS is protected. client and how the communication between client and AS is protected.
The default name of this endpoint in an url-path is 'token', however The default name of this endpoint in an url-path is 'token', however
implementations are not required to use this name and can define implementations are not required to use this name and can define
their own instead. their own instead.
The figures of this section use CBOR diagnostic notation without the The figures of this section use CBOR diagnostic notation without the
integer abbreviations for the parameters or their values for integer abbreviations for the parameters or their values for
illustrative purposes. Note that implementations MUST use the illustrative purposes. Note that implementations MUST use the
skipping to change at page 19, line 8 skipping to change at page 19, line 15
Profiles of this framework MUST specify how the AS authenticates the Profiles of this framework MUST specify how the AS authenticates the
client and how the communication between client and AS is protected. client and how the communication between client and AS is protected.
The default name of this endpoint in an url-path is 'token', however The default name of this endpoint in an url-path is 'token', however
implementations are not required to use this name and can define implementations are not required to use this name and can define
their own instead. their own instead.
The figures of this section use CBOR diagnostic notation without the The figures of this section use CBOR diagnostic notation without the
integer abbreviations for the parameters or their values for integer abbreviations for the parameters or their values for
illustrative purposes. Note that implementations MUST use the illustrative purposes. Note that implementations MUST use the
integer abbreviations and the binary CBOR encoding. integer abbreviations and the binary CBOR encoding, if the CBOR
encoding is used.
5.6.1. Client-to-AS Request 5.6.1. Client-to-AS Request
The client sends a POST request to the token endpoint at the AS. The The client sends a POST request to the token endpoint at the AS. The
profile MUST specify the Content-Type and wrapping of the payload. profile MUST specify the Content-Type and wrapping of the payload.
The content of the request consists of the parameters specified in The content of the request consists of the parameters specified in
section 4 of the OAuth 2.0 specification [RFC6749], encoded as a CBOR Section 4 of the OAuth 2.0 specification [RFC6749].
map, where the "scope" parameter can additionally be formatted as a
byte array, in order to allow compact encoding of complex scope If CBOR is used then this parameter is encoded as a CBOR map, where
structures. the "scope" parameter can additionally be formatted as a byte array,
in order to allow compact encoding of complex scope structures.
When HTTP is used as a transport then the client makes a request to
the token endpoint by sending the parameters using the "application/
x-www-form-urlencoded" format with a character encoding of UTF-8 in
the HTTP request entity-body, as defined in RFC 6749.
In addition to these parameters, this framework defines the following In addition to these parameters, this framework defines the following
parameters for requesting an access token from a token endpoint: parameters for requesting an access token from a token endpoint:
aud aud:
OPTIONAL. Specifies the audience for which the client is OPTIONAL. Specifies the audience for which the client is
requesting an access token. If this parameter is missing, it is requesting an access token. If this parameter is missing, it is
assumed that the client and the AS have a pre-established assumed that the client and the AS have a pre-established
understanding of the audience that an access token should address. understanding of the audience that an access token should address.
If a client submits a request for an access token without If a client submits a request for an access token without
specifying an "aud" parameter, and the AS does not have an specifying an "aud" parameter, and the AS does not have an
implicit understanding of the "aud" value for this client, then implicit understanding of the "aud" value for this client, then
the AS MUST respond with an error message using a response code the AS MUST respond with an error message using a response code
equivalent to the CoAP response code 4.00 (Bad Request). equivalent to the CoAP response code 4.00 (Bad Request).
cnf cnf:
OPTIONAL. This field contains information about the key the OPTIONAL. This field contains information about the key the
client would like to bind to the access token for proof-of- client would like to bind to the access token for proof-of-
possession. It is RECOMMENDED that an AS reject a request possession. It is RECOMMENDED that an AS reject a request
containing a symmetric key value in the 'cnf' field, since the AS containing a symmetric key value in the 'cnf' field, since the AS
is expected to be able to generate better symmetric keys than a is expected to be able to generate better symmetric keys than a
potentially constrained client. See Section 5.6.4.5 for more potentially constrained client. See Section 5.6.4.5 for more
details on the formatting of the 'cnf' parameter. details on the formatting of the 'cnf' parameter.
The following examples illustrate different types of requests for The following examples illustrate different types of requests for
proof-of-possession tokens. proof-of-possession tokens.
Figure 5 shows a request for a token with a symmetric proof-of- Figure 5 shows a request for a token with a symmetric proof-of-
possession key. Note that in this example it is assumed that possession key. Note that in this example it is assumed that
transport layer communication security is used, therefore the transport layer communication security is used with a CBOR payload,
Content-Type is "application/cbor". The content is displayed in CBOR therefore the Content-Type is "application/cbor". The content is
diagnostic notation, without abbreviations for better readability. displayed in CBOR diagnostic notation, without abbreviations for
better readability.
Header: POST (Code=0.02) Header: POST (Code=0.02)
Uri-Host: "as.example.com" Uri-Host: "as.example.com"
Uri-Path: "token" Uri-Path: "token"
Content-Type: "application/cbor" Content-Type: "application/cbor"
Payload: Payload:
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"client_id" : "myclient", "client_id" : "myclient",
"aud" : "tempSensor4711" "aud" : "tempSensor4711"
skipping to change at page 21, line 7 skipping to change at page 21, line 36
"x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8',
"y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4'
} }
} }
} }
Figure 6: Example token request bound to an asymmetric key. Figure 6: Example token request bound to an asymmetric key.
Figure 7 shows a request for a token where a previously communicated Figure 7 shows a request for a token where a previously communicated
proof-of-possession key is only referenced. Note that a transport proof-of-possession key is only referenced. Note that a transport
layer based communication security profile is assumed in this layer based communication security profile with a CBOR payload is
example, therefore the Content-Type is "application/cbor". Also note assumed in this example, therefore the Content-Type is "application/
that the client performs a password based authentication in this cbor". Also note that the client performs a password based
example by submitting its client_secret (see section 2.3.1. of authentication in this example by submitting its client_secret (see
[RFC6749]). Section 2.3.1 of [RFC6749]).
Header: POST (Code=0.02) Header: POST (Code=0.02)
Uri-Host: "as.example.com" Uri-Host: "as.example.com"
Uri-Path: "token" Uri-Path: "token"
Content-Type: "application/cbor" Content-Type: "application/cbor"
Payload: Payload:
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"client_id" : "myclient", "client_id" : "myclient",
"client_secret" : "mysecret234", "client_secret" : "mysecret234",
skipping to change at page 21, line 47 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. It MUST The content of the successful reply is the RS Information. When
be encoded as CBOR map, containing parameters as specified in section using CBOR payloads, the content MUST be encoded as CBOR map,
5.1 of [RFC6749]. In addition to these parameters, the following containing parameters as specified in Section 5.1 of [RFC6749]. In
parameters are also part of a successful response: addition to these parameters, the following parameters are also part
of a successful response:
profile OPTIONAL. This indicates the profile that the client MUST profile:
use towards the RS. See Section 5.6.4.4 for the formatting of OPTIONAL. This indicates the profile that the client MUST use
this parameter. 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 client . If this parameter is absent, the AS assumes that the client
implicitly knows which profile to use towards the RS. implicitly knows which profile to use towards the RS.
cnf REQUIRED if the token type is "pop" and a symmetric key is used. cnf:
REQUIRED if the token type is "pop" and a symmetric key is used.
MUST NOT be present otherwise. This field contains the symmetric MUST NOT be present otherwise. This field contains the symmetric
proof-of-possession key the client is supposed to use. See proof-of-possession key the client is supposed to use. See
Section 5.6.4.5 for details on the use of this parameter. Section 5.6.4.5 for details on the use of this parameter.
rs_cnf OPTIONAL if the token type is "pop" and asymmetric keys are rs_cnf:
used. MUST NOT be present otherwise. This field contains OPTIONAL if the token type is "pop" and asymmetric keys are used.
information about the public key used by the RS to authenticate. MUST NOT be present otherwise. This field contains information
See Section 5.6.4.5 for details on the use of this parameter. If about the public key used by the RS to authenticate. See
this parameter is absent, the AS assumes that the client already Section 5.6.4.5 for details on the use of this parameter. If this
knows the public key of the RS. parameter is absent, the AS assumes that the client already knows
token_type OPTIONAL. By default implementations of this framework the public key of the RS.
SHOULD assume that the token_type is "pop". If a specific use token_type:
case requires another token_type (e.g., "Bearer") to be used then OPTIONAL. By default implementations of this framework SHOULD
this parameter is REQUIRED. assume that the token_type is "pop". If a specific use case
requires another token_type (e.g., "Bearer") to be used then this
parameter is REQUIRED.
Note that if CBOR Web Tokens [I-D.ietf-ace-cbor-web-token] are used, Note that if CBOR Web Tokens [I-D.ietf-ace-cbor-web-token] are used,
the access token can also contain a "cnf" claim the access token can also contain a "cnf" claim
[I-D.ietf-ace-cwt-proof-of-possession]. This claim is however [I-D.ietf-ace-cwt-proof-of-possession]. This claim is however
consumed by a different party. The access token is created by the AS consumed by a different party. The access token is created by the AS
and processed by the RS (and opaque to the client) whereas the RS and processed by the RS (and opaque to the client) whereas the RS
Information is created by the AS and processed by the client; it is Information is created by the AS and processed by the client; it is
never forwarded to the resource server. 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 RS
skipping to change at page 23, line 26 skipping to change at page 24, line 7
| 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: RS 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 is assumed in this example, therefore the Content-Type is security with CBOR encoding is assumed in this example, therefore the
"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:
{ {
"access_token" : b64'SlAV32hkKG ... "access_token" : b64'SlAV32hkKG ...
(remainder of CWT omitted for brevity; (remainder of CWT omitted for brevity;
CWT contains COSE_Key in the "cnf" claim)', CWT contains COSE_Key in the "cnf" claim)',
"profile" : "coap_dtls", "profile" : "coap_dtls",
"expires_in" : "3600", "expires_in" : "3600",
skipping to change at page 24, line 9 skipping to change at page 24, line 35
} }
} }
Figure 9: Example AS response with an access token bound to a Figure 9: Example AS response with an access token bound to a
symmetric key. symmetric key.
5.6.3. Error Response 5.6.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 5.2 of [RFC6749], with the following differences: Section 5.2 of [RFC6749], with the following differences:
o The Content-Type MUST be specified by the communication security o The Content-Type MUST be specified by the communication security
profile used between client and AS. The raw payload before being profile used between client and AS. The raw payload before being
processed by the communication security protocol MUST be encoded processed by the communication security protocol MUST be encoded
as a CBOR map. as a CBOR map.
o A response code equivalent to the CoAP code 4.00 (Bad Request) o A response code equivalent to the CoAP code 4.00 (Bad Request)
MUST be used for all error responses, except for invalid_client MUST be used for all error responses, except for invalid_client
where a response code equivalent to the CoAP code 4.01 where a response code equivalent to the CoAP code 4.01
(Unauthorized) MAY be used under the same conditions as specified (Unauthorized) MAY be used under the same conditions as specified
in section 5.2 of [RFC6749]. in Section 5.2 of [RFC6749].
o The parameters "error", "error_description" and "error_uri" MUST o The parameters "error", "error_description" and "error_uri" MUST
be abbreviated using the codes specified in Figure 12. be abbreviated using the codes specified in Figure 12, when a CBOR
encoding is used.
o The error code (i.e., value of the "error" parameter) MUST be o The error code (i.e., value of the "error" parameter) MUST be
abbreviated as specified in Figure 10. abbreviated as specified in Figure 10, when a CBOR encoding is
used.
/------------------------+----------\ /------------------------+----------\
| Name | CBOR Key | | Name | CBOR Key |
|------------------------+----------| |------------------------+----------|
| invalid_request | 0 | | invalid_request | 0 |
| invalid_client | 1 | | invalid_client | 1 |
| invalid_grant | 2 | | invalid_grant | 2 |
| unauthorized_client | 3 | | unauthorized_client | 3 |
| unsupported_grant_type | 4 | | unsupported_grant_type | 4 |
| invalid_scope | 5 | | invalid_scope | 5 |
skipping to change at page 25, line 8 skipping to change at page 25, line 36
5.6.4. Request and Response Parameters 5.6.4. Request and Response Parameters
This section provides more detail about the new parameters that can This section provides more detail about the new parameters that can
be used in access token requests and responses, as well as be used in access token requests and responses, as well as
abbreviations for more compact encoding of existing parameters and abbreviations for more compact encoding of existing parameters and
common parameter values. common parameter values.
5.6.4.1. Audience 5.6.4.1. Audience
This parameter specifies for which audience the client is requesting This parameter specifies for which audience the client is requesting
a token. It should be encoded as CBOR text string (major type 3). a token. The formatting and semantics of these strings are
The formatting and semantics of these strings are application application specific.
specific.
When encoded as a CBOR payload it is represented as a CBOR text
string.
5.6.4.2. Grant Type 5.6.4.2. Grant Type
The abbreviations in Figure 11 MUST be used in CBOR encodings instead The abbreviations in Figure 11 MUST be used in CBOR encodings instead
of the string values defined in [RFC6749]. of the string values defined in [RFC6749], if CBOR payloads are used.
/--------------------+----------+------------------------\ /--------------------+----------+------------------------\
| Name | CBOR Key | Original Specification | | Name | CBOR Key | Original Specification |
|--------------------+----------+------------------------| |--------------------+----------+------------------------|
| 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 |
\--------------------+----------+------------------------/ \--------------------+----------+------------------------/
skipping to change at page 25, line 39 skipping to change at page 26, line 27
The token_type parameter is defined in [RFC6749], allowing the AS to The token_type parameter is defined in [RFC6749], allowing 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 is performed MUST be specified by the
profiles. 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,
(major type 3). if a CBOR encoding is used.
In this framework token type "pop" MUST be assumed by default if the In this framework token type "pop" MUST be assumed by default if the
AS does not provide a different value. AS does not 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
skipping to change at page 26, line 17 skipping to change at page 27, line 4
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 RS 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
JSON then the formatting and semantics of the "cnf" claim specified
in RFC 7800 [RFC7800].
In addition to the use as a claim in a CWT, the "cnf" parameter is In addition to the use as a claim in a CWT, the "cnf" parameter is
used in the following contexts with the following meaning: used in the following contexts with the following meaning:
o In the token request C -> AS, to indicate the client's raw public o In the token request C -> AS, to indicate the client's raw public
key, or the key-identifier of a previously established key between key, or the key-identifier of a previously established key between
C and RS. C and RS.
o In the token response AS -> C, to indicate the symmetric key o In the token response AS -> C, to indicate the symmetric key
generated by the AS for proof-of-possession. generated by the AS for proof-of-possession.
o In the introspection response AS -> RS, to indicate the proof-of- o In the introspection response AS -> RS, to indicate the proof-of-
possession key bound to the introspected token. possession key bound to the introspected token.
o In the client token AS -> RS -> C, to indicate the proof-of-
possession key bound to the access token.
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.
5.6.5. Mapping parameters to CBOR 5.6.5. Mapping Parameters to CBOR
All OAuth parameters in access token requests and responses MUST be All OAuth parameters in access token requests and responses MUST be
mapped to CBOR types as specified in Figure 12, using the given mapped to CBOR types as specified in Figure 12, using the given
integer abbreviation for the key. integer abbreviation for the key, if a CBOR encoding is used.
Note that we have aligned these abbreviations with the claim Note that we have aligned these abbreviations with the claim
abbreviations defined in [I-D.ietf-ace-cbor-web-token]. abbreviations defined in [I-D.ietf-ace-cbor-web-token].
/-------------------+----------+---------------------\ /-------------------+----------+---------------------\
| Name | CBOR Key | Major Type | | Name | CBOR Key | Value Type |
|-------------------+----------+---------------------| |-------------------+----------+---------------------|
| aud | 3 | text string | | aud | 3 | text string |
| client_id | 8 | text string | | client_id | 8 | text string |
| client_secret | 9 | byte string | | client_secret | 9 | byte string |
| response_type | 10 | text string | | response_type | 10 | text string |
| redirect_uri | 11 | text string | | redirect_uri | 11 | text string |
| scope | 12 | text or byte string | | scope | 12 | text or byte string |
| state | 13 | text string | | state | 13 | text string |
| code | 14 | byte string | | code | 14 | byte string |
| error | 15 | text string | | error | 15 | text string |
skipping to change at page 28, line 26 skipping to change at page 29, line 26
5.7.1. RS-to-AS Request 5.7.1. RS-to-AS Request
The RS sends a POST request to the introspection endpoint at the AS, The RS sends a POST request to the introspection endpoint at the AS,
the profile MUST specify the Content-Type and wrapping of the the profile MUST specify the Content-Type and wrapping of the
payload. The payload MUST be encoded as a CBOR map with a "token" payload. The payload MUST be encoded as a CBOR map with a "token"
parameter containing either the access token or a reference to the parameter containing either the access token or a reference to the
token (e.g., the cti). Further optional parameters representing token (e.g., the cti). Further optional parameters representing
additional context that is known by the RS to aid the AS in its additional context that is known by the RS to aid the AS in its
response MAY be included. 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".
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"
skipping to change at page 29, line 7 skipping to change at page 30, line 7
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
CBOR map including with the same required and optional parameters as CBOR map including with the same required and optional parameters as
in section 2.2. of RFC 7662 [RFC7662] with the following additions: in 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.
client_token OPTIONAL. This parameter contains information that the
RS MUST pass on to the client. See Section 5.7.4 for more
details.
For example, Figure 14 shows an AS response to the introspection For example, Figure 14 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",
"client_token" : b64'2QPhg0OhAQo ...
(remainder of client token omitted for brevity)',
"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 14: 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, and the specification of the communication security profile, and the
content payload MUST be encoded as a CBOR map. content payload MUST be encoded as a CBOR map.
o If the credentials used by the RS are invalid the AS MUST respond o If the credentials used by the RS are invalid the AS MUST respond
with the response code equivalent to the CoAP code 4.01 with the response code equivalent to the CoAP code 4.01
(Unauthorized) and use the required and optional parameters from (Unauthorized) and use the required and optional parameters from
section 5.2 in RFC 6749 [RFC6749]. Section 5.2 in RFC 6749 [RFC6749].
o If the RS does not have the right to perform this introspection o If the RS does not have the right to perform this introspection
request, the AS MUST respond with a response code equivalent to request, the AS MUST respond with a response code equivalent to
the CoAP code 4.03 (Forbidden). In this case no payload is the CoAP code 4.03 (Forbidden). In this case no payload is
returned. returned.
o The parameters "error", "error_description" and "error_uri" MUST o The parameters "error", "error_description" and "error_uri" MUST
be abbreviated using the codes specified in Figure 12. be abbreviated using the codes specified in Figure 12.
o The error codes MUST be abbreviated using the codes specified in o The error codes MUST be abbreviated using the codes specified in
Figure 10. Figure 10.
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. Client Token 5.7.4. Mapping Introspection parameters to CBOR
In cases where the client has limited connectivity and needs to get
access to a previously unknown resource servers, this framework
suggests the following OPTIONAL approach: The client is pre-
configured with a long-term access token, which is not self-contained
(i.e. it is only a reference to a token at the AS) when it is
commissioned. When the client then tries to access a RS it transmits
this access token. The RS then performs token introspection to learn
what access this token grants. In the introspection response, the AS
also relays information for the client, such as the proof-of-
possession key, through the RS. The RS passes on this Client Token
to the client in response to the submission of the token.
The client_token parameter is designed to carry such information, and
is intended to be used as described in Figure 15.
Resource Authorization
Client Server Server
| | |
| | |
C: +--------------->| |
| POST | |
| Access Token | |
| D: +--------------->|
| | Introspection |
| | Request |
| | |
| E: +<---------------+
| | Introspection |
| | Response |
| | + Client Token |
|<---------------+ |
| 2.01 Created | |
| + Client Token |
Figure 15: Use of the client_token parameter.
The client token is a COSE_Encrypted object, containing as payload a
CBOR map with the following claims:
cnf REQUIRED if the token type is "pop", OPTIONAL otherwise.
Contains information about the proof-of-possession key the client
is to use with its access token. See Section 5.6.4.5.
token_type OPTIONAL. See Section 5.6.4.3.
profile REQUIRED. See Section 5.6.4.4.
rs_cnf OPTIONAL. Contains information about the key that the RS
uses to authenticate towards the client. If the key is symmetric
then this claim MUST NOT be part of the Client Token, since this
is the same key as the one specified through the "cnf" claim.
This claim uses the same encoding as the "cnf" parameter. See
Section 5.6.4.4.
The AS encrypts this token using a key shared between the AS and the
client, so that only the client can decrypt it and access its
payload. How this key is established is out of scope of this
framework, however it can be established at the same time at which
the client's long term token is created.
An RS that is configured to perform introspection, MUST do so
immediately after receiving an access token, in order to be able to
return a potential client token to the client. This does not
preclude the RS to perform additional introspection asynchronously,
e.g., when the token is later used.
5.7.5. Mapping Introspection parameters to CBOR
The introspection request and response parameters MUST be mapped to The introspection request and response parameters MUST be mapped to
CBOR types as specified in Figure 16, using the given integer CBOR types as specified in Figure 15, using the given integer
abbreviation for the key. abbreviation for the key.
Note that we have aligned these abbreviations with the claim Note that we have aligned these abbreviations with the claim
abbreviations defined in [I-D.ietf-ace-cbor-web-token]. abbreviations defined in [I-D.ietf-ace-cbor-web-token].
/-----------------+----------+-----------------------\ /-----------------+----------+-----------------------\
| Parameter name | CBOR Key | Major Type | | Parameter name | CBOR Key | Value Type |
|-----------------+----------+-----------------------| |-----------------+----------+-----------------------|
| iss | 1 | text string | | iss | 1 | text string |
| sub | 2 | text string | | sub | 2 | text string |
| aud | 3 | text string | | aud | 3 | text string |
| exp | 4 | Epoch-based date/time | | exp | 4 | Epoch-based date/time |
| nbf | 5 | Epoch-based date/time | | nbf | 5 | Epoch-based date/time |
| iat | 6 | Epoch-based date/time | | iat | 6 | Epoch-based date/time |
| cti | 7 | byte string | | cti | 7 | byte string |
| client_id | 8 | text string | | client_id | 8 | text string |
| scope | 12 | text OR byte string | | scope | 12 | text OR byte string |
skipping to change at page 32, line 37 skipping to change at page 31, line 52
| username | 22 | text string | | username | 22 | text string |
| cnf | 25 | map | | cnf | 25 | map |
| profile | 26 | unsigned integer | | profile | 26 | unsigned integer |
| token | 27 | text string | | token | 27 | text string |
| token_type_hint | 28 | text string | | token_type_hint | 28 | text string |
| active | 29 | unsigned integer | | active | 29 | unsigned integer |
| client_token | 30 | byte string | | client_token | 30 | byte string |
| rs_cnf | 31 | map | | rs_cnf | 31 | map |
\-----------------+----------+-----------------------/ \-----------------+----------+-----------------------/
Figure 16: CBOR Mappings to Token Introspection Parameters. Figure 15: 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 [I-D.ietf-ace-cbor-web-token]. specified in [I-D.ietf-ace-cbor-web-token].
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.
The "scope" claim explicitly encodes the scope of a given access The "scope" claim explicitly encodes the scope of a given access
token. This claim follows the same encoding rules as defined in token. This claim follows the same encoding rules as defined in
section 3.3 of [RFC6749], but in addition implementers MAY use byte Section 3.3 of [RFC6749], but in addition implementers MAY use byte
arrays as scope values, to achieve compact encoding of large scope arrays as scope values, to achieve compact encoding of large scope
elements. The meaning of a specific scope value is application elements. The meaning of a specific scope value is application
specific and expected to be known to the RS running that application. specific and expected to be known to the RS running that application.
5.8.1. The 'Authorization Information' Endpoint 5.8.1. The 'Authorization Information' Endpoint
The access token, containing authorization information and The access token, containing authorization information and
information about the key used by the client, needs to be transported information about the key used by the client, needs to be transported
to the RS so that the RS can authenticate and authorize the client to the RS so that the RS can authenticate and authorize the client
request. request.
skipping to change at page 33, line 43 skipping to change at page 33, line 9
equivalent to the CoAP code 4.01 (Unauthorized). If the token is equivalent to the CoAP code 4.01 (Unauthorized). If the token is
valid but the audience of the token does not match the RS, the RS valid but the audience of the token does not match the RS, the RS
MUST respond with a response code equivalent to the CoAP code 4.03 MUST respond with a response code equivalent to the CoAP code 4.03
(Forbidden). If the token is valid but is associated to claims that (Forbidden). If the token is valid but is associated to claims that
the RS cannot process (e.g., an unknown scope) the RS MUST respond the RS cannot process (e.g., an unknown scope) the RS MUST respond
with a response code equivalent to the CoAP code 4.00 (Bad Request). 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 In the latter case the RS MAY provide additional information in the
error response, in order to clarify what went wrong. 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. If the responding to the POST request to the authz-info endpoint.
introspection response contains a client token (Section 5.7.4) then
this token SHALL be included in the payload of the 2.01 (Created)
response.
Profiles MUST specify how the authz-info endpoint is protected. Note Profiles MUST specify how the authz-info endpoint is 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.
The default name of this endpoint in an url-path is 'authz-info', The default name of this endpoint in an url-path is 'authz-info',
however implementations are not required to use this name and can however implementations are not required to use this name and can
define their own instead. define their own instead.
skipping to change at page 35, line 32 skipping to change at page 34, line 46
of-possession concept is significantly reduced. of-possession concept is significantly reduced.
The authorization server MUST offer confidentiality protection for The authorization server MUST offer confidentiality protection for
any interactions with the client. This step is extremely important any interactions with the client. This step is extremely important
since the client may obtain the proof-of-possession key from the since the client may obtain the proof-of-possession key from the
authorization server for use with a specific access token. Not using authorization server for use with a specific access token. Not using
confidentiality protection exposes this secret (and the access token) confidentiality protection exposes this secret (and the access token)
to an eavesdropper thereby completely negating proof-of-possession to an eavesdropper thereby completely negating proof-of-possession
security. Profiles MUST specify how confidentiality protection is security. Profiles MUST specify how confidentiality protection is
provided, and additional protection can be applied by encrypting the provided, and additional protection can be applied by encrypting the
token, for example encryption of CWTs is specified in section 5.1 of token, for example encryption of CWTs is specified in Section 5.1 of
[I-D.ietf-ace-cbor-web-token]. [I-D.ietf-ace-cbor-web-token].
Developers MUST ensure that the ephemeral credentials (i.e., the Developers MUST ensure that the ephemeral credentials (i.e., the
private key or the session key) are not leaked to third parties. An private key or the session key) are not leaked to third parties. An
adversary in possession of the ephemeral credentials bound to the adversary in possession of the ephemeral credentials bound to the
access token will be able to impersonate the client. Be aware that access token will be able to impersonate the client. Be aware that
this is a real risk with many constrained environments, since this is a real risk with many constrained environments, since
adversaries can often easily get physical access to the devices. adversaries can often easily get physical access to the devices.
Clients can at any time request a new proof-of-possession capable Clients can at any time request a new proof-of-possession capable
skipping to change at page 38, line 8 skipping to change at page 37, line 21
8.1. Authorization Server Information 8.1. Authorization Server Information
A new registry will be requested from IANA, entitled "Authorization A new registry will be requested from IANA, entitled "Authorization
Server Information". The registry is to be created as Expert Review Server Information". The registry is to be created as Expert Review
Required. Required.
The columns of this table are: The columns of this table are:
Name The name of the parameter Name The name of the parameter
CBOR Key The unsigned integer value (CBOR major type 0) abbreviating CBOR Key The unsigned integer value abbreviating this parameter
this parameter name. Registration in the table is based on the name. Registration in the table is based on the value of the
value of the mapping requested. Integer values between 1 and 255 mapping requested. Integer values between 1 and 255 are
are designated as Standards Track Document required. Integer designated as Standards Track Document required. Integer values
values from 256 to 65535 are designated as Specification Required. from 256 to 65535 are designated as Specification Required.
Integer values greater than 65535 are designated as private use. Integer values greater than 65535 are designated as private use.
Major Type The CBOR major type allowable for the values of this Value Type The CBOR data types allowable for the 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 2. This registry will be initially populated by the values in Figure 2.
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.2. OAuth Error Code CBOR Mappings Registry 8.2. OAuth Error Code CBOR Mappings Registry
A new registry will be requested from IANA, entitled "OAuth Error A new registry will be requested from IANA, entitled "OAuth Error
Code CBOR Mappings Registry". The registry is to be created as Code CBOR Mappings Registry". The registry is to be created as
Expert Review Required. Expert Review Required.
The columns of this table are: The columns of this table 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 Key The unsigned integer value (CBOR major type 0) abbreviating CBOR Key The unsigned integer value abbreviating this error code.
this error code. Registration in the table is based on the value Registration in the table is based on the value of the mapping
of the mapping requested. Integer values between 1 and 255 are requested. Integer values between 1 and 255 are designated as
designated as Standards Track Document required. Integer values Standards Track Document required. Integer values from 256 to
from 256 to 65535 are designated as Specification Required. 65535 are designated as Specification Required. Integer values
Integer values greater than 65535 are designated as private use. greater than 65535 are designated 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.
This registry will be initially populated by the values in Figure 10. This registry will be initially populated by the values in Figure 10.
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.3. OAuth Grant Type CBOR Mappings 8.3. OAuth Grant Type CBOR Mappings
A new registry will be requested from IANA, entitled "OAuth Grant A new registry will be requested from IANA, entitled "OAuth Grant
Type CBOR Mappings". The registry is to be created as Expert Review Type CBOR Mappings". The registry is to be created as Expert Review
Required. Required.
The columns of this table are: The columns of this table are:
Name The name of the grant type as specified in Section 1.3 of Name The name of the grant type as specified in Section 1.3 of
[RFC6749]. [RFC6749].
CBOR Key The unsigned integer value (CBOR major type 0) abbreviating CBOR Key The unsigned integer value abbreviating this grant type.
this grant type. Registration in the table is based on the value Registration in the table is based on the value of the mapping
of the mapping requested. Integer values between 1 and 255 are requested. Integer values between 1 and 255 are designated as
designated as Standards Track Document required. Integer values Standards Track Document required. Integer values from 256 to
from 256 to 65535 are designated as Specification Required. 65535 are designated as Specification Required. Integer values
Integer values greater than 65535 are designated as private use. greater than 65535 are designated 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.
Original Specification This contains a pointer to the public Original Specification This contains a pointer to the public
specification of the grant type, if one exists. specification of the grant type, if one exists.
This registry will be initially populated by the values in Figure 11. This registry will be initially populated by the values in Figure 11.
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.4. OAuth Access Token Types 8.4. OAuth Access Token Types
skipping to change at page 39, line 39 skipping to change at page 39, line 4
8.5. OAuth Token Type CBOR Mappings 8.5. OAuth Token Type CBOR Mappings
A new registry will be requested from IANA, entitled "Token Type CBOR A new registry will be requested from IANA, entitled "Token Type CBOR
Mappings". The registry is to be created as Expert Review Required. Mappings". The registry is to be created as Expert Review Required.
The columns of this table are: The columns of this table 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 Key The unsigned integer value (CBOR major type 0) abbreviating
this access token type. Registration in the table is based on the CBOR Key The unsigned integer value abbreviating this access token
value of the mapping requested. Integer values between 1 and 255 type. Registration in the table is based on the value of the
are designated as Standards Track Document required. Integer mapping requested. Integer values between 1 and 255 are
values from 256 to 65535 are designated as Specification Required. designated as Standards Track Document required. Integer values
from 256 to 65535 are designated as Specification Required.
Integer values greater than 65535 are designated as private use. Integer values greater than 65535 are designated 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
specification of the grant type, if one exists. specification of the grant type, if one exists.
8.5.1. Initial Registry Contents 8.5.1. Initial Registry Contents
o Name: "Bearer" o Name: "Bearer"
o Value: 1 o Value: 1
skipping to change at page 40, line 28 skipping to change at page 39, line 39
A new registry will be requested from IANA, entitled "ACE Profile A new registry will be requested from IANA, entitled "ACE Profile
Registry". The registry is to be created as Expert Review Required. Registry". The registry is to be created as Expert Review Required.
The columns of this table are: The columns of this table are:
Name The name of the profile, to be used as value of the profile Name The name of the profile, to be used as value of the profile
attribute. attribute.
Description Text giving an overview of the profile and the context Description Text giving an overview of the profile and the context
it is developed for. it is developed for.
CBOR Key The unsigned integer value (CBOR major type 0) abbreviating CBOR Key The unsigned integer value abbreviating this profile name.
this profile name. Registration in the table is based on the Registration in the table is based on the value of the mapping
value of the mapping requested. Integer values between 1 and 255 requested. Integer values between 1 and 255 are designated as
are designated as Standards Track Document required. Integer Standards Track Document required. Integer values from 256 to
values from 256 to 65535 are designated as Specification Required. 65535 are designated as Specification Required. Integer values
Integer values greater than 65535 are designated as private use. greater than 65535 are designated 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
profile abbreviation, if one exists. profile abbreviation, if one exists.
8.7. OAuth Parameter Registration 8.7. OAuth Parameter Registration
This specification registers the following parameters in the OAuth This specification registers the following parameters in the OAuth
Parameters Registry Parameters Registry:
o Name: "aud"
o Parameter Usage Location: authorization request, token request
o Change Controller: IESG
o Reference: Section 5.6.1 of [this document]
o Name: "profile" o Name: "profile"
o Parameter Usage Location: token request, token response o Parameter Usage Location: token response
o Change Controller: IESG o Change Controller: IESG
o Reference: Section 5.6.4.4 of [this document] o Reference: Section 5.6.4.4 of [this document]
o Name: "cnf" o Name: "cnf"
o Parameter Usage Location: token request, token response o Parameter Usage Location: token request, token response
o Change Controller: IESG o Change Controller: IESG
o Reference: Section 5.6.4.5 of [this document] o Reference: Section 5.6.4.5 of [this document]
o Name: "rs_cnf" o Name: "rs_cnf"
o Parameter Usage Location: token response o Parameter Usage Location: token response
skipping to change at page 41, line 18 skipping to change at page 40, line 35
8.8. OAuth CBOR Parameter Mappings Registry 8.8. OAuth CBOR Parameter Mappings Registry
A new registry will be requested from IANA, entitled "Token Endpoint A new registry will be requested from IANA, entitled "Token Endpoint
CBOR Mappings Registry". The registry is to be created as Expert CBOR Mappings Registry". The registry is to be created as Expert
Review Required. Review Required.
The columns of this table are: The columns of this table 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 The unsigned integer value (CBOR major type 0) abbreviating CBOR Key The unsigned integer value abbreviating this parameter.
this parameter. Registration in the table is based on the value Registration in the table is based on the value of the mapping
of the mapping requested. Integer values between 1 and 255 are requested. Integer values between 1 and 255 are designated as
designated as Standards Track Document required. Integer values Standards Track Document required. Integer values from 256 to
from 256 to 65535 are designated as Specification Required. 65535 are designated as Specification Required. Integer values
Integer values greater than 65535 are designated as private use. greater than 65535 are designated as private use.
Major 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 12. This registry will be initially populated by the values in Figure 12.
The Reference column for all of these entries will be this document. The Reference column for all of these entries will be this document.
Note that these mappings intentionally coincide with the CWT claim Note that these mappings intentionally coincide with the CWT claim
name mappings from [I-D.ietf-ace-cbor-web-token]. name mappings from [I-D.ietf-ace-cbor-web-token].
8.9. OAuth Introspection Response Parameter Registration 8.9. OAuth Introspection Response Parameter Registration
This specification registers the following parameters in the OAuth This specification registers the following parameters in the OAuth
Token Introspection Response registry. Token Introspection Response registry.
o Name: "cnf" o Name: "cnf"
o Description: Key to prove the right to use an access token, o Description: Key to prove the right to use a PoP token.
formatted as specified in [I-D.ietf-ace-cwt-proof-of-possession].
o Change Controller: IESG o Change Controller: IESG
o Reference: Section 5.7.2 of [this document] o Reference: Section 5.7.2 of [this document]
o Name: "profile" o Name: "profile"
o Description: The communication and communication security profile o Description: The communication and communication security profile
used between client and RS, as defined in ACE profiles. used between client and RS, as defined in ACE profiles.
o Change Controller: IESG o Change Controller: IESG
o Reference: Section 5.7.2 of [this document] o Reference: Section 5.7.2 of [this document]
o Name: "client_token" o Name: "client_token"
o Description: Information that the RS MUST pass to the client e.g., o Description: Information that the RS MUST pass to the client e.g.,
about the proof-of-possession keys. about the proof-of-possession keys.
o Change Controller: IESG o Change Controller: IESG
o Reference: Section 5.7.2 of [this document] o Reference: Section 5.7.2 of [this document]
8.10. Introspection Endpoint CBOR Mappings Registry 8.10. Introspection Endpoint CBOR Mappings Registry
A new registry will be requested from IANA, entitled "Introspection A new registry will be requested from IANA, entitled "Introspection
Endpoint CBOR Mappings Registry". The registry is to be created as Endpoint CBOR Mappings Registry". The registry is to be created as
skipping to change at page 42, line 20 skipping to change at page 41, line 37
8.10. Introspection Endpoint CBOR Mappings Registry 8.10. Introspection Endpoint CBOR Mappings Registry
A new registry will be requested from IANA, entitled "Introspection A new registry will be requested from IANA, entitled "Introspection
Endpoint CBOR Mappings Registry". The registry is to be created as Endpoint CBOR Mappings Registry". The registry is to be created as
Expert Review Required. Expert Review Required.
The columns of this table are: The columns of this table 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 The unsigned integer value (CBOR major type 0) abbreviating CBOR Key The unsigned integer value abbreviating this parameter.
this parameter. Registration in the table is based on the value Registration in the table is based on the value of the mapping
of the mapping requested. Integer values between 1 and 255 are requested. Integer values between 1 and 255 are designated as
designated as Standards Track Document required. Integer values Standards Track Document required. Integer values from 256 to
from 256 to 65535 are designated as Specification Required. 65535 are designated as Specification Required. Integer values
Integer values greater than 65535 are designated as private use. greater than 65535 are designated as private use.
Major 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 16. This registry will be initially populated by the values in Figure 15.
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:
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
[RFC6749]. [RFC6749].
skipping to change at page 44, line 4 skipping to change at page 43, line 20
where large parts of the security considerations where copied. where large parts of the security considerations where copied.
Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten Bormann for Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten Bormann for
contributing their work on AS discovery from draft-gerdes-ace-dcaf- contributing their work on AS discovery from draft-gerdes-ace-dcaf-
authorize (see Section 5.1). authorize (see Section 5.1).
Ludwig Seitz and Goeran Selander worked on this document as part of Ludwig Seitz and Goeran Selander worked on this document as part of
the CelticPlus project CyberWI, with funding from Vinnova. the CelticPlus project CyberWI, with funding from Vinnova.
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-ace-cbor-web-token] [I-D.ietf-ace-cbor-web-token]
Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig,
"CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-09 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-12
(work in progress), October 2017. (work in progress), February 2018.
[I-D.ietf-ace-cwt-proof-of-possession] [I-D.ietf-ace-cwt-proof-of-possession]
Jones, M., Seitz, L., Selander, G., Wahlstroem, E., Jones, M., Seitz, L., Selander, G., Wahlstroem, E.,
Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key
Semantics for CBOR Web Tokens (CWTs)", draft-ietf-ace-cwt- Semantics for CBOR Web Tokens (CWTs)", draft-ietf-ace-cwt-
proof-of-possession-01 (work in progress), October 2017. proof-of-possession-01 (work in progress), October 2017.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, <https://www.rfc- DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
skipping to change at page 44, line 40 skipping to change at page 44, line 9
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, <https://www.rfc- DOI 10.17487/RFC7252, June 2014, <https://www.rfc-
editor.org/info/rfc7252>. editor.org/info/rfc7252>.
[RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection",
RFC 7662, DOI 10.17487/RFC7662, October 2015, RFC 7662, DOI 10.17487/RFC7662, October 2015,
<https://www.rfc-editor.org/info/rfc7662>. <https://www.rfc-editor.org/info/rfc7662>.
[RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-
Possession Key Semantics for JSON Web Tokens (JWTs)",
RFC 7800, DOI 10.17487/RFC7800, April 2016,
<https://www.rfc-editor.org/info/rfc7800>.
[RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)",
RFC 8152, DOI 10.17487/RFC8152, July 2017, RFC 8152, DOI 10.17487/RFC8152, July 2017,
<https://www.rfc-editor.org/info/rfc8152>. <https://www.rfc-editor.org/info/rfc8152>.
10.2. Informative References 10.2. Informative References
[I-D.erdtman-ace-rpcc] [I-D.erdtman-ace-rpcc]
Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared- Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared-
Key as OAuth client credentials", draft-erdtman-ace- Key as OAuth client credentials", draft-erdtman-ace-
rpcc-02 (work in progress), October 2017. rpcc-02 (work in progress), October 2017.
[I-D.ietf-ace-actors] [I-D.ietf-ace-actors]
Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An
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-06 (work in (OSCORE)", draft-ietf-core-object-security-08 (work in
progress), October 2017. progress), January 2018.
[I-D.ietf-core-resource-directory] [I-D.ietf-core-resource-directory]
Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. Shelby, Z., Koster, M., Bormann, C., Stok, P., and C.
Amsuess, "CoRE Resource Directory", draft-ietf-core- Amsuess, "CoRE Resource Directory", draft-ietf-core-
resource-directory-12 (work in progress), October 2017. resource-directory-12 (work in progress), October 2017.
[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-07 Constrained Devices", draft-ietf-oauth-device-flow-07
(work in progress), October 2017. (work in progress), October 2017.
[I-D.ietf-oauth-discovery] [I-D.ietf-oauth-discovery]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", draft-ietf-oauth- Authorization Server Metadata", draft-ietf-oauth-
discovery-07 (work in progress), September 2017. discovery-08 (work in progress), November 2017.
[I-D.ietf-oauth-native-apps]
Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
draft-ietf-oauth-native-apps-12 (work in progress), June
2017.
[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 47, line 26 skipping to change at page 46, line 35
and S. Kumar, "Use Cases for Authentication and and S. Kumar, "Use Cases for Authentication and
Authorization in Constrained Environments", RFC 7744, Authorization in Constrained Environments", RFC 7744,
DOI 10.17487/RFC7744, January 2016, <https://www.rfc- DOI 10.17487/RFC7744, January 2016, <https://www.rfc-
editor.org/info/rfc7744>. editor.org/info/rfc7744>.
[RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
the Constrained Application Protocol (CoAP)", RFC 7959, the Constrained Application Protocol (CoAP)", RFC 7959,
DOI 10.17487/RFC7959, August 2016, <https://www.rfc- DOI 10.17487/RFC7959, August 2016, <https://www.rfc-
editor.org/info/rfc7959>. editor.org/info/rfc7959>.
[RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,
<https://www.rfc-editor.org/info/rfc8252>.
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:
skipping to change at page 50, line 49 skipping to change at page 50, line 18
that prevent it from communicating with the AS). In that case that prevent it from communicating with the AS). In that case
this framework RECOMMENDS the use of a long-term token, that could this framework RECOMMENDS the use of a long-term token, that could
be a simple reference. The RS is assumed to be able to be a simple reference. The RS is assumed to be able to
communicate with the AS, and can therefore perform introspection, communicate with the AS, and can therefore perform introspection,
in order to learn the claims associated with the token reference. in order to learn the claims associated with the token reference.
The advantage of such an approach is that the resource owner can The advantage of such an approach is that the resource owner can
change the claims associated to the token reference without having change the claims associated to the token reference without having
to be in contact with the client, thus granting or revoking access to be in contact with the client, thus granting or revoking access
rights. rights.
Client Token:
In cases where the client is constrained and does not have
connectivity to the AS, and furthermore does not have a previous
security relation to the RS that it needs to communicate with,
this framework proposes the use of "client tokens". A client
token is a data object obtained from the AS by the RS, during
access token introspection. The RS passes the client token on to
the client. It contains information that allows the client to
perform the proof of possession for its access token and to
authenticate the RS (e.g. with it's public key).
Appendix B. Roles and Responsibilities Appendix B. Roles and Responsibilities
Resource Owner Resource Owner
* Make sure that the RS is registered at the AS. This includes * Make sure that the RS is registered at the AS. This includes
making known to the AS which profiles, token_types, scopes, and making known to the AS which profiles, token_types, scopes, and
key types (symmetric/asymmetric) the RS supports. Also making key types (symmetric/asymmetric) the RS supports. Also making
it known to the AS which audience(s) the RS identifies itself it known to the AS which audience(s) the RS identifies itself
with. with.
* Make sure that clients can discover the AS that is in charge of * Make sure that clients can discover the AS that is in charge of
skipping to change at page 55, line 7 skipping to change at page 54, line 7
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 17. server. Message exchanges A and B are shown in Figure 16.
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
skipping to change at page 56, line 21 skipping to change at page 55, line 21
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 17: Token Request and Response Using Client Credentials. Figure 16: 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 18. Note that a transport layer security Payload is shown in Figure 17. Note that a transport layer security
based communication security profile is used in this example, based communication security profile is used in this example,
therefore the Content-Type is "application/cbor". therefore the 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"
} }
skipping to change at page 56, line 52 skipping to change at page 55, line 52
"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 18: Request and Response Payload Details. Figure 17: Request and Response Payload Details.
The content of the access token is shown in Figure 19. The content of the access token is shown in Figure 18.
{ {
"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 19: Access Token including Public Key of the Client. Figure 18: Access Token including Public Key of the Client.
Messages C and F are shown in Figure 20 - Figure 21. Messages C and F are shown in Figure 19 - Figure 20.
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 between client and RS,
since the token is integrity protected between the AS and RS. The since the token is integrity protected between the AS and RS. The
RS verifies that the PoP access token was created by a known and RS verifies that the PoP access token was created by a known and
trusted AS, is valid, and responds to the client. The RS caches trusted AS, is valid, and responds to the client. The RS caches
the security context together with authorization information about the security context together with authorization information about
this client contained in the PoP access token. this client contained in the PoP access token.
skipping to change at page 57, line 47 skipping to change at page 56, line 47
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 20: Access Token provisioning to RS Figure 19: 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
skipping to change at page 58, line 25 skipping to change at page 57, line 25
| | | |
+-------->| 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 21: Resource Request and Response protected by DTLS. Figure 20: 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 58, line 48 skipping to change at page 57, line 48
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 22. Figure 21.
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 59, line 45 skipping to change at page 58, line 45
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 22: Token Request and Response using Client Credentials. Figure 21: 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 23. Payload is shown in Figure 22.
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 60, line 28 skipping to change at page 59, 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 23: Request and Response Payload for C offline Figure 22: 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 61, line 30 skipping to change at page 60, 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 24: Token Introspection for C offline Figure 23: 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 25. Payload is shown in Figure 24.
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 25: Request and Response Payload for Introspection Figure 24: 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 62, line 26 skipping to change at page 61, 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 26: Resource request and response protected by OSCOAP Figure 25: Resource request and response protected by OSCOAP
Appendix F. Document Updates Appendix F. Document Updates
F.1. Version -08 to -09 F.1. Version -09 to -10
o Removed CBOR major type numbers.
o Removed the client token design.
o Rephrased to clarify that other protocols than CoAP can be used.
o Clarifications regarding the use of HTTP
F.2. 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.2. Version -07 to -08 F.3. 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 63, line 22 skipping to change at page 62, line 33
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.3. Version -06 to -07 F.4. Version -06 to -07
o Various clarifications added. o Various clarifications added.
o Fixed erroneous author email. o Fixed erroneous author email.
F.4. Version -05 to -06 F.5. 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.5. Version -04 to -05 F.6. 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.2 requests in Section 5.8.2
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
skipping to change at page 64, line 5 skipping to change at page 63, line 17
o Added clarification about token expiration and long-running o Added clarification about token expiration and long-running
requests in Section 5.8.2 requests in Section 5.8.2
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.6. Version -03 to -04 F.7. 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.7. Version -02 to -03 F.8. 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.8. Version -01 to -02 F.9. 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.9. Version -00 to -01 F.10. 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 65, line 40 skipping to change at page 65, line 4
Authors' Addresses Authors' Addresses
Ludwig Seitz Ludwig Seitz
RISE SICS RISE SICS
Scheelevaegen 17 Scheelevaegen 17
Lund 223 70 Lund 223 70
Sweden Sweden
Email: ludwig.seitz@ri.se Email: ludwig.seitz@ri.se
Goeran Selander Goeran Selander
Ericsson Ericsson
Faroegatan 6 Faroegatan 6
Kista 164 80 Kista 164 80
Sweden Sweden
Email: goran.selander@ericsson.com Email: goran.selander@ericsson.com
Erik Wahlstroem Erik Wahlstroem
(no affiliation)
Sweden Sweden
Email: erik@wahlstromtekniska.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
 End of changes. 120 change blocks. 
321 lines changed or deleted 278 lines changed or added

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