--- 1/draft-ietf-ace-oauth-authz-11.txt 2018-05-21 03:13:09.975981371 -0700 +++ 2/draft-ietf-ace-oauth-authz-12.txt 2018-05-21 03:13:10.103984423 -0700 @@ -1,26 +1,26 @@ ACE Working Group L. Seitz Internet-Draft RISE SICS Intended status: Standards Track G. Selander -Expires: September 20, 2018 Ericsson +Expires: November 22, 2018 Ericsson E. Wahlstroem S. Erdtman Spotify AB H. Tschofenig ARM Ltd. - March 19, 2018 + May 21, 2018 Authentication and Authorization for Constrained Environments (ACE) using the OAuth 2.0 Framework (ACE-OAuth) - draft-ietf-ace-oauth-authz-11 + draft-ietf-ace-oauth-authz-12 Abstract This specification defines a framework for authentication and authorization in Internet of Things (IoT) environments called ACE- OAuth. The framework is based on a set of building blocks including OAuth 2.0 and CoAP, thus making a well-known and widely used authorization solution suitable for IoT devices. Existing specifications are used where possible, but where the constraints of IoT devices require it, extensions are added and profiles are @@ -34,21 +34,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on September 20, 2018. + This Internet-Draft will expire on November 22, 2018. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -56,95 +56,96 @@ 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 7 + 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.1. Discovering Authorization Servers . . . . . . . . . . . . 15 5.1.1. Unauthorized Resource Request Message . . . . . . . . 15 5.1.2. AS Information . . . . . . . . . . . . . . . . . . . 16 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 18 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18 - 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 19 + 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 18 5.6.1. Client-to-AS Request . . . . . . . . . . . . . . . . 19 5.6.2. AS-to-Client Response . . . . . . . . . . . . . . . . 22 - 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 25 + 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 24 5.6.4. Request and Response Parameters . . . . . . . . . . . 25 - 5.6.4.1. Audience . . . . . . . . . . . . . . . . . . . . 26 - 5.6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 26 + 5.6.4.1. Audience . . . . . . . . . . . . . . . . . . . . 25 + 5.6.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 25 5.6.4.3. Token Type . . . . . . . . . . . . . . . . . . . 26 - 5.6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 27 + 5.6.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 26 5.6.4.5. Confirmation . . . . . . . . . . . . . . . . . . 27 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 27 5.7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 28 5.7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 29 5.7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 29 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 30 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 31 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 32 - 5.8.1. The 'Authorization Information' Endpoint . . . . . . 32 - 5.8.2. Token Expiration . . . . . . . . . . . . . . . . . . 33 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 34 - 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 35 - 6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 35 - 6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 35 - 6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 36 - 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 36 - 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 - 8.1. Authorization Server Information . . . . . . . . . . . . 37 - 8.2. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 37 - 8.3. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 38 - 8.4. OAuth Access Token Types . . . . . . . . . . . . . . . . 38 - 8.5. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 38 - 8.5.1. Initial Registry Contents . . . . . . . . . . . . . . 39 - 8.6. ACE OAuth Profile Registry . . . . . . . . . . . . . . . 39 - 8.7. OAuth Parameter Registration . . . . . . . . . . . . . . 39 - 8.8. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 40 - 8.9. OAuth Introspection Response Parameter Registration . . . 41 - 8.10. Introspection Endpoint CBOR Mappings Registry . . . . . . 41 - 8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 41 - 8.12. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 42 - 8.13. CoAP Option Number Registration . . . . . . . . . . . . . 42 - 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 43 - 10.2. Informative References . . . . . . . . . . . . . . . . . 44 - Appendix A. Design Justification . . . . . . . . . . . . . . . . 46 - Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 50 - Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 52 - Appendix D. Assumptions on AS knowledge about C and RS . . . . . 53 - Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 53 - E.1. Local Token Validation . . . . . . . . . . . . . . . . . 53 - E.2. Introspection Aided Token Validation . . . . . . . . . . 57 - Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 61 - F.1. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 61 - F.2. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 61 - F.3. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 61 - F.4. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 62 - F.5. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 62 - F.6. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 62 - F.7. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 63 - F.8. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 63 - F.9. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 63 - F.10. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 63 - F.11. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 64 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 65 + 5.8.1. The 'Authorization Information' Endpoint . . . . . . 33 + 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 34 + 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 34 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 35 + 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 36 + 6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 37 + 6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 37 + 6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 37 + 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 37 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 + 8.1. Authorization Server Information . . . . . . . . . . . . 38 + 8.2. OAuth Error Code CBOR Mappings Registry . . . . . . . . . 39 + 8.3. OAuth Grant Type CBOR Mappings . . . . . . . . . . . . . 39 + 8.4. OAuth Access Token Types . . . . . . . . . . . . . . . . 40 + 8.5. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 40 + 8.5.1. Initial Registry Contents . . . . . . . . . . . . . . 40 + 8.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 41 + 8.7. OAuth Parameter Registration . . . . . . . . . . . . . . 41 + 8.8. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 42 + 8.9. OAuth Introspection Response Parameter Registration . . . 42 + 8.10. Introspection Endpoint CBOR Mappings Registry . . . . . . 43 + 8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 43 + 8.12. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 44 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 44 + 10.2. Informative References . . . . . . . . . . . . . . . . . 46 + Appendix A. Design Justification . . . . . . . . . . . . . . . . 48 + Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 52 + Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 54 + Appendix D. Assumptions on AS knowledge about C and RS . . . . . 55 + Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 55 + E.1. Local Token Validation . . . . . . . . . . . . . . . . . 55 + E.2. Introspection Aided Token Validation . . . . . . . . . . 59 + Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 63 + F.1. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 63 + F.2. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 63 + F.3. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 64 + F.4. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 64 + F.5. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 64 + F.6. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 65 + F.7. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 65 + F.8. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 65 + F.9. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 65 + F.10. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 65 + F.11. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 66 + F.12. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 66 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 67 1. Introduction Authorization is the process for granting approval to an entity to access a resource [RFC4949]. The authorization task itself can best be described as granting access to a requesting client, for a resource hosted on a device, the resource server (RS). This exchange is mediated by one or multiple authorization servers (AS). Managing authorization for a large number of devices and users can be a complex task. @@ -249,23 +250,22 @@ designed for small code and message size, which may be used for encoding of self contained tokens, and also for encoding payload transferred in protocol messages. A fourth building block is the compact CBOR-based secure message format COSE [RFC8152], which enables application layer security as an alternative or complement to transport layer security (DTLS [RFC6347] or TLS [RFC5246]). COSE is used to secure self-contained tokens such as proof-of-possession (PoP) tokens, which is an extension to the OAuth tokens. The default token format is defined in CBOR web token - (CWT) [I-D.ietf-ace-cbor-web-token]. Application layer security for - CoAP using COSE can be provided with OSCOAP - [I-D.ietf-core-object-security]. + (CWT) [RFC8392]. Application layer security for CoAP using COSE can + be provided with OSCORE [I-D.ietf-core-object-security]. With the building blocks listed above, solutions satisfying various IoT device and network constraints are possible. A list of constraints is described in detail in RFC 7228 [RFC7228] and a description of how the building blocks mentioned above relate to the various constraints can be found in Appendix A. Luckily, not every IoT device suffers from all constraints. The ACE framework nevertheless takes all these aspects into account and allows several different deployment variants to co-exist, rather than @@ -343,32 +343,32 @@ public key is sent to the AS (if it does not already have knowledge of the client's public key). Information about the public key, which is the PoP key in this case, is either stored to be returned on introspection calls or included inside the access token and sent back to the requesting client. The RS can identify the client's public key from the information in the token, which allows the client to use the corresponding private key for the proof of possession. The access token is either a simple reference, or a structured - information object (e.g., CWT [I-D.ietf-ace-cbor-web-token]), - protected by a cryptographic wrapper (e.g., COSE [RFC8152]). The - choice of PoP key does not necessarily imply a specific credential - type for the integrity protection of the token. + information object (e.g., CWT [RFC8392]), protected by a + cryptographic wrapper (e.g., COSE [RFC8152]). The choice of PoP + key does not necessarily imply a specific credential type for the + integrity protection of the token. Scopes and Permissions: In OAuth 2.0, the client specifies the type of permissions it is seeking to obtain (via the scope parameter) in the access token request. In turn, the AS may use the scope response parameter to inform the client of the scope of the access token issued. As the client could be a constrained device as well, this specification - uses CBOR encoding as data format, defined in Section 5, to + defines the use of CBOR encoding as data format, see Section 5, to request scopes and to be informed what scopes the access token actually authorizes. The values of the scope parameter in OAuth 2.0 are expressed as a list of space-delimited, case-sensitive strings, with a semantic that is well-known to the AS and the RS. More details about the concept of scopes is found under Section 3.3 in [RFC6749]. Claims: Information carried in the access token or returned from @@ -376,22 +376,22 @@ An access token may, for example, include a claim identifying the AS that issued the token (via the "iss" claim) and what audience the access token is intended for (via the "aud" claim). The audience of an access token can be a specific resource or one or many resource servers. The resource owner policies influence what claims are put into the access token by the authorization server. While the structure and encoding of the access token varies throughout deployments, a standardized format has been defined with the JSON Web Token (JWT) [RFC7519] where claims are encoded - as a JSON object. In [I-D.ietf-ace-cbor-web-token], an equivalent - format using CBOR encoding (CWT) has been defined. + as a JSON object. In [RFC8392], an equivalent format using CBOR + encoding (CWT) has been defined. Introspection: Introspection is a method for a resource server to query the authorization server for the active state and content of a received access token. This is particularly useful in those cases where the authorization decisions are very dynamic and/or where the received access token itself is an opaque reference rather than a self-contained token. More information about introspection in OAuth 2.0 can be found in [RFC7662]. @@ -414,24 +414,24 @@ Transport layer security for CoAP can be provided by DTLS 1.2 [RFC6347] or TLS 1.2 [RFC5246]. CoAP defines a number of proxy operations that require transport layer security to be terminated at the proxy. One approach for protecting CoAP communication end-to-end through proxies, and also to support security for CoAP over a different transport in a uniform way, is to provide security at the application layer using an object-based security mechanism such as COSE [RFC8152]. - One application of COSE is OSCOAP [I-D.ietf-core-object-security], + One application of COSE is OSCORE [I-D.ietf-core-object-security], which provides end-to-end confidentiality, integrity and replay protection, and a secure binding between CoAP request and response - messages. In OSCOAP, the CoAP messages are wrapped in COSE objects + messages. In OSCORE, the CoAP messages are wrapped in COSE objects and sent using CoAP. This framework RECOMMENDS the use of CoAP as replacement for HTTP. 4. Protocol Interactions The ACE framework is based on the OAuth 2.0 protocol interactions using the token endpoint and optionally the introspection endpoint. A client obtains an access token from an AS using the token endpoint and subsequently presents the access token to a RS to gain access to @@ -630,31 +630,33 @@ exchanged with the AS is encrypted and integrity protected. It is furthermore REQUIRED that the AS and the endpoint communicating with it (client or RS) perform mutual authentication. Profiles MUST specify how mutual authentication is done, depending e.g. on the communication protocol and the credentials used by the client or the RS. In OAuth 2.0 the communication with the Token and the Introspection endpoints at the AS is assumed to be via HTTP and may use Uri-query - parameters. This framework RECOMMENDS to use CoAP instead and - RECOMMENDS the use of the following alternative instead of Uri-query - parameters: The sender (client or RS) encodes the parameters of its - request as a CBOR map and submits that map as the payload of the POST - request. The Content-format depends on the security applied to the - content and MUST be specified by the profile that is used. + parameters. When profiles of this framework use CoAP instead, this + framework REQUIRES the use of the following alternative instead of + Uri-query parameters: The sender (client or RS) encodes the + parameters of its request as a CBOR map and submits that map as the + payload of the POST request. The Content-format depends on the + security applied to the content and MUST be specified by the profile + that is used. The OAuth 2.0 AS uses a JSON structure in the payload of its - responses both to client and RS. This framework REQUIRES the use of - CBOR [RFC7049] instead. Depending on the profile, the CBOR payload - MAY be enclosed in a non-CBOR cryptographic wrapper. + responses both to client and RS. If CoAP is used, this framework + REQUIRES the use of CBOR [RFC7049] instead of JSON. Depending on the + profile, the CBOR payload MAY be enclosed in a non-CBOR cryptographic + wrapper. 5.1. Discovering Authorization Servers In order to determine the AS in charge of a resource hosted at the 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. Instead of the initial Unauthorized Resource Request message, C MAY look up the desired resource in a resource directory (cf. @@ -678,35 +680,22 @@ autonomously once access was granted and a secure channel has been established between C and RS. The authz-info endpoint MUST NOT be protected as specified above, in order to allow clients to upload access tokens to RS (cf. Section 5.8.1). Unauthorized Resource Request messages MUST be denied with a client error response. In this response, the Resource Server SHOULD provide proper AS Information to enable the Client to request an access token from RS's AS as described in Section 5.1.2. - The response code MUST be 4.01 (Unauthorized) in case the sender of - the Unauthorized Resource Request message is not authenticated, or if - RS has no valid access token for C. If RS has an access token for C - but not for the resource that C has requested, RS MUST reject the - request with a 4.03 (Forbidden). If RS has an access token for C but - it does not cover the action C requested on the resource, RS MUST - reject the request with a 4.05 (Method Not Allowed). - - Note: The use of the response codes 4.03 and 4.05 is intended to - prevent infinite loops where a dumb Client optimistically tries to - access a requested resource with any access token received from AS. - As malicious clients could pretend to be C to determine C's - privileges, these detailed response codes must be used only when a - certain level of security is already available which can be achieved - only when the Client is authenticated. + The handling of all client requests (including unauthorized ones) by + the RS is described in Section 5.8.2. 5.1.2. AS Information The AS Information is sent by RS as a response to an Unauthorized Resource Request message (see Section 5.1.1) to point the sender of the Unauthorized Resource Request message to RS's AS. The AS information is a set of attributes containing an absolute URI (see Section 4.3 of [RFC3986]) that specifies the AS in charge of RS. The message MAY also contain a nonce generated by RS to ensure @@ -860,23 +849,24 @@ integer abbreviations and the binary CBOR encoding, if the CBOR encoding is used. 5.6.1. Client-to-AS Request The client sends a POST request to the token endpoint at the AS. The profile MUST specify the Content-Type and wrapping of the payload. The content of the request consists of the parameters specified in Section 4 of the OAuth 2.0 specification [RFC6749]. - If CBOR is used then this parameter is encoded as a CBOR map, where - the "scope" parameter can additionally be formatted as a byte array, - in order to allow compact encoding of complex scope structures. + If CBOR is used then this parameter MUST be encoded as a CBOR map, + where the "scope" parameter can additionally be formatted as a byte + array, in order to allow compact encoding of complex scope + structures. When HTTP is used as a transport then the client makes a request to the token endpoint by sending the parameters using the "application/ x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body, as defined in RFC 6749. In addition to these parameters, this framework defines the following parameters for requesting an access token from a token endpoint: aud: @@ -1000,49 +990,46 @@ The content of the successful reply is the RS Information. When using CBOR payloads, the content MUST be encoded as CBOR map, containing parameters as specified in Section 5.1 of [RFC6749]. In addition to these parameters, the following parameters are also part of a successful response: profile: OPTIONAL. This indicates the profile that the client MUST use towards the RS. See Section 5.6.4.4 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. + parameter. If this parameter is absent, the AS assumes that the + client implicitly knows which profile to use towards the RS. cnf: REQUIRED if the token type is "pop" and a symmetric key is used. MUST NOT be present otherwise. This field contains the symmetric proof-of-possession key the client is supposed to use. See Section 5.6.4.5 for details on the use of this parameter. rs_cnf: OPTIONAL if the token type is "pop" and asymmetric keys are used. MUST NOT be present otherwise. This field contains information about the public key used by the RS to authenticate. See Section 5.6.4.5 for details on the use of this parameter. If this parameter is absent, the AS assumes that the client already knows the public key of the RS. token_type: OPTIONAL. 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. - Note that if CBOR Web Tokens [I-D.ietf-ace-cbor-web-token] are used, - the access token can also contain a "cnf" claim - [I-D.ietf-ace-cwt-proof-of-possession]. This claim is however - consumed by a different party. The access token is created by the AS - and processed by the RS (and opaque to the client) whereas the RS - Information is created by the AS and processed by the client; it is - never forwarded to the resource server. + Note that if CBOR Web Tokens [RFC8392] are used, the access token + also contains a "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession]. + This claim is however consumed by a different party. The access + token is created by the AS and processed by the RS (and opaque to the + client) whereas the RS Information is created by the AS and processed + by the client; it is never forwarded to the resource server. Figure 8 summarizes the parameters that may be part of the RS Information. /-------------------+-----------------\ | Parameter name | Specified in | |-------------------+-----------------| | access_token | RFC 6749 | | token_type | RFC 6749 | | expires_in | RFC 6749 | @@ -1085,23 +1072,23 @@ Figure 9: Example AS response with an access token bound to a symmetric key. 5.6.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 5.2 of [RFC6749], with the following differences: o The Content-Type MUST be specified by the communication security - profile used between client and AS. The raw payload before being - processed by the communication security protocol MUST be encoded - as a CBOR map. + profile used between client and AS. When using CoAP 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 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 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 abbreviated as specified in Figure 10, when a CBOR encoding is @@ -1178,22 +1165,24 @@ AS does not provide a different value. 5.6.4.4. 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. Furthermore profiles MUST define proof-of-possession methods, if they support proof-of-possession tokens. - A profile MUST specify an identifier that can be used to uniquely - identify itself in the "profile" parameter. + A profile MUST specify an identifier that MUST be used to uniquely + identify itself in the "profile" parameter. The textual + representation of the profile identifier is just intended for human + readability and MUST NOT be used in parameters and claims.. Profiles MAY define additional parameters for both the token request and the RS Information in the access token response in order to support negotiation or signaling of profile specific parameters. 5.6.4.5. Confirmation The "cnf" parameter identifies or provides the key used for proof-of- possession, while the "rs_cnf" parameter provides the raw public key of the RS. Both parameters use the same formatting and semantics as @@ -1213,28 +1202,37 @@ o In the introspection response AS -> RS, to indicate the proof-of- possession key bound to the introspected token. Note that the COSE_Key structure in a "cnf" claim or parameter may contain an "alg" or "key_ops" parameter. If such parameters are present, a client MUST NOT use a key that is not compatible with the profile or proof-of-possession algorithm according to those parameters. An RS MUST reject a proof-of-possession using such a key. + Also note that the "rs_cnf" parameter is supposed to indicate the key + that the RS uses to authenticate. If the access token is issued for + an audience that includes several RS, this parameter MUST NOT be + used, since it is them impossible to determine for which RS the key + applies. This framework recommends to specify a different endpoint + that the client can use to acquire RS authentication keys in such + cases. The specification of such an endpoint is out of scope for + this framework. + 5.6.5. Mapping Parameters to CBOR - All OAuth parameters in access token requests and responses MUST be - mapped to CBOR types as specified in Figure 12, using the given - integer abbreviation for the key, if a CBOR encoding is used. + If CBOR encoding is used, all OAuth parameters in access token + requests and responses MUST be mapped to CBOR types as specified in + Figure 12, using the given integer abbreviation for the map keys. Note that we have aligned these abbreviations with the claim - abbreviations defined in [I-D.ietf-ace-cbor-web-token]. + abbreviations defined in [RFC8392]. /-------------------+----------+---------------------\ | Name | CBOR Key | Value Type | |-------------------+----------+---------------------| | aud | 3 | text string | | client_id | 8 | text string | | client_secret | 9 | byte string | | response_type | 10 | text string | | redirect_uri | 11 | text string | | scope | 12 | text or byte string | @@ -1283,25 +1281,25 @@ 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. RS-to-AS Request The RS sends a POST request to the introspection endpoint at the AS, the profile MUST specify the Content-Type and wrapping of the - payload. The payload MUST be encoded as a CBOR map with a "token" - parameter containing either the access token or a reference to the - token (e.g., the cti). Further optional parameters representing - additional context that is known by the RS to aid the AS in its - response MAY be included. + payload. If CBOR is used, the payload MUST be encoded as a CBOR map + with a "token" entry containing either the access token or a + reference to the token (e.g., the cti). Further optional parameters + representing additional context that is known by the RS to aid the AS + in its response MAY be included. The same parameters are required and optional as in Section 2.1 of RFC 7662 [RFC7662]. For example, Figure 13 shows a RS calling the token introspection endpoint at the AS to query about an OAuth 2.0 proof-of-possession token. Note that object security based on COSE is assumed in this example, therefore the Content-Type is "application/cose+cbor". Header: POST (Code=0.02) @@ -1318,30 +1316,36 @@ 5.7.2. AS-to-RS 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. In a successful response, the AS encodes the response parameters in a - CBOR map including with the same required and optional parameters as - in Section 2.2. of RFC 7662 [RFC7662] with the following additions: + map including with the same required and optional parameters as in + Section 2.2. of RFC 7662 [RFC7662] with the following additions: cnf OPTIONAL. This field contains information about the proof-of- possession key that binds the client to the access token. See Section 5.6.4.5 for more details on the use of the "cnf" parameter. profile OPTIONAL. This indicates the profile that the RS MUST use with the client. See Section 5.6.4.4 for more details on the formatting of this parameter. + rs_cnf OPTIONAL. If the RS has several keys it can use to + authenticate towards the client, the AS can give the RS a hint + using this parameter, as to which key it should use (e.g. if the + AS previously informed the client about a public key the RS is + holding). See Section 5.6.4.5 for more details on the use of this + parameter. For example, Figure 14 shows an AS response to the introspection request in Figure 13. Note that transport layer security is assumed in this example, therefore the Content-Type is "application/cbor". Header: Created Code=2.01) Content-Type: "application/cbor" Payload: { "active" : true, @@ -1358,27 +1362,26 @@ Figure 14: Example introspection response. 5.7.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, the Content-Type MUST be set according to the - specification of the communication security profile, and the - content payload MUST be encoded as a CBOR map. + specification of the communication security profile. If CoAP is + used the payload MUST be encoded as a CBOR map. o If the credentials used by 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 5.2 in RFC 6749 [RFC6749]. - o If the RS 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 be abbreviated using the codes specified in Figure 12. o The error codes MUST be abbreviated using the codes specified in Figure 10. Note that a properly formed and authorized query for an inactive or @@ -1382,26 +1385,26 @@ Figure 10. 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 - The introspection request and response parameters MUST be mapped to - CBOR types as specified in Figure 15, using the given integer - abbreviation for the key. + If CBOR is used, the introspection request and response parameters + MUST be mapped to CBOR types as specified in Figure 15, using the + given integer abbreviation for the map key. Note that we have aligned these abbreviations with the claim - abbreviations defined in [I-D.ietf-ace-cbor-web-token]. + abbreviations defined in [RFC8392]. /-----------------+----------+----------------------------------\ | 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 | @@ -1416,34 +1419,43 @@ | token_type_hint | 28 | text string | | active | 29 | True or False | | rs_cnf | 30 | map | \-----------------+----------+----------------------------------/ Figure 15: CBOR Mappings to Token Introspection Parameters. 5.8. The Access Token This framework RECOMMENDS the use of CBOR web token (CWT) as - specified in [I-D.ietf-ace-cbor-web-token]. + specified in [RFC8392]. In order to facilitate offline processing of access tokens, this draft uses the "cnf" claim from [I-D.ietf-ace-cwt-proof-of-possession] and specifies the "scope" claim for both JSON and CBOR web tokens. The "scope" claim explicitly encodes the scope of a given access token. This claim follows the same encoding rules as defined in Section 3.3 of [RFC6749], but in addition implementers MAY use byte arrays as scope values, to achieve compact encoding of large scope elements. The meaning of a specific scope value is application specific and expected to be known to the RS running that application. + If the AS needs to convey a hint to the RS about which key it should + use to authenticate towards the client, the rs_cnf claim MAY be used + with the same syntax and semantics as defined in Section 5.6.4.5. + + If the AS needs to convey a hint to the RS about which profile it + should use to communicate with the client, the AS MAY include a + "profile" claim in the access token, with the same syntax and + semantics as defined in Section 5.6.4.4. + 5.8.1. The 'Authorization Information' Endpoint The access token, containing authorization information and information about the key used by the client, needs to be transported to the RS so that the RS can authenticate and authorize the client request. This section defines a method for transporting the access token to the RS using a RESTful protocol such as CoAP. Profiles of this framework MAY define other methods for token transport. @@ -1468,30 +1480,63 @@ MUST respond with a response code equivalent to the CoAP code 4.03 (Forbidden). If the token is valid but is associated to claims that the RS cannot process (e.g., an unknown scope) the RS MUST respond with a response code equivalent to the CoAP code 4.00 (Bad Request). In the latter case the RS MAY provide additional information in the error response, in order to clarify what went wrong. The RS MAY make an introspection request to validate the token before responding to the POST request to the authz-info endpoint. - Profiles MUST specify how the authz-info endpoint is protected. Note + Profiles MUST specify how the authz-info endpoint is protected, + including how 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.2. Token Expiration +5.8.2. Client Requests to the RS + + A RS receiving a client request MUST first verify that it has an + access token that authorizes this request, and that the client has + performed the proof-of-possession for that token. + + The response code MUST be 4.01 (Unauthorized) in case the client has + not performed the proof-of-possession, or if RS has no valid access + token for the client. If RS has an access token for the client but + not for the resource that was requested, RS MUST reject the request + with a 4.03 (Forbidden). If RS has an access token for the client + but it does not cover the action that was requested on the resource, + RS MUST reject the request with a 4.05 (Method Not Allowed). + + Note: The use of the response codes 4.03 and 4.05 is intended to + prevent infinite loops where a dumb Client optimistically tries to + access a requested resource with any access token received from AS. + As malicious clients could pretend to be C to determine C's + privileges, these detailed response codes must be used only when a + certain level of security is already available which can be achieved + only when the Client is authenticated. + + 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 Depending on the capabilities of the RS, there are various ways in which it can verify the validity 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 @@ -1510,22 +1555,22 @@ sequence number, and only accepts tokens as valid, that are in a certain range around this number. This method does only require the RS to keep track of the sequence number. The method does not provide timely expiration, but it makes sure that older tokens cease to be valid after a certain number of newer ones got issued. For a constrained RS with no network connectivity and no means of reliably measuring time, this is the best that can be achieved. If a token that authorizes a long running request such as a CoAP Observe [RFC7641] expires, the RS MUST send an error response with - the response code 4.01 Unauthorized to the client and then terminate - processing the long running request. + the response code equivalent to the CoAP code 4.01 (Unauthorized) to + the client and then terminate processing the long running request. 6. Security Considerations Security considerations applicable to authentication and authorization in RESTful environments provided in OAuth 2.0 [RFC6749] apply to this work, as well as the security considerations from [I-D.ietf-ace-actors]. Furthermore [RFC6819] provides additional security considerations for OAuth which apply to IoT deployments as well. @@ -1550,21 +1595,21 @@ The authorization server MUST offer confidentiality protection for any interactions with the client. This step is extremely important since the client may obtain the proof-of-possession key from the authorization server for use with a specific access token. Not using confidentiality protection exposes this secret (and the access token) to an eavesdropper thereby completely negating proof-of-possession security. Profiles MUST specify how confidentiality protection is provided, and additional protection can be applied by encrypting the token, for example encryption of CWTs is specified in Section 5.1 of - [I-D.ietf-ace-cbor-web-token]. + [RFC8392]. Developers MUST ensure that the ephemeral credentials (i.e., the private key or the session key) are not leaked to third parties. An adversary in possession of the ephemeral credentials bound to the access token will be able to impersonate the client. Be aware that this is a real risk with many constrained environments, since adversaries can often easily get physical access to the devices. Clients can at any time request a new proof-of-possession capable access token. If clients have that capability, the AS can keep the @@ -1589,21 +1634,21 @@ contained in an unprotected response from RS to an unauthorized request (c.f. Section 5.1.2) is authentic. It is therefore advisable to provide C with a (possibly hard-coded) list of trustworthy authorization servers. AS information responses referring to a URI not listed there would be ignored. 6.2. Use of Nonces for Replay Protection RS may add a nonce to the AS Information message sent as a response to an unauthorized request to ensure freshness of an Access Token - subsequently presented to RS. While a timestamp of some granularity + subsequently presented to RS. While a time-stamp of some granularity would be sufficient to protect against replay attacks, using randomized nonce is preferred to prevent disclosure of information about RS's internal clock characteristics. 6.3. Combining profiles There may exist reasonable use cases where implementers want to combine different profiles of this framework, e.g., using an MQTT profile between client and RS, while using a DTLS profile for interactions between client and AS. Profiles should be designed in a @@ -1655,159 +1700,177 @@ 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. 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 specification registers new parameters for OAuth and establishes - registries for mappings to CBOR abbreviations. - 8.1. Authorization Server Information - A new registry will be requested from IANA, entitled "Authorization - Server Information". The registry is to be created as Expert Review - Required. + This section establishes the IANA "ACE Authorization Server + Information" registry. The registry has been created to use the + "Expert Review Required" 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 table are: + The columns of the registry are: Name The name of the parameter - CBOR Key The unsigned integer value abbreviating this parameter - name. Registration in the table is based on the value of the - mapping requested. Integer values between 1 and 255 are - designated as Standards Track Document required. Integer values - from 256 to 65535 are designated as Specification Required. - Integer values greater than 65535 are designated as private use. + CBOR Key CBOR map key for the parameter. Different ranges of values + use different registration policies [RFC8126]. Integer values + from -256 to 255 are designated as Standards Action. Integer + values from -65536 to -257 and from 256 to 65535 are designated as + Specification Required. Integer values greater than 65535 are + designated as Expert Review. Integer values less than -65536 are + marked as Private Use. Value Type The CBOR data types allowable for the values of this parameter. Reference This contains a pointer to the public specification of the grant type abbreviation, if one exists. 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. OAuth Error Code CBOR Mappings Registry - A new registry will be requested from IANA, entitled "OAuth Error - Code CBOR Mappings Registry". The registry is to be created as - Expert Review Required. + This section establish the IANA "OAuth Error Code CBOR Mappings" + registry. The registry has been created to use the "Expert Review + Required" 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 table are: + 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 The unsigned integer value abbreviating this error code. - Registration in the table is based on the value of the mapping - requested. Integer values between 1 and 255 are designated as - Standards Track Document required. Integer values from 256 to - 65535 are designated as Specification Required. Integer values - greater than 65535 are designated as private use. - + CBOR Value CBOR abbreviation for this error code. Different ranges + of values use different registration policies [RFC8126]. Integer + values from -256 to 255 are designated as Standards Action. + Integer values from -65536 to -257 and from 256 to 65535 are + designated as Specification Required. Integer values greater than + 65535 are designated as Expert Review. Integer values less than + -65536 are marked as Private Use. Reference This contains a pointer to the public specification of the grant type abbreviation, 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.3. OAuth Grant Type CBOR Mappings - A new registry will be requested from IANA, entitled "OAuth Grant - Type CBOR Mappings". The registry is to be created as Expert Review - Required. + This section establishes the IANA "OAuth Grant Type CBOR Mappings" + registry. The registry has been created to use the "Expert Review + Required" 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 table are: + The columns of this registry are: Name The name of the grant type as specified in Section 1.3 of [RFC6749]. - CBOR Value The unsigned integer value abbreviating this grant type. - Registration in the table is based on the value of the mapping - requested. Integer values between 1 and 255 are designated as - Standards Track Document required. Integer values from 256 to - 65535 are designated as Specification Required. Integer values - greater than 65535 are designated as private use. + CBOR Value CBOR abbreviation for this grant type. Different ranges + of values use different registration policies [RFC8126]. Integer + values from -256 to 255 are designated as Standards Action. + Integer values from -65536 to -257 and from 256 to 65535 are + designated as Specification Required. Integer values greater than + 65535 are designated as Expert Review. Integer values less than + -65536 are marked as Private Use. Reference This contains a pointer to the public specification of the grant type abbreviation, if one exists. + Original Specification This contains a pointer to the public 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.4. OAuth Access Token Types - This specification registers the following new token type in the - OAuth Access Token Types Registry + This section registers the following new token type in the "OAuth + Access Token Types" registry [IANA.OAuthAccessTokenTypes]. o Name: "PoP" o Change Controller: IETF o Reference: [this document] 8.5. OAuth Token Type CBOR Mappings - A new registry will be requested from IANA, entitled "Token Type CBOR - Mappings". The registry is to be created as Expert Review Required. + This section eatables the IANA "Token Type CBOR Mappings" registry. + The registry has been created to use the "Expert Review Required" + 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 table are: + The columns of this registry are: Name The name of token type as registered in the OAuth Access Token Types registry e.g., "Bearer". - - CBOR Value The unsigned integer value abbreviating this access token - type. Registration in the table is based on the value of the - mapping requested. Integer values between 1 and 255 are - designated as Standards Track Document required. Integer values - from 256 to 65535 are designated as Specification Required. - Integer values greater than 65535 are designated as private use. + CBOR Value CBOR abbreviation for this token type. Different ranges + of values use different registration policies [RFC8126]. Integer + values from -256 to 255 are designated as Standards Action. + Integer values from -65536 to -257 and from 256 to 65535 are + designated as Specification Required. Integer values greater than + 65535 are designated as Expert Review. Integer values less than + -65536 are marked as Private Use. 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 grant type, if one exists. 8.5.1. Initial Registry Contents o Name: "Bearer" o Value: 1 o Reference: [this document] o Original Specification: [RFC6749] o Name: "pop" o Value: 2 o Reference: [this document] o Original Specification: [this document] -8.6. ACE OAuth Profile Registry +8.6. ACE Profile Registry - A new registry will be requested from IANA, entitled "ACE Profile - Registry". The registry is to be created as Expert Review Required. + This section establishes the IANA "ACE Profile" registry. The + registry has been created to use the "Expert Review Required" + 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 table are: + The columns of this registry are: Name The name of the profile, to be used as value of the profile attribute. Description Text giving an overview of the profile and the context it is developed for. - CBOR Value The unsigned integer value abbreviating this profile - name. Registration in the table is based on the value of the - mapping requested. Integer values between 1 and 255 are - designated as Standards Track Document required. Integer values - from 256 to 65535 are designated as Specification Required. - Integer values greater than 65535 are designated as private use. + CBOR Value CBOR abbreviation for this profile name. Different + ranges of values use different registration policies [RFC8126]. + Integer values from -256 to 255 are designated as Standards + Action. Integer values from -65536 to -257 and from 256 to 65535 + are designated as Specification Required. Integer values greater + than 65535 are designated as Expert Review. Integer values less + than -65536 are marked as Private Use. Reference This contains a pointer to the public specification of the profile abbreviation, if one exists. 8.7. OAuth Parameter Registration - This specification registers the following parameters in the OAuth - Parameters Registry: + This section registers the following parameters in the "OAuth + Parameters" registry [IANA.OAuthParameters]: o Name: "aud" o Parameter Usage Location: authorization request, token request o Change Controller: IESG o Reference: Section 5.6.1 of [this document] o Name: "profile" o Parameter Usage Location: token response o Change Controller: IESG o Reference: Section 5.6.4.4 of [this document] @@ -1809,169 +1872,180 @@ o Name: "profile" o Parameter Usage Location: token response o Change Controller: IESG o Reference: Section 5.6.4.4 of [this document] o Name: "cnf" o Parameter Usage Location: token request, token response o Change Controller: IESG o Reference: Section 5.6.4.5 of [this document] - o Name: "rs_cnf" o Parameter Usage Location: token response o Change Controller: IESG o Reference: Section 5.6.4.5 of [this document] 8.8. OAuth CBOR Parameter Mappings Registry - A new registry will be requested from IANA, entitled "Token Endpoint - CBOR Mappings Registry". The registry is to be created as Expert - Review Required. + This section establishes the IANA "Token Endpoint CBOR Mappings" + registry. The registry has been created to use the "Expert Review + Required" 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 table are: + 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 The unsigned integer value abbreviating this parameter. - Registration in the table is based on the value of the mapping - requested. Integer values between 1 and 255 are designated as - Standards Track Document required. Integer values from 256 to - 65535 are designated as Specification Required. Integer values - greater than 65535 are designated as private use. + CBOR Key CBOR map key for this parameter. Different ranges of + values use different registration policies [RFC8126]. Integer + values from -256 to 255 are designated as Standards Action. + Integer values from -65536 to -257 and from 256 to 65535 are + designated as Specification Required. Integer values greater than + 65535 are designated as Expert Review. Integer values less than + -65536 are marked as Private Use. Value Type The allowable CBOR data types for values of this parameter. Reference This contains a pointer to the public specification of the grant type abbreviation, 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. Note that these mappings intentionally coincide with the CWT claim - name mappings from [I-D.ietf-ace-cbor-web-token]. + name mappings from [RFC8392]. 8.9. OAuth Introspection Response Parameter Registration - This specification registers the following parameters in the OAuth - Token Introspection Response registry. + This section registers the following parameters in the OAuth Token + Introspection Response registry [IANA.TokenIntrospectionResponse]. o Name: "cnf" o Description: Key to prove the right to use a PoP token. o Change Controller: IESG o Reference: Section 5.7.2 of [this document] o Name: "profile" o Description: The communication and communication security profile used between client and RS, as defined in ACE profiles. o Change Controller: IESG o Reference: Section 5.7.2 of [this document] 8.10. Introspection Endpoint CBOR Mappings Registry - A new registry will be requested from IANA, entitled "Introspection - Endpoint CBOR Mappings Registry". The registry is to be created as - Expert Review Required. + This section establishes the IANA "Introspection Endpoint CBOR + Mappings" registry. The registry has been created to use the "Expert + Review Required" 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 table are: + 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 The unsigned integer value abbreviating this parameter. - Registration in the table is based on the value of the mapping - requested. Integer values between 1 and 255 are designated as - Standards Track Document required. Integer values from 256 to - 65535 are designated as Specification Required. Integer values - greater than 65535 are designated as private use. + CBOR Key CBOR map key for this parameter. Different ranges of + values use different registration policies [RFC8126]. Integer + values from -256 to 255 are designated as Standards Action. + Integer values from -65536 to -257 and from 256 to 65535 are + designated as Specification Required. Integer values greater than + 65535 are designated as Expert Review. Integer values less than + -65536 are marked as Private Use. Value Type The allowable CBOR data types for values of this parameter. Reference This contains a pointer to the public specification of the grant type abbreviation, if one exists. This registry will be initially populated by the values in Figure 15. The Reference column for all of these entries will be this document. 8.11. JSON Web Token Claims This specification registers the following new claims in the JSON Web - Token (JWT) registry of JSON Web Token Claims: + Token (JWT) registry of JSON Web Token Claims + [IANA.JsonWebTokenClaims]: o Claim Name: "scope" o Claim Description: The scope of an access token as defined in [RFC6749]. - o Change Controller: IESG o Reference: Section 5.8 of [this document] 8.12. CBOR Web Token Claims - This specification registers the following new claims in the CBOR Web - Token (CWT) registry of CBOR Web Token Claim:s + This specification registers the following new claims in the "CBOR + Web Token (CWT) Claims" registry [IANA.CborWebTokenClaims]. o Claim Name: "scope" o Claim Description: The scope of an access token as defined in [RFC6749]. o JWT Claim Name: N/A o Claim Key: 12 o Claim Value Type(s): 0 (uint), 2 (byte string), 3 (text string) o Change Controller: IESG o Specification Document(s): Section 5.8 of [this document] -8.13. CoAP Option Number Registration - - This section registers the "Access-Token" CoAP Option Number in the - "CoRE Parameters" sub-registry "CoAP Option Numbers" in the manner - described in [RFC7252]. - - o Name: "Access-Token" - o Number: TBD - o Reference: [this document]. - o Meaning in Request: Contains an Access Token according to [this - document] containing access permissions of the client. - o Meaning in Response: Not used in response. - o Safe-to-Forward: Yes - o Format: Based on the observer the format is perceived differently. - Opaque data to the client and CWT or reference token to the RS. - o Length: Less than 255 bytes - 9. Acknowledgments This document is a product of the ACE working group of the IETF. Thanks to Eve Maler for her contributions to the use of OAuth 2.0 and UMA in IoT scenarios, Robert Taylor for his discussion input, and Malisa Vucinic for his input on the predecessors of this proposal. Thanks to the authors of draft-ietf-oauth-pop-key-distribution, from where large parts of the security considerations where copied. Thanks to Stefanie Gerdes, Olaf Bergmann, and Carsten Bormann for contributing their work on AS discovery from draft-gerdes-ace-dcaf- authorize (see Section 5.1). + Thanks to Jim Schaad and Mike Jones for their comprehensive reviews. + Ludwig Seitz and Goeran Selander worked on this document as part of the CelticPlus project CyberWI, with funding from Vinnova. 10. References 10.1. Normative References - [I-D.ietf-ace-cbor-web-token] - Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, - "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-14 - (work in progress), March 2018. - [I-D.ietf-ace-cwt-proof-of-possession] Jones, M., Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs)", draft-ietf-ace-cwt- proof-of-possession-02 (work in progress), March 2018. + [IANA.CborWebTokenClaims] + IANA, "CBOR Web Token (CWT) Claims", + . + + [IANA.JsonWebTokenClaims] + IANA, "JSON Web Token Claims", + . + + [IANA.OAuthAccessTokenTypes] + IANA, "OAuth Access Token Types", + . + + [IANA.OAuthParameters] + IANA, "OAuth Parameters", + . + + [IANA.TokenIntrospectionResponse] + IANA, "OAuth Token Introspection Response", + . + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . @@ -1986,57 +2060,66 @@ [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, . [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- Possession Key Semantics for JSON Web Tokens (JWTs)", RFC 7800, DOI 10.17487/RFC7800, April 2016, . + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + . + [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", RFC 8152, DOI 10.17487/RFC8152, July 2017, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . + [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, + "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, + May 2018, . + 10.2. Informative References [I-D.erdtman-ace-rpcc] Seitz, L. and S. Erdtman, "Raw-Public-Key and Pre-Shared- Key as OAuth client credentials", draft-erdtman-ace- rpcc-02 (work in progress), October 2017. [I-D.ietf-ace-actors] Gerdes, S., Seitz, L., Selander, G., and C. Bormann, "An architecture for authorization in constrained environments", draft-ietf-ace-actors-06 (work in progress), November 2017. [I-D.ietf-core-object-security] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments - (OSCORE)", draft-ietf-core-object-security-10 (work in + (OSCORE)", draft-ietf-core-object-security-12 (work in progress), March 2018. [I-D.ietf-core-resource-directory] Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. Amsuess, "CoRE Resource Directory", draft-ietf-core- resource-directory-13 (work in progress), March 2018. [I-D.ietf-oauth-device-flow] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, "OAuth 2.0 Device Flow for Browserless and Input - Constrained Devices", draft-ietf-oauth-device-flow-07 - (work in progress), October 2017. + Constrained Devices", draft-ietf-oauth-device-flow-09 + (work in progress), April 2018. [I-D.ietf-oauth-discovery] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", draft-ietf-oauth- discovery-10 (work in progress), March 2018. [Margi10impact] Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr, M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold, "Impact of Operating Systems on Wireless Sensor Networks @@ -2204,25 +2287,24 @@ layer security over the various interfaces. In the light of these constraints we have made the following design decisions: CBOR, COSE, CWT: This framework REQUIRES the use of CBOR [RFC7049] as data format. Where CBOR data needs to be protected, the use of COSE [RFC8152] is RECOMMENDED. Furthermore where self-contained tokens are - needed, this framework RECOMMENDS the use of CWT - [I-D.ietf-ace-cbor-web-token]. These measures aim 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. + needed, this framework RECOMMENDS the use of CWT [RFC8392]. These + measures aim 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. CoAP: This framework RECOMMENDS the use of CoAP [RFC7252] instead of HTTP. This does not preclude the use of other protocols 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. @@ -2392,38 +2474,38 @@ security. Appendix C. Requirements on Profiles This section lists the requirements on profiles of this framework, for the convenience of profile designers. o Specify the communication protocol the client and RS the must use (e.g., CoAP). Section 5 and Section 5.6.4.4 o Specify the security protocol the client and RS must use to - protect their communication (e.g., OSCOAP or DTLS over CoAP). + protect their communication (e.g., OSCORE or DTLS over CoAP). This must provide encryption, integrity and replay protection. Section 5.6.4.4 o Specify how the client and the RS mutually authenticate. Section 4 o Specify the Content-format of the protocol messages (e.g., "application/cbor" or "application/cose+cbor"). 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.3 o Specify a unique profile identifier. Section 5.6.4.4 o If introspection is supported: Specify the communication and security protocol for introspection.Section 5.7 o Specify the communication and security protocol for interactions between client and AS. Section 5.6 - o Specify how/if the authz-info endpoint is protected. - Section 5.8.1 + o Specify how/if the authz-info endpoint is protected, including how + error responses are protected. Section 5.8.1 o Optionally define other methods of token transport than the authz- info endpoint. Section 5.8.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 a 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. @@ -2800,52 +2882,65 @@ | | using Pre Shared Key | | +-------->| Header: PUT (Code=0.03) | PUT | Uri-Path: "state" | | Payload: | | F: |<--------+ Header: 2.04 Changed | 2.04 | Payload: | | - Figure 25: Resource request and response protected by OSCOAP + Figure 25: Resource request and response protected by OSCORE Appendix F. Document Updates RFC EDITOR: PLEASE REMOVE THIS SECTION. -F.1. Version -10 to -11 +F.1. Version -11 to -12 + + o Moved the Request error handling to a section of its own. + o Require the use of the abbreviation for profile identifiers. + o Added rs_cnf parameter in the introspection response, to inform + RS' with several RPKs on which key to use. + o Allowed use of rs_cnf as claim in the access token in order to + inform an RS with several RPKs on which key to use. + o Clarified that profiles must specify if/how error responses are + protected. + o Fixed label number range to align with COSE/CWT. + o Clarified the requirements language in order to allow profiles to + specify other payload formats than CBOR if they do not use CoAP. + +F.2. Version -10 to -11 o Fixed some CBOR data type errors. o Updated boilerplate text -F.2. Version -09 to -10 +F.3. Version -09 to -10 o Removed CBOR major type numbers. o Removed the client token design. o Rephrased to clarify that other protocols than CoAP can be used. o Clarifications regarding the use of HTTP -F.3. Version -08 to -09 +F.4. Version -08 to -09 o Allowed scope to be byte arrays. o Defined default names for endpoints. o Refactored the IANA section for briefness and consistency. o Refactored tables that define IANA registry contents for consistency. o Created IANA registry for CBOR mappings of error codes, grant types and Authorization Server Information. - o Added references to other document sections defining IANA entries in the IANA section. -F.4. Version -07 to -08 +F.5. Version -07 to -08 o Moved AS discovery from the DTLS profile to the framework, see Section 5.1. o Made the use of CBOR mandatory. If you use JSON you can use vanilla OAuth. o Made it mandatory for profiles to specify C-AS security and RS-AS security (the latter only if introspection is supported). o Made the use of CBOR abbreviations mandatory. o Added text to clarify the use of token references as an alternative to CWTs. @@ -2859,82 +2954,82 @@ o Added text that clarifies that introspection is optional. o Made profile parameter optional since it can be implicit. o Clarified that CoAP is not mandatory and other protocols can be used. o Clarified the design justification for specific features of the framework in appendix A. o Clarified appendix E.2. o Removed specification of the "cnf" claim for CBOR/COSE, and replaced with references to [I-D.ietf-ace-cwt-proof-of-possession] -F.5. Version -06 to -07 +F.6. Version -06 to -07 o Various clarifications added. o Fixed erroneous author email. -F.6. Version -05 to -06 +F.7. Version -05 to -06 o Moved sections that define the ACE framework into a subsection of the framework Section 5. o Split section on client credentials and grant into two separate sections, Section 5.2, and Section 5.3. o Added Section 5.4 on AS authentication. o Added Section 5.5 on the Authorization endpoint. -F.7. Version -04 to -05 +F.8. Version -04 to -05 o Added RFC 2119 language to the specification of the required behavior of profile specifications. o Added Section 5.3 on the relation to the OAuth2 grant types. o Added CBOR abbreviations for error and the error codes defined in OAuth2. o Added clarification about token expiration and long-running - requests in Section 5.8.2 + requests in Section 5.8.3 o Added security considerations about tokens with symmetric pop keys valid for more than one RS. o Added privacy considerations section. o Added IANA registry mapping the confirmation types from RFC 7800 to equivalent COSE types. o Added appendix D, describing assumptions about what the AS knows about the client and the RS. -F.8. Version -03 to -04 +F.9. Version -03 to -04 o Added a description of the terms "framework" and "profiles" as used in this document. o Clarified protection of access tokens in section 3.1. o Clarified uses of the "cnf" parameter in section 6.4.5. o Clarified intended use of Client Token in section 7.4. -F.9. Version -02 to -03 +F.10. Version -02 to -03 o Removed references to draft-ietf-oauth-pop-key-distribution since the status of this draft is unclear. o Copied and adapted security considerations from draft-ietf-oauth- pop-key-distribution. o Renamed "client information" to "RS information" since it is information about the RS. o Clarified the requirements on profiles of this framework. + o Clarified the token endpoint protocol and removed negotiation of "profile" and "alg" (section 6). o Renumbered the abbreviations for claims and parameters to get a consistent numbering across different endpoints. o Clarified the introspection endpoint. o Renamed token, introspection and authz-info to "endpoint" instead of "resource" to mirror the OAuth 2.0 terminology. o Updated the examples in the appendices. -F.10. Version -01 to -02 +F.11. Version -01 to -02 o Restructured to remove communication security parts. These shall now be defined in profiles. - o Restructured section 5 to create new sections on the OAuth endpoints token, introspection and authz-info. o Pulled in material from draft-ietf-oauth-pop-key-distribution in order to define proof-of-possession key distribution. o Introduced the "cnf" parameter as defined in RFC7800 to reference or transport keys used for proof of possession. o Introduced the "client-token" to transport client information from the AS to the client via the RS in conjunction with introspection. o Expanded the IANA section to define parameters for token request, introspection and CWT claims. @@ -2933,21 +3028,21 @@ o Pulled in material from draft-ietf-oauth-pop-key-distribution in order to define proof-of-possession key distribution. o Introduced the "cnf" parameter as defined in RFC7800 to reference or transport keys used for proof of possession. o Introduced the "client-token" to transport client information from the AS to the client via the RS in conjunction with introspection. o Expanded the IANA section to define parameters for token request, introspection and CWT claims. o Moved deployment scenarios to the appendix as examples. -F.11. Version -00 to -01 +F.12. Version -00 to -01 o Changed 5.1. from "Communication Security Protocol" to "Client Information". o Major rewrite of 5.1 to clarify the information exchanged between C and AS in the PoP access token request profile for IoT. * Allow the client to indicate preferences for the communication security protocol. * Defined the term "Client Information" for the additional information returned to the client in addition to the access