--- 1/draft-ietf-ace-oauth-authz-14.txt 2018-09-27 07:13:50.237169131 -0700 +++ 2/draft-ietf-ace-oauth-authz-15.txt 2018-09-27 07:13:50.381172619 -0700 @@ -1,26 +1,26 @@ ACE Working Group L. Seitz -Internet-Draft RISE SICS +Internet-Draft RISE Intended status: Standards Track G. Selander -Expires: March 23, 2019 Ericsson +Expires: March 31, 2019 Ericsson E. Wahlstroem S. Erdtman Spotify AB H. Tschofenig Arm Ltd. - September 19, 2018 + September 27, 2018 Authentication and Authorization for Constrained Environments (ACE) using the OAuth 2.0 Framework (ACE-OAuth) - draft-ietf-ace-oauth-authz-14 + draft-ietf-ace-oauth-authz-15 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 March 23, 2019. + This Internet-Draft will expire on March 31, 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 @@ -57,46 +57,46 @@ include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 6 - 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.2. CoAP . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 10 5. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.1. Discovering Authorization Servers . . . . . . . . . . . . 15 5.1.1. Unauthorized Resource Request Message . . . . . . . . 15 5.1.2. AS Information . . . . . . . . . . . . . . . . . . . 16 5.2. Authorization Grants . . . . . . . . . . . . . . . . . . 17 5.3. Client Credentials . . . . . . . . . . . . . . . . . . . 18 5.4. AS Authentication . . . . . . . . . . . . . . . . . . . . 18 5.5. The Authorization Endpoint . . . . . . . . . . . . . . . 18 5.6. The Token Endpoint . . . . . . . . . . . . . . . . . . . 19 5.6.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. Grant Type . . . . . . . . . . . . . . . . . . . 25 5.6.4.2. Token Type . . . . . . . . . . . . . . . . . . . 26 5.6.4.3. Profile . . . . . . . . . . . . . . . . . . . . . 26 5.6.5. Mapping Parameters to CBOR . . . . . . . . . . . . . 26 - 5.7. The 'Introspect' Endpoint . . . . . . . . . . . . . . . . 27 - 5.7.1. RS-to-AS Request . . . . . . . . . . . . . . . . . . 28 - 5.7.2. AS-to-RS Response . . . . . . . . . . . . . . . . . . 28 + 5.7. The Introspection Endpoint . . . . . . . . . . . . . . . 27 + 5.7.1. Introspection Request . . . . . . . . . . . . . . . . 28 + 5.7.2. Introspection Response . . . . . . . . . . . . . . . 28 5.7.3. Error Response . . . . . . . . . . . . . . . . . . . 29 5.7.4. Mapping Introspection parameters to CBOR . . . . . . 30 5.8. The Access Token . . . . . . . . . . . . . . . . . . . . 31 - 5.8.1. The 'Authorization Information' Endpoint . . . . . . 31 + 5.8.1. The Authorization Information Endpoint . . . . . . . 31 5.8.2. Client Requests to the RS . . . . . . . . . . . . . . 32 5.8.3. Token Expiration . . . . . . . . . . . . . . . . . . 33 6. Security Considerations . . . . . . . . . . . . . . . . . . . 34 6.1. Unprotected AS Information . . . . . . . . . . . . . . . 35 6.2. Use of Nonces for Replay Protection . . . . . . . . . . . 35 6.3. Combining profiles . . . . . . . . . . . . . . . . . . . 35 6.4. Error responses . . . . . . . . . . . . . . . . . . . . . 36 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 36 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 8.1. Authorization Server Information . . . . . . . . . . . . 37 @@ -106,48 +106,48 @@ 8.5. OAuth Token Type CBOR Mappings . . . . . . . . . . . . . 39 8.5.1. Initial Registry Contents . . . . . . . . . . . . . . 39 8.6. ACE Profile Registry . . . . . . . . . . . . . . . . . . 39 8.7. OAuth Parameter Registration . . . . . . . . . . . . . . 40 8.8. OAuth CBOR Parameter Mappings Registry . . . . . . . . . 40 8.9. OAuth Introspection Response Parameter Registration . . . 41 8.10. Introspection Endpoint CBOR Mappings Registry . . . . . . 41 8.11. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 42 8.12. CBOR Web Token Claims . . . . . . . . . . . . . . . . . . 42 8.13. Media Type Registrations . . . . . . . . . . . . . . . . 43 - 8.13.1. Media Type Registration . . . . . . . . . . . . . . 43 8.14. CoAP Content-Format Registry . . . . . . . . . . . . . . 44 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 10.1. Normative References . . . . . . . . . . . . . . . . . . 44 10.2. Informative References . . . . . . . . . . . . . . . . . 46 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 . . . . . . . . . . . . . . . . . 56 E.2. Introspection Aided Token Validation . . . . . . . . . . 60 Appendix F. Document Updates . . . . . . . . . . . . . . . . . . 64 - F.1. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 64 - F.2. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 64 - F.3. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 65 - F.4. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 65 - F.5. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 65 - F.6. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 65 - F.7. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 65 - F.8. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 66 - F.9. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 66 - F.10. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 66 - F.11. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 67 - F.12. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 67 - F.13. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 67 - F.14. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 68 + F.1. Version -14 to -15 . . . . . . . . . . . . . . . . . . . 64 + F.2. Version -13 to -14 . . . . . . . . . . . . . . . . . . . 64 + F.3. Version -12 to -13 . . . . . . . . . . . . . . . . . . . 65 + F.4. Version -11 to -12 . . . . . . . . . . . . . . . . . . . 65 + F.5. Version -10 to -11 . . . . . . . . . . . . . . . . . . . 65 + F.6. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 65 + F.7. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 65 + F.8. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 66 + F.9. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 66 + F.10. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 66 + F.11. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 66 + F.12. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 67 + F.13. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 67 + F.14. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 67 + F.15. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 68 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 @@ -306,20 +306,38 @@ Access tokens are credentials needed to access protected resources. An access token is a data structure representing authorization permissions issued by the AS to the client. Access tokens are generated by the AS and consumed by the RS. The access token content is opaque to the client. Access tokens can have different formats, and various methods of utilization (e.g., cryptographic properties) based on the security requirements of the given deployment. + Refresh Tokens: + Refresh tokens are credentials used to obtain access tokens. + Refresh tokens are issued to the client by the authorization + server and are used to obtain a new access token when the current + access token becomes invalid or expires, or to obtain additional + access tokens with identical or narrower scope (access tokens may + have a shorter lifetime and fewer permissions than authorized by + the resource owner). Issuing a refresh token is optional at the + discretion of the authorization server. If the authorization + server issues a refresh token, it is included when issuing an + access token (i.e., step (B) in Figure 1). + + A refresh token is a string representing the authorization granted + to the client by the resource owner. The string is usually opaque + to the client. The token denotes an identifier used to retrieve + the authorization information. Unlike access tokens, refresh + tokens are intended for use only with authorization servers and + are never sent to resource servers. Proof of Possession Tokens: An access token may be bound to a cryptographic key, which is then used by an RS to authenticate requests from a client. Such tokens are called proof-of-possession access tokens (or PoP access tokens). The proof-of-possession (PoP) security concept assumes that the AS acts as a trusted third party that binds keys to access tokens. These so called PoP keys are then used by the client to demonstrate the possession of the secret to the RS when accessing @@ -430,27 +448,28 @@ 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 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. - These interactions are shown in Figure 1. An overview of various - OAuth concepts is provided in Section 3.1. + A client obtains an access token, and optionally a refresh 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. These interactions are shown in + Figure 1. An overview of various OAuth concepts is provided in + Section 3.1. The OAuth 2.0 framework defines a number of "protocol flows" via grant types, which have been extended further with extensions to OAuth 2.0 (such as RFC 7521 [RFC7521] and [I-D.ietf-oauth-device-flow]). What grant types works best depends on the usage scenario and RFC 7744 [RFC7744] describes many different IoT use cases but there are two preferred grant types, namely the Authorization Code Grant (described in Section 4.1 of [RFC7521]) and the Client Credentials Grant (described in Section 4.4 of [RFC7521]). The Authorization Code Grant is a good fit for use with apps running @@ -505,21 +524,21 @@ 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 | | | + Access Information | | - | | +---------------+ + | | + Refresh Token (optional) +---------------+ | | ^ | | | Introspection Request (D)| | | Client | (optional) | | | | Response | |(E) | | (optional) | v | | +--------------+ | |---(C)-- Token + Request ----->| | | | | Resource | | |<--(F)-- Protected Resource ---| Server | | | | | @@ -531,26 +550,29 @@ The client makes an access token request to the token endpoint at 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 "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. + returns an access token and optionally a refresh token (note that + only certain grant types support refresh tokens). It can also + return additional parameters, referred to as "Access Information". + + In addition to the response parameters defined by OAuth 2.0 and + the PoP access token extension, this framework defines parameters + that can be used to inform the client about capabilities of the + RS. 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: @@ -858,34 +881,34 @@ integer abbreviations and the binary CBOR encoding, if the CBOR encoding is used. 5.6.1. Client-to-AS Request The client sends a POST request to the token endpoint at the AS. The profile MUST specify how the communication is protected. The content of the request consists of the parameters specified in Section 4 of the OAuth 2.0 specification [RFC6749]. + In addition to these parameters the parameters from + [I-D.ietf-ace-oauth-params] can be used for requesting an access + token from a token endpoint. + If CBOR is used then this parameter MUST be encoded as a CBOR map. The "scope" parameter can be formatted as specified in [RFC6749] and additionally as a byte array, in order to allow compact encoding of complex scopes. When HTTP is used as a transport then the client makes a request to the token endpoint by sending the parameters using the "application/ x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body, as defined in RFC 6749. - In addition to these parameters the parameters from - [I-D.ietf-ace-oauth-params] can be used for requesting an access - token from a token endpoint. - The following examples illustrate different types of requests for proof-of-possession tokens. Figure 5 shows a request for a token with a symmetric proof-of- possession key. The content is displayed in CBOR diagnostic notation, without abbreviations for better readability. Header: POST (Code=0.02) Uri-Host: "as.example.com" Uri-Path: "token" @@ -951,20 +974,28 @@ "aud" : "valve424", "scope" : "read", "cnf" : { "kid" : b64'6kg0dXJM13U' } } Figure 7: Example request for an access token bound to a key reference. + Refresh tokens are typically not stored as securely as proof-of- + possession keys in requesting clients. Proof-of-possession based + refresh token requests MUST NOT request different proof-of-possession + keys or different audiences in token requests. Refresh token + requests can only use to request access tokens bound to the same + proof-of-possession key and the same audience as access tokens issued + in the initial token request. + 5.6.2. AS-to-Client Response If the access token request has been successfully verified by the AS and the client is authorized to obtain an access token corresponding to its access token request, the AS sends a response with the response code equivalent to the CoAP response code 2.01 (Created). If client request was invalid, or not authorized, the AS returns an error response as described in Section 5.6.3. Note that the AS decides which token type and profile to use when @@ -987,21 +1019,22 @@ This parameter is OPTIONAL, as opposed to 'required' in [RFC6749]. By default implementations of this framework SHOULD assume that the token_type is "pop". If a specific use case requires another token_type (e.g., "Bearer") to be used then this parameter is REQUIRED. Furthermore [I-D.ietf-ace-oauth-params] defines further parameters the AS can use when responding to a request to the token endpoint. Figure 8 summarizes the parameters that may be part of the Access - Information. + Information. This does not include the additional parameters + specified in [I-D.ietf-ace-oauth-params]. /-------------------+-------------------------------\ | 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 | @@ -1137,83 +1170,89 @@ 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]. + Note also that abbreviations from -24 to 23 have a 1 byte encoding + size in CBOR. We have thus choosen to assign abbreviations in that + range to parameters we expect to be used most frequently in + constrained scenarios. + /-------------------+----------+---------------------\ | Name | CBOR Key | Value Type | |-------------------+----------+---------------------| | scope | 9 | text or byte string | | profile | 10 | unsigned integer | - | error | 11 | unsinged integer | + | error | 11 | unsigned integer | | grant_type | 12 | unsigned integer | | access_token | 13 | byte string | | token_type | 14 | unsigned integer | | client_id | 24 | text string | | client_secret | 25 | byte string | | response_type | 26 | text string | | state | 27 | text string | | redirect_uri | 28 | text string | | error_description | 29 | text string | | error_uri | 30 | text string | | code | 31 | byte string | | expires_in | 32 | unsigned integer | | username | 33 | text string | | password | 34 | text string | | refresh_token | 35 | byte string | \-------------------+----------+---------------------/ Figure 12: CBOR mappings used in token requests -5.7. The 'Introspect' Endpoint +5.7. The Introspection Endpoint Token introspection [RFC7662] can be OPTIONALLY provided by the AS, and is then used by the RS and potentially the client to query the AS for metadata about a given token, e.g., validity or scope. Analogous to the protocol defined in 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 - introspection MUST specify how authentication and communication - security between RS and AS is implemented. + Communication between the requesting entity and the introspection + endpoint at the AS MUST be integrity protected and encrypted. + Furthermore the two MUST perform mutual authentication. Finally the + AS SHOULD verify that the requesting entity 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 the requesting entity and the AS + is implemented. The default name of this endpoint in an url-path is '/introspect', however implementations are not required to use this name and can define their own instead. The figures of this section uses CBOR diagnostic notation without the integer abbreviations for the parameters or their values for better readability. Note that supporting introspection is OPTIONAL for implementations of this framework. -5.7.1. RS-to-AS Request +5.7.1. Introspection Request - The RS sends a POST request to the introspection endpoint at the AS, - the profile MUST specify how the communication is protected. If CBOR - is used, the payload MUST be encoded as a CBOR map with a "token" - entry containing either the access token or a reference to the token - (e.g., the cti). Further optional parameters representing additional - context that is known by the RS to aid the AS in its response MAY be - included. + The requesting entity sends a POST request to the introspection + endpoint at the AS, the profile MUST specify how the communication is + protected. If CBOR is used, the payload MUST be encoded as a CBOR + map with a "token" entry containing either the access token or a + reference to the token (e.g., the cti). Further optional parameters + representing additional context that is known by the requesting + entity 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-Format is "application/cose". Figure 14 shows the decoded payload. @@ -1226,21 +1265,21 @@ Figure 13: Example introspection request. { "token" : b64'7gj0dXJQ43U', "token_type_hint" : "pop" } Figure 14: Decoded token. -5.7.2. AS-to-RS Response +5.7.2. Introspection Response If the introspection request is authorized and successfully processed, the AS sends a response with the response code equivalent to the CoAP code 2.01 (Created). If the introspection request was invalid, not authorized or couldn't be processed the AS returns an error response as described in Section 5.7.3. 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 addition: @@ -1276,28 +1315,28 @@ 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 and CBOR is used the payload MUST be encoded as a CBOR map and the Content-Format "application/ace+cbor" MUST be used. - o If the credentials used by the RS are invalid the AS MUST respond - with the response code equivalent to the CoAP code 4.01 - (Unauthorized) and use the required and optional parameters from - Section 5.2 in RFC 6749 [RFC6749]. - o If the RS does not have the right to perform this introspection - request, the AS MUST respond with a response code equivalent to - the CoAP code 4.03 (Forbidden). In this case no payload is - returned. + o If the credentials used by the requesting entity (usually the RS) + are invalid the AS MUST respond with the response code equivalent + to the CoAP code 4.01 (Unauthorized) and use the required and + optional parameters from Section 5.2 in RFC 6749 [RFC6749]. + o If the requesting entity does not have the right to perform this + introspection request, the AS MUST respond with a response code + equivalent to the CoAP code 4.03 (Forbidden). In this case no + payload is returned. o The parameters "error", "error_description" and "error_uri" MUST be abbreviated using the codes specified in Figure 12. o The error codes MUST be abbreviated using the codes specified in Figure 10. Note that a properly formed and authorized query for an inactive or 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". @@ -1353,21 +1392,21 @@ If the AS needs to convey a hint to the RS about which key it should use to authenticate towards the client, the rs_cnf claim MAY be used with the same syntax and semantics as defined in [I-D.ietf-ace-oauth-params]. If the AS needs to convey a hint to the RS about which profile it should use to communicate with the client, the AS MAY include a "profile" claim in the access token, with the same syntax and semantics as defined in Section 5.6.4.3. -5.8.1. The 'Authorization Information' Endpoint +5.8.1. The Authorization Information Endpoint The access token, containing authorization information and information about the key used by the client, needs to be transported to the RS so that the RS can authenticate and authorize the client request. This section defines a method for transporting the access token to the RS using a RESTful protocol such as CoAP. Profiles of this framework MAY define other methods for token transport. @@ -1395,21 +1434,21 @@ 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 whether the authz-info endpoint is protected, - including wheter error responses from this endpoint are protected. + including whether error responses from this endpoint are protected. Note that since the token contains information that allow the client and the RS to establish a security context in the first place, mutual authentication may not be possible at this point. The default name of this endpoint in an url-path is '/authz-info', however implementations are not required to use this name and can define their own instead. 5.8.2. Client Requests to the RS @@ -1519,27 +1558,26 @@ token, for example encryption of CWTs is specified in Section 5.1 of [RFC8392]. Developers MUST ensure that the ephemeral credentials (i.e., the private key or the session key) are not leaked to third parties. An adversary in possession of the ephemeral credentials bound to the access token will be able to impersonate the client. Be aware that this is a real risk with many constrained environments, since adversaries can often easily get physical access to the devices. - Clients can at any time request a new proof-of-possession capable - access token. If clients have that capability, the AS can keep the - lifetime of the access token and the associated proof-of-possession - key short and therefore use shorter proof-of-possession key sizes, - which translate to a performance benefit for the client and for the - resource server. Shorter keys also lead to shorter messages - (particularly with asymmetric keying material). + If clients are capable of doing so, they should frequently request + fresh access tokens, as this allows the AS to keep the lifetime of + the tokens short. This allows the AS to use shorter proof-of- + possession key sizes, which translate to a performance benefit for + the client and for the resource server. Shorter keys also lead to + shorter messages (particularly with asymmetric keying material). When authorization servers bind symmetric keys to access tokens, they SHOULD scope these access tokens to a specific permissions. Furthermore access tokens using symmetric keys for proof-of- 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 @@ -1907,35 +1945,34 @@ o Claim Description: The public key the RS is supposed to use to authenticate to the client wielding this token. o JWT Claim Name: N/A o Claim Key: 17 o Claim Value Type(s): map o Change Controller: IESG o Specification Document(s): Section 5.8 of [this document] 8.13. Media Type Registrations - This document registres a media type for messages of the protocols - defined in this document carrying parameters encoded in CBOR. This - registration follows the procedures specified in [RFC6838]. - -8.13.1. Media Type Registration + This document registers the 'application/ace+cbor' media type for + messages of the protocols defined in this document carrying + parameters encoded in CBOR. This registration follows the procedures + specified in [RFC6838]. Type name: application Subtype name: ace+cbor Required parameters: none Optional parameters: none - Encoding considerations: Must be encoded as CBOR map containg the + Encoding considerations: Must be encoded as CBOR map containing the protocol parameters defined in [this document]. Security considerations: See Section 6 of this document. Interoperability considerations: n/a Published specification: [this document] Applications that use this media type: The type is used by authorization servers, clients and resource servers that support the @@ -1944,25 +1981,25 @@ Additional information: Magic number(s): n/a File extension(s): .ace Macintosh file type code(s): n/a Person & email address to contact for further information: Ludwig Seitz - Intended usage: COMMON + Intended usage: COMMON Restrictions on usage: None - Author: Ludwig Seitzs + Author: Ludwig Seitz Change controller: IESG 8.14. CoAP Content-Format Registry This document registers the following entry to the "CoAP Content- Formats" registry: Media Type: application/ace+cbor @@ -2395,44 +2433,47 @@ * 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 [RFC8414] + * Optionally: Handle refresh tokens. Client * Discover the AS in charge of the RS that is to be targeted with a request. * Submit the token request (see step (A) of Figure 1). + Authenticate to the AS. + Optionally (if not pre-configured): Specify which RS, which 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 Access Information (see step (B) of Figure 1). + Check that the Access Information provides the necessary security parameters (e.g., PoP key, information on communication security protocols supported by the RS). - + + Safely store the proof-of-possession key. + + If provided by the AS: Safely store the refresh token. * 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 through the authentication procedure). * Process the RS response (see step (F) of Figure 1) of the RS. Resource Server @@ -2451,20 +2492,23 @@ + Set up communication security with the client. + Authenticate the client. + Match the client against existing tokens. + Check that tokens belonging to the client actually authorize the requested action. + Optionally: Check that the matching tokens are still valid, using introspection (if this is possible.) * Send a response following the agreed upon communication security. + * Safely store credentials such as raw public keys for + authentication or proof-of-possession keys linked to access + tokens. Appendix C. Requirements on Profiles This section lists the requirements on profiles of this framework, for the convenience of profile designers. o Specify the communication protocol the client and RS the must use (e.g., CoAP). Section 5 and Section 5.6.4.3 o Specify the security protocol the client and RS must use to protect their communication (e.g., OSCORE or DTLS over CoAP). @@ -2605,21 +2649,20 @@ "x" : b64'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU', "y" : b64'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0' } } } Response-Payload : { "access_token" : b64'SlAV32hkKG ...', "token_type" : "pop", - "csp" : "DTLS", "rs_cnf" : { "COSE_Key" : { "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kty" : "EC", "crv" : "P-256", "x" : b64'MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4', "y" : b64'4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM' } } } @@ -2769,21 +2812,20 @@ { "grant_type" : "client_credentials", "client_id" : "keyfob", "client_secret" : "qwerty" } Response-Payload: { "access_token" : b64'VGVzdCB0b2tlbg==', "token_type" : "pop", - "csp" : "DTLS", "cnf" : { "COSE_Key" : { "kid" : b64'c29tZSBwdWJsaWMga2V5IGlk', "kty" : "oct", "alg" : "HS256", "k": b64'ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE' } } } @@ -2879,85 +2921,91 @@ F: |<--------+ Header: 2.04 Changed | 2.04 | Payload: | | Figure 26: Resource request and response protected by OSCORE Appendix F. Document Updates RFC EDITOR: PLEASE REMOVE THIS SECTION. -F.1. Version -13 to -14 +F.1. Version -14 to -15 + + o Added text about refresh tokens. + o Added text about protection of credentials. + o Rephrased introspection so that other entities than RS can do it. + o Editorial improvements. + +F.2. Version -13 to -14 o Split out the 'aud', 'cnf' and 'rs_cnf' parameters to [I-D.ietf-ace-oauth-params] o Introduced the "application/ace+cbor" Content-Type. o Added claim registrations from 'profile' and 'rs_cnf'. o Added note on schema part of AS Information Section 5.1.2 o Realigned the parameter abbreviations to push rarely used ones to the 2-byte encoding size of CBOR integers. -F.2. Version -12 to -13 +F.3. Version -12 to -13 o Changed "Resource Information" to "Access Information" to avoid confusion. o Clarified section about AS discovery. o Editorial changes -F.3. Version -11 to -12 +F.4. 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.4. Version -10 to -11 +F.5. Version -10 to -11 o Fixed some CBOR data type errors. o Updated boilerplate text -F.5. Version -09 to -10 +F.6. 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.6. Version -08 to -09 +F.7. 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.7. Version -07 to -08 +F.8. 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. o Added text to clarify that introspection must not be delayed, in case the RS has to return a client token. o Added security considerations about leakage through unprotected AS 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. @@ -2963,95 +3011,96 @@ 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.8. Version -06 to -07 +F.9. Version -06 to -07 o Various clarifications added. o Fixed erroneous author email. -F.9. Version -05 to -06 +F.10. 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.10. Version -04 to -05 +F.11. 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.11. Version -03 to -04 +F.12. 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.12. Version -02 to -03 +F.13. 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.13. Version -01 to -02 +F.14. 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.14. Version -00 to -01 +F.15. 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 @@ -3073,21 +3122,21 @@ 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 - RISE SICS + RISE Scheelevaegen 17 Lund 223 70 Sweden Email: ludwig.seitz@ri.se Goeran Selander Ericsson Faroegatan 6 Kista 164 80 Sweden