--- 1/draft-ietf-ace-oauth-authz-04.txt 2017-02-06 01:13:08.780309830 -0800 +++ 2/draft-ietf-ace-oauth-authz-05.txt 2017-02-06 01:13:08.896312555 -0800 @@ -1,25 +1,25 @@ ACE Working Group L. Seitz Internet-Draft SICS Intended status: Standards Track G. Selander -Expires: May 4, 2017 Ericsson +Expires: August 7, 2017 Ericsson E. Wahlstroem S. Erdtman Spotify AB H. Tschofenig ARM Ltd. - October 31, 2016 + February 3, 2017 Authentication and Authorization for Constrained Environments (ACE) - draft-ietf-ace-oauth-authz-04 + draft-ietf-ace-oauth-authz-05 Abstract This specification defines a framework for authentication and authorization in Internet of Things (IoT) environments. 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 defined. @@ -32,99 +32,107 @@ 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 May 4, 2017. + This Internet-Draft will expire on August 7, 2017. Copyright Notice - Copyright (c) 2016 IETF Trust and the persons identified as the + Copyright (c) 2017 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 carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 - 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 9 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 13 6. The 'Token' Endpoint . . . . . . . . . . . . . . . . . . . . 14 - 6.1. Client-to-AS Request . . . . . . . . . . . . . . . . . . 15 - 6.2. AS-to-Client Response . . . . . . . . . . . . . . . . . . 17 - 6.3. Error Response . . . . . . . . . . . . . . . . . . . . . 19 - 6.4. New Request and Response Parameters . . . . . . . . . . . 19 - 6.4.1. Audience . . . . . . . . . . . . . . . . . . . . . . 19 - 6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . . . 19 - 6.4.3. Token Type . . . . . . . . . . . . . . . . . . . . . 19 - 6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . . . 20 - 6.4.5. Confirmation . . . . . . . . . . . . . . . . . . . . 20 - 6.5. Mapping parameters to CBOR . . . . . . . . . . . . . . . 22 - 7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . . . 23 - 7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . . . 24 - 7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . . . 24 - 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 25 - 7.4. Client Token . . . . . . . . . . . . . . . . . . . . . . 26 - 7.5. Mapping Introspection parameters to CBOR . . . . . . . . 28 - 8. The Access Token . . . . . . . . . . . . . . . . . . . . . . 28 - 8.1. The 'Authorization Information' Endpoint . . . . . . . . 29 - 8.2. Token Expiration . . . . . . . . . . . . . . . . . . . . 29 - 9. Security Considerations . . . . . . . . . . . . . . . . . . . 30 - 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 - 10.1. OAuth Introspection Response Parameter Registration . . 31 - 10.2. OAuth Parameter Registration . . . . . . . . . . . . . . 32 - 10.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 32 - 10.4. Token Type Mappings . . . . . . . . . . . . . . . . . . 33 - 10.4.1. Registration Template . . . . . . . . . . . . . . . 33 - 10.4.2. Initial Registry Contents . . . . . . . . . . . . . 33 - 10.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . 33 - 10.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 34 - 10.6.1. Registration Template . . . . . . . . . . . . . . . 34 - 10.7. OAuth Parameter Mappings Registry . . . . . . . . . . . 34 - 10.7.1. Registration Template . . . . . . . . . . . . . . . 34 - 10.7.2. Initial Registry Contents . . . . . . . . . . . . . 35 - 10.8. Introspection Endpoint CBOR Mappings Registry . . . . . 37 - 10.8.1. Registration Template . . . . . . . . . . . . . . . 37 - 10.8.2. Initial Registry Contents . . . . . . . . . . . . . 37 - 10.9. CoAP Option Number Registration . . . . . . . . . . . . 39 - 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40 - 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 - 12.1. Normative References . . . . . . . . . . . . . . . . . . 40 - 12.2. Informative References . . . . . . . . . . . . . . . . . 41 - Appendix A. Design Justification . . . . . . . . . . . . . . . . 43 - Appendix B. Roles and Responsibilites . . . . . . . . . . . . . 45 - Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 47 - Appendix D. Deployment Examples . . . . . . . . . . . . . . . . 47 - D.1. Local Token Validation . . . . . . . . . . . . . . . . . 48 - D.2. Introspection Aided Token Validation . . . . . . . . . . 51 - Appendix E. Document Updates . . . . . . . . . . . . . . . . . . 55 - E.1. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 55 - E.2. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 55 - E.3. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 56 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57 + 6.1. Client Credentials and Grants . . . . . . . . . . . . . . 15 + 6.2. Client-to-AS Request . . . . . . . . . . . . . . . . . . 15 + 6.3. AS-to-Client Response . . . . . . . . . . . . . . . . . . 18 + 6.4. Error Response . . . . . . . . . . . . . . . . . . . . . 20 + 6.5. Request and Response Parameters . . . . . . . . . . . . . 20 + 6.5.1. Audience . . . . . . . . . . . . . . . . . . . . . . 20 + 6.5.2. Grant Type . . . . . . . . . . . . . . . . . . . . . 21 + 6.5.3. Token Type . . . . . . . . . . . . . . . . . . . . . 21 + 6.5.4. Profile . . . . . . . . . . . . . . . . . . . . . . . 21 + 6.5.5. Confirmation . . . . . . . . . . . . . . . . . . . . 22 + 6.6. Mapping parameters to CBOR . . . . . . . . . . . . . . . 24 + 7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . . . 24 + 7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . . . 25 + 7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . . . 25 + 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 27 + 7.4. Client Token . . . . . . . . . . . . . . . . . . . . . . 27 + 7.5. Mapping Introspection parameters to CBOR . . . . . . . . 29 + 8. The Access Token . . . . . . . . . . . . . . . . . . . . . . 29 + 8.1. The 'Authorization Information' Endpoint . . . . . . . . 30 + 8.2. Token Expiration . . . . . . . . . . . . . . . . . . . . 30 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 31 + 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 33 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 + 11.1. OAuth Introspection Response Parameter Registration . . 33 + 11.2. OAuth Parameter Registration . . . . . . . . . . . . . . 34 + 11.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 34 + 11.4. Token Type Mappings . . . . . . . . . . . . . . . . . . 35 + 11.4.1. Registration Template . . . . . . . . . . . . . . . 35 + 11.4.2. Initial Registry Contents . . . . . . . . . . . . . 35 + 11.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . 35 + 11.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 36 + 11.6.1. Registration Template . . . . . . . . . . . . . . . 36 + 11.7. OAuth Parameter Mappings Registry . . . . . . . . . . . 36 + 11.7.1. Registration Template . . . . . . . . . . . . . . . 36 + 11.7.2. Initial Registry Contents . . . . . . . . . . . . . 37 + 11.8. Introspection Endpoint CBOR Mappings Registry . . . . . 39 + 11.8.1. Registration Template . . . . . . . . . . . . . . . 39 + 11.8.2. Initial Registry Contents . . . . . . . . . . . . . 39 + 11.9. CoAP Option Number Registration . . . . . . . . . . . . 41 + 11.10. CWT Confirmation Methods Registry . . . . . . . . . . . 42 + 11.10.1. Registration Template . . . . . . . . . . . . . . . 42 + 11.10.2. Initial Registry Contents . . . . . . . . . . . . . 43 + 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 + 13.1. Normative References . . . . . . . . . . . . . . . . . . 44 + 13.2. Informative References . . . . . . . . . . . . . . . . . 44 + Appendix A. Design Justification . . . . . . . . . . . . . . . . 46 + Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 48 + Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 50 + Appendix D. Assumptions on AS knowledge about C and RS . . . . . 51 + Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 51 + E.1. Local Token Validation . . . . . . . . . . . . . . . . . 52 + E.2. Introspection Aided Token Validation . . . . . . . . . . 55 + Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 59 + F.1. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 59 + F.2. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 59 + F.3. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 60 + F.4. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 60 + F.5. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 60 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 61 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 is a complex task. @@ -156,22 +164,23 @@ Implementations may claim conformance with a specific profile, whereby implementations utilizing the same profile interoperate while implementations of different profiles are not expected to be interoperable. Some devices, such as mobile phones and tablets, may implement multiple profiles and will therefore be able to interact with a wider range of low end devices. 2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in [RFC2119]. + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + [RFC2119]. Certain security-related terms such as "authentication", "authorization", "confidentiality", "(data) integrity", "message authentication code", and "verify" are taken from [RFC4949]. Since we describe exchanges as RESTful protocol interactions HTTP [RFC7231] offers useful terminology. Terminology for entities in the architecture is defined in OAuth 2.0 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource @@ -223,21 +232,21 @@ A fourth building block is the compact CBOR-based secure message format COSE [I-D.ietf-cose-msg], which enables application layer security as an alternative or complement to transport layer security (DTLS [RFC6347] or TLS [RFC5246]). COSE is used to secure self contained tokens such as proof-of-possession (PoP) tokens, which is an extension to the OAuth access tokens, and "client tokens" which are defined in this framework (see Section 7.4). The default access token format is defined in CBOR web token (CWT) [I-D.ietf-ace-cbor-web-token]. Application layer security for CoAP using COSE can be provided with OSCOAP - [I-D.selander-ace-object-security]. + [I-D.ietf-core-object-security]. With the building blocks listed above, solutions satisfying various IoT device and network constraints are possible. A list of constraints is described in detail in RFC 7228 [RFC7228] and a description of how the building blocks mentioned above relate to the various constraints can be found in Appendix A. Luckily, not every IoT device suffers from all constraints. The ACE framework nevertheless takes all these aspects into account and allows several different deployment variants to co-exist rather than @@ -394,21 +403,21 @@ 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 which requires 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 on application layer using an object-based security mechanism such as COSE [I-D.ietf-cose-msg]. - One application of COSE is OSCOAP [I-D.selander-ace-object-security], + One application of COSE is OSCOAP [I-D.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 OSCOAP, the CoAP messages are wrapped in COSE objects and sent using CoAP. 4. Protocol Interactions The ACE framework is based on the OAuth 2.0 protocol interactions using the /token and /introspect endpoints. A client obtains an access token from an AS using the /token endpoint and subsequently @@ -516,21 +524,21 @@ specific credential). Access Token Response (B): If the AS successfully processes the request from the client, it returns an access token. It also returns various parameters, referred as "RS Information". In addition to the response parameters defined by OAuth 2.0 and the PoP token extension, further response parameters, such as information on which profile the client should use with the resource server(s). More - information about these parameters can be found in Section 6.4. + information about these parameters can be found in Section 6.5. Resource Request (C): The client interacts with the RS to request access to the protected resource and provides the access token. The protocol to use between the client and the RS is not restricted to CoAP. HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also viable candidates. Depending on the device limitations and the selected protocol this @@ -594,88 +602,114 @@ or associated information to allow mutual authentication. These credentials need to be provided to the parties before or during the authentication protocol is executed, and may be re-used for subsequent token requests. Proof-of-Possession The ACE framework by default implements proof-of-possession for 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 the - "cnf" claim indicating what key is used for mutual authentication. + "cnf" claim indicating what key is used for proof-of-possession. If clients need to update a token, e.g. to get additional rights, they can request that the AS binds the new access token to the - same credential as the previous token. + same key as the previous token. ACE Profiles The client or RS may be limited in the encodings or protocols it supports. To support a variety of different deployment settings, specific interactions between client and RS are defined in an ACE 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 request and token response. + "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 for introspection. 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. - Profiles are expected to specify the details of how this is done, - depending e.g. on the communication protocol and the credentials used - by the client or the RS. + 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. 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. This framework RECOMMENDS to use CoAP instead and RECOMMENDS 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. The Content-format depends on the security applied to the - content and must be specified by the corresponding profile. + content and MUST be specified by the profile that is used. The OAuth 2.0 AS uses a JSON structure in the payload of its responses both to client and RS. This framework RECOMMENDS the use of CBOR [RFC7049] instead. The requesting device can explicitly request this encoding by setting the CoAP Accept option in the request to "application/cbor". Depending on the profile, the content - may arrive in a different format wrapping a CBOR payload. + MAY arrive in a different format wrapping a CBOR payload. 6. The 'Token' Endpoint In plain OAuth 2.0 the AS provides the /token endpoint for submitting access token requests. This framework extends the functionality of the /token endpoint, giving the AS the possibility to help client and RS to establish shared keys or to exchange their public keys. - Furthermore this framework defines encodings using CoAP and CBOR, - instead of HTTP and JSON. + Furthermore this framework defines encodings using CoAP and CBOR, in + addition to HTTP and JSON. - Communication between the client and the /token endpoint at the AS - MUST be integrity protected and encrypted. Furthermore AS and client - MUST perform mutual authentication. Profiles of this framework are - expected to specify how authentication and communication security is - implemented. + Authentication of the requesting client is done using client + credentials as defined by OAuth 2.0. A profile MAY specify new + client credentials types for the authentication of the client. + + Profiles of this framework SHOULD specify how authentication of the + AS is done and how communication security is implemented. If nothing + is specified TLS with server certificate is assumed as defined by + OAuth 2.0. + + When requesting a token the client is authenticated with client + credentials and then a grant is presented that gives the client the + right to get a token. The figures of this section uses CBOR diagnostic notation without the integer abbreviations for the parameters or their values for better readability. -6.1. Client-to-AS Request +6.1. Client Credentials and Grants + + To issue a token the client MUST be authenticated and present a valid + grant for the scopes requested. + + The OAuth framework, [RFC6749], defines one client credential type, + client id and client secret. Profiles of this framework MAY extend + with additional client credentials such as DTLS pre-shared keys or + client certificates. + + In the OAuth framework five grant types are defined. The grant types + can be split up into three groups, those granted on behalf of the + resource owner (password, authorization code, implicit), those for + the client (client_credentials), and those used to prolong a grant + (refresh token). + + profiles MAY define additional grant types if needed, e.g. a proof of + possession refresh token. + +6.2. Client-to-AS Request The client sends a CoAP POST request to the token endpoint at the AS, - the profile is expected to specify the Content-Type and wrapping of - the payload. The content of the request consists of the parameters + the profile MUST specify the Content-Type and wrapping of the + payload. The content of the request consists of the parameters specified in section 4 of the OAuth 2.0 specification [RFC6749] encoded as a CBOR map. In addition to these parameters, this framework defines the following parameters for requesting an access token from a /token endpoint: aud OPTIONAL. Specifies the audience for which the client is requesting an access token. If this parameter is missing it is assumed that the client and the AS have a pre-established @@ -683,30 +718,31 @@ If a client submits a request for an access token without specifying an "aud" parameter, and the AS does not have a default "aud" value for this client, then the AS MUST respond with an error message with the CoAP response code 4.00 (Bad Request). cnf OPTIONAL. This field contains information about the key the client would like to bind to the access token for proof-of- possession. It is NOT RECOMMENDED that a client submits a symmetric key value to the AS using this parameter. See - Section 6.4.5 for more details on the formatting of the 'cnf' + Section 6.5.5 for more details on the formatting of the 'cnf' parameter. The following examples illustrate different types of requests for proof-of-possession tokens. Figure 2 shows a request for a token with a symmetric proof-of- possession key. Note that in this example we assume a DTLS-based communication security profile, therefore the Content-Type is - "application/cbor". + "application/cbor". The content is displayed in CBOR diagnostic + notation, without abbreviations for better readability. Header: POST (Code=0.02) Uri-Host: "server.example.com" Uri-Path: "token" Content-Type: "application/cbor" Payload: { "grant_type" : "client_credentials", "aud" : "tempSensor4711", } @@ -719,20 +755,22 @@ security-based profile, therefore the Content-Type is "application/ cose+cbor". Header: POST (Code=0.02) Uri-Host: "server.example.com" Uri-Path: "token" Content-Type: "application/cose+cbor" Payload: { "grant_type" : "client_credentials", + "client_id" : "myclient", + "client_secret" : "mysecret234", "cnf" : { "COSE_Key" : { "kty" : "EC", "kid" : h'11', "crv" : "P-256", "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' } } } @@ -759,69 +797,87 @@ "aud" : "valve424", "scope" : "read", "cnf" : { "kid" : b64'6kg0dXJM13U' } } Figure 4: Example request for an access token bound to a key reference. -6.2. AS-to-Client Response +6.3. AS-to-Client Response If the access token request has been successfully verified by the AS and the client is authorized to obtain an access token corresponding to its access token request, the AS sends a response with the CoAP response code 2.01 (Created). If client request was invalid, or not authorized, the AS returns an error response as described in - Section 6.3. + Section 6.4. Note that the AS decides which token type and profile to use when issuing a successful response. It is assumed that the AS has prior - knowledge of the capabilities of the client, and the RS. This prior - knowledge may, for example, be set by the use of a dynamic client - registration protocol exchange [RFC7591]. + knowledge of the capabilities of the client, and the RS (see + Appendix D. This prior knowledge may, for example, be set by the use + of a dynamic client registration protocol exchange [RFC7591]. - The content of the successful reply MUST be encoded as CBOR map, - containing parameters as speficied in section 5.1 of [RFC6749]. In - addition to these parameters, the following parameters are also part - of a successful response: + The content of the successful reply is the RS Information. It MUST + be encoded as CBOR map, containing parameters as specified in section + 5.1 of [RFC6749]. In addition to these parameters, the following + parameters are also part of a successful response: profile REQUIRED. This indicates the profile that the client MUST use - towards the RS. See Section 6.4.4 for the formatting of this + towards the RS. See Section 6.5.4 for the formatting of this parameter. cnf REQUIRED if the token type is 'pop'. OPTIONAL otherwise. If a symmetric proof-of-possession algorithms was selected, this field contains the proof-of-possession key. If an asymmetric algorithm was selected, this field contains information about the public key - used by the RS to authenticate. See Section 6.4.5 for the + used by the RS to authenticate. See Section 6.5.5 for the formatting of this parameter. token_type OPTIONAL. By default implementations of this framework SHOULD assume that the token_type is 'pop'. If a specific use case requires another token_type (e.g. 'Bearer') to be used then this parameter is REQUIRED. Note that if CBOR Web Tokens [I-D.ietf-ace-cbor-web-token] are used, the access token can also contain a 'cnf' claim. This claim is however consumed by a different party. The access token is created by the AS and processed by the RS (and opaque to the client) whereas the RS Information is created by the AS and processed by the client; it is never forwarded to the resource server. + Figure Figure 5 summarizes the parameters that may be part of the RS + Information. + + /-------------------+--------------------------\ + | Parameter name | Specified in | + |-------------------+--------------------------| + | access_token | RFC 6749 | + | token_type | RFC 6749 | + | expires_in | RFC 6749 | + | refresh_token | RFC 6749 | + | scope | RFC 6749 | + | state | RFC 6749 | + | profile | [[ this specification ]] | + | cnf | [[ this specification ]] | + \-------------------+--------------------------/ + + Figure 5: RS Information parameters + The following examples illustrate different types of responses for proof-of-possession tokens. - Figure 5 shows a response containing a token and a 'cnf' parameter + Figure 6 shows a response containing a token and a 'cnf' parameter with a symmetric proof-of-possession key. Note that we assume a DTLS-based communication security profile for this example, therefore the Content-Type is "application/cbor". Header: Created (Code=2.01) Content-Type: "application/cbor" Payload: { "access_token" : b64'SlAV32hkKG ... (remainder of CWT omitted for brevity; @@ -830,93 +886,117 @@ "expires_in" : "3600", "cnf" : { "COSE_Key" : { "kty" : "Symmetric", "kid" : b64'39Gqlw', "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' } } } - Figure 5: Example AS response with an access token bound to a + Figure 6: Example AS response with an access token bound to a symmetric key. -6.3. Error Response +6.4. Error Response The error responses for CoAP-based interactions with the AS are equivalent to the ones for HTTP-based interactions as defined in - section 5.2 of [RFC6749], with the following differences: The - Content-Type is specified by the communication security profile used - between client and AS. The raw payload before being processed by the - communication security protocol MUST be encoded as a CBOR map and the - CoAP response code 4.00 (Bad Request) MUST be used unless specified - otherwise. + section 5.2 of [RFC6749], with the following differences: -6.4. New Request and Response Parameters + o The Content-Type MUST be specified by the communication security + profile used between client and AS. The raw payload before being + processed by the communication security protocol MUST be encoded + as a CBOR map. + o The CoAP response code 4.00 (Bad Request) MUST be used for all + error responses, except for invalid_client where the CoAP response + code 4.01 (Unauthorized) MAY be used under the same conditions as + specified in section 5.2 of [RFC6749]. + o The parameters "error", "error_description" and "error_uri" MAY be + abbreviated using the codes specified in table Figure 13. + o The error codes MAY be abbreviated using the codes specified in + table Figure 7. + + /------------------------+----------+--------------\ + | error code | CBOR Key | Major Type | + |------------------------+----------+--------------| + | invalid_request | 0 | 0 (uint) | + | invalid_client | 1 | 0 | + | invalid_grant | 2 | 0 | + | unauthorized_client | 3 | 0 | + | unsupported_grant_type | 4 | 0 | + | invalid_scope | 5 | 0 | + \------------------------+----------+--------------/ + + Figure 7: CBOR abbreviations for common error codes + +6.5. Request and Response Parameters This section provides more detail about the new parameters that can be used in access token requests and responses, as well as abbreviations for more compact encoding of existing parameters and common parameter values. -6.4.1. Audience +6.5.1. Audience This parameter specifies for which audience the client is requesting a token. It should be encoded as CBOR text string (major type 3). The formatting and semantics of these strings are application specific. -6.4.2. Grant Type +6.5.2. Grant Type - The abbreviations in Figure 6 MAY be used in CBOR encodings instead + The abbreviations in Figure 8 MAY be used in CBOR encodings instead of the string values defined in [RFC6749]. /--------------------+----------+--------------\ | grant_type | CBOR Key | Major Type | |--------------------+----------+--------------| | password | 0 | 0 (uint) | | authorization_code | 1 | 0 | | client_credentials | 2 | 0 | | refresh_token | 3 | 0 | \--------------------+----------+--------------/ - Figure 6: CBOR abbreviations for common grant types + Figure 8: CBOR abbreviations for common grant types -6.4.3. Token Type +6.5.3. Token Type - The 'token_type' parameter allows the AS to indicate to the client - which type of access token it is receiving (e.g. a bearer token). - The 'pop' token type MUST be assumed by default if the AS does not - provide a different value. + The toke_type parameter is defined in [RFC6749], allowing the AS to + indicate to the client which type of access token it is receiving + (e.g. a bearer token). This document registers the new value "pop" for the OAuth Access Token Types registry, specifying a Proof-of-Possession token. How - the proof-of-possession is performed is specified by the profiles. + the proof-of-possession is performed MUST be specified by the + profiles. - The values in the 'token_type' parameter are CBOR text strings (major - type 3). + The values in the 'token_type' parameter MUST be CBOR text strings + (major type 3). -6.4.4. Profile + In this framework token type 'pop' MUST be assumed by default if the + AS does not provide a different value. - Profiles of this framework are expected to define the communication - protocol and the communication security protocol between the client - and the RS. Furthermore profiles are expected to define proof-of- - possession methods, if they support proof-of-possession tokens. +6.5.4. Profile - A profile should specify an identifier that is used to uniquely + Profiles of this framework MUST define the communication protocol and + the communication security protocol between the client and the RS. + Furthermore profiles MUST define proof-of-possession methods, if they + support proof-of-possession tokens. + + A profile MUST specify an identifier that is used to uniquely identify itself in the 'profile' parameter. Profiles MAY define additional parameters for both the token request and the RS Information in the access token response in order to - support negotioation or signalling of profile specific parameters. + support negotiation or signalling of profile specific parameters. -6.4.5. Confirmation +6.5.5. Confirmation The "cnf" parameter identifies or provides the key used for proof-of- possession or for authenticating the RS depending on the proof-of- possession algorithm and the context cnf is used in. This framework extends the definition of 'cnf' from [RFC7800] by adding CBOR/COSE encodings and the use of 'cnf' for transporting keys in the RS Information. The "cnf" parameter is used in the following contexts with the following meaning: @@ -932,192 +1012,203 @@ o In the introspection response AS -> RS, to indicate the proof-of- possession key bound to the introspected token. o In the client token AS -> RS -> C, to indicate the proof-of- possession key bound to the access token. A CBOR encoded payload MAY contain the 'cnf' parameter with the following contents: COSE_Key In this case the 'cnf' parameter contains the proof-of- possession key to be used by the client. An example is shown in - Figure 7. + Figure 9. "cnf" : { "COSE_Key" : { "kty" : "EC", "kid" : h'11', "crv" : "P-256", "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' } } - Figure 7: Confirmation parameter containing a public key + Figure 9: Confirmation parameter containing a public key Note that the COSE_Key structure may contain an "alg" or "key_ops" parameter. If such parameters are present, a client MUST NOT use a key that is not compatible with the profile or proof-of- possession algorithm according to those parameters. + COSE_Encrypted In this case the 'cnf' parameter contains an encrypted symmetric key destined for the client. The client is - assumed to be able to decrypt the cihpertext of this parameter. + assumed to be able to decrypt the ciphertext of this parameter. The parameter is encoded as COSE_Encrypted object wrapping a - COSE_Key object. Figure 8 shows an example of this type of + COSE_Key object. Figure 10 shows an example of this type of encoding. "cnf" : { "COSE_Encrypted" : { 993( [ h'a1010a' # protected header : {"alg" : "AES-CCM-16-64-128"} "iv" : b64'ifUvZaHFgJM7UmGnjA', # unprotected header b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext ] ) } } - Figure 8: Confirmation paramter containing an encrypted symmetric key + Figure 10: Confirmation parameter containing an encrypted symmetric + key The ciphertext here could e.g. contain a symmetric key as in - Figure 9. + Figure 11. { "kty" : "Symmetric", "kid" : b64'39Gqlw', "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' } - Figure 9: Example plaintext of an encrypted cnf parameter + Figure 11: Example plaintext of an encrypted cnf parameter Key Identifier In this case the 'cnf' parameter references a key that is assumed to be previously known by the recipient. This allows clients that perform repeated requests for an access token for the same audience but e.g. with different scopes to omit key transport in the access token, token request and token response. - Figure 10 shows such an example. + Figure 12 shows such an example. "cnf" : { "kid" : b64'39Gqlw' } - Figure 10: A Confirmation parameter with just a key identifier + Figure 12: A Confirmation parameter with just a key identifier -6.5. Mapping parameters to CBOR + This specification establishes the IANA "CWT Confirmation Methods" + registry for these types of confirmation methods in Section 11.10 and + registers the methods defined by this specification. Other + specifications can register other methods used for confirmation. The + registry is meant to be analogous to the "JWT Confirmation Methods" + registry defined by [RFC7800]. + +6.6. Mapping parameters to CBOR All OAuth parameters in access token requests and responses are mapped to CBOR types as follows and are given an integer key value to save space. /-------------------+----------+-----------------\ | Parameter name | CBOR Key | Major Type | |-------------------+----------+-----------------| | aud | 3 | 3 | | client_id | 8 | 3 (text string) | | client_secret | 9 | 2 (byte string) | | response_type | 10 | 3 | | redirect_uri | 11 | 3 | | scope | 12 | 3 | | state | 13 | 3 | | code | 14 | 2 | - | error_description | 15 | 3 | - | error_uri | 16 | 3 | - | grant_type | 17 | 0 (unit) | - | access_token | 18 | 3 | - | token_type | 19 | 0 | - | expires_in | 20 | 0 | - | username | 21 | 3 | - | password | 22 | 3 | - | refresh_token | 23 | 3 | - | cnf | 24 | 5 (map) | - | profile | 25 | 3 | + | error | 15 | 3 | + | error_description | 16 | 3 | + | error_uri | 17 | 3 | + | grant_type | 18 | 0 | + | access_token | 19 | 3 | + | token_type | 20 | 0 | + | expires_in | 21 | 0 | + | username | 22 | 3 | + | password | 23 | 3 | + | refresh_token | 24 | 3 | + | cnf | 25 | 5 (map) | + | profile | 26 | 3 | \-------------------+----------+-----------------/ - Figure 11: CBOR mappings used in token requests + Figure 13: CBOR mappings used in token requests 7. The 'Introspect' Endpoint Token introspection [RFC7662] is 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 CoAP and CBOR. Communication between the RS and the introspection endpoint at the AS MUST be integrity protected and encrypted. Furthermore AS and RS MUST perform mutual authentication. Finally the AS SHOULD verify that the RS has the right to access introspection information about - the provided token. Profiles of this framework are expected to - specify how authentication and communication security is implemented. + the provided token. Profiles of this framework that support + introspection MUST specify how authentication and communication + security between RS and AS is implemented. The figures of this section uses CBOR diagnostic notation without the integer abbreviations for the parameters or their values for better readability. 7.1. RS-to-AS Request The RS sends a CoAP POST request to the introspection endpoint at the - AS, the profile is expected to specify the Content-Type and wrapping - of the payload. The payload MUST be encoded as a CBOR map with a - 'token' parameter containing the access token along with optional - parameters representing additional context that is known by the RS to - aid the AS in its response. + AS, the profile MUST specify the Content-Type and wrapping of the + payload. The payload MUST be encoded as a CBOR map with a 'token' + parameter containing the access token along with optional parameters + representing additional context that is known by the RS to aid the AS + in its response. The same parameters are required and optional as in section 2.1 of RFC 7662 [RFC7662]. - For example, Figure 12 shows a RS calling the token introspection + For example, Figure 14 shows a RS calling the token introspection endpoint at the AS to query about an OAuth 2.0 proof-of-possession token. Note that we assume a object security-based communication security profile for this example, therefore the Content-Type is "application/cose+cbor". Header: POST (Code=0.02) Uri-Host: "server.example.com" Uri-Path: "introspect" Content-Type: "application/cose+cbor" Payload: { "token" : b64'7gj0dXJQ43U', "token_type_hint" : "pop" } - Figure 12: Example introspection request. + Figure 14: Example introspection request. 7.2. AS-to-RS Response If the introspection request is authorized and successfully processed, the AS sends a response with the CoAP response code 2.01 (Created). If the introspection request was invalid, not authorized or couldn't be processed the AS returns an error response as described in Section 7.3. In a successful response, the AS encodes the response parameters in a CBOR map including with the same required and optional parameters as in section 2.2. of RFC 7662 [RFC7662] with the following additions: cnf OPTIONAL. This field contains information about the proof-of- possession key that binds the client to the access token. See - Section 6.4.5 for more details on the formatting of the 'cnf' + Section 6.5.5 for more details on the formatting of the 'cnf' parameter. profile OPTIONAL. This indicates the profile that the RS MUST use with - the client. See Section 6.4.4 for more details on the formatting + the client. See Section 6.5.4 for more details on the formatting of this parameter. client_token OPTIONAL. This parameter contains information that the RS MUST pass on to the client. See Section 7.4 for more details. - For example, Figure 13 shows an AS response to the introspection - request in Figure 12. Note that we assume a DTLS-based communication + For example, Figure 15 shows an AS response to the introspection + request in Figure 14. Note that we assume a DTLS-based communication security profile for this example, therefore the Content-Type is "application/cbor". Header: Created Code=2.01) Content-Type: "application/cbor" Payload: { "active" : true, "scope" : "read", "profile" : "coap_dtls", @@ -1125,21 +1216,21 @@ (remainder of client token omitted for brevity)', "cnf" : { "COSE_Key" : { "kty" : "Symmetric", "kid" : b64'39Gqlw', "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' } } } - Figure 13: Example introspection response. + Figure 15: Example introspection response. 7.3. Error Response The error responses for CoAP-based interactions with the AS are equivalent to the ones for HTTP-based interactions as defined in section 2.3 of [RFC7662], with the following differences: o If content is sent, the Content-Type MUST be set according to the specification of the communication security profile, and the content payload MUST be encoded as a CBOR map. @@ -1140,24 +1231,27 @@ equivalent to the ones for HTTP-based interactions as defined in section 2.3 of [RFC7662], with the following differences: o If content is sent, the Content-Type MUST be set according to the specification of the communication security profile, and the content payload MUST be encoded as a CBOR map. o If the credentials used by the RS are invalid the AS MUST respond with the CoAP response code 4.01 (Unauthorized) and use the required and optional parameters from section 5.2 in RFC 6749 [RFC6749]. - o If the RS does not have the right to perform this introspection request, the AS MUST respond with the CoAP response code 4.03 (Forbidden). In this case no payload is returned. + o The parameters "error", "error_description" and "error_uri" MAY be + abbreviated using the codes specified in table Figure 13. + o The error codes MAY be abbreviated using the codes specified in + table Figure 7. Note that a properly formed and authorized query for an inactive or otherwise invalid token does not warrant an error response by this specification. In these cases, the authorization server MUST instead respond with an introspection response with the "active" field set to "false". 7.4. Client Token EDITORIAL NOTE: We have tentatively introduced this concept and would @@ -1169,63 +1263,63 @@ suggests the following approach: The client is pre-configured with a generic, long-term access token when it is commissioned. When the client then tries to access a RS it transmits this access token. The RS then performs token introspection to learn what access this token grants. In the introspection response, the AS also relays information for the client, such as the proof-of-possession key, through the RS. The RS passes on this Client Token to the client in response to the submission of the token. The client_token parameter is designed to carry such information, and - is intended to be used as described in Figure 14. + is intended to be used as described in Figure 16. Resource Authorization Client Server Server | | | | | | C: +--------------->| | | POST | | | Access Token | | | D: +--------------->| | | Introspection | | | Request | | | | | E: +<---------------+ | | Introspection | | | Response | | | + Client Token | |<---------------+ | | 2.01 Created | | | + Client Token | - Figure 14: Use of the client_token parameter. + Figure 16: Use of the client_token parameter. The client token is a COSE_Encrypted object, containing as payload a CBOR map with the following claims: cnf REQUIRED if the token type is 'pop', OPTIONAL otherwise. Contains information about the proof-of-possession key the client is to use - with its access token. See Section 6.4.5. + with its access token. See Section 6.5.5. token_type - OPTIONAL. See Section 6.4.3. + OPTIONAL. See Section 6.5.3. profile - REQUIRED. See Section 6.4.4. + REQUIRED. See Section 6.5.4. rs_cnf OPTIONAL. Contains information about the key that the RS uses to authenticate towards the client. If the key is symmetric then this claim MUST NOT be part of the Client Token, since this is the same key as the one specified through the 'cnf' claim. This claim - uses the same encoding as the 'cnf' parameter. See Section 6.4.4. + uses the same encoding as the 'cnf' parameter. See Section 6.5.4. The AS encrypts this token using a key shared between the AS and the client, so that only the client can decrypt it and access its payload. How this key is established is out of scope of this framework. 7.5. Mapping Introspection parameters to CBOR The introspection request and response parameters are mapped to CBOR types as follows and are given an integer key value to save space. @@ -1235,83 +1329,93 @@ |-----------------+----------+-----------------| | iss | 1 | 3 (text string) | | sub | 2 | 3 | | aud | 3 | 3 | | exp | 4 | 6 tag value 1 | | nbf | 5 | 6 tag value 1 | | iat | 6 | 6 tag value 1 | | cti | 7 | 2 (byte string) | | client_id | 8 | 3 | | scope | 12 | 3 | - | token_type | 19 | 3 | - | username | 21 | 3 | - | cnf | 24 | 5 (map) | - | profile | 25 | 0 (uint) | - | token | 26 | 3 | - | token_type_hint | 27 | 3 | - | active | 28 | 0 | - | client_token | 29 | 3 | - | rs_cnf | 30 | 5 | + | token_type | 20 | 3 | + | username | 22 | 3 | + | cnf | 25 | 5 (map) | + | profile | 26 | 0 (uint) | + | token | 27 | 3 | + | token_type_hint | 28 | 3 | + | active | 29 | 0 | + | client_token | 30 | 3 | + | rs_cnf | 31 | 5 | \-----------------+----------+-----------------/ - Figure 15: CBOR Mappings to Token Introspection Parameters. + Figure 17: CBOR Mappings to Token Introspection Parameters. 8. The Access Token This framework RECOMMENDS the use of CBOR web token (CWT) as specified in [I-D.ietf-ace-cbor-web-token]. In order to facilitate offline processing of access tokens, this draft specifies the "cnf" and "scope" claims for 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]. The meaning of a specific scope value is application specific and expected to be known to the RS running that application. The "cnf" claim follows the same rules as specified for JSON web token in RFC7800 [RFC7800], except that it is encoded in CBOR in the - same way as specified for the "cnf" parameter in Section 6.4.5. + same way as specified for the "cnf" parameter in Section 6.5.5. 8.1. The 'Authorization Information' Endpoint The access token, containing authorization information and - information of the key used by the client, needs to be transported to - the RS so that the RS can authenticate and authorize the client + 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 request. This section defines a method for transporting the access token to the RS using CoAP. Profiles of this framework MAY define other - methods for token transport. Implementations conforming to this - framework MUST implement this method of token transportation. + methods for token transport. - The method consists of a /authz-info endpoint, implemented by the RS. - A client using this method MUST make a POST request to /authz-info 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.04 (Changed). + The method consists of an /authz-info endpoint, implemented by the + RS. A client using this method MUST make a POST request to /authz- + info 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 the identifier of the token + (e.g. the cti for a CWT) as a payload. If the token is not valid, the RS MUST respond with the CoAP response 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 the CoAP - response code 4.03 (Forbidden). + response 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 the CoAP response code 4.00 (Bad + Request). In the latter case the RS MAY provide additional + information in the error response, in order to clarify what went + wrong. The RS MAY make an introspection request to validate the token before responding to the POST /authz-info request. If the introspection response contains a client token (Section 7.4) then this token SHALL - be included in the payload of the 2.04 (Changed) response. + be included in the payload of the 2.01 (Created) response. - Profiles are expected to specify how the /authz-info endpoint is - 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. + Profiles MUST specify how the /authz-info endpoint is 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 RS MUST be prepared to store more than one token for each client, + and MUST apply the combined permissions granted by all applicable, + valid tokens to client requests. 8.2. 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. We list the possibilities here including what functionality they require of the RS. o The token is a CWT/JWT and includes a 'exp' claim and possibly the 'nbf' claim. The RS verifies these by comparing them to values @@ -1330,20 +1434,25 @@ which is a CWT/JWT. 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. + If a token, that authorizes a long running request such as e.g. a + CoAP Observe [RFC7641], expires, the RS MUST send an error response + with the response code 4.01 Unauthorized to the client and then + terminate processing the long running request. + 9. Security Considerations The entire document is about security. Security considerations applicable to authentication and authorization in RESTful environments provided in OAuth 2.0 [RFC6749] apply to this work, as well as the security considerations from [I-D.ietf-ace-actors]. Furthermore [RFC6819] provides additional security considerations for OAuth which apply to IoT deployments as well. A large range of threats can be mitigated by protecting the contents @@ -1355,73 +1464,106 @@ be encrypted by the authorization server with a long-term key shared with the resource server. It is important for the authorization server to include the identity of the intended recipient (the audience), typically a single resource server (or a list of resource servers), in the token. Using a single shared secret with multiple resource servers to simplify key management is NOT RECOMMENDED since the benefit from using the proof- of-possession concept is significantly reduced. - Token replay is also not possible since an eavesdropper will also - have to obtain the corresponding private key or shared secret that is - bound to the access token. Nevertheless, it is good practice to - limit the lifetime of the access token and therefore the lifetime of - associated key. + Token replay is also more difficult since an eavesdropper will have + to obtain the token and the corresponding private key or shared + secret that is bound to the access token. Nevertheless, it is good + practice to limit the lifetime of the access token and therefore the + lifetime of associated key. The authorization server MUST offer confidentiality protection for any interactions with the client. This step is extremely important since the client will obtain the session key from the authorization server for use with a specific access token. Not using confidentiality protection exposes this secret (and the access token) - to an eavesdropper thereby making the proof-of-possession security - model completely insecure. This framework relies on profiles to - define how confidentiality protection is provided, and additional - protection can be applied by encrypting the CWT as specified in - section 5.1 of [I-D.ietf-ace-cbor-web-token] to provide an additional - layer of protection for cases where keying material is conveyed, for - example, to a hardware security module. + to an eavesdropper thereby completely negating proof-of-possession + security. Profiles MUST specify how confidentiality protection is + provided, and additional protection can be applied by encrypting the + token, for example encryption of CWTs is specified in section 5.1 of + [I-D.ietf-ace-cbor-web-token]. Developers MUST ensure that the ephemeral credentials (i.e., the - private key or the session key) is not leaked to third parties. An + private key or the session key) are not leaked to third parties. An adversary in possession of the ephemeral credentials bound to the 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. Clients can at any time request a new proof-of-possession capable access token. Using a refresh token to regularly request new access tokens that are bound to fresh and unique keys is important if the client has this capability. Keeping the lifetime of the access token short allows the authorization server to use shorter 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 then - they SHOULD scope these access tokens to a specific permissions. + When authorization servers bind symmetric keys to access tokens, they + SHOULD scope these access tokens to a specific permissions. + Furthermore access tokens SHOULD NOT apply to an audience that + comprises more than one RS, since otherwise any RS in the audience + can impersonate the client towards the other members of the audience. -10. IANA Considerations + Clients using an asymmetric key pair for proof-of-possession towards + several different RS should be aware that they will need to rotate + that key pair more frequently than if it was only used towards a + single RS. + +10. 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 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, the + Resource Owner can bind the grants to anonymous (rotating) + credentials, that do not allow the AS to link different access token + requests by the same client. + + If access tokens are only integrity protected and not encrypted, they + may reveal information to attackers listening on the wire, or able to + acquire the access tokens in some other way. In the case of CWTs or + JWTs the token may e.g. reveal the audience, the scope and the + confirmation method used by the client. The latter may reveal the + client's identity. + + Clients using asymmetric keys for proof-of-possession should be aware + of the consequences of using the same key pair for proof-of- + possession towards different RS. A set of colluding RS or an + attacker able to obtain the access tokens will be able to link the + requests, or even to determine the client's identity. + +11. IANA Considerations This specification registers new parameters for OAuth and establishes registries for mappings to CBOR. -10.1. OAuth Introspection Response Parameter Registration +11.1. OAuth Introspection Response Parameter Registration This specification registers the following parameters in the OAuth introspection response parameters o Name: "cnf" o Description: Key to prove the right to use an access token, as defined in [RFC7800]. o Change Controller: IESG o Specification Document(s): this document + o Name: "aud" o Description: Reference to intended receiving RS, as defined in PoP token specification. o Change Controller: IESG o Specification Document(s): this document o Name: "profile" o Description: The communication and communication security profile used between client and RS, as defined in ACE profiles. o Change Controller: IESG @@ -1431,149 +1573,149 @@ o Description: Information that the RS MUST pass to the client e.g. about the proof-of-possession keys. o Change Controller: IESG o Specification Document(s): this document o Name: "rs_cnf" o Description: Describes the public key the RS uses to authenticate. o Change Controller: IESG o Specification Document(s): this document -10.2. OAuth Parameter Registration +11.2. OAuth Parameter Registration This specification registers the following parameters in the OAuth Parameters Registry o Parameter name: "profile" o Parameter usage location: token request, and token response o Change Controller: IESG o Specification Document(s): this document o Name: "cnf" o Description: Key to prove the right to use an access token, as defined in [RFC7800]. o Change Controller: IESG o Specification Document(s): this document -10.3. OAuth Access Token Types +11.3. OAuth Access Token Types This specification registers the following new token type in the OAuth Access Token Types Registry o Name: "PoP" o Description: A proof-of-possession token. o Change Controller: IESG o Specification Document(s): this document -10.4. Token Type Mappings +11.4. Token Type Mappings A new registry will be requested from IANA, entitled "Token Type Mappings". The registry is to be created as Expert Review Required. -10.4.1. Registration Template +11.4.1. Registration Template 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 in the range of 1 to 65536. 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. -10.4.2. Initial Registry Contents +11.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" o Mapped value: 2 o Change Controller: IESG o Specification Document(s): this document -10.5. CBOR Web Token Claims +11.5. CBOR Web Token Claims This specification registers the following new claims in the CBOR Web Token (CWT) registry: o Claim Name: "scope" o Claim Description: The scope of an access token as defined in [RFC6749]. o Change Controller: IESG o Specification Document(s): this document o Claim Name: "cnf" o Claim Description: The proof-of-possession key of an access token as defined in [RFC7800]. o Change Controller: IESG o Specification Document(s): this document -10.6. ACE Profile Registry +11.6. ACE Profile Registry A new registry will be requested from IANA, entitled "ACE Profile Registry". The registry is to be created as Expert Review Required. -10.6.1. Registration Template +11.6.1. Registration Template 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. The value MUST be an integer in the range of 1 to 65536. 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. -10.7. OAuth Parameter Mappings Registry +11.7. OAuth 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. -10.7.1. Registration Template +11.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 in the range of 1 to 65536. 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. -10.7.2. Initial Registry Contents +11.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 @@ -1600,100 +1742,105 @@ o Parameter name: "state" o CBOR key value: 13 o Change Controller: IESG o Specification Document(s): this document o Parameter name: "code" o CBOR key value: 14 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "error_description" + o Parameter name: "error" o CBOR key value: 15 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "error_uri" + o Parameter name: "error_description" o CBOR key value: 16 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "grant_type" + o Parameter name: "error_uri" o CBOR key value: 17 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "access_token" + o Parameter name: "grant_type" o CBOR key value: 18 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "token_type" + o Parameter name: "access_token" o CBOR key value: 19 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "expires_in" + o Parameter name: "token_type" o CBOR key value: 20 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "username" + o Parameter name: "expires_in" o CBOR key value: 21 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "password" + o Parameter name: "username" o CBOR key value: 22 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "refresh_token" + o Parameter name: "password" o CBOR key value: 23 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "cnf" + o Parameter name: "refresh_token" o CBOR key value: 24 o Change Controller: IESG o Specification Document(s): this document - o Parameter name: "profile" + o Parameter name: "cnf" o CBOR key value: 25 o Change Controller: IESG o Specification Document(s): this document -10.8. Introspection Endpoint CBOR Mappings Registry + o Parameter name: "profile" + o CBOR key value: 26 + o Change Controller: IESG + o Specification Document(s): this document + +11.8. Introspection Endpoint CBOR Mappings Registry A new registry will be requested from IANA, entitled "Introspection Endpoint CBOR Mappings Registry". The registry is to be created as Expert Review Required. -10.8.1. Registration Template +11.8.1. Registration Template 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 in the range of 1 to 65536. 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. -10.8.2. Initial Registry Contents +11.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 @@ -1726,65 +1873,65 @@ 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: 19 + o CBOR key value: 20 o Change Controller: IESG o Specification Document(s): this document o Response parameter name: "username" - o CBOR key value: 21 + o CBOR key value: 22 o Change Controller: IESG o Specification Document(s): this document o Parameter name: "cnf" - o CBOR key value: 24 + o CBOR key value: 25 o Change Controller: IESG o Specification Document(s): this document o Parameter name: "profile" - o CBOR key value: 25 + o CBOR key value: 26 o Change Controller: IESG o Specification Document(s): this document o Response parameter name: "token" - o CBOR key value: 26 + o CBOR key value: 27 o Change Controller: IESG o Specification Document(s): this document o Response parameter name: "token_type_hint" - o CBOR key value: 27 + o CBOR key value: 28 o Change Controller: IESG o Specification Document(s): this document o Response parameter name: "active" - o CBOR key value: 28 + o CBOR key value: 29 o Change Controller: IESG o Specification Document(s): this document o Response parameter name: "client_token" - o CBOR key value: 29 + o CBOR key value: 30 o Change Controller: IESG o Specification Document(s): this document o Response parameter name: "rs_cnf" - o CBOR key value: 30 + o CBOR key value: 31 o Change Controller: IESG o Specification Document(s): this document -10.9. CoAP Option Number Registration +11.9. CoAP Option Number Registration This section registers the "Access-Token" CoAP Option Number in the "CoRE Parameters" sub-registry "CoAP Option Numbers" in the manner described in [RFC7252]. Name Access-Token Number @@ -1802,48 +1949,100 @@ 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 -11. Acknowledgments +11.10. CWT Confirmation Methods Registry + + This specification establishes the IANA "CWT Confirmation Methods" + registry for CWT "cnf" member values. The registry records the + confirmation method member and a reference to the specification that + defines it. + +11.10.1. Registration Template + + Confirmation Method Name: + The name requested (e.g., "kid"). This name is intended to be + human readable and be used for debugging purposes. It is case + sensitive. Names may not match other registered names in a case- + insensitive manner unless the Designated Experts state that there + is a compelling reason to allow an exception. + + Confirmation Method Value: + Integer representation for the confirmation method value. + Intended for use to uniquely identify the confirmation method. + The value MUST be an integer in the range of 1 to 65536. + + Confirmation Method Description: + Brief description of the confirmation method (e.g. "Key + Identifier"). + + 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. + +11.10.2. Initial Registry Contents + + o Confirmation Method Name: "COSE_Key" + o Confirmation Method Value: 1 + o Confirmation Method Description: A COSE_Key that is either a + public key or a symmetric key. + o Change Controller: IESG + o Specification Document(s): this document + + o Confirmation Method Name: "COSE_Encrypted" + o Confirmation Method Value: 2 + o Confirmation Method Description: A COSE_Encrypted structure that + wraps a COSE_Key containing a symmetric key. + o Change Controller: IESG + o Specification Document(s): this document + + o Confirmation Method Name: "Key Identifier" + o Confirmation Method Value: 3 + o Confirmation Method Description: A key identifier. + o Change Controller: IESG + o Specification Document(s): this document + +12. Acknowledgments We would like to thank Eve Maler for her contributions to the use of OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion - input, and Malisa Vucinic for his input on the ACRE proposal - [I-D.seitz-ace-core-authz] which was one source of inspiration for - this work. Finally, we would like to thank the ACE working group in + input, and Malisa Vucinic for his input on the predecessors of this + proposal. Finally, we would like to thank the ACE working group in general for their feedback. We would like to thank the authors of draft-ietf-oauth-pop-key- distribution, from where we copied large parts of our security considerations. Ludwig Seitz and Goeran Selander worked on this document as part of the CelticPlus project CyberWI, with funding from Vinnova. -12. References - -12.1. Normative References - - [I-D.ietf-ace-cbor-web-token] - Wahlstroem, E., Jones, M., Tschofenig, H., and S. Erdtman, - "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-01 - (work in progress), July 2016. +13. References +13.1. Normative References [I-D.ietf-cose-msg] Schaad, J., "CBOR Object Signing and Encryption (COSE)", - draft-ietf-cose-msg-23 (work in progress), October 2016. + draft-ietf-cose-msg-24 (work in progress), November 2016. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, January 2012, . @@ -1854,47 +2053,47 @@ [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, . [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- Possession Key Semantics for JSON Web Tokens (JWTs)", RFC 7800, DOI 10.17487/RFC7800, April 2016, . -12.2. Informative References +13.2. Informative References [I-D.ietf-ace-actors] Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An architecture for authorization in constrained environments", draft-ietf-ace-actors-04 (work in progress), September 2016. + [I-D.ietf-ace-cbor-web-token] + Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, + "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-02 + (work in progress), January 2017. + + [I-D.ietf-core-object-security] + Selander, G., Mattsson, J., Palombini, F., and L. Seitz, + "Object Security of CoAP (OSCOAP)", draft-ietf-core- + object-security-01 (work in progress), December 2016. + [I-D.ietf-oauth-device-flow] Denniss, W., Myrseth, S., Bradley, J., Jones, M., and H. Tschofenig, "OAuth 2.0 Device Flow", draft-ietf-oauth- device-flow-03 (work in progress), July 2016. [I-D.ietf-oauth-native-apps] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", - draft-ietf-oauth-native-apps-05 (work in progress), - October 2016. - - [I-D.seitz-ace-core-authz] - Seitz, L., Selander, G., and M. Vucinic, "Authorization - for Constrained RESTful Environments", draft-seitz-ace- - core-authz-00 (work in progress), June 2015. - - [I-D.selander-ace-object-security] - Selander, G., Mattsson, J., Palombini, F., and L. Seitz, - "Object Security of CoAP (OSCOAP)", draft-selander-ace- - object-security-06 (work in progress), October 2016. + draft-ietf-oauth-native-apps-07 (work in progress), + January 2017. [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, . [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, . @@ -1936,20 +2135,25 @@ [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, May 2015, . [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, . + [RFC7641] Hartke, K., "Observing Resources in the Constrained + Application Protocol (CoAP)", RFC 7641, + DOI 10.17487/RFC7641, September 2015, + . + [RFC7744] Seitz, L., Ed., Gerdes, S., Ed., Selander, G., Mani, M., and S. Kumar, "Use Cases for Authentication and Authorization in Constrained Environments", RFC 7744, DOI 10.17487/RFC7744, January 2016, . [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in the Constrained Application Protocol (CoAP)", RFC 7959, DOI 10.17487/RFC7959, August 2016, . @@ -2027,46 +2231,47 @@ security reasons, e.g. to avoid an entry point for Denial-of- Service attacks. The communication interactions this framework builds upon (as shown graphically in Figure 1) may be accomplished using a variety of different protocols, and not all parts of the message flow are used in all applications due to the communication constraints. While we envision deployments to make use of CoAP we explicitly want to support HTTP, HTTP/2 or specific protocols, such as Bluetooth Smart communication, which does not necessarily use IP. - The latter raises the need for application layer security over the various interfaces. -Appendix B. Roles and Responsibilites +Appendix B. Roles and Responsibilities Resource Owner * Make sure that the RS is registered at the AS. This includes making known to the AS which profiles, token_types, scopes, and key types (symmetric/asymmetric) the RS supports. Also making it known to the AS which audience(s) the RS identifies itself with. * Make sure that clients can discover the AS which is in charge of the RS. - * Make sure that the AS has the necessary, up-to-date, access - control policies for the RS. + * If the client-credentials grant is used, make sure that the AS + has the necessary, up-to-date, access control policies for the + RS. Requesting Party * Make sure that the client is provisioned the necessary credentials to authenticate to the AS. * Make sure that the client is configured to follow the security requirements of the Requesting Party, when issuing requests (e.g. minimum communication security requirements, trust anchors). + * Register the client at the AS. This includes making known to the AS which profiles, token_types, and key types (symmetric/ asymmetric) the client. Authorization Server * Register RS and manage corresponding security contexts. * Register clients and including authentication credentials. * Allow Resource Owners to configure and update access control policies related to their registered RS' @@ -2067,27 +2272,30 @@ Authorization Server * Register RS and manage corresponding security contexts. * Register clients and including authentication credentials. * Allow Resource Owners to configure and update access control policies related to their registered RS' * Expose the /token endpoint to allow clients to request tokens. * Authenticate clients that wish to request a token. * Process a token request against the authorization policies configured for the RS. - * Expose the /introspection endpoint that allows RS's to submit - token introspection requests. - * Authenticate RS's that wish to get an introspection response. - * Process token introspection requests. + * Optionally: Expose the /introspection endpoint that allows RS's + to submit token introspection requests. + * If providing an introspection endpoint: Authenticate RS's that + wish to get an introspection response. + * If providing an introspection endpoint: Process token + introspection requests. * Optionally: Handle token revocation. Client + * Discover the AS in charge of the RS that is to be targeted with a request. * Submit the token request (A). + Authenticate towards the AS. + Optionally (if not pre-configured): Specify which RS, which resource(s), and which action(s) the request(s) will target. + If raw public key (rpk) or certificate is used, make sure the AS has the right rpk or certificate for this client. * Process the access token and RS Information (B) @@ -2132,84 +2340,106 @@ + Check that tokens belonging to the client actually authorize the requested action. + Optionally: Check that the matching tokens are still valid, using introspection (if this is possible.) * Send a response following the agreed upon communication security. Appendix C. Requirements on Profiles This section lists the requirements on profiles of this framework, - for the convenience of a profile designer. All this information is - also given in the appropriate sections of the main document, this is - just meant as a checklist, to make it more easy to spot parts one - might have missed. + for the convenience of a profile designer. - o Specify the discovery process of how the client finds the right AS - for an RS it wants to send a request to. + o Optionally Specify the discovery process of how the client finds + the right AS for an RS it wants to send a request to. Section 4 o Specify the communication protocol the client and RS the must use - (e.g. CoAP). + (e.g. CoAP). Section 5 and Section 6.5.4 o Specify the security protocol the client and RS must use to protect their communication (e.g. OSCOAP or DTLS over CoAP). This must provide encryption and integrity protection. - o Specify how the client and the RS mutually authenticate + Section 6.5.4 + o Specify how the client and the RS mutually authenticate. + Section 4 o Specify the Content-format of the protocol messages (e.g. - "application/cbor" or "application/cose+cbor"). + "application/cbor" or "application/cose+cbor"). 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. - o Specify a unique profile identifier. - o Optionally specify how the RS talks to the AS for introspection. + possession protocol. Section 6.5.3 + o Specify a unique profile identifier. Section 6.5.4 + o Optionally specify how the RS talks to the AS for + introspection.Section 7 o Optionally specify how the client talks to the AS for requesting a - token. - o Specify how/if the /authz-info endpoint is protected. + token. Section 6 + o Specify how/if the /authz-info endpoint is protected. Section 8.1 o Optionally define other methods of token transport than the - /authz-info endpoint. + /authz-info endpoint. Section 8.1 -Appendix D. Deployment Examples +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 /introspect endpoints. How this information is + established is out of scope for this document. + + o The identifier of the client or RS. + o The profiles that the client or RS supports. + o The scopes that the RS supports. + o The audiences that the RS identifies with. + o The key types (e.g. pre-shared symmetric key, raw public key, key + length, other key parameters) that the client or RS supports. + o The types of access tokens the RS supports (e.g. CWT). + o If the RS supports CWTs, the COSE parameters for the crypto + wrapper (e.g. algorithm, key-wrap algorithm, key-length). + o The expiration time for access tokens issued to this RS (unless + the RS accepts a default time chosen by the AS). + o The symmetric key shared between client or RS and AS (if any). + o The raw public key of the client or RS (if any). + +Appendix E. Deployment Examples There is a large variety of IoT deployments, as is indicated in Appendix A, and this section highlights a few common variants. This section is not normative but illustrates how the framework can be applied. For each of the deployment variants there are a number of possible security setups between clients, resource servers and authorization servers. The main focus in the following subsections is on how authorization of a client request for a resource hosted by a RS is performed. This requires the the security of the requests and responses between the clients and the RS to consider. Note: CBOR diagnostic notation is used for examples of requests and responses. -D.1. Local Token Validation +E.1. Local Token Validation In this scenario we consider the case where the resource server is offline, i.e. it is not connected to the AS at the time of the access request. This access procedure involves steps A, B, C, and F of Figure 1. Since the resource server must be able to verify the access token locally, self-contained access tokens must be used. This example shows the interactions between a client, the authorization server and a temperature sensor acting as a resource - server. Message exchanges A and B are shown in Figure 16. + server. Message exchanges A and B are shown in Figure 18. A: The client first generates a public-private key pair used for communication security with the RS. The client sends the POST request to /token at the AS. The security of this request can be transport or application layer, it - is up the the comunication security profile to define. In the - example trasport layer identification of the AS is done and the + is up the the communication security profile to define. In the + example transport layer identification of the AS is done and the client identifies with client_id and client_secret as in classic OAuth. The request contains the public key of the client and the Audience parameter set to "tempSensorInLivingRoom", a value that the temperature sensor identifies itself with. The AS evaluates the request and authorizes the client to access the resource. B: The AS responds with a PoP token and RS Information. The PoP token contains the public key of the client, and the RS Information contains the public key of the RS. For communication security this example uses DTLS RawPublicKey between the client and the RS. The issued token will have a short validity time, @@ -2234,24 +2464,24 @@ A: +-------->| Header: POST (Code=0.02) | POST | Uri-Path:"token" | | Content-Type: application/cbor | | Payload: | | B: |<--------+ Header: 2.05 Content | 2.05 | Content-Type: application/cbor | | Payload: | | - Figure 16: Token Request and Response Using Client Credentials. + Figure 18: Token Request and Response Using Client Credentials. The information contained in the Request-Payload and the Response- - Payload is shown in Figure 17. Note that we assume a DTLS-based + Payload is shown in Figure 19. Note that we assume a DTLS-based communication security profile for this example, therefore the Content-Type is "application/cbor". Request-Payload : { "grant_type" : "client_credentials", "aud" : "tempSensorInLivingRoom", "client_id" : "myclient", "client_secret" : "qwerty" } @@ -2265,43 +2495,43 @@ "COSE_Key" : { "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kty" : "EC", "crv" : "P-256", "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' } } } - Figure 17: Request and Response Payload Details. + Figure 19: Request and Response Payload Details. - The content of the access token is shown in Figure 18. + The content of the access token is shown in Figure 20. { "aud" : "tempSensorInLivingRoom", "iat" : "1360189224", "exp" : "1360289224", "scope" : "temperature_g firmware_p", "cnf" : { "jwk" : { "kid" : b64'1Bg8vub9tLe1gHMzV76e8', "kty" : "EC", "crv" : "P-256", "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' } } } - Figure 18: Access Token including Public Key of the Client. + Figure 20: Access Token including Public Key of the Client. - Messages C and F are shown in Figure 19 - Figure 20. + Messages C and F are shown in Figure 21 - Figure 22. C: The client then sends the PoP token to the /authz-info endpoint at the RS. This is a plain CoAP request, i.e. no transport or application layer security between client and RS, since the token is integrity protected between AS and RS. The RS verifies that the PoP token was created by a known and trusted AS, is valid, and responds to the client. The RS caches the security context together with authorization information about this client contained in the PoP token. @@ -2309,21 +2539,21 @@ Client Server | | C: +-------->| Header: POST (Code=0.02) | POST | Uri-Path:"authz-info" | | Payload: SlAV32hkKG ... | | |<--------+ Header: 2.04 Changed | 2.04 | | | - Figure 19: Access Token provisioning to RS + Figure 21: Access Token provisioning to RS The client and the RS runs the DTLS handshake using the raw public keys established in step B and C. The client sends the CoAP request GET to /temperature on RS over DTLS. The RS verifies that the request is authorized, based on previously established security context. F: The RS responds with a resource representation over DTLS. Resource Client Server @@ -2333,42 +2563,42 @@ | | +-------->| Header: GET (Code=0.01) | GET | Uri-Path: "temperature" | | | | | | F: |<--------+ Header: 2.05 Content | 2.05 | Payload: | | - Figure 20: Resource Request and Response protected by DTLS. + Figure 22: Resource Request and Response protected by DTLS. -D.2. Introspection Aided Token Validation +E.2. Introspection Aided Token Validation In this deployment scenario we assume that a client is not able to access the AS at the time of the access request. Since the RS is, however, connected to the back-end infrastructure it 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 out during a phase when the client had connectivity to AS. 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. The resource server may use its online connectivity to validate the access token with the authorization server, which is shown in the example below. In the example interactions between an offline client (key fob), a RS (online lock), and an AS is shown. We assume that there is a provisioning step where the client has access to the AS. This corresponds to message exchanges A and B which are shown in - Figure 21. + Figure 23. Authorization consent from the resource owner can be pre-configured, but it can also be provided via an interactive flow with the resource owner. An example of this for the key fob case could be that the resource owner has a connected car, he buys a generic key that he wants to use with the car. To authorize the key fob he connects it to his computer that then provides the UI for the device. After that OAuth 2.0 implicit flow can used to authorize the key for his car at the the car manufacturers AS. @@ -2399,24 +2629,24 @@ A: +-------->| Header: POST (Code=0.02) | POST | Uri-Path:"token" | | Content-Type: application/cbor | | Payload: | | B: |<--------+ Header: 2.05 Content | | Content-Type: application/cbor | 2.05 | Payload: | | - Figure 21: Token Request and Response using Client Credentials. + Figure 23: Token Request and Response using Client Credentials. The information contained in the Request-Payload and the Response- - Payload is shown in Figure 22. + Payload is shown in Figure 24. Request-Payload: { "grant_type" : "client_credentials", "aud" : "lockOfDoor4711", "client_id" : "keyfob", "client_secret" : "qwerty" } Response-Payload: @@ -2427,21 +2657,21 @@ "cnf" : { "COSE_Key" : { "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kty" : "oct", "alg" : "HS256", "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' } } } - Figure 22: Request and Response Payload for C offline + Figure 24: Request and Response Payload for C offline The access token in this case is just an opaque string referencing the authorization information at the AS. C: Next, the client POSTs the access token to the /authz-info endpoint in the RS. This is a plain CoAP request, i.e. no DTLS between client and RS. Since the token is an opaque string, the RS cannot verify it on its own, and thus defers to respond the client with a status code until after step E. D: The RS forwards the token to the /introspect endpoint on the @@ -2475,43 +2705,43 @@ | | | | E: |<---------+ Header: 2.05 Content | | 2.05 | Content-Type: "application/cbor" | | | Payload: | | | | | |<--------+ Header: 2.01 Created | 2.01 | | | - Figure 23: Token Introspection for C offline + Figure 25: Token Introspection for C offline The information contained in the Request-Payload and the Response- - Payload is shown in Figure 24. + Payload is shown in Figure 26. Request-Payload: { "token" : b64'SlAV32hkKG...', "client_id" : "FrontDoor", "client_secret" : "ytrewq" } Response-Payload: { "active" : true, "aud" : "lockOfDoor4711", "scope" : "open, close", "iat" : 1311280970, "cnf" : { "kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' } } - Figure 24: Request and Response Payload for Introspection + Figure 26: Request and Response Payload for Introspection The client uses the symmetric PoP key to establish a DTLS PreSharedKey secure connection to the RS. The CoAP request PUT is sent to the uri-path /state on RS changing state of the door to locked. F: The RS responds with a appropriate over the secure DTLS channel. Resource Client Server @@ -2520,60 +2750,85 @@ | | using Pre Shared Key | | +-------->| Header: PUT (Code=0.03) | PUT | Uri-Path: "state" | | Payload: | | F: |<--------+ Header: 2.04 Changed | 2.04 | Payload: | | - Figure 25: Resource request and response protected by OSCOAP + Figure 27: Resource request and response protected by OSCOAP -Appendix E. Document Updates +Appendix F. Document Updates -E.1. Version -02 to -03 +F.1. Version -04 to -05 + + o Added RFC 2119 language to the specification of the required + behavior of profile specifications. + o Added section 6.1 on the relation to the OAuth2 grant types. + o Added CBOR abbreviations for error and the error codes defined in + OAuth2. + o Added clarification about token expiration and long-running + requests in section 8.2. + o Added security considerations about tokens with symmetric pop keys + valid for more than one RS. + o Added privacy considerations section. + o Added IANA registry mapping the confirmation types from RFC 7800 + to equivalent COSE types. + o Added appendix D, describing assumptions about what the AS knows + about the client and the RS. + +F.2. Version -03 to -04 + + o Added a description of the terms "framework" and "profiles" as + used in this document. + o Clarified protection of access tokens in section 3.1. + o Clarified uses of the 'cnf' parameter in section 6.4.5. + + o Clarified intended use of Client Token in section 7.4. + +F.3. Version -02 to -03 o Removed references to draft-ietf-oauth-pop-key-distribution since the status of this draft is unclear. o Copied and adapted security considerations from draft-ietf-oauth- pop-key-distribution. o Renamed "client information" to "RS information" since it is information about the RS. o Clarified the requirements on profiles of this framework. o Clarified the token endpoint protocol and removed negotiation of 'profile' and 'alg' (section 6). o Renumbered the abbreviations for claims and parameters to get a consistent numbering across different endpoints. o Clarified the introspection endpoint. o Renamed token, introspection and authz-info to 'endpoint' instead of 'resource' to mirror the OAuth 2.0 terminology. o Updated the examples in the appendices. -E.2. Version -01 to -02 +F.4. Version -01 to -02 o Restructured to remove communication security parts. These shall now be defined in profiles. - o Restructured section 5 to create new sections on the OAuth endpoints /token, /introspect and /authz-info. o Pulled in material from draft-ietf-oauth-pop-key-distribution in order to define proof-of-possession key distribution. o Introduced the 'cnf' parameter as defined in RFC7800 to reference - or transport keys used for proof of posession. + or transport keys used for proof of possession. o Introduced the 'client-token' to transport client information from the AS to the client via the RS in conjunction with introspection. o Expanded the IANA section to define parameters for token request, introspection and CWT claims. o Moved deployment scenarios to the appendix as examples. -E.3. Version -00 to -01 +F.5. Version -00 to -01 o Changed 5.1. from "Communication Security Protocol" to "Client Information". o Major rewrite of 5.1 to clarify the information exchanged between C and AS in the PoP token request profile for IoT. * Allow the client to indicate preferences for the communication security protocol. * Defined the term "Client Information" for the additional information returned to the client in addition to the access