--- 1/draft-ietf-ace-oauth-authz-35.txt 2020-11-17 00:13:23.254432614 -0800 +++ 2/draft-ietf-ace-oauth-authz-36.txt 2020-11-17 00:13:23.466437975 -0800 @@ -1,26 +1,26 @@ ACE Working Group L. Seitz Internet-Draft Combitech Intended status: Standards Track G. Selander -Expires: December 26, 2020 Ericsson +Expires: May 21, 2021 Ericsson E. Wahlstroem S. Erdtman Spotify AB H. Tschofenig Arm Ltd. - June 24, 2020 + November 17, 2020 Authentication and Authorization for Constrained Environments (ACE) using the OAuth 2.0 Framework (ACE-OAuth) - draft-ietf-ace-oauth-authz-35 + draft-ietf-ace-oauth-authz-36 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,21 +34,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on December 26, 2020. + This Internet-Draft will expire on May 21, 2021. Copyright Notice Copyright (c) 2020 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 @@ -61,88 +61,88 @@ 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.1. Discovering Authorization Servers . . . . . . . . . . . . 16 - 5.1.1. Unauthorized Resource Request Message . . . . . . . . 16 - 5.1.2. AS Request Creation Hints . . . . . . . . . . . . . . 17 - 5.1.2.1. The Client-Nonce Parameter . . . . . . . . . . . 19 - 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 20 - 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 20 - 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 21 - 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 21 - 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 21 - 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 22 - 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 25 - 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 27 - 5.6.4. Request and Response Parameters . . . . . . . . . . . 28 - 5.6.4.1. Grant Type . . . . . . . . . . . . . . . . . . . 28 - 5.6.4.2. Token Type . . . . . . . . . . . . . . . . . . . 29 - 5.6.4.3. Profile . . . . . . . . . . . . . . . . . . . . . 29 - 5.6.4.4. Client-Nonce . . . . . . . . . . . . . . . . . . 30 - 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 30 - 5.7. The Introspection Endpoint . . . . . . . . . . . . . . . 31 - 5.7.1. Introspection Request . . . . . . . . . . . . . . . . 32 - 5.7.2. Introspection Response . . . . . . . . . . . . . . . 33 - 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 34 - 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 35 - 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 35 - 5.8.1. The Authorization Information Endpoint . . . . . . . 36 - 5.8.1.1. Verifying an Access Token . . . . . . . . . . . . 37 - 5.8.1.2. Protecting the Authorization Information + 5.2. Unauthorized Resource Request Message . . . . . . . . . . 17 + 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.6. AS Authentication . . . . . . . . . . . . . . . . . . . . 21 + 5.7. The Authorization Endpoint . . . . . . . . . . . . . . . 21 + 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.1. The Authorization Information Endpoint . . . . . . . 36 + 5.10.1.1. Verifying an Access Token . . . . . . . . . . . 37 + 5.10.1.2. Protecting the Authorization Information Endpoint . . . . . . . . . . . . . . . . . . . . 39 - 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 39 - 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 40 - 5.8.4. Key Expiration . . . . . . . . . . . . . . . . . . . 41 + 5.10.2. Client Requests to the RS . . . . . . . . . . . . . 39 + 5.10.3. Token Expiration . . . . . . . . . . . . . . . . . . 40 + 5.10.4. Key Expiration . . . . . . . . . . . . . . . . . . . 41 6. Security Considerations . . . . . . . . . . . . . . . . . . . 42 6.1. Protecting Tokens . . . . . . . . . . . . . . . . . . . . 42 6.2. Communication Security . . . . . . . . . . . . . . . . . 43 6.3. Long-Term Credentials . . . . . . . . . . . . . . . . . . 44 6.4. Unprotected AS Request Creation Hints . . . . . . . . . . 44 6.5. Minimal security requirements for communication . 45 6.6. Token Freshness and Expiration . . . . . . . . . . . . . 46 - 6.7. Combining profiles . . . . . . . . . . . . . . . . . . . 47 + 6.7. Combining profiles . . . . . . . . . . . . . . . . . . . 46 6.8. Unprotected Information . . . . . . . . . . . . . . . . . 47 - 6.9. Identifying audiences . . . . . . . . . . . . . . . . . . 48 + 6.9. Identifying audiences . . . . . . . . . . . . . . . . . . 47 6.10. Denial of service against or with Introspection . . 48 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.2. CoRE Resource Type registry . . . . . . . . . . . . . . . 50 8.3. OAuth Extensions Error Registration . . . . . . . . . . . 51 8.4. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 51 - 8.5. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 52 + 8.5. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 51 8.6. OAuth Access Token Types . . . . . . . . . . . . . . . . 52 8.7. OAuth Access Token Type CBOR Mappings . . . . . . . . . . 52 8.7.1. Initial Registry Contents . . . . . . . . . . . . . . 53 8.8. ACE Profile Registry . . . . . . . . . . . . . . . . . . 53 - 8.9. OAuth Parameter Registration . . . . . . . . . . . . . . 54 + 8.9. OAuth Parameter Registration . . . . . . . . . . . . . . 53 8.10. OAuth Parameters CBOR Mappings Registry . . . . . . . . . 54 8.11. OAuth Introspection Response Parameter Registration . . . 54 8.12. OAuth Token Introspection Response CBOR Mappings Registry 55 8.13. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 55 8.14. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 56 8.15. Media Type Registrations . . . . . . . . . . . . . . . . 57 - 8.16. CoAP Content-Format Registry . . . . . . . . . . . . . . 58 + 8.16. CoAP Content-Format Registry . . . . . . . . . . . . . . 57 8.17. Expert Review Instructions . . . . . . . . . . . . . . . 58 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 59 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 59 10.1. Normative References . . . . . . . . . . . . . . . . . . 59 10.2. Informative References . . . . . . . . . . . . . . . . . 62 - Appendix A. Design Justification . . . . . . . . . . . . . . . . 65 + Appendix A. Design Justification . . . . . . . . . . . . . . . . 64 Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 68 - Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 71 + Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 70 Appendix D. Assumptions on AS knowledge about C and RS . . . . . 71 Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 72 E.1. Local Token Validation . . . . . . . . . . . . . . . . . 72 E.2. Introspection Aided Token Validation . . . . . . . . . . 76 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 80 F.1. Version -21 to 22 . . . . . . . . . . . . . . . . . . . . 81 F.2. Version -20 to 21 . . . . . . . . . . . . . . . . . . . . 81 F.3. Version -19 to 20 . . . . . . . . . . . . . . . . . . . . 81 F.4. Version -18 to -19 . . . . . . . . . . . . . . . . . . . 81 F.5. Version -17 to -18 . . . . . . . . . . . . . . . . . . . 81 @@ -227,21 +227,21 @@ Since exchanges in this specification are described as RESTful protocol interactions, HTTP [RFC7231] offers useful terminology. Terminology for entities in the architecture is defined in OAuth 2.0 [RFC6749] such as client (C), resource server (RS), and authorization server (AS). Note that the term "endpoint" is used here following its OAuth definition, which is to denote resources such as token and - introspection at the AS and authz-info at the RS (see Section 5.8.1 + introspection at the AS and authz-info at the RS (see Section 5.10.1 for a definition of the authz-info endpoint). The CoAP [RFC7252] definition, which is "An entity participating in the CoAP protocol" is not used in this specification. The specifications in this document is called the "framework" or "ACE framework". When referring to "profiles of this framework" it refers to additional specifications that define the use of this specification with concrete transport and communication security protocols (e.g., CoAP over DTLS). @@ -595,21 +595,21 @@ Access Token Response (B): If the AS successfully processes the request from the client, it returns an access token and optionally a refresh token (note that only certain grant types support refresh tokens). It can also return additional parameters, referred to as "Access Information". In addition to the response parameters defined by OAuth 2.0 and the PoP access token extension, this framework defines parameters that can be used to inform the client about capabilities of the RS, e.g. the profiles the RS supports. More information about - these parameters can be found in Section 5.6.4. + these parameters can be found in Section 5.8.4. Resource Request (C): The client interacts with the RS to request access to the protected resource and provides the access token. The protocol to use between the client and the RS is not restricted to CoAP. HTTP, HTTP/2, QUIC, MQTT, Bluetooth Low Energy, etc., are also viable candidates. Depending on the device limitations and the selected protocol, this exchange may be split up into two parts: @@ -627,21 +627,21 @@ obtained in the access token or the Access Information. The RS verifies that the token is integrity protected and originated by the AS. It then compares the claims contained in the access token with the resource request. If the RS is online, validation can be handed over to the AS using token introspection (see messages D and E) over HTTP or CoAP. Token Introspection Request (D): A resource server may be configured to introspect the access token by including it in a request to the introspection endpoint at that - AS. Token introspection over CoAP is defined in Section 5.7 and + AS. Token introspection over CoAP is defined in Section 5.9 and for HTTP in [RFC7662]. Note that token introspection is an optional step and can be omitted if the token is self-contained and the resource server is prepared to perform the token validation on its own. Token Introspection Response (E): The AS validates the token and returns the most recent parameters, such as scope, audience, validity etc. associated with it back to the RS. The RS then uses the received parameters to process the @@ -716,30 +716,33 @@ ace+cbor'. If CoAP is used for communication, the Content-Format MUST be abbreviated with the ID: 19 (see Section 8.16). The OAuth 2.0 AS uses a JSON structure in the payload of its responses both to client and RS. If CoAP is used, it is REQUIRED to use CBOR [RFC7049] instead of JSON. Depending on the profile, the CBOR payload MAY be enclosed in a non-CBOR cryptographic wrapper. 5.1. Discovering Authorization Servers - In order to determine the AS in charge of a resource hosted at the - RS, C MAY send an initial Unauthorized Resource Request message to - RS. RS then denies the request and sends the address of its AS back - to C. + C must discover the AS in charge of RS to determine where to request + the access token. To do so, C must 1. find out the AS URI to which + the token request message must be sent and 2. MUST validate that the + AS with this URI is authorized to provide access tokens for this RS. - Instead of the initial Unauthorized Resource Request message, other - discovery methods may be used, or the client may be pre-provisioned - with an RS-to-AS mapping. + In order to determine the AS URI, C MAY send an initial Unauthorized + Resource Request message to RS. RS then denies the request and sends + the address of its AS back to C (see Section 5.2). How C validates + the AS authorization is not in scope for this document. C may, e.g., + ask it's owner if this AS is authorized for this RS. C may also use + a mechanism that addresses both problems at once. -5.1.1. Unauthorized Resource Request Message +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 unprotected channel. o The RS has no valid access token for the sender of the request @@ -747,54 +750,53 @@ o 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.8.1). + Section 5.10.1). Unauthorized Resource Request messages MUST be denied with an "unauthorized_client" error response. In this response, the Resource Server SHOULD provide proper AS Request Creation Hints to enable the Client to request an access token from RS's AS as described in - Section 5.1.2. + Section 5.3. The handling of all client requests (including unauthorized ones) by - the RS is described in Section 5.8.2. + the RS is described in Section 5.10.2. -5.1.2. AS Request Creation Hints +5.3. AS Request Creation Hints The AS Request Creation Hints message is sent by an 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 acquire - a valid access token. The AS Request Creation Hints message is a - CBOR map, with a MANDATORY element "AS" specifying an absolute URI - (see Section 4.3 of [RFC3986]) that identifies the appropriate AS for - the RS. + 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 + 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 containing a suggested audience that the client should request at 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 "cnonce" element containing a client-nonce. See - Section 5.1.2.1. + o A "cnonce" element containing a client-nonce. See Section 5.3.1. o A "scope" element containing the suggested scope that the client should request towards the AS. Figure 2 summarizes the parameters that may be part of the AS Request Creation Hints. /-----------+----------+---------------------\ | Name | CBOR Key | Value Type | |-----------+----------+---------------------| @@ -830,21 +832,21 @@ Figure 3: AS Request Creation Hints payload example In the example above, the response parameter "AS" points the receiver of this message to the URI "coaps://as.example.com/token" to request access tokens. The RS sending this response (i.e., RS) uses an internal clock that is only loosely synchronized with the clock of the AS. Therefore it can not reliably verify the expiration time of access tokens it receives. To ensure a certain level of access token freshness nevetheless, the RS has included a "cnonce" parameter (see - Section 5.1.2.1) in the response. + Section 5.3.1) in the response. Figure 4 illustrates the mandatory to use binary encoding of the message payload shown in Figure 3. a4 # map(4) 01 # unsigned(1) (=AS) 78 1c # text(28) 636f6170733a2f2f61732e657861 6d706c652e636f6d2f746f6b656e # "coaps://as.example.com/token" 05 # unsigned(5) (=audience) @@ -853,57 +855,57 @@ 6d706c652e636f6d # "coaps://rs.example.com" 09 # unsigned(9) (=scope) 66 # text(6) 7254656d7043 # "rTempC" 18 27 # unsigned(39) (=cnonce) 45 # bytes(5) e0a156bb3f # Figure 4: AS Request Creation Hints example encoded in CBOR -5.1.2.1. The Client-Nonce Parameter +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 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 Hints message MUST include this in the parameters when requesting an access token at the AS, using the "cnonce" parameter from - Section 5.6.4.4. + Section 5.8.4.4. o If an AS grants an access token request containing a "cnonce" parameter, it MUST include this value in the access token, using - the "cnonce" claim specified in Section 5.8. + the "cnonce" claim specified in Section 5.10. o 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.2. Authorization Grants +5.4. Authorization Grants To request an access token, the client obtains authorization from the resource owner or uses its client credentials as a grant. The authorization is expressed in the form of an authorization grant. The OAuth framework [RFC6749] defines four grant types. The grant types can be split up into two groups, those granted on behalf of the resource owner (password, authorization code, implicit) and those for the client (client credentials). Further grant types have been added later, such as [RFC7521] defining an assertion-based authorization @@ -915,60 +917,60 @@ resource owner, but does not have any display or has very limited interaction possibilities, it is recommended to use the device code grant defined in [RFC8628]. In cases where the client acts autonomously the client credentials grant is recommended. For details on the different grant types, see section 1.3 of [RFC6749]. The OAuth 2.0 framework provides an extension mechanism for defining additional grant types, so profiles of this framework MAY define additional grant types, if needed. -5.3. Client Credentials +5.5. Client Credentials Authentication of the client is mandatory independent of the grant type when requesting an access token from the token endpoint. In the case of the client credentials grant type, the authentication and grant coincide. Client registration and provisioning of client credentials to the client is out of scope for this specification. The OAuth framework defines one client credential type in section 2.3.1 of [RFC6749]: client id and client secret. [I-D.erdtman-ace-rpcc] adds raw-public-key and pre-shared-key to the client credentials types. Profiles of this framework MAY extend with an additional client credentials type using client certificates. -5.4. AS Authentication +5.6. AS Authentication The client credential grant does not, by default, authenticate the AS that the client connects to. In classic OAuth, the AS is authenticated with a TLS server certificate. Profiles of this framework MUST specify how clients authenticate the AS and how communication security is implemented. By default, server side TLS certificates, as defined by OAuth 2.0, are required. -5.5. The Authorization Endpoint +5.7. The Authorization Endpoint The OAuth 2.0 authorization endpoint is used to interact with the resource owner and obtain an authorization grant, in certain grant flows. The primary use case for the ACE-OAuth framework is for machine-to-machine interactions that do not involve the resource owner in the authorization flow; therefore, this endpoint is out of scope here. Future profiles may define constrained adaptation mechanisms for this endpoint as well. Non-constrained clients interacting with constrained resource servers can use the specification in section 3.1 of [RFC6749] and the attack countermeasures suggested in section 4.2 of [RFC6819]. -5.6. The Token Endpoint +5.8. The Token Endpoint In standard OAuth 2.0, the AS provides the token endpoint for submitting access token requests. This framework extends the functionality of the token endpoint, giving the AS the possibility to help the client and RS to establish shared keys or to exchange their public keys. Furthermore, this framework defines encodings using CBOR, as a substitute for JSON. The endpoint may, however, be exposed over HTTPS as in classical OAuth or even other transports. A profile MUST define the details of @@ -989,64 +990,64 @@ The default name of this endpoint in an url-path is '/token', however implementations are not required to use this name and can define their own instead. The figures of this section use CBOR diagnostic notation without the integer abbreviations for the parameters or their values for illustrative purposes. Note that implementations MUST use the integer abbreviations and the binary CBOR encoding, if the CBOR encoding is used. -5.6.1. Client-to-AS Request +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 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 access token bound to a specific audience. - o The "cnonce" parameter defined in Section 5.6.4.4 is REQUIRED if + o 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.1.2 + message Section 5.3 o The "scope" parameter MAY be encoded as a byte string instead of the string encoding specified in section 3.3 of [RFC6749], in order allow compact encoding of complex scopes. The syntax of such a binary encoding is explicitly not specified here and left to profiles or applications, specifically note 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 to indicate that it wants the AS to include the "ace_profile" - parameter in the response. See Section 5.6.4.3. + parameter in the response. See Section 5.8.4.3. o A client MUST be able to use the parameters from [I-D.ietf-ace-oauth-params] in an access token request to the token endpoint and the AS MUST be able to process these additional parameters. 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]. - If CBOR is used then these parameters MUST be encoded as a CBOR map. + If CBOR is used then these parameters MUST be provided as a CBOR map. When HTTP is used as a transport then the client makes a request to the token endpoint by sending the parameters using the "application/ x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body, as defined in section 3.2 of [RFC6749]. The following examples illustrate different types of requests for proof-of-possession tokens. Figure 5 shows a request for a token with a symmetric proof-of- @@ -1123,49 +1124,49 @@ reference. Refresh tokens are typically not stored as securely as proof-of- possession keys in requesting clients. Proof-of-possession based refresh token requests MUST NOT request different proof-of-possession keys or different audiences in token requests. Refresh token requests can only use to request access tokens bound to the same proof-of-possession key and the same audience as access tokens issued in the initial token request. -5.6.2. AS-to-Client Response +5.8.2. AS-to-Client Response If the access token request has been successfully verified by the AS and the client is authorized to obtain an access token corresponding to its access token request, the AS sends a response with the response code equivalent to the CoAP response code 2.01 (Created). If client request was invalid, or not authorized, the AS returns an - error response as described in Section 5.6.3. + error response as described in Section 5.8.3. Note that the AS decides which token type and profile to use when issuing a successful response. It is assumed that the AS has prior knowledge of the capabilities of the client and the RS (see Appendix D). This prior knowledge may, for example, be set by the use of a dynamic client registration protocol exchange [RFC7591]. If the client has requested a specific proof-of-possession key using the "req_cnf" parameter from [I-D.ietf-ace-oauth-params], this may also influence which profile the AS selects, as it needs to support the use of the key type requested the client. The content of the successful reply is the Access Information. When using CBOR payloads, the content MUST be encoded as a CBOR map, containing parameters as specified in Section 5.1 of [RFC6749], with the following additions and changes: ace_profile: OPTIONAL unless the request included an empty ace_profile parameter in which case it is MANDATORY. This indicates the profile that the client MUST use towards the RS. See - Section 5.6.4.3 for the formatting of this parameter. If this + Section 5.8.4.3 for the formatting of this parameter. If this parameter is absent, the AS assumes that the client implicitly knows which profile to use towards the RS. token_type: This parameter is OPTIONAL, as opposed to 'required' in [RFC6749]. By default implementations of this framework SHOULD assume that the token_type is "PoP". If a specific use case requires another token_type (e.g., "Bearer") to be used then this parameter is REQUIRED. @@ -1217,21 +1218,21 @@ "kty" : "Symmetric", "kid" : b64'39Gqlw', "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' } } } Figure 9: Example AS response with an access token bound to a symmetric key. -5.6.3. Error Response +5.8.3. Error Response The error responses for CoAP-based interactions with the AS are generally equivalent to the ones for HTTP-based interactions as defined in Section 5.2 of [RFC6749], with the following exceptions: o When using CBOR the raw payload before being processed by the communication security protocol MUST be encoded as a CBOR map. o A response code equivalent to the CoAP code 4.00 (Bad Request) MUST be used for all error responses, except for invalid_client @@ -1274,63 +1275,63 @@ response code equivalent to the CoAP code 4.00 (Bad Request) including the error code "unsupported_pop_key" defined in Figure 10. o 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" defined in Figure 10. -5.6.4. Request and Response Parameters +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 common parameter values. -5.6.4.1. Grant Type +5.8.4.1. Grant Type The abbreviations specified in the registry defined in Section 8.5 MUST be used in CBOR encodings instead of the string values defined in [RFC6749], if CBOR payloads are used. /--------------------+------------+------------------------\ | Name | CBOR Value | Original Specification | |--------------------+------------+------------------------| | password | 0 | [RFC6749] | | authorization_code | 1 | [RFC6749] | | client_credentials | 2 | [RFC6749] | | refresh_token | 3 | [RFC6749] | \--------------------+------------+------------------------/ Figure 11: CBOR abbreviations for common grant types -5.6.4.2. Token Type +5.8.4.2. Token Type The "token_type" parameter, defined in section 5.1 of [RFC6749], allows the AS to indicate to the client which type of access token it is receiving (e.g., a bearer token). This document registers the new value "PoP" for the OAuth Access Token Types registry, specifying a proof-of-possession token. How the proof-of-possession by the client to the RS is performed MUST be specified by the profiles. The values in the "token_type" parameter MUST use the CBOR abbreviations defined in the registry specified by Section 8.7, if a CBOR encoding is used. In this framework the "pop" value for the "token_type" parameter is the default. The AS may, however, provide a different value. -5.6.4.3. Profile +5.8.4.3. Profile Profiles of this framework MUST define the communication protocol and the communication security protocol between the client and the RS. The security protocol MUST provide encryption, integrity and replay protection. It MUST also provide a binding between requests and responses. Furthermore profiles MUST define a list of allowed proof- of-possession methods, if they support proof-of-possession tokens. A profile MUST specify an identifier that MUST be used to uniquely identify itself in the "ace_profile" parameter. The textual @@ -1342,30 +1343,30 @@ Profiles MAY define additional parameters for both the token request and the Access Information in the access token response in order to support negotiation or signaling of profile specific parameters. Clients that want the AS to provide them with the "ace_profile" parameter in the access token response can indicate that by sending a ace_profile parameter with a null value (for CBOR-based interactions) or an empty string (for JSON based interactions) in the access token request. -5.6.4.4. Client-Nonce +5.8.4.4. Client-Nonce This parameter MUST be sent from the client to the AS, if it previously received a "cnonce" parameter in the AS Request Creation - Hints Section 5.1.2. The parameter is encoded as a byte string for + Hints Section 5.3. The parameter is encoded as a byte string for CBOR-based interactions, and as a string (Base64 encoded binary) for JSON-based interactions. It MUST copy the value from the cnonce parameter in the AS Request Creation Hints. -5.6.5. Mapping Parameters to CBOR +5.8.5. Mapping Parameters to CBOR If CBOR encoding is used, all OAuth parameters in access token requests and responses MUST be mapped to CBOR types as specified in the registry defined by Section 8.10, using the given integer abbreviation for the map keys. Note that we have aligned the abbreviations corresponding to claims with the abbreviations defined in [RFC8392]. Note also that abbreviations from -24 to 23 have a 1 byte encoding @@ -1379,35 +1380,35 @@ | 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 | unsigned integer | + | error | 30 | integer | | error_description | 31 | text string | | error_uri | 32 | text string | | grant_type | 33 | unsigned integer | - | token_type | 34 | unsigned integer | + | token_type | 34 | integer | | username | 35 | text string | | password | 36 | text string | | refresh_token | 37 | byte string | - | ace_profile | 38 | unsigned integer | + | ace_profile | 38 | integer | | cnonce | 39 | byte string | \-------------------+----------+---------------------/ Figure 12: CBOR mappings used in token requests and responses -5.7. The Introspection Endpoint +5.9. The Introspection Endpoint Token introspection [RFC7662] can be OPTIONALLY provided by the AS, and is then used by the RS and potentially the client to query the AS for metadata about a given token, e.g., validity or scope. Analogous to the protocol defined in [RFC7662] for HTTP and JSON, this section defines adaptations to more constrained environments using CBOR and leaving the choice of the application protocol to the profile. Communication between the requesting entity and the introspection endpoint at the AS MUST be integrity protected and encrypted. The @@ -1423,21 +1424,21 @@ however implementations are not required to use this name and can define their own instead. The figures of this section uses CBOR diagnostic notation without the integer abbreviations for the parameters or their values for better readability. Note that supporting introspection is OPTIONAL for implementations of this framework. -5.7.1. Introspection Request +5.9.1. Introspection Request The requesting entity sends a POST request to the introspection endpoint at the AS. The profile MUST specify how the communication is protected. If CBOR is used, the payload MUST be encoded as a CBOR map with a "token" entry containing the access token. Further optional parameters representing additional context that is known by the requesting entity to aid the AS in its response MAY be included. For CoAP-based interaction, all messages MUST use the content type "application/ace+cbor", while for HTTP-based interactions the @@ -1462,43 +1463,43 @@ Figure 13: Example introspection request. { "token" : b64'7gj0dXJQ43U', "token_type_hint" : "PoP" } Figure 14: Decoded payload. -5.7.2. Introspection Response +5.9.2. Introspection Response If the introspection request is authorized and successfully processed, the AS sends a response with the response code equivalent to the CoAP code 2.01 (Created). If the introspection request was invalid, not authorized or couldn't be processed the AS returns an - error response as described in Section 5.7.3. + error response as described in Section 5.9.3. In a successful response, the AS encodes the response parameters in a map including with the same required and optional parameters as in Section 2.2 of [RFC7662] with the following addition: ace_profile OPTIONAL. This indicates the profile that the RS MUST - use with the client. See Section 5.6.4.3 for more details on the + use with the client. See Section 5.8.4.3 for more details on the formatting of this parameter. 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.1.2 and Section 5.6.4.4. + Hints. See Section 5.3 and Section 5.8.4.4. exi OPTIONAL. The "expires-in" claim associated to this access - token. See Section 5.8.3. + 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]. Header: Created (Code=2.01) @@ -1512,21 +1513,21 @@ "COSE_Key" : { "kty" : "Symmetric", "kid" : b64'39Gqlw', "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' } } } Figure 15: Example introspection response. -5.7.3. Error 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 CBOR is used the payload MUST be encoded as a CBOR map and the Content-Format "application/ace+cbor" MUST be used. o If the credentials used by the requesting entity (usually the RS) @@ -1544,101 +1545,101 @@ o 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.7.4. Mapping Introspection parameters to CBOR +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.6.5. + 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 | unsigned integer | + | error | 30 | integer | | error_description | 31 | text string | | error_uri | 32 | text string | | token_type_hint | 33 | text string | - | token_type | 34 | text string | + | token_type | 34 | integer | | username | 35 | text string | - | ace_profile | 38 | unsigned integer | + | ace_profile | 38 | integer | | cnonce | 39 | byte string | | exi | 40 | unsigned integer | \-------------------+----------+-------------------------/ Figure 16: CBOR Mappings to Token Introspection Parameters. -5.8. The Access Token +5.10. The Access Token This framework RECOMMENDS the use of CBOR web token (CWT) as specified in [RFC8392]. In order to facilitate offline processing of access tokens, this 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 MAY be used. The syntax of such an encoding is explicitly not specified here and left to profiles or applications, specifically note that a binary encoded scope does not necessarily use the space character '0x20' to delimit scope-tokens. If the AS needs to convey a hint to the RS about which profile it should use to communicate with the client, the AS MAY include an "ace_profile" claim in the access token, with the same syntax and - semantics as defined in Section 5.6.4.3. + semantics as defined in Section 5.8.4.3. If the client submitted a client-nonce parameter in the access token - request Section 5.6.4.4, the AS MUST include the value of this + request Section 5.8.4.4, the AS MUST include the value of this parameter in the "cnonce" claim specified here. The "cnonce" claim uses binary encoding. -5.8.1. The Authorization Information Endpoint +5.10.1. The Authorization Information Endpoint The access token, containing authorization information and information about the proof-of-possession method used by the client, needs to be transported to the RS so that the RS can authenticate and authorize the client request. This section defines a method for transporting the access token to the RS using a RESTful protocol such as CoAP. Profiles of this framework MAY define other methods for token transport. The method consists of an authz-info endpoint, implemented by the RS. A client using this method MUST make a POST request to the authz-info endpoint at the RS with the access token in the payload. The RS receiving the token MUST verify the validity of the token. If the token is valid, the RS MUST respond to the POST request with 2.01 - (Created). Section Section 5.8.1.1 outlines how an RS MUST proceed + (Created). Section Section 5.10.1.1 outlines how an RS MUST proceed to verify the validity of an access token. The RS MUST be prepared to store at least one access token for future use. This is a difference to how access tokens are handled in OAuth 2.0, where the access token is typically sent along with each request, and therefore not stored at the RS. This specification RECOMMENDS that an RS stores only one token per proof-of-possession key, meaning that an additional token linked to the same key will overwrite any existing token at the RS. The reason @@ -1660,21 +1661,21 @@ Profiles MUST specify whether the authz-info endpoint is protected, including whether error responses from this endpoint are protected. Note that since the token contains information that allow the client and the RS to establish a security context in the first place, mutual authentication may not be possible at this point. The default name of this endpoint in an url-path is '/authz-info', however implementations are not required to use this name and can define their own instead. -5.8.1.1. Verifying an Access Token +5.10.1.1. Verifying an Access Token When an RS receives an access token, it MUST verify it before storing it. The details of token verification depends on various aspects, including the token encoding, the type of token, the security protection applied to the token, and the claims. The token encoding matters since the security wrapper differs between the token encodings. For example, a CWT token uses COSE while a JWT token uses JOSE. The type of token also has an influence on the verification procedure since tokens may be self-contained whereby token verification may happen locally at the RS while a token-by-reference @@ -1687,21 +1688,21 @@ of the token first, as specified by the respective token format. For CWT the description can be found in [RFC8392] and for JWT the relevant specification is [RFC7519]. This MUST include a verification that security protection (and thus the token) was 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.7. + Section 5.9. Errors may happen during this initial processing stage: o If token or claim verification fails, 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 and, in case of an interaction via the authz-info endpoint, return @@ -1748,43 +1749,43 @@ Also note that profiles of this framework may define access token transport mechanisms that do not allow for error responses. Therefore the error messages specified here only apply if the token was sent to the authz-info endpoint. When sending error responses, the RS MAY use the error codes from Section 3.1 of [RFC6750], to provide additional details to the client. -5.8.1.2. Protecting the Authorization Information Endpoint +5.10.1.2. Protecting the Authorization Information Endpoint As this framework can be used in RESTful environments, it is important to make sure that attackers cannot perform unauthorized requests on the authz-info endpoints, other than submitting access tokens. Specifically it SHOULD NOT be possible to perform GET, DELETE or PUT on the authz-info endpoint and on it's children (if any). The POST method SHOULD NOT be allowed on children of the authz-info endpoint. The RS SHOULD implement rate limiting measures to mitigate attacks aiming to overload the processing capacity of the RS by repeatedly submitting tokens. For CoAP-based communication the RS could use the mechanisms from [RFC8516] to indicate that it is overloaded. -5.8.2. Client Requests to the RS +5.10.2. Client Requests to the RS Before sending a request to an RS, the client MUST verify that the keys used to protect this communication are still valid. See - Section 5.8.4 for details on how the client determines the validity + Section 5.10.4 for details on how the client determines the validity of the keys used. If an RS receives a request from a client, and the target resource requires authorization, the RS MUST first verify that it has an access token that authorizes this request, and that the client has performed the proof-of-possession binding that token to the request. The response code MUST be 4.01 (Unauthorized) in case the client has not performed the proof-of-possession, or if RS has no valid access token for the client. If RS has an access token for the client but @@ -1805,37 +1806,37 @@ Note: The RS MAY use introspection for timely validation of an access token, at the time when a request is presented. Note: Matching the claims of the access token (e.g., scope) to a specific request is application specific. If the request matches a valid token and the client has performed the proof-of-possession for that token, the RS continues to process the request as specified by the underlying application. -5.8.3. Token Expiration +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 "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 - introspection request as specified in Section 5.7. This requires + 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 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. For CBOR-based interaction this parameter is encoded as @@ -1863,21 +1864,21 @@ + 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. If a token that authorizes a long running request such as a CoAP Observe [RFC7641] expires, the RS MUST send an error response with the response code equivalent to the CoAP code 4.01 (Unauthorized) to the client and then terminate processing the long running request. -5.8.4. Key Expiration +5.10.4. Key Expiration The AS provides the client with key material that the RS uses. This can either be a common symmetric PoP-key, or an asymmetric key used by the RS to authenticate towards the client. Since there is currently no expiration metadata associated to those keys, the client has no way of knowing if these keys are still valid. This may lead to situations where the client sends requests containing sensitive 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 @@ -2008,41 +2009,31 @@ Operators also SHOULD have procedures for decommissioning devices, that include securely erasing credentials and other security critical material in the devices being decommissioned. 6.4. Unprotected AS Request Creation Hints Initially, no secure channel exists to protect the communication between C and RS. Thus, C cannot determine if the AS Request Creation Hints contained in an unprotected response from RS to an - unauthorized request (see Section 5.1.2) are authentic. It is - therefore advisable to provide C with a (possibly hard-coded) list of - trustworthy authorization servers, possibly including information - used to authenticate the AS, such as a public key or certificate - fingerprint. AS Request Creation Hints referring to a URI not listed - there would be ignored. - - A compromised RS may use the hints to trick a client into contacting - an AS that is not supposed to be in charge of that RS. Since this AS - must be in the hard-coded list of trusted AS no violation of - privileges and or exposure of credentials should happen, since a - trusted AS is expected to refuse requestes for which it is not - applicable and render a corresponding error response. However a - compromised RS may use this to perform a denial of service against a - specific AS, by redirecting a large number of client requests to that - AS. + unauthorized request (see Section 5.3) are authentic. C therefore + MUST determine if an AS is authorized to provide access tokens for a + certain RS. - A compromised client can be made to contact any AS, including - compromised ones. This should not affect the RS, since it is - supposed to keep track of which AS are trusted and have corresponding - credentials to verify the source of access tokens it receives. + A compromised RS may use the hints for attempting to trick a client + into contacting an AS that is not supposed to be in charge of that + RS. Therefore, C must not communicate with an AS if it cannot + determine that this AS has the authority to issue access tokens for + this RS. Otherwise, a compromised RS may use this to perform a + denial of service attack against a specific AS, by redirecting a + large number of client requests to that AS. 6.5. Minimal security requirements for communication This section summarizes the minimal requirements for the communication security of the different protocol interactions. C-AS All communication between the client and the Authorization Server MUST be encrypted, integrity and replay protected. Furthermore responses from the AS to the client MUST be bound to the client's request to avoid attacks where the attacker swaps the @@ -2086,21 +2077,21 @@ negotiation between C and RS, the client MUST have learned what profile the RS supports (e.g. from the AS or pre-configured) and initiate the communication accordingly. 6.6. Token Freshness and Expiration An RS that is offline faces the problem of clock drift. Since it cannot synchronize its clock with the AS, it may be tricked into accepting old access tokens that are no longer valid or have been compromised. In order to prevent this, an RS may use the nonce-based - mechanism defined in Section 5.1.2 to ensure freshness of an Access + mechanism defined in Section 5.3 to ensure freshness of an Access Token subsequently presented to this RS. Another problem with clock drift is that evaluating the standard token expiration claim "exp" can give unpredictable results. Acceptable ranges of clock drift are highly dependent on the concrete application. Important factors are how long access tokens are valid, and how critical timely expiration of access token is. The expiration mechanism implemented by the "exi" claim, based on the @@ -2147,21 +2138,21 @@ particular use cases, where this assessment does not apply, detailed error messages can be replaced by more generic ones. In some scenarios it may be possible to protect the communication with the authz-info endpoint (e.g. through DTLS with only server-side authentication). In cases where this is not possible this framework RECOMMENDS to use encrypted CWTs or tokens that are 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 + Section 5.2) 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, POST and PUT requests would reveal the whole payload of the intended operation. Since the client is not authenticated at the point when it is submitting an access token to the authz-info endpoint, attackers may be pretending to be a client and trying to trick an RS to use an obsolete profile that in turn specifies a vulnerable security mechanism via the authz-info endpoint. Such an attack would require a valid access token containing an "ace_profile" claim requesting the @@ -2198,21 +2189,21 @@ 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 inadvertently obtaining a token for the wrong RS. The correct values for "audience" can either be provisioned to the client as part of its configuration, 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. Note that the "audience" hint provided by the RS as part of the "AS Request Creation Hints" - Section 5.1.2 is not typically source authenticated and integrity + Section 5.3 is not typically source authenticated and integrity protected, and should therefore not be treated a trusted value. 6.10. 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 @@ -2259,28 +2250,32 @@ device or application running the client. This may be linkable to the identity of the person using the client (if there is a person and not a machine-to-machine interaction). Clients using asymmetric keys for proof-of-possession should be aware of the consequences of using the same key pair for proof-of- possession towards different RSs. A set of colluding RSs or an attacker able to obtain the access tokens will be able to link the requests, or even to determine the client's identity. - An unprotected response to an unauthorized request (see - Section 5.1.2) may disclose information about RS and/or its existing - relationship with C. It is advisable to include as little - information as possible in an unencrypted response. If means of - encrypting communication between C and RS already exist, more - detailed information may be included with an error response to - provide C with sufficient information to react on that particular - error. + An unprotected response to an unauthorized request (see Section 5.3) + may disclose information about RS and/or its existing relationship + with C. It is advisable to include as little information as possible + in an unencrypted response. Even the absolute URI of the AS may + reveal sensitive information about the service that RS provides. + Developers must ensure that the RS does not disclose information that + has an impact on the privacy of the stakeholders in the AS Request + Creation Hints. They may choose to use a different mechanism for the + discovery of the AS if necessary. If means of encrypting + communication between C and RS already exist, more detailed + information may be included with an error response to provide C with + sufficient information to react on that particular error. 8. IANA Considerations This document creates several registries with a registration policy of "Expert Review"; guidelines to the experts are given in Section 8.17. 8.1. ACE Authorization Server Request Creation Hints This specification establishes the IANA "ACE Authorization Server @@ -2326,27 +2321,27 @@ 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.6.3 of [this document] + o 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.6.3 of [this document] + o 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: @@ -2455,21 +2449,21 @@ 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.6.2 and Section 5.6.4.3 of [this document] + o 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: @@ -2488,36 +2482,36 @@ 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.7.2 of [this document] + o Reference: Section 5.9.2 of [this document] o Name: "cnonce" o 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.7.2 of [this document] + o Reference: Section 5.9.2 of [this document] o Name: "exi" o 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.7.2 of [this document] + o 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: @@ -2541,67 +2535,68 @@ 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 with. o Change Controller: IESG - o Reference: Section 5.8 of [this document] + o Reference: Section 5.10 of [this document] + o Claim Name: "cnonce" o Claim Description: "client-nonce". A nonce previously provided to the AS by the RS via the client. Used to verify token freshness when the RS cannot synchronize its clock with the AS. o Change Controller: IESG - o Reference: Section 5.8 of [this document] + o Reference: Section 5.10 of [this document] o Claim Name: "exi" o Claim Description: "Expires in". Lifetime of the token in seconds from the time the RS first sees it. Used to implement a weaker from of token expiration for devices that cannot synchronize their internal clocks. o Change Controller: IESG - o Reference: Section 5.8.3 of [this document] + o 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 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.8 of [this document] + o 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 the client. o JWT Claim Name: cnonce o Claim Key: TBD (suggested: 39) o Claim Value Type(s): byte string o Change Controller: IESG - o Specification Document(s): Section 5.8 of [this document] + 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 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.8.3 of [this document] + o 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 [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] @@ -2859,28 +2855,28 @@ . [I-D.erdtman-ace-rpcc] Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared- Key as OAuth client credentials", draft-erdtman-ace- rpcc-02 (work in progress), October 2017. [I-D.ietf-quic-transport] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed - and Secure Transport", draft-ietf-quic-transport-29 (work - in progress), June 2020. + and Secure Transport", draft-ietf-quic-transport-32 (work + in progress), October 2020. [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-38 (work in progress), May - 2020. + 1.3", draft-ietf-tls-dtls13-39 (work in progress), + November 2020. [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. [MQTT5.0] Banks, A., Briggs, E., Borgendale, K., and R. Gupta, "MQTT @@ -3081,21 +3077,21 @@ specifically aimed at constrained devices, like, e.g., Bluetooth Low Energy (see Section 3.2). This aims again at reducing the size of messages sent over the wire, the RAM size of data objects that need to be kept in memory and the size of libraries that devices need to support. Access Information: This framework defines the name "Access Information" for data concerning the RS that the AS returns to the client in an access - token response (see Section 5.6.2). This aims at enabling + token response (see Section 5.8.2). This aims at enabling scenarios where a powerful client, supporting multiple profiles, needs to interact with an RS for which it does not know the supported profiles and the raw public key. Proof-of-Possession: This framework makes use of proof-of-possession tokens, using the "cnf" claim [RFC8747]. A request parameter "cnf" and a Response parameter "cnf", both having a value space semantically and syntactically identical to the "cnf" claim, are defined for the @@ -3260,46 +3257,47 @@ 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 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.2 + o Optionally specify new grant types. Section 5.4 o Optionally define the use of client certificates as client - credential type. Section 5.3 + credential type. Section 5.5 + o Specify the communication protocol the client and RS the must use - (e.g., CoAP). Section 5 and Section 5.6.4.3 + (e.g., CoAP). Section 5 and Section 5.8.4.3 o 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.6.4.3 + Section 5.8.4.3 o Specify how the client and the RS mutually authenticate. Section 4 o Specify the proof-of-possession protocol(s) and how to select one, if several are available. Also specify which key types (e.g., symmetric/asymmetric) are supported by a specific proof-of- - possession protocol. Section 5.6.4.2 - o Specify a unique ace_profile identifier. Section 5.6.4.3 + 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 - security protocol for introspection. Section 5.7 + security protocol for introspection. Section 5.9 o 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.6 + responses. Section 5 and Section 5.8 o Specify how/if the authz-info endpoint is protected, including how - error responses are protected. Section 5.8.1 + error responses are protected. Section 5.10.1 o Optionally define other methods of token transport than the authz- - info endpoint. Section 5.8.1 + 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. @@ -3786,21 +3782,21 @@ o Added text about protection of credentials. o Rephrased introspection so that other entities than RS can do it. o Editorial improvements. F.9. 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 Added note on schema part of AS Information Section 5.3 o Realigned the parameter abbreviations to push rarely used ones to the 2-byte encoding size of CBOR integers. F.10. Version -12 to -13 o Changed "Resource Information" to "Access Information" to avoid confusion. o Clarified section about AS discovery. o Editorial changes @@ -3874,33 +3870,33 @@ F.16. Version -06 to -07 o Various clarifications added. o Fixed erroneous author email. F.17. 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. + sections, Section 5.4, and Section 5.5. + o Added Section 5.6 on AS authentication. + o Added Section 5.7 on the Authorization endpoint. F.18. 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 Section 5.5 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 + requests in Section 5.10.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.19. Version -03 to -04