draft-ietf-ace-oauth-authz-03.txt   draft-ietf-ace-oauth-authz-04.txt 
ACE Working Group L. Seitz ACE Working Group L. Seitz
Internet-Draft SICS Internet-Draft SICS
Intended status: Standards Track G. Selander Intended status: Standards Track G. Selander
Expires: April 15, 2017 Ericsson Expires: May 4, 2017 Ericsson
E. Wahlstroem E. Wahlstroem
S. Erdtman S. Erdtman
Spotify AB Spotify AB
H. Tschofenig H. Tschofenig
ARM Ltd. ARM Ltd.
October 12, 2016 October 31, 2016
Authentication and Authorization for Constrained Environments (ACE) Authentication and Authorization for Constrained Environments (ACE)
draft-ietf-ace-oauth-authz-03 draft-ietf-ace-oauth-authz-04
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 April 15, 2017. This Internet-Draft will expire on May 4, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 25 skipping to change at page 2, line 25
Table of Contents Table of Contents
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 . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 9 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 9
5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6. The 'Token' Endpoint . . . . . . . . . . . . . . . . . . . . 14 6. The 'Token' Endpoint . . . . . . . . . . . . . . . . . . . . 14
6.1. Client-to-AS Request . . . . . . . . . . . . . . . . . . 14 6.1. Client-to-AS Request . . . . . . . . . . . . . . . . . . 15
6.2. AS-to-Client Response . . . . . . . . . . . . . . . . . . 17 6.2. AS-to-Client Response . . . . . . . . . . . . . . . . . . 17
6.3. Error Response . . . . . . . . . . . . . . . . . . . . . 18 6.3. Error Response . . . . . . . . . . . . . . . . . . . . . 19
6.4. New Request and Response Parameters . . . . . . . . . . . 18 6.4. New Request and Response Parameters . . . . . . . . . . . 19
6.4.1. Audience . . . . . . . . . . . . . . . . . . . . . . 18 6.4.1. Audience . . . . . . . . . . . . . . . . . . . . . . 19
6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . . . 19 6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . . . 19
6.4.3. Token Type . . . . . . . . . . . . . . . . . . . . . 19 6.4.3. Token Type . . . . . . . . . . . . . . . . . . . . . 19
6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . . . 19 6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . . . 20
6.4.5. Confirmation . . . . . . . . . . . . . . . . . . . . 20 6.4.5. Confirmation . . . . . . . . . . . . . . . . . . . . 20
6.5. Mapping parameters to CBOR . . . . . . . . . . . . . . . 21 6.5. Mapping parameters to CBOR . . . . . . . . . . . . . . . 22
7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . . . 22 7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . . . 23
7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . . . 23 7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . . . 24
7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . . . 23 7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . . . 24
7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 24 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 25
7.4. Client Token . . . . . . . . . . . . . . . . . . . . . . 25 7.4. Client Token . . . . . . . . . . . . . . . . . . . . . . 26
7.5. Mapping Introspection parameters to CBOR . . . . . . . . 26 7.5. Mapping Introspection parameters to CBOR . . . . . . . . 28
8. The Access Token . . . . . . . . . . . . . . . . . . . . . . 27 8. The Access Token . . . . . . . . . . . . . . . . . . . . . . 28
8.1. The 'Authorization Information' Endpoint . . . . . . . . 28 8.1. The 'Authorization Information' Endpoint . . . . . . . . 29
8.2. Token Expiration . . . . . . . . . . . . . . . . . . . . 28 8.2. Token Expiration . . . . . . . . . . . . . . . . . . . . 29
9. Security Considerations . . . . . . . . . . . . . . . . . . . 29 9. Security Considerations . . . . . . . . . . . . . . . . . . . 30
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31
10.1. OAuth Introspection Response Parameter Registration . . 30 10.1. OAuth Introspection Response Parameter Registration . . 31
10.2. OAuth Parameter Registration . . . . . . . . . . . . . . 31 10.2. OAuth Parameter Registration . . . . . . . . . . . . . . 32
10.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 31 10.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 32
10.4. Token Type Mappings . . . . . . . . . . . . . . . . . . 32 10.4. Token Type Mappings . . . . . . . . . . . . . . . . . . 33
10.4.1. Registration Template . . . . . . . . . . . . . . . 32 10.4.1. Registration Template . . . . . . . . . . . . . . . 33
10.4.2. Initial Registry Contents . . . . . . . . . . . . . 32 10.4.2. Initial Registry Contents . . . . . . . . . . . . . 33
10.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . 32 10.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . 33
10.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 33 10.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 34
10.6.1. Registration Template . . . . . . . . . . . . . . . 33 10.6.1. Registration Template . . . . . . . . . . . . . . . 34
10.7. OAuth Parameter Mappings Registry . . . . . . . . . . . 33 10.7. OAuth Parameter Mappings Registry . . . . . . . . . . . 34
10.7.1. Registration Template . . . . . . . . . . . . . . . 33 10.7.1. Registration Template . . . . . . . . . . . . . . . 34
10.7.2. Initial Registry Contents . . . . . . . . . . . . . 34 10.7.2. Initial Registry Contents . . . . . . . . . . . . . 35
10.8. Introspection Endpoint CBOR Mappings Registry . . . . . 36 10.8. Introspection Endpoint CBOR Mappings Registry . . . . . 37
10.8.1. Registration Template . . . . . . . . . . . . . . . 36 10.8.1. Registration Template . . . . . . . . . . . . . . . 37
10.8.2. Initial Registry Contents . . . . . . . . . . . . . 36 10.8.2. Initial Registry Contents . . . . . . . . . . . . . 37
10.9. CoAP Option Number Registration . . . . . . . . . . . . 38 10.9. CoAP Option Number Registration . . . . . . . . . . . . 39
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 39 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 40
12.1. Normative References . . . . . . . . . . . . . . . . . . 39 12.1. Normative References . . . . . . . . . . . . . . . . . . 40
12.2. Informative References . . . . . . . . . . . . . . . . . 40 12.2. Informative References . . . . . . . . . . . . . . . . . 41
Appendix A. Design Justification . . . . . . . . . . . . . . . . 42 Appendix A. Design Justification . . . . . . . . . . . . . . . . 43
Appendix B. Roles and Responsibilites . . . . . . . . . . . . . 44 Appendix B. Roles and Responsibilites . . . . . . . . . . . . . 45
Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 46 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 47
Appendix D. Deployment Examples . . . . . . . . . . . . . . . . 46 Appendix D. Deployment Examples . . . . . . . . . . . . . . . . 47
D.1. Local Token Validation . . . . . . . . . . . . . . . . . 47 D.1. Local Token Validation . . . . . . . . . . . . . . . . . 48
D.2. Introspection Aided Token Validation . . . . . . . . . . 50 D.2. Introspection Aided Token Validation . . . . . . . . . . 51
Appendix E. Document Updates . . . . . . . . . . . . . . . . . . 54 Appendix E. Document Updates . . . . . . . . . . . . . . . . . . 55
E.1. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 54 E.1. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 55
E.2. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 54 E.2. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 55
E.3. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 55 E.3. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 56
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57
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 is a complex authorization for a large number of devices and users is a complex
task. task.
skipping to change at page 5, line 5 skipping to change at page 5, line 5
/introspect at the AS and /authz-info at the RS. The CoAP [RFC7252] /introspect at the AS and /authz-info at the RS. 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 memo. is not used in this memo.
Since this specification focuses on the problem of access control to Since this specification focuses on the problem of access control to
resources, we simplify the actors by assuming that the client resources, we simplify the actors 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]).
We call the specifications of this memo the "framework" or "ACE
framework". When referring to "profiles of this framework" we mean
additional memo's that define the use of this specification with
concrete transport, and communication security protocols (e.g. CoAP
over DTLS).
3. Overview 3. Overview
This specification defines the ACE framework for authorization in the This specification defines the ACE framework for authorization in the
Internet of Things environment. It consists of a set of building Internet of Things environment. It consists of a set of building
blocks. blocks.
The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys
widespread deployment. Many IoT devices can support OAuth 2.0 widespread deployment. Many IoT devices can support OAuth 2.0
without any additional extensions, but for certain constrained without any additional extensions, but for certain constrained
settings additional profiling is needed. settings additional profiling is needed.
skipping to change at page 6, line 33 skipping to change at page 6, line 39
The token and introspect Endpoints: The token and introspect Endpoints:
The AS hosts the /token endpoint that allows a client to request The AS hosts the /token endpoint that allows a client to request
access tokens. The client makes a POST request to the /token access tokens. The client makes a POST request to the /token
endpoint on the AS and receives the access token in the response endpoint on the AS and receives the access token in the response
(if the request was successful). (if the request was successful).
The token introspection endpoint, /introspect, is used by the RS The token introspection endpoint, /introspect, is used by the RS
when requesting additional information regarding a received access when requesting additional information regarding a received access
token. The RS makes a POST request to /introspect on the AS and token. The RS makes a POST request to /introspect on the AS and
receives information about the access token contain in the receives information about the access token in the response. (See
response. (See "Introspection" below.) "Introspection" below.)
Access Tokens: Access Tokens:
Access tokens are credentials needed to access protected Access tokens are credentials needed to access protected
resources. An access token is a data structure representing resources. An access token is a data structure representing
authorization permissions issued by the AS to the client. Access authorization permissions issued by the AS to the client. Access
tokens are generated by the authorization server and consumed by tokens are generated by the authorization server and consumed by
the resource server. The access token content is opaque to the the resource server. The access token content is opaque to the
client. client.
skipping to change at page 7, line 40 skipping to change at page 7, line 46
Asymmetric PoP key: An asymmetric key pair is generated on the Asymmetric PoP key: An asymmetric key pair is generated on the
client and the public key is sent to the AS (if it does not client and the public key is sent to the AS (if it does not
already have knowledge of the client's public key). already have knowledge of the client's public key).
Information about the public key, which is the PoP key in this Information about the public key, which is the PoP key in this
case, is either stored to be returned on introspection calls or case, is either stored to be returned on introspection calls or
included inside the access token and sent back to the included inside the access token and sent back to the
requesting client. The RS can identify the client's public key requesting client. The RS can identify the client's public key
from the information in the token, which allows the client to from the information in the token, which allows the client to
use the corresponding private key for the proof of possession. use the corresponding private key for the proof of possession.
The access token is protected against modifications using a MAC or The access token is either a simple reference, or a structured
a digital signature, which is added by the AS. The choice of PoP information object (e.g. CWT [I-D.ietf-ace-cbor-web-token]),
key does not necessarily imply a specific credential type for the protected by a cryptographic wrapper (e.g. COSE
integrity protection of the token. [I-D.ietf-cose-msg]). The choice of PoP key does not necessarily
imply a specific credential type for the integrity protection of
the token.
Scopes and Permissions: Scopes and Permissions:
In OAuth 2.0, the client specifies the type of permissions it is In OAuth 2.0, the client specifies the type of permissions it is
seeking to obtain (via the scope parameter) in the access token seeking to obtain (via the scope parameter) in the access token
request. In turn, the AS may use the scope response parameter to request. In turn, the AS may use the scope response parameter to
inform the client of the scope of the access token issued. As the inform the client of the scope of the access token issued. As the
client could be a constrained device as well, this specification client could be a constrained device as well, this specification
uses CBOR encoded messages for CoAP, defined in Section 5, to uses CBOR encoded messages for CoAP, defined in Section 5, to
request scopes and to be informed what scopes the access token was request scopes and to be informed what scopes the access token was
skipping to change at page 9, line 14 skipping to change at page 9, line 20
CoAP supports application-layer fragmentation of the CoAP payloads CoAP supports application-layer fragmentation of the CoAP payloads
through blockwise transfers [RFC7959]. However, block-wise transfer through blockwise transfers [RFC7959]. However, block-wise transfer
does not increase the size limits of CoAP options, therefore data does not increase the size limits of CoAP options, therefore data
encoded in options has to be kept small. encoded in options has to be kept small.
Transport layer security for CoAP can be provided by DTLS 1.2 Transport layer security for CoAP can be provided by DTLS 1.2
[RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy [RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy
operations which requires transport layer security to be terminated operations which requires transport layer security to be terminated
at the proxy. One approach for protecting CoAP communication end-to- at the proxy. One approach for protecting CoAP communication end-to-
end through proxies, and also to support security for CoAP over end through proxies, and also to support security for CoAP over a
different transport in a uniform way, is to provide security on different transport in a uniform way, is to provide security on
application layer using an object-based security mechanism such as application layer using an object-based security mechanism such as
COSE [I-D.ietf-cose-msg]. COSE [I-D.ietf-cose-msg].
One application of COSE is OSCOAP [I-D.selander-ace-object-security], One application of COSE is OSCOAP [I-D.selander-ace-object-security],
which provides end-to-end confidentiality, integrity and replay which provides end-to-end confidentiality, integrity and replay
protection, and a secure binding between CoAP request and response protection, and a secure binding between CoAP request and response
messages. In OSCOAP, the CoAP messages are wrapped in COSE objects messages. In OSCOAP, the CoAP messages are wrapped in COSE objects
and sent using CoAP. and sent using CoAP.
skipping to change at page 9, line 43 skipping to change at page 9, line 49
access token. In other deployments the RS may process the access access token. In other deployments the RS may process the access
token locally without the need to contact an AS. These interactions token locally without the need to contact an AS. These interactions
are shown in Figure 1. An overview of various OAuth concepts is are shown in Figure 1. An overview of various OAuth concepts is
provided in Section 3.1. provided in Section 3.1.
The OAuth 2.0 framework defines a number of "protocol flows" via The OAuth 2.0 framework defines a number of "protocol flows" via
grant types, which have been extended further with extensions to grant types, which have been extended further with extensions to
OAuth 2.0 (such as RFC 7521 [RFC7521] and OAuth 2.0 (such as RFC 7521 [RFC7521] and
[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 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 RFC 7521) and Authorization Code Grant (described in Section 4.1 of RFC 7521) and
the Client Credentials Grant (described in Section 4.4 of RFC 7521). the Client Credentials Grant (described in Section 4.4 of RFC 7521).
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 [I-D.ietf-oauth-native-apps] are applicable to this use case. The
Client Credential Grant is a good fit for use with IoT devices where Client Credential Grant is a good fit for use with IoT devices where
the OAuth client itself is constraint. In such a case the resource the OAuth client itself is constrained. In such a case the resource
owner or another person on his or her behalf have arranged with the owner or another person on his or her behalf have arranged with the
authorization server out-of-band, which is often accomplished using authorization server out-of-band, which is often accomplished using a
an 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. We mechanisms between the ACE entities, such as client, AS, and RS. We
skipping to change at page 11, line 43 skipping to change at page 11, line 51
specific credential). specific credential).
Access Token Response (B): Access Token Response (B):
If the AS successfully processes the request from the client, it If the AS successfully processes the request from the client, it
returns an access token. It also returns various parameters, returns an access token. It also returns various parameters,
referred as "RS Information". In addition to the response referred as "RS Information". In addition to the response
parameters defined by OAuth 2.0 and the PoP token extension, parameters defined by OAuth 2.0 and the PoP token extension,
further response parameters, such as information on which profile further response parameters, such as information on which profile
the client should use with the resource server(s). More the client should use with the resource server(s). More
information about these parameters can be found in in Section 6.4. information about these parameters can be found in Section 6.4.
Resource Request (C): Resource Request (C):
The client interacts with the RS to request access to the The client interacts with the RS to request access to the
protected resource and provides the access token. The protocol to protected resource and provides the access token. The protocol to
use between the client and the RS is not restricted to CoAP. use between the client and the RS is not restricted to CoAP.
HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also
viable candidates. viable candidates.
Depending on the device limitations and the selected protocol this Depending on the device limitations and the selected protocol this
skipping to change at page 12, line 45 skipping to change at page 13, line 5
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. The AS can additionally
return information that the RS needs to pass on to the client in 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 the form of a client token. The latter is used to establish keys
for mutual authentication between client and RS, when the client for mutual authentication between client and RS, when the client
has no direct connectivity to the AS. has no direct connectivity to the AS, see Section 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
skipping to change at page 16, line 31 skipping to change at page 16, line 49
} }
Figure 3: Example request for an access token bound to an asymmetric Figure 3: Example request for an access token bound to an asymmetric
key. key.
Figure 4 shows a request for a token where a previously communicated Figure 4 shows a request for a token where a previously communicated
proof-of-possession key is only referenced. Note that we assume a proof-of-possession key is only referenced. Note that we assume a
DTLS-based communication security profile for this example, therefore DTLS-based communication security profile for this example, therefore
the Content-Type is "application/cbor". Also note that the client the Content-Type is "application/cbor". Also note that the client
performs a password based authentication in this example by performs a password based authentication in this example by
submitting its client_secret. submitting its client_secret (see section 2.3.1. of [RFC6749]).
Header: POST (Code=0.02) Header: POST (Code=0.02)
Uri-Host: "server.example.com" Uri-Host: "server.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 17, line 21 skipping to change at page 17, line 40
authorized, the AS returns an error response as described in authorized, the AS returns an error response as described in
Section 6.3. Section 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. This prior knowledge of the capabilities of the client, and the RS. This prior
knowledge may, for example, be set by the use of a dynamic client knowledge may, for example, be set by the use of a dynamic client
registration protocol exchange [RFC7591]. registration protocol exchange [RFC7591].
The content of the successful reply MUST be encoded as CBOR map, The content of the successful reply MUST be encoded as CBOR map,
containing paramters as speficied in section 5.1 of [RFC6749]. In containing parameters as speficied in section 5.1 of [RFC6749]. In
addition to these parameters, the following parameters are also part addition to these parameters, the following parameters are also part
of a successful response: of a successful response:
profile profile
REQUIRED. This indicates the profile that the client MUST use REQUIRED. This indicates the profile that the client MUST use
towards the RS. See Section 6.4.4 for the formatting of this towards the RS. See Section 6.4.4 for the formatting of this
parameter. parameter.
cnf cnf
REQUIRED if the token type is 'pop'. OPTIONAL otherwise. If a REQUIRED if the token type is 'pop'. OPTIONAL otherwise. If a
skipping to change at page 18, line 17 skipping to change at page 18, line 35
DTLS-based communication security profile for this example, therefore DTLS-based communication security profile for this example, therefore
the Content-Type is "application/cbor". 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:
{ {
"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",
"expires_in" : "3600", "expires_in" : "3600",
"cnf" : { "cnf" : {
"COSE_Key" : { "COSE_Key" : {
"kty" : "Symmetric", "kty" : "Symmetric",
"kid" : b64'39Gqlw', "kid" : b64'39Gqlw',
"k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh'
} }
} }
} }
skipping to change at page 20, line 14 skipping to change at page 20, line 35
6.4.5. Confirmation 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 or for authenticating the RS depending on the proof-of- possession or for authenticating the RS depending on the proof-of-
possession algorithm and the context cnf is used in. This framework possession algorithm and the context cnf is used in. This framework
extends the definition of 'cnf' from [RFC7800] by adding CBOR/COSE extends the definition of 'cnf' from [RFC7800] by adding CBOR/COSE
encodings and the use of 'cnf' for transporting keys in the RS encodings and the use of 'cnf' for transporting keys in the RS
Information. Information.
The "cnf" parameter is used in the following contexts with the
following meaning:
o In the access token, to indicate the proof-of-possession key bound
to this token.
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
C and RS.
o In the token response AS -> C, to indicate either the symmetric
key generated by the AS for proof-of-possession or the raw public
key used by the RS to authenticate.
o In the introspection response AS -> RS, to indicate the proof-of-
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.
A CBOR encoded payload MAY contain the 'cnf' parameter with the A CBOR encoded payload MAY contain the 'cnf' parameter with the
following contents: following contents:
COSE_Key In this case the 'cnf' parameter contains the proof-of- COSE_Key In this case the 'cnf' parameter contains the proof-of-
possession key to be used by the client. An example is shown in possession key to be used by the client. An example is shown in
Figure 7. Figure 7.
"cnf" : { "cnf" : {
"COSE_Key" : { "COSE_Key" : {
"kty" : "EC", "kty" : "EC",
skipping to change at page 25, line 18 skipping to change at page 26, line 18
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".
7.4. Client Token 7.4. Client Token
EDITORIAL NOTE: We have tentatively introduced this concept and would EDITORIAL NOTE: We have tentatively introduced this concept and would
specifically like feedback if this is viewed as a useful addition to specifically like feedback whether this is viewed as a useful
the framework. addition to the framework.
In cases where the client has limited connectivity and is requesting In cases where the client has limited connectivity and needs to get
access to a previously unknown resource servers, using a long term access to a previously unknown resource servers, this framework
token, there are situations where it would be beneficial to relay the suggests the following approach: The client is pre-configured with a
proof-of-possession key and other relevant information from the AS to generic, long-term access token when it is commissioned. When the
the client through the RS. The client_token parameter is designed to client then tries to access a RS it transmits this access token. The
carry such information, and is intended to be used as described in RS then performs token introspection to learn what access this token
Figure 14. 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 14.
Resource Authorization Resource Authorization
Client Server Server Client Server Server
| | | | | |
| | | | | |
C: +--------------->| | C: +--------------->| |
| POST | | | POST | |
| Access Token | | | Access Token | |
| D: +--------------->| | D: +--------------->|
| | Introspection | | | Introspection |
skipping to change at page 25, line 50 skipping to change at page 27, line 26
| E: +<---------------+ | E: +<---------------+
| | Introspection | | | Introspection |
| | Response | | | Response |
| | + Client Token | | | + Client Token |
|<---------------+ | |<---------------+ |
| 2.01 Created | | | 2.01 Created | |
| + Client Token | | + Client Token |
Figure 14: Use of the client_token parameter. Figure 14: Use of the client_token parameter.
The client token is a COSE_Encrytped object, containing as payload a The client token is a COSE_Encrypted object, containing as payload a
CBOR map with the following claims: CBOR map with the following claims:
cnf cnf
REQUIRED if the token type is 'pop', OPTIONAL otherwise. Contains REQUIRED if the token type is 'pop', OPTIONAL otherwise. Contains
information about the proof-of-possession key the client is to use information about the proof-of-possession key the client is to use
with its access token. See Section 6.4.5. with its access token. See Section 6.4.5.
token_type token_type
OPTIONAL. See Section 6.4.3. OPTIONAL. See Section 6.4.3.
skipping to change at page 27, line 46 skipping to change at page 28, line 51
draft specifies the "cnf" and "scope" claims for CBOR web tokens. draft specifies the "cnf" and "scope" claims for 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]. The meaning of a specific scope value is section 3.3 of [RFC6749]. 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. application.
The "cnf" claim follows the same rules as specified for JSON web The "cnf" claim follows the same rules as specified for JSON web
token in RFC7800 [RFC7800], except that it is encoded in CBOR in the token in RFC7800 [RFC7800], except that it is encoded in CBOR in the
same way as specified for the "cnf" parameter in section same way as specified for the "cnf" parameter in Section 6.4.5.
Section 6.4.5.
8.1. The 'Authorization Information' Endpoint 8.1. The 'Authorization Information' Endpoint
The access token, containing authorization information and The access token, containing authorization information and
information of the key used by the client, needs to be transported to information of the key used by the client, needs to be transported to
the RS so that the RS can authenticate and authorize the client the RS so that the RS can authenticate and authorize the client
request. request.
This section defines a method for transporting the access token to This section defines a method for transporting the access token to
the RS using CoAP. Profiles of this framework MAY define other the RS using CoAP. Profiles of this framework MAY define other
skipping to change at page 29, line 41 skipping to change at page 30, line 41
digest. Consequently, the token integrity protection MUST be applied digest. Consequently, the token integrity protection MUST be applied
to prevent the token from being modified, particularly since it to prevent the token from being modified, particularly since it
contains a reference to the symmetric key or the asymmetric key. If contains a reference to the symmetric key or the asymmetric key. If
the access token contains the symmetric key, this symmetric key MUST the access token contains the symmetric key, this symmetric key MUST
be encrypted by the authorization server with a long-term key shared be encrypted by the authorization server with a long-term key shared
with the resource server. with the resource server.
It is important for the authorization server to include the identity It is important for the authorization server to include the identity
of the intended recipient (the audience), typically a single resource of the intended recipient (the audience), typically a single resource
server (or a list of resource servers), in the token. Using a single server (or a list of resource servers), in the token. Using a single
shared secret with multiple authorization server to simplify key shared secret with multiple resource servers to simplify key
management is NOT RECOMMENDED since the benefit from using the proof- management is NOT RECOMMENDED since the benefit from using the proof-
of-possession concept is significantly reduced. of-possession concept is significantly reduced.
Token replay is also not possible since an eavesdropper will also Token replay is also not possible since an eavesdropper will also
have to obtain the corresponding private key or shared secret that is have to obtain the corresponding private key or shared secret that is
bound to the access token. Nevertheless, it is good practice to bound to the access token. Nevertheless, it is good practice to
limit the lifetime of the access token and therefore the lifetime of limit the lifetime of the access token and therefore the lifetime of
associated key. associated key.
The authorization server MUST offer confidentiality protection for The authorization server MUST offer confidentiality protection for
skipping to change at page 30, line 48 skipping to change at page 31, line 48
This specification registers new parameters for OAuth and establishes This specification registers new parameters for OAuth and establishes
registries for mappings to CBOR. registries for mappings to CBOR.
10.1. OAuth Introspection Response Parameter Registration 10.1. OAuth Introspection Response Parameter Registration
This specification registers the following parameters in the OAuth This specification registers the following parameters in the OAuth
introspection response parameters introspection response parameters
o Name: "cnf" o Name: "cnf"
o Description: Key to use to prove the right to use an access token, o Description: Key to prove the right to use an access token, as
as defined in [RFC7800]. defined in [RFC7800].
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Name: "aud" o Name: "aud"
o Description: reference to intended receiving RS, as defined in PoP o Description: Reference to intended receiving RS, as defined in PoP
token specification. token specification.
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): 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 Specification Document(s): this document o Specification Document(s): this document
skipping to change at page 31, line 38 skipping to change at page 32, line 38
This specification registers the following parameters in the OAuth This specification registers the following parameters in the OAuth
Parameters Registry Parameters Registry
o Parameter name: "profile" o Parameter name: "profile"
o Parameter usage location: token request, and token response o Parameter usage location: token request, and token response
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
o Name: "cnf" o Name: "cnf"
o Description: Key to use to prove the right to use an access token, o Description: Key to prove the right to use an access token, as
as defined in [RFC7800]. defined in [RFC7800].
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): this document
10.3. OAuth Access Token Types 10.3. OAuth Access Token Types
This specification registers the following new token type in the This specification registers the following new token type in the
OAuth Access Token Types Registry OAuth Access Token Types Registry
o Name: "PoP" o Name: "PoP"
o Description: A proof-of-possession token. o Description: A proof-of-possession token.
skipping to change at page 33, line 19 skipping to change at page 34, line 19
10.6. ACE Profile Registry 10.6. ACE Profile Registry
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.
10.6.1. Registration Template 10.6.1. Registration Template
Profile name: Profile name:
Name of the profile to be included in the profile attribute. Name of the profile to be included in the profile attribute.
Profile description: Profile description:
Text giving an over view of the profile and the context it is Text giving an overview of the profile and the context it is
developed for. developed for.
Profile ID: Profile ID:
Integer value to identify the profile. The value MUST be an Integer value to identify the profile. The value MUST be an
integer in the range of 1 to 65536. integer in the range of 1 to 65536.
Change Controller: Change Controller:
For Standards Track RFCs, list the "IESG". For others, give the For Standards Track RFCs, list the "IESG". For others, give the
name of the responsible party. Other details (e.g., postal name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included. address, email address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document or documents that specify the Reference to the document or documents that specify the
skipping to change at page 39, line 43 skipping to change at page 40, line 43
12.1. Normative References 12.1. Normative References
[I-D.ietf-ace-cbor-web-token] [I-D.ietf-ace-cbor-web-token]
Wahlstroem, E., Jones, M., Tschofenig, H., and S. Erdtman, Wahlstroem, E., Jones, M., Tschofenig, H., and S. Erdtman,
"CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-01 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-01
(work in progress), July 2016. (work in progress), July 2016.
[I-D.ietf-cose-msg] [I-D.ietf-cose-msg]
Schaad, J., "CBOR Object Signing and Encryption (COSE)", Schaad, J., "CBOR Object Signing and Encryption (COSE)",
draft-ietf-cose-msg-19 (work in progress), September 2016. draft-ietf-cose-msg-23 (work in progress), October 2016.
[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, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <http://www.rfc-editor.org/info/rfc6347>. January 2012, <http://www.rfc-editor.org/info/rfc6347>.
skipping to change at page 40, line 38 skipping to change at page 41, line 38
environments", draft-ietf-ace-actors-04 (work in environments", draft-ietf-ace-actors-04 (work in
progress), September 2016. progress), September 2016.
[I-D.ietf-oauth-device-flow] [I-D.ietf-oauth-device-flow]
Denniss, W., Myrseth, S., Bradley, J., Jones, M., and H. Denniss, W., Myrseth, S., Bradley, J., Jones, M., and H.
Tschofenig, "OAuth 2.0 Device Flow", draft-ietf-oauth- Tschofenig, "OAuth 2.0 Device Flow", draft-ietf-oauth-
device-flow-03 (work in progress), July 2016. device-flow-03 (work in progress), July 2016.
[I-D.ietf-oauth-native-apps] [I-D.ietf-oauth-native-apps]
Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
draft-ietf-oauth-native-apps-03 (work in progress), July draft-ietf-oauth-native-apps-05 (work in progress),
2016. October 2016.
[I-D.seitz-ace-core-authz] [I-D.seitz-ace-core-authz]
Seitz, L., Selander, G., and M. Vucinic, "Authorization Seitz, L., Selander, G., and M. Vucinic, "Authorization
for Constrained RESTful Environments", draft-seitz-ace- for Constrained RESTful Environments", draft-seitz-ace-
core-authz-00 (work in progress), June 2015. core-authz-00 (work in progress), June 2015.
[I-D.selander-ace-object-security] [I-D.selander-ace-object-security]
Selander, G., Mattsson, J., Palombini, F., and L. Seitz, Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security of CoAP (OSCOAP)", draft-selander-ace- "Object Security of CoAP (OSCOAP)", draft-selander-ace-
object-security-05 (work in progress), July 2016. object-security-06 (work in progress), October 2016.
[RFC4949] Shirey, R., "Internet Security Glossary, Version 2", [RFC4949] Shirey, R., "Internet Security Glossary, Version 2",
FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007,
<http://www.rfc-editor.org/info/rfc4949>. <http://www.rfc-editor.org/info/rfc4949>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, (TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008, DOI 10.17487/RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>. <http://www.rfc-editor.org/info/rfc5246>.
skipping to change at page 46, line 7 skipping to change at page 47, line 7
+ Store the token so that it can be retrieved in the context + Store the token so that it can be retrieved in the context
of a matching request. of a matching request.
* Process a request. * Process a request.
+ Set up communication security with the client. + Set up communication security with the client.
+ Authenticate the client. + Authenticate the client.
+ Match the client against existing tokens. + Match the client against existing tokens.
+ Check that tokens belonging to the client actually authorize + Check that tokens belonging to the client actually authorize
the requested action. the requested action.
+ Optionally: Check that the matching tokens are still valid + Optionally: Check that the matching tokens are still valid,
(if this is possible.) using introspection (if this is possible.)
* Send a response following the agreed upon communication * Send a response following the agreed upon communication
security. security.
Appendix C. Requirements on Profiles Appendix C. Requirements on Profiles
This section lists the requirements on profiles of this framework, This section lists the requirements on profiles of this framework,
for the convenience of a profile designer. All this information is for the convenience of a profile designer. All this information is
also given in the appropriate sections of the main document, this is also given in the appropriate sections of the main document, this is
just meant as a checklist, to make it more easy to spot parts one just meant as a checklist, to make it more easy to spot parts one
might have missed. might have missed.
 End of changes. 35 change blocks. 
92 lines changed or deleted 123 lines changed or added

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