--- 1/draft-ietf-ace-oauth-authz-22.txt 2019-03-25 09:13:42.338543770 -0700 +++ 2/draft-ietf-ace-oauth-authz-23.txt 2019-03-25 09:13:42.490547516 -0700 @@ -1,26 +1,26 @@ ACE Working Group L. Seitz Internet-Draft RISE Intended status: Standards Track G. Selander -Expires: September 6, 2019 Ericsson +Expires: September 26, 2019 Ericsson E. Wahlstroem S. Erdtman Spotify AB H. Tschofenig Arm Ltd. - March 5, 2019 + March 25, 2019 Authentication and Authorization for Constrained Environments (ACE) using the OAuth 2.0 Framework (ACE-OAuth) - draft-ietf-ace-oauth-authz-22 + draft-ietf-ace-oauth-authz-23 Abstract This specification defines a framework for authentication and authorization in Internet of Things (IoT) environments called ACE- OAuth. The framework is based on a set of building blocks including OAuth 2.0 and CoAP, thus making a well-known and widely used authorization solution suitable for IoT devices. Existing specifications are used where possible, but where the constraints of IoT devices require it, extensions are added and profiles are @@ -34,21 +34,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://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 6, 2019. + This Internet-Draft will expire on September 26, 2019. Copyright Notice Copyright (c) 2019 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 (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -63,108 +63,110 @@ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 11 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.1. Discovering Authorization Servers . . . . . . . . . . . . 16 5.1.1. Unauthorized Resource Request Message . . . . . . . . 16 5.1.2. AS Request Creation Hints . . . . . . . . . . . . . . 17 - 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 19 + 5.1.2.1. The Client-Nonce Parameter . . . . . . . . . . . 19 + 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 20 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 20 - 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 20 - 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 20 - 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 20 - 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 21 + 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 21 + 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 21 + 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 21 + 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 22 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 24 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 26 5.6.4. Request and Response Parameters . . . . . . . . . . . 27 5.6.4.1. Grant Type . . . . . . . . . . . . . . . . . . . 27 5.6.4.2. Token Type . . . . . . . . . . . . . . . . . . . 28 5.6.4.3. Profile . . . . . . . . . . . . . . . . . . . . . 28 + 5.6.4.4. Client-Nonce . . . . . . . . . . . . . . . . . . 29 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 29 - 5.7. The Introspection Endpoint . . . . . . . . . . . . . . . 29 + 5.7. The Introspection Endpoint . . . . . . . . . . . . . . . 30 5.7.1. Introspection Request . . . . . . . . . . . . . . . . 30 5.7.2. Introspection Response . . . . . . . . . . . . . . . 31 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 32 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 33 - 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 33 + 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 34 5.8.1. The Authorization Information Endpoint . . . . . . . 34 5.8.1.1. Verifying an Access Token . . . . . . . . . . . . 35 5.8.1.2. Protecting the Authorization Information Endpoint . . . . . . . . . . . . . . . . . . . . 37 - 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 37 + 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 38 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 38 5.8.4. Key Expiration . . . . . . . . . . . . . . . . . . . 39 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 39 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 40 6.1. Unprotected AS Request Creation Hints . . . . . . . . . . 41 6.2. Minimal security requirements for communication . 41 - 6.3. Use of Nonces for Replay Protection . . . . . . . . . . . 42 - 6.4. Combining profiles . . . . . . . . . . . . . . . . . . . 42 - 6.5. Unprotected Information . . . . . . . . . . . . . . . . . 42 + 6.3. Use of Nonces for Token Freshness . . . . . . . . . . . . 42 + 6.4. Combining profiles . . . . . . . . . . . . . . . . . . . 43 + 6.5. Unprotected Information . . . . . . . . . . . . . . . . . 43 6.6. Identifying audiences . . . . . . . . . . . . . . . . . . 43 6.7. Denial of service against or with Introspection . . 44 - 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 44 + 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 45 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 8.1. ACE Authorization Server Request Creation Hints . . . . . 45 8.2. OAuth Extensions Error Registration . . . . . . . . . . . 46 8.3. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 46 8.4. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 47 8.5. OAuth Access Token Types . . . . . . . . . . . . . . . . 47 - 8.6. OAuth Access Token Type CBOR Mappings . . . . . . . . . . 47 + 8.6. OAuth Access Token Type CBOR Mappings . . . . . . . . . . 48 8.6.1. Initial Registry Contents . . . . . . . . . . . . . . 48 8.7. ACE Profile Registry . . . . . . . . . . . . . . . . . . 48 8.8. OAuth Parameter Registration . . . . . . . . . . . . . . 49 8.9. OAuth Parameters CBOR Mappings Registry . . . . . . . . . 49 - 8.10. OAuth Introspection Response Parameter Registration . . . 49 + 8.10. OAuth Introspection Response Parameter Registration . . . 50 8.11. OAuth Token Introspection Response CBOR Mappings Registry 50 8.12. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 50 8.13. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 51 - 8.14. Media Type Registrations . . . . . . . . . . . . . . . . 51 - 8.15. CoAP Content-Format Registry . . . . . . . . . . . . . . 52 + 8.14. Media Type Registrations . . . . . . . . . . . . . . . . 52 + 8.15. CoAP Content-Format Registry . . . . . . . . . . . . . . 53 8.16. Expert Review Instructions . . . . . . . . . . . . . . . 53 - 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 54 - 10.2. Informative References . . . . . . . . . . . . . . . . . 56 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 55 + 10.2. Informative References . . . . . . . . . . . . . . . . . 57 Appendix A. Design Justification . . . . . . . . . . . . . . . . 59 - Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 62 - Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 64 - Appendix D. Assumptions on AS knowledge about C and RS . . . . . 65 - Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 65 + Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 63 + Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 65 + Appendix D. Assumptions on AS knowledge about C and RS . . . . . 66 + Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 66 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 66 - E.2. Introspection Aided Token Validation . . . . . . . . . . 70 - Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 74 - F.1. Version -21 to 22 . . . . . . . . . . . . . . . . . . . . 74 - F.2. Version -20 to 21 . . . . . . . . . . . . . . . . . . . . 74 - F.3. Version -19 to 20 . . . . . . . . . . . . . . . . . . . . 74 - F.4. Version -18 to -19 . . . . . . . . . . . . . . . . . . . 75 - F.5. Version -17 to -18 . . . . . . . . . . . . . . . . . . . 75 - F.6. Version -16 to -17 . . . . . . . . . . . . . . . . . . . 75 - F.7. Version -15 to -16 . . . . . . . . . . . . . . . . . . . 76 - F.8. Version -14 to -15 . . . . . . . . . . . . . . . . . . . 76 - F.9. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 76 - F.10. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 76 - F.11. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 76 - F.12. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 77 - F.13. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 77 - F.14. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 77 - F.15. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 77 - F.16. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 78 - F.17. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 78 - F.18. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 78 - F.19. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 78 - F.20. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 78 - F.21. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 79 - F.22. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 79 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 80 + E.2. Introspection Aided Token Validation . . . . . . . . . . 71 + Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 75 + F.1. Version -21 to 22 . . . . . . . . . . . . . . . . . . . . 75 + F.2. Version -20 to 21 . . . . . . . . . . . . . . . . . . . . 75 + F.3. Version -19 to 20 . . . . . . . . . . . . . . . . . . . . 75 + F.4. Version -18 to -19 . . . . . . . . . . . . . . . . . . . 76 + F.5. Version -17 to -18 . . . . . . . . . . . . . . . . . . . 76 + F.6. Version -16 to -17 . . . . . . . . . . . . . . . . . . . 76 + F.7. Version -15 to -16 . . . . . . . . . . . . . . . . . . . 77 + F.8. Version -14 to -15 . . . . . . . . . . . . . . . . . . . 77 + F.9. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 77 + F.10. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 77 + F.11. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 77 + F.12. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 78 + F.13. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 78 + F.14. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 78 + F.15. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 78 + F.16. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 79 + F.17. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 79 + F.18. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 79 + F.19. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 79 + F.20. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 79 + F.21. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 80 + F.22. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 80 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 81 1. Introduction Authorization is the process for granting approval to an entity to access a resource [RFC4949]. The authorization task itself can best be described as granting access to a requesting client, for a resource hosted on a device, the resource server (RS). This exchange is mediated by one or multiple authorization servers (AS). Managing authorization for a large number of devices and users can be a complex task. @@ -687,21 +690,21 @@ endpoints at the AS is assumed to be via HTTP and may use Uri-query parameters. When profiles of this framework use CoAP instead, this framework REQUIRES the use of the following alternative instead of Uri-query parameters: The sender (client or RS) encodes the parameters of its request as a CBOR map and submits that map as the payload of the POST request. Profiles that use CBOR encoding of protocol message parameters MUST use the media format 'application/ ace+cbor', unless the protocol message is wrapped in another Content- Format (e.g. object security). If CoAP is used for communication, the Content-Format MUST be abbreviated with the ID: 19 (see - Section 8.15. + Section 8.15). The OAuth 2.0 AS uses a JSON structure in the payload of its responses both to client and RS. If CoAP is used, this framework REQUIRES the use of CBOR [RFC7049] instead of JSON. Depending on the profile, the CBOR payload MAY be enclosed in a non-CBOR cryptographic wrapper. 5.1. Discovering Authorization Servers In order to determine the AS in charge of a resource hosted at the @@ -756,113 +759,148 @@ o A "audience" element containing a suggested audience that the client should request towards the AS. o A "kid" element containing the key identifier of a key used in an existing security association between the client and the RS. The RS expects the client to request an access token bound to this key, in order to avoid having to re-establish the security association. - o A "nonce" element containing a nonce generated by RS to ensure - freshness in case that the RS and AS do not have synchronized - clocks. + o A "cnonce" element containing a client-nonce. See + Section 5.1.2.1. o A "scope" element containing the suggested scope that the client should request towards the AS. Figure 2 summarizes the parameters that may be part of the AS Request Creation Hints. /-----------+----------+---------------------\ | Name | CBOR Key | Value Type | |-----------+----------+---------------------| - | AS | 0 | text string | - | kid | 4 | byte string | - | nonce | 5 | byte string | + | AS | 1 | text string | + | kid | 2 | byte string | + | audience | 5 | text string | | scope | 9 | text or byte string | - | audience | 18 | text string | + | cnonce | 39 | byte string | \-----------+----------+---------------------/ Figure 2: AS Request Creation Hints Note that the schema part of the AS parameter may need to be adapted to the security protocol that is used between the client and the AS. Thus the example AS value "coap://as.example.com/token" might need to be transformed to "coaps://as.example.com/token". It is assumed that the client can determine the correct schema part on its own depending on the way it communicates with the AS. Figure 3 shows an example for an AS Request Creation Hints message payload using CBOR [RFC7049] diagnostic notation, using the parameter names instead of the CBOR keys for better human readability. 4.01 Unauthorized Content-Format: application/ace+cbor - {"AS" : "coaps://as.example.com/token", - "nonce" : h'e0a156bb3f', - "scope" : "rTempC", + Payload : + { + "AS" : "coaps://as.example.com/token", "audience" : "coaps://rs.example.com" + "scope" : "rTempC", + "cnonce" : h'e0a156bb3f' } Figure 3: AS Request Creation Hints payload example In this example, the attribute AS points the receiver of this message to the URI "coaps://as.example.com/token" to request access permissions. The originator of the AS Request Creation Hints payload (i.e., RS) uses a local clock that is loosely synchronized with a time scale common between RS and AS (e.g., wall clock time). - Therefore, it has included a parameter "nonce" for replay attack - prevention. + Therefore, it has included a parameter "nonce" (see Section 5.1.2.1). Figure 4 illustrates the mandatory to use binary encoding of the message payload shown in Figure 3. a4 # map(4) - 00 # unsigned(0) (=AS) + 01 # unsigned(1) (=AS) 78 1c # text(28) 636f6170733a2f2f61732e657861 6d706c652e636f6d2f746f6b656e # "coaps://as.example.com/token" - 05 # unsigned(5) (=nonce) - 45 # bytes(5) - e0a156bb3f # "\xE0\xA1V\xBB?" - 09 # unsigned(9) (=scope) - 66 # text(6) - 7254656d7043 # "rTempC" - 12 # unsigned(18) (=audience) + 05 # unsigned(5) (=audience) 76 # text(22) 636f6170733a2f2f72732e657861 6d706c652e636f6d # "coaps://rs.example.com" + 09 # unsigned(9) (=scope) + 66 # text(6) + 7254656d7043 # "rTempC" + 18 27 # unsigned(39) (=cnonce) + 45 # bytes(5) + e0a156bb3f # "\xE0\xA1V\xBB?" Figure 4: AS Request Creation Hints example encoded in CBOR +5.1.2.1. The Client-Nonce Parameter + + If the RS does not synchronize its clock with the AS, it could be + tricked into accepting old access tokens, that are either expired or + have been compromised. In order to ensure some level of token + freshness in that case, the RS can use the "cnonce" (client-nonce) + parameter. The processing requirements for this parameter are as + follows: + + o A RS sending a "cnonce" parameter in an an AS Request Creation + Hints message MUST store information to validate that a given + cnonce is fresh. How this is implemented internally is out of + scope for this specification. Expiration of client-nonces should + be based roughly on the time it would take a client to obtain an + access token after receiving the AS Request Creation Hints + message. + + o A client receiving a "cnonce" parameter in an AS Request Creation + Hints message MUST include this in the parameters when requesting + an access token at the AS, using the "cnonce" parameter from + Section 5.6.4.4. + + o If an AS grants an access token request containing a "cnonce" + parameter, it MUST include this value in the access token, using + the "cnonce" claim specified in Section 5.8. + + o A RS that is using the client-nonce mechanism and that receives an + access token MUST verify that this token contains a cnonce claim, + with a client-nonce value that is fresh according to the + information stored at the first step above. If the cnonce claim + is not present or if the cnonce claim value is not fresh, it MUST + discard the access token. If this was an interaction with the + authz-info endpoint the RS MUST also respond with an error message + using a response code equivalent to the CoAP code 4.01 + (Unauthorized). + 5.2. Authorization Grants 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 [RFC6749] 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). Further grant types have been added later, such as [RFC7521] defining an assertion-based authorization grant. 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. + acts autonomously the client credentials grant is recommended. For details on the different grant types, see section 1.3 of [RFC6749]. 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.3. Client Credentials Authentication of the client is mandatory independent of the grant type when requesting the access token from the token endpoint. In @@ -884,30 +922,28 @@ client connects to. In classic OAuth, the AS is authenticated with a TLS server certificate. Profiles of this framework MUST specify how clients authenticate the AS and how communication security is implemented, otherwise server side TLS certificates, as defined by OAuth 2.0, are required. 5.5. The Authorization Endpoint The authorization endpoint is used to interact with the resource - 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 section 3.1 of [RFC6749] and of section 4.2 of - [RFC6819]. - - If clients involved cannot support HTTP and TLS, profiles MAY define - mappings for the authorization endpoint. + owner and obtain an authorization grant in certain grant flows. The + primary use case for this framework is machine-to-machine + interactions, not involving the resource owner in the authorization + flow, therefore this endpoint is out of scope here. Future profiles + may define constrained adaptation mechanisms for this endpoint as + well. Non-constrained clients interacting with constrained resource + servers can use the specifications in section 3.1 of [RFC6749] and of + section 4.2 of [RFC6819]. 5.6. The Token Endpoint In standard 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 the client and RS to establish shared keys or to exchange their public keys. Furthermore, this framework defines encodings using CBOR, as a substitute for JSON. @@ -934,38 +970,44 @@ illustrative purposes. Note that implementations MUST use the integer abbreviations and the binary CBOR encoding, if the CBOR encoding is used. 5.6.1. Client-to-AS Request The client sends a POST request to the token endpoint at the AS. The profile MUST specify how the communication is protected. The content of the request consists of the parameters specified in the relevant subsection of section 4 of the OAuth 2.0 specification [RFC6749], - depending on the grant type. The parameter "grant_type" is an - exception, as it is OPTIONAL in the context of this framework (as - opposed to REQUIRED in RFC6749). If that parameter is missing, the - default value "client_credentials" is implied. + depending on the grant type with the following exceptions and + additions: - Furthermore the "audience" parameter from - [I-D.ietf-oauth-token-exchange] can be used to request an access - token bound to a specific audience. + o The parameter "grant_type" is OPTIONAL in the context of this + framework (as opposed to REQUIRED in RFC6749). If that parameter + is missing, the default value "client_credentials" is implied. - In addition to these parameters, a client MUST be able to use the - parameters from [I-D.ietf-ace-oauth-params] in an access token - request to the token endpoint and the AS MUST be able to process - these additional parameters. + o The "audience" parameter from [I-D.ietf-oauth-token-exchange] is + OPTIONAL to request an access token bound to a specific audience. - If CBOR is used then this parameter MUST be encoded as a CBOR map. - The "scope" parameter can be formatted as specified in section 3.3 of - [RFC6749] and additionally as a byte string, in order to allow - compact encoding of complex scopes. + o The "cnonce" parameter defined in Section 5.6.4.4 is REQUIRED if + the RS provided a client-nonce in the "AS Request Creation Hints" + message Section 5.1.2 + + o The "scope" parameter MAY be encoded as a byte string instead of + the string encoding specified in section 3.3 of [RFC6749], in + order allow compact encoding of complex scopes. + + o A client MUST be able to use the parameters from + [I-D.ietf-ace-oauth-params] in an access token request to the + token endpoint and the AS MUST be able to process these additional + parameters. + + If CBOR is used then these parameters MUST be encoded as a CBOR map. When HTTP is used as a transport then the client makes a request to the token endpoint by sending the parameters using the "application/ x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body, as defined in section 3.2 of [RFC6749]. The following examples illustrate different types of requests for proof-of-possession tokens. Figure 5 shows a request for a token with a symmetric proof-of- @@ -994,21 +1036,20 @@ note that this example uses the "req_cnf" parameter from [I-D.ietf-ace-oauth-params]. Header: POST (Code=0.02) Uri-Host: "as.example.com" Uri-Path: "token" OSCORE: 0x19, 0x05, 0x05, 0x44, 0x61, 0x6c, 0x65, 0x6b Content-Format: "application/oscore" Payload: 0x44025d1 ... (full payload omitted for brevity) ... 68b3825e - ) Decrypted payload: { "client_id" : "myclient", "req_cnf" : { "COSE_Key" : { "kty" : "EC", "kid" : h'11', "crv" : "P-256", "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', @@ -1057,30 +1098,29 @@ 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 response code equivalent to 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 5.6.3. 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 (see - Appendix D. This prior knowledge may, for example, be set by the use - of a dynamic client registration protocol exchange [RFC7591]. + 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 is the Access Information. When using CBOR payloads, the content MUST be encoded as CBOR map, containing parameters as specified in Section 5.1 of [RFC6749], with the following additions and changes: profile: - OPTIONAL. This indicates the profile that the client MUST use towards the RS. See Section 5.6.4.3 for the formatting of this parameter. If this parameter is absent, the AS assumes that the client implicitly knows which profile to use towards the RS. token_type: This parameter is OPTIONAL, as opposed to 'required' in [RFC6749]. 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 @@ -1244,56 +1284,65 @@ A profile MUST specify an identifier that MUST be used to uniquely identify itself in the "profile" parameter. The textual representation of the profile identifier is just intended for human readability and MUST NOT be used in parameters and claims. Profiles MAY define additional parameters for both the token request and the Access Information in the access token response in order to support negotiation or signaling of profile specific parameters. +5.6.4.4. Client-Nonce + + This parameter MUST be sent from the client to the AS, if it + previously received a "cnonce" parameter in the AS Request Creation + Hints Section 5.1.2. The parameter is encoded as a byte string and + copies the value from the cnonce parameter in the AS Request Creation + Hints. + 5.6.5. Mapping Parameters to CBOR If CBOR encoding is used, all OAuth parameters in access token requests and responses MUST be mapped to CBOR types as specified in Figure 12, using the given integer abbreviation for the map keys. Note that we have aligned the abbreviations corresponding to claims with the abbreviations defined in [RFC8392]. Note also that abbreviations from -24 to 23 have a 1 byte encoding size in CBOR. We have thus chosen to assign abbreviations in that range to parameters we expect to be used most frequently in constrained scenarios. /-------------------+----------+---------------------\ | Name | CBOR Key | Value Type | |-------------------+----------+---------------------| | access_token | 1 | byte string | + | expires_in | 2 | unsigned integer | + | audience | 5 | text string | | scope | 9 | text or byte string | - | audience | 18 | text string | | client_id | 24 | text string | | client_secret | 25 | byte string | | response_type | 26 | text string | | redirect_uri | 27 | text string | | state | 28 | text string | | code | 29 | byte string | | error | 30 | unsigned integer | | error_description | 31 | text string | | error_uri | 32 | text string | | grant_type | 33 | unsigned integer | | token_type | 34 | unsigned integer | - | expires_in | 35 | unsigned integer | - | username | 36 | text string | - | password | 37 | text string | - | refresh_token | 38 | byte string | - | profile | 39 | unsigned integer | + | username | 35 | text string | + | password | 36 | text string | + | refresh_token | 37 | byte string | + | profile | 38 | unsigned integer | + | cnonce | 39 | byte string | \-------------------+----------+---------------------/ Figure 12: CBOR mappings used in token requests 5.7. The Introspection Endpoint Token introspection [RFC7662] can be OPTIONALLY provided by the AS, and is then used by the RS and potentially the client to query the AS for metadata about a given token, e.g., validity or scope. Analogous to the protocol defined in [RFC7662] for HTTP and JSON, this section @@ -1371,29 +1420,35 @@ error response as described in Section 5.7.3. In a successful response, the AS encodes the response parameters in a map including with the same required and optional parameters as in Section 2.2 of [RFC7662] with the following addition: profile OPTIONAL. This indicates the profile that the RS MUST use with the client. See Section 5.6.4.3 for more details on the formatting of this parameter. + cnonce OPTIONAL. A client-nonce previously provided to the AS by + the RS via the client. See Section 5.6.4.4. + + exi OPTIONAL. The "expires-in" claim associated to this access + token. See Section 5.8.3. + Furthermore [I-D.ietf-ace-oauth-params] defines more parameters that the AS MUST be able to use when responding to a request to the introspection endpoint. For example, Figure 15 shows an AS response to the introspection request in Figure 13. Note that this example contains the "cnf" parameter defined in [I-D.ietf-ace-oauth-params]. - Header: Created Code=2.01) + Header: Created (Code=2.01) Content-Format: "application/ace+cbor" Payload: { "active" : true, "scope" : "read", "profile" : "coap_dtls", "cnf" : { "COSE_Key" : { "kty" : "Symmetric", "kid" : b64'39Gqlw', @@ -1454,29 +1509,31 @@ | aud | 3 | text string | | exp | 4 | integer or | | | | floating-point number | | nbf | 5 | integer or | | | | floating-point number | | iat | 6 | integer or | | | | floating-point number | | cti | 7 | byte string | | scope | 9 | text or byte string | | active | 10 | True or False | - | token | 12 | byte string | + | token | 11 | byte string | | client_id | 24 | text string | | error | 30 | unsigned integer | | error_description | 31 | text string | | error_uri | 32 | text string | | token_type_hint | 33 | text string | | token_type | 34 | text string | - | username | 36 | text string | - | profile | 39 | unsigned integer | + | username | 35 | text string | + | profile | 38 | unsigned integer | + | cnonce | 39 | byte string | + | exi | 40 | unsigned integer | \-------------------+----------+-------------------------/ Figure 16: CBOR Mappings to Token Introspection Parameters. 5.8. The Access Token This framework RECOMMENDS the use of CBOR web token (CWT) as specified in [RFC8392]. In order to facilitate offline processing of access tokens, this @@ -1490,20 +1546,25 @@ Section 3.3 of [RFC6749], but in addition implementers MAY use byte strings as scope values, to achieve compact encoding of large scope elements. The meaning of a specific scope value is application specific and expected to be known to the RS running that application. If the AS needs to convey a hint to the RS about which profile it should use to communicate with the client, the AS MAY include a "profile" claim in the access token, with the same syntax and semantics as defined in Section 5.6.4.3. + If the client submitted a client-nonce parameter in the access token + request Section 5.6.4.4, the AS MUST include the value of this + parameter in the "cnonce" claim specified here. The "cnonce" claim + uses binary encoding. + 5.8.1. The Authorization Information Endpoint The access token, containing authorization information and information about the key used by the client, needs to be transported to the RS so that the RS can authenticate and authorize the client request. This section defines a method for transporting the access token to the RS using a RESTful protocol such as CoAP. Profiles of this framework MAY define other methods for token transport. @@ -1654,20 +1715,25 @@ The POST method SHOULD NOT be allowed on children of the authz-info endpoint. The RS SHOULD implement rate limiting measures to mitigate attacks aiming to overload the processing capacity of the RS by repeatedly submitting tokens. For CoAP-based communication the RS could use the mechanisms from [RFC8516] to indicate that it is overloaded. 5.8.2. Client Requests to the RS + Before sending a request to a RS, the client MUST verify that the + keys used to protect this communication are still valid. See + Section 5.8.4 for details on how the client determines the validity + of the keys used. + If an RS receives a request from a client, and the target resource requires authorization, the RS MUST first verify that it has an access token that authorizes this request, and that the client has performed the proof-of-possession for that token. The response code MUST be 4.01 (Unauthorized) in case the client has not performed the proof-of-possession, or if RS has no valid access token for the client. If RS has an access token for the client but not for the resource that was requested, RS MUST reject the request with a 4.03 (Forbidden). If RS has an access token for the client @@ -1750,22 +1816,22 @@ o The client knows a default validity period for all tokens it is using. This information could be provisioned to the client when it is registered at the AS, or published by the AS in a way that the client can query. o The AS informs the client about the token validity using the "expires_in" parameter in the Access Information. o The client performs an introspection of the token. Although this - is not explicitly forbidden, how exactly this is done is not - currently specified for OAuth. + is not explicitly forbidden, how exactly a client does + introspection is not currently specified for OAuth. A client that is not able to obtain information about the expiration of a token MUST NOT use this token. 6. Security Considerations Security considerations applicable to authentication and authorization in RESTful environments provided in OAuth 2.0 [RFC6749] apply to this work. Furthermore [RFC6819] provides additional security considerations for OAuth which apply to IoT deployments as @@ -1881,28 +1947,27 @@ protection as well as a binding between requests and responses. This requires that the client learned either the RS's public key or received a symmetric proof-of-possession key bound to the access token from the AS. The RS must have learned either the client's public key or a shared symmetric key from the claims in the token or an introspection request. Since ACE does not provide profile negotiation between C and RS, the client MUST have learned what profile the RS supports (e.g. from the AS or pre-configured) and initiate the communication accordingly. -6.3. Use of Nonces for Replay Protection +6.3. Use of Nonces for Token Freshness - The RS may add a nonce to the AS Request Creation Hints message sent - as a response to an unauthorized request to ensure freshness of an - Access Token subsequently presented to RS. While a time-stamp of - some granularity would be sufficient to protect against replay - attacks, using randomized nonce is preferred to prevent disclosure of - information about RS's internal clock characteristics. + An RS that does not synchronize its clock with the AS may be tricked + into accepting old access tokens that are no longer valid or have + been compromised. In order to prevent this, an RS may use the nonce- + based mechanism defined in Section 5.1.2 to ensure freshness of an + Access Token subsequently presented to this RS. 6.4. Combining profiles There may be use cases were different profiles of this framework are combined. For example, an MQTT-TLS profile is used between the client and the RS in combination with a CoAP-DTLS profile for interactions between the client and the AS. Ideally, profiles should be designed in a way that the security of system should not depend on the specific security mechanisms used in individual protocol interactions. @@ -2286,50 +2350,66 @@ o Reference: Section 5.8 of [this document] o Claim Name: "exi" o Claim Description: "Expires in". Lifetime of the token in seconds from the time the RS first sees it. Used to implement a weaker from of token expiration for devices that cannot synchronize their internal clocks. o Change Controller: IESG o Reference: Section 5.8.3 of [this document] + o Claim Name: "cnonce" + o Claim Description: "client-nonce". A nonce previously provided to + the AS by the RS via the client. Used verify token freshness when + the RS cannot synchronize its clock with the AS. + o Change Controller: IESG + o Reference: Section 5.8 of [this document] + 8.13. CBOR Web Token Claims This specification registers the following new claims in the "CBOR Web Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. o Claim Name: "scope" o Claim Description: The scope of an access token as defined in [RFC6749]. o JWT Claim Name: scope o Claim Key: TBD (suggested: 9) o Claim Value Type(s): byte string or text string o Change Controller: IESG o Specification Document(s): Section 5.8 of [this document] o Claim Name: "profile" o Claim Description: The profile a token is supposed to be used with. o JWT Claim Name: profile - o Claim Key: TBD (suggested: 39) + o Claim Key: TBD (suggested: 38) o Claim Value Type(s): integer o Change Controller: IESG o Specification Document(s): Section 5.8 of [this document] o Claim Name: "exi" o Claim Description: The expiration time of a token measured from when it was received at the RS in seconds. o JWT Claim Name: exi - o Claim Key: TBD (suggested: 41) + o Claim Key: TBD (suggested: 40) o Claim Value Type(s): integer o Change Controller: IESG + o Specification Document(s): Section 5.8.3 of [this document] + + o Claim Name: "cnonce" + o Claim Description: The client-nonce sent to the AS by the RS via + the client. + o JWT Claim Name: cnonce + o Claim Key: TBD (suggested: 39) + o Claim Value Type(s): byte string + o Change Controller: IESG o Specification Document(s): Section 5.8 of [this document] 8.14. Media Type Registrations This specification registers the 'application/ace+cbor' media type for messages of the protocols defined in this document carrying parameters encoded in CBOR. This registration follows the procedures specified in [RFC6838]. Type name: application @@ -2440,22 +2520,26 @@ Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten Bormann for contributing their work on AS discovery from draft-gerdes-ace-dcaf- authorize (see Section 5.1). Thanks to Jim Schaad and Mike Jones for their comprehensive reviews. Thanks to Benjamin Kaduk for his input on various questions related to this work. + Thanks to Cigdem Sengul for some very useful review comments. + Ludwig Seitz and Goeran Selander worked on this document as part of - the CelticPlus project CyberWI, with funding from Vinnova. + the CelticPlus project CyberWI, with funding from Vinnova. Ludwig + Seitz was also received further funding for this work by Vinnova in + the context of the CelticNext project Critisec. 10. References 10.1. Normative References [I-D.ietf-ace-cwt-proof-of-possession] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- possession-06 (work in progress), February 2019. @@ -2556,28 +2640,27 @@ 10.2. Informative References [I-D.erdtman-ace-rpcc] Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared- Key as OAuth client credentials", draft-erdtman-ace- rpcc-02 (work in progress), October 2017. [I-D.ietf-core-object-security] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments - (OSCORE)", draft-ietf-core-object-security-15 (work in - progress), August 2018. + (OSCORE)", draft-ietf-core-object-security-16 (work in + progress), March 2019. [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-14 - (work in progress), January 2019. + "OAuth 2.0 Device Authorization Grant", draft-ietf-oauth- + device-flow-15 (work in progress), March 2019. [I-D.ietf-tls-dtls13] Rescorla, E., Tschofenig, H., and N. Modadugu, "The Datagram Transport Layer Security (DTLS) Protocol Version 1.3", draft-ietf-tls-dtls13-30 (work in progress), November 2018. [Margi10impact] Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr, M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold,