ACE H. Tschofenig
Internet-Draft ARM Limited
Intended status: Informational March 8, 2015
Expires: September 9, 2015

The OAuth 2.0 Internet of Things (IoT) Client Credentials Grant


As Internet of Things (IoT) deployments increase steadily the need for a better user experience for handling the authentication and authorization tasks in constrained environments increases.

While several technologies have been developed already that allow federated access to protected resource the nature of IoT deployments requires care with the limited resources available on many of these devices.

This document defines a new OAuth 2.0 authorization grant for the interaction between constrained clients and resource servers to obtain access tokens for access to protected resources. It does so by leveraging prior work on OAuth 2.0, CoAP, and DTLS.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

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

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on September 9, 2015.

Copyright Notice

Copyright (c) 2015 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 ( in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1. Introduction

Early Internet of Things deployments used Internet connectivity to push data to a cloud service or to an application on a smart phone. While these IoT deployments offer great benefits for their users they also suffer from a usability problem that can best be demonstrated with a door lock example.

Consider an enterprise environment where access to different parts of the campus is granted to employees dynamically and on a need-by-need basis. New employees receive access rights and those who decide to leave the company get their access rights revoked.

When an employee approaches a door the door lock is supposed to check the authorization rights of that employee in a fraction of a second and to grant (or deny) access appropriately. The building managers expect a centralized management of employees and their access rights and no prior interaction of employees with any object, such as a door, upfront (such as it would be needed with pairing mechanisms utilized by some IoT technologies).

To accomplish such a seamless user experience and offering security at the same time it is necessary to make use of an authentication and authorization server that manages policies for access to protected resources (such as door locks in the previous example). As outlined in [I-D.seitz-ace-usecases], it is assumed that resource servers do not necessarily need to contact the authorization server every time they receive an access request.

OAuth 2.0 [RFC6749] is a technology that offers such a design pattern via the use of access tokens, which are requested by clients, and subsequently presented to resource servers when demanding access to protected resources managed by those resource servers.

OAuth 2.0 was, however, design primarily for use with the HTTP-based web infrastructure and has only recently been extended for use with SASL [I-D.ietf-kitten-sasl-oauth]. This document extends the OAuth 2.0 idea one step further and defines a Constrained Application Protocol (CoAP)- based transport profile for OAuth 2.0. CoAP is specified in RFC 7252 [RFC7252].

The benefits are as follows:

Intentionally left outside the scope of this document are the following items:

2. Terminology

The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this specification are to be interpreted as described in [RFC2119].

All terms are as defined in The OAuth 2.0 Authorization Framework [RFC6749].

3. Applicability Statement

The OAuth 2.0 IoT grant defined in this document is only applicable for OAuth 2.0 clients that are resource constrained. For all other clients regular OAuth 2.0 can be re-used since those clients will be able to execute the RFC 6749-defined client credential grant, which uses HTTPS as a transport.

The communication between the client and a resource constrained resource server is not described in this document and orthogonal to this document.

4. IoT Client Credentials Grant

This IoT credential grant is a variation of the client credential grant defined in RFC 6749.

The client can request an access token using only its client credentials when the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the authorization server (the method of which is beyond the scope of this specification).

The IoT client credentials grant type MUST only be used by confidential clients.

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(A)- Access Token Request  --->| Authorization |
     | Client  |        (protected by DTLS)       |     Server    |
     |         |<--(B)- Access Token Response ---<|               |
     |         |        (protected by DTLS)       |               |
     +---------+                                  +---------------+


Figure 1: IoT Client Credentials Flow.

The exchange illustrated in Figure 1 includes the following steps:

4.1. Authorization Request and Response

Since the client authentication is used as the authorization grant, no additional authorization request is needed.

4.2. Access Token Request

The client makes a request to the token endpoint by adding the following parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the CoAP request entity-body:

OPTIONAL. Value MUST be set to "urn:ietf:params:oauth:grant-type:iot" for this grant type. The value is optional since the client may have been pre-provisioned by the authorization server with information about the grant type.
OPTIONAL. The scope of the access request as described by Section 3.3 of RFC 6749.
OPTIONAL. Value is used by the client to indicate what resource server, as the intended recipient, it wants to access. This field is defined in [I-D.tschofenig-oauth-audience]

(QUESTION: Would it be useful to also use a JSON encoding here?)

In order to prevent man-in-the-middle attacks, the client MUST require the use of DTLS with server authentication for any request sent to the authorization and token endpoints. If certificate-based server authentication is used then the client MUST validate the TLS certificate of the authorization server, as defined by [RFC6125].

4.3. Access Token Response

If the access token request is valid and authorized, the authorization server issues an access token as described in Section 5.1 of RFC 6749 but encoded in a CoAP message using the Content response code with the response encoded as a JSON structure in the payload of the message. A refresh token MUST NOT be included. If the request failed client authentication or is invalid, the authorization server returns an error response using the CoAP 4.00 'Bad Request' response code with the error messages defined in Section 5.2 of RFC 6749.

Note that the HTTP "Cache-Control" parameters are not used in the CoAP response message.

QUESTION: Would it be useful to use the CBOR encoding for the response? This could reduce the response size by a few %.

5. Example

For example, the client makes a CoAP carrying the Access Token Request protected with DTLS to the authorization server. It then receives a successful Access Token Response containing the access token.

In the example below content-type 51 corresponds to the 'application/x-www-form-urlencoded'.

   Client     Server
      |         |
      |<=======>| DTLS Connection Establishment
      |         |
      +-------->| Header: POST (T=CON, Code=0.02, MID=0x7d34, 
      | POST    | ct=51, Uri-Path:"token"
      |         | Payload: grant_type=client_credentials
      |         |
      |<--------+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34,
      | 2.05    | ct=50)
      |         | Payload: <JSON-Payload>
      |         |


Figure 2: Example CoAP POST Message Exchange.

6. Security Considerations

This document re-uses a sub-set of the OAuth 2.0 functionality specified in RFC 6749 and intentionally inherits the security properties of OAuth 2.0, and DTLS. The discussion in Section 10 of RFC 6749 and Section 4 of RFC 6819 are relevant for this document.

7. IANA Considerations

7.1. Sub-Namespace Registration of urn:ietf:params:oauth:grant-type:iot

This specification registers the value "grant-type:iot" in the IANA urn:ietf:params:oauth registry established in An IETF URN Sub-Namespace for OAuth [RFC6755].

  • URN: urn:ietf:params:oauth:grant-type:iot
  • Common Name: Internet of Things (IoT) Client Credentails Grant Type Profile for OAuth 2.0
  • Change controller: IETF
  • Specification Document: [[this document]]

8. References

8.1. Normative References

[I-D.ietf-dice-profile] Hartke, K. and H. Tschofenig, "A DTLS 1.2 Profile for the Internet of Things", Internet-Draft draft-ietf-dice-profile-01, May 2014.
[I-D.tschofenig-oauth-audience] Tschofenig, H., "OAuth 2.0: Audience Information", Internet-Draft draft-tschofenig-oauth-audience-00, February 2013.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, March 2011.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, January 2012.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012.
[RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace for OAuth", RFC 6755, October 2012.
[RFC7252] Shelby, Z., Hartke, K. and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, June 2014.

8.2. Informative References

[I-D.bormann-core-ace-aif] Bormann, C., "An Authorization Information Format (AIF) for ACE", Internet-Draft draft-bormann-core-ace-aif-00, January 2014.
[I-D.hunt-oauth-pop-architecture] Hunt, P., Richer, J., Mills, W., Mishra, P. and H. Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security Architecture", Internet-Draft draft-hunt-oauth-pop-architecture-02, June 2014.
[I-D.ietf-kitten-sasl-oauth] Mills, W., Showalter, T. and H. Tschofenig, "A set of SASL and GSS-API Mechanisms for OAuth", Internet-Draft draft-ietf-kitten-sasl-oauth-10, February 2013.
[I-D.ietf-oauth-json-web-token] Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", Internet-Draft draft-ietf-oauth-json-web-token-06, December 2012.
[I-D.richer-oauth-introspection] Richer, J., "OAuth Token Introspection", Internet-Draft draft-richer-oauth-introspection-03, February 2013.
[I-D.seitz-ace-usecases] Seitz, L., Gerdes, S. and G. Selander, "ACE use cases", Internet-Draft draft-seitz-ace-usecases-00, February 2014.

Author's Address

Hannes Tschofenig ARM Limited Austria EMail: URI: