--- 1/draft-ietf-ace-oauth-authz-05.txt 2017-03-13 07:14:07.281299244 -0700 +++ 2/draft-ietf-ace-oauth-authz-06.txt 2017-03-13 07:14:07.397301989 -0700 @@ -1,25 +1,25 @@ ACE Working Group L. Seitz -Internet-Draft SICS +Internet-Draft RISE SICS Intended status: Standards Track G. Selander -Expires: August 7, 2017 Ericsson +Expires: September 14, 2017 Ericsson E. Wahlstroem - + (no affiliation) S. Erdtman Spotify AB H. Tschofenig ARM Ltd. - February 3, 2017 + March 13, 2017 Authentication and Authorization for Constrained Environments (ACE) - draft-ietf-ace-oauth-authz-05 + draft-ietf-ace-oauth-authz-06 Abstract This specification defines a framework for authentication and authorization in Internet of Things (IoT) environments. The framework is based on a set of building blocks including OAuth 2.0 and CoAP, thus making a well-known and widely used authorization solution suitable for IoT devices. Existing specifications are used where possible, but where the constraints of IoT devices require it, extensions are added and profiles are defined. @@ -32,21 +32,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 August 7, 2017. + This Internet-Draft will expire on September 14, 2017. Copyright Notice Copyright (c) 2017 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 @@ -58,81 +58,85 @@ Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 9 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 13 - 6. The 'Token' Endpoint . . . . . . . . . . . . . . . . . . . . 14 - 6.1. Client Credentials and Grants . . . . . . . . . . . . . . 15 - 6.2. Client-to-AS Request . . . . . . . . . . . . . . . . . . 15 - 6.3. AS-to-Client Response . . . . . . . . . . . . . . . . . . 18 - 6.4. Error Response . . . . . . . . . . . . . . . . . . . . . 20 - 6.5. Request and Response Parameters . . . . . . . . . . . . . 20 - 6.5.1. Audience . . . . . . . . . . . . . . . . . . . . . . 20 - 6.5.2. Grant Type . . . . . . . . . . . . . . . . . . . . . 21 - 6.5.3. Token Type . . . . . . . . . . . . . . . . . . . . . 21 - 6.5.4. Profile . . . . . . . . . . . . . . . . . . . . . . . 21 - 6.5.5. Confirmation . . . . . . . . . . . . . . . . . . . . 22 - 6.6. Mapping parameters to CBOR . . . . . . . . . . . . . . . 24 - 7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . . . 24 - 7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . . . 25 - 7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . . . 25 - 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 27 - 7.4. Client Token . . . . . . . . . . . . . . . . . . . . . . 27 - 7.5. Mapping Introspection parameters to CBOR . . . . . . . . 29 - 8. The Access Token . . . . . . . . . . . . . . . . . . . . . . 29 - 8.1. The 'Authorization Information' Endpoint . . . . . . . . 30 - 8.2. Token Expiration . . . . . . . . . . . . . . . . . . . . 30 - 9. Security Considerations . . . . . . . . . . . . . . . . . . . 31 - 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 33 - 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 - 11.1. OAuth Introspection Response Parameter Registration . . 33 - 11.2. OAuth Parameter Registration . . . . . . . . . . . . . . 34 - 11.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 34 - 11.4. Token Type Mappings . . . . . . . . . . . . . . . . . . 35 - 11.4.1. Registration Template . . . . . . . . . . . . . . . 35 - 11.4.2. Initial Registry Contents . . . . . . . . . . . . . 35 - 11.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . 35 - 11.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 36 - 11.6.1. Registration Template . . . . . . . . . . . . . . . 36 - 11.7. OAuth Parameter Mappings Registry . . . . . . . . . . . 36 - 11.7.1. Registration Template . . . . . . . . . . . . . . . 36 - 11.7.2. Initial Registry Contents . . . . . . . . . . . . . 37 - 11.8. Introspection Endpoint CBOR Mappings Registry . . . . . 39 - 11.8.1. Registration Template . . . . . . . . . . . . . . . 39 - 11.8.2. Initial Registry Contents . . . . . . . . . . . . . 39 - 11.9. CoAP Option Number Registration . . . . . . . . . . . . 41 - 11.10. CWT Confirmation Methods Registry . . . . . . . . . . . 42 - 11.10.1. Registration Template . . . . . . . . . . . . . . . 42 - 11.10.2. Initial Registry Contents . . . . . . . . . . . . . 43 - 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 - 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 - 13.1. Normative References . . . . . . . . . . . . . . . . . . 44 - 13.2. Informative References . . . . . . . . . . . . . . . . . 44 - Appendix A. Design Justification . . . . . . . . . . . . . . . . 46 - Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 48 - Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 50 - Appendix D. Assumptions on AS knowledge about C and RS . . . . . 51 - Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 51 - E.1. Local Token Validation . . . . . . . . . . . . . . . . . 52 - E.2. Introspection Aided Token Validation . . . . . . . . . . 55 - Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 59 - F.1. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 59 - F.2. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 59 - F.3. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 60 - F.4. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 60 - F.5. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 60 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 61 + 5.1. Authorization Grants . . . . . . . . . . . . . . . . . . 14 + 5.2. Client Credentials . . . . . . . . . . . . . . . . . . . 15 + 5.3. AS Authentication . . . . . . . . . . . . . . . . . . . . 15 + 5.4. The 'Authorize' Endpoint . . . . . . . . . . . . . . . . 15 + 5.5. The 'Token' Endpoint . . . . . . . . . . . . . . . . . . 16 + 5.5.1. Client-to-AS Request . . . . . . . . . . . . . . . . 16 + 5.5.2. AS-to-Client Response . . . . . . . . . . . . . . . . 19 + 5.5.3. Error Response . . . . . . . . . . . . . . . . . . . 21 + 5.5.4. Request and Response Parameters . . . . . . . . . . . 21 + 5.5.4.1. Audience . . . . . . . . . . . . . . . . . . . . 21 + 5.5.4.2. Grant Type . . . . . . . . . . . . . . . . . . . 22 + 5.5.4.3. Token Type . . . . . . . . . . . . . . . . . . . 22 + 5.5.4.4. Profile . . . . . . . . . . . . . . . . . . . . . 22 + 5.5.4.5. Confirmation . . . . . . . . . . . . . . . . . . 23 + 5.5.5. Mapping parameters to CBOR . . . . . . . . . . . . . 25 + 5.6. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 25 + 5.6.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 26 + 5.6.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 26 + 5.6.3. Error Response . . . . . . . . . . . . . . . . . . . 28 + 5.6.4. Client Token . . . . . . . . . . . . . . . . . . . . 28 + 5.6.5. Mapping Introspection parameters to CBOR . . . . . . 30 + 5.7. The Access Token . . . . . . . . . . . . . . . . . . . . 30 + 5.7.1. The 'Authorization Information' Endpoint . . . . . . 31 + 5.7.2. Token Expiration . . . . . . . . . . . . . . . . . . 31 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 32 + 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 34 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 + 8.1. OAuth Introspection Response Parameter Registration . . . 34 + 8.2. OAuth Parameter Registration . . . . . . . . . . . . . . 35 + 8.3. OAuth Access Token Types . . . . . . . . . . . . . . . . 35 + 8.4. Token Type Mappings . . . . . . . . . . . . . . . . . . . 36 + 8.4.1. Registration Template . . . . . . . . . . . . . . . . 36 + 8.4.2. Initial Registry Contents . . . . . . . . . . . . . . 36 + 8.5. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 36 + 8.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 37 + 8.6.1. Registration Template . . . . . . . . . . . . . . . . 37 + 8.7. OAuth Parameter Mappings Registry . . . . . . . . . . . . 37 + 8.7.1. Registration Template . . . . . . . . . . . . . . . . 37 + 8.7.2. Initial Registry Contents . . . . . . . . . . . . . . 38 + 8.8. Introspection Endpoint CBOR Mappings Registry . . . . . . 40 + 8.8.1. Registration Template . . . . . . . . . . . . . . . . 40 + 8.8.2. Initial Registry Contents . . . . . . . . . . . . . . 40 + 8.9. CoAP Option Number Registration . . . . . . . . . . . . . 42 + 8.10. CWT Confirmation Methods Registry . . . . . . . . . . . . 43 + 8.10.1. Registration Template . . . . . . . . . . . . . . . 43 + 8.10.2. Initial Registry Contents . . . . . . . . . . . . . 44 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 45 + 10.2. Informative References . . . . . . . . . . . . . . . . . 45 + Appendix A. Design Justification . . . . . . . . . . . . . . . . 47 + Appendix B. Roles and Responsibilities . . . . . . . . . . . . . 49 + Appendix C. Requirements on Profiles . . . . . . . . . . . . . . 51 + Appendix D. Assumptions on AS knowledge about C and RS . . . . . 52 + Appendix E. Deployment Examples . . . . . . . . . . . . . . . . 52 + E.1. Local Token Validation . . . . . . . . . . . . . . . . . 53 + E.2. Introspection Aided Token Validation . . . . . . . . . . 56 + Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 60 + F.1. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 60 + F.2. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 60 + F.3. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 61 + F.4. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 61 + F.5. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 61 + F.6. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 62 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 62 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 is a complex task. @@ -228,22 +232,22 @@ designed for small code and message size, which may be used for encoding of self contained tokens, and also for encoding CoAP POST parameters and CoAP responses. A fourth building block is the compact CBOR-based secure message format COSE [I-D.ietf-cose-msg], 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 access tokens, and "client tokens" which - are defined in this framework (see Section 7.4). The default access - token format is defined in CBOR web token (CWT) + are defined in this framework (see Section 5.6.4). The default + access 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]. 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. @@ -524,21 +529,21 @@ specific credential). Access Token Response (B): If the AS successfully processes the request from the client, it returns an access token. It also returns various parameters, referred as "RS Information". In addition to the response parameters defined by OAuth 2.0 and the PoP token extension, further response parameters, such as information on which profile the client should use with the resource server(s). More - information about these parameters can be found in Section 6.5. + information about these parameters can be found in Section 5.5.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 @@ -558,37 +563,38 @@ 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, in which case the different parts of step C may be interleaved with introspection. Token Introspection Request (D): A resource server may be configured to introspect the access token by including it in a request to the /introspect endpoint at that - AS. Token introspection over CoAP is defined in Section 7 and for - HTTP in [RFC7662]. + AS. Token introspection over CoAP is defined in Section 5.6 and + for HTTP in [RFC7662]. Note that token introspection is an optional step and can be omitted if the token is self-contained and the resource server is prepared to perform the token validation on its own. Token Introspection Response (E): The AS validates the token and returns the most recent parameters, such as scope, audience, validity etc. associated with it back to the RS. The RS then uses the received parameters to process the request to either accept or to deny it. The AS can additionally return information that the RS needs to pass on to the client in the form of a client token. The latter is used to establish keys for mutual authentication between client and RS, when the client - has no direct connectivity to the AS, see Section 7.4 for details. + has no direct connectivity to the AS, see Section 5.6.4 for + details. Protected Resource (F): If the request from the client is authorized, the RS fulfills the request and returns a response with the appropriate response code. The RS uses the dynamically established keys to protect the response, according to used communication security protocol. 5. Framework @@ -646,66 +651,106 @@ 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 RECOMMENDS the use of CBOR [RFC7049] instead. The requesting device can explicitly request this encoding by setting the CoAP Accept option in the request to "application/cbor". Depending on the profile, the content MAY arrive in a different format wrapping a CBOR payload. -6. The 'Token' Endpoint +5.1. Authorization Grants - In plain OAuth 2.0 the AS provides the /token endpoint for submitting - access token requests. This framework extends the functionality of - the /token endpoint, giving the AS the possibility to help client and - RS to establish shared keys or to exchange their public keys. - Furthermore this framework defines encodings using CoAP and CBOR, in - addition to HTTP and JSON. + 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. - Authentication of the requesting client is done using client - credentials as defined by OAuth 2.0. A profile MAY specify new - client credentials types for the authentication of the client. + 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). - Profiles of this framework SHOULD specify how authentication of the - AS is done and how communication security is implemented. If nothing - is specified TLS with server certificate is assumed as defined by - OAuth 2.0. + The grant type selected depending based on the use case. In cases + where the client will act on behalf of the resource owner, + authorization code grant is recommended. If the client should to act + on be half of the user 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 will not act on be half of the resource owner, client + credentials grant is recommended. - When requesting a token the client is authenticated with client - credentials and then a grant is presented that gives the client the - right to get a token. + For details on the different grant types see the OAuth 2.0 framework. + The OAuth 2.0 framework provides an extension mechanism for defining + additional grant types so profiles of this framework MAY define + additional grant types if needed. - The figures of this section uses CBOR diagnostic notation without the - integer abbreviations for the parameters or their values for better - readability. +5.2. Client Credentials -6.1. Client Credentials and Grants + Authentication of the client is mandatory independent of the grant + type when requesting the access token from the token endpoint. In + the case of client credentials grant type the authentication and + grant coincides. - To issue a token the client MUST be authenticated and present a valid - grant for the scopes requested. + Client registration and provisioning of client credentials to the + client is out of scope for this specification. The OAuth framework, [RFC6749], defines one client credential type, client id and client secret. Profiles of this framework MAY extend with additional client credentials such as DTLS pre-shared keys or client certificates. - In the OAuth framework five grant types are defined. The grant types - can be split up into three groups, those granted on behalf of the - resource owner (password, authorization code, implicit), those for - the client (client_credentials), and those used to prolong a grant - (refresh token). +5.3. AS Authentication - profiles MAY define additional grant types if needed, e.g. a proof of - possession refresh token. + Client credential does not by default authenticate the AS that the + client connects to. In classic OAuth the AS is authenticated with a + TLS server certificate. -6.2. Client-to-AS Request + Profiles of this framework SHOULD specify how clients authenticate + the AS and how communication security is implemented, otherwise + server side TLS certificates as defined by OAuth 2.0 is required. + +5.4. The 'Authorize' Endpoint + + The authorization endpoint is used to interact with the resource + owner and obtain an authorization grant. It is used for + authorization code and implicit grant, flows that requires online + user consent. In the most common implementation a users-agent is + used and redirected from the client to the AS. The AS shows a + consent dialog and directs back to the client, with the approved + grant or an error message. + + The grant types defined in OAuth 2.0, that use the authorization + endpoint, require the use of a user agent (i.e. a browser). This + endpoint is therefore out of scope for this specification. + Implementations should use the definition and recommendations of + [RFC6749] and [RFC6819]. + + If clients involved cannot support HTTP and TLS profiles MAY define + mappings for the authorization endpoint. + +5.5. The 'Token' Endpoint + + In plain OAuth 2.0 the AS provides the /token endpoint for submitting + access token requests. This framework extends the functionality of + the /token endpoint, giving the AS the possibility to help client and + RS to establish shared keys or to exchange their public keys. + Furthermore this framework defines encodings using CoAP and CBOR, in + addition to HTTP and JSON. + + For the AS to be able to issue a token the client MUST be + authenticated and present a valid grant for the scopes requested. + + The figures of this section uses CBOR diagnostic notation without the + integer abbreviations for the parameters or their values for better + readability. + +5.5.1. Client-to-AS Request The client sends a CoAP 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] encoded as a CBOR map. In addition to these parameters, this framework defines the following parameters for requesting an access token from a /token endpoint: @@ -718,21 +762,21 @@ If a client submits a request for an access token without specifying an "aud" parameter, and the AS does not have a default "aud" value for this client, then the AS MUST respond with an error message with the CoAP response code 4.00 (Bad Request). cnf OPTIONAL. This field contains information about the key the client would like to bind to the access token for proof-of- possession. It is NOT RECOMMENDED that a client submits a symmetric key value to the AS using this parameter. See - Section 6.5.5 for more details on the formatting of the 'cnf' + Section 5.5.4.5 for more details on the formatting of the 'cnf' parameter. The following examples illustrate different types of requests for proof-of-possession tokens. Figure 2 shows a request for a token with a symmetric proof-of- possession key. Note that in this example we assume a DTLS-based communication security profile, therefore the Content-Type is "application/cbor". The content is displayed in CBOR diagnostic notation, without abbreviations for better readability. @@ -797,51 +841,51 @@ "aud" : "valve424", "scope" : "read", "cnf" : { "kid" : b64'6kg0dXJM13U' } } Figure 4: Example request for an access token bound to a key reference. -6.3. AS-to-Client Response +5.5.2. AS-to-Client Response If the access token request has been successfully verified by the AS and the client is authorized to obtain an access token corresponding to its access token request, the AS sends a response with the CoAP response code 2.01 (Created). If client request was invalid, or not authorized, the AS returns an error response as described in - Section 6.4. + Section 5.5.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. It 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 REQUIRED. This indicates the profile that the client MUST use - towards the RS. See Section 6.5.4 for the formatting of this + towards the RS. See Section 5.5.4.4 for the formatting of this parameter. cnf REQUIRED if the token type is 'pop'. OPTIONAL otherwise. If a symmetric proof-of-possession algorithms was selected, this field contains the proof-of-possession key. If an asymmetric algorithm was selected, this field contains information about the public key - used by the RS to authenticate. See Section 6.5.5 for the + used by the RS to authenticate. See Section 5.5.4.5 for the formatting of this parameter. 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. This claim is however consumed by a different party. The access token is created @@ -889,21 +933,21 @@ "kty" : "Symmetric", "kid" : b64'39Gqlw', "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' } } } Figure 6: Example AS response with an access token bound to a symmetric key. -6.4. Error Response +5.5.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. o The CoAP response code 4.00 (Bad Request) MUST be used for all @@ -921,82 +965,82 @@ | invalid_request | 0 | 0 (uint) | | invalid_client | 1 | 0 | | invalid_grant | 2 | 0 | | unauthorized_client | 3 | 0 | | unsupported_grant_type | 4 | 0 | | invalid_scope | 5 | 0 | \------------------------+----------+--------------/ Figure 7: CBOR abbreviations for common error codes -6.5. Request and Response Parameters +5.5.4. Request and Response Parameters This section provides more detail about the new parameters that can be used in access token requests and responses, as well as abbreviations for more compact encoding of existing parameters and common parameter values. -6.5.1. Audience +5.5.4.1. Audience This parameter specifies for which audience the client is requesting a token. It should be encoded as CBOR text string (major type 3). The formatting and semantics of these strings are application specific. -6.5.2. Grant Type +5.5.4.2. Grant Type The abbreviations in Figure 8 MAY be used in CBOR encodings instead of the string values defined in [RFC6749]. /--------------------+----------+--------------\ | grant_type | CBOR Key | Major Type | |--------------------+----------+--------------| | password | 0 | 0 (uint) | | authorization_code | 1 | 0 | | client_credentials | 2 | 0 | | refresh_token | 3 | 0 | \--------------------+----------+--------------/ Figure 8: CBOR abbreviations for common grant types -6.5.3. Token Type +5.5.4.3. Token Type - The toke_type parameter is defined in [RFC6749], allowing the AS to + The token_type parameter is defined in [RFC6749], allowing 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. The values in the 'token_type' parameter MUST be CBOR text strings (major type 3). In this framework token type 'pop' MUST be assumed by default if the AS does not provide a different value. -6.5.4. Profile +5.5.4.4. Profile Profiles of this framework MUST define the communication protocol and the communication security protocol between the client and the RS. Furthermore profiles MUST define proof-of-possession methods, if they support proof-of-possession tokens. A profile MUST specify an identifier that is used to uniquely identify itself in the 'profile' parameter. 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 signalling of profile specific parameters. -6.5.5. Confirmation +5.5.4.5. Confirmation The "cnf" parameter identifies or provides the key used for proof-of- possession or for authenticating the RS depending on the proof-of- possession algorithm and the context cnf is used in. This framework extends the definition of 'cnf' from [RFC7800] by adding CBOR/COSE encodings and the use of 'cnf' for transporting keys in the RS Information. The "cnf" parameter is used in the following contexts with the following meaning: @@ -1077,27 +1121,27 @@ transport in the access token, token request and token response. Figure 12 shows such an example. "cnf" : { "kid" : b64'39Gqlw' } Figure 12: A Confirmation parameter with just a key identifier This specification establishes the IANA "CWT Confirmation Methods" - registry for these types of confirmation methods in Section 11.10 and + registry for these types of confirmation methods in Section 8.10 and registers the methods defined by this specification. Other specifications can register other methods used for confirmation. The registry is meant to be analogous to the "JWT Confirmation Methods" registry defined by [RFC7800]. -6.6. Mapping parameters to CBOR +5.5.5. Mapping parameters to CBOR All OAuth parameters in access token requests and responses are mapped to CBOR types as follows and are given an integer key value to save space. /-------------------+----------+-----------------\ | Parameter name | CBOR Key | Major Type | |-------------------+----------+-----------------| | aud | 3 | 3 | | client_id | 8 | 3 (text string) | @@ -1116,41 +1160,41 @@ | expires_in | 21 | 0 | | username | 22 | 3 | | password | 23 | 3 | | refresh_token | 24 | 3 | | cnf | 25 | 5 (map) | | profile | 26 | 3 | \-------------------+----------+-----------------/ Figure 13: CBOR mappings used in token requests -7. The 'Introspect' Endpoint +5.6. The 'Introspect' Endpoint Token introspection [RFC7662] is used by the RS and potentially the client to query the AS for metadata about a given token e.g. validity or scope. Analogous to the protocol defined in RFC 7662 [RFC7662] for HTTP and JSON, this section defines adaptations to more constrained environments using CoAP and CBOR. 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 introspection MUST specify how authentication and communication security between RS and AS is implemented. The figures of this section uses CBOR diagnostic notation without the integer abbreviations for the parameters or their values for better readability. -7.1. RS-to-AS Request +5.6.1. RS-to-AS Request The RS sends a CoAP 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 the access token along with optional parameters representing additional context that is known by the RS to aid the AS in its response. The same parameters are required and optional as in section 2.1 of RFC 7662 [RFC7662]. @@ -1166,46 +1210,46 @@ Uri-Path: "introspect" Content-Type: "application/cose+cbor" Payload: { "token" : b64'7gj0dXJQ43U', "token_type_hint" : "pop" } Figure 14: Example introspection request. -7.2. AS-to-RS Response +5.6.2. AS-to-RS Response If the introspection request is authorized and successfully processed, the AS sends a response with the CoAP response 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 7.3. + described in Section 5.6.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: cnf OPTIONAL. This field contains information about the proof-of- possession key that binds the client to the access token. See - Section 6.5.5 for more details on the formatting of the 'cnf' + Section 5.5.4.5 for more details on the formatting of the 'cnf' parameter. profile OPTIONAL. This indicates the profile that the RS MUST use with - the client. See Section 6.5.4 for more details on the formatting - of this parameter. + the client. See Section 5.5.4.4 for more details on the + formatting of this parameter. client_token OPTIONAL. This parameter contains information that the RS MUST - pass on to the client. See Section 7.4 for more details. + pass on to the client. See Section 5.6.4 for more details. For example, Figure 15 shows an AS response to the introspection request in Figure 14. Note that we assume a DTLS-based communication security profile for this example, therefore the Content-Type is "application/cbor". Header: Created Code=2.01) Content-Type: "application/cbor" Payload: { @@ -1218,21 +1262,21 @@ "COSE_Key" : { "kty" : "Symmetric", "kid" : b64'39Gqlw', "k" : b64'hJtXhkV8FJG+Onbc6mxCcQh' } } } Figure 15: Example introspection response. -7.3. Error Response +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 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. o If the credentials used by the RS are invalid the AS MUST respond with the CoAP response code 4.01 (Unauthorized) and use the @@ -1245,21 +1289,21 @@ abbreviated using the codes specified in table Figure 13. o The error codes MAY be abbreviated using the codes specified in table Figure 7. 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". -7.4. Client Token +5.6.4. Client Token EDITORIAL NOTE: We have tentatively introduced this concept and would specifically like feedback whether this is viewed as a useful addition to the framework. In cases where the client has limited connectivity and needs to get access to a previously unknown resource servers, this framework suggests the following approach: The client is pre-configured with a generic, long-term access token when it is commissioned. When the client then tries to access a RS it transmits this access token. The @@ -1292,41 +1336,42 @@ | + Client Token | Figure 16: Use of the client_token parameter. The client token is a COSE_Encrypted object, containing as payload a CBOR map with the following claims: cnf REQUIRED if the token type is 'pop', OPTIONAL otherwise. Contains information about the proof-of-possession key the client is to use - with its access token. See Section 6.5.5. + with its access token. See Section 5.5.4.5. token_type - OPTIONAL. See Section 6.5.3. + OPTIONAL. See Section 5.5.4.3. profile - REQUIRED. See Section 6.5.4. + REQUIRED. See Section 5.5.4.4. rs_cnf OPTIONAL. Contains information about the key that the RS uses to authenticate towards the client. If the key is symmetric then this claim MUST NOT be part of the Client Token, since this is the same key as the one specified through the 'cnf' claim. This claim - uses the same encoding as the 'cnf' parameter. See Section 6.5.4. + uses the same encoding as the 'cnf' parameter. See + Section 5.5.4.4. The AS encrypts this token using a key shared between the AS and the client, so that only the client can decrypt it and access its payload. How this key is established is out of scope of this framework. -7.5. Mapping Introspection parameters to CBOR +5.6.5. Mapping Introspection parameters to CBOR The introspection request and response parameters are mapped to CBOR types as follows and are given an integer key value to save space. /-----------------+----------+-----------------\ | Parameter name | CBOR Key | Major Type | |-----------------+----------+-----------------| | iss | 1 | 3 (text string) | | sub | 2 | 3 | | aud | 3 | 3 | @@ -1342,39 +1387,39 @@ | profile | 26 | 0 (uint) | | token | 27 | 3 | | token_type_hint | 28 | 3 | | active | 29 | 0 | | client_token | 30 | 3 | | rs_cnf | 31 | 5 | \-----------------+----------+-----------------/ Figure 17: CBOR Mappings to Token Introspection Parameters. -8. The Access Token +5.7. The Access Token This framework RECOMMENDS the use of CBOR web token (CWT) as specified in [I-D.ietf-ace-cbor-web-token]. In order to facilitate offline processing of access tokens, this draft specifies the "cnf" and "scope" claims for 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]. The meaning of a specific scope value is application specific and expected to be known to the RS running that application. The "cnf" claim follows the same rules as specified for JSON web token in RFC7800 [RFC7800], except that it is encoded in CBOR in the - same way as specified for the "cnf" parameter in Section 6.5.5. + same way as specified for the "cnf" parameter in Section 5.5.4.5. -8.1. The 'Authorization Information' Endpoint +5.7.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 CoAP. Profiles of this framework MAY define other methods for token transport. @@ -1391,69 +1436,68 @@ the token does not match the RS, the RS MUST respond with the CoAP response 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 the CoAP response 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 /authz-info request. If the introspection - response contains a client token (Section 7.4) then this token SHALL - be included in the payload of the 2.01 (Created) response. + response contains a client token (Section 5.6.4) then this token + SHALL be included in the payload of the 2.01 (Created) response. Profiles MUST specify how the /authz-info endpoint is 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 RS MUST be prepared to store more than one token for each client, and MUST apply the combined permissions granted by all applicable, valid tokens to client requests. -8.2. Token Expiration +5.7.2. 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. We list the possibilities here including what functionality they require of the RS. o The token is a CWT/JWT and includes a 'exp' claim and possibly the 'nbf' claim. The RS verifies these by comparing them to values from its internal clock as defined in [RFC7519]. In this case the RS's internal clock must reflect the current date and time, or at least be synchronized with the AS's clock. How this clock synchronization would be performed is out of scope for this memo. o The RS verifies the validity of the token by performing an - introspection request as specified in Section 7. This requires + introspection request as specified in Section 5.6. This requires the RS to have a reliable network connection to the AS and to be able to handle two secure sessions in parallel (C to RS and AS to RS). o The RS and the AS both store a sequence number linked to their common security association. The AS increments this number for each access token it issues and includes it in the access token, - which is a CWT/JWT. The RS keeps track of the most recently - received 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. + which is a CWT. The RS keeps track of the most recently received + 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 e.g. 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. -9. Security Considerations +6. Security Considerations The entire document is about security. 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. A large range of threats can be mitigated by protecting the contents of the access token by using a digital signature or a keyed message @@ -1508,21 +1552,21 @@ SHOULD scope these access tokens to a specific permissions. Furthermore access tokens SHOULD NOT apply to an audience that comprises more than one RS, since otherwise any RS in the audience can impersonate the client towards the other members of the audience. Clients using an asymmetric key pair for proof-of-possession towards several different RS should be aware that they will need to rotate that key pair more frequently than if it was only used towards a single RS. -10. Privacy Considerations +7. Privacy Considerations Implementers and users should be aware of the privacy implications of the different possible deployments of this framework. The AS is in a very central position can potentially learn sensitive information about the clients requesting access tokens. If the client credentials grant is used, the AS can track what kind of access the client intends to perform. With other grants, the Resource Owner can bind the grants to anonymous (rotating) credentials, that do not allow the AS to link different access token @@ -1534,26 +1578,26 @@ JWTs the token may e.g. reveal the audience, the scope and the confirmation method used by the client. The latter may reveal the client's identity. 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 RS. A set of colluding RS or an attacker able to obtain the access tokens will be able to link the requests, or even to determine the client's identity. -11. IANA Considerations +8. IANA Considerations This specification registers new parameters for OAuth and establishes registries for mappings to CBOR. -11.1. OAuth Introspection Response Parameter Registration +8.1. OAuth Introspection Response Parameter Registration This specification registers the following parameters in the OAuth introspection response parameters o Name: "cnf" o Description: Key to prove the right to use an access token, as defined in [RFC7800]. o Change Controller: IESG o Specification Document(s): this document @@ -1573,149 +1618,149 @@ o Description: Information that the RS MUST pass to the client e.g. about the proof-of-possession keys. o Change Controller: IESG o Specification Document(s): this document o Name: "rs_cnf" o Description: Describes the public key the RS uses to authenticate. o Change Controller: IESG o Specification Document(s): this document -11.2. OAuth Parameter Registration +8.2. OAuth Parameter Registration This specification registers the following parameters in the OAuth Parameters Registry o Parameter name: "profile" o Parameter usage location: token request, and token response o Change Controller: IESG o Specification Document(s): this document o Name: "cnf" o Description: Key to prove the right to use an access token, as defined in [RFC7800]. o Change Controller: IESG o Specification Document(s): this document -11.3. OAuth Access Token Types +8.3. OAuth Access Token Types This specification registers the following new token type in the OAuth Access Token Types Registry o Name: "PoP" o Description: A proof-of-possession token. o Change Controller: IESG o Specification Document(s): this document -11.4. Token Type Mappings +8.4. Token Type Mappings A new registry will be requested from IANA, entitled "Token Type Mappings". The registry is to be created as Expert Review Required. -11.4.1. Registration Template +8.4.1. Registration Template Token Type: Name of token type as registered in the OAuth token type registry e.g. "Bearer". Mapped value: Integer representation for the token type value. The key value MUST be an integer in the range of 1 to 65536. Change Controller: For Standards Track RFCs, list the "IESG". For others, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included. Specification Document(s): Reference to the document or documents that specify the parameter,preferably including URIs that can be used to retrieve copies of the documents. An indication of the relevant sections may also be included but is not required. -11.4.2. Initial Registry Contents +8.4.2. Initial Registry Contents o Parameter name: "Bearer" o Mapped value: 1 o Change Controller: IESG o Specification Document(s): this document o Parameter name: "pop" o Mapped value: 2 o Change Controller: IESG o Specification Document(s): this document -11.5. CBOR Web Token Claims +8.5. CBOR Web Token Claims This specification registers the following new claims in the CBOR Web Token (CWT) registry: o Claim Name: "scope" o Claim Description: The scope of an access token as defined in [RFC6749]. o Change Controller: IESG o Specification Document(s): this document o Claim Name: "cnf" o Claim Description: The proof-of-possession key of an access token as defined in [RFC7800]. o Change Controller: IESG o Specification Document(s): this document -11.6. ACE 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. -11.6.1. Registration Template +8.6.1. Registration Template Profile name: Name of the profile to be included in the profile attribute. Profile description: Text giving an overview of the profile and the context it is developed for. Profile ID: Integer value to identify the profile. The value MUST be an integer in the range of 1 to 65536. Change Controller: For Standards Track RFCs, list the "IESG". For others, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included. Specification Document(s): Reference to the document or documents that specify the parameter,preferably including URIs that can be used to retrieve copies of the documents. An indication of the relevant sections may also be included but is not required. -11.7. OAuth Parameter Mappings Registry +8.7. OAuth 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. -11.7.1. Registration Template +8.7.1. Registration Template Parameter name: OAuth Parameter name, refers to the name in the OAuth parameter registry e.g. "client_id". CBOR key value: Key value for the claim. The key value MUST be an integer in the range of 1 to 65536. Change Controller: For Standards Track RFCs, list the "IESG". For others, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included. Specification Document(s): Reference to the document or documents that specify the parameter,preferably including URIs that can be used to retrieve copies of the documents. An indication of the relevant sections may also be included but is not required. -11.7.2. Initial Registry Contents +8.7.2. Initial Registry Contents o Parameter name: "aud" o CBOR key value: 3 o Change Controller: IESG o Specification Document(s): this document o Parameter name: "client_id" o CBOR key value: 8 o Change Controller: IESG o Specification Document(s): this document @@ -1802,45 +1847,45 @@ o Parameter name: "cnf" o CBOR key value: 25 o Change Controller: IESG o Specification Document(s): this document o Parameter name: "profile" o CBOR key value: 26 o Change Controller: IESG o Specification Document(s): this document -11.8. Introspection Endpoint CBOR Mappings Registry +8.8. 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. -11.8.1. Registration Template +8.8.1. Registration Template Response parameter name: Name of the response parameter as defined in the "OAuth Token Introspection Response" registry e.g. "active". CBOR key value: Key value for the claim. The key value MUST be an integer in the range of 1 to 65536. Change Controller: For Standards Track RFCs, list the "IESG". For others, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included. Specification Document(s): Reference to the document or documents that specify the parameter,preferably including URIs that can be used to retrieve copies of the documents. An indication of the relevant sections may also be included but is not required. -11.8.2. Initial Registry Contents +8.8.2. Initial Registry Contents o Response parameter name: "iss" o CBOR key value: 1 o Change Controller: IESG o Specification Document(s): this document o Response parameter name: "sub" o CBOR key value: 2 o Change Controller: IESG o Specification Document(s): this document @@ -1917,21 +1962,21 @@ o Response parameter name: "client_token" o CBOR key value: 30 o Change Controller: IESG o Specification Document(s): this document o Response parameter name: "rs_cnf" o CBOR key value: 31 o Change Controller: IESG o Specification Document(s): this document -11.9. CoAP Option Number Registration +8.9. 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]. Name Access-Token Number @@ -1949,28 +1994,28 @@ Yes Format Based on the observer the format is perceived differently. Opaque data to the client and CWT or reference token to the RS. Length Less then 255 bytes -11.10. CWT Confirmation Methods Registry +8.10. CWT Confirmation Methods Registry This specification establishes the IANA "CWT Confirmation Methods" registry for CWT "cnf" member values. The registry records the confirmation method member and a reference to the specification that defines it. -11.10.1. Registration Template +8.10.1. Registration Template Confirmation Method Name: The name requested (e.g., "kid"). This name is intended to be human readable and be used for debugging purposes. It is case sensitive. Names may not match other registered names in a case- insensitive manner unless the Designated Experts state that there is a compelling reason to allow an exception. Confirmation Method Value: Integer representation for the confirmation method value. @@ -1986,21 +2031,21 @@ name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included. Specification Document(s): Reference to the document or documents that specify the parameter, preferably including URIs that can be used to retrieve copies of the documents. An indication of the relevant sections may also be included but is not required. -11.10.2. Initial Registry Contents +8.10.2. Initial Registry Contents o Confirmation Method Name: "COSE_Key" o Confirmation Method Value: 1 o Confirmation Method Description: A COSE_Key that is either a public key or a symmetric key. o Change Controller: IESG o Specification Document(s): this document o Confirmation Method Name: "COSE_Encrypted" o Confirmation Method Value: 2 @@ -2008,37 +2053,37 @@ wraps a COSE_Key containing a symmetric key. o Change Controller: IESG o Specification Document(s): this document o Confirmation Method Name: "Key Identifier" o Confirmation Method Value: 3 o Confirmation Method Description: A key identifier. o Change Controller: IESG o Specification Document(s): this document -12. Acknowledgments +9. Acknowledgments We would like to thank 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. Finally, we would like to thank the ACE working group in general for their feedback. We would like to thank the authors of draft-ietf-oauth-pop-key- distribution, from where we copied large parts of our security considerations. Ludwig Seitz and Goeran Selander worked on this document as part of the CelticPlus project CyberWI, with funding from Vinnova. -13. References -13.1. Normative References +10. References +10.1. Normative References [I-D.ietf-cose-msg] Schaad, J., "CBOR Object Signing and Encryption (COSE)", draft-ietf-cose-msg-24 (work in progress), November 2016. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . @@ -2053,47 +2098,48 @@ [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, . -13.2. Informative References +10.2. Informative References [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-04 (work in - progress), September 2016. + environments", draft-ietf-ace-actors-05 (work in + progress), March 2017. [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-02 - (work in progress), January 2017. + "CBOR Web Token (CWT)", draft-ietf-ace-cbor-web-token-03 + (work in progress), March 2017. [I-D.ietf-core-object-security] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security of CoAP (OSCOAP)", draft-ietf-core- object-security-01 (work in progress), December 2016. [I-D.ietf-oauth-device-flow] - Denniss, W., Myrseth, S., Bradley, J., Jones, M., and H. - Tschofenig, "OAuth 2.0 Device Flow", draft-ietf-oauth- - device-flow-03 (work in progress), July 2016. + 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-04 + (work in progress), February 2017. [I-D.ietf-oauth-native-apps] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", - draft-ietf-oauth-native-apps-07 (work in progress), - January 2017. + draft-ietf-oauth-native-apps-09 (work in progress), March + 2017. [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, . [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, . @@ -2345,42 +2391,43 @@ security. Appendix C. Requirements on Profiles This section lists the requirements on profiles of this framework, for the convenience of a profile designer. o Optionally Specify the discovery process of how the client finds the right AS for an RS it wants to send a request to. Section 4 o Specify the communication protocol the client and RS the must use - (e.g. CoAP). Section 5 and Section 6.5.4 + (e.g. CoAP). Section 5 and Section 5.5.4.4 o Specify the security protocol the client and RS must use to protect their communication (e.g. OSCOAP or DTLS over CoAP). This must provide encryption and integrity protection. - Section 6.5.4 + Section 5.5.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 6.5.3 - o Specify a unique profile identifier. Section 6.5.4 + possession protocol. Section 5.5.4.3 + o Specify a unique profile identifier. Section 5.5.4.4 o Optionally specify how the RS talks to the AS for - introspection.Section 7 + introspection.Section 5.6 o Optionally specify how the client talks to the AS for requesting a - token. Section 6 - o Specify how/if the /authz-info endpoint is protected. Section 8.1 + token. Section 5.5 + o Specify how/if the /authz-info endpoint is protected. + Section 5.7.1 o Optionally define other methods of token transport than the - /authz-info endpoint. Section 8.1 + /authz-info endpoint. Section 5.7.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 /introspect endpoints. How this information is established is out of scope for this document. o The identifier of the client or RS. o The profiles that the client or RS supports. @@ -2754,81 +2801,90 @@ | | Payload: | | F: |<--------+ Header: 2.04 Changed | 2.04 | Payload: | | Figure 27: Resource request and response protected by OSCOAP Appendix F. Document Updates -F.1. Version -04 to -05 +F.1. 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.1, and Section 5.2. + o Added Section 5.3 on AS authentication. + o Added Section 5.4 on the Authorize endpoint. + +F.2. Version -04 to -05 o Added RFC 2119 language to the specification of the required behavior of profile specifications. - o Added section 6.1 on the relation to the OAuth2 grant types. + o Added Section 5.2 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 8.2. + requests in Section 5.7.2 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.2. Version -03 to -04 +F.3. 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.3. Version -02 to -03 +F.4. 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.4. Version -01 to -02 +F.5. 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, /introspect 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.5. Version -00 to -01 +F.6. 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 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 @@ -2826,24 +2882,23 @@ 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 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 token. - * Require that the messages between AS and client are secured, either with (D)TLS or with COSE_Encrypted wrappers. - * Removed dependency on OSCoAP and added generic text about + * Removed dependency on OSCOAP and added generic text about object security instead. * Defined the "rpk" parameter in the client information to transmit the raw public key of the RS from AS to client. * (D)TLS MUST use the PoP key in the handshake (either as PSK or as client RPK with client authentication). * Defined the use of x5c, x5t and x5tS256 parameters when a client certificate is used for proof of possession. * Defined "tktn" parameter for signaling for how to transfer the access token. o Added 5.2. the CoAP Access-Token option for transferring access @@ -2851,39 +2906,40 @@ o 5.3.2. Defined success and error responses from the RS when receiving an access token. o 5.6.:Added section giving guidance on how to handle token expiration in the absence of reliable time. o Appendix B Added list of roles and responsibilities for C, AS and RS. Authors' Addresses Ludwig Seitz - SICS + RISE SICS Scheelevaegen 17 Lund 223 70 SWEDEN - Email: ludwig@sics.se - + Email: ludwig@ri.se Goeran Selander Ericsson Faroegatan 6 Kista 164 80 SWEDEN Email: goran.selander@ericsson.com Erik Wahlstroem + (no affiliation) Sweden Email: erik@wahlstromtekniska.se + Samuel Erdtman Spotify AB Birger Jarlsgatan 61, 4tr Stockholm 113 56 Sweden Email: erdtman@spotify.com Hannes Tschofenig ARM Ltd.