--- 1/draft-ietf-ace-oauth-authz-19.txt 2019-02-11 06:13:11.327365681 -0800 +++ 2/draft-ietf-ace-oauth-authz-20.txt 2019-02-11 06:13:11.475369251 -0800 @@ -1,165 +1,167 @@ ACE Working Group L. Seitz Internet-Draft RISE Intended status: Standards Track G. Selander -Expires: August 4, 2019 Ericsson +Expires: August 15, 2019 Ericsson E. Wahlstroem S. Erdtman Spotify AB H. Tschofenig Arm Ltd. - January 31, 2019 + February 11, 2019 Authentication and Authorization for Constrained Environments (ACE) using the OAuth 2.0 Framework (ACE-OAuth) - draft-ietf-ace-oauth-authz-19 + draft-ietf-ace-oauth-authz-20 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 defined. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. 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/. + 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 August 4, 2019. + This Internet-Draft will expire on August 15, 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 - (http://trustee.ietf.org/license-info) in effect on the date of + (https://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 . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 11 - 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.1. Discovering Authorization Servers . . . . . . . . . . . . 16 5.1.1. Unauthorized Resource Request Message . . . . . . . . 16 - 5.1.2. AS Request Creation Hints . . . . . . . . . . . . . . 16 - 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 18 + 5.1.2. AS Request Creation Hints . . . . . . . . . . . . . . 17 + 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 19 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 19 - 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 19 - 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 19 + 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 20 + 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 20 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 20 - 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 20 - 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 23 - 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 25 - 5.6.4. Request and Response Parameters . . . . . . . . . . . 26 - 5.6.4.1. Grant Type . . . . . . . . . . . . . . . . . . . 26 - 5.6.4.2. Token Type . . . . . . . . . . . . . . . . . . . 27 - 5.6.4.3. Profile . . . . . . . . . . . . . . . . . . . . . 27 - 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 28 - 5.7. The Introspection Endpoint . . . . . . . . . . . . . . . 28 - 5.7.1. Introspection Request . . . . . . . . . . . . . . . . 29 - 5.7.2. Introspection Response . . . . . . . . . . . . . . . 30 - 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 31 - 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 32 - 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 32 - 5.8.1. The Authorization Information Endpoint . . . . . . . 33 - 5.8.1.1. Verifying an Access Token . . . . . . . . . . . . 34 + 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 21 + 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.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 29 + 5.7. The Introspection Endpoint . . . . . . . . . . . . . . . 29 + 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.1. The Authorization Information Endpoint . . . . . . . 34 + 5.8.1.1. Verifying an Access Token . . . . . . . . . . . . 35 5.8.1.2. Protecting the Authorization Information - Endpoint . . . . . . . . . . . . . . . . . . . . 36 - 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 36 - 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 37 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 37 - 6.1. Unprotected AS Request Creation Hints . . . . . . . . . . 39 - 6.2. Minimal security requirements for communication . 39 - 6.3. Use of Nonces for Replay Protection . . . . . . . . . . . 40 - 6.4. Combining profiles . . . . . . . . . . . . . . . . . . . 40 - 6.5. Unprotected Information . . . . . . . . . . . . . . . . . 40 - 6.6. Denial of service against or with Introspection . . 41 - 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 41 - 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 - 8.1. ACE Authorization Server Request Creation Hints . . . . . 42 - 8.2. OAuth Extensions Error Registration . . . . . . . . . . . 43 - 8.3. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 43 - 8.4. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 44 - 8.5. OAuth Access Token Types . . . . . . . . . . . . . . . . 44 - 8.6. OAuth Access Token Type CBOR Mappings . . . . . . . . . . 44 - 8.6.1. Initial Registry Contents . . . . . . . . . . . . . . 45 - 8.7. ACE Profile Registry . . . . . . . . . . . . . . . . . . 45 - 8.8. OAuth Parameter Registration . . . . . . . . . . . . . . 46 - 8.9. OAuth Parameters CBOR Mappings Registry . . . . . . . . . 46 - 8.10. OAuth Introspection Response Parameter Registration . . . 47 - 8.11. OAuth Token Introspection Response CBOR Mappings Registry 47 - 8.12. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 48 - 8.13. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 48 - 8.14. Media Type Registrations . . . . . . . . . . . . . . . . 49 - 8.15. CoAP Content-Format Registry . . . . . . . . . . . . . . 50 - 8.16. Expert Review Instructions . . . . . . . . . . . . . . . 50 - 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 51 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 51 - 10.2. Informative References . . . . . . . . . . . . . . . . . 53 - Appendix A. Design Justification . . . . . . . . . . . . . . . . 56 - Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 59 - Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 62 - Appendix D. Assumptions on AS knowledge about C and RS . . . . . 62 - Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 63 - E.1. Local Token Validation . . . . . . . . . . . . . . . . . 63 - E.2. Introspection Aided Token Validation . . . . . . . . . . 67 - Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 71 - F.1. Version -18 to -19 . . . . . . . . . . . . . . . . . . . 71 - F.2. Version -17 to -18 . . . . . . . . . . . . . . . . . . . 71 - F.3. Version -16 to -17 . . . . . . . . . . . . . . . . . . . 72 - F.4. Version -15 to -16 . . . . . . . . . . . . . . . . . . . 72 - F.5. Version -14 to -15 . . . . . . . . . . . . . . . . . . . 72 - F.6. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 72 - F.7. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 73 - F.8. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 73 - F.9. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 73 - F.10. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 73 - F.11. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 73 - F.12. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 74 - F.13. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 74 - F.14. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 74 - F.15. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 74 - F.16. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 75 - F.17. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 75 - F.18. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 75 - F.19. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 76 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 76 + Endpoint . . . . . . . . . . . . . . . . . . . . 37 + 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 37 + 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 38 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 39 + 6.1. Unprotected AS Request Creation Hints . . . . . . . . . . 40 + 6.2. Minimal security requirements for communication . 40 + 6.3. Use of Nonces for Replay Protection . . . . . . . . . . . 41 + 6.4. Combining profiles . . . . . . . . . . . . . . . . . . . 41 + 6.5. Unprotected Information . . . . . . . . . . . . . . . . . 42 + 6.6. Identifying audiences . . . . . . . . . . . . . . . . . . 42 + 6.7. Denial of service against or with Introspection . . 43 + 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 43 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 + 8.1. ACE Authorization Server Request Creation Hints . . . . . 44 + 8.2. OAuth Extensions Error Registration . . . . . . . . . . . 45 + 8.3. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 45 + 8.4. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 46 + 8.5. OAuth Access Token Types . . . . . . . . . . . . . . . . 46 + 8.6. OAuth Access Token Type CBOR Mappings . . . . . . . . . . 47 + 8.6.1. Initial Registry Contents . . . . . . . . . . . . . . 47 + 8.7. ACE Profile Registry . . . . . . . . . . . . . . . . . . 47 + 8.8. OAuth Parameter Registration . . . . . . . . . . . . . . 48 + 8.9. OAuth Parameters CBOR Mappings Registry . . . . . . . . . 48 + 8.10. OAuth Introspection Response Parameter Registration . . . 49 + 8.11. OAuth Token Introspection Response CBOR Mappings Registry 49 + 8.12. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 50 + 8.13. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 50 + 8.14. Media Type Registrations . . . . . . . . . . . . . . . . 51 + 8.15. CoAP Content-Format Registry . . . . . . . . . . . . . . 52 + 8.16. Expert Review Instructions . . . . . . . . . . . . . . . 52 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 54 + 10.2. Informative References . . . . . . . . . . . . . . . . . 56 + Appendix A. Design Justification . . . . . . . . . . . . . . . . 58 + Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 62 + Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 64 + Appendix D. Assumptions on AS knowledge about C and RS . . . . . 64 + Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 65 + E.1. Local Token Validation . . . . . . . . . . . . . . . . . 65 + E.2. Introspection Aided Token Validation . . . . . . . . . . 69 + Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 73 + F.1. Verion -19 to 20 . . . . . . . . . . . . . . . . . . . . 73 + F.2. Version -18 to -19 . . . . . . . . . . . . . . . . . . . 73 + F.3. Version -17 to -18 . . . . . . . . . . . . . . . . . . . 74 + F.4. Version -16 to -17 . . . . . . . . . . . . . . . . . . . 74 + F.5. Version -15 to -16 . . . . . . . . . . . . . . . . . . . 74 + F.6. Version -14 to -15 . . . . . . . . . . . . . . . . . . . 74 + F.7. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 75 + F.8. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 75 + F.9. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 75 + F.10. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 75 + F.11. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 75 + F.12. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 75 + F.13. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 76 + F.14. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 76 + F.15. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 76 + F.16. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 77 + F.17. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 77 + F.18. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 77 + F.19. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 77 + F.20. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 78 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 79 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. @@ -739,30 +744,33 @@ The AS Request Creation Hints message is sent by RS as a response to an Unauthorized Resource Request message (see Section 5.1.1) to help the sender of the Unauthorized Resource Request message in acquiring a valid access token. The AS Request Creation Hints message is CBOR map, with a MANDATORY element "AS" specifying an absolute URI (see Section 4.3 of [RFC3986]) that identifies the AS in charge of RS. The message can also contain the following OPTIONAL parameters: - o A "req_aud" element containing a suggested audience that the + 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 "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 | @@ -759,43 +767,43 @@ 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 | - | req_aud | 3 | text string | | kid | 4 | byte string | | nonce | 5 | byte string | | scope | 9 | text or byte string | + | audience | 18 | text 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", - req_aud: "coaps://rs.example.com", + audience: "coaps://rs.example.com", nonce: h'e0a156bb3f', scope: "rTempC" } 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 @@ -919,53 +927,54 @@ 5.6.1. Client-to-AS Request The client sends a POST request to the token endpoint at the AS. The profile MUST specify how the communication is protected. The content of the request consists of the parameters specified in Section 4 of the OAuth 2.0 specification [RFC6749] with the exception of the "grant_type" parameter, which is OPTIONAL in the context of this framework (as opposed to REQUIRED in RFC6749). If that parameter is missing, the default value "client_credentials" is implied. + Furthermore the "audience" parameter from + [I-D.ietf-oauth-token-exchange] can be used to request an access + token bound to a specific audience. + In addition to these parameters, a client MUST be able to use the parameters from [I-D.ietf-ace-oauth-params] in an access token request to the token endpoint and the AS MUST be able to process these additional parameters. If CBOR is used then this parameter MUST be encoded as a CBOR map. The "scope" parameter can be formatted as specified in [RFC6749] and additionally as a byte string, in order to allow compact encoding of complex scopes. When HTTP is used as a transport then the client makes a request to the token endpoint by sending the parameters using the "application/ x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body, as defined in RFC 6749. The following examples illustrate different types of requests for proof-of-possession tokens. Figure 5 shows a request for a token with a symmetric proof-of- possession key. The content is displayed in CBOR diagnostic - notation, without abbreviations for better readability. Note that - this example uses the "req_aud" parameter from - [I-D.ietf-ace-oauth-params]. + notation, without abbreviations for better readability. Header: POST (Code=0.02) Uri-Host: "as.example.com" Uri-Path: "token" Content-Format: "application/ace+cbor" Payload: { - "grant_type" : "client_credentials", "client_id" : "myclient", - "req_aud" : "tempSensor4711" + "audience" : "tempSensor4711" } Figure 5: Example request for an access token bound to a symmetric key. Figure 6 shows a request for a token with an asymmetric proof-of- possession key. Note that in this example OSCORE [I-D.ietf-core-object-security] is used to provide object-security, therefore the Content-Format is "application/oscore" wrapping the "application/ace+cbor" type content. Also note that in this example @@ -977,52 +986,50 @@ 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: { - "grant_type" : "client_credentials", "client_id" : "myclient", "req_cnf" : { "COSE_Key" : { "kty" : "EC", "kid" : h'11', "crv" : "P-256", "x" : b64'usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8', "y" : b64'IBOL+C3BttVivg+lSreASjpkttcsz+1rb7btKLv8EX4' } } } Figure 6: Example token request bound to an asymmetric key. Figure 7 shows a request for a token where a previously communicated proof-of-possession key is only referenced. Note that the client performs a password based authentication in this example by submitting its client_secret (see Section 2.3.1 of [RFC6749]). Note - that this example uses the "req_aud" and "req_cnf" parameters from + that this example uses the "req_cnf" parameter from [I-D.ietf-ace-oauth-params]. Header: POST (Code=0.02) Uri-Host: "as.example.com" Uri-Path: "token" Content-Format: "application/ace+cbor" Payload: { - "grant_type" : "client_credentials", "client_id" : "myclient", "client_secret" : "mysecret234", - "req_aud" : "valve424", + "audience" : "valve424", "scope" : "read", "req_cnf" : { "kid" : b64'6kg0dXJM13U' } } Figure 7: Example request for an access token bound to a key reference. Refresh tokens are typically not stored as securely as proof-of- @@ -1238,20 +1251,21 @@ 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 | | 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 | @@ -1848,21 +1874,58 @@ RECOMMENDS to use encrypted CWTs or opaque references and need to be subjected to introspection by the RS. If the initial unauthorized resource request message (see Section 5.1.1) is used, the client MUST make sure that it is not sending sensitive content in this request. While GET and DELETE requests only reveal the target URI of the resource, while POST and PUT requests would reveal the whole payload of the intended operation. -6.6. Denial of service against or with Introspection +6.6. Identifying audiences + + The audience claim as defined in [RFC7519] and the equivalent + "audience" parameter from [I-D.ietf-oauth-token-exchange] are + intentionally vague on how to match the audience value to a specific + RS. This is intended to allow application specific semantics to be + used. This section attempts to give some general guidance for the + use of audiences in constrained environments. + + URLs are not a good way of identifying mobile devices that can switch + networks and thus be associated with new URLs. If the audience + represents a single RS, and asymmetric keys are used, the RS can be + uniquely identified by a hash of its public key. If this approach is + used this framework RECOMMENDS to apply the procedure from section 3 + of [RFC6920]. + + If the audience addresses a group of resource servers, the mapping of + group identifier to individual RS has to be provisioned to each RS + before the group-audience is usable. Managing dynamic groups could + be an issue, if the RS is not always reachable when the group + memberships change. Furthermore issuing access tokens bound to + symmetric proof-of-possession keys that apply to a group-audience is + problematic, as an RS that is in possession of the access token can + impersonate the client towards the other RSs that are part of the + group. It is therefore NOT RECOMMENDED to issue access tokens bound + to a group audience and symmetric proof-of possession keys. + + Even the client must be able to determine the correct values to put + into the "audience" parameter, in order to obtain a token for the + intended RS. Errors in this process can lead to the client + inadvertantly communicating with the wrong RS. The correct values + for "audience" can either be provisioned to the client as part of its + configuration, or provided by the RS as part of the "AS Request + Creation Hints" Section 5.1.2 or dynamically looked up by the client + in some directory. In the latter case the integrity and correctness + of the directory data must be assured. + +6.7. Denial of service against or with Introspection The optional introspection mechanism provided by OAuth and supported in the ACE framework allows for two types of attacks that need to be considered by implementers. First an attacker could perform a denial of service attack against the introspection endpoint at the AS in order to prevent validation of access tokens. To mitigate this attack, an RS that is configured to use introspection MUST NOT allow access based on a token for which it couldn't reach the introspection endpoint. @@ -2361,78 +2425,88 @@ [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-05 (work in progress), November 2018. [I-D.ietf-ace-oauth-params] Seitz, L., "Additional OAuth Parameters for Authorization in Constrained Environments (ACE)", draft-ietf-ace-oauth- - params-03 (work in progress), January 2019. + params-02 (work in progress), January 2019. + + [I-D.ietf-oauth-token-exchange] + Jones, M., Nadalin, A., Campbell, B., Bradley, J., and C. + Mortimore, "OAuth 2.0 Token Exchange", draft-ietf-oauth- + token-exchange-16 (work in progress), October 2018. [IANA.CborWebTokenClaims] IANA, "CBOR Web Token (CWT) Claims", - . + . [IANA.JsonWebTokenClaims] IANA, "JSON Web Token Claims", . [IANA.OAuthAccessTokenTypes] IANA, "OAuth Access Token Types", - . + . [IANA.OAuthParameters] IANA, "OAuth Parameters", - . + . [IANA.TokenIntrospectionResponse] IANA, "OAuth Token Introspection Response", - . + . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, - DOI 10.17487/RFC2119, March 1997, . + DOI 10.17487/RFC2119, March 1997, + . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, January 2012, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, - DOI 10.17487/RFC6750, October 2012, . + DOI 10.17487/RFC6750, October 2012, + . [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, . + [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., + Keranen, A., and P. Hallam-Baker, "Naming Things with + Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013, + . + [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, - DOI 10.17487/RFC7252, June 2014, . + DOI 10.17487/RFC7252, June 2014, + . [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, . [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . @@ -2472,100 +2546,100 @@ Datagram Transport Layer Security (DTLS) Protocol Version 1.3", draft-ietf-tls-dtls13-30 (work in progress), November 2018. [Margi10impact] Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr, M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold, "Impact of Operating Systems on Wireless Sensor Networks (Security) Applications and Testbeds", Proceedings of the 19th International Conference on Computer - Communications and Networks (ICCCN), 2010 August. + Communications and Networks (ICCCN), August 2010. [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, . [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, . [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, - DOI 10.17487/RFC6819, January 2013, . + DOI 10.17487/RFC6819, January 2013, + . [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013, . [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for Constrained-Node Networks", RFC 7228, - DOI 10.17487/RFC7228, May 2014, . + DOI 10.17487/RFC7228, May 2014, + . [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, - DOI 10.17487/RFC7231, June 2014, . + DOI 10.17487/RFC7231, June 2014, + . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [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, . + 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, . + 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, . + DOI 10.17487/RFC7959, August 2016, + . [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, - DOI 10.17487/RFC8259, December 2017, . + DOI 10.17487/RFC8259, December 2017, + . [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, - DOI 10.17487/RFC8414, June 2018, . + DOI 10.17487/RFC8414, June 2018, + . [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . - [RFC8516] Keranen, A., ""Too Many Requests" - Response Code for the Constrained Application Protocol", - RFC 8516, DOI 10.17487/RFC8516, January 2019, + [RFC8516] Keraenen, A., ""Too Many Requests" Response Code for the + Constrained Application Protocol", RFC 8516, + DOI 10.17487/RFC8516, January 2019, . Appendix A. Design Justification This section provides further insight into the design decisions of the solution documented in this document. Section 3 lists several building blocks and briefly summarizes their importance. The justification for offering some of those building blocks, as opposed to using OAuth 2.0 as is, is given below. @@ -2963,44 +3037,43 @@ | | B: |<--------+ Header: 2.05 Content | 2.05 | Content-Format: application/ace+cbor | | Payload: | | Figure 17: Token Request and Response Using Client Credentials. The information contained in the Request-Payload and the Response- Payload is shown in Figure 18 Note that the parameter "rs_cnf" from + [I-D.ietf-ace-oauth-params] is used to inform the client about the resource server's public key. Request-Payload : { - "grant_type" : "client_credentials", - "req_aud" : "tempSensorInLivingRoom", + "audience" : "tempSensorInLivingRoom", "client_id" : "myclient", "client_secret" : "qwerty" "req_cnf" : { "COSE_Key" : { "kid" : b64'1Bg8vub9tLe1gHMzV76e8', "kty" : "EC", "crv" : "P-256", "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' } } } Response-Payload : { "access_token" : b64'SlAV32hkKG ...', - "token_type" : "pop", "rs_cnf" : { "COSE_Key" : { "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kty" : "EC", "crv" : "P-256", "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' } } } @@ -3141,29 +3214,27 @@ | 2.05 | Payload: | | Figure 22: Token Request and Response using Client Credentials. The information contained in the Request-Payload and the Response- Payload is shown in Figure 23. Request-Payload: { - "grant_type" : "client_credentials", "client_id" : "keyfob", "client_secret" : "qwerty" } Response-Payload: { "access_token" : b64'VGVzdCB0b2tlbg==', - "token_type" : "pop", "cnf" : { "COSE_Key" : { "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kty" : "oct", "alg" : "HS256", "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' } } } @@ -3258,46 +3329,51 @@ F: |<--------+ Header: 2.04 Changed | 2.04 | Payload: | | Figure 26: Resource request and response protected by OSCORE Appendix F. Document Updates RFC EDITOR: PLEASE REMOVE THIS SECTION. -F.1. Version -18 to -19 +F.1. Verion -19 to 20 + + o Replaced "req_aud" with "audience" from the OAuth token exchange + draft. + o Updated examples to remove unnecessary elements. + +F.2. Version -18 to -19 o Added definition of "Authorization Information". o Explicitly state that ACE allows encoding refresh tokens in binary format in addition to strings. o Renamed "AS Information" to "AS Request Creation Hints" and added the possibility to specify req_aud and scope as hints. o Added the "kid" parameter to AS Request Creation Hints. o Added security considerations about the integrity protection of tokens with multi-RS audiences. o Renamed IANA registries mapping OAuth parameters to reflect the mapped registry. o Added JWT claim names to CWT claim registrations. o Added expert review instructions. o Updated references to TLS from 1.2 to 1.3. -F.2. Version -17 to -18 +F.3. Version -17 to -18 o Added OSCORE options in examples involving OSCORE. o Removed requirement for the client to send application/cwt, since the client has no way to know. - o Clarified verification of tokens by the RS. o Added exi claim CWT registration. -F.3. Version -16 to -17 +F.4. Version -16 to -17 o Added references to (D)TLS 1.3. o Added requirement that responses are bound to requests. o Specify that grant_type is OPTIONAL in C2AS requests (as opposed to REQUIRED in OAuth). o Replaced examples with hypothetical COSE profile with OSCORE. o Added requirement for content type application/ace+cbor in error responses for token and introspection requests and responses. o Reworked abbreviation space for claims, request and response parameters. @@ -3305,90 +3381,91 @@ info resource. o Added section that specifies how the RS verifies an access token. o Added section on the protection of the authz-info endpoint. o Removed the expiration mechanism based on sequence numbers. o Added reference to RFC7662 security considerations. o Added considerations on minimal security requirements for communication. o Added security considerations on unprotected information sent to authz-info and in the error responses. -F.4. Version -15 to -16 +F.5. Version -15 to -16 o Added text the RS using RFC6750 error codes. o Defined an error code for incompatible token request parameters. o Removed references to the actors draft. o Fixed errors in examples. -F.5. Version -14 to -15 +F.6. Version -14 to -15 o Added text about refresh tokens. o Added text about protection of credentials. o Rephrased introspection so that other entities than RS can do it. o Editorial improvements. -F.6. Version -13 to -14 +F.7. Version -13 to -14 o Split out the 'aud', 'cnf' and 'rs_cnf' parameters to [I-D.ietf-ace-oauth-params] o Introduced the "application/ace+cbor" Content-Type. o Added claim registrations from 'profile' and 'rs_cnf'. o Added note on schema part of AS Information Section 5.1.2 o Realigned the parameter abbreviations to push rarely used ones to the 2-byte encoding size of CBOR integers. -F.7. Version -12 to -13 +F.8. Version -12 to -13 o Changed "Resource Information" to "Access Information" to avoid confusion. o Clarified section about AS discovery. o Editorial changes -F.8. Version -11 to -12 +F.9. Version -11 to -12 o Moved the Request error handling to a section of its own. o Require the use of the abbreviation for profile identifiers. o Added rs_cnf parameter in the introspection response, to inform RS' with several RPKs on which key to use. o Allowed use of rs_cnf as claim in the access token in order to inform an RS with several RPKs on which key to use. o Clarified that profiles must specify if/how error responses are protected. o Fixed label number range to align with COSE/CWT. o Clarified the requirements language in order to allow profiles to specify other payload formats than CBOR if they do not use CoAP. -F.9. Version -10 to -11 +F.10. Version -10 to -11 o Fixed some CBOR data type errors. o Updated boilerplate text -F.10. Version -09 to -10 +F.11. Version -09 to -10 o Removed CBOR major type numbers. o Removed the client token design. o Rephrased to clarify that other protocols than CoAP can be used. o Clarifications regarding the use of HTTP -F.11. Version -08 to -09 +F.12. Version -08 to -09 o Allowed scope to be byte strings. o Defined default names for endpoints. o Refactored the IANA section for briefness and consistency. + o Refactored tables that define IANA registry contents for consistency. o Created IANA registry for CBOR mappings of error codes, grant types and Authorization Server Information. o Added references to other document sections defining IANA entries in the IANA section. -F.12. Version -07 to -08 +F.13. Version -07 to -08 o Moved AS discovery from the DTLS profile to the framework, see Section 5.1. o Made the use of CBOR mandatory. If you use JSON you can use vanilla OAuth. o Made it mandatory for profiles to specify C-AS security and RS-AS security (the latter only if introspection is supported). o Made the use of CBOR abbreviations mandatory. o Added text to clarify the use of token references as an alternative to CWTs. @@ -3402,40 +3479,39 @@ o Added text that clarifies that introspection is optional. o Made profile parameter optional since it can be implicit. o Clarified that CoAP is not mandatory and other protocols can be used. o Clarified the design justification for specific features of the framework in appendix A. o Clarified appendix E.2. o Removed specification of the "cnf" claim for CBOR/COSE, and replaced with references to [I-D.ietf-ace-cwt-proof-of-possession] -F.13. Version -06 to -07 +F.14. Version -06 to -07 o Various clarifications added. o Fixed erroneous author email. -F.14. Version -05 to -06 +F.15. 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.2, and Section 5.3. o Added Section 5.4 on AS authentication. o Added Section 5.5 on the Authorization endpoint. -F.15. Version -04 to -05 +F.16. Version -04 to -05 o Added RFC 2119 language to the specification of the required behavior of profile specifications. o Added Section 5.3 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.8.3 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 @@ -3434,64 +3510,64 @@ o Added clarification about token expiration and long-running requests in Section 5.8.3 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.16. Version -03 to -04 +F.17. 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.17. Version -02 to -03 +F.18. 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.18. Version -01 to -02 +F.19. 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, introspection 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.19. Version -00 to -01 +F.20. 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 access 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