--- 1/draft-ietf-ace-oauth-authz-16.txt 2018-11-26 02:14:31.537657580 -0800 +++ 2/draft-ietf-ace-oauth-authz-17.txt 2018-11-26 02:14:31.677660941 -0800 @@ -1,26 +1,26 @@ ACE Working Group L. Seitz Internet-Draft RISE Intended status: Standards Track G. Selander -Expires: April 5, 2019 Ericsson +Expires: May 30, 2019 Ericsson E. Wahlstroem S. Erdtman Spotify AB H. Tschofenig Arm Ltd. - October 2, 2018 + November 26, 2018 Authentication and Authorization for Constrained Environments (ACE) using the OAuth 2.0 Framework (ACE-OAuth) - draft-ietf-ace-oauth-authz-16 + draft-ietf-ace-oauth-authz-17 Abstract This specification defines a framework for authentication and authorization in Internet of Things (IoT) environments called ACE- OAuth. The framework is based on a set of building blocks including OAuth 2.0 and CoAP, thus making a well-known and widely used authorization solution suitable for IoT devices. Existing specifications are used where possible, but where the constraints of IoT devices require it, extensions are added and profiles are @@ -34,21 +34,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on April 5, 2019. + This Internet-Draft will expire on May 30, 2019. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -57,100 +57,105 @@ include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 - 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.1. Discovering Authorization Servers . . . . . . . . . . . . 15 5.1.1. Unauthorized Resource Request Message . . . . . . . . 15 5.1.2. AS Information . . . . . . . . . . . . . . . . . . . 16 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 18 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18 - 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18 + 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 19 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 19 - 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 19 + 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 20 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 22 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 24 5.6.4. Request and Response Parameters . . . . . . . . . . . 25 5.6.4.1. Grant Type . . . . . . . . . . . . . . . . . . . 25 5.6.4.2. Token Type . . . . . . . . . . . . . . . . . . . 26 5.6.4.3. Profile . . . . . . . . . . . . . . . . . . . . . 26 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 27 5.7. The Introspection Endpoint . . . . . . . . . . . . . . . 27 5.7.1. Introspection Request . . . . . . . . . . . . . . . . 28 5.7.2. Introspection Response . . . . . . . . . . . . . . . 29 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 30 - 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 30 + 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 31 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 31 5.8.1. The Authorization Information Endpoint . . . . . . . 32 - 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 33 - 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 33 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 34 - 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 35 - 6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 36 - 6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 36 - 6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 36 - 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 36 - 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 - 8.1. Authorization Server Information . . . . . . . . . . . . 37 - 8.2. OAuth Extensions Error Registration . . . . . . . . . . . 38 - 8.3. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 38 - 8.4. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 39 - 8.5. OAuth Access Token Types . . . . . . . . . . . . . . . . 39 - 8.6. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 39 - 8.6.1. Initial Registry Contents . . . . . . . . . . . . . . 40 - 8.7. ACE Profile Registry . . . . . . . . . . . . . . . . . . 40 - 8.8. OAuth Parameter Registration . . . . . . . . . . . . . . 41 - 8.9. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 41 - 8.10. OAuth Introspection Response Parameter Registration . . . 42 - 8.11. Introspection Endpoint CBOR Mappings Registry . . . . . . 42 - 8.12. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 42 - 8.13. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 43 - 8.14. Media Type Registrations . . . . . . . . . . . . . . . . 44 - 8.15. CoAP Content-Format Registry . . . . . . . . . . . . . . 45 - 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 45 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 45 - 10.2. Informative References . . . . . . . . . . . . . . . . . 47 - Appendix A. Design Justification . . . . . . . . . . . . . . . . 50 - Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 53 - Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 55 - Appendix D. Assumptions on AS knowledge about C and RS . . . . . 56 - Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 56 - E.1. Local Token Validation . . . . . . . . . . . . . . . . . 57 - E.2. Introspection Aided Token Validation . . . . . . . . . . 61 - Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 65 - F.1. Version -15 to -16 . . . . . . . . . . . . . . . . . . . 65 - F.2. Version -14 to -15 . . . . . . . . . . . . . . . . . . . 65 - F.3. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 65 - F.4. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 66 - F.5. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 66 - F.6. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 66 - F.7. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 66 - F.8. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 66 - F.9. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 67 - F.10. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 67 - F.11. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 67 - F.12. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 67 - F.13. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 68 - F.14. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 68 - F.15. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 68 - F.16. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 69 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 69 + 5.8.1.1. Verifying an Access Token . . . . . . . . . . . . 33 + 5.8.1.2. Protecting the Authzorization Information + Endpoint . . . . . . . . . . . . . . . . . . . . 34 + 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 34 + 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 35 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 36 + 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 37 + 6.2. Minimal security requirements for communication . 37 + 6.3. Use of Nonces for Replay Protection . . . . . . . . . . . 38 + 6.4. Combining profiles . . . . . . . . . . . . . . . . . . . 39 + 6.5. Unprotected Information . . . . . . . . . . . . . . . . . 39 + 6.6. Denial of service against or with Introspection . . 39 + 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 40 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 + 8.1. Authorization Server Information . . . . . . . . . . . . 41 + 8.2. OAuth Extensions Error Registration . . . . . . . . . . . 41 + 8.3. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 42 + 8.4. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 42 + 8.5. OAuth Access Token Types . . . . . . . . . . . . . . . . 43 + 8.6. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 43 + 8.6.1. Initial Registry Contents . . . . . . . . . . . . . . 43 + 8.7. ACE Profile Registry . . . . . . . . . . . . . . . . . . 44 + 8.8. OAuth Parameter Registration . . . . . . . . . . . . . . 44 + 8.9. Token Endpoint CBOR Mappings Registry . . . . . . . . . . 44 + 8.10. OAuth Introspection Response Parameter Registration . . . 45 + 8.11. Introspection Endpoint CBOR Mappings Registry . . . . . . 45 + 8.12. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 46 + 8.13. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 47 + 8.14. Media Type Registrations . . . . . . . . . . . . . . . . 47 + 8.15. CoAP Content-Format Registry . . . . . . . . . . . . . . 48 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 49 + 10.2. Informative References . . . . . . . . . . . . . . . . . 51 + Appendix A. Design Justification . . . . . . . . . . . . . . . . 53 + Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 57 + Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 59 + Appendix D. Assumptions on AS knowledge about C and RS . . . . . 60 + Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 60 + E.1. Local Token Validation . . . . . . . . . . . . . . . . . 61 + E.2. Introspection Aided Token Validation . . . . . . . . . . 65 + Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 69 + F.1. Version -15 to -16 . . . . . . . . . . . . . . . . . . . 69 + F.2. Version -14 to -15 . . . . . . . . . . . . . . . . . . . 69 + F.3. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 69 + F.4. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 70 + F.5. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 70 + F.6. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 70 + F.7. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 70 + F.8. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 70 + F.9. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 71 + F.10. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 71 + F.11. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 71 + F.12. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 71 + F.13. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 72 + F.14. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 72 + F.15. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 72 + F.16. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 73 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 73 1. Introduction Authorization is the process for granting approval to an entity to access a resource [RFC4949]. The authorization task itself can best be described as granting access to a requesting client, for a resource hosted on a device, the resource server (RS). This exchange is mediated by one or multiple authorization servers (AS). Managing authorization for a large number of devices and users can be a complex task. @@ -315,27 +319,26 @@ Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner). Issuing a refresh token is optional at the discretion of the authorization server. If the authorization server issues a refresh token, it is included when issuing an access token (i.e., step (B) in Figure 1). - A refresh token is a string representing the authorization granted - to the client by the resource owner. The string is usually opaque - to the client. The token denotes an identifier used to retrieve - the authorization information. Unlike access tokens, refresh - tokens are intended for use only with authorization servers and - are never sent to resource servers. - + A refresh token in OAuth 2.0 is a string representing the + authorization granted to the client by the resource owner. The + string is usually opaque to the client. The token denotes an + identifier used to retrieve the authorization information. Unlike + access tokens, refresh tokens are intended for use only with + authorization servers and are never sent to resource servers. Proof of Possession Tokens: An access token may be bound to a cryptographic key, which is then used by an RS to authenticate requests from a client. Such tokens are called proof-of-possession access tokens (or PoP access tokens). The proof-of-possession (PoP) security concept assumes that the AS acts as a trusted third party that binds keys to access tokens. These so called PoP keys are then used by the client to demonstrate the possession of the secret to the RS when accessing @@ -424,28 +427,28 @@ While HTTP uses headers and query strings to convey additional information about a request, CoAP encodes such information into header parameters called 'options'. CoAP supports application-layer fragmentation of the CoAP payloads through blockwise transfers [RFC7959]. However, blockwise transfer does not increase the size limits of CoAP options, therefore data encoded in options has to be kept small. - Transport layer security for CoAP can be provided by DTLS 1.2 - [RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy - operations that require transport layer security to be terminated at - the proxy. One approach for protecting CoAP communication end-to-end - through proxies, and also to support security for CoAP over a - different transport in a uniform way, is to provide security at the - application layer using an object-based security mechanism such as - COSE [RFC8152]. + Transport layer security for CoAP can be provided by DTLS or TLS + [RFC6347][RFC5246][RFC8446] [I-D.ietf-tls-dtls13]. CoAP defines a + number of proxy operations that require transport layer security to + be terminated at the proxy. One approach for protecting CoAP + communication end-to-end through proxies, and also to support + security for CoAP over a different transport in a uniform way, is to + provide security at the application layer using an object-based + security mechanism such as COSE [RFC8152]. One application of COSE is OSCORE [I-D.ietf-core-object-security], which provides end-to-end confidentiality, integrity and replay protection, and a secure binding between CoAP request and response messages. In OSCORE, the CoAP messages are wrapped in COSE objects and sent using CoAP. This framework RECOMMENDS the use of CoAP as replacement for HTTP for use in constrained environments. @@ -643,27 +647,30 @@ profile. In ACE framework the AS is expected to manage the matching of compatible profile choices between a client and an RS. The AS informs the client of the selected profile using the "profile" parameter in the token response. OAuth 2.0 requires the use of TLS both to protect the communication between AS and client when requesting an access token; between client and RS when accessing a resource and between AS and RS if introspection is used. In constrained settings TLS is not always feasible, or desirable. Nevertheless it is REQUIRED that the data - exchanged with the AS is encrypted and integrity protected. It is - furthermore REQUIRED that the AS and the endpoint communicating with - it (client or RS) perform mutual authentication. + exchanged with the AS is encrypted, integrity protected and protected + against message replay. It is also REQUIRED that the AS and the + endpoint communicating with it (client or RS) perform mutual + authentication. Furthermore it MUST be assured that responses are + bound to the requests in the sense that the receiver of a response + can be certain that the response actually belongs to a certain + request. - Profiles MUST specify how mutual authentication is done, depending - e.g. on the communication protocol and the credentials used by the - client or the RS. + Profiles MUST specify a communication security protocol that provides + the features required above. In OAuth 2.0 the communication with the Token and the Introspection endpoints at the AS is assumed to be via HTTP and may use Uri-query parameters. When profiles of this framework use CoAP instead, this framework REQUIRES the use of the following alternative instead of Uri-query parameters: The sender (client or RS) encodes the parameters of its request as a CBOR map and submits that map as the payload of the POST request. Profiles that use CBOR encoding of protocol message parameters MUST use the media format 'application/ ace+cbor', unless the protocol message is wrapped in another Content- @@ -876,74 +883,78 @@ integer abbreviations for the parameters or their values for illustrative purposes. Note that implementations MUST use the integer abbreviations and the binary CBOR encoding, if the CBOR encoding is used. 5.6.1. Client-to-AS Request The client sends a POST request to the token endpoint at the AS. The profile MUST specify how the communication is protected. The content of the request consists of the parameters specified in Section 4 of - the OAuth 2.0 specification [RFC6749]. + the OAuth 2.0 specification [RFC6749] with the exception of the + "grant_type" parameter, which is OPTIONAL in the context of this + framework (as opposed to REQUIRED in RFC6749). If that parameter is + missing, the default value "client_credentials" is implied. In addition to these parameters, a client MUST be able to use the parameters from [I-D.ietf-ace-oauth-params] in an access token request to the token endpoint and the AS MUST be able to process these additional parameters. If CBOR is used then this parameter MUST be encoded as a CBOR map. The "scope" parameter can be formatted as specified in [RFC6749] and - additionally as a byte array, in order to allow compact encoding of + additionally as a byte string, in order to allow compact encoding of complex scopes. When HTTP is used as a transport then the client makes a request to the token endpoint by sending the parameters using the "application/ x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body, as defined in RFC 6749. The following examples illustrate different types of requests for proof-of-possession tokens. Figure 5 shows a request for a token with a symmetric proof-of- possession key. The content is displayed in CBOR diagnostic - notation, without abbreviations for better readability. + notation, without abbreviations for better readability. Note that + this example uses the "req_aud" parameter from + [I-D.ietf-ace-oauth-params]. Header: POST (Code=0.02) Uri-Host: "as.example.com" Uri-Path: "token" Content-Format: "application/ace+cbor" Payload: { "grant_type" : "client_credentials", "client_id" : "myclient", "req_aud" : "tempSensor4711" } Figure 5: Example request for an access token bound to a symmetric key. 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 - object-security, therefore the Content-Format is "application/cose" - wrapping the "application/ace+cbor" type content. Also note that in - this example the audience is implicitly known by both client and AS. + possession key. Note that in this example OSCORE + [I-D.ietf-core-object-security] is used to provide object-security, + therefore the Content-Format is "application/oscore" wrapping the + "application/ace+cbor" type content. Also note that in this example + the audience is implicitly known by both client and AS. Furthermore + note that this example uses the "req_cnf" parameter from + [I-D.ietf-ace-oauth-params]. Header: POST (Code=0.02) Uri-Host: "as.example.com" Uri-Path: "token" - Content-Format: "application/cose" + Content-Format: "application/oscore" Payload: - 16( # COSE_ENCRYPTED - [ h'a1010a', # protected header: {"alg" : "AES-CCM-16-64-128"} - {5 : b64'ifUvZaHFgJM7UmGnjA'}, # unprotected header, IV - b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext - ] + 0x44025d1 ... (full payload ommitted for brevity) ... 68b3825e ) Decrypted payload: { "grant_type" : "client_credentials", "client_id" : "myclient", "req_cnf" : { "COSE_Key" : { "kty" : "EC", "kid" : h'11', @@ -952,21 +963,23 @@ "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' } } } Figure 6: Example token request bound to an asymmetric key. Figure 7 shows a request for a token where a previously communicated proof-of-possession key is only referenced. Note that the client performs a password based authentication in this example by - submitting its client_secret (see Section 2.3.1 of [RFC6749]). + submitting its client_secret (see Section 2.3.1 of [RFC6749]). Note + that this example uses the "req_aud" and "req_cnf" parameters from + [I-D.ietf-ace-oauth-params]. Header: POST (Code=0.02) Uri-Host: "as.example.com" Uri-Path: "token" Content-Format: "application/ace+cbor" Payload: { "grant_type" : "client_credentials", "client_id" : "myclient", "client_secret" : "mysecret234", @@ -1040,21 +1053,22 @@ | state | RFC 6749 | | error | RFC 6749 | | error_description | RFC 6749 | | error_uri | RFC 6749 | | profile | [this document] | \-------------------+-------------------------------/ Figure 8: Access Information parameters Figure 9 shows a response containing a token and a "cnf" parameter - with a symmetric proof-of-possession key. + with a symmetric proof-of-possession key, which is defined in + [I-D.ietf-ace-oauth-params]. Header: Created (Code=2.01) Content-Format: "application/ace+cbor" Payload: { "access_token" : b64'SlAV32hkKG ... (remainder of CWT omitted for brevity; CWT contains COSE_Key in the "cnf" claim)', "profile" : "coap_dtls", "expires_in" : "3600", @@ -1076,20 +1090,23 @@ equivalent to the ones for HTTP-based interactions as defined in Section 5.2 of [RFC6749], with the following differences: o When using CBOR the raw payload before being processed by the communication security protocol MUST be encoded as a CBOR map. o A response code equivalent to the CoAP code 4.00 (Bad Request) MUST be used for all error responses, except for invalid_client where a response code equivalent to the CoAP code 4.01 (Unauthorized) MAY be used under the same conditions as specified in Section 5.2 of [RFC6749]. + o The content type (for CoAP-based interactions) or media type (for + HTTP-based interactions) "application/ace+cbor" MUST be used for + the error response. o The parameters "error", "error_description" and "error_uri" MUST be abbreviated using the codes specified in Figure 12, when a CBOR encoding is used. o The error code (i.e., value of the "error" parameter) MUST be abbreviated as specified in Figure 10, when a CBOR encoding is used. /------------------------+-------------\ | Name | CBOR Values | |------------------------+-------------| @@ -1157,89 +1174,91 @@ if a CBOR encoding is used. In this framework the "pop" value for the "token_type" parameter is the default. The AS may, however, provide a different value. 5.6.4.3. Profile Profiles of this framework MUST define the communication protocol and the communication security protocol between the client and the RS. The security protocol MUST provide encryption, integrity and replay - protection. Furthermore profiles MUST define proof-of-possession + protection. It MUST also provide a binding between requests and + responses. Furthermore profiles MUST define proof-of-possession methods, if they support proof-of-possession tokens. A profile MUST specify an identifier that MUST be used to uniquely identify itself in the "profile" parameter. The textual representation of the profile identifier is just intended for human readability and MUST NOT be used in parameters and claims. Profiles MAY define additional parameters for both the token request and the Access Information in the access token response in order to support negotiation or signaling of profile specific parameters. 5.6.5. Mapping Parameters to CBOR If CBOR encoding is used, all OAuth parameters in access token requests and responses MUST be mapped to CBOR types as specified in Figure 12, using the given integer abbreviation for the map keys. - Note that we have aligned these abbreviations with the claim - abbreviations defined in [RFC8392]. + Note that we have aligned the abbreviations corresponding to claims + with the abbreviations defined in [RFC8392]. Note also that abbreviations from -24 to 23 have a 1 byte encoding - size in CBOR. We have thus choosen to assign abbreviations in that + size in CBOR. We have thus chosen to assign abbreviations in that range to parameters we expect to be used most frequently in constrained scenarios. /-------------------+----------+---------------------\ | Name | CBOR Key | Value Type | |-------------------+----------+---------------------| + | access_token | 1 | byte string | | scope | 9 | text or byte string | - | profile | 10 | unsigned integer | - | error | 11 | unsigned integer | - | grant_type | 12 | unsigned integer | - | access_token | 13 | byte string | - | token_type | 14 | unsigned integer | | client_id | 24 | text string | | client_secret | 25 | byte string | | response_type | 26 | text string | - | state | 27 | text string | - | redirect_uri | 28 | text string | - | error_description | 29 | text string | - | error_uri | 30 | text string | - | code | 31 | byte string | - | expires_in | 32 | unsigned integer | - | username | 33 | text string | - | password | 34 | text string | - | refresh_token | 35 | byte string | + | redirect_uri | 27 | text string | + | state | 28 | text string | + | code | 29 | byte string | + | error | 30 | unsigned integer | + | error_description | 31 | text string | + | error_uri | 32 | text string | + | grant_type | 33 | unsigned integer | + | token_type | 34 | unsigned integer | + | expires_in | 35 | unsigned integer | + | username | 36 | text string | + | password | 37 | text string | + | refresh_token | 38 | byte string | + | profile | 39 | unsigned integer | \-------------------+----------+---------------------/ Figure 12: CBOR mappings used in token requests 5.7. The Introspection Endpoint 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 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 section defines adaptations to more constrained environments using CBOR and leaving the choice of the application protocol to the profile. Communication between the requesting entity and the introspection - endpoint at the AS MUST be integrity protected and encrypted. - Furthermore the two MUST perform mutual authentication. Finally the - AS SHOULD verify that the requesting entity has the right to access - introspection information about the provided token. Profiles of this - framework that support introspection MUST specify how authentication - and communication security between the requesting entity and the AS - is implemented. + endpoint at the AS MUST be integrity protected and encrypted. The + communication security protocol MUST also provide a binding between + requests and responses. Furthermore the two interacting parties MUST + perform mutual authentication. Finally the AS SHOULD verify that the + requesting entity has the right to access introspection information + about the provided token. Profiles of this framework that support + introspection MUST specify how authentication and communication + security between the requesting entity and the 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 integer abbreviations for the parameters or their values for better readability. Note that supporting introspection is OPTIONAL for implementations of @@ -1248,33 +1267,38 @@ 5.7.1. Introspection Request The requesting entity sends a POST request to the introspection endpoint at the AS, the profile MUST specify how the communication is protected. If CBOR is used, the payload MUST be encoded as a CBOR map with a "token" entry containing either the access token or a reference to the token (e.g., the cti). Further optional parameters representing additional context that is known by the requesting entity to aid the AS in its response MAY be included. + For CoAP-based interaction, all messages MUST use the content type + "application/ace+cbor", while for HTTP-based interactions the + equivalent media type "application/ace+cbor" MUST be used. + The same parameters are required and optional as in Section 2.1 of RFC 7662 [RFC7662]. 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 - token. Note that object security based on COSE is assumed in this - example, therefore the Content-Format is "application/cose". - Figure 14 shows the decoded payload. + token. Note that object security based on OSCORE + [I-D.ietf-core-object-security] is assumed in this example, therefore + the Content-Format is "application/oscore". Figure 14 shows the + decoded payload. Header: POST (Code=0.02) Uri-Host: "as.example.com" Uri-Path: "introspect" - Content-Format: "application/cose" + Content-Format: "application/oscore" Payload: ... COSE content ... Figure 13: Example introspection request. { "token" : b64'7gj0dXJQ43U', "token_type_hint" : "pop" } @@ -1294,21 +1318,22 @@ profile OPTIONAL. This indicates the profile that the RS MUST use with the client. See Section 5.6.4.3 for more details on the formatting of this parameter. Furthermore [I-D.ietf-ace-oauth-params] defines more parameters that the AS MUST be able to use when responding to a request to the introspection endpoint. For example, Figure 15 shows an AS response to the introspection - request in Figure 13. + request in Figure 13. Note that this example contains the "cnf" + parameter defined in [I-D.ietf-ace-oauth-params]/. Header: Created Code=2.01) Content-Format: "application/ace+cbor" Payload: { "active" : true, "scope" : "read", "profile" : "coap_dtls", "cnf" : { "COSE_Key" : { @@ -1348,67 +1373,69 @@ specification. In these cases, the authorization server MUST instead respond with an introspection response with the "active" field set to "false". 5.7.4. Mapping Introspection parameters to CBOR If CBOR is used, the introspection request and response parameters MUST be mapped to CBOR types as specified in Figure 16, using the given integer abbreviation for the map key. - Note that we have aligned these abbreviations with the claim - abbreviations defined in [RFC8392]. + Note that we have aligned abbreviations that correspond to a claim + with the abbreviations defined in [RFC8392] and the abbreviations of + parameters with the same name from Section 5.6.5. - /-----------------+----------+----------------------------------\ + /-------------------+----------+-------------------------\ | Parameter name | CBOR Key | Value Type | - |-----------------+----------+----------------------------------| + |-------------------+----------+-------------------------| | iss | 1 | text string | | sub | 2 | text string | | aud | 3 | text string | - | exp | 4 | integer or floating-point number | - | nbf | 5 | integer or floating-point number | - | iat | 6 | integer or floating-point number | + | exp | 4 | integer or | + | | | floating-point number | + | nbf | 5 | integer or | + | | | floating-point number | + | iat | 6 | integer or | + | | | floating-point number | | cti | 7 | byte string | - | scope | 9 | text OR byte string | - | token_type | 13 | text string | - | token | 14 | byte string | - | active | 15 | True or False | - | profile | 16 | unsigned integer | + | scope | 9 | text or byte string | + | active | 10 | True or False | + | token | 12 | byte string | | client_id | 24 | text string | - | username | 33 | text string | - | token_type_hint | 36 | text string | - \-----------------+----------+----------------------------------/ + | error | 30 | unsigned integer | + | error_description | 31 | text string | + | error_uri | 32 | text string | + | token_type_hint | 33 | text string | + | token_type | 34 | text string | + | username | 36 | text string | + | profile | 39 | unsigned integer | + \-------------------+----------+-------------------------/ Figure 16: CBOR Mappings to Token Introspection Parameters. 5.8. The Access Token This framework RECOMMENDS the use of CBOR web token (CWT) as specified in [RFC8392]. In order to facilitate offline processing of access tokens, this draft uses the "cnf" claim from [I-D.ietf-ace-cwt-proof-of-possession] and specifies the "scope" claim for both JSON and CBOR web tokens. The "scope" claim explicitly encodes the scope of a given access token. This claim follows the same encoding rules as defined in Section 3.3 of [RFC6749], but in addition implementers MAY use byte - arrays as scope values, to achieve compact encoding of large scope + strings as scope values, to achieve compact encoding of large scope elements. The meaning of a specific scope value is application specific and expected to be known to the RS running that application. - If the AS needs to convey a hint to the RS about which key it should - use to authenticate towards the client, the rs_cnf claim MAY be used - with the same syntax and semantics as defined in - [I-D.ietf-ace-oauth-params]. - If the AS needs to convey a hint to the RS about which profile it should use to communicate with the client, the AS MAY include a "profile" claim in the access token, with the same syntax and semantics as defined in Section 5.6.4.3. 5.8.1. The Authorization Information Endpoint The access token, containing authorization information and 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 @@ -1416,58 +1443,131 @@ This section defines a method for transporting the access token to the RS using a RESTful protocol such as CoAP. Profiles of this framework MAY define other methods for token transport. The method consists of an authz-info endpoint, implemented by the RS. A client using this method MUST make a POST request to the authz-info endpoint at the RS with the access token in the payload. The RS receiving the token MUST verify the validity of the token. If the token is valid, the RS MUST respond to the POST request with 2.01 - (Created). This response MAY contain an identifier of the token - (e.g., the cti for a CWT) as a payload, in order to allow the client - to refer to the token. + (Created). Section Section 5.8.1.1 outlines how an RS MUST proceed + to verify the validity of an access token. + + If the access token is a CWT and is sent via CoAP, the content format + "application/cwt" MUST be used. If a token is sent via HTTP the + equivalent media type "application/cwt" MUST be used. The RS MUST be prepared to store at least one access token for future use. This is a difference to how access tokens are handled in OAuth 2.0, where the access token is typically sent along with each request, and therefore not stored at the RS. + This specification RECOMMENDS that an RS stores only one token per + proof-of-possession key, meaning that an additional token linked to + the same key will overwrite any exiting token at the RS. + If the payload sent to the authz-info endpoint does not parse to a token, the RS MUST respond with a response code equivalent to the - CoAP code 4.00 (Bad Request). If the token is not valid, the RS MUST - respond with a response code equivalent to the CoAP code 4.01 - (Unauthorized). If the token is valid but the audience of the token - does not match the RS, the RS MUST respond with a response code - equivalent to the CoAP code 4.03 (Forbidden). If the token is valid - but is associated to claims that the RS cannot process (e.g., an - unknown scope) the RS MUST respond with a response code equivalent to - the CoAP code 4.00 (Bad Request). In the latter case the RS MAY - provide additional information in the error response, in order to - clarify what went wrong. - - The RS MAY use the error codes from section 3.1 of [RFC6750] when - giving error responses, in order to provide additional detail. + CoAP code 4.00 (Bad Request). The RS MAY make an introspection request to validate the token before responding to the POST request to the authz-info endpoint. Profiles MUST specify whether the authz-info endpoint is protected, including whether error responses from this endpoint are protected. Note that since the token contains information that allow the client and the RS to establish a security context in the first place, mutual 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. + A RS MAY use introspection on a token received through the authz-info + endpoint, e.g. if the token is an opaque reference. Some transport + protocols may provide a way to indicate that the RS is busy and the + client should retry after an interval; this type of status update + would be appropriate while the RS is waiting for an introspection + response. + +5.8.1.1. Verifying an Access Token + + When an RS receives an access token, it MUST verify it before storing + it. The verification is based on the claims of the token and its + cryptographic wrapper (if any), so the RS needs to retrieve those + claims. If the claims cannot be retrieved the RS MUST discard the + token and in case of an interaction via the authz-info endpoint, + return an error message with a response code equivalent to the CoAP + code 4.00 (Bad Request). + + Since the cryptographic wrapper of the token (e.g. a COSE message) + could include encryption, it needs to be verified first, based on + shared cryptographic material with recognized AS. If this + verification fails, the RS MUST discard the token and if this was an + interaction with authz-info it MUST respond with a response code + equivalent to the CoAP code 4.01 (Unauthorized). + + The following claims MUST be checked if present, and errors returned + when a check fails, in the order of priority of this list: + + iss The issuer claim must identify an AS that has the authority to + issue access tokens for the receiving RS. If that is not the case + the RS MUST respond with a response code equivalent to the CoAP + code 4.01 (Unauthorized). + exp The expiration date must be in the future. Note that this has + to be verified again at access time. If that is not the case the + RS MUST respond with a response code equivalent to the CoAP code + 4.01 (Unauthorized). + + aud The audience claim must refer to an audience that the RS + identifies with. If that is not the case the RS MUST respond with + a response code equivalent to the CoAP code 4.03 (Forbidden). + scope The RS must recognize value of the scope claim. If that is + not the case the RS MUST respond with a response code equivalent + to the CoAP code 4.00 (Bad Request). The RS MAY provide + additional information in the error response, in order to clarify + what went wrong. + + If the access token contains any other claims that the RS cannot + process the RS MUST respond with a response code equivalent to the + CoAP code 4.00 (Bad Request). The RS MAY provide additional detail + in the error response to clarify which claim couldn't be processed. + + Note that the Subject (sub) claim cannot always be verified when the + token is submitted to the RS, since the client may not have + authenticated yet. Also note that a counter for the expires_in (exi) + claim MUST be initialized when the RS first verifies this token. + + When sending error responses, the RS MAY use the error codes from + section 3.1 of [RFC6750], in order to provide additional detail to + the client. + +5.8.1.2. Protecting the Authzorization Information Endpoint + + As this framework can be used in RESTful environments, it is + important to make sure that attackers cannot perform unauthorized + requests on the auth-info endpoints, other than submitting access + tokens. + + Specifically it SHOULD NOT be possible to perform GET, DELETE or PUT + on the authz-info endpoint and on it's children (if any). + + The POST method SHOULD NOT be allowed on children of the authz-info + endpoint. + + The RS SHOULD implement rate limiting measures to mitigate attacks + aiming to overload the processing capacity of the RS by repeatedly + submitting tokens. For CoAP-based communication the RS could use the + mechanisms from [I-D.ietf-core-too-many-reqs] to indicate that it is + overloaded. + 5.8.2. Client Requests to the RS If an RS receives a request from a client, and the target resource requires authorization, the RS MUST first verify that it has an access token that authorizes this request, and that the client has performed the proof-of-possession for that token. The response code MUST be 4.01 (Unauthorized) in case the client has not performed the proof-of-possession, or if RS has no valid access token for the client. If RS has an access token for the client but @@ -1490,60 +1590,62 @@ Note: Matching the claims of the access token (e.g., scope) to a specific request is application specific. If the request matches a valid token and the client has performed the proof-of-possession for that token, the RS continues to process the request as specified by the underlying application. 5.8.3. Token Expiration 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 expiration of a received access token. Here follows a list of the possibilities including what functionality they require of the RS. 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 from its internal clock as defined in [RFC7519]. In this case the RS's internal clock must reflect the current date and time, or at least be synchronized with the AS's clock. How this clock synchronization would be performed is out of scope for this specification. o The RS verifies the validity of the token by performing an introspection request as specified in Section 5.7. This requires the RS to have a reliable network connection to the AS and to be able to handle two secure sessions in parallel (C to RS and AS to RS). - o The RS and the AS both store a sequence number linked to their - common security association. The AS increments this number for - each access token it issues and includes it in the access token, - which is a CWT. The RS keeps track of the most recently received - sequence number, and only accepts tokens as valid, that are in a - certain range around this number. This method does only require - the RS to keep track of the sequence number. The method does not - provide timely expiration, but it makes sure that older tokens - cease to be valid after a certain number of newer ones got issued. - For a constrained RS with no network connectivity and no means of - reliably measuring time, this is the best that can be achieved. + o In order to support token expiration for devices that have no + reliable way of synchronizing their internal clocks, this + specification defines the following approach: The claim "exi" + ("expires in") can be used, to provide the RS with the lifetime of + the token in seconds from the time the RS first receives the + token. This approach is of course vulnerable to malicious clients + holding back tokens they do not want to expire. Such an attack + can only be prevented if the RS is able to communicate with the AS + in some regular intervals, so that the can AS provide the RS with + a list of expired tokens. The drawback of this mitigation is that + the RS might as well use the communication with the AS to + synchronize its internal clock. If a token that authorizes a long running request such as a CoAP Observe [RFC7641] expires, the RS MUST send an error response with the response code equivalent to the CoAP code 4.01 (Unauthorized) to the client and then terminate processing the long running request. 6. Security Considerations Security considerations applicable to authentication and authorization in RESTful environments provided in OAuth 2.0 [RFC6749] apply to this work. Furthermore [RFC6819] provides additional security considerations for OAuth which apply to IoT deployments as - well. + well. If the introspection endpoint is used, the security + considerations from [RFC7662] also apply. A large range of threats can be mitigated by protecting the contents of the access token by using a digital signature or a keyed message digest (MAC) or an Authenticated Encryption with Associated Data (AEAD) algorithm. Consequently, the token integrity protection MUST be applied to prevent the token from being modified, particularly since it contains a reference to the symmetric key or the asymmetric key. If the access token contains the symmetric key, this symmetric key MUST be encrypted by the authorization server so that only the resource server can decrypt it. Note that using an AEAD algorithm is @@ -1567,76 +1669,158 @@ provided, and additional protection can be applied by encrypting the token, for example encryption of CWTs is specified in Section 5.1 of [RFC8392]. Developers MUST ensure that the ephemeral credentials (i.e., the private key or the session key) are not leaked to third parties. An adversary in possession of the ephemeral credentials bound to the access token will be able to impersonate the client. Be aware that this is a real risk with many constrained environments, since adversaries can often easily get physical access to the devices. + This risk can also be mitigated to some extent by making sure that + keys are refreshed more frequently. If clients are capable of doing so, they should frequently request fresh access tokens, as this allows the AS to keep the lifetime of the tokens short. This allows the AS to use shorter proof-of- possession key sizes, which translate to a performance benefit for the client and for the resource server. Shorter keys also lead to shorter messages (particularly with asymmetric keying material). When authorization servers bind symmetric keys to access tokens, they - SHOULD scope these access tokens to a specific permissions. - Furthermore access tokens using symmetric keys for proof-of- - possession SHOULD NOT be targeted at an audience that contains more - than one RS, since otherwise any RS in the audience that receives - that access token can impersonate the client towards the other - members of the audience. + SHOULD scope these access tokens to a specific permission. 6.1. Unprotected AS Information Initially, no secure channel exists to protect the communication between C and RS. Thus, C cannot determine if the AS information contained in an unprotected response from RS to an unauthorized request (see Section 5.1.2) is authentic. It is therefore advisable to provide C with a (possibly hard-coded) list of trustworthy authorization servers. AS information responses referring to a URI not listed there would be ignored. -6.2. Use of Nonces for Replay Protection +6.2. Minimal security requirements for communication + + This section summarizes the minimal requirements for the + communication security of the different protocol interactions. + + C-AS All communication between the client and the Authorization + Server MUST be encrypted, integrity and replay protected. + Furthermore responses from the AS to the client MUST be bound to + the client's request to avoid attacks where the attacker swaps the + intended response for an older one valid for a previous request. + This requires that the client and the Authorization Server have + previously exchanged either a shared secret, or their public keys + in order to negotiate a secure communication. Furthermore the + client MUST be able to determine whether an AS has the authority + to issue access tokens for a certain RS. This can be done through + pre-configured lists, or through an online lookup mechanism that + in turn also must be secured. + RS-AS The communication between the Resource Server and the + Authorization Server via the introspection endpoint MUST be + encrypted, integrity and replay protected. Furthermore responses + from the AS to the RS MUST be bound to the RS's request. This + requires that the client and the Authorization Server have + previously exchanged either a shared secret, or their public keys + in order to negotiate a secure communication. Furthermore the RS + MUST be able to determine whether an AS has the authority to issue + access tokens itself. This is usually configured out of band, but + could also be performed through an online lookup mechanism + provided that it is also secured in the same way. + C-RS The initial communication between the client and the Resource + Server can not be secured in general, since the RS is not in + possession of on access token for that client, which would carry + the necessary parameters. Certain security mechanisms (e.g. DTLS + with server-side authentication via a certificate or a raw public + key) can be possible and are RECOMMEND if supported by both + parties. After the client has successfully transmitted the access + token to the RS, a secure communication protocol MUST be + established between client and RS for the actual resource request. + This protocol MUST provide encryption, integrity and replay + protection as well as a binding between requests and responses. + This requires that the client learned either the RS's public key + or received a symmetric proof-of-possession key bound to the + access token from the AS. The RS must have learned either the + client's public key or a shared symmetric key from the claims in + the token or an introspection request. Since ACE does not provide + profile negotiation between C and RS, the client MUST have learned + what profile the RS supports (e.g. from the AS or pre-configured) + and initiate the communication accordingly. + +6.3. Use of Nonces for Replay Protection The RS may add a nonce to the AS Information message sent as a response to an unauthorized request to ensure freshness of an Access Token subsequently presented to RS. While a time-stamp of some granularity would be sufficient to protect against replay attacks, using randomized nonce is preferred to prevent disclosure of information about RS's internal clock characteristics. -6.3. Combining profiles +6.4. Combining profiles There may be use cases were different profiles of this framework are combined. For example, an MQTT-TLS profile is used between the client and the RS in combination with a CoAP-DTLS profile for interactions between the client and the AS. Ideally, profiles should be designed in a way that the security of system should not depend on the specific security mechanisms used in individual protocol interactions. -6.4. Error responses +6.5. Unprotected Information - The various error responses defined in this framework may leak - information to an adversary. For example errors responses for + Communication with the authz-info endpoint, as well as the various + error responses defined in this framework all potentially include + sending information over an unprotected channel. These messages may + leak information to an adversary. For example errors responses for requests to the Authorization Information endpoint can reveal information about an otherwise opaque access token to an adversary - who has intercepted this token. This framework is written under the - assumption that, in general, the benefits of detailed error messages - outweigh the risk due to information leakage. For particular use - cases, where this assessment does not apply, detailed error messages - can be replaced by more generic ones. + who has intercepted this token. + + As far as error messages are concerned, this framework is written + under the assumption that, in general, the benefits of detailed error + messages outweigh the risk due to information leakage. For + particular use cases, where this assessment does not apply, detailed + error messages can be replaced by more generic ones. + + In some scenarios it may be possible to protect the communication + with the authz-info endpoint (e.g. through DTLS with only server-side + authentication). In cases where this is not possible this framework + RECOMMENDS to use encrypted CWTs or opaque references and need to be + subjected to introspection by the RS. + + If the initial unauthorized resource request message (see + Section 5.1.1) is used, the client MUST make sure that it is not + sending sensitive content in this request. While GET and DELETE + requests only reveal the target URI of the resource, while POST and + PUT requests would reveal the whole payload of the intended + operation. + +6.6. Denial of service against or with Introspection + + The optional introspection mechanism provided by OAuth and supported + in the ACE framework allows for two types of attacks that need to be + considered by implementers. + + First an attacker could perform a denial of service attack against + the introspection endpoint at the AS in order to prevent validation + of access tokens. To mitigate this attack, an RS that is configured + to use introspection MUST NOT allow access based on a token for which + it couln't reach the introspection endpoint. + + Second an attacker could use the fact that an RS performs + introspection to perform a denial of service attack against that RS + by repeatedly sending tokens to its authz-info endpoint that require + an introspection call. RS can mitigate such attacks by implementing + a rate limit on how many introspection requests they perform in a + given time intervall and rejecting incoming requests to authz-info + for a certain amount of time, when that rate limit has been reached. 7. Privacy Considerations Implementers and users should be aware of the privacy implications of the different possible deployments of this framework. The AS is in a very central position and can potentially learn sensitive information about the clients requesting access tokens. If the client credentials grant is used, the AS can track what kind of access the client intends to perform. With other grants this can be @@ -1685,43 +1869,42 @@ Name The name of the parameter CBOR Key CBOR map key for the parameter. Different ranges of values use different registration policies [RFC8126]. Integer values from -256 to 255 are designated as Standards Action. Integer values from -65536 to -257 and from 256 to 65535 are designated as Specification Required. Integer values greater than 65535 are designated as Expert Review. Integer values less than -65536 are marked as Private Use. Value Type The CBOR data types allowable for the values of this parameter. - Reference This contains a pointer to the public specification of the grant type abbreviation, if one exists. This registry will be initially populated by the values in Figure 2. The Reference column for all of these entries will be this document. 8.2. OAuth Extensions Error Registration - This specification registers the follwoing error values in the OAuth + This specification registers the following error values in the OAuth Extensions Error registry defined in [RFC6749]. o Error name: "unsupported_pop_key" o Error usage location: AS token endpoint error response o Related protocol extension: The ACE framework [this document] o Change Controller: IESG - o Specification doucment(s): Section 5.6.3 of [this document] + o Specification document(s): Section 5.6.3 of [this document] o Error name: "incompatible_profiles" o Error usage location: AS token endpoint error response o Related protocol extension: The ACE framework [this document] o Change Controller: IESG - o Specification doucment(s): Section 5.6.3 of [this document] + o Specification document(s): Section 5.6.3 of [this document] 8.3. OAuth Error Code CBOR Mappings Registry This specification establishes the IANA "OAuth Error Code CBOR Mappings" registry. The registry has been created to use the "Expert Review Required" registration procedure [RFC8126]. It should be noted that, in addition to the expert review, some portions of the registry require a specification, potentially a Standards Track RFC, be supplied as well. @@ -1845,21 +2028,21 @@ 8.8. OAuth Parameter Registration This specification registers the following parameter in the "OAuth Parameters" registry [IANA.OAuthParameters]: o Name: "profile" o Parameter Usage Location: token response o Change Controller: IESG o Reference: Section 5.6.4.3 of [this document] -8.9. OAuth CBOR Parameter Mappings Registry +8.9. Token Endpoint CBOR Mappings Registry This specification establishes the IANA "Token Endpoint CBOR Mappings" registry. The registry has been created to use the "Expert Review Required" registration procedure [RFC8126]. It should be noted that, in addition to the expert review, some portions of the registry require a specification, potentially a Standards Track RFC, be supplied as well. The columns of this registry are: @@ -1868,27 +2051,28 @@ CBOR Key CBOR map key for this parameter. Different ranges of values use different registration policies [RFC8126]. Integer values from -256 to 255 are designated as Standards Action. Integer values from -65536 to -257 and from 256 to 65535 are designated as Specification Required. Integer values greater than 65535 are designated as Expert Review. Integer values less than -65536 are marked as Private Use. Value 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. + parameter abbreviation, if one exists. This registry will be initially populated by the values in Figure 12. The Reference column for all of these entries will be this document. - Note that these mappings intentionally coincide with the CWT claim - name mappings from [RFC8392]. + Note that the mappings of parameters corresponding to claim names + intentionally coincide with the CWT claim name mappings from + [RFC8392]. 8.10. OAuth Introspection Response Parameter Registration This specification registers the following parameter in the OAuth Token Introspection Response registry [IANA.TokenIntrospectionResponse]. o Name: "profile" o Description: The communication and communication security profile used between client and RS, as defined in ACE profiles. @@ -1916,76 +2101,73 @@ 65535 are designated as Expert Review. Integer values less than -65536 are marked as Private Use. Value 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. This registry will be initially populated by the values in Figure 16. The Reference column for all of these entries will be this document. + Note that the mappings of parameters corresponding to claim names + intentionally coincide with the CWT claim name mappings from + [RFC8392]. + 8.12. JSON Web Token Claims This specification registers the following new claims in the JSON Web Token (JWT) registry of JSON Web Token Claims [IANA.JsonWebTokenClaims]: o Claim Name: "scope" o Claim Description: The scope of an access token as defined in [RFC6749]. o Change Controller: IESG o Reference: Section 5.8 of [this document] o Claim Name: "profile" o Claim Description: The profile a token is supposed to be used with. o Change Controller: IESG o Reference: Section 5.8 of [this document] - o Claim Name: "rs_cnf" - o Claim Description: The public key the RS is supposed to use to - authenticate to the client wielding this token. + o Claim Name: "exi" + o Claim Description: "Expires in". Lifetime of the token in seconds + from the time the RS first sees it. Used to implement a weaker + from of token expiration for devices that cannot synchronize their + internal clocks. o Change Controller: IESG - o Reference: Section 5.8 of [this document] + o Reference: Section 5.8.3 of [this document] 8.13. CBOR Web Token Claims This specification registers the following new claims in the "CBOR Web Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. o Claim Name: "scope" 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 Key: TBD (suggested: 9) o Claim Value Type(s): byte string or text string o Change Controller: IESG o Specification Document(s): Section 5.8 of [this document] o Claim Name: "profile" o Claim Description: The profile a token is supposed to be used with. o JWT Claim Name: N/A - o Claim Key: 16 + o Claim Key: TBD (suggested: 39) o Claim Value Type(s): integer o Change Controller: IESG o Specification Document(s): Section 5.8 of [this document] - o Claim Name: "rs_cnf" - o Claim Description: The public key the RS is supposed to use to - authenticate to the client wielding this token. - o JWT Claim Name: N/A - o Claim Key: 17 - o Claim Value Type(s): map - o Change Controller: IESG - o Specification Document(s): Section 5.8 of [this document] - 8.14. Media Type Registrations This specification registers the 'application/ace+cbor' media type for messages of the protocols defined in this document carrying parameters encoded in CBOR. This registration follows the procedures specified in [RFC6838]. Type name: application Subtype name: ace+cbor @@ -2049,32 +2230,35 @@ Thanks to the authors of draft-ietf-oauth-pop-key-distribution, from where large parts of the security considerations where copied. Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten Bormann for contributing their work on AS discovery from draft-gerdes-ace-dcaf- authorize (see Section 5.1). Thanks to Jim Schaad and Mike Jones for their comprehensive reviews. + Thanks to Benjamin Kaduk for his input on various questions related + to this work. + Ludwig Seitz and Goeran Selander worked on this document as part of the CelticPlus project CyberWI, with funding from Vinnova. 10. References 10.1. Normative References [I-D.ietf-ace-cwt-proof-of-possession] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- - possession-03 (work in progress), June 2018. + possession-05 (work in progress), November 2018. [I-D.ietf-ace-oauth-params] Seitz, L., "Additional OAuth Parameters for Authorization in Constrained Environments (ACE)", draft-ietf-ace-oauth- params-00 (work in progress), September 2018. [IANA.CborWebTokenClaims] IANA, "CBOR Web Token (CWT) Claims", . @@ -2158,25 +2342,36 @@ Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared- Key as OAuth client credentials", draft-erdtman-ace- rpcc-02 (work in progress), October 2017. [I-D.ietf-core-object-security] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments (OSCORE)", draft-ietf-core-object-security-15 (work in progress), August 2018. + [I-D.ietf-core-too-many-reqs] + Keranen, A., "Too Many Requests Response Code for the + Constrained Application Protocol", draft-ietf-core-too- + many-reqs-06 (work in progress), November 2018. + [I-D.ietf-oauth-device-flow] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, "OAuth 2.0 Device Flow for Browserless and Input - Constrained Devices", draft-ietf-oauth-device-flow-12 - (work in progress), August 2018. + Constrained Devices", draft-ietf-oauth-device-flow-13 + (work in progress), October 2018. + + [I-D.ietf-tls-dtls13] + Rescorla, E., Tschofenig, H., and N. Modadugu, "The + Datagram Transport Layer Security (DTLS) Protocol Version + 1.3", draft-ietf-tls-dtls13-30 (work in progress), + November 2018. [Margi10impact] Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr, M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold, "Impact of Operating Systems on Wireless Sensor Networks (Security) Applications and Testbeds", Proceedings of the 19th International Conference on Computer Communications and Networks (ICCCN), 2010 August. [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", @@ -2248,20 +2443,24 @@ [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, . + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + . + Appendix A. Design Justification This section provides further insight into the design decisions of the solution documented in this document. Section 3 lists several building blocks and briefly summarizes their importance. The justification for offering some of those building blocks, as opposed to using OAuth 2.0 as is, is given below. Common IoT constraints are: @@ -2337,47 +2536,46 @@ other protocols such as HTTP, HTTP/2 or other specific protocols, such as Bluetooth Smart communication, that do not necessarily use IP could also be used. The latter raises the need for application layer security over the various interfaces. In the light of these constraints we have made the following design decisions: CBOR, COSE, CWT: - This framework REQUIRES the use of CBOR [RFC7049] as data format. - Where CBOR data needs to be protected, the use of COSE [RFC8152] - is RECOMMENDED. Furthermore where self-contained tokens are - needed, this framework RECOMMENDS the use of CWT [RFC8392]. These - measures aim at reducing the size of messages sent over the wire, - the RAM size of data objects that need to be kept in memory and - the size of libraries that devices need to support. + This framework RECOMMENDS the use of CBOR [RFC7049] as data + format. Where CBOR data needs to be protected, the use of COSE + [RFC8152] is RECOMMENDED. Furthermore where self-contained tokens + are needed, this framework RECOMMENDS the use of CWT [RFC8392]. + These measures aim at reducing the size of messages sent over the + wire, the RAM size of data objects that need to be kept in memory + and the size of libraries that devices need to support. CoAP: This framework RECOMMENDS the use of CoAP [RFC7252] instead of HTTP. This does not preclude the use of other protocols specifically aimed at constrained devices, like, e.g., Bluetooth Low Energy (see Section 3.2). This aims again at reducing the size of messages sent over the wire, the RAM size of data objects that need to be kept in memory and the size of libraries that devices need to support. Access Information: This framework defines the name "Access Information" for data concerning the RS that the AS returns to the client in an access - token response (see Section 5.6.2). This includes the "profile" - and the "rs_cnf" parameters. This aims at enabling scenarios, - where a powerful client, supporting multiple profiles, needs to - interact with a RS for which it does not know the supported - profiles and the raw public key. + token response (see Section 5.6.2). This aims at enabling + scenarios, where a powerful client, supporting multiple profiles, + needs to interact with a RS for which it does not know the + supported profiles and the raw public key. Proof-of-Possession: This framework makes use of proof-of-possession tokens, using the "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession]. A semantically and syntactically identical request and response parameter is defined for the token endpoint, to allow requesting and stating confirmation keys. This aims at making token theft harder. Token theft is specifically relevant in constrained use cases, as communication often passes through middle-boxes, which @@ -2398,21 +2596,21 @@ packet gets lost. Thus separating sending of the request and sending of the access tokens helps to reduce fragmentation. Client Credentials Grant: This framework RECOMMENDS the use of the client credentials grant for machine-to-machine communication use cases, where manual intervention of the resource owner to produce a grant token is not feasible. The intention is that the resource owner would instead pre-arrange authorization with the AS, based on the client's own - credentials. The client can the (without manual intervention) + credentials. The client can then (without manual intervention) obtain access tokens from the AS. Introspection: This framework RECOMMENDS the use of access token introspection in cases where the client is constrained in a way that it can not easily obtain new access tokens (i.e. it has connectivity issues that prevent it from communicating with the AS). In that case this framework RECOMMENDS the use of a long-term token, that could be a simple reference. The RS is assumed to be able to @@ -2547,21 +2742,23 @@ o Specify how the client and the RS mutually authenticate. Section 4 o Specify the proof-of-possession protocol(s) and how to select one, if several are available. Also specify which key types (e.g., symmetric/asymmetric) are supported by a specific proof-of- possession protocol. Section 5.6.4.2 o Specify a unique profile identifier. Section 5.6.4.3 o If introspection is supported: Specify the communication and security protocol for introspection.Section 5.7 o Specify the communication and security protocol for interactions - between client and AS. Section 5.6 + between client and AS. This must provide encryption, integrity + protection, replay protection and a binding between requests and + responses. Section 5 and Section 5.6 o Specify how/if the authz-info endpoint is protected, including how error responses are protected. Section 5.8.1 o Optionally define other methods of token transport than the authz- info endpoint. Section 5.8.1 Appendix D. Assumptions on AS knowledge about C and RS This section lists the assumptions on what an AS should know about a client and a RS in order to be able to respond to requests to the token and introspection endpoints. How this information is @@ -2655,21 +2851,23 @@ | | Payload: | | B: |<--------+ Header: 2.05 Content | 2.05 | Content-Format: application/ace+cbor | | Payload: | | Figure 17: Token Request and Response Using Client Credentials. The information contained in the Request-Payload and the Response- - Payload is shown in Figure 18. + Payload is shown in Figure 18 Note that the parameter "rs_cnf" from + [I-D.ietf-ace-oauth-params] is used to inform the client about the + resource server's public key. Request-Payload : { "grant_type" : "client_credentials", "req_aud" : "tempSensorInLivingRoom", "client_id" : "myclient", "client_secret" : "qwerty" "req_cnf" : { "COSE_Key" : { "kid" : b64'1Bg8vub9tLe1gHMzV76e8', @@ -3009,21 +3207,21 @@ F.7. Version -09 to -10 o Removed CBOR major type numbers. o Removed the client token design. o Rephrased to clarify that other protocols than CoAP can be used. o Clarifications regarding the use of HTTP F.8. Version -08 to -09 - o Allowed scope to be byte arrays. + o Allowed scope to be byte strings. 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.9. Version -07 to -08