--- 1/draft-ietf-ace-oauth-authz-43.txt 2021-08-25 00:13:23.048835828 -0700 +++ 2/draft-ietf-ace-oauth-authz-44.txt 2021-08-25 00:13:23.208839844 -0700 @@ -1,26 +1,26 @@ ACE Working Group L. Seitz Internet-Draft Combitech Intended status: Standards Track G. Selander -Expires: January 11, 2022 Ericsson +Expires: 25 February 2022 Ericsson E. Wahlstroem S. Erdtman Spotify AB H. Tschofenig Arm Ltd. - July 10, 2021 + 24 August 2021 Authentication and Authorization for Constrained Environments (ACE) using the OAuth 2.0 Framework (ACE-OAuth) - draft-ietf-ace-oauth-authz-43 + draft-ietf-ace-oauth-authz-44 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 the Constrained Application Protocol (CoAP), thus transforming a well-known and widely used authorization solution into a form suitable for IoT devices. Existing specifications are used where possible, but extensions are added and profiles are defined to @@ -34,113 +34,113 @@ 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 January 11, 2022. + This Internet-Draft will expire on 25 February 2022. Copyright Notice Copyright (c) 2021 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 - 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. + 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 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.1. Discovering Authorization Servers . . . . . . . . . . . . 16 - 5.2. Unauthorized Resource Request Message . . . . . . . . . . 17 + 5.2. Unauthorized Resource Request Message . . . . . . . . . . 16 5.3. AS Request Creation Hints . . . . . . . . . . . . . . . . 17 5.3.1. The Client-Nonce Parameter . . . . . . . . . . . . . 19 5.4. Authorization Grants . . . . . . . . . . . . . . . . . . 20 - 5.5. Client Credentials . . . . . . . . . . . . . . . . . . . 21 + 5.5. Client Credentials . . . . . . . . . . . . . . . . . . . 20 5.6. AS Authentication . . . . . . . . . . . . . . . . . . . . 21 5.7. The Authorization Endpoint . . . . . . . . . . . . . . . 21 - 5.8. The Token Endpoint . . . . . . . . . . . . . . . . . . . 22 + 5.8. The Token Endpoint . . . . . . . . . . . . . . . . . . . 21 5.8.1. Client-to-AS Request . . . . . . . . . . . . . . . . 22 5.8.2. AS-to-Client Response . . . . . . . . . . . . . . . . 25 5.8.3. Error Response . . . . . . . . . . . . . . . . . . . 27 5.8.4. Request and Response Parameters . . . . . . . . . . . 28 5.8.4.1. Grant Type . . . . . . . . . . . . . . . . . . . 28 5.8.4.2. Token Type . . . . . . . . . . . . . . . . . . . 29 5.8.4.3. Profile . . . . . . . . . . . . . . . . . . . . . 29 5.8.4.4. Client-Nonce . . . . . . . . . . . . . . . . . . 30 5.8.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 30 5.9. The Introspection Endpoint . . . . . . . . . . . . . . . 31 5.9.1. Introspection Request . . . . . . . . . . . . . . . . 32 5.9.2. Introspection Response . . . . . . . . . . . . . . . 33 5.9.3. Error Response . . . . . . . . . . . . . . . . . . . 34 5.9.4. Mapping Introspection Parameters to CBOR . . . . . . 35 - 5.10. The Access Token . . . . . . . . . . . . . . . . . . . . 35 + 5.10. The Access Token . . . . . . . . . . . . . . . . . . . . 36 5.10.1. The Authorization Information Endpoint . . . . . . . 36 - 5.10.1.1. Verifying an Access Token . . . . . . . . . . . 37 + 5.10.1.1. Verifying an Access Token . . . . . . . . . . . 38 5.10.1.2. Protecting the Authorization Information - Endpoint . . . . . . . . . . . . . . . . . . . . 39 - 5.10.2. Client Requests to the RS . . . . . . . . . . . . . 39 - 5.10.3. Token Expiration . . . . . . . . . . . . . . . . . . 40 + Endpoint . . . . . . . . . . . . . . . . . . . . . 39 + 5.10.2. Client Requests to the RS . . . . . . . . . . . . . 40 + 5.10.3. Token Expiration . . . . . . . . . . . . . . . . . . 41 5.10.4. Key Expiration . . . . . . . . . . . . . . . . . . . 42 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 42 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 43 6.1. Protecting Tokens . . . . . . . . . . . . . . . . . . . . 43 6.2. Communication Security . . . . . . . . . . . . . . . . . 44 6.3. Long-Term Credentials . . . . . . . . . . . . . . . . . . 44 6.4. Unprotected AS Request Creation Hints . . . . . . . . . . 45 - 6.5. Minimal Security Requirements for Communication . 45 + 6.5. Minimal Security Requirements for Communication . . . . . 45 6.6. Token Freshness and Expiration . . . . . . . . . . . . . 46 6.7. Combining Profiles . . . . . . . . . . . . . . . . . . . 47 6.8. Unprotected Information . . . . . . . . . . . . . . . . . 47 6.9. Identifying Audiences . . . . . . . . . . . . . . . . . . 48 - 6.10. Denial of Service Against or with Introspection . . 49 + 6.10. Denial of Service Against or with Introspection . . . . . 49 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 49 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 8.1. ACE Authorization Server Request Creation Hints . . . . . 50 8.2. CoRE Resource Type Registry . . . . . . . . . . . . . . . 51 8.3. OAuth Extensions Error Registration . . . . . . . . . . . 51 - 8.4. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 51 + 8.4. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 52 8.5. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 52 - 8.6. OAuth Access Token Types . . . . . . . . . . . . . . . . 52 + 8.6. OAuth Access Token Types . . . . . . . . . . . . . . . . 53 8.7. OAuth Access Token Type CBOR Mappings . . . . . . . . . . 53 8.7.1. Initial Registry Contents . . . . . . . . . . . . . . 53 - 8.8. ACE Profile Registry . . . . . . . . . . . . . . . . . . 53 + 8.8. ACE Profile Registry . . . . . . . . . . . . . . . . . . 54 8.9. OAuth Parameter Registration . . . . . . . . . . . . . . 54 8.10. OAuth Parameters CBOR Mappings Registry . . . . . . . . . 54 8.11. OAuth Introspection Response Parameter Registration . . . 55 - 8.12. OAuth Token Introspection Response CBOR Mappings Registry 55 + 8.12. OAuth Token Introspection Response CBOR Mappings + Registry . . . . . . . . . . . . . . . . . . . . . . . . 56 8.13. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 56 - 8.14. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 56 - 8.15. Media Type Registrations . . . . . . . . . . . . . . . . 57 + 8.14. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 57 + 8.15. Media Type Registrations . . . . . . . . . . . . . . . . 58 8.16. CoAP Content-Format Registry . . . . . . . . . . . . . . 58 - 8.17. Expert Review Instructions . . . . . . . . . . . . . . . 58 - 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 59 + 8.17. Expert Review Instructions . . . . . . . . . . . . . . . 59 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 60 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 60 10.1. Normative References . . . . . . . . . . . . . . . . . . 60 - 10.2. Informative References . . . . . . . . . . . . . . . . . 62 - Appendix A. Design Justification . . . . . . . . . . . . . . . . 65 + 10.2. Informative References . . . . . . . . . . . . . . . . . 63 + Appendix A. Design Justification . . . . . . . . . . . . . . . . 66 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 69 Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 71 Appendix D. Assumptions on AS Knowledge about C and RS . . . . . 72 Appendix E. Differences to OAuth 2.0 . . . . . . . . . . . . . . 73 Appendix F. Deployment Examples . . . . . . . . . . . . . . . . 73 F.1. Local Token Validation . . . . . . . . . . . . . . . . . 74 F.2. Introspection Aided Token Validation . . . . . . . . . . 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82 1. Introduction @@ -733,26 +736,26 @@ dedicated secure service provided by the client owner) . 5.2. Unauthorized Resource Request Message An Unauthorized Resource Request message is a request for any resource hosted by RS for which the client does not have authorization granted. RSes MUST treat any request for a protected resource as an Unauthorized Resource Request message when any of the following hold: - o The request has been received on an unsecured channel. + * The request has been received on an unsecured channel. - o The RS has no valid access token for the sender of the request + * The RS has no valid access token for the sender of the request regarding the requested action on that resource. - o The RS has a valid access token for the sender of the request, but + * The RS has a valid access token for the sender of the request, but that token does not authorize the requested action on the requested resource. Note: These conditions ensure that the RS can handle requests autonomously once access was granted and a secure channel has been established between C and RS. The authz-info endpoint, as part of the process for authorizing to protected resources, is not itself a protected resource and MUST NOT be protected as specified above (cf. Section 5.10.1). @@ -770,35 +773,35 @@ The "AS Request Creation Hints" message is sent by an RS as a response to an Unauthorized Resource Request message (see Section 5.2) to help the sender of the Unauthorized Resource Request message acquire a valid access token. The "AS Request Creation Hints" message is a CBOR or JSON map, with an OPTIONAL element "AS" specifying an absolute URI (see Section 4.3 of [RFC3986]) that identifies the appropriate AS for the RS. The message can also contain the following OPTIONAL parameters: - o A "audience" element contains an identifier the client should + * A "audience" element contains an identifier the client should request at the AS, as suggested by the RS. With this parameter, when included in the access token request to the AS, the AS is able to restrict the use of access token to specific RSs. See Section 6.9 for a discussion of this parameter. - o A "kid" element containing the key identifier of a key used in an + * 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 "cnonce" element containing a client-nonce. See Section 5.3.1. + * A "cnonce" element containing a client-nonce. See Section 5.3.1. - o A "scope" element containing the suggested scope that the client + * 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 | 1 | text string | | kid | 2 | byte string | @@ -865,38 +867,38 @@ 5.3.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 An RS sending a "cnonce" parameter in an "AS Request Creation + * An RS sending a "cnonce" parameter in 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, with some allowance for unexpected delays. - o A client receiving a "cnonce" parameter in an "AS Request Creation + * 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.8.4.4. - o If an AS grants an access token request containing a "cnonce" + * 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.10. - o An RS that is using the client-nonce mechanism and that receives + * An 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, the RS 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.4. Authorization Grants @@ -1000,44 +1002,44 @@ 5.8.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, with the following exceptions and additions: - o The parameter "grant_type" is OPTIONAL in the context of this + * 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. - o The "audience" parameter from [RFC8693] is OPTIONAL to request an + * The "audience" parameter from [RFC8693] is OPTIONAL to request an access token bound to a specific audience. - o The "cnonce" parameter defined in Section 5.8.4.4 is REQUIRED if + * The "cnonce" parameter defined in Section 5.8.4.4 is REQUIRED if the RS provided a client-nonce in the "AS Request Creation Hints" message Section 5.3 - o The "scope" parameter MAY be encoded as a byte string instead of + * 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. The syntax of such a binary encoding is explicitly not specified here and left to profiles or applications. Note specifically that a binary encoded scope does not necessarily use the space character '0x20' to delimit scope-tokens. - o The client can send an empty (null value) "ace_profile" parameter + * The client can send an empty (null value) "ace_profile" parameter to indicate that it wants the AS to include the "ace_profile" parameter in the response. See Section 5.8.4.3. - o A client MUST be able to use the parameters from + * 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. The default behavior, is that the AS generates a symmetric proof-of- possession key for the client. In order to use an asymmetric key pair or to re-use a key previously established with the RS, the client is supposed to use the "req_cnf" parameter from [I-D.ietf-ace-oauth-params]. @@ -1058,22 +1060,22 @@ Header: POST (Code=0.02) Uri-Host: "as.example.com" Uri-Path: "token" Content-Format: "application/ace+cbor" Payload: { "client_id" : "myclient", "audience" : "tempSensor4711" } - Figure 5: Example request for an access token bound to a symmetric - key. + 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 [RFC8613] is used to provide object-security, therefore the Content-Format is "application/oscore" wrapping the "application/ace+cbor" type content. The OSCORE option has a decoded interpretation appended in parentheses for the reader's convenience. Also note that in this example the audience is implicitly known by both client and AS. Furthermore note that this example uses the "req_cnf" parameter from [I-D.ietf-ace-oauth-params]. @@ -1226,64 +1228,65 @@ Figure 9: Example AS response with an access token bound to a symmetric key. 5.8.3. Error Response The error responses for interactions with the AS are generally equivalent to the ones defined in Section 5.2 of [RFC6749], with the following exceptions: - o When using CoAP the payload MUST be encoded as a CBOR map, with + * When using CoAP the payload MUST be encoded as a CBOR map, with the Content-Format "application/ace+cbor". When using HTTP the payload is encoded in JSON as specified in section 5.2 of [RFC6749]. - o A response code equivalent to the CoAP code 4.00 (Bad Request) + * A response code equivalent to the CoAP code 4.00 (Bad Request) MUST be used for all error responses, except for invalid_client where a response code equivalent to the CoAP code 4.01 (Unauthorized) MAY be used under the same conditions as specified in Section 5.2 of [RFC6749]. - o The parameters "error", "error_description" and "error_uri" MUST + * The parameters "error", "error_description" and "error_uri" MUST be abbreviated using the codes specified in Figure 12, when a CBOR encoding is used. - o The error code (i.e., value of the "error" parameter) MUST be + * The error code (i.e., value of the "error" parameter) MUST be abbreviated as specified in Figure 10, when a CBOR encoding is used. - /---------------------------+-------------\ - | Name | CBOR Values | - |---------------------------+-------------| - | invalid_request | 1 | - | invalid_client | 2 | - | invalid_grant | 3 | - | unauthorized_client | 4 | - | unsupported_grant_type | 5 | - | invalid_scope | 6 | - | unsupported_pop_key | 7 | - | incompatible_ace_profiles | 8 | - \---------------------------+-------------/ + /---------------------------+--------+--------------------------\ + | | CBOR | Original | + | Name | Values | Specification | + |---------------------------+--------+--------------------------| + | invalid_request | 1 | section 5.2 of [RFC6749] | + | invalid_client | 2 | section 5.2 of [RFC6749] | + | invalid_grant | 3 | section 5.2 of [RFC6749] | + | unauthorized_client | 4 | section 5.2 of [RFC6749] | + | unsupported_grant_type | 5 | section 5.2 of [RFC6749] | + | invalid_scope | 6 | section 5.2 of [RFC6749] | + | unsupported_pop_key | 7 | [this document] | + | incompatible_ace_profiles | 8 | [this document] | + \---------------------------+--------+--------------------------/ Figure 10: CBOR abbreviations for common error codes In addition to the error responses defined in OAuth 2.0, the following behavior MUST be implemented by the AS: - o If the client submits an asymmetric key in the token request that + * If the client submits an asymmetric key in the token request that the RS cannot process, the AS MUST reject that request with a response code equivalent to the CoAP code 4.00 (Bad Request) including the error code "unsupported_pop_key" specified in Figure 10. - o If the client and the RS it has requested an access token for do + * If the client and the RS it has requested an access token for do not share a common profile, the AS MUST reject that request with a response code equivalent to the CoAP code 4.00 (Bad Request) including the error code "incompatible_ace_profiles" specified in Figure 10. 5.8.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 @@ -1367,44 +1370,45 @@ 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 | - | 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 | integer | - | error_description | 31 | text string | - | error_uri | 32 | text string | - | grant_type | 33 | unsigned integer | - | token_type | 34 | integer | - | username | 35 | text string | - | password | 36 | text string | - | refresh_token | 37 | byte string | - | ace_profile | 38 | integer | - | cnonce | 39 | byte string | - \-------------------+----------+---------------------/ + /-------------------+----------+---------------------+---------------\ + | | | | Original | + | Name | CBOR Key | Value Type | Specification | + |-------------------+----------+---------------------+---------------| + | access_token | 1 | byte string | [RFC6749] | + | expires_in | 2 | unsigned integer | [RFC6749] | + | audience | 5 | text string | [RFC8693] | + | scope | 9 | text or byte string | [RFC6749] | + | client_id | 24 | text string | [RFC6749] | + | client_secret | 25 | byte string | [RFC6749] | + | response_type | 26 | text string | [RFC6749] | + | redirect_uri | 27 | text string | [RFC6749] | + | state | 28 | text string | [RFC6749] | + | code | 29 | byte string | [RFC6749] | + | error | 30 | integer | [RFC6749] | + | error_description | 31 | text string | [RFC6749] | + | error_uri | 32 | text string | [RFC6749] | + | grant_type | 33 | unsigned integer | [RFC6749] | + | token_type | 34 | integer | [RFC6749] | + | username | 35 | text string | [RFC6749] | + | password | 36 | text string | [RFC6749] | + | refresh_token | 37 | byte string | [RFC6749] | + | ace_profile | 38 | integer |[this document]| + | cnonce | 39 | byte string |[this document]| + \-------------------+----------+---------------------+---------------/ Figure 12: CBOR mappings used in token requests and responses 5.9. The Introspection Endpoint Token introspection [RFC7662] MAY be implemented by the AS, and the RS. When implemented, it MAY be used by the RS and 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 defines adaptations to more constrained environments using CBOR and @@ -1487,20 +1491,25 @@ use with the client. See Section 5.8.4.3 for more details on the formatting of this parameter. If this parameter is absent, the AS assumes that the RS implicitly knows which profile to use towards the client. cnonce OPTIONAL. A client-nonce provided to the AS by the client. The RS MUST verify that this corresponds to the client-nonce previously provided to the client in the "AS Request Creation Hints". See Section 5.3 and Section 5.8.4.4. + cti OPTIONAL. The "cti" claim associated to this access token. + This parameter has the same meaning and processing rules as the + "jti" parameter defined in section 3.1.2 of [RFC7662] except that + the value is a byte string. + exi OPTIONAL. The "expires-in" claim associated to this access token. See Section 5.10.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]. @@ -1522,86 +1531,89 @@ } Figure 15: Example introspection response. 5.9.3. Error Response The error responses for CoAP-based interactions with the AS are equivalent to the ones for HTTP-based interactions as defined in Section 2.3 of [RFC7662], with the following differences: - o If content is sent and CoAP is used the payload MUST be encoded as + * If content is sent and CoAP is used the payload MUST be encoded as a CBOR map and the Content-Format "application/ace+cbor" MUST be used. For HTTP the encoding defined in section 2.3 of [RFC6749] is used. - o If the credentials used by the requesting entity (usually the RS) + * If the credentials used by the requesting entity (usually the RS) are invalid the AS MUST respond with the response code equivalent to the CoAP code 4.01 (Unauthorized) and use the required and optional parameters from Section 2.3 in [RFC7662]. - o If the requesting entity does not have the right to perform this + * If the requesting entity does not have the right to perform this introspection request, the AS MUST respond with a response code equivalent to the CoAP code 4.03 (Forbidden). In this case no payload is returned. - o The parameters "error", "error_description" and "error_uri" MUST + * The parameters "error", "error_description" and "error_uri" MUST be abbreviated using the codes specified in Figure 12. - o The error codes MUST be abbreviated using the codes specified in + * The error codes MUST be abbreviated using the codes specified in the registry defined by Section 8.4. Note that a properly formed and authorized query for an inactive or otherwise invalid token does not warrant an error response by this specification. In these cases, the authorization server MUST instead respond with an introspection response with the "active" field set to "false". 5.9.4. Mapping Introspection Parameters to CBOR If CBOR is used, the introspection request and response parameters MUST be mapped to CBOR types as specified in the registry defined by Section 8.12, using the given integer abbreviation for the map key. Note that we have aligned abbreviations that correspond to a claim with the abbreviations defined in [RFC8392] and the abbreviations of parameters with the same name from Section 5.8.5. - /-------------------+----------+-------------------------\ - | Parameter name | CBOR Key | Value Type | - |-------------------+----------+-------------------------| - | iss | 1 | text string | - | sub | 2 | text string | - | aud | 3 | text string | - | exp | 4 | integer or | - | | | floating-point number | - | nbf | 5 | integer or | - | | | floating-point number | - | iat | 6 | integer or | - | | | floating-point number | - | cti | 7 | byte string | - | scope | 9 | text or byte string | - | active | 10 | True or False | - | token | 11 | byte string | - | client_id | 24 | text string | - | error | 30 | integer | - | error_description | 31 | text string | - | error_uri | 32 | text string | - | token_type_hint | 33 | text string | - | token_type | 34 | integer | - | username | 35 | text string | - | ace_profile | 38 | integer | - | cnonce | 39 | byte string | - | exi | 40 | unsigned integer | - \-------------------+----------+-------------------------/ - - Figure 16: CBOR Mappings to Token Introspection Parameters. + /-------------------+----------+-------------------+---------------\ + | | | | Original | + | Parameter name | CBOR Key | Value Type | Specification | + |-------------------+----------+-------------------+---------------| + | iss | 1 | text string | [RFC7662] | + | sub | 2 | text string | [RFC7662] | + | aud | 3 | text string | [RFC7662] | + | exp | 4 | integer or | [RFC7662] | + | | | floating-point | | + | | | number | | + | nbf | 5 | integer or | [RFC7662] | + | | | floating-point | | + | | | number | | + | iat | 6 | integer or | [RFC7662] | + | | | floating-point | | + | | | number | | + | scope | 9 | text or | | + | | | byte string | [RFC7662] | + | active | 10 | True or False | [RFC7662] | + | token | 11 | byte string | [RFC7662] | + | client_id | 24 | text string | [RFC7662] | + | error | 30 | integer | [RFC7662] | + | error_description | 31 | text string | [RFC7662] | + | error_uri | 32 | text string | [RFC7662] | + | token_type_hint | 33 | text string | [RFC7662] | + | token_type | 34 | integer | [RFC7662] | + | username | 35 | text string | [RFC7662] | + | ace_profile | 38 | integer |[this document]| + | cnonce | 39 | byte string |[this document]| + | exi | 40 | unsigned integer |[this document]| + \-------------------+----------+-------------------+---------------/ + Figure 16: CBOR mappings for Token Introspection Parameters. 5.10. The Access Token In this framework the use of CBOR Web Token (CWT) as specified in [RFC8392] is RECOMMENDED. In order to facilitate offline processing of access tokens, this document uses the "cnf" claim from [RFC8747] and the "scope" claim from [RFC8693] for JWT- and CWT-encoded tokens. In addition to string encoding specified for the "scope" claim, a binary encoding @@ -1709,27 +1721,27 @@ generated by an AS that has the right to issue access tokens for this RS. In case the token is communicated by reference the RS needs to obtain the claims first. When the RS uses token introspection the relevant specification is [RFC7662] with CoAP transport specified in Section 5.9. Errors may happen during this initial processing stage: - o If the verification of the security wrapper fails, or the token + * If the verification of the security wrapper fails, or the token was issued by an AS that does not have the right to issue tokens for the receiving RS, the RS MUST discard the token and, if this was an interaction with authz-info, return an error message with a response code equivalent to the CoAP code 4.01 (Unauthorized). - o If the claims cannot be obtained the RS MUST discard the token + * If the claims cannot be obtained the RS MUST discard the token and, in case of an interaction via the authz-info endpoint, return an error message with a response code equivalent to the CoAP code 4.00 (Bad Request). Next, the RS MUST verify claims, if present, contained in the access token. Errors are returned when claim checks fail, in the order of priority of this list: iss The issuer claim (if present) must identify the AS that has produced the security protection for the access token. If that is @@ -1828,63 +1840,63 @@ proof-of-possession for that token, the RS continues to process the request as specified by the underlying application. 5.10.3. Token Expiration Depending on the capabilities of the RS, there are various ways in which it can verify the expiration of a received access token. Here follows a list of the possibilities including what functionality they require of the RS. - o The token is a CWT and includes an "exp" claim and possibly the + * The token is a CWT and includes an "exp" claim and possibly the "nbf" claim. The RS verifies these by comparing them to values from its internal clock as defined in [RFC7519]. In this case the RS's internal clock must reflect the current date and time, or at least be synchronized with the AS's clock. How this clock synchronization would be performed is out of scope for this specification. - o The RS verifies the validity of the token by performing an + * The RS verifies the validity of the token by performing an introspection request as specified in Section 5.9. This requires the RS to have a reliable network connection to the AS and to be able to handle two secure sessions in parallel (C to RS and RS to AS). - o In order to support token expiration for devices that have no + * In order to support token expiration for devices that have no reliable way of synchronizing their internal clocks, this specification defines the following approach: The claim "exi" ("expires in") can be used, to provide the RS with the lifetime of the token in seconds from the time the RS first receives the token. This mechanism only works for self-contained tokens, i.e. CWTs and JWTs. For CWTs this parameter is encoded as unsigned integer, while JWTs encode this as JSON number. - o Processing this claim requires that the RS does the following: + * Processing this claim requires that the RS does the following: - * For each token the RS receives, that contains an "exi" claim: + - For each token the RS receives, that contains an "exi" claim: Keep track of the time it received that token and revisit that list regularly to expunge expired tokens. - * Keep track of the identifiers of tokens containing the "exi" + - Keep track of the identifiers of tokens containing the "exi" claim that have expired (in order to avoid accepting them again). In order to avoid an unbounded memory usage growth, this MUST be implemented in the following way when the "exi" claim is used: - + When creating the token, the AS MUST add a 'cti' claim ( or + o When creating the token, the AS MUST add a 'cti' claim ( or 'jti' for JWTs) to the access token. The value of this claim MUST be created as the binary representation of the concatenation of the identifier of the RS with a sequence number counting the tokens containing an 'exi' claim, issued by this AS for the RS. - + The RS MUST store the highest sequence number of an expired + o The RS MUST store the highest sequence number of an expired token containing the "exi" claim that it has seen, and treat tokens with lower sequence numbers as expired. Note that this could lead to discarding valid tokens with lower sequence numbers, if the AS where to issue tokens of different validity time for the same RS. The assumption is that typically tokens in such a scenario would all have the same validity time. If a token that authorizes a long running request such as a CoAP Observe [RFC7641] expires, the RS MUST send an error response with @@ -1902,27 +1914,27 @@ information to the RS using a key that is expired and possibly in the hands of an attacker, or accepts responses from the RS that are not properly protected and could possibly have been forged by an attacker. In order to prevent this, the client must assume that those keys are only valid as long as the related access token is. Since the access token is opaque to the client, one of the following methods MUST be used to inform the client about the validity of an access token: - o The client knows a default validity time for all tokens it is + * The client knows a default validity time for all tokens it is using (i.e. how long a token is valid after being issued). 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 + * The AS informs the client about the token validity using the "expires_in" parameter in the Access Information. 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 @@ -2326,60 +2338,62 @@ This registry will be initially populated by the values in Figure 2. The Reference column for all of these entries will be this document. 8.2. CoRE Resource Type Registry IANA is requested to register a new Resource Type (rt=) Link Target Attribute in the "Resource Type (rt=) Link Target Attribute Values" subregistry under the "Constrained RESTful Environments (CoRE) Parameters" [IANA.CoreParameters] registry: - o Value: "ace.ai" - o Description: ACE-OAuth authz-info endpoint resource. - o Reference: [this document] + * Value: "ace.ai" + * Description: ACE-OAuth authz-info endpoint resource. + * Reference: [this document] Specific ACE-OAuth profiles can use this common resource type for defining their profile-specific discovery processes. 8.3. OAuth Extensions Error Registration This specification registers the following error values in the OAuth Extensions Error registry [IANA.OAuthExtensionsErrorRegistry]. - o Error name: "unsupported_pop_key" - o Error usage location: token error response - o Related protocol extension: [this document] - o Change Controller: IESG - o Specification document(s): Section 5.8.3 of [this document] + * Error name: "unsupported_pop_key" + * Error usage location: token error response + * Related protocol extension: [this document] + * Change Controller: IETF + * Specification document(s): Section 5.8.3 of [this document] - o Error name: "incompatible_ace_profiles" - o Error usage location: token error response - o Related protocol extension: [this document] - o Change Controller: IESG - o Specification document(s): Section 5.8.3 of [this document] + * Error name: "incompatible_ace_profiles" + * Error usage location: token error response + * Related protocol extension: [this document] + * Change Controller: IETF + * Specification document(s): Section 5.8.3 of [this document] 8.4. OAuth Error Code CBOR Mappings Registry This specification establishes the IANA "OAuth Error Code CBOR Mappings" registry. The registry has been created to use the "Expert Review" registration procedure [RFC8126], except for the value range designated for private use. The columns of the registry are: Name The OAuth Error Code name, refers to the name in Section 5.2. of [RFC6749], e.g., "invalid_request". CBOR Value CBOR abbreviation for this error code. Integer values less than -65536 are marked as "Private Use", all other values use the registration policy "Expert Review" [RFC8126]. Reference This contains a pointer to the public specification of the error code abbreviation, if one exists. + Original Specification This contains a pointer to the public + specification of the error code, if one exists. This registry will be initially populated by the values in Figure 10. The Reference column for all of these entries will be this document. 8.5. OAuth Grant Type CBOR Mappings This specification establishes the IANA "OAuth Grant Type CBOR Mappings" registry. The registry has been created to use the "Expert Review" registration procedure [RFC8126], except for the value range designated for private use. @@ -2397,26 +2411,27 @@ specification of the grant type, if one exists. This registry will be initially populated by the values in Figure 11. The Reference column for all of these entries will be this document. 8.6. OAuth Access Token Types This section registers the following new token type in the "OAuth Access Token Types" registry [IANA.OAuthAccessTokenTypes]. - o Type name: "PoP" - o Additional Token Endpoint Response Parameters: "cnf", "rs_cnf" see - section 3.3 of [I-D.ietf-ace-oauth-params]. - o HTTP Authentication Scheme(s): N/A - o Change Controller: IETF - o Specification document(s): [this document] + * Type name: "PoP" + * Additional Token Endpoint Response Parameters: "cnf", "rs_cnf" see + section 3.1 of [RFC8747] and section 3.1 of + [I-D.ietf-ace-oauth-params]. + * HTTP Authentication Scheme(s): N/A + * Change Controller: IETF + * Specification document(s): [this document] 8.7. OAuth Access Token Type CBOR Mappings This specification established the IANA "OAuth Access Token Type CBOR Mappings" registry. The registry has been created to use the "Expert Review" registration procedure [RFC8126], except for the value range designated for private use. The columns of this registry are: @@ -2425,29 +2440,29 @@ CBOR Value CBOR abbreviation for this token type. Integer values less than -65536 are marked as "Private Use", all other values use the registration policy "Expert Review" [RFC8126]. Reference This contains a pointer to the public specification of the OAuth token type abbreviation, if one exists. Original Specification This contains a pointer to the public specification of the OAuth token type, if one exists. 8.7.1. Initial Registry Contents - o Name: "Bearer" - o Value: 1 - o Reference: [this document] - o Original Specification: [RFC6749] + * Name: "Bearer" + * Value: 1 + * Reference: [this document] + * Original Specification: [RFC6749] - o Name: "PoP" - o Value: 2 - o Reference: [this document] - o Original Specification: [this document] + * Name: "PoP" + * Value: 2 + * Reference: [this document] + * Original Specification: [this document] 8.8. ACE Profile Registry This specification establishes the IANA "ACE Profile" registry. The registry has been created to use the "Expert Review" registration procedure [RFC8126]. It should be noted that, in addition to the expert review, some portions of the registry require a specification, potentially a Standards Track RFC, be supplied as well. The columns of this registry are: @@ -2468,24 +2482,24 @@ profile abbreviation, if one exists. This registry will be initially empty and will be populated by the registrations from the ACE framework profiles. 8.9. OAuth Parameter Registration This specification registers the following parameter in the "OAuth Parameters" registry [IANA.OAuthParameters]: - o Name: "ace_profile" - o Parameter Usage Location: token response - o Change Controller: IESG - o Reference: Section 5.8.2 and Section 5.8.4.3 of [this document] + * Name: "ace_profile" + * Parameter Usage Location: token response + * Change Controller: IETF + * Reference: Section 5.8.2 and Section 5.8.4.3 of [this document] 8.10. OAuth Parameters CBOR Mappings Registry This specification establishes the IANA "OAuth Parameters CBOR Mappings" registry. The registry has been created to use the "Expert Review" registration procedure [RFC8126], except for the value range designated for private use. The columns of this registry are: @@ -2484,151 +2498,161 @@ This specification establishes the IANA "OAuth Parameters CBOR Mappings" registry. The registry has been created to use the "Expert Review" registration procedure [RFC8126], except for the value range designated for private use. The columns of this registry are: Name The OAuth Parameter name, refers to the name in the OAuth parameter registry, e.g., "client_id". + CBOR Key CBOR map key for this parameter. Integer values less than -65536 are marked as "Private Use", all other values use the registration policy "Expert Review" [RFC8126]. Value Type The allowable CBOR data types for values of this parameter. Reference This contains a pointer to the public specification of the OAuth parameter abbreviation, if one exists. + Original Specification This contains a pointer to the public + specification of the OAuth parameter, if one exists. This registry will be initially populated by the values in Figure 12. The Reference column for all of these entries will be this document. 8.11. OAuth Introspection Response Parameter Registration This specification registers the following parameters in the OAuth Token Introspection Response registry [IANA.TokenIntrospectionResponse]. - o Name: "ace_profile" - o Description: The ACE profile used between client and RS. - o Change Controller: IESG - o Reference: Section 5.9.2 of [this document] + * Name: "ace_profile" + * Description: The ACE profile used between client and RS. + * Change Controller: IETF + * Reference: Section 5.9.2 of [this document] - o Name: "cnonce" - o Description: "client-nonce". A nonce previously provided to the + * Name: "cnonce" + * Description: "client-nonce". A nonce previously provided to the AS by the RS via the client. Used to verify token freshness when the RS cannot synchronize its clock with the AS. - o Change Controller: IESG - o Reference: Section 5.9.2 of [this document] + * Change Controller: IETF + * Reference: Section 5.9.2 of [this document] - o Name: "exi" - o Description: "Expires in". Lifetime of the token in seconds from + * Name: "cti" + * Description: "CWT ID". The identifier of a CWT as defined in + [RFC8392]. + * Change Controller: IETF + * Reference: Section 5.9.2 of [this document] + + * Name: "exi" + * 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.9.2 of [this document] + * Change Controller: IETF + * Reference: Section 5.9.2 of [this document] 8.12. OAuth Token Introspection Response CBOR Mappings Registry This specification establishes the IANA "OAuth Token Introspection Response CBOR Mappings" registry. The registry has been created to use the "Expert Review" registration procedure [RFC8126], except for the value range designated for private use. The columns of this registry are: Name The OAuth Parameter name, refers to the name in the OAuth parameter registry, e.g., "client_id". CBOR Key CBOR map key for this parameter. Integer values less than -65536 are marked as "Private Use", all other values use the registration policy "Expert Review" [RFC8126]. Value Type The allowable CBOR data types for values of this parameter. Reference This contains a pointer to the public specification of the introspection response parameter abbreviation, if one exists. + Original Specification This contains a pointer to the public + specification of OAuth Token Introspection parameter, if one + exists. This registry will be initially populated by the values in Figure 16. The Reference column for all of these entries will be this document. Note that the mappings of parameters corresponding to claim names intentionally coincide with the CWT claim name mappings from [RFC8392]. 8.13. JSON Web Token Claims This specification registers the following new claims in the JSON Web Token (JWT) registry of JSON Web Token Claims [IANA.JsonWebTokenClaims]: - o Claim Name: "ace_profile" - o Claim Description: The ACE profile a token is supposed to be used + * Claim Name: "ace_profile" + * Claim Description: The ACE profile a token is supposed to be used with. - o Change Controller: IESG - o Reference: Section 5.10 of [this document] + * Change Controller: IETF + * Reference: Section 5.10 of [this document] - o Claim Name: "cnonce" - o Claim Description: "client-nonce". A nonce previously provided to + * Claim Name: "cnonce" + * Claim Description: "client-nonce". A nonce previously provided to the AS by the RS via the client. Used to verify token freshness when the RS cannot synchronize its clock with the AS. - o Change Controller: IESG - o Reference: Section 5.10 of [this document] - - o Claim Name: "exi" - o Claim Description: "Expires in". Lifetime of the token in seconds + * Change Controller: IETF + * Reference: Section 5.10 of [this document] + * Claim Name: "exi" + * 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.10.3 of [this document] + * Change Controller: IETF + * Reference: Section 5.10.3 of [this document] 8.14. CBOR Web Token Claims This specification registers the following new claims in the "CBOR Web Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. - o Claim Name: "ace_profile" - o Claim Description: The ACE profile a token is supposed to be used + * Claim Name: "ace_profile" + * Claim Description: The ACE profile a token is supposed to be used with. - o JWT Claim Name: ace_profile - o Claim Key: TBD (suggested: 38) - o Claim Value Type(s): integer - o Change Controller: IESG - o Specification Document(s): Section 5.10 of [this document] + * JWT Claim Name: ace_profile + * Claim Key: TBD (suggested: 38) + * Claim Value Type(s): integer + * Change Controller: IETF + * Specification Document(s): Section 5.10 of [this document] - o Claim Name: "cnonce" - o Claim Description: The client-nonce sent to the AS by the RS via + * Claim Name: "cnonce" + * Claim Description: The client-nonce sent to the AS by the RS via the client. + * JWT Claim Name: cnonce + * Claim Key: TBD (suggested: 39) + * Claim Value Type(s): byte string + * Change Controller: IETF + * Specification Document(s): Section 5.10 of [this document] - 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.10 of [this document] - - o Claim Name: "exi" - o Claim Description: The expiration time of a token measured from + * Claim Name: "exi" + * 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: 40) - o Claim Value Type(s): integer - o Change Controller: IESG - o Specification Document(s): Section 5.10.3 of [this document] + * JWT Claim Name: exi + * Claim Key: TBD (suggested: 40) + * Claim Value Type(s): integer + * Change Controller: IETF + * Specification Document(s): Section 5.10.3 of [this document] - o Claim Name: "scope" - o Claim Description: The scope of an access token as defined in + * Claim Name: "scope" + * 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 4.2 of [RFC8693] + * JWT Claim Name: scope + * Claim Key: TBD (suggested: 9) + * Claim Value Type(s): byte string or text string + * Change Controller: IETF + * Specification Document(s): Section 4.2 of [RFC8693] 8.15. 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 @@ -2656,21 +2681,21 @@ Person & email address to contact for further information: Intended usage: COMMON Restrictions on usage: none Author: Ludwig Seitz - Change controller: IESG + Change controller: IETF 8.16. CoAP Content-Format Registry This specification registers the following entry to the "CoAP Content-Formats" registry: Media Type: application/ace+cbor Encoding: - @@ -2681,40 +2706,40 @@ 8.17. Expert Review Instructions All of the IANA registries established in this document are defined to use a registration policy of Expert Review. This section gives some general guidelines for what the experts should be looking for, but they are being designated as experts for a reason, so they should be given substantial latitude. Expert reviewers should take into consideration the following points: - o Point squatting should be discouraged. Reviewers are encouraged + * Point squatting should be discouraged. Reviewers are encouraged to get sufficient information for registration requests to ensure that the usage is not going to duplicate one that is already registered, and that the point is likely to be used in deployments. The zones tagged as private use are intended for testing purposes and closed environments; code points in other ranges should not be assigned for testing. - o Specifications are needed for the first-come, first-serve range if + * Specifications are needed for the first-come, first-serve range if they are expected to be used outside of closed environments in an interoperable way. When specifications are not provided, the description provided needs to have sufficient information to identify what the point is being used for. - o Experts should take into account the expected usage of fields when + * Experts should take into account the expected usage of fields when approving point assignment. The fact that there is a range for standards track documents does not mean that a standards track document cannot have points assigned outside of that range. The length of the encoded value should be weighed against how many code points of that length are left, the size of device it will be used on. - o Since a high degree of overlap is expected between these + * Since a high degree of overlap is expected between these registries and the contents of the OAuth parameters [IANA.OAuthParameters] registries, experts should require new registrations to maintain alignment with parameters from OAuth that have comparable functionality. Deviation from this alignment should only be allowed if there are functional differences, that are motivated by the use case and that cannot be easily or efficiently addressed by comparable OAuth parameters. 9. Acknowledgments @@ -2749,22 +2774,24 @@ 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-oauth-params] Seitz, L., "Additional OAuth Parameters for Authorization - in Constrained Environments (ACE)", draft-ietf-ace-oauth- - params-14 (work in progress), March 2021. + in Constrained Environments (ACE)", Work in Progress, + Internet-Draft, draft-ietf-ace-oauth-params-15, 6 May + 2021, . [IANA.CborWebTokenClaims] IANA, "CBOR Web Token (CWT) Claims", . [IANA.CoreParameters] IANA, "Constrained RESTful Environments (CoRE) Parameters", . @@ -2873,54 +2900,63 @@ 10.2. Informative References [BLE] Bluetooth SIG, "Bluetooth Core Specification v5.1", Section 4.4, January 2019, . [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. + Key as OAuth client credentials", Work in Progress, + Internet-Draft, draft-erdtman-ace-rpcc-02, 30 October + 2017, . [I-D.ietf-ace-dtls-authorize] Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and L. Seitz, "Datagram Transport Layer Security (DTLS) Profile for Authentication and Authorization for - Constrained Environments (ACE)", draft-ietf-ace-dtls- - authorize-16 (work in progress), March 2021. + Constrained Environments (ACE)", Work in Progress, + Internet-Draft, draft-ietf-ace-dtls-authorize-18, 4 June + 2021, . [I-D.ietf-ace-oscore-profile] Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, "OSCORE Profile of the Authentication and Authorization - for Constrained Environments Framework", draft-ietf-ace- - oscore-profile-18 (work in progress), April 2021. + for Constrained Environments Framework", Work in Progress, + Internet-Draft, draft-ietf-ace-oscore-profile-19, 6 May + 2021, . [I-D.ietf-quic-transport] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed - and Secure Transport", draft-ietf-quic-transport-34 (work - in progress), January 2021. + and Secure Transport", Work in Progress, Internet-Draft, + draft-ietf-quic-transport-34, 14 January 2021, + . [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-43 (work in progress), April - 2021. + 1.3", Work in Progress, Internet-Draft, draft-ietf-tls- + dtls13-43, 30 April 2021, . [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), August 2010. + Margi, C. B., de Oliveira, B.T., de Sousa, G.T., Simplicio + Jr, M.A., Barreto, P.S.L.M., Carvalho, T.C.M.B., 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), August 2010. [MQTT5.0] Banks, A., Briggs, E., Borgendale, K., and R. Gupta, "MQTT Version 5.0", OASIS Standard, March 2019, . [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, . @@ -3219,175 +3230,165 @@ configured for the RS. * Optionally: Expose the introspection endpoint that allows RS's to submit token introspection requests. * If providing an introspection endpoint: Authenticate RSs that wish to get an introspection response. * If providing an introspection endpoint: Process token introspection requests. * Optionally: Handle token revocation. * Optionally: Provide discovery metadata. See [RFC8414] * Optionally: Handle refresh tokens. - Client - * Discover the AS in charge of the RS that is to be targeted with a request. * Submit the token request (see step (A) of Figure 1). - - + Authenticate to the AS. - + Optionally (if not pre-configured): Specify which RS, which + - Authenticate to the AS. + - Optionally (if not pre-configured): Specify which RS, which resource(s), and which action(s) the request(s) will target. - + If raw public keys (rpk) or certificates are used, make sure + - If raw public keys (rpk) or certificates are used, make sure the AS has the right rpk or certificate for this client. * Process the access token and Access Information (see step (B) of Figure 1). - - + Check that the Access Information provides the necessary + - Check that the Access Information provides the necessary security parameters (e.g., PoP key, information on communication security protocols supported by the RS). - + Safely store the proof-of-possession key. - + If provided by the AS: Safely store the refresh token. + - Safely store the proof-of-possession key. + + - If provided by the AS: Safely store the refresh token. * Send the token and request to the RS (see step (C) of Figure 1). - - + Authenticate towards the RS (this could coincide with the + - Authenticate towards the RS (this could coincide with the proof of possession process). - + Transmit the token as specified by the AS (default is to the + - Transmit the token as specified by the AS (default is to the authz-info endpoint, alternative options are specified by profiles). - + Perform the proof-of-possession procedure as specified by + - Perform the proof-of-possession procedure as specified by the profile in use (this may already have been taken care of through the authentication procedure). * Process the RS response (see step (F) of Figure 1) of the RS. - Resource Server - * Expose a way to submit access tokens. By default this is the authz-info endpoint. * Process an access token. - - + Verify the token is from a recognized AS. - + Check the token's integrity. - + Verify that the token applies to this RS. - + Check that the token has not expired (if the token provides + - Verify the token is from a recognized AS. + - Check the token's integrity. + - Verify that the token applies to this RS. + - Check that the token has not expired (if the token provides expiration information). - + Store the token so that it can be retrieved in the context + - Store the token so that it can be retrieved in the context of a matching request. - Note: The order proposed here is not normative, any process that arrives at an equivalent result can be used. A noteworthy consideration is whether one can use cheap operations early on to quickly discard non-applicable or invalid tokens, before performing expensive cryptographic operations (e.g. doing an expiration check before verifying a signature). - * Process a request. - - + Set up communication security with the client. - + Authenticate the client. - + Match the client against existing tokens. - + Check that tokens belonging to the client actually authorize + - Set up communication security with the client. + - Authenticate the client. + - Match the client against existing tokens. + - Check that tokens belonging to the client actually authorize the requested action. - + Optionally: Check that the matching tokens are still valid, + - Optionally: Check that the matching tokens are still valid, using introspection (if this is possible.) * Send a response following the agreed upon communication security mechanism(s). * Safely store credentials such as raw public keys for authentication or proof-of-possession keys linked to access tokens. Appendix C. Requirements on Profiles This section lists the requirements on profiles of this framework, for the convenience of profile designers. - o Optionally define new methods for the client to discover the + * Optionally define new methods for the client to discover the necessary permissions and AS for accessing a resource, different from the one proposed in Section 5.1. Section 4 - o Optionally specify new grant types. Section 5.4 - o Optionally define the use of client certificates as client + * Optionally specify new grant types. Section 5.4 + * Optionally define the use of client certificates as client credential type. Section 5.5 - - o Specify the communication protocol the client and RS the must use + * Specify the communication protocol the client and RS the must use (e.g., CoAP). Section 5 and Section 5.8.4.3 - o Specify the security protocol the client and RS must use to + * Specify the security protocol the client and RS must use to protect their communication (e.g., OSCORE or DTLS). This must provide encryption, integrity and replay protection. Section 5.8.4.3 - o Specify how the client and the RS mutually authenticate. + * Specify how the client and the RS mutually authenticate. Section 4 - o Specify the proof-of-possession protocol(s) and how to select one, + * Specify the proof-of-possession protocol(s) and how to select one, if several are available. Also specify which key types (e.g., symmetric/asymmetric) are supported by a specific proof-of- possession protocol. Section 5.8.4.2 - o Specify a unique ace_profile identifier. Section 5.8.4.3 - o If introspection is supported: Specify the communication and + * Specify a unique ace_profile identifier. Section 5.8.4.3 + * If introspection is supported: Specify the communication and security protocol for introspection. Section 5.9 - o Specify the communication and security protocol for interactions + * Specify the communication and security protocol for interactions between client and AS. This must provide encryption, integrity protection, replay protection and a binding between requests and responses. Section 5 and Section 5.8 - o Specify how/if the authz-info endpoint is protected, including how + * Specify how/if the authz-info endpoint is protected, including how error responses are protected. Section 5.10.1 - o Optionally define other methods of token transport than the authz- + * Optionally define other methods of token transport than the authz- info endpoint. Section 5.10.1 Appendix D. Assumptions on AS Knowledge about C and RS This section lists the assumptions on what an AS should know about a client and an RS in order to be able to respond to requests to the token and introspection endpoints. How this information is established is out of scope for this document. - o The identifier of the client or RS. - o The profiles that the client or RS supports. - o The scopes that the RS supports. - o The audiences that the RS identifies with. - o The key types (e.g., pre-shared symmetric key, raw public key, key + * The identifier of the client or RS. + * The profiles that the client or RS supports. + * The scopes that the RS supports. + * The audiences that the RS identifies with. + * The key types (e.g., pre-shared symmetric key, raw public key, key length, other key parameters) that the client or RS supports. - o The types of access tokens the RS supports (e.g., CWT). - o If the RS supports CWTs, the COSE parameters for the crypto + * The types of access tokens the RS supports (e.g., CWT). + * If the RS supports CWTs, the COSE parameters for the crypto wrapper (e.g., algorithm, key-wrap algorithm, key-length) that the RS supports. - o The expiration time for access tokens issued to this RS (unless + + * The expiration time for access tokens issued to this RS (unless the RS accepts a default time chosen by the AS). - o The symmetric key shared between client and AS (if any). - o The symmetric key shared between RS and AS (if any). - o The raw public key of the client or RS (if any). - o Whether the RS has synchronized time (and thus is able to use the + * The symmetric key shared between client and AS (if any). + * The symmetric key shared between RS and AS (if any). + * The raw public key of the client or RS (if any). + * Whether the RS has synchronized time (and thus is able to use the 'exp' claim) or not. Appendix E. Differences to OAuth 2.0 This document adapts OAuth 2.0 to be suitable for constrained environments. This sections lists the main differences from the normative requirements of OAuth 2.0. - o Use of TLS -- OAuth 2.0 requires the use of TLS both to protect + * Use of TLS -- OAuth 2.0 requires the use of TLS both to protect the communication between AS and client when requesting an access token; between client and RS when accessing a resource and between AS and RS if introspection is used. This framework requires similar security properties, but does not require that they be realized with TLS. See Section 5. - o Cardinality of "grant_type" parameter -- In client-to-AS requests + * Cardinality of "grant_type" parameter -- In client-to-AS requests using OAuth 2.0, the "grant_type" parameter is required (per [RFC6749]). In this framework, this parameter is optional. See Section 5.8.1. - o Encoding of "scope" parameter -- In client-to-AS requests using + * Encoding of "scope" parameter -- In client-to-AS requests using OAuth 2.0, the "scope" parameter is string encoded (per [RFC6749]). In this framework, this parameter may also be encoded as a byte string. See Section 5.8.1. - o Cardinality of "token_type" parameter -- in AS-to-client responses + * Cardinality of "token_type" parameter -- in AS-to-client responses using OAuth 2.0, the token_type parameter is required (per [RFC6749]). In this framework, this parameter is optional. See Section 5.8.2. - o Access token retention -- in OAuth 2.0, the access token may be + * Access token retention -- in OAuth 2.0, the access token may be sent with every request to the RS. The exact use of access tokens depends on the semantics of the application and the session management concept it uses. In this framework, the RS must be able to store these tokens for later use. See Section 5.10.1. Appendix F. Deployment Examples There is a large variety of IoT deployments, as is indicated in Appendix A, and this section highlights a few common variants. This section is not normative but illustrates how the framework can be @@ -3762,45 +3759,45 @@ | PUT | Uri-Path: "state" | | Payload: | | F: |<--------+ Header: 2.04 Changed | 2.04 | Payload: | | Figure 26: Resource request and response protected by OSCORE Authors' Addresses + Ludwig Seitz Combitech - Djaeknegatan 31 - Malmoe 211 35 + Djäknegatan 31 + SE-211 35 Malmö Sweden Email: ludwig.seitz@combitech.com Goeran Selander Ericsson Faroegatan 6 - Kista 164 80 + SE-164 80 Kista Sweden Email: goran.selander@ericsson.com Erik Wahlstroem Sweden Email: erik@wahlstromstekniska.se Samuel Erdtman Spotify AB Birger Jarlsgatan 61, 4tr - Stockholm 113 56 + SE-113 56 Stockholm Sweden - Email: erdtman@spotify.com Hannes Tschofenig Arm Ltd. - Absam 6067 + 6067 Absam Austria Email: Hannes.Tschofenig@arm.com