--- 1/draft-ietf-ace-oauth-authz-06.txt 2017-08-08 09:13:13.081087939 -0700 +++ 2/draft-ietf-ace-oauth-authz-07.txt 2017-08-08 09:13:13.197090706 -0700 @@ -1,25 +1,25 @@ ACE Working Group L. Seitz Internet-Draft RISE SICS Intended status: Standards Track G. Selander -Expires: September 14, 2017 Ericsson +Expires: February 9, 2018 Ericsson E. Wahlstroem (no affiliation) S. Erdtman Spotify AB H. Tschofenig ARM Ltd. - March 13, 2017 + August 8, 2017 Authentication and Authorization for Constrained Environments (ACE) - draft-ietf-ace-oauth-authz-06 + draft-ietf-ace-oauth-authz-07 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,21 +32,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on September 14, 2017. + This Internet-Draft will expire on February 9, 2018. Copyright Notice 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 @@ -61,82 +61,83 @@ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 9 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.1. Authorization Grants . . . . . . . . . . . . . . . . . . 14 5.2. Client Credentials . . . . . . . . . . . . . . . . . . . 15 5.3. AS Authentication . . . . . . . . . . . . . . . . . . . . 15 - 5.4. The 'Authorize' Endpoint . . . . . . . . . . . . . . . . 15 + 5.4. The 'Authorize' Endpoint . . . . . . . . . . . . . . . . 16 5.5. The 'Token' Endpoint . . . . . . . . . . . . . . . . . . 16 5.5.1. Client-to-AS Request . . . . . . . . . . . . . . . . 16 5.5.2. AS-to-Client Response . . . . . . . . . . . . . . . . 19 5.5.3. Error Response . . . . . . . . . . . . . . . . . . . 21 - 5.5.4. Request and Response Parameters . . . . . . . . . . . 21 - 5.5.4.1. Audience . . . . . . . . . . . . . . . . . . . . 21 + 5.5.4. Request and Response Parameters . . . . . . . . . . . 22 + 5.5.4.1. Audience . . . . . . . . . . . . . . . . . . . . 22 5.5.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 22 - 5.5.4.3. Token Type . . . . . . . . . . . . . . . . . . . 22 - 5.5.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 22 + 5.5.4.3. Token Type . . . . . . . . . . . . . . . . . . . 23 + 5.5.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 23 5.5.4.5. Confirmation . . . . . . . . . . . . . . . . . . 23 - 5.5.5. Mapping parameters to CBOR . . . . . . . . . . . . . 25 - 5.6. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 25 - 5.6.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 26 - 5.6.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 26 + 5.5.5. Mapping parameters to CBOR . . . . . . . . . . . . . 26 + 5.6. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 26 + 5.6.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 27 + 5.6.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 27 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 28 - 5.6.4. Client Token . . . . . . . . . . . . . . . . . . . . 28 - 5.6.5. Mapping Introspection parameters to CBOR . . . . . . 30 - 5.7. The Access Token . . . . . . . . . . . . . . . . . . . . 30 - 5.7.1. The 'Authorization Information' Endpoint . . . . . . 31 - 5.7.2. Token Expiration . . . . . . . . . . . . . . . . . . 31 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 32 - 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 34 - 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 - 8.1. OAuth Introspection Response Parameter Registration . . . 34 - 8.2. OAuth Parameter Registration . . . . . . . . . . . . . . 35 - 8.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 35 + 5.6.4. Client Token . . . . . . . . . . . . . . . . . . . . 29 + 5.6.5. Mapping Introspection parameters to CBOR . . . . . . 31 + 5.7. The Access Token . . . . . . . . . . . . . . . . . . . . 31 + 5.7.1. The 'Authorization Information' Endpoint . . . . . . 32 + 5.7.2. Token Expiration . . . . . . . . . . . . . . . . . . 32 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 33 + 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 35 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 + 8.1. OAuth Introspection Response Parameter Registration . . . 35 + 8.2. OAuth Parameter Registration . . . . . . . . . . . . . . 36 + 8.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 36 8.4. Token Type Mappings . . . . . . . . . . . . . . . . . . . 36 - 8.4.1. Registration Template . . . . . . . . . . . . . . . . 36 - 8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 36 - 8.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 36 - 8.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 37 - 8.6.1. Registration Template . . . . . . . . . . . . . . . . 37 - 8.7. OAuth Parameter Mappings Registry . . . . . . . . . . . . 37 - 8.7.1. Registration Template . . . . . . . . . . . . . . . . 37 - 8.7.2. Initial Registry Contents . . . . . . . . . . . . . . 38 - 8.8. Introspection Endpoint CBOR Mappings Registry . . . . . . 40 - 8.8.1. Registration Template . . . . . . . . . . . . . . . . 40 - 8.8.2. Initial Registry Contents . . . . . . . . . . . . . . 40 - 8.9. CoAP Option Number Registration . . . . . . . . . . . . . 42 - 8.10. CWT Confirmation Methods Registry . . . . . . . . . . . . 43 - 8.10.1. Registration Template . . . . . . . . . . . . . . . 43 - 8.10.2. Initial Registry Contents . . . . . . . . . . . . . 44 - 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 + 8.4.1. Registration Template . . . . . . . . . . . . . . . . 37 + 8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 37 + 8.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 37 + 8.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 38 + 8.6.1. Registration Template . . . . . . . . . . . . . . . . 38 + 8.7. OAuth Parameter Mappings Registry . . . . . . . . . . . . 38 + 8.7.1. Registration Template . . . . . . . . . . . . . . . . 38 + 8.7.2. Initial Registry Contents . . . . . . . . . . . . . . 39 + 8.8. Introspection Endpoint CBOR Mappings Registry . . . . . . 41 + 8.8.1. Registration Template . . . . . . . . . . . . . . . . 41 + 8.8.2. Initial Registry Contents . . . . . . . . . . . . . . 41 + 8.9. CoAP Option Number Registration . . . . . . . . . . . . . 43 + 8.10. CWT Confirmation Methods Registry . . . . . . . . . . . . 44 + 8.10.1. Registration Template . . . . . . . . . . . . . . . 44 + 8.10.2. Initial Registry Contents . . . . . . . . . . . . . 45 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 45 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 10.1. Normative References . . . . . . . . . . . . . . . . . . 45 - 10.2. Informative References . . . . . . . . . . . . . . . . . 45 - Appendix A. Design Justification . . . . . . . . . . . . . . . . 47 - Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 49 - Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 51 - Appendix D. Assumptions on AS knowledge about C and RS . . . . . 52 - Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 52 + 10.2. Informative References . . . . . . . . . . . . . . . . . 46 + Appendix A. Design Justification . . . . . . . . . . . . . . . . 48 + Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 50 + Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 52 + Appendix D. Assumptions on AS knowledge about C and RS . . . . . 53 + Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 53 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 53 - E.2. Introspection Aided Token Validation . . . . . . . . . . 56 - Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 60 - F.1. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 60 - F.2. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 60 - F.3. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 61 - F.4. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 61 - F.5. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 61 - F.6. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 62 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 62 + E.2. Introspection Aided Token Validation . . . . . . . . . . 57 + Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 61 + F.1. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 61 + F.2. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 61 + F.3. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 61 + F.4. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 62 + F.5. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 62 + F.6. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 62 + F.7. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 63 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 63 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. @@ -163,21 +164,23 @@ OAuth 2.0 [RFC6749], thereby extending authorization to Internet of Things devices. This specification contains the necessary building blocks for adjusting OAuth 2.0 to IoT environments. More detailed, interoperable specifications can be found in profiles. 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. + with a wider range of low end devices. Requirements on profiles are + described at contextually appropriate places througout this memo, and + also summarized in Appendix C. 2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "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 @@ -227,30 +230,29 @@ underlying protocols to be supported in the future, such as HTTP/2, MQTT and QUIC. A third building block is CBOR [RFC7049] for encodings where JSON [RFC7159] is not sufficiently compact. CBOR is a binary encoding designed for small code and message size, which may be used for encoding of self contained tokens, and also for encoding CoAP POST parameters and CoAP responses. 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 5.6.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.ietf-core-object-security]. + format COSE [RFC8152], 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 5.6.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.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 @@ -324,45 +326,43 @@ Symmetric PoP key: The AS generates a random symmetric PoP key. The key is either stored to be returned on introspection calls or encrypted and included in the access token. The PoP key is also encrypted for the client and sent together with the access token to the client. Asymmetric PoP key: An asymmetric key pair is generated on the client and the public key is sent to the AS (if it does not already have knowledge of the client's public key). - Information about the public key, which is the PoP key in this case, is either stored to be returned on introspection calls or included inside the access token and sent back to the requesting client. The RS can identify the client's public key from the information in the token, which allows the client to use the corresponding private key for the proof of possession. The access token is either a simple reference, or a structured information object (e.g. CWT [I-D.ietf-ace-cbor-web-token]), - protected by a cryptographic wrapper (e.g. COSE - [I-D.ietf-cose-msg]). The choice of PoP key does not necessarily - imply a specific credential type for the integrity protection of - the token. + protected by a cryptographic wrapper (e.g. COSE [RFC8152]). The + choice of PoP key does not necessarily imply a specific credential + type for the integrity protection of the token. Scopes and Permissions: In OAuth 2.0, the client specifies the type of permissions it is seeking to obtain (via the scope parameter) in the access token request. In turn, the AS may use the scope response parameter to inform the client of the scope of the access token issued. As the client could be a constrained device as well, this specification uses CBOR encoded messages for CoAP, defined in Section 5, to - request scopes and to be informed what scopes the access token was - actually authorized for by the AS. + request scopes and to be informed what scopes the access token + actually authorizes. The values of the scope parameter are expressed as a list of space- delimited, case-sensitive strings, with a semantic that is well-known to the AS and the RS. More details about the concept of scopes is found under Section 3.3 in [RFC6749]. Claims: Information carried in the access token or returned from introspection, called claims, is in the form of type-value pairs. @@ -406,21 +406,21 @@ does not increase the size limits of CoAP options, therefore data encoded in options has to be kept small. Transport layer security for CoAP can be provided by DTLS 1.2 [RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy operations 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]. + COSE [RFC8152]. 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 @@ -433,22 +433,22 @@ token locally without the need to contact an AS. These interactions are shown in Figure 1. An overview of various OAuth concepts is provided in Section 3.1. The OAuth 2.0 framework defines a number of "protocol flows" via grant types, which have been extended further with extensions to OAuth 2.0 (such as RFC 7521 [RFC7521] and [I-D.ietf-oauth-device-flow]). What grant types works best depends on the usage scenario and RFC 7744 [RFC7744] describes many different IoT use cases but there are two preferred grant types, namely the - Authorization Code Grant (described in Section 4.1 of RFC 7521) and - the Client Credentials Grant (described in Section 4.4 of RFC 7521). + Authorization Code Grant (described in Section 4.1 of [RFC7521]) and + the Client Credentials Grant (described in Section 4.4 of [RFC7521]). The Authorization Code Grant is a good fit for use with apps running on smart phones and tablets that request access to IoT devices, a common scenario in the smart home environment, where users need to go through an authentication and authorization phase (at least during the initial setup phase). The native apps guidelines described in [I-D.ietf-oauth-native-apps] are applicable to this use case. The Client Credential Grant is a good fit for use with IoT devices where the OAuth client itself is constrained. In such a case the resource owner or another person on his or her behalf have arranged with the authorization server out-of-band, which is often accomplished using a @@ -662,28 +663,28 @@ To request an access token, the client obtains authorization from the resource owner or uses its client credentials as grant. The authorization is expressed in the form of an authorization grant. The OAuth framework defines four grant types. The grant types can be split up into two groups, those granted on behalf of the resource owner (password, authorization code, implicit) and those for the client (client credentials). - The grant type selected depending based on the use case. In cases - where the client will act on behalf of the resource owner, - authorization code grant is recommended. If the client should to act - on be half of the user but does not have any display or very limited - interaction possibilities it is recommended to use the device code - grant defined in [I-D.ietf-oauth-device-flow]. In cases where the - client will not act on be half of the resource owner, client - credentials grant is recommended. + The grant type is selected depending on the use case. In cases where + the client acts on behalf of the resource owner, authorization code + grant is recommended. If the client acts on behalf of the resource + owner, but does not have any display or very limited interaction + possibilities it is recommended to use the device code grant defined + in [I-D.ietf-oauth-device-flow]. In cases where the client does not + act on behalf of the resource owner, client credentials grant is + recommended. For details on the different grant types see the OAuth 2.0 framework. The OAuth 2.0 framework provides an extension mechanism for defining additional grant types so profiles of this framework MAY define additional grant types if needed. 5.2. Client Credentials Authentication of the client is mandatory independent of the grant type when requesting the access token from the token endpoint. In @@ -704,32 +705,26 @@ client connects to. In classic OAuth the AS is authenticated with a TLS server certificate. Profiles of this framework SHOULD specify how clients authenticate the AS and how communication security is implemented, otherwise server side TLS certificates as defined by OAuth 2.0 is required. 5.4. The 'Authorize' Endpoint The authorization endpoint is used to interact with the resource - owner and obtain an authorization grant. It is used for - authorization code and implicit grant, flows that requires online - user consent. In the most common implementation a users-agent is - used and redirected from the client to the AS. The AS shows a - consent dialog and directs back to the client, with the approved - grant or an error message. - - The grant types defined in OAuth 2.0, that use the authorization - endpoint, require the use of a user agent (i.e. a browser). This - endpoint is therefore out of scope for this specification. - Implementations should use the definition and recommendations of - [RFC6749] and [RFC6819]. + owner and obtain an authorization grant in certain grant flows. + Since it requires the use of a user agent (i.e. browser), it is not + expected that these types of grant flow will be used by constrained + clients. This endpoint is therefore out of scope for this + specification. Implementations should use the definition and + recommendations of [RFC6749] and [RFC6819]. If clients involved cannot support HTTP and TLS profiles MAY define mappings for the authorization endpoint. 5.5. 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. @@ -760,22 +755,22 @@ assumed that the client and the AS have a pre-established understanding of the audience that an access token should address. 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 + possession. It is RECOMMENDED that an AS reject a request + containing a symmetric key value in the 'cnf' field. See Section 5.5.4.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". The content is displayed in CBOR diagnostic @@ -790,44 +785,51 @@ "grant_type" : "client_credentials", "aud" : "tempSensor4711", } Figure 2: Example request for an access token bound to a symmetric key. Figure 3 shows a request for a token with an asymmetric proof-of- possession key. Note that in this example we assume an object security-based profile, therefore the Content-Type is "application/ - cose+cbor". + cose". Header: POST (Code=0.02) Uri-Host: "server.example.com" Uri-Path: "token" - Content-Type: "application/cose+cbor" + Content-Type: "application/cose" Payload: + "COSE_Encrypted" : { + 16( + [ h'a1010a', # protected header: {"alg" : "AES-CCM-16-64-128"} + {5 : b64'ifUvZaHFgJM7UmGnjA'}, # unprotected header, IV + b64'WXThuZo6TMCaZZqi6ef/8WHTjOdGk8kNzaIhIQ' # ciphertext + ] + ) + } + + Decrypted 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' } } } - Figure 3: Example request for an access token bound to an asymmetric - key. + Figure 3: Example token request bound to an asymmetric key. Figure 4 shows a request for a token where a previously communicated proof-of-possession key is only referenced. Note that we assume a DTLS-based communication security profile for this example, therefore the Content-Type is "application/cbor". Also note that the client performs a password based authentication in this example by submitting its client_secret (see section 2.3.1. of [RFC6749]). Header: POST (Code=0.02) Uri-Host: "server.example.com" @@ -904,23 +906,20 @@ | 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 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 ... @@ -961,24 +960,32 @@ /------------------------+----------+--------------\ | 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 | + | unsupported_pop_key | 6 | 0 | \------------------------+----------+--------------/ Figure 7: CBOR abbreviations for common error codes + In addition to the error responses defined in OAuth 2.0, the + follwoing behaviour MUST be implemented by the AS: If the client + submits an asymmetric key in the token request that the RS cannot + process, the AS MUST reject that request with the CoAP response code + 4.00 (Bad Request) with the error code "unsupported_pop_key" defined + in figure Figure 7. + 5.5.4. 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. 5.5.4.1. Audience This parameter specifies for which audience the client is requesting @@ -1355,21 +1362,22 @@ OPTIONAL. Contains information about the key that the RS uses to authenticate towards the client. If the key is symmetric then this claim MUST NOT be part of the Client Token, since this is the same key as the one specified through the 'cnf' claim. This claim uses the same encoding as the 'cnf' parameter. See Section 5.5.4.4. The AS encrypts this token using a key shared between the AS and the client, so that only the client can decrypt it and access its payload. How this key is established is out of scope of this - framework. + framework, however it can be established at the same time at which + the client's long term token is created. 5.6.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. /-----------------+----------+-----------------\ | Parameter name | CBOR Key | Major Type | |-----------------+----------+-----------------| | iss | 1 | 3 (text string) | @@ -1401,22 +1409,22 @@ 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 + The "cnf" claim follows the same rules as specified for JOSE web + token in RFC7800 [RFC7800], except that it is encoded in COSE in the same way as specified for the "cnf" parameter in Section 5.5.4.5. 5.7.1. The 'Authorization Information' Endpoint The access token, containing authorization information and information about the key used by the client, needs to be transported to the RS so that the RS can authenticate and authorize the client request. This section defines a method for transporting the access token to @@ -1485,99 +1493,92 @@ 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. 6. 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. + 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 of the access token by using a digital signature or a keyed message - digest. Consequently, the token integrity protection MUST be applied - to prevent the token from being modified, particularly since it - contains a reference to the symmetric key or the asymmetric key. If - the access token contains the symmetric key, this symmetric key MUST - be encrypted by the authorization server with a long-term key shared - with the resource server. + digest (MAC) or an AEAD algorithm. Consequently, the token integrity + protection MUST be applied to prevent the token from being modified, + particularly since it contains a reference to the symmetric key or + the asymmetric key. If the access token contains the symmetric key, + this symmetric key MUST be encrypted by the authorization server so + that only the resource server can decrypt it. Note that using an + AEAD algorithm is preferrable over using a MAC unless the message + needs to be publicly readable. 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 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 + since the client may obtion the proof-of-possession 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 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) 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 + access token. If clients have that capability, the AS can keep the + lifetime of the access token and the associated proof-of-possesion + key short and therefore use shorter proof-of-possession key sizes, + which translate to a performance benefit for the client and for the resource server. Shorter keys also lead to shorter messages (particularly with asymmetric keying material). When authorization servers bind symmetric keys to access tokens, they SHOULD scope these access tokens to a specific permissions. - Furthermore access tokens 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. - - 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. + Furthermore access tokens using symmetric keys for proof-of- + possession SHOULD NOT be targeted at an audience that contains more + than one RS, since otherwise any RS in the audience that receives + that access token can impersonate the client towards the other + members of the audience. 7. Privacy Considerations Implementers and users should be aware of the privacy implications of the different possible deployments of this framework. The AS is in a very central position 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. + access the client intends to perform. With other grants this can be + prevented by the Resource Owner. To do so the resource owner needs + to bind the grants it issues to anonymous, ephemeral credentials, + that do not allow the AS to link different grants and thus 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- @@ -2069,25 +2066,22 @@ 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. 10. References -10.1. Normative References - [I-D.ietf-cose-msg] - Schaad, J., "CBOR Object Signing and Encryption (COSE)", - draft-ietf-cose-msg-24 (work in progress), November 2016. +10.1. Normative References [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, . @@ -2098,47 +2092,51 @@ [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, . + [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", + RFC 8152, DOI 10.17487/RFC8152, July 2017, + . + 10.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-05 (work in progress), March 2017. [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-03 - (work in progress), March 2017. + "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-07 + (work in progress), July 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. + object-security-04 (work in progress), July 2017. [I-D.ietf-oauth-device-flow] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, "OAuth 2.0 Device Flow for Browserless and Input - Constrained Devices", draft-ietf-oauth-device-flow-04 - (work in progress), February 2017. + Constrained Devices", draft-ietf-oauth-device-flow-06 + (work in progress), May 2017. [I-D.ietf-oauth-native-apps] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", - draft-ietf-oauth-native-apps-09 (work in progress), March + draft-ietf-oauth-native-apps-12 (work in progress), June 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, . @@ -2801,74 +2798,79 @@ | | Payload: | | F: |<--------+ Header: 2.04 Changed | 2.04 | Payload: | | Figure 27: Resource request and response protected by OSCOAP Appendix F. Document Updates -F.1. Version -05 to -06 +F.1. Version -06 to -07 + + o Various clarifications added. + o Fixed erroneous author email. + +F.2. Version -05 to -06 o Moved sections that define the ACE framework into a subsection of the framework Section 5. o Split section on client credentials and grant into two separate sections, Section 5.1, and Section 5.2. o Added Section 5.3 on AS authentication. o Added Section 5.4 on the Authorize endpoint. -F.2. Version -04 to -05 +F.3. Version -04 to -05 o Added RFC 2119 language to the specification of the required behavior of profile specifications. o Added Section 5.2 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 5.7.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.3. Version -03 to -04 +F.4. 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.4. Version -02 to -03 +F.5. 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. -F.5. Version -01 to -02 +F.6. 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 possession. o Introduced the 'client-token' to transport client information from @@ -2868,23 +2870,24 @@ 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 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. -F.6. Version -00 to -01 +F.7. 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 @@ -2911,21 +2914,21 @@ RS. Authors' Addresses Ludwig Seitz RISE SICS Scheelevaegen 17 Lund 223 70 SWEDEN - Email: ludwig@ri.se + Email: ludwig.seitz@ri.se Goeran Selander Ericsson Faroegatan 6 Kista 164 80 SWEDEN Email: goran.selander@ericsson.com Erik Wahlstroem (no affiliation)