draft-ietf-ace-oauth-authz-08.txt   draft-ietf-ace-oauth-authz-09.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: April 22, 2018 Ericsson Expires: May 20, 2018 Ericsson
E. Wahlstroem E. Wahlstroem
(no affiliation) (no affiliation)
S. Erdtman S. Erdtman
Spotify AB Spotify AB
H. Tschofenig H. Tschofenig
ARM Ltd. ARM Ltd.
October 19, 2017 November 16, 2017
Authentication and Authorization for Constrained Environments (ACE) Authentication and Authorization for Constrained Environments (ACE)
draft-ietf-ace-oauth-authz-08 draft-ietf-ace-oauth-authz-09
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 22, 2018. This Internet-Draft will expire on May 20, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 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
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10
5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.1. Discovering Authorization Servers . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . . . . . . . 16
5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17
5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 18 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 17
5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18
5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18
5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 19 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 18
5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 19 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 19
5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 22 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 21
5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 24 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 24
5.6.4. Request and Response Parameters . . . . . . . . . . . 25 5.6.4. Request and Response Parameters . . . . . . . . . . . 24
5.6.4.1. Audience . . . . . . . . . . . . . . . . . . . . 25 5.6.4.1. Audience . . . . . . . . . . . . . . . . . . . . 25
5.6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 25 5.6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 25
5.6.4.3. Token Type . . . . . . . . . . . . . . . . . . . 26 5.6.4.3. Token Type . . . . . . . . . . . . . . . . . . . 25
5.6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 26 5.6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 25
5.6.4.5. Confirmation . . . . . . . . . . . . . . . . . . 26 5.6.4.5. Confirmation . . . . . . . . . . . . . . . . . . 26
5.6.5. Mapping parameters to CBOR . . . . . . . . . . . . . 27 5.6.5. Mapping parameters to CBOR . . . . . . . . . . . . . 26
5.7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 28 5.7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 27
5.7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 29 5.7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 28
5.7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 29 5.7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 28
5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 30 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 29
5.7.4. Client Token . . . . . . . . . . . . . . . . . . . . 31 5.7.4. Client Token . . . . . . . . . . . . . . . . . . . . 30
5.7.5. Mapping Introspection parameters to CBOR . . . . . . 33 5.7.5. Mapping Introspection parameters to CBOR . . . . . . 32
5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 33 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 32
5.8.1. The 'Authorization Information' Endpoint . . . . . . 34 5.8.1. The 'Authorization Information' Endpoint . . . . . . 33
5.8.2. Token Expiration . . . . . . . . . . . . . . . . . . 35 5.8.2. Token Expiration . . . . . . . . . . . . . . . . . . 34
6. Security Considerations . . . . . . . . . . . . . . . . . . . 36 6. Security Considerations . . . . . . . . . . . . . . . . . . . 34
6.1. Unprotected AS Information . . . . . . . . . . . . . . . 37 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 36
6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 37 6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 36
6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 37 6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 36
6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 37 6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 36
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 38 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37
8.1. OAuth Introspection Response Parameter Registration . . . 39 8.1. Authorization Server Information . . . . . . . . . . . . 37
8.2. OAuth Parameter Registration . . . . . . . . . . . . . . 39 8.2. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 38
8.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 40 8.3. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 38
8.4. OAuth Token Type CBOR Mappings . . . . . . . . 40 8.4. OAuth Access Token Types . . . . . . . . . . . . . . . . 39
8.4.1. Registration Template . . . . . . . . . . . . . . . . 40 8.5. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 39
8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 40 8.5.1. Initial Registry Contents . . . . . . . . . . . . . . 40
8.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 41 8.6. ACE OAuth Profile Registry . . . . . . . . . . . . . . . 40
8.6. ACE OAuth Profile Registry . . . . . . . . . . . . . . . 41 8.7. OAuth Parameter Registration . . . . . . . . . . . . . . 40
8.6.1. Registration Template . . . . . . . . . . . . . . . . 41 8.8. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 41
8.7. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 41 8.9. OAuth Introspection Response Parameter Registration . . . 41
8.7.1. Registration Template . . . . . . . . . . . . . . . . 42 8.10. Introspection Endpoint CBOR Mappings Registry . . . . . . 42
8.7.2. Initial Registry Contents . . . . . . . . . . . . . . 42 8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 42
8.8. Introspection Endpoint CBOR Mappings Registry . . . . . . 44 8.12. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 42
8.8.1. Registration Template . . . . . . . . . . . . . . . . 44 8.13. CoAP Option Number Registration . . . . . . . . . . . . . 43
8.8.2. Initial Registry Contents . . . . . . . . . . . . . . 45 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43
8.9. CoAP Option Number Registration . . . . . . . . . . . . . 47 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 43
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47 10.1. Normative References . . . . . . . . . . . . . . . . . . 44
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 10.2. Informative References . . . . . . . . . . . . . . . . . 44
10.1. Normative References . . . . . . . . . . . . . . . . . . 48 Appendix A. Design Justification . . . . . . . . . . . . . . . . 47
10.2. Informative References . . . . . . . . . . . . . . . . . 49 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 51
Appendix A. Design Justification . . . . . . . . . . . . . . . . 51 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 53
Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 55 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 54
Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 57 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 54
Appendix D. Assumptions on AS knowledge about C and RS . . . . . 58 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 54
Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 58 E.2. Introspection Aided Token Validation . . . . . . . . . . 58
E.1. Local Token Validation . . . . . . . . . . . . . . . . . 58 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 62
E.2. Introspection Aided Token Validation . . . . . . . . . . 62 F.1. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 62
Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 66 F.2. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 62
F.1. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 66 F.3. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 63
F.2. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 67 F.4. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 63
F.3. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 67 F.5. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 63
F.4. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 67 F.6. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 64
F.5. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 67 F.7. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 64
F.6. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 67 F.8. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 64
F.7. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 68 F.9. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 64
F.8. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 65
F.9. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 68
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 69
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 6, line 15 skipping to change at page 5, line 51
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.
Another building block is the lightweight web transfer protocol CoAP Another building block is the lightweight web transfer protocol CoAP
[RFC7252], for those communication environments where HTTP is not [RFC7252], for those communication environments where HTTP is not
appropriate. CoAP typically runs on top of UDP, which further appropriate. CoAP typically runs on top of UDP, which further
reduces overhead and message exchanges. While this specification reduces overhead and message exchanges. While this specification
defines extensions for the use of OAuth over CoAP, other underlying defines extensions for the use of OAuth over CoAP, other underlying
protocols are not prohibited from beeing supported in the future, protocols are not prohibited from being supported in the future, such
such as HTTP/2, MQTT, BLE and QUIC. as HTTP/2, MQTT, BLE and QUIC.
A third building block is CBOR [RFC7049], for encodings where JSON A third building block is CBOR [RFC7049], for encodings where JSON
[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]
skipping to change at page 7, line 18 skipping to change at page 6, line 50
scoped access to a resource with the permission of a resource owner. scoped access to a resource with the permission of a resource owner.
Authorization information, or references to it, is passed between the Authorization information, or references to it, is passed between the
nodes using access tokens. These access tokens are issued to clients nodes using access tokens. These access tokens are issued to clients
by an authorization server with the approval of the resource owner. by an authorization server with the approval of the resource owner.
The client uses the access token to access the protected resources The client uses the access token to access the protected resources
hosted by the resource server. hosted by the resource server.
A number of OAuth 2.0 terms are used within this specification: A number of OAuth 2.0 terms are used within this specification:
The token and introspection Endpoints: The token and introspection 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).
In some deployments, a token introspection endpoint is provided by
In some deployments, a token introspection endpoint is provied by
the AS, which can be used by the RS if it needs to request the AS, which can be used by the RS if it needs to request
additional information regarding a received access token. The RS additional information regarding a received access token. The RS
makes a POST request to the introspecton endpoint on the AS and makes a POST request to the introspection endpoint on the AS and
receives information about the access token in the response. (See receives information about the access token in the 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 AS and consumed by the RS. The access tokens are generated by the AS and consumed by the RS. The access
token content is opaque to the client. token content is opaque to the client.
Access tokens can have different formats, and various methods of Access tokens can have different formats, and various methods of
utilization (e.g., cryptographic properties) based on the security utilization (e.g., cryptographic properties) based on the security
requirements of the given deployment. requirements of the given deployment.
skipping to change at page 8, line 20 skipping to change at page 7, line 45
verify that the key used by the client matches the one bound to verify that the key used by the client matches the one bound to
the access token. When this specification uses the term "access the access token. When this specification uses the term "access
token" it is assumed to be a PoP access token token unless token" it is assumed to be a PoP access token token unless
specifically stated otherwise. specifically stated otherwise.
The key bound to the access token (the PoP key) may use either The key bound to the access token (the PoP key) may use either
symmetric or asymmetric cryptography. The appropriate choice of symmetric or asymmetric cryptography. The appropriate choice of
the kind of cryptography depends on the constraints of the IoT the kind of cryptography depends on the constraints of the IoT
devices as well as on the security requirements of the use case. devices as well as on the security requirements of the use case.
Symmetric PoP key: The AS generates a random symmetric PoP key. Symmetric PoP key:
The key is either stored to be returned on introspection calls The AS generates a random symmetric PoP key. The key is either
or encrypted and included in the access token. The PoP key is stored to be returned on introspection calls or encrypted and
also encrypted for the client and sent together with the access included in the access token. The PoP key is also encrypted
token to the client. for the client and sent together with the access token to the
client.
Asymmetric PoP key: An asymmetric key pair is generated on the Asymmetric PoP key:
client and the public key is sent to the AS (if it does not An asymmetric key pair is generated on the client and the
already have knowledge of the client's public key). public key is sent to the AS (if it does not already have
Information about the public key, which is the PoP key in this knowledge of the client's public key). Information about the
case, is either stored to be returned on introspection calls or public key, which is the PoP key in this case, is either stored
included inside the access token and sent back to the to be returned on introspection calls or included inside the
requesting client. The RS can identify the client's public key access token and sent back to the requesting client. The RS
from the information in the token, which allows the client to can identify the client's public key from the information in
use the corresponding private key for the proof of possession. the token, which allows the client to use the corresponding
private key for the proof of possession.
The access token is either a simple reference, or a structured The access token is either a simple reference, or a structured
information object (e.g., CWT [I-D.ietf-ace-cbor-web-token]), information object (e.g., CWT [I-D.ietf-ace-cbor-web-token]),
protected by a cryptographic wrapper (e.g., COSE [RFC8152]). The protected by a cryptographic wrapper (e.g., COSE [RFC8152]). The
choice of PoP key does not necessarily imply a specific credential choice of PoP key does not necessarily imply a specific credential
type for the integrity protection of the token. 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 encoding as data formt, defined in Section 5, to request uses CBOR encoding as data format, defined in Section 5, to
scopes and to be informed what scopes the access token actually request scopes and to be informed what scopes the access token
authorizes. actually authorizes.
The values of the scope parameter are expressed as a list of The values of the scope parameter in OAuth 2.0 are expressed as a
space-delimited, case-sensitive strings, with a semantic that is list of space-delimited, case-sensitive strings, with a semantic
well-known to the AS and the RS. More details about the concept that is well-known to the AS and the RS. More details about the
of scopes is found under Section 3.3 in [RFC6749]. concept of scopes is found under Section 3.3 in [RFC6749].
Claims: Claims:
Information carried in the access token or returned from Information carried in the access token or returned from
introspection, called claims, is in the form of name-value pairs. introspection, called claims, is in the form of name-value pairs.
An access token may, for example, include a claim identifying the An access token may, for example, include a claim identifying the
AS that issued the token (via the "iss" claim) and what audience AS that issued the token (via the "iss" claim) and what audience
the access token is intended for (via the "aud" claim). The the access token is intended for (via the "aud" claim). The
audience of an access token can be a specific resource or one or audience of an access token can be a specific resource or one or
many resource servers. The resource owner policies influence what many resource servers. The resource owner policies influence what
claims are put into the access token by the authorization server. claims are put into the access token by the authorization server.
While the structure and encoding of the access token varies While the structure and encoding of the access token varies
skipping to change at page 14, line 15 skipping to change at page 13, line 39
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
2.0 for constrained environments, which constitutes the ACE 2.0 for constrained environments, which constitutes the ACE
framework. framework.
Credential Provisioning Credential Provisioning
For IoT, it cannot be assumed that the client and RS are part of a For IoT, it cannot be assumed that the client and RS are part of a
common key infrastructure, so the AS provisions credentials or common key infrastructure, so the AS provisions credentials or
associated information to allow mutual authentication. These associated information to allow mutual authentication. These
credentials need to be provided to the parties before or during credentials need to be provided to the parties before or during
the authentication protocol is executed, and may be re-used for the authentication protocol is executed, and may be re-used for
subsequent token requests. subsequent token requests.
Proof-of-Possession Proof-of-Possession
The ACE framework, by default, implements proof-of-possession for The ACE framework, by default, implements proof-of-possession for
access tokens, i.e., that the token holder can prove being a access tokens, i.e., that the token holder can prove being a
holder of the key bound to the token. The binding is provided by holder of the key bound to the token. The binding is provided by
the "cnf" claim [I-D.jones-ace-cwt-proof-of-possession] indicating the "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession] indicating
what key is used for proof-of-possession. If a client needs to what key is used for proof-of-possession. If a client needs to
submit a new access token e.g., to obtain additional access submit a new access token e.g., to obtain additional access
rights, they can request that the AS binds this token to the same rights, they can request that the AS binds this token to the same
key as the previous one. key as the previous one.
ACE Profiles ACE Profiles
The client or RS may be limited in the encodings or protocols it The client or RS may be limited in the encodings or protocols it
supports. To support a variety of different deployment settings, supports. To support a variety of different deployment settings,
specific interactions between client and RS are defined in an ACE specific interactions between client and RS are defined in an ACE
profile. In ACE framework the AS is expected to manage the profile. In ACE framework the AS is expected to manage the
matching of compatible profile choices between a client and an RS. matching of compatible profile choices between a client and an RS.
The AS informs the client of the selected profile using the The AS informs the client of the selected profile using the
"profile" parameter in the token response. "profile" parameter in the token response.
OAuth 2.0 requires the use of TLS both to protect the communication OAuth 2.0 requires the use of TLS both to protect the communication
between AS and client when requesting an access token; between client between AS and client when requesting an access token; between client
skipping to change at page 16, line 40 skipping to change at page 16, line 19
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.
/----------------+----------+-------------------\ /-------+----------+-----------------\
| Parameter name | CBOR Key | Major Type | | Name | CBOR Key | Major Type |
|----------------+----------+-------------------| |-------+----------+-----------------|
| AS | 0 | 3 (text string) | | AS | 0 | 3 (text string) |
| nonce | 5 | 2 (byte string) | | nonce | 5 | 2 (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 19, line 22 skipping to change at page 18, line 48
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.
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
implementations are not required to use this name and can define
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.
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], encoded as a CBOR
map. map, where the "scope" parameter can additionally be formatted as a
byte array, in order to allow compact encoding of complex scope
structures.
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
skipping to change at page 20, line 19 skipping to change at page 20, line 6
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, therefore the
Content-Type is "application/cbor". The content is displayed in CBOR Content-Type is "application/cbor". The content is displayed in CBOR
diagnostic notation, without abbreviations for better readability. diagnostic notation, without abbreviations for better readability.
Header: POST (Code=0.02) Header: POST (Code=0.02)
Uri-Host: "server.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"
} }
Figure 5: Example request for an access token bound to a symmetric Figure 5: Example request for an access token bound to a symmetric
key. key.
Figure 6 shows a request for a token with an asymmetric proof-of- Figure 6 shows a request for a token with an asymmetric proof-of-
possession key. Note that in this example COSE is used to provide possession key. Note that in this example COSE is used to provide
object-security, therefore the Content-Type is "application/cose". object-security, therefore the Content-Type is "application/cose".
Header: POST (Code=0.02) Header: POST (Code=0.02)
Uri-Host: "server.example.com" Uri-Host: "as.example.com"
Uri-Path: "token" Uri-Path: "token"
Content-Type: "application/cose" Content-Type: "application/cose"
Payload: Payload:
"COSE_Encrypted" : { 16( # COSE_ENCRYPTED
16(
[ h'a1010a', # protected header: {"alg" : "AES-CCM-16-64-128"} [ h'a1010a', # protected header: {"alg" : "AES-CCM-16-64-128"}
{5 : b64'ifUvZaHFgJM7UmGnjA'}, # unprotected header, IV {5 : b64'ifUvZaHFgJM7UmGnjA'}, # unprotected header, IV
b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext
] ]
) )
}
Decrypted payload: Decrypted payload:
{ {
"grant_type" : "client_credentials", "grant_type" : "client_credentials",
"client_id" : "myclient", "client_id" : "myclient",
"cnf" : { "cnf" : {
"COSE_Key" : { "COSE_Key" : {
"kty" : "EC", "kty" : "EC",
"kid" : h'11', "kid" : h'11',
"crv" : "P-256", "crv" : "P-256",
skipping to change at page 22, line 6 skipping to change at page 21, line 14
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 is assumed in this
example, therefore the Content-Type is "application/cbor". Also note example, therefore the Content-Type is "application/cbor". Also note
that the client performs a password based authentication in this that the client performs a password based authentication in this
example by submitting its client_secret (see section 2.3.1. of example by submitting its client_secret (see section 2.3.1. of
[RFC6749]). [RFC6749]).
Header: POST (Code=0.02) Header: POST (Code=0.02)
Uri-Host: "server.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",
"aud" : "valve424", "aud" : "valve424",
"scope" : "read", "scope" : "read",
"cnf" : { "cnf" : {
skipping to change at page 22, line 44 skipping to change at page 22, line 5
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. It MUST
be encoded as CBOR map, containing parameters as specified in section be encoded as CBOR map, containing parameters as specified in section
5.1 of [RFC6749]. In addition to these parameters, the following 5.1 of [RFC6749]. In addition to these parameters, the following
parameters are also part of a successful response: parameters are also part of a successful response:
profile profile OPTIONAL. This indicates the profile that the client MUST
OPTIONAL. This indicates the profile that the client MUST use use towards the RS. See Section 5.6.4.4 for the formatting of
towards the RS. See Section 5.6.4.4 for the formatting of this this parameter.
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 cnf REQUIRED if the token type is "pop" and a symmetric key is used.
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 rs_cnf OPTIONAL if the token type is "pop" and asymmetric keys are
OPTIONAL if the token type is "pop" and asymmetric keys are used. used. MUST NOT be present otherwise. This field contains
MUST NOT be present otherwise. This field contains information information about the public key used by the RS to authenticate.
about the public key used by the RS to authenticate. See See Section 5.6.4.5 for details on the use of this parameter. If
Section 5.6.4.5 for details on the use of this parameter. If this this parameter is absent, the AS assumes that the client already
parameter is absent, the AS assumes that the client already knows knows the public key of the RS.
the public key of the RS. token_type OPTIONAL. By default implementations of this framework
token_type SHOULD assume that the token_type is "pop". If a specific use
OPTIONAL. By default implementations of this framework SHOULD case requires another token_type (e.g., "Bearer") to be used then
assume that the token_type is "pop". If a specific use case this parameter is REQUIRED.
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.jones-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
Information. Information.
/-------------------+--------------------------\ /-------------------+-----------------\
| Parameter name | Specified in | | Parameter name | Specified in |
|-------------------+--------------------------| |-------------------+-----------------|
| access_token | RFC 6749 | | access_token | RFC 6749 |
| token_type | RFC 6749 | | token_type | RFC 6749 |
| expires_in | RFC 6749 | | expires_in | RFC 6749 |
| refresh_token | RFC 6749 | | refresh_token | RFC 6749 |
| scope | RFC 6749 | | scope | RFC 6749 |
| state | RFC 6749 | | state | RFC 6749 |
| error | RFC 6749 | | error | RFC 6749 |
| error_description | RFC 6749 | | error_description | RFC 6749 |
| error_uri | RFC 6749 | | error_uri | RFC 6749 |
| profile | [[ this specification ]] | | profile | [this document] |
| cnf | [[ this specification ]] | | cnf | [this document] |
| rs_cnf | [[ this specification ]] | | 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 is assumed in this example, therefore the Content-Type is
"application/cbor". "application/cbor".
Header: Created (Code=2.01) Header: Created (Code=2.01)
Content-Type: "application/cbor" Content-Type: "application/cbor"
skipping to change at page 25, line 5 skipping to change at page 24, line 25
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.
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.
/------------------------+-------------------\ /------------------------+----------\
| error code | CBOR Value (uint) | | 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 |
| unsupported_pop_key | 6 | | unsupported_pop_key | 6 |
\------------------------+-------------------/ \------------------------+----------/
Figure 10: CBOR abbreviations for common error codes Figure 10: CBOR abbreviations for common error codes
In addition to the error responses defined in OAuth 2.0, the In addition to the error responses defined in OAuth 2.0, the
following behavior MUST be implemented by the AS: If the client following behavior MUST be implemented by the AS: If the client
submits an asymmetric key in the token request that the RS cannot submits an asymmetric key in the token request that the RS cannot
process, the AS MUST reject that request with a response code process, the AS MUST reject that request with a response code
equivalent to the CoAP code 4.00 (Bad Request) including the error equivalent to the CoAP code 4.00 (Bad Request) including the error
code "unsupported_pop_key" defined in Figure 10. code "unsupported_pop_key" defined in Figure 10.
skipping to change at page 26, line 5 skipping to change at page 25, line 17
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. It should be encoded as CBOR text string (major type 3).
The formatting and semantics of these strings are application The formatting and semantics of these strings are application
specific. specific.
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].
/--------------------+-------------------\ /--------------------+----------+------------------------\
| grant_type | CBOR Value (uint) | | Name | CBOR Key | Original Specification |
|--------------------+-------------------| |--------------------+----------+------------------------|
| password | 0 | | password | 0 | RFC6749 |
| authorization_code | 1 | | authorization_code | 1 | RFC6749 |
| client_credentials | 2 | | client_credentials | 2 | RFC6749 |
| refresh_token | 3 | | refresh_token | 3 | RFC6749 |
\--------------------+-------------------/ \--------------------+----------+------------------------/
Figure 11: CBOR abbreviations for common grant types Figure 11: CBOR abbreviations for common grant types
5.6.4.3. Token Type 5.6.4.3. Token Type
The token_type parameter is defined in [RFC6749], allowing the AS to The token_type parameter 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
skipping to change at page 27, line 5 skipping to change at page 26, line 17
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.jones-ace-cwt-proof-of-possession]. the "cnf" claim specified in [I-D.ietf-ace-cwt-proof-of-possession].
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-
skipping to change at page 28, line 5 skipping to change at page 27, line 5
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.
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 | Type | | Name | CBOR Key | Major 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 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 |
| error_description | 16 | text string | | error_description | 16 | text string |
| error_uri | 17 | text string | | error_uri | 17 | text string |
| grant_type | 18 | unsigned integer | | grant_type | 18 | unsigned integer |
| access_token | 19 | text string | | access_token | 19 | text string |
| token_type | 20 | unsigned integer | | token_type | 20 | unsigned integer |
| expires_in | 21 | unsigned integer | | expires_in | 21 | unsigned integer |
| username | 22 | text string | | username | 22 | text string |
| password | 23 | text string | | password | 23 | text string |
| refresh_token | 24 | text string | | refresh_token | 24 | text string |
| cnf | 25 | map | | cnf | 25 | map |
| profile | 26 | text string | | profile | 26 | text string |
| rs_cnf | 31 | map | | rs_cnf | 31 | map |
\-------------------+----------+------------------/ \-------------------+----------+---------------------/
Figure 12: CBOR mappings used in token requests Figure 12: CBOR mappings used in token requests
5.7. The 'Introspect' Endpoint 5.7. The 'Introspect' Endpoint
Token introspection [RFC7662] can be OPTIONALLY provided by the AS, Token introspection [RFC7662] can be OPTIONALLY provided by the AS,
and is then used by the RS and potentially the client to query the AS and is then used by the RS and potentially the client to query the AS
for metadata about a given token e.g., validity or scope. Analogous for metadata about a given token e.g., validity or scope. Analogous
to the protocol defined in RFC 7662 [RFC7662] for HTTP and JSON, this to the protocol defined in RFC 7662 [RFC7662] for HTTP and JSON, this
section defines adaptations to more constrained environments using section defines adaptations to more constrained environments using
skipping to change at page 29, line 5 skipping to change at page 28, line 5
profile. profile.
Communication between the RS and the introspection endpoint at the AS Communication between the RS and the introspection endpoint at the AS
MUST be integrity protected and encrypted. Furthermore AS and RS MUST be integrity protected and encrypted. Furthermore AS and RS
MUST perform mutual authentication. Finally the AS SHOULD verify MUST perform mutual authentication. Finally the AS SHOULD verify
that the RS has the right to access introspection information about that the RS has the right to access introspection information about
the provided token. Profiles of this framework that support the provided token. Profiles of this framework that support
introspection MUST specify how authentication and communication introspection MUST specify how authentication and communication
security between RS and AS is implemented. security between RS and AS is implemented.
The default name of this endpoint in an url-path is 'introspect',
however implementations are not required to use this name and can
define their own instead.
The figures of this section uses CBOR diagnostic notation without the The figures of this section uses CBOR diagnostic notation without the
integer abbreviations for the parameters or their values for better integer abbreviations for the parameters or their values for better
readability. readability.
Note that supporting introspection is OPTIONAL for implementations of Note that supporting introspection is OPTIONAL for implementations of
this framework. this framework.
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,
skipping to change at page 29, line 31 skipping to change at page 28, line 35
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: "server.example.com" Uri-Host: "as.example.com"
Uri-Path: "introspect" Uri-Path: "introspect"
Content-Type: "application/cose+cbor" Content-Type: "application/cose+cbor"
Payload: Payload:
{ {
"token" : b64'7gj0dXJQ43U', "token" : b64'7gj0dXJQ43U',
"token_type_hint" : "pop" "token_type_hint" : "pop"
} }
Figure 13: Example introspection request. Figure 13: Example introspection request.
skipping to change at page 30, line 5 skipping to change at page 29, line 9
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 cnf OPTIONAL. This field contains information about the proof-of-
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 with the client. See Section 5.6.4.4 for more details on the
OPTIONAL. This indicates the profile that the RS MUST use 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
client_token RS MUST pass on to the client. See Section 5.7.4 for more
OPTIONAL. This parameter contains information that the RS MUST details.
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,
skipping to change at page 32, line 29 skipping to change at page 31, line 29
| | + Client Token | | | + Client Token |
|<---------------+ | |<---------------+ |
| 2.01 Created | | | 2.01 Created | |
| + Client Token | | + Client Token |
Figure 15: Use of the client_token parameter. Figure 15: Use of the client_token parameter.
The client token is a COSE_Encrypted 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.
REQUIRED if the token type is "pop", OPTIONAL otherwise. Contains Contains information about the proof-of-possession key the client
information about the proof-of-possession key the client is to use is to use with its access token. See Section 5.6.4.5.
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.
token_type rs_cnf OPTIONAL. Contains information about the key that the RS
OPTIONAL. See Section 5.6.4.3. uses to authenticate towards the client. If the key is symmetric
then this claim MUST NOT be part of the Client Token, since this
profile is the same key as the one specified through the "cnf" claim.
REQUIRED. See Section 5.6.4.4. This claim uses the same encoding as the "cnf" parameter. See
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. Section 5.6.4.4.
The AS encrypts this token using a key shared between the AS and the 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 client, so that only the client can decrypt it and access its
payload. How this key is established is out of scope of this payload. How this key is established is out of scope of this
framework, however it can be established at the same time at which framework, however it can be established at the same time at which
the client's long term token is created. the client's long term token is created.
An RS that is configured to perform introspection, MUST do so An RS that is configured to perform introspection, MUST do so
immediately after receiving an access token, in order to be able to immediately after receiving an access token, in order to be able to
return a potential client token to the client. This does not return a potential client token to the client. This does not
preclude the RS to perform additional introspection asynchronously, preclude the RS to perform additional introspection asynchronously,
e.g., when the token is later used. e.g., when the token is later used.
5.7.5. Mapping Introspection parameters to CBOR 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 16, using the given integer
abbreviation for the key. abbreviation for the key.
Note that we have aligned these abbreviatations 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 | Major Type |
|-----------------+----------+-----------------| |-----------------+----------+-----------------------|
| iss | 1 | 3 (text string) | | iss | 1 | text string |
| sub | 2 | 3 | | sub | 2 | text string |
| aud | 3 | 3 | | aud | 3 | text string |
| exp | 4 | 6 tag value 1 | | exp | 4 | Epoch-based date/time |
| nbf | 5 | 6 tag value 1 | | nbf | 5 | Epoch-based date/time |
| iat | 6 | 6 tag value 1 | | iat | 6 | Epoch-based date/time |
| cti | 7 | 2 (byte string) | | cti | 7 | byte string |
| client_id | 8 | 3 | | client_id | 8 | text string |
| scope | 12 | 3 | | scope | 12 | text OR byte string |
| token_type | 20 | 3 | | token_type | 20 | text string |
| username | 22 | 3 | | username | 22 | text string |
| cnf | 25 | 5 (map) | | cnf | 25 | map |
| profile | 26 | 0 (uint) | | profile | 26 | unsigned integer |
| token | 27 | 3 | | token | 27 | text string |
| token_type_hint | 28 | 3 | | token_type_hint | 28 | text string |
| active | 29 | 0 | | active | 29 | unsigned integer |
| client_token | 30 | 3 | | client_token | 30 | byte string |
| rs_cnf | 31 | 5 | | rs_cnf | 31 | map |
\-----------------+----------+-----------------/ \-----------------+----------+-----------------------/
Figure 16: CBOR Mappings to Token Introspection Parameters. Figure 16: CBOR Mappings to Token Introspection Parameters.
5.8. The Access Token 5.8. The Access Token
This framework RECOMMENDS the use of CBOR web token (CWT) as This framework RECOMMENDS the use of CBOR web token (CWT) as
specified in [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.jones-ace-cwt-proof-of-possession] and specifies the "scope" claim for both JSON and CBOR web tokens.
claim 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], but in addition implementers MAY use byte
application specific and expected to be known to the RS running that arrays as scope values, to achieve compact encoding of large scope
application. elements. The meaning of a specific scope value is 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.
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 a RESTful protocol such as CoAP. Profiles of this the RS using a RESTful protocol such as CoAP. Profiles of this
skipping to change at page 35, line 12 skipping to change at page 34, line 5
responding to the POST request to the authz-info endpoint. If the responding to the POST request to the authz-info endpoint. If the
introspection response contains a client token (Section 5.7.4) then introspection response contains a client token (Section 5.7.4) then
this token SHALL be included in the payload of the 2.01 (Created) this token SHALL be included in the payload of the 2.01 (Created)
response. 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',
however implementations are not required to use this name and can
define their own instead.
5.8.2. Token Expiration 5.8.2. Token Expiration
Depending on the capabilities of the RS, there are various ways in Depending on the capabilities of the RS, there are various ways in
which it can verify the validity of a received access token. Here which it can verify the validity of a received access token. Here
follows a list of the possibilities including what functionality they follows a list of the possibilities including what functionality they
require of the RS. require of the RS.
o The token is a CWT and includes an "exp" claim and possibly the o The token is a CWT and includes an "exp" claim and possibly the
"nbf" claim. The RS verifies these by comparing them to values "nbf" claim. The RS verifies these by comparing them to values
from its internal clock as defined in [RFC7519]. In this case the from its internal clock as defined in [RFC7519]. In this case the
skipping to change at page 39, line 8 skipping to change at page 37, line 46
relationship with C. It is advisable to include as little relationship with C. It is advisable to include as little
information as possible in an unencrypted response. Means of information as possible in an unencrypted response. Means of
encrypting communication between C and RS already exist, more encrypting communication between C and RS already exist, more
detailed information may be included with an error response to detailed information may be included with an error response to
provide C with sufficient information to react on that particular provide C with sufficient information to react on that particular
error. error.
8. IANA Considerations 8. IANA Considerations
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 abbreviations.
8.1. OAuth Introspection Response Parameter Registration 8.1. Authorization Server Information
This specification registers the following parameters in the OAuth A new registry will be requested from IANA, entitled "Authorization
introspection response parameters Server Information". The registry is to be created as Expert Review
Required.
o Name: "cnf" The columns of this table are:
o Description: Key to prove the right to use an access token,
formatted as specified in [I-D.jones-ace-cwt-proof-of-possession].
o Change Controller: IESG
o Specification Document(s): this document
o Name: "profile" Name The name of the parameter
o Description: The communication and communication security profile CBOR Key The unsigned integer value (CBOR major type 0) abbreviating
used between client and RS, as defined in ACE profiles. this parameter name. Registration in the table is based on the
o Change Controller: IESG value of the mapping requested. Integer values between 1 and 255
o Specification Document(s): this document are 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.
Major Type The CBOR major type allowable for the values of this
parameter.
Reference This contains a pointer to the public specification of the
grant type abbreviation, if one exists.
o Name: "client_token" This registry will be initially populated by the values in Figure 2.
o Description: Information that the RS MUST pass to the client e.g., The Reference column for all of these entries will be this document.
about the proof-of-possession keys.
o Change Controller: IESG
o Specification Document(s): this document
o Name: "rs_cnf" 8.2. OAuth Error Code CBOR Mappings Registry
o Description: Describes the public key the RS uses to authenticate.
o Change Controller: IESG
o Specification Document(s): this document
8.2. OAuth Parameter Registration A new registry will be requested from IANA, entitled "OAuth Error
Code CBOR Mappings Registry". The registry is to be created as
Expert Review Required.
This specification registers the following parameters in the OAuth The columns of this table are:
Parameters Registry
o Parameter name: "profile" Name The OAuth Error Code name, refers to the name in section 5.2.
o Parameter usage location: token request, and token response of [RFC6749] e.g., "invalid_request".
o Change Controller: IESG CBOR Key The unsigned integer value (CBOR major type 0) abbreviating
o Specification Document(s): this document this error code. Registration in the table is based on the value
of the mapping requested. Integer values between 1 and 255 are
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.
Reference This contains a pointer to the public specification of the
grant type abbreviation, if one exists.
o Name: "cnf" This registry will be initially populated by the values in Figure 10.
o Description: Key to prove the right to use an access token, The Reference column for all of these entries will be this document.
formatted as defined in [I-D.jones-ace-cwt-proof-of-possession].
o Change Controller: IESG
o Specification Document(s): this document
8.3. OAuth Access Token Types 8.3. OAuth Grant Type CBOR Mappings
A new registry will be requested from IANA, entitled "OAuth Grant
Type CBOR Mappings". The registry is to be created as Expert Review
Required.
The columns of this table are:
Name The name of the grant type as specified in Section 1.3 of
[RFC6749].
CBOR Key The unsigned integer value (CBOR major type 0) abbreviating
this grant type. Registration in the table is based on the value
of the mapping requested. Integer values between 1 and 255 are
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.
Reference This contains a pointer to the public specification of the
grant type abbreviation, if one exists.
Original Specification This contains a pointer to the public
specification of the grant type, if one exists.
This registry will be initially populated by the values in Figure 11.
The Reference column for all of these entries will be this document.
8.4. 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 Change Controller: IETF
o Change Controller: IESG o Reference: [this document]
o Specification Document(s): this document
8.4. OAuth Token Type CBOR Mappings 8.5. OAuth Token Type CBOR Mappings
A new registry will be requested from IANA, entitled "Token Type 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.
8.4.1. Registration Template The columns of this table are:
Token Type:
Name of token type as registered in the OAuth token type registry
e.g., "Bearer".
Mapped value:
Integer representation for the token type value. The key value
MUST be an integer. Integer values from -65536 to 65535 are
designated as Specification Required. Integer values of greater
than 65535 designated as expert review. Integer values less than
-65536 are marked as private use.
Change Controller:
For Standards Track RFCs, list the "IESG". For others, give the
name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included.
Specification Document(s):
Reference to the document or documents that specify the
parameter,preferably including URIs that can be used to retrieve
copies of the documents. An indication of the relevant sections
may also be included but is not required.
8.4.2. Initial Registry Contents
o Parameter name: "Bearer"
o Mapped value: 1
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "pop" Name The name of token type as registered in the OAuth Access Token
o Mapped value: 2 Types registry e.g., "Bearer".
o Change Controller: IESG CBOR Key The unsigned integer value (CBOR major type 0) abbreviating
o Specification Document(s): this document this access token type. Registration in the table is based on the
value of the mapping requested. Integer values between 1 and 255
are 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.
Reference This contains a pointer to the public specification of the
OAuth token type abbreviation, if one exists.
Original Specification This contains a pointer to the public
specification of the grant type, if one exists.
8.5. CBOR Web Token Claims 8.5.1. Initial Registry Contents
This specification registers the following new claims in the CBOR Web o Name: "Bearer"
Token (CWT) registry: o Value: 1
o Reference: [this document]
o Original Specification: [RFC6749]
o Claim Name: "scope" o Name: "pop"
o Claim Description: The scope of an access token as defined in o Value: 2
[RFC6749]. o Reference: [this document]
o Change Controller: IESG o Original Specification: [this document]
o Specification Document(s): this document
8.6. ACE OAuth Profile Registry 8.6. ACE OAuth 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.
8.6.1. Registration Template The columns of this table are:
Profile name:
Name of the profile to be included in the profile attribute.
Profile description:
Text giving an overview of the profile and the context it is
developed for.
Profile ID:
Integer value to identify the profile. Integer values from -65536
to 65535 are designated as Specification Required. Integer values
of greater than 65535 designated as expert review. Integer values
less than -65536 are marked as private use.
Change Controller:
For Standards Track RFCs, list the "IESG". For others, give the
name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included.
Specification Document(s):
Reference to the document or documents that specify the
parameter,preferably including URIs that can be used to retrieve
copies of the documents. An indication of the relevant sections
may also be included but is not required.
8.7. OAuth CBOR Parameter Mappings Registry
A new registry will be requested from IANA, entitled "Token Endpoint
CBOR Mappings Registry". The registry is to be created as Expert
Review Required.
8.7.1. Registration Template
Parameter name:
OAuth Parameter name, refers to the name in the OAuth parameter
registry e.g., "client_id".
CBOR key value:
Key value for the claim. The key value MUST be an integer.
Integer values from -65536 to 65535 are designated as
Specification Required. Integer values of greater than 65535
designated as expert review. Integer values less than -65536 are
marked as private use.
Change Controller:
For Standards Track RFCs, list the "IESG". For others, give the
name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included.
Specification Document(s):
Reference to the document or documents that specify the
parameter,preferably including URIs that can be used to retrieve
copies of the documents. An indication of the relevant sections
may also be included but is not required.
8.7.2. Initial Registry Contents
o Parameter name: "aud"
o CBOR key value: 3
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "client_id"
o CBOR key value: 8
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "client_secret" Name The name of the profile, to be used as value of the profile
o CBOR key value: 9 attribute.
o Change Controller: IESG Description Text giving an overview of the profile and the context
o Specification Document(s): this document it is developed for.
CBOR Key The unsigned integer value (CBOR major type 0) abbreviating
this profile name. Registration in the table is based on the
value of the mapping requested. Integer values between 1 and 255
are 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.
Reference This contains a pointer to the public specification of the
profile abbreviation, if one exists.
o Parameter name: "response_type" 8.7. OAuth Parameter Registration
o CBOR key value: 10
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "redirect_uri" This specification registers the following parameters in the OAuth
o CBOR key value: 11 Parameters Registry
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "scope"
o CBOR key value: 12
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "state" o Name: "profile"
o CBOR key value: 13 o Parameter Usage Location: token request, token response
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Reference: Section 5.6.4.4 of [this document]
o Parameter name: "code" o Name: "cnf"
o CBOR key value: 14 o Parameter Usage Location: token request, token response
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Reference: Section 5.6.4.5 of [this document]
o Parameter name: "error" o Name: "rs_cnf"
o CBOR key value: 15 o Parameter Usage Location: token response
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Reference: Section 5.6.4.5 of [this document]
o Parameter name: "error_description" 8.8. OAuth CBOR Parameter Mappings Registry
o CBOR key value: 16
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "error_uri" A new registry will be requested from IANA, entitled "Token Endpoint
o CBOR key value: 17 CBOR Mappings Registry". The registry is to be created as Expert
o Change Controller: IESG Review Required.
o Specification Document(s): this document
o Parameter name: "grant_type" The columns of this table are:
o CBOR key value: 18
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "access_token" Name The OAuth Parameter name, refers to the name in the OAuth
o CBOR key value: 19 parameter registry e.g., "client_id".
o Change Controller: IESG CBOR Key The unsigned integer value (CBOR major type 0) abbreviating
o Specification Document(s): this document this parameter. Registration in the table is based on the value
of the mapping requested. Integer values between 1 and 255 are
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.
Major Type The allowable CBOR data types for values of this
parameter.
Reference This contains a pointer to the public specification of the
grant type abbreviation, if one exists.
o Parameter name: "token_type" This registry will be initially populated by the values in Figure 12.
o CBOR key value: 20 The Reference column for all of these entries will be this document.
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "expires_in" Note that these mappings intentionally coincide with the CWT claim
o CBOR key value: 21 name mappings from [I-D.ietf-ace-cbor-web-token].
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "username" 8.9. OAuth Introspection Response Parameter Registration
o CBOR key value: 22
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "password" This specification registers the following parameters in the OAuth
o CBOR key value: 23 Token Introspection Response registry.
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "refresh_token" o Name: "cnf"
o CBOR key value: 24 o Description: Key to prove the right to use an access token,
formatted as specified in [I-D.ietf-ace-cwt-proof-of-possession].
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Reference: Section 5.7.2 of [this document]
o Parameter name: "cnf" o Name: "profile"
o CBOR key value: 25 o Description: The communication and communication security profile
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 Reference: Section 5.7.2 of [this document]
o Name: "client_token"
o Parameter name: "profile" o Description: Information that the RS MUST pass to the client e.g.,
o CBOR key value: 26 about the proof-of-possession keys.
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Reference: Section 5.7.2 of [this document]
8.8. 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.
8.8.1. Registration Template The columns of this table are:
Response parameter name:
Name of the response parameter as defined in the "OAuth Token
Introspection Response" registry e.g., "active".
CBOR key value:
Key value for the claim. The key value MUST be an integer.
Integer values from -65536 to 65535 are designated as
Specification Required. Integer values of greater than 65535
designated as expert review. Integer values less than -65536 are
marked as private use.
Change Controller:
For Standards Track RFCs, list the "IESG". For others, give the
name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included.
Specification Document(s):
Reference to the document or documents that specify the
parameter,preferably including URIs that can be used to retrieve
copies of the documents. An indication of the relevant sections
may also be included but is not required.
8.8.2. Initial Registry Contents
o Response parameter name: "iss"
o CBOR key value: 1
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "sub"
o CBOR key value: 2
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "aud"
o CBOR key value: 3
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "exp"
o CBOR key value: 4
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "nbf"
o CBOR key value: 5
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "iat"
o CBOR key value: 6
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "cti"
o CBOR key value: 7
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "client_id"
o CBOR key value: 8
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "scope"
o CBOR key value: 12
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "token_type"
o CBOR key value: 20
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "username" Name The OAuth Parameter name, refers to the name in the OAuth
o CBOR key value: 22 parameter registry e.g., "client_id".
o Change Controller: IESG CBOR Key The unsigned integer value (CBOR major type 0) abbreviating
o Specification Document(s): this document this parameter. Registration in the table is based on the value
of the mapping requested. Integer values between 1 and 255 are
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.
Major Type The allowable CBOR data types for values of this
parameter.
Reference This contains a pointer to the public specification of the
grant type abbreviation, if one exists.
o Parameter name: "cnf" This registry will be initially populated by the values in Figure 16.
o CBOR key value: 25 The Reference column for all of these entries will be this document.
o Change Controller: IESG
o Specification Document(s): this document
o Parameter name: "profile" 8.11. JSON Web Token Claims
o CBOR key value: 26
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "token" This specification registers the following new claims in the JSON Web
o CBOR key value: 27 Token (JWT) registry of JSON Web Token Claims:
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "token_type_hint" o Claim Name: "scope"
o CBOR key value: 28 o Claim Description: The scope of an access token as defined in
[RFC6749].
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Reference: Section 5.8 of [this document]
o Response parameter name: "active" 8.12. CBOR Web Token Claims
o CBOR key value: 29
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "client_token" This specification registers the following new claims in the CBOR Web
o CBOR key value: 30 Token (CWT) registry of CBOR Web Token Claim:s
o Change Controller: IESG
o Specification Document(s): this document
o Response parameter name: "rs_cnf" o Claim Name: "scope"
o CBOR key value: 31 o Claim Description: The scope of an access token as defined in
[RFC6749].
o JWT Claim Name: N/A
o Claim Key: 12
o Claim Value Type(s): 0 (uint), 2 (byte string), 3 (text string)
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): this document o Specification Document(s): Section 5.8 of [this document]
8.9. CoAP Option Number Registration 8.13. CoAP Option Number Registration
This section registers the "Access-Token" CoAP Option Number in the This section registers the "Access-Token" CoAP Option Number in the
"CoRE Parameters" sub-registry "CoAP Option Numbers" in the manner "CoRE Parameters" sub-registry "CoAP Option Numbers" in the manner
described in [RFC7252]. described in [RFC7252].
Name o Name: "Access-Token"
o Number: TBD
Access-Token o Reference: [this document].
Number o Meaning in Request: Contains an Access Token according to [this
document] containing access permissions of the client.
TBD o Meaning in Response: Not used in response.
Reference o Safe-to-Forward: Yes
o Format: Based on the observer the format is perceived differently.
[This document]. Opaque data to the client and CWT or reference token to the RS.
Meaning in Request o Length: Less than 255 bytes
Contains an Access Token according to [This document] containing
access permissions of the client.
Meaning in Response
Not used in response
Safe-to-Forward
Yes
Format
Based on the observer the format is perceived differently. Opaque
data to the client and CWT or reference token to the RS.
Length
Less then 255 bytes
9. Acknowledgments 9. Acknowledgments
This document is a product of the ACE working group of the IETF. This document is a product of the ACE working group of the IETF.
Thanks to Eve Maler for her contributions to the use of OAuth 2.0 and Thanks to Eve Maler for her contributions to the use of OAuth 2.0 and
UMA in IoT scenarios, Robert Taylor for his discussion input, and UMA in IoT scenarios, Robert Taylor for his discussion input, and
Malisa Vucinic for his input on the predecessors of this proposal. Malisa Vucinic for his input on the predecessors of this proposal.
Thanks to the authors of draft-ietf-oauth-pop-key-distribution, from Thanks to the authors of draft-ietf-oauth-pop-key-distribution, from
skipping to change at page 48, line 13 skipping to change at page 44, line 4
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-08 "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-09
(work in progress), August 2017. (work in progress), October 2017.
[I-D.jones-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-jones-ace- Semantics for CBOR Web Tokens (CWTs)", draft-ietf-ace-cwt-
cwt-proof-of-possession-01 (work in progress), June 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-
editor.org/info/rfc2119>. editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
skipping to change at page 49, line 10 skipping to change at page 44, line 49
[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-01 (work in progress), August 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-05 (work in environments", draft-ietf-ace-actors-06 (work in
progress), March 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-05 (work in (OSCORE)", draft-ietf-core-object-security-06 (work in
progress), September 2017. progress), October 2017.
[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-11 (work in progress), July 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-06 Constrained Devices", draft-ietf-oauth-device-flow-07
(work in progress), May 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-07 (work in progress), September 2017.
[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-12 (work in progress), June draft-ietf-oauth-native-apps-12 (work in progress), June
2017. 2017.
skipping to change at page 53, line 49 skipping to change at page 49, line 49
concerning the RS that the AS returns to the client in an access concerning the RS that the AS returns to the client in an access
token response (see Section 5.6.2). This includes the "profile" token response (see Section 5.6.2). This includes the "profile"
and the "rs_cnf" parameters. This aims at enabling scenarios, and the "rs_cnf" parameters. This aims at enabling scenarios,
where a powerful client, supporting multiple profiles, needs to where a powerful client, supporting multiple profiles, needs to
interact with a RS for which it does not know the supported interact with a RS for which it does not know the supported
profiles and the raw public key. profiles and the raw public key.
Proof-of-Possession: Proof-of-Possession:
This framework makes use of proof-of-possession tokens, using the This framework makes use of proof-of-possession tokens, using the
"cnf" claim [I-D.jones-ace-cwt-proof-of-possession]. A "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession]. A
semantically and syntactically identical request and response semantically and syntactically identical request and response
parameter is defined for the token endpoint, to allow requesting parameter is defined for the token endpoint, to allow requesting
and stating confirmation keys. This aims at making token theft and stating confirmation keys. This aims at making token theft
harder. Token theft is specifically relevant in constrained use harder. Token theft is specifically relevant in constrained use
cases, as communication often passes through middle-boxes, which cases, as communication often passes through middle-boxes, which
could be able to steal bearer tokens and use them to gain could be able to steal bearer tokens and use them to gain
unauthorized access. unauthorized access.
Auth-Info endpoint: Auth-Info endpoint:
skipping to change at page 56, line 12 skipping to change at page 52, line 12
* Process a token request using the authorization policies * Process a token request using the authorization policies
configured for the RS. configured for the RS.
* Optionally: Expose the introspection endpoint that allows RS's * Optionally: Expose the introspection endpoint that allows RS's
to submit token introspection requests. to submit token introspection requests.
* If providing an introspection endpoint: Authenticate RSs that * If providing an introspection endpoint: Authenticate RSs that
wish to get an introspection response. wish to get an introspection response.
* If providing an introspection endpoint: Process token * If providing an introspection endpoint: Process token
introspection requests. introspection requests.
* Optionally: Handle token revocation. * Optionally: Handle token revocation.
* Optionally: Provide discovery metadta. See * Optionally: Provide discovery metadata. See
[I-D.ietf-oauth-discovery] [I-D.ietf-oauth-discovery]
Client Client
* Discover the AS in charge of the RS that is to be targeted with * Discover the AS in charge of the RS that is to be targeted with
a request. a request.
* Submit the token request (see step (A) of Figure 1). * Submit the token request (see step (A) of Figure 1).
+ Authenticate to the AS. + Authenticate to the AS.
+ Optionally (if not pre-configured): Specify which RS, which + Optionally (if not pre-configured): Specify which RS, which
skipping to change at page 62, line 40 skipping to change at page 58, line 40
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.
Since the client is assumed to be offline, at least for a certain Since the client is assumed to be offline, at least for a certain
period of time, a pre-provisioned access token has to be long-lived. period of time, a pre-provisioned access token has to be long-lived.
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 assoicated 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 22.
Authorization consent from the resource owner can be pre-configured, Authorization consent from the resource owner can be pre-configured,
skipping to change at page 66, line 32 skipping to change at page 62, line 32
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 26: Resource request and response protected by OSCOAP
Appendix F. Document Updates Appendix F. Document Updates
F.1. Version -08 to -09 F.1. Version -08 to -09
o Allowed scope to be byte arrays.
o Defined default names for endpoints.
o Refactored the IANA section for briefness and consistency.
o Refactored tables that define IANA registry contents for
consistency.
o Created IANA registry for CBOR mappings of error codes, grant
types and Authorization Server Information.
o Added references to other document sections defining IANA entries
in the IANA section.
F.2. 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.
o Added text to clarify that introspection must not be delayed, in o Added text to clarify that introspection must not be delayed, in
case the RS has to return a client token. case the RS has to return a client token.
o Added security considerations about leakage through unprotected AS o Added security considerations about leakage through unprotected AS
discovery information, combining profiles and leakage through discovery information, combining profiles and leakage through
error responses. error responses.
o Added privacy considerations about leakage through unprotected AS o Added privacy considerations about leakage through unprotected AS
discovery. discovery.
o Added text that clarifies that introspection is optional. o Added text that clarifies that introspection is optional.
o Made profile parameter optional since it can be implicit. o Made profile parameter optional since it can be implicit.
o Clarified that CoAP is not mandatory and other protocols can be o Clarified that CoAP is not mandatory and other protocols can be
skipping to change at page 67, line 4 skipping to change at page 63, line 16
case the RS has to return a client token. case the RS has to return a client token.
o Added security considerations about leakage through unprotected AS o Added security considerations about leakage through unprotected AS
discovery information, combining profiles and leakage through discovery information, combining profiles and leakage through
error responses. error responses.
o Added privacy considerations about leakage through unprotected AS o Added privacy considerations about leakage through unprotected AS
discovery. discovery.
o Added text that clarifies that introspection is optional. o Added text that clarifies that introspection is optional.
o Made profile parameter optional since it can be implicit. o Made profile parameter optional since it can be implicit.
o Clarified that CoAP is not mandatory and other protocols can be o Clarified that CoAP is not mandatory and other protocols can be
used. used.
o Clarified the design justification for specific features of the o Clarified the design justification for specific features of the
framework in appendix A. framework in appendix A.
o Clarified appendix E.2. o Clarified appendix E.2.
F.2. Version -07 to -08
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 replaced with references to [I-D.ietf-ace-cwt-proof-of-possession]
[I-D.jones-ace-cwt-proof-of-possession]
F.3. Version -06 to -07 F.3. 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.4. 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.
 End of changes. 130 change blocks. 
615 lines changed or deleted 466 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/