--- 1/draft-ietf-ace-oauth-authz-12.txt 2018-07-02 07:13:53.019078407 -0700 +++ 2/draft-ietf-ace-oauth-authz-13.txt 2018-07-02 07:13:53.199082716 -0700 @@ -1,26 +1,26 @@ ACE Working Group L. Seitz Internet-Draft RISE SICS Intended status: Standards Track G. Selander -Expires: November 22, 2018 Ericsson +Expires: January 3, 2019 Ericsson E. Wahlstroem S. Erdtman Spotify AB H. Tschofenig - ARM Ltd. - May 21, 2018 + Arm Ltd. + July 2, 2018 Authentication and Authorization for Constrained Environments (ACE) using the OAuth 2.0 Framework (ACE-OAuth) - draft-ietf-ace-oauth-authz-12 + draft-ietf-ace-oauth-authz-13 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 November 22, 2018. + This Internet-Draft will expire on January 3, 2019. 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 @@ -64,88 +64,90 @@ 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 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.3. Client Credentials . . . . . . . . . . . . . . . . . . . 17 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18 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 . . . . . . . . . . . . . . . . . . . 24 5.6.4. Request and Response Parameters . . . . . . . . . . . 25 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 . . . . . . . . . . . . . . . . . . . . . 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.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 30 + 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 31 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 31 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 32 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.5.1. Initial Registry Contents . . . . . . . . . . . . . . 41 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.9. OAuth Introspection Response Parameter Registration . . . 43 8.10. Introspection Endpoint CBOR Mappings Registry . . . . . . 43 - 8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 43 + 8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 44 8.12. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 44 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 44 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 45 10.2. Informative References . . . . . . . . . . . . . . . . . 46 - Appendix A. Design Justification . . . . . . . . . . . . . . . . 48 + Appendix A. Design Justification . . . . . . . . . . . . . . . . 49 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 + E.1. Local Token Validation . . . . . . . . . . . . . . . . . 56 + E.2. Introspection Aided Token Validation . . . . . . . . . . 60 + Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 64 + F.1. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 64 + F.2. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 64 + F.3. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 65 + F.4. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 65 + F.5. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 65 + F.6. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 65 + F.7. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 66 + F.8. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 66 + F.9. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 66 + F.10. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 66 + F.11. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 66 + F.12. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 67 + F.13. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 67 + + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 68 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. @@ -215,23 +217,23 @@ authorization server (CAS) functionality is not stand-alone but subsumed by either the authorization server or the client (see Section 2.2 in [I-D.ietf-ace-actors]). 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). - We use the term "RS Information" for parameters describing - characteristics of the RS (e.g. public key) that the AS provides to - the client. + We use the term "Access Information" for parameters other than the + access token provided to the client by the AS to enable it to access + the RS (e.g. public key of the RS, profile supported by RS). 3. Overview This specification defines the ACE framework for authorization in the Internet of Things environment. It consists of a set of building blocks. The basic block is the OAuth 2.0 [RFC6749] framework, which enjoys widespread deployment. Many IoT devices can support OAuth 2.0 without any additional extensions, but for certain constrained @@ -343,21 +345,21 @@ 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 [RFC8392]), protected by a + 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 @@ -420,21 +422,22 @@ 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 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 OSCORE, the CoAP messages are wrapped in COSE objects and sent using CoAP. - This framework RECOMMENDS the use of CoAP as replacement for HTTP. + This framework RECOMMENDS the use of CoAP as replacement for HTTP for + use in constrained environments. 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 a protected resource. In most deployments the RS can process the access token locally, however in some cases the RS may present it to the AS via the introspection endpoint to get fresh information. @@ -500,21 +503,21 @@ In Bluetooth Low Energy, for example, advertisements are broadcasted by a peripheral, including information about the primary services. In CoAP, as a second example, a client can make a request to "/.well- known/core" to obtain information about available resources, which are returned in a standardized format as described in [RFC6690]. +--------+ +---------------+ | |---(A)-- Token Request ------->| | | | | Authorization | | |<--(B)-- Access Token ---------| Server | - | | + RS Information | | + | | + Access Information | | | | +---------------+ | | ^ | | | Introspection Request (D)| | | Client | (optional) | | | | Response | |(E) | | (optional) | v | | +--------------+ | |---(C)-- Token + Request ----->| | | | | Resource | | |<--(F)-- Protected Resource ---| Server | @@ -528,46 +531,46 @@ the AS. This framework assumes the use of PoP access tokens (see Section 3.1 for a short description) wherein the AS binds a key to an access token. The client may include permissions it seeks to obtain, and information about the credentials it wants to use (e.g., symmetric/asymmetric cryptography or a reference to a specific credential). Access Token Response (B): If the AS successfully processes the request from the client, it returns an access token. It can also return additional - parameters, referred to as "RS 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. More information - about these parameters can be found in Section 5.6.4. + 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. More + information about these parameters can be found in Section 5.6.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: (1) the client sends the access token containing, or referencing, the authorization information to the RS, that may be used for subsequent resource requests by the client, and (2) the client makes the resource access request, using the - communication security protocol and other RS Information + communication security protocol and other Access Information obtained from the AS. The Client and the RS mutually authenticate using the security protocol specified in the profile (see step B) and the keys - obtained in the access token or the RS Information. The RS + obtained in the access token or the Access Information. The RS verifies that the token is integrity protected by the AS and 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 @@ -602,21 +605,21 @@ credentials need to be provided to the parties before or during the authentication protocol is executed, and may be re-used for subsequent token requests. Proof-of-Possession The ACE framework, by default, implements proof-of-possession for access tokens, i.e., that the token holder can prove being a holder of the key bound to the token. The binding is provided by the "cnf" claim [I-D.ietf-ace-cwt-proof-of-possession] indicating what key is used for proof-of-possession. If a client needs to - submit a new access token e.g., to obtain additional access + submit a new access token, e.g., to obtain additional access rights, they can request that the AS binds this token to the same key as the previous one. ACE Profiles The client or RS may be limited in the encodings or protocols it supports. To support a variety of different deployment settings, specific interactions between client and RS are defined in an ACE profile. In ACE framework the AS is expected to manage the matching of compatible profile choices between a client and an RS. The AS informs the client of the selected profile using the @@ -651,23 +654,23 @@ 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. - [I-D.ietf-core-resource-directory]). + Instead of the initial Unauthorized Resource Request message, other + discovery methods may be used, or the client may be pre-provisioned + with the address of the AS. 5.1.1. Unauthorized Resource Request Message The optional Unauthorized Resource Request message is a request for a resource hosted by RS for which no proper authorization is granted. RS MUST treat any request for a protected resource as Unauthorized Resource Request message when any of the following holds: o The request has been received on an unprotected channel. o RS has no valid access token for the sender of the request @@ -724,51 +727,46 @@ Figure 3: AS Information payload example In this example, the attribute AS points the receiver of this message to the URI "coaps://as.example.com/token" to request access permissions. The originator of the AS Information payload (i.e., RS) uses a local clock that is loosely synchronized with a time scale common between RS and AS (e.g., wall clock time). Therefore, it has included a parameter "nonce" for replay attack prevention. - Note: There is an ongoing discussion how freshness of access - tokens - can be achieved in constrained environments. This specification - for now assumes that RS and AS do not have a common understanding - of time that allows RS to achieve its security objectives without - explicitly adding a nonce. - Figure 4 illustrates the mandatory to use binary encoding of the message payload shown in Figure 3. a2 # map(2) 00 # unsigned(0) (=AS) 78 1c # text(28) 636f6170733a2f2f61732e657861 6d706c652e636f6d2f746f6b656e # "coaps://as.example.com/token" 05 # unsigned(5) (=nonce) 45 # bytes(5) e0a156bb3f Figure 4: AS Information example encoded in CBOR 5.2. Authorization Grants To request an access token, the client obtains authorization from the resource owner or uses its client credentials as grant. The authorization is expressed in the form of an authorization grant. - The OAuth framework 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). + The OAuth framework [RFC6749] defines four grant types. The grant + types can be split up into two groups, those granted on behalf of the + resource owner (password, authorization code, implicit) and those for + the client (client credentials). Further grant types have been added + later, such as [RFC7521] defining an assertion-based authorization + grant. The grant type is selected depending on the use case. In cases where the client acts on behalf of the resource owner, authorization code grant is recommended. If the client acts on behalf of the resource owner, but does not have any display or very limited interaction possibilities it is recommended to use the device code grant defined in [I-D.ietf-oauth-device-flow]. In cases where the client does not act on behalf of the resource owner, client credentials grant is recommended. @@ -981,21 +980,21 @@ response code equivalent to the CoAP response code 2.01 (Created). If client request was invalid, or not authorized, the AS returns an error response as described in Section 5.6.3. Note that the AS decides which token type and profile to use when issuing a successful response. It is assumed that the AS has prior knowledge of the capabilities of the client and the RS (see Appendix D. This prior knowledge may, for example, be set by the use of a dynamic client registration protocol exchange [RFC7591]. - The content of the successful reply is the RS Information. When + The content of the successful reply is the Access Information. When using CBOR payloads, the content MUST be encoded as CBOR map, containing parameters as specified in Section 5.1 of [RFC6749]. 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. @@ -1014,44 +1013,45 @@ 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 [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. + client) whereas the Access 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 + Figure 8 summarizes the parameters that may be part of the Access Information. /-------------------+-----------------\ | Parameter name | Specified in | |-------------------+-----------------| | access_token | RFC 6749 | | token_type | RFC 6749 | | expires_in | RFC 6749 | | refresh_token | RFC 6749 | | scope | RFC 6749 | | state | RFC 6749 | | error | RFC 6749 | | error_description | RFC 6749 | | error_uri | RFC 6749 | | profile | [this document] | | cnf | [this document] | | rs_cnf | [this document] | \-------------------+-----------------/ - Figure 8: RS Information parameters + Figure 8: Access Information parameters Figure 9 shows a response containing a token and a "cnf" parameter with a symmetric proof-of-possession key. Note that transport layer security with CBOR encoding is assumed in this example, therefore the Content-Type is "application/cbor". Header: Created (Code=2.01) Content-Type: "application/cbor" Payload: { @@ -1142,50 +1142,50 @@ | 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.3. Token Type - The token_type parameter is defined in [RFC6749], allowing the AS to + The "token_type" parameter, defined in [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 is performed MUST be specified by the - profiles. + 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 be CBOR text strings, if a CBOR encoding is used. - In this framework token type "pop" MUST be assumed by default if the - AS does not provide a different value. + 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.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 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 + and the Access 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 the "cnf" claim specified in [I-D.ietf-ace-cwt-proof-of-possession] when used with a CBOR encoding. When these parameters are used in JSON then the formatting and semantics of the "cnf" claim specified @@ -1205,25 +1205,24 @@ 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. + used, since the client cannot 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 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 [RFC8392]. @@ -1252,21 +1251,21 @@ | profile | 26 | unsigned integer | | rs_cnf | 31 | map | \-------------------+----------+---------------------/ Figure 12: CBOR mappings used in token requests 5.7. The 'Introspect' 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 + for metadata about a given token, e.g., validity or scope. Analogous to the protocol defined in RFC 7662 [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 RS and the introspection endpoint at the AS MUST be integrity protected and encrypted. Furthermore AS and RS MUST perform mutual authentication. Finally the AS SHOULD verify that the RS has the right to access introspection information about the provided token. Profiles of this framework that support @@ -1294,80 +1293,85 @@ 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". + Figure 14 shows the decoded payload. Header: POST (Code=0.02) Uri-Host: "as.example.com" Uri-Path: "introspect" Content-Type: "application/cose+cbor" Payload: + ... COSE content ... + + Figure 13: Example introspection request. + { "token" : b64'7gj0dXJQ43U', "token_type_hint" : "pop" } - Figure 13: Example introspection request. + Figure 14: Decoded token. 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 map including with the same required and optional parameters as in - Section 2.2. of RFC 7662 [RFC7662] with the following additions: + 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 + 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 + For example, Figure 15 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, "scope" : "read", "profile" : "coap_dtls", "cnf" : { "COSE_Key" : { "kty" : "Symmetric", "kid" : b64'39Gqlw', "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' } } } - Figure 14: Example introspection response. + Figure 15: 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. If CoAP is used the payload MUST be encoded as a CBOR map. @@ -1386,21 +1390,21 @@ 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 If CBOR is used, the introspection request and response parameters - MUST be mapped to CBOR types as specified in Figure 15, using the + MUST be mapped to CBOR types as specified in Figure 16, using the given integer abbreviation for the map key. Note that we have aligned these abbreviations with the claim abbreviations defined in [RFC8392]. /-----------------+----------+----------------------------------\ | Parameter name | CBOR Key | Value Type | |-----------------+----------+----------------------------------| | iss | 1 | text string | | sub | 2 | text string | @@ -1414,21 +1418,21 @@ | token_type | 20 | text string | | username | 22 | text string | | cnf | 25 | map | | profile | 26 | unsigned integer | | token | 27 | byte string | | token_type_hint | 28 | text string | | active | 29 | True or False | | rs_cnf | 30 | map | \-----------------+----------+----------------------------------/ - Figure 15: CBOR Mappings to Token Introspection Parameters. + Figure 16: CBOR Mappings to Token Introspection Parameters. 5.8. The Access Token This framework RECOMMENDS the use of CBOR web token (CWT) as specified in [RFC8392]. In order to facilitate offline processing of access tokens, this 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. @@ -1467,29 +1471,32 @@ token is valid, the RS MUST respond to the POST request with 2.01 (Created). This response MAY contain an identifier of the token (e.g., the cti for a CWT) as a payload, in order to allow the client to refer to the 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. - If the token is not valid, the RS MUST respond with a response code - equivalent to the CoAP code 4.01 (Unauthorized). If the token is - valid but the audience of the token does not match the RS, the RS - 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. + If the payload sent to the authz-info endpoint does not parse to a + token, the RS MUST respond with a response code equivalent to the + CoAP code 4.00 (Bad Request). If the token is not valid, the RS MUST + respond with a response code equivalent to the CoAP code 4.01 + (Unauthorized). If the token is valid but the audience of the token + does not match the RS, the RS 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, 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. @@ -1515,21 +1522,21 @@ 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 + 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 @@ -1625,42 +1632,43 @@ possession SHOULD NOT be targeted at an audience that contains more than one RS, since otherwise any RS in the audience that receives that access token can impersonate the client towards the other members of the audience. 6.1. Unprotected AS Information Initially, no secure channel exists to protect the communication between C and RS. Thus, C cannot determine if the AS information 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. + request (see 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 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. + The 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 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 - way that the security of a protocol interaction does not depend on - the specific security mechanisms used in other protocol interactions. + There may be use cases were different profiles of this framework are + combined. For example, an MQTT-TLS profile is used between the + client and the RS in combination with a CoAP-DTLS profile for + interactions between the client and the AS. Ideally, profiles should + be designed in a way that the security of system should not depend on + the specific security mechanisms used in individual protocol + interactions. 6.4. Error responses The various error responses defined in this framework may leak information to an adversary. For example errors responses for requests to the Authorization Information endpoint can reveal information about an otherwise opaque access token to an adversary who has intercepted this token. This framework is written under the assumption that, in general, the benefits of detailed error messages outweigh the risk due to information leakage. For particular use @@ -1677,33 +1685,33 @@ the client credentials grant is used, the AS can track what kind of access the client intends to perform. With other grants this can be prevented by the Resource Owner. To do so, the resource owner needs to bind the grants it issues to anonymous, ephemeral credentials that do not allow the AS to link different grants and thus different access token requests by the same client. If access tokens are only integrity protected and not encrypted, they may reveal information to attackers listening on the wire, or able to acquire the access tokens in some other way. In the case of CWTs the - token may e.g., reveal the audience, the scope and the confirmation + token may, e.g., reveal the audience, the scope and the confirmation method used by the client. The latter may reveal the identity of the 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 (c.f. + 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. 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 @@ -1739,21 +1748,21 @@ 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 the registry are: Name The OAuth Error Code name, refers to the name in Section 5.2. - of [RFC6749] e.g., "invalid_request". + of [RFC6749], e.g., "invalid_request". 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. @@ -1803,21 +1812,21 @@ 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 registry are: Name The name of token type as registered in the OAuth Access Token - Types registry e.g., "Bearer". + Types registry, e.g., "Bearer". 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 @@ -1889,21 +1899,21 @@ 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 registry are: Name The OAuth Parameter name, refers to the name in the OAuth - parameter registry e.g., "client_id". + parameter registry, e.g., "client_id". 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 @@ -1936,34 +1946,34 @@ 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 registry are: Name The OAuth Parameter name, refers to the name in the OAuth - parameter registry e.g., "client_id". + parameter registry, e.g., "client_id". 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. + This registry will be initially populated by the values in Figure 16. 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 [IANA.JsonWebTokenClaims]: o Claim Name: "scope" o Claim Description: The scope of an access token as defined in @@ -2096,35 +2106,25 @@ 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-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-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. + Constrained Devices", draft-ietf-oauth-device-flow-10 + (work in progress), June 2018. [Margi10impact] Margi, C., de Oliveira, B., de Sousa, G., Simplicio Jr, M., Barreto, P., Carvalho, T., Naeslund, M., and R. Gold, "Impact of Operating Systems on Wireless Sensor Networks (Security) Applications and Testbeds", Proceedings of the 19th International Conference on Computer Communications and Networks (ICCCN), 2010 August. [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", @@ -2195,55 +2195,60 @@ [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . + [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 + Authorization Server Metadata", RFC 8414, + DOI 10.17487/RFC8414, June 2018, . + Appendix A. Design Justification This section provides further insight into the design decisions of the solution documented in this document. Section 3 lists several building blocks and briefly summarizes their importance. The justification for offering some of those building blocks, as opposed to using OAuth 2.0 as is, is given below. Common IoT constraints are: Low Power Radio: Many IoT devices are equipped with a small battery which needs to last for a long time. For many constrained wireless devices, the highest energy cost is associated to transmitting or receiving - messages (roughly by a factor of 10 compared to e.g. AES) + messages (roughly by a factor of 10 compared to AES) [Margi10impact]. It is therefore important to keep the total communication overhead low, including minimizing the number and size of messages sent and received, which has an impact of choice on the message format and protocol. By using CoAP over UDP and CBOR encoded messages, some of these aspects are addressed. Security protocols contribute to the communication overhead and can, in some cases, be optimized. For example, authentication and key establishment may, in certain cases where security requirements allow, be replaced by provisioning of security context by a trusted third party, using transport or application layer security. Low CPU Speed: Some IoT devices are equipped with processors that are significantly slower than those found in most current devices on the Internet. This typically has implications on what timely cryptographic operations a device is capable of performing, which - in turn impacts e.g., protocol latency. Symmetric key + in turn impacts, e.g., protocol latency. Symmetric key cryptography may be used instead of the computationally more expensive public key cryptography where the security requirements so allows, but this may also require support for trusted third party assisted secret key establishment using transport or application layer security. Small Amount of Memory: Microcontrollers embedded in IoT devices are often equipped with small amount of RAM and flash memory, which places limitations what kind of processing can be performed and how much code can be @@ -2296,29 +2301,29 @@ is RECOMMENDED. Furthermore where self-contained tokens are 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 + 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. - RS Information: + Access Information: - This framework defines the name "RS Information" for data + 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 includes the "profile" and the "rs_cnf" parameters. This aims at enabling scenarios, where a powerful client, supporting multiple profiles, needs to interact with a 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 @@ -2331,22 +2336,22 @@ could be able to steal bearer tokens and use them to gain unauthorized access. Auth-Info endpoint: This framework introduces a new way of providing access tokens to a RS by exposing a authz-info endpoint, to which access tokens can be POSTed. This aims at reducing the size of the request message and the code complexity at the RS. The size of the request message is problematic, since many constrained protocols have - severe message size limitations at the physical layer (e.g. in the - order of 100 bytes). This means that larger packets get + severe message size limitations at the physical layer (e.g., in + the order of 100 bytes). This means that larger packets get fragmented, which in turn combines badly with the high rate of packet loss, and the need to retransmit the whole message if one packet gets lost. Thus separating sending of the request and sending of the access tokens helps to reduce fragmentation. Client Credentials Grant: This framework RECOMMENDS the use of the client credentials grant for machine-to-machine communication use cases, where manual intervention of the resource owner to produce a grant token is not @@ -2408,40 +2412,40 @@ * Authenticate clients that wish to request a token. * Process a token request using the authorization policies configured for the RS. * Optionally: Expose the introspection endpoint that allows RS's to submit token introspection requests. * If providing an introspection endpoint: Authenticate RSs that wish to get an introspection response. * If providing an introspection endpoint: Process token introspection requests. * Optionally: Handle token revocation. - * Optionally: Provide discovery metadata. See - [I-D.ietf-oauth-discovery] + * Optionally: Provide discovery metadata. See [RFC8414] Client * Discover the AS in charge of the RS that is to be targeted with a request. * Submit the token request (see step (A) of Figure 1). + Authenticate to the AS. + Optionally (if not pre-configured): Specify which RS, which resource(s), and which action(s) the request(s) will target. + If raw public keys (rpk) or certificates are used, make sure the AS has the right rpk or certificate for this client. - * Process the access token and RS Information (see step (B) of - Figure 1). + * Process the access token and Access Information (see step (B) + of Figure 1). - + Check that the RS Information provides the necessary + + Check that the Access Information provides the necessary security parameters (e.g., PoP key, information on communication security protocols supported by the RS). + * Send the token and request to the RS (see step (C) of Figure 1). + Authenticate towards the RS (this could coincide with the proof of possession process). + Transmit the token as specified by the AS (default is to the authz-info endpoint, alternative options are specified by profiles). + Perform the proof-of-possession procedure as specified by the profile in use (this may already have been taken care of @@ -2545,37 +2550,37 @@ In this scenario, the case where the resource server is offline is considered, i.e., it is not connected to the AS at the time of the access request. This access procedure involves steps A, B, C, and F of Figure 1. Since the resource server must be able to verify the access token locally, self-contained access tokens must be used. This example shows the interactions between a client, the authorization server and a temperature sensor acting as a resource - server. Message exchanges A and B are shown in Figure 16. + server. Message exchanges A and B are shown in Figure 17. A: The client first generates a public-private key pair used for communication security with the RS. The client sends the POST request to the token endpoint at the AS. The security of this request can be transport or application layer. It is up the the communication security profile to define. In the example transport layer identification of the AS is done and the client identifies with client_id and client_secret as in classic OAuth. The request contains the public key of the client and the Audience parameter set to "tempSensorInLivingRoom", a value that the temperature sensor identifies itself with. The AS evaluates the request and authorizes the client to access the resource. - B: The AS responds with a PoP access token and RS Information. + B: The AS responds with a PoP access token and Access Information. The PoP access token contains the public key of the client, and - the RS Information contains the public key of the RS. For + the Access Information contains the public key of the RS. For communication security this example uses DTLS RawPublicKey between the client and the RS. The issued token will have a short validity time, i.e., "exp" close to "iat", to protect the RS from replay attacks. The token includes the claim such as "scope" with the authorized access that an owner of the temperature device can enjoy. In this example, the "scope" claim, issued by the AS, informs the RS that the owner of the token, that can prove the possession of a key is authorized to make a GET request against the /temperature resource and a POST request on the /firmware resource. Note that the syntax and semantics of the scope claim @@ -2593,26 +2598,26 @@ A: +-------->| Header: POST (Code=0.02) | POST | Uri-Path:"token" | | Content-Type: application/cbor | | Payload: | | B: |<--------+ Header: 2.05 Content | 2.05 | Content-Type: application/cbor | | Payload: | | - Figure 16: Token Request and Response Using Client Credentials. + Figure 17: Token Request and Response Using Client Credentials. The information contained in the Request-Payload and the Response- - Payload is shown in Figure 17. Note that a transport layer security - based communication security profile is used in this example, - therefore the Content-Type is "application/cbor". + Payload is shown in Figure 18. Note that a TLS/DTLS-based + communication security profile is used in this example. Hence, the + Content-Type is "application/cbor". Request-Payload : { "grant_type" : "client_credentials", "aud" : "tempSensorInLivingRoom", "client_id" : "myclient", "client_secret" : "qwerty" } Response-Payload : @@ -2624,68 +2629,67 @@ "COSE_Key" : { "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kty" : "EC", "crv" : "P-256", "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' } } } - Figure 17: Request and Response Payload Details. + Figure 18: Request and Response Payload Details. - The content of the access token is shown in Figure 18. + The content of the access token is shown in Figure 19. { "aud" : "tempSensorInLivingRoom", "iat" : "1360189224", "exp" : "1360289224", "scope" : "temperature_g firmware_p", "cnf" : { "COSE_Key" : { "kid" : b64'1Bg8vub9tLe1gHMzV76e8', "kty" : "EC", "crv" : "P-256", "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' } } } - Figure 18: Access Token including Public Key of the Client. + Figure 19: Access Token including Public Key of the Client. - Messages C and F are shown in Figure 19 - Figure 20. + Messages C and F are shown in Figure 20 - Figure 21. C: The client then sends the PoP access token to the authz-info endpoint at the RS. This is a plain CoAP request, i.e., no - transport or application layer security between client and RS, - since the token is integrity protected between the AS and RS. The - RS verifies that the PoP access token was created by a known and - trusted AS, is valid, and responds to the client. The RS caches - the security context together with authorization information about - this client contained in the PoP access token. + transport or application layer security is used between client and + RS since the token is integrity protected between the AS and RS. + The RS verifies that the PoP access token was created by a known + and trusted AS, is valid, and has been issued to the client. The + RS caches the security context together with authorization + information about this client contained in the PoP access token. Resource Client Server | | C: +-------->| Header: POST (Code=0.02) | POST | Uri-Path:"authz-info" | | Payload: SlAV32hkKG ... | | |<--------+ Header: 2.04 Changed | 2.04 | | | - Figure 19: Access Token provisioning to RS + Figure 20: Access Token provisioning to RS The client and the RS runs the DTLS handshake using the raw public keys established in step B and C. - The client sends the CoAP request GET to /temperature on RS over DTLS. The RS verifies that the request is authorized, based on previously established security context. F: The RS responds with a resource representation over DTLS. Resource Client Server | | |<=======>| DTLS Connection Establishment | | using Raw Public Keys @@ -2692,21 +2696,21 @@ | | +-------->| Header: GET (Code=0.01) | GET | Uri-Path: "temperature" | | | | | | F: |<--------+ Header: 2.05 Content | 2.05 | Payload: | | - Figure 20: Resource Request and Response protected by DTLS. + Figure 21: Resource Request and Response protected by DTLS. E.2. Introspection Aided Token Validation In this deployment scenario it is assumed that a client is not able to access the AS at the time of the access request, whereas the RS is assumed to be connected to the back-end infrastructure. Thus the RS can make use of token introspection. This access procedure involves steps A-F of Figure 1, but assumes steps A and B have been carried out during a phase when the client had connectivity to AS. @@ -2715,21 +2719,21 @@ Since the client is constrained, the token will not be self contained (i.e. not a CWT) but instead just a reference. The resource server uses its connectivity to learn about the claims associated to the access token by using introspection, which is shown in the example below. In the example interactions between an offline client (key fob), a RS (online lock), and an AS is shown. It is assumed that there is a provisioning step where the client has access to the AS. This corresponds to message exchanges A and B which are shown in - Figure 21. + Figure 22. Authorization consent from the resource owner can be pre-configured, but it can also be provided via an interactive flow with the resource owner. An example of this for the key fob case could be that the resource owner has a connected car, he buys a generic key that he wants to use with the car. To authorize the key fob he connects it to his computer that then provides the UI for the device. After that OAuth 2.0 implicit flow can used to authorize the key for his car at the the car manufacturers AS. @@ -2742,43 +2746,44 @@ A: The client sends the request using POST to the token endpoint at AS. The request contains the Audience parameter set to "PACS1337" (PACS, Physical Access System), a value the that the online door in question identifies itself with. The AS generates an access token as an opaque string, which it can match to the specific client, a targeted audience and a symmetric key. The security is provided by identifying the AS on transport layer using a pre shared security context (psk, rpk or certificate) and then the client is identified using client_id and client_secret as in classic OAuth. - B: The AS responds with the an access token and RS Information, - the latter containing a symmetric key. Communication security - between C and RS will be DTLS and PreSharedKey. The PoP key is - used as the PreSharedKey. + + B: The AS responds with the an access token and Access + Information, the latter containing a symmetric key. Communication + security between C and RS will be DTLS and PreSharedKey. The PoP + key is used as the PreSharedKey. Authorization Client Server | | | | A: +-------->| Header: POST (Code=0.02) | POST | Uri-Path:"token" | | Content-Type: application/cbor | | Payload: | | B: |<--------+ Header: 2.05 Content | | Content-Type: application/cbor | 2.05 | Payload: | | - Figure 21: Token Request and Response using Client Credentials. + Figure 22: Token Request and Response using Client Credentials. The information contained in the Request-Payload and the Response- - Payload is shown in Figure 22. + Payload is shown in Figure 23. Request-Payload: { "grant_type" : "client_credentials", "aud" : "lockOfDoor4711", "client_id" : "keyfob", "client_secret" : "qwerty" } Response-Payload: @@ -2789,21 +2794,21 @@ "cnf" : { "COSE_Key" : { "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kty" : "oct", "alg" : "HS256", "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' } } } - Figure 22: Request and Response Payload for C offline + Figure 23: Request and Response Payload for C offline The access token in this case is just an opaque string referencing the authorization information at the AS. C: Next, the client POSTs the access token to the authz-info endpoint in the RS. This is a plain CoAP request, i.e., no DTLS between client and RS. Since the token is an opaque string, the RS cannot verify it on its own, and thus defers to respond the client with a status code until after step E. D: The RS forwards the token to the introspection endpoint on the @@ -2837,43 +2842,43 @@ | | | | E: |<---------+ Header: 2.05 Content | | 2.05 | Content-Type: "application/cbor" | | | Payload: | | | | | |<--------+ Header: 2.01 Created | 2.01 | | | - Figure 23: Token Introspection for C offline + Figure 24: Token Introspection for C offline The information contained in the Request-Payload and the Response- - Payload is shown in Figure 24. + Payload is shown in Figure 25. Request-Payload: { "token" : b64'SlAV32hkKG...', "client_id" : "FrontDoor", "client_secret" : "ytrewq" } Response-Payload: { "active" : true, "aud" : "lockOfDoor4711", "scope" : "open, close", "iat" : 1311280970, "cnf" : { "kid" : b64'JDLUhTMjU2IiwiY3R5Ijoi ...' } } - Figure 24: Request and Response Payload for Introspection + Figure 25: Request and Response Payload for Introspection The client uses the symmetric PoP key to establish a DTLS PreSharedKey secure connection to the RS. The CoAP request PUT is sent to the uri-path /state on the RS, changing the state of the door to locked. F: The RS responds with a appropriate over the secure DTLS channel. Resource Client Server @@ -2882,65 +2887,72 @@ | | 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 OSCORE + Figure 26: Resource request and response protected by OSCORE Appendix F. Document Updates RFC EDITOR: PLEASE REMOVE THIS SECTION. -F.1. Version -11 to -12 +F.1. Version -12 to -13 + + o Changed "Resource Information" to "Access Information" to avoid + confusion. + o Clarified section about AS discovery. + o Editorial changes + +F.2. 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 +F.3. Version -10 to -11 o Fixed some CBOR data type errors. o Updated boilerplate text -F.3. Version -09 to -10 +F.4. 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.4. Version -08 to -09 +F.5. 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.5. Version -07 to -08 +F.6. 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. @@ -2950,99 +2962,100 @@ discovery information, combining profiles and leakage through error responses. o Added privacy considerations about leakage through unprotected AS discovery. 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.6. Version -06 to -07 +F.7. Version -06 to -07 o Various clarifications added. o Fixed erroneous author email. -F.7. Version -05 to -06 +F.8. 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.8. Version -04 to -05 +F.9. Version -04 to -05 o Added RFC 2119 language to the specification of the required behavior of profile specifications. o Added Section 5.3 on the relation to the OAuth2 grant types. o Added CBOR abbreviations for error and the error codes defined in OAuth2. o Added clarification about token expiration and long-running requests in Section 5.8.3 o Added security considerations about tokens with symmetric pop keys valid for more than one RS. o Added privacy considerations section. o Added IANA registry mapping the confirmation types from RFC 7800 to equivalent COSE types. o Added appendix D, describing assumptions about what the AS knows about the client and the RS. -F.9. Version -03 to -04 +F.10. 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.10. Version -02 to -03 +F.11. 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.11. Version -01 to -02 +F.12. Version -01 to -02 o Restructured to remove communication security parts. These shall now be defined in profiles. o Restructured section 5 to create new sections on the OAuth endpoints token, introspection and authz-info. o Pulled in material from draft-ietf-oauth-pop-key-distribution in order to define proof-of-possession key distribution. o Introduced the "cnf" parameter as defined in RFC7800 to reference or transport keys used for proof of possession. o Introduced the "client-token" to transport client information from the AS to the client via the RS in conjunction with introspection. o Expanded the IANA section to define parameters for token request, introspection and CWT claims. o Moved deployment scenarios to the appendix as examples. -F.12. Version -00 to -01 +F.13. 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 @@ -3093,15 +3106,15 @@ Email: erik@wahlstromstekniska.se Samuel Erdtman Spotify AB Birger Jarlsgatan 61, 4tr Stockholm 113 56 Sweden Email: erdtman@spotify.com Hannes Tschofenig - ARM Ltd. - Hall in Tirol 6060 + Arm Ltd. + Absam 6067 Austria Email: Hannes.Tschofenig@arm.com