draft-ietf-ace-mqtt-tls-profile-00.txt   draft-ietf-ace-mqtt-tls-profile-01.txt 
ACE Working Group C. Sengul ACE Working Group C. Sengul
Internet-Draft Nominet Internet-Draft Nominet
Intended status: Standards Track A. Kirby Intended status: Standards Track A. Kirby
Expires: November 8, 2019 Oxbotica Expires: April 7, 2020 Oxbotica
P. Fremantle P. Fremantle
University of Portsmouth University of Portsmouth
May 7, 2019 October 5, 2019
MQTT-TLS profile of ACE MQTT-TLS profile of ACE
draft-ietf-ace-mqtt-tls-profile-00 draft-ietf-ace-mqtt-tls-profile-01
Abstract Abstract
This document specifies a profile for the ACE (Authentication and This document specifies a profile for the ACE (Authentication and
Authorization for Constrained Environments) to enable authorization Authorization for Constrained Environments) to enable authorization
in an MQTT-based publish-subscribe messaging system. Proof-of- in an MQTT-based publish-subscribe messaging system. Proof-of-
possession keys, bound to OAuth2.0 access tokens, are used to possession keys, bound to OAuth2.0 access tokens, are used to
authenticate and authorize publisher and subscriber clients. The authenticate and authorize MQTT Clients. The protocol relies on TLS
protocol relies on TLS for confidentiality and server authentication. for confidentiality and server authentication.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 8, 2019. This Internet-Draft will expire on April 7, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4
1.2. ACE-Related Terminology . . . . . . . . . . . . . . . . . 4 1.2. ACE-Related Terminology . . . . . . . . . . . . . . . . . 4
1.3. MQTT-Related Terminology . . . . . . . . . . . . . . . . 4 1.3. MQTT-Related Terminology . . . . . . . . . . . . . . . . 4
2. Basic Protocol Interactions . . . . . . . . . . . . . . . . . 5 2. Protocol Interactions . . . . . . . . . . . . . . . . . . . . 6
2.1. Authorizing Connection Establishment . . . . . . . . . . 6 2.1. Authorizing Connection Establishment . . . . . . . . . . 7
2.1.1. Client Authorization Server (CAS) and Authorization 2.1.1. Client Token Request to the Authorization Server (AS) 8
Server (AS) Interaction . . . . . . . . . . . . . . . 7 2.1.2. Client Connection Request to the Broker (C) . . . . . 8
2.1.2. Client Connection Request to the Broker . . . . . . . 8 2.1.2.1. Proof-of-Possession over Predefined Field . . . . 10
2.1.3. Token Validation . . . . . . . . . . . . . . . . . . 10 2.1.2.2. Proof-of-Possession via challenge/response . . . 11
2.1.4. The Broker's Response to Client Connection Request . 11 2.1.2.3. Unauthorised Request: Authorisation Server
2.2. Authorizing PUBLISH Messages . . . . . . . . . . . . . . 12 Discovery . . . . . . . . . . . . . . . . . . . . 12
2.1.3. Token Validation . . . . . . . . . . . . . . . . . . 12
2.1.4. The Broker's Response to Client Connection Request . 13
2.2. Authorizing PUBLISH Messages . . . . . . . . . . . . . . 13
2.2.1. PUBLISH Messages from the Publisher Client to the 2.2.1. PUBLISH Messages from the Publisher Client to the
Broker . . . . . . . . . . . . . . . . . . . . . . . 12 Broker . . . . . . . . . . . . . . . . . . . . . . . 13
2.2.2. PUBLISH Messages from the Broker to the Subscriber 2.2.2. PUBLISH Messages from the Broker to the Subscriber
Clients . . . . . . . . . . . . . . . . . . . . . . . 12 Clients . . . . . . . . . . . . . . . . . . . . . . . 14
2.3. Authorizing SUBSCRIBE Messages . . . . . . . . . . . . . 13 2.3. Authorizing SUBSCRIBE Messages . . . . . . . . . . . . . 14
2.4. Token Expiration . . . . . . . . . . . . . . . . . . . . 13 2.4. Token Expiration and Reauthentication . . . . . . . . . . 15
2.5. Handling Disconnections and Retained Messages . . . . . . 13 2.5. Handling Disconnections and Retained Messages . . . . . . 15
3. Improved Protocol Interactions with MQTT v5 . . . . . . . . . 14 3. Reduced Protocol Interactions for MQTT v3.1.1 . . . . . . . . 16
3.1. Token Transport via Authentication Exchange (AUTH) . . . 14 3.1. Token Transport . . . . . . . . . . . . . . . . . . . . . 16
3.2. Authorization Errors and Client Re-authentication . . . . 16 3.2. Handling Authorization Errors . . . . . . . . . . . . . . 17
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
5. Security Considerations . . . . . . . . . . . . . . . . . . . 17 5. Security Considerations . . . . . . . . . . . . . . . . . . . 18
6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 18 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 19
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 19
7.1. Normative References . . . . . . . . . . . . . . . . . . 18 7.1. Normative References . . . . . . . . . . . . . . . . . . 19
7.2. Informative References . . . . . . . . . . . . . . . . . 19 7.2. Informative References . . . . . . . . . . . . . . . . . 20
Appendix A. Checklist for profile requirements . . . . . . . . . 20 Appendix A. Checklist for profile requirements . . . . . . . . . 21
Appendix B. The Authorization Information Endpoint . . . . . . . 21 Appendix B. The Authorization Information Endpoint . . . . . . . 21
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 21 Appendix C. Document Updates . . . . . . . . . . . . . . . . . . 22
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 22
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23
1. Introduction 1. Introduction
This document specifies a profile for the ACE framework This document specifies a profile for the ACE framework
[I-D.ietf-ace-oauth-authz]. In this profile, clients and a resource [I-D.ietf-ace-oauth-authz]. In this profile, Clients and a Broker
server use MQTT to communicate. The protocol relies on TLS for use MQTT to exchange Application messages. The protocol relies on
communication security between entities. The basic protocol TLS for communication security between entities. The MQTT protocol
interactions follow MQTT v3.1.1 - the OASIS Standard interactions are described based on the MQTT v5.0 - the OASIS
[MQTT-OASIS-Standard]. In addition, this document describes Standard [MQTT-OASIS-Standard-v5]. It is expected that MQTT
improvements to the basic protocol with the new MQTT v5.0 - the OASIS deployments will retain backward compatibility for MQTT v3.1.1
Standard [MQTT-OASIS-Standard-v5] (e.g., improved authentication clients, and therefore, this document describes a reduced set of
exchange and error reporting). Both versions are expected to be protocol interactions suited to MQTT v3.1.1 - the OASIS Standard
supported in practice, and therefore, covered in this document. [MQTT-OASIS-Standard]. However, it is RECOMMENDED to use MQTT v5.0
as it works more naturally with ACE-style authentication and
authorization.
MQTT is a publish-subscribe protocol and supports two main types of MQTT is a publish-subscribe protocol and supports two main types of
client operation: publish and subscribe. Once connected, a client Client operation: publish and subscribe. Once connected, a Client
can publish to multiple topics, and subscribe to multiple topics; can publish to multiple topics, and subscribe to multiple topics.
however, for this document, these actions are described separately. The MQTT Broker is responsible for distributing messages published by
The MQTT broker is responsible for distributing messages published by
the publishers to the appropriate subscribers. Each publish message the publishers to the appropriate subscribers. Each publish message
contains a topic, which is used by the broker to filter the contains a Topic Name, which is used by the Broker to filter the
subscribers for the message. Subscribers must subscribe to the subscribers for the message. Subscribers must subscribe to the
topics to receive the corresponding messages. topics to receive the corresponding messages.
In this document, message topics are treated as resources. Clients In this document, message topics are treated as resources. Clients
use an access token, bound to a key (the proof-of-possession key) to use an access token, bound to a key (the proof-of-possession key) to
authorize with the MQTT broker their connection and publish/subscribe authorize with the MQTT Broker their connection and publish/subscribe
permissions to topics. In the context of this ACE profile, the MQTT permissions to topics. In the context of this ACE profile, the MQTT
broker acts as the resource server. To provide communication Broker acts as the Resource Server (RS). In the rest of the document
confidentiality and resource server authentication, TLS is used. RS and Broker are used interchangeably. To provide communication
confidentiality and Resource Server authentication, TLS is used.
Clients use client authorization servers [I-D.ietf-ace-actors] to This document makes the same assumptions as the Section 4 of the ACE
obtain tokens from the authorization server. The communication framework [I-D.ietf-ace-oauth-authz] regarding Client and RS
protocol between the client authorization server and the registration with the AS and establishing of keying material.
authorization server is assumed to be HTTPS. Also, if the broker
supports token introspection, it is assumed to use HTTPS to
communicate with the authorization server. These interfaces MAY be
implemented using other protocols, e.g., CoAP or MQTT. This document
makes the same assumptions as the Section 4 of the ACE framework
[I-D.ietf-ace-oauth-authz] regarding client and RS registration with
the AS and establishing of keying material.
This document describes the authorization of the following exchanges This document describes the authorization of the following exchanges
between publisher and subscriber clients, and the broker. between Clients and the Broker.
o Connection establishment between the clients and the broker o Connection establishment between the Clients and the Broker
o Publish messages from the publishers to the broker, and from the o Publish messages from the Clients to the Broker, and from the
broker to the subscribers Broker to the Clients
o Subscribe messages from the subscribers to the broker o Subscribe messages from the Clients to the Broker
In Section 2, these exchanges are described based on the MQTT v3.1.1 While the Client-Broker exchanges are over MQTT, the required Client-
- the OASIS Standard [MQTT-OASIS-Standard]. These exchanges are also AS and RS-AS interactions are described for HTTPS-based
supported by the new MQTT v5 - the OASIS Standard communication, using 'application/ace+json' content type, and unless
[MQTT-OASIS-Standard-v5]. Section 3 describes how they may be otherwise specified, using JSON encoding. The token may be a
improved by the new MQTT v5. reference, or JWT. For JWT tokens, this document follows RFC 7800
[RFC7800] for PoP semantics for JWTs. The Client-AS and RS-AS may
also be based on CoAP. It is also possible to use 'application/
ace+cbor' content type, and CBOR encoding, and CWT and associated PoP
semantics to reduce the protocol memory and bandwidth requirements.
For more information on Proof of Possession semantics for CWTs, see
Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs)
[I-D.ietf-ace-cwt-proof-of-possession].
1.1. Requirements Language 1.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174], when, and only when, they appear in all 14 [RFC2119] [RFC8174], when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
1.2. ACE-Related Terminology 1.2. ACE-Related Terminology
The terminology for entities in the architecture is defined in OAuth The terminology for entities in the architecture is defined in OAuth
2.0 RFC 6749 [RFC6749] and ACE actors [I-D.ietf-ace-actors], such as 2.0 RFC 6749 [RFC6749] such as "Client" (C), "Resource Server" (RS)
"Client" (C), "Resource Server" (RS) and "Authorization Server" (AS). and "Authorization Server" (AS).
The term "endpoint" is used following its OAuth definition, to denote The term "endpoint" is used following its OAuth definition, to denote
resources such as /token and /introspect at the AS. resources such as /token and /introspect at the AS.
The term "Resource" is used to refer to an MQTT "topic name," which The term "Resource" is used to refer to an MQTT Topic Name, which is
is defined in Section 1.3. Hence, the "Resource Owner" is any entity defined in Section 1.3. Hence, the "Resource Owner" is any entity
that can authoritatively speak for the "topic". that can authoritatively speak for the topic.
Certain security-related terms such as "authentication", Certain security-related terms such as "authentication",
"authorization", "confidentiality", "(data) integrity", "message "authorization", "confidentiality", "(data) integrity", "message
authentication code", and "verify" are taken from RFC 4949 [RFC4949]. authentication code", and "verify" are taken from RFC 4949 [RFC4949].
1.3. MQTT-Related Terminology 1.3. MQTT-Related Terminology
The document describes message exchanges as MQTT protocol The document describes message exchanges as MQTT protocol
interactions. For additional information, please refer to the MQTT interactions. The Clients are MQTT Clients, which connect to the
v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard] or the MQTT v5 - Broker to publish and subscribe to Application Messages. For
the OASIS Standard [MQTT-OASIS-Standard-v5]. additional information, please refer to the MQTT v5.0 - the OASIS
Standard [MQTT-OASIS-Standard-v5] or the MQTT v3.1.1 - the OASIS
Topic name Standard [MQTT-OASIS-Standard].
The label attached to an application message, which is
matched to a subscription.
Topic filter MQTTS
An expression that indicates interest in one or more topic Secured transport profile of MQTT. MQTTS runs over TLS.
names. Topic filters may include wildcards.
Subscription Broker
A subscription comprises a Topic filter and a maximum quality The Server in MQTT and acts as an intermediary between
of service (QoS). Clients that publish Application Messages, and the Clients
that made Subscriptions. The Broker acts as the Resource
Server for the Clients.
Application Message Application Message
The data carried by the MQTT protocol. The data has an The data carried by the MQTT protocol. The data has an
associated QoS level and a Topic name. associated QoS level and a Topic Name.
Topic Name
The label attached to an Application Message, which is
matched to a Subscription.
Subscription
A subscription comprises a Topic Filter and a maximum Quality
of Service (QoS).
Topic Filter
An expression that indicates interest in one or more Topic
Names. Topic Filters may include wildcards.
MQTT sends various control messages across a network connection. The MQTT sends various control messages across a network connection. The
following is not an exhaustive list and the control packets that are following is not an exhaustive list and the control packets that are
not relevant for authorization are not explained. These include, for not relevant for authorization are not explained. These include, for
instance, the PUBREL and PUBCOMP packets used in the 4-step handshake instance, the PUBREL and PUBCOMP packets used in the 4-step handshake
required for the QoS level 2. required for the QoS level 2.
CONNECT CONNECT
Client request to connect to the broker. After a network Client request to connect to the Broker. After a network
connection is established, this is the first packet sent by a connection is established, this is the first packet sent by a
client. Client.
CONNACK CONNACK
The broker connection acknowledgment. The first packet sent The Broker connection acknowledgment. The first packet sent
from the broker to a client is a CONNACK packet. CONNACK from the Broker to a Client is a CONNACK packet. CONNACK
packets contain return codes indicating either a success or packets contain return codes indicating either a success or
an error state to a client. an error state to a Client.
PUBLISH PUBLISH
Publish packet that can be sent from a client to the broker, Publish packet that can be sent from a Client to the Broker,
or from the broker to a client. or from the Broker to a Client.
PUBACK PUBACK
Response to PUBLISH packet with QoS level 1. PUBACK can be Response to PUBLISH packet with QoS level 1. PUBACK can be
sent from the broker to a client or a client to the broker. sent from the Broker to a Client or a Client to the Broker.
PUBREC PUBREC
Response to PUBLISH packet with QoS level 2. PUBREC can be Response to PUBLISH packet with QoS level 2. PUBREC can be
sent from the broker to a client or a client to the broker. sent from the Broker to a Client or a Client to the Broker.
SUBSCRIBE SUBSCRIBE
The client subscribe request. The Client subscribe request.
SUBACK SUBACK
Subscribe acknowledgment. Subscribe acknowledgment.
PINGREQ A ping request sent from a client to the broker. It signals PINGREQ
to the broker that the client is alive, and is used to A ping request sent from a Client to the Broker. It signals
confirm that the broker is still alive. to the Broker that the Client is alive, and is used to
confirm that the Broker is still alive.
2. Basic Protocol Interactions Will
An application message published by the Server after the
network connection is closed in cases where the network
connection is not closed normally. If the Will Flag is set,
then the payload of the CONNECT message has information about
the Will. The Will consists of the Will Properties, Will
Topic, and Will Payload fields in the CONNECT message.
This section describes the following exchanges between publisher and 2. Protocol Interactions
subscriber clients, the broker, and the authorization server
according to the MQTT v3.1.1 - the OASIS Standard
[MQTT-OASIS-Standard]. These exchanges are compatible also with the
new MQTT v5 - the OASIS Standard [MQTT-OASIS-Standard-v5]. In
addition, Section 3 describes how these exchanges may be improved
with the MQTT v5.
o Authorizing connection establishment between the clients and the This section describes the following exchanges between Clients, the
broker Broker, and the Authorization Server according to the MQTT v5.0.
o Authorizing publish messages from the publishers to the broker, o Authorizing connection establishment between the Clients and the
and from the broker to the subscribers Broker
o Authorizing subscribe messages from the subscribers to the broker o Authorizing publish messages from the Clients to the Broker, and
from the Broker to the Clients
Message topics are treated as resources. The publisher and o Authorizing subscribe messages from Clients to the Broker
subscriber clients are assumed to have identified the topics of
interest out-of-band (topic discovery is not a feature of the MQTT
protocol).
A connection request carries a token specifying the permissions that Section 3 describes how these exchanges can also be supported using
the client has (e.g., publish permission to a given topic). A the MQTT v3.1.1. MQTT v5.0 brokers MAY also only support the basic
resource owner can pre-configure policies at the AS that give clients operation; however, this is NOT RECOMMENDED.
publish or subscribe permissions to different topics.
2.1. Authorizing Connection Establishment In this profile document, message topics are treated as resources.
The Clients are assumed to have identified the publish/subscribe
topics of interest out-of-band (topic discovery is not a feature of
the MQTT protocol). A resource owner can pre-configure policies at
the AS that give Clients publish or subscribe permissions to
different topics.
This section specifies how publishers and subscribers establish an 2.1. Authorizing Connection Establishment
authorized connection to an MQTT broker. The token request and
response use the /token endpoint of the authorization server, as
specified in Section 5 of the ACE framework
[I-D.ietf-ace-oauth-authz].
Figure 1 shows the basic protocol flow during connection This section specifies how Clients establish an authorized connection
establishment. The step (C), client onboarding, is out of the scope to an MQTT Broker. Figure 1 shows the basic protocol flow during
of this document. Steps (E) and (F) are optional. connection establishment.The token request and response use the
/token endpoint of the authorization server, specified in the
Section 5.6 of the ACE framework [I-D.ietf-ace-oauth-authz]. Steps
(D) and (E) are optional, and use the introspection endpoint,
specified in the Section 5.7 of the ACE framework. The Client and
Broker use HTTPS to communicate to AS via these endpoints. If the
Client is resource-constrained, a Client Authorisation Server may
carry out the token request on behalf of the Client, and later,
onboard the Client with the token. Also, these interfaces may be
implemented using other protocols, e.g., CoAP or MQTT. The
interactions between a Client and its Client Authorization Server for
token onboarding, and the MQTTS support for token requests are out of
scope of this document.
+----------------+ +---------------------+
+---(A) Token request----| Client | | Client |
| | Authorization | | |
| +-(B) Access token-->| Server | +---(A) Token request--| Client - |
| | |________________| | | Authorization |
| | | | +-(B) Access token-> Server Interface |
| | (C) Client On-boarding | | | (HTTPS) |
| | | | | |_____________________|
| | +---------v-----+ | | | |
+--v-------------+ | Publisher or | +--v-------------+ | Pub/Sub Interface |
| | | Subscriber | | Authorization | | (MQTTS) |
| Authorization | |_______________| | Server | +-----------^---------+
| Server | | ^
|________________| | | |________________| | |
| ^ (D)Connection (G)Connection | ^ (C)Connection (F)Connection
| | request + response | | request + response
| | access token | | | access token |
| | | | | | | |
| | +---v--------------+ | | +---v--------------+
| | | Broker | | | | Broker (MQTTS) |
| +(E)Introspection-| Resource Server | | | |__________________|
| request (optional) | | | +(D)Introspection-| |
+-(F)Introspection---->|__________________| | request (optional) | RS-AS interface |
| | (HTTPS) |
+-(E)Introspection---->|__________________|
response (optional) response (optional)
Figure 1: Connection establishment Figure 1: Connection establishment
2.1.1. Client Authorization Server (CAS) and Authorization Server (AS) 2.1.1. Client Token Request to the Authorization Server (AS)
Interaction
The first step in the protocol flow (Figure 1 (A)) is the token The first step in the protocol flow (Figure 1 (A)) is the token
acquisition by the client authorization server (CAS) from the AS. If acquisition by the Client from the AS. When requesting an access
a client has enough resources and can support HTTPS, or optionally token from the AS, the Client MAY include parameters in its request
the AS supports MQTTS, these steps can instead be carried out by a as defined in Section 5.6.1 of the ACE framework
client directly. [I-D.ietf-ace-oauth-authz]. The media format is 'application/
ace+json'. The profile parameter MUST be set to 'mqtt_tls'. The
When requesting an access token from the AS, the CAS MAY include OAuth 2.0 AS uses a JSON structure in the payload of its responses
parameters in its request as defined in Section 5.6.1 of the ACE both to client and RS.
framework [I-D.ietf-ace-oauth-authz]. The content type is set to
"application/json". The profile parameter is set to 'mqtt_tls'.
If the AS successfully verifies the access token request and If the AS successfully verifies the access token request and
authorizes the client for the indicated audience (e.g., RS) and authorizes the Client for the indicated audience (e.g., RS) and
scopes (e.g., publish/subscribe permissions over topics), the AS scopes (e.g., publish/subscribe permissions over topics), the AS
issues an access token (Figure 1 (B)). The response includes the issues an access token (Figure 1 (B)). The response includes the
parameters described in Section 5.6.2 of the ACE framework parameters described in Section 5.6.2 of the ACE framework
[I-D.ietf-ace-oauth-authz]. The included token is assumed to be [I-D.ietf-ace-oauth-authz]. The included token is assumed to be
Proof-of-Possession (PoP) token by default. Hence, a 'cnf' parameter Proof-of-Possession (PoP) token by default. This document follows
with a symmetric or asymmetric PoP key is returned. The token may be RFC 7800 [RFC7800] for PoP semantics for JWTs. The PoP token
a reference, or a CBOR or JWT web token. Note that the 'cnf' includes a 'cnf' parameter with a symmetric or asymmetric PoP key.
parameter in the web tokens are to be consumed by the resource server Note that the 'cnf' parameter in the web tokens are to be consumed by
and not the client. For more information on Proof of Possession the resource server and not the Client.
semantics in JWTs see RFC 7800 [RFC7800] and for CWTs, see Proof-of-
Possession Key Semantics for CBOR Web Tokens (CWTs)
[I-D.ietf-ace-cwt-proof-of-possession].
In the case of an error, the AS returns error responses for HTTP- In the case of an error, the AS returns error responses for HTTP-
based interactions as ASCII codes in JSON content, as defined in based interactions as ASCII codes in JSON content, as defined in
Section 5.2 of RFC 6749 [RFC6749]. Section 5.2 of RFC 6749 [RFC6749].
2.1.2. Client Connection Request to the Broker 2.1.2. Client Connection Request to the Broker (C)
Once the client acquires the token, it can use it to request an MQTT This section describes how the Client transports the token to the
connection to the broker over a TLS session with server Broker (RS) via the CONNECT control message after the TLS handshake.
authentication (Figure 1 (D)). This section describes the client This is similar to an earlier proposal by Fremantle et al.
transporting the token to the broker (RS) via the CONNECT control [fremantle14]. Alternatively, the token may be used for the TLS
message after the TLS handshake. This is similar to an earlier session establishment as described in the DTLS profile for ACE
proposal by Fremantle et al. [fremantle14]. An improvement to this [I-D.gerdes-ace-dtls-authorize]. In this case, both the TLS PSK and
is presented in Section 3 for the MQTT v5 - the OASIS Standard RPK handshakes MAY be supported. This may additionally require that
[MQTT-OASIS-Standard-v5]. Alternatively, the token may be used for the Client transports the token to the Broker before the connection
the TLS session establishment as described in the DTLS profile for establishment. To this end, the Broker MAY support /authz-info
ACE [I-D.gerdes-ace-dtls-authorize]. In this case, both the TLS PSK endpoint via the "authz-info" topic. Then, to transport the token,
and RPK handshakes MAY be supported. This may additionally require Clients publish to "authz-info" topic unauthorized. The topic
that the client transports the token to the broker before the "authz-info" MUST be publish-only for Clients (i.e., the Clients are
connection establishment. To this end, the broker MAY support not allowed to subscribe to it). This option is described in more
/authz-info endpoint via the "authz-info" topic. Then, to transport detail in Appendix B.
the token, clients publish to "authz-info" topic unauthorized. The
topic "authz-info" MUST be publish-only for clients (i.e., the
clients are not allowed to subscribe to it). This option is
described in more detail in Appendix B.
When the client wishes to connect to the broker, it uses the CONNECT After the token acquisition, the Client connects to the RS (Broker)
message of MQTT. Figure 2 shows the structure of the MQTT CONNECT using the CONNECT message of MQTT over TLS. For server
control message. authentication, the client MAY either have the ability to receive and
validate a certificate or a raw public key from the Broker. The
client needs to use this raw public key in the TLS handshake together
with an out-of-band validation technique (see RFC 7250 [RFC7250] for
details).
Figure 2 shows the structure of the MQTT CONNECT control message used
in MQTT v5.0. A CONNECT message is composed of a fixed header, a
variable header and a payload. The fixed header contains Control
Packet Type (CPT), Reserved, and Remaining Length. The Variable
Header contains the Protocol Name, Protocol Level, Connect Flags,
Keep Alive, and Properties. The Connect Flags in the variable header
specify the behavior of the MQTT connection. It also indicates the
presence or absence of fields in the Payload. The payload contains
one or more encoded fields, namely a unique Client identifier for the
Client, a Will Topic, Will Payload, User Name and Password. All but
the Client identifier can be omitted depending on flags in the
Variable Header.
0 8 16 24 32 0 8 16 24 32
+------------------------------------------------------+ +------------------------------------------------------+
|CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 | |CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 |
+------------------------------------------------------+ +------------------------------------------------------+
| 'M' 'Q' 'T' 'T' | | 'M' 'Q' 'T' 'T' |
+------------------------------------------------------+ +------------------------------------------------------+
| Proto.level=4|Connect flags| Keep alive | | Proto.level=5|Connect flags| Keep alive |
+------------------------------------------------------+ +------------------------------------------------------+
| Payload | | Property length |
| Username as access token (UTF-8) | | Auth. Method (0x15) | 'ace' |
| Password length (2 Bytes) | | Auth. Data (0x16) | empty or token or |
| Password data as signature/MAC (binary) | | token + PoP data |
| ... | +------------------------------------------------------+
| Payload: Client Identifier |
+------------------------------------------------------+ +------------------------------------------------------+
Figure 2: MQTT CONNECT control message. (CPT=Control Packet Type, Figure 2: MQTT CONNECT control message. (CPT=Control Packet Type,
Rsvd=Reserved, len.=length, Proto.=Protocol) Rsvd=Reserved, len.=length, Proto.=Protocol)
To communicate the necessary connection parameters, the Client uses Connect Flags include Clean Start, Will, Will QoS, Will Retain,
the appropriate flags of the CONNECT message. Figure 3 shows how the Password and Username flags. Figure 6 shows how the MQTT connect
MQTT connect flags MUST be set to initiate a connection with the flags MUST be set to initiate a connection with the Broker.
broker.
+-----------------------------------------------------------+ +-----------------------------------------------------------+
|User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.| |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.|
| flag |flag | | | | | | | flag |flag | | | | | |
+-----------------------------------------------------------+ +-----------------------------------------------------------+
| 1 | 1 | X | X X | X | 1 | 0 | | 0 | 0 | X | X X | X | 1 | 0 |
+-----------------------------------------------------------+ +-----------------------------------------------------------+
Figure 3: MQTT CONNECT flags. (Rsvd=Reserved) Figure 3: MQTT CONNECT flags. (Rsvd=Reserved)
To ensure that the client and the broker discard any previous session To achieve a clean session (i.e., the session starts without an
and start a new session, the Clean Session Flag MUST be set to 1. existing session), the Clean Start Flag MUST be set to 1. In
addition, if the Session Expiry Interval is present in the CONNECT
message, it MUST be set to 0.
The Will flag indicates that a Will message needs to be sent when a The Will Flag indicates that a Will message needs to be sent if
client disconnection occurs. The situations in which the Will network connection is not closed normally. The situations in which
message is published include disconnections due to I/O or network the Will message is published include disconnections due to I/O or
failures, and the server closing the networking connection due to a network failures, and the server closing the network connection due
protocol error. The client may set the Will flag as desired (marked to a protocol error. The Client may set the Will Flag as desired
as 'X' in Figure 3). If the Will flag is set to 1 and the broker (marked as 'X' in Figure 3). If the Will Flag is set to 1 and the
accepts the connection request, the broker must store the Will Broker accepts the connection request, the Broker must store the Will
message, and publish it when the network connection is closed message, and publish it when the network connection is closed
according to Will QoS and Will retain parameters, and MQTT Will according to Will QoS and Will retain parameters, and MQTT Will
management rules. Section 2.5 explains how the broker deals with the management rules. To avoid publishing Will Messages in the case of
retained messages in further detail. temporary network disconnections, the Client my specify a Will Delay
Interval in Will Properties. Section 2.5 explains how the Broker
deals with the retained messages in further detail.
Finally, Username and Password flags MUST be set to 1 to ensure that For token transport, the RS SHOULD support AUTH (Authentication
the Payload of the CONNECT message includes both Username and Exchange) method. The RS MAY support token transport via username
Password fields. and password, which is described in Section 3 for MQTT v3.1.1. The
rest of this section describes the AUTH method, for which the
username and password flags MUST be set to 0.
The CONNECT message defaults to ACE for authentication and To implement the AUTH (Authentication Exchange) method, the Client
authorization. For the basic operation described in this section, MUST set the Authentication Method as a property of a CONNECT packet
the Username field MUST be set to the access token. The Password by using the property identifier 21 (0x15). This is followed by a
field MUST be set to the keyed message digest (MAC) or signature UTF-8 Encoded String containing the name of the authentication
associated with the access token for proof-of-possession. The client method, which MUST be set to 'ace'. If the RS does not support this
MAY apply the PoP key either to the entire request by computing a profile, it sends a CONNACK with a Reason Code of '0x8C (Bad
keyed message digest (for symmetric key) or a digital signature (for authentication method)'.
asymmetric key). The CONNECT message is assumed to have enough
randomness in the payload, and inside a TLS session (excluding the
0-RTT case) will not be exposed to a replay attack. When either
cannot be guaranteed, the Password MAY also contain a nonce.
Section 3.1.3 of MQTT v3.1.1 - the OASIS Standard The Authentication Method is followed by the Authentication Data,
[MQTT-OASIS-Standard] defines the MQTT Username as a UTF-8 encoded which has a property identifier 22 (0x16) and is binary data. Based
string, which is prefixed by a 2-byte length field followed by UTF-8 on the Authentication Data, this profile allows:
encoded character data up to 65535 bytes. Therefore an access token
that is not a valid UTF-8 MUST be Base64 [RFC4648] encoded. (The o Proof-of-Possession over predefined field
MQTT Password allows binary data up to 65535 bytes, and so, does not
require encoding.) o Proof-of-Possession via challenge/response
o Unauthorised request: Authorisation Server discovery
2.1.2.1. Proof-of-Possession over Predefined Field
For this option, the Authentication Data MUST contain the token and
the keyed message digest (MAC) or the Client signature. To calculate
the keyed message digest (MAC) or the Client signature, the Client
SHOULD apply the PoP key to the CONNECT payload. The CONNECT payload
has at least a Client Identifier, and if the Will Flag is set to 1,
may contain Will-related information. The Client Identifier is a
MUST be a UTF-8 Encoded String (i.e., is prefixed with a two-byte
integer length field that gives the number of bytes in a UTF-8
encoded string itself). The Client Identifier may be 1-23 UTF-8
encoded bytes, and contain only the characters
"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".
However, according to MQTTv5 standard, the Broker may except longer
Client Identifiers, and characters not included in the list given
above. Clients MUST change their Client Identifier for each session,
if the Client Identifier is the only source of randomness in the
payload to defend against a replay attack. If the Client reuses its
Client Identifier across different sessions, the Authentication Data
MUST also contain a nonce, and the keyed message digest (MAC) or the
Client signature MUST be computed over this nonce. Finally, the
token is validated as described in Section 2.1.3 and the server
responds with a CONNACK.
2.1.2.2. Proof-of-Possession via challenge/response
For this option, the RS follows a challenge/response protocol. The
success case is illustrated in Figure 4. If the Authentication Data
only includes the token, the RS MUST respond with an AUTH packet,
with the Authenticate Reason Code set to '0x18 (Continue
Authentication)'. This packet includes the Authentication Method,
which MUST be set to 'ace' and Authentication Data. The
Authentication Data MUST NOT be empty and contains a challenge for
the Client. The Client responds to this with an AUTH packet with a
reason code '0x18 (Continue Authentication)'. Similarly, the Client
packet sets the Authentication Method to 'ace'. The Authentication
Data in the Client's response contains the signature or MAC computed
over the RS's challenge. Next, the token is validated as described
in Section 2.1.3.
Resource
Client Server
| |
|<===========>| TLS connection establishment
| |
| |
+------------>| CONNECT with Authentication Data
| | contains only token
| |
<-------------+ AUTH '0x18 (Continue Authentication)'
| | challenge
| |
|------------>| AUTH '0x18 (Continue Authentication)'
| | signature
| |
| |-----+ Token validation (may involve introspection)
| | |
| |<----+
| |
|<------------+ CONNACK '0x00 (Success)'
Figure 4: PoP Challenge/Response Protocol Flow - Success
2.1.2.3. Unauthorised Request: Authorisation Server Discovery
Finally, this document allows the CONNECT message to have an empty
Authentication Data field. This is the AS discovery option and the
RS responds with the CONNACK reason code '0x87 (Not Authorized)' and
includes a User Property (identified by 38 (0x26)) for the AS
creation hints as dedined in the Section 5.1.2 of the ACE framework
[I-D.ietf-ace-oauth-authz].
2.1.3. Token Validation 2.1.3. Token Validation
RS MUST verify the validity of the token. This validation MAY be The RS MUST verify the validity of the token. This validation MAY be
done locally (e.g., in the case of a self-contained token) or the RS done locally (e.g., in the case of a self-contained token) or the RS
MAY send an introspection request to the AS. If introspection is MAY send an introspection request to the AS. If introspection is
used, this section follows similar steps to those described in used, this section follows similar steps to those described in
Sections 5.7 of the ACE framework [I-D.ietf-ace-oauth-authz]. The Sections 5.7 of the ACE framework [I-D.ietf-ace-oauth-authz]. The
communication between AS and RS MAY be HTTPS, but it, in every case, communication between AS and RS MUST be confidential, mutually
MUST be confidential, mutually authenticated and integrity protected. authenticated and integrity protected.
The broker MUST check if the token is active either using 'exp' claim The Broker MUST check if the token is active either using 'exp' claim
of the token or 'active' parameter of the introspection response. of the token or 'active' parameter of the introspection response.
Also, if present in the access token, RS must check that the 'iss'
corresponds to AS, the 'aud' field corresponds to RS. It also has to
check whether the 'nbf' and the 'iat' claims are present and valid.
The access token is constructed by the AS such that RS can associate To authenticate the Client, the RS validates the signature or the
the access token with the client key. This document assumes that the MAC, depending on how the PoP protocol is implemented. To authorize
Access Token is a PoP token as described in the Client, the Broker uses the scope field in the token (or in the
[I-D.ietf-ace-oauth-authz]. Therefore, the necessary information is introspection result). The scope field contains the publish and
contained in the 'cnf' claim of the access token and may use either subscribe permissions for the Client. If the Will Flag is set,then
public or shared key approaches. The client uses the signature or the Broker MUST check that the token allows the publication of the
the MAC in the password field to prove the possession of the key. Will message.
The resource server validates the signature or the MAC over the
contents of the packet, authenticating the client.
The broker uses the scope field in the token (or in the introspection
result) to determine the publish and subscribe permissions for the
client. If the Will flag is set, then the broker MUST check that the
token allows the publication of the Will message too.
If the token is not self-contained and the broker uses token
introspection, it MAY cache the validation result to decide whether
to accept subsequent PUBLISH and SUBSCRIBE messages as these
messages, which are sent after a connection set-up, do not contain
access tokens. If the introspection result is not cached, then the
RS needs to introspect the saved token for each request.
Scope strings SHOULD be encoded as a permission, followed by an Scope strings SHOULD be encoded as a permission, followed by an
underscore, followed by a topic filter. Two permissions apply to underscore, followed by a topic filter. Two permissions apply to
topics: 'publish' and 'subscribe'. An example scope field may topics: 'publish' and 'subscribe'. An example scope field may
contain multiple such strings, space delimited, e.g., 'publish_topic1 contain multiple such strings, space delimited, e.g., 'publish_topic1
subscribe_topic2/#'. Hence, this access token would give 'publish' subscribe_topic2/#'. Hence, this access token would give 'publish'
permission to the 'topic1', 'subscribe' permission to all the permission to the 'topic1', 'subscribe' permission to all the
subtopics of 'topic2'. subtopics of 'topic2'.
Also, if present in the access token, RS must check that the 'iss'
corresponds to AS, the 'aud' field (if not used to define topics)
corresponds to RS. It also has to check whether 'nbf' and 'iat'
claims are present and valid.
2.1.4. The Broker's Response to Client Connection Request 2.1.4. The Broker's Response to Client Connection Request
Based on the validation result (obtained either via local inspection Based on the validation result (obtained either via local inspection
or using the /introspection interface of the AS), the broker MUST or using the /introspection interface of the AS), the Broker MUST
send a CONNACK message to the client. send a CONNACK message to the Client. The reason code of the CONNACK
is '0x00 (Success)' if the authentication is successful. In case of
The broker responses may follow either the MQTT v3.1.1 - the OASIS an invalid PoP token, the CONNACK reason code is '0x87 (Not
Standard [MQTT-OASIS-Standard] or the MQTT v5 - the OASIS Standard Authorized)'.
[MQTT-OASIS-Standard-v5], depending on which version(s) the broker
supports.
In MQTT v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard], it is not If the RS accepts the connection, it MUST store the token until the
possible to support AS discovery via sending a tokenless CONNECT end of connection. On Client or RS disconnection, the token is
message to the broker. This is because a CONNACK packet does not discarded, and the Client MUST provide a token inside each CONNECT
include a means to provide additional information to the client. message.
Therefore, AS discovery needs to take place out-of-band. This is
remedied in the MQTT v5 - the OASIS Standard [MQTT-OASIS-Standard-v5]
and a solution is described in Section 3.
If the RS accepts the connection, it MUST store the token. If the token is not self-contained and the Broker uses token
introspection, it MAY cache the validation result to authorize the
subsequent PUBLISH and SUBSCRIBE messages. PUBLISH and SUBSCRIBE
messages, which are sent after a connection set-up, do not contain
access tokens. If the introspection result is not cached, then the
RS needs to introspect the saved token for each request. The Broker
SHOULD use a cache time out to introspect tokens regularly.
2.2. Authorizing PUBLISH Messages 2.2. Authorizing PUBLISH Messages
2.2.1. PUBLISH Messages from the Publisher Client to the Broker 2.2.1. PUBLISH Messages from the Publisher Client to the Broker
On receiving the PUBLISH message, the broker MUST use the type of On receiving the PUBLISH message, the Broker MUST use the type of
message (i.e., PUBLISH) and the topic name in the message header to message (i.e., PUBLISH) and the Topic name in the message header to
compare against the cached token or its introspection result. compare against the cached token or its introspection result.
If the client is allowed to publish to the topic, the RS must publish If the Client is allowed to publish to the topic, the RS must publish
the message to all valid subscribers of the topic. The broker may the message to all valid subscribers of the topic. The Broker may
also return an acknowledgment message if the QoS level is greater also return an acknowledgment message if the QoS level is greater
than or equal to 1. than or equal to 1.
In case of a failure, it is not possible to return an error in MQTT In case of an authorization failure, an error MAY be returned to the
v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard]. Acknowledgement Client. For this the QoS level of the PUBLISH message, should be set
messages only indicate success. In the case of an authorization to greater than or equal to 1. This guarantees that RS responds with
error, the broker SHOULD disconnect the client. Otherwise, it MUST either a PUBACK or PUBREC packet with reason code '0x87 (Not
ignore the PUBLISH message. Also, DISCONNECT messages are only sent authorized)'.
from a client to the broker. So, server disconnection needs to take
place below the application layer. However, in MQTT v5 - the OASIS On receiving a PUBACK with '0x87 (Not authorized)', the Client MAY
Standard [MQTT-OASIS-Standard-v5], it is possible to indicate failure reauthenticate as described in Section 2.4, and pass a new token
and provide a reason code. Section 3 describes in more detail how following the same PoP methods as described in Figure 2.
MQTT v5 handles PUBLISH authorization errors.
2.2.2. PUBLISH Messages from the Broker to the Subscriber Clients 2.2.2. PUBLISH Messages from the Broker to the Subscriber Clients
To forward PUBLISH messages to the subscribing clients, the broker To forward PUBLISH messages to the subscribing Clients, the Broker
identifies all the subscribers that have valid matching topic identifies all the subscribers that have valid matching topic
subscriptions (i.e., the tokens are valid, and token scopes allow a subscriptions (i.e., the tokens are valid, and token scopes allow a
subscription to the particular topic name). The broker sends a subscription to the particular topic). The Broker sends a PUBLISH
PUBLISH message with the topic name and the topic message to all the message with the Topic name to all the valid subscribers.
valid subscribers.
In MQTT, after connection establishment, there is no way to inform a RS MUST stop forwarding messages to the unauthorized subscribers.
client that an authorization error has occurred for previously For Clients with invalid tokens, there is no way to inform the Client
subscribed topics, e.g., token expiry. In the case of an that an authorization error has occurred other than sending a
authorization error, the broker disconnects the client. In the MQTT DISCONNECT message. The RS SHOULD send a DISCONNECT message with the
v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard], the MQTT reason code '0x87 (Not authorized)'. Note that the server-side
DISCONNECT messages are only sent from a client to the broker. DISCONNECT is a new feature of MQTT v5.0 (in MQTT v3.1.1, the server
Therefore, the server disconnection needs to take place below the needs to drop the connection).
application layer. In MQTT v5 - the OASIS Standard
[MQTT-OASIS-Standard-v5], a server-side DISCONNECT message is
possible and described in Section 3.
2.3. Authorizing SUBSCRIBE Messages 2.3. Authorizing SUBSCRIBE Messages
In MQTT, a SUBSCRIBE message is sent from a client to the broker to In MQTT, a SUBSCRIBE message is sent from a Client to the Broker to
create one or more subscriptions to one or more topics. The create one or more subscriptions to one or more topics. The
SUBSCRIBE message may contain multiple topic filters. The topic SUBSCRIBE message may contain multiple Topic Filters. The Topic
filters may include wildcard characters. Filters may include wildcard characters.
On receiving the SUBSCRIBE message, the broker MUST use the type of On receiving the SUBSCRIBE message, the Broker MUST use the type of
message (i.e., SUBSCRIBE) and the topic filter in the message header message (i.e., SUBSCRIBE) and the Topic Filter in the message header
to compare against the stored token or introspection result. to compare against the stored token or introspection result.
As a response to the SUBSCRIBE message, the broker issues a SUBACK As a response to the SUBSCRIBE message, the Broker issues a SUBACK
message. For each topic filter, the SUBACK packet includes a return message. For each Topic Filter, the SUBACK packet includes a return
code matching the QoS level for the corresponding topic filter. In code matching the QoS level for the corresponding Topic Filter. In
the case of failure, the return code, in MQTT v3.1.1, must be 0x80 the case of failure, the return code is 0x87, indicating that the
indicating 'Failure'. In MQTT v5, the appropriate return code is Client is 'Not authorized'. A reason code is returned for each Topic
0x87, indicating that the client is 'Not authorized'. Note that, in Filter. Therefore, the Client may receive success codes for a subset
both MQTT versions, a reason code is returned for each topic filter. of its Topic Filters while being unauthorized for the rest.
Therefore, the client may receive success codes for a subset of its
topic filters, while being unauthorized for the rest.
2.4. Token Expiration 2.4. Token Expiration and Reauthentication
The broker MUST check for token expiration whenever a CONNECT, The Broker MUST check for token expiration whenever a CONNECT,
PUBLISH or SUBSCRIBE message is received or sent. The broker SHOULD PUBLISH or SUBSCRIBE message is received or sent. The Broker SHOULD
check for token expiration on receiving a PINGREQUEST message. This check for token expiration on receiving a PINGREQUEST message. This
may allow for early detection of a token expiry. may allow for early detection of a token expiry.
The token expiration is checked by checking the 'exp' claim of a CWT/ The token expiration is checked by checking the 'exp' claim of a JWT
JWT or via performing an introspection request with the Authorization or introspection response, or via performing an introspection request
server as described in Section 5.7 of the ACE framework with the Authorization server as described in Section 5.7 of the ACE
[I-D.ietf-ace-oauth-authz]. In the basic operation, token framework [I-D.ietf-ace-oauth-authz]. Token expirations may trigger
expirations MAY lead to disconnecting the associated client. the RS to send PUBACK, SUBACK and DISCONNECT messages with return
However, in MQTT v5 - the OASIS Standard [MQTT-OASIS-Standard-v5], code set to 'Not authorised'. As a response, the Client MAY re-
better error handling and re-authentication are possible. This is authenticate by sending an AUTH packet with a Reason Code of 0x19
explained in more detail in Section 3. (Re-authentication)
2.5. Handling Disconnections and Retained Messages To re-authenticate, the Client sends an AUTH packet with reason code
'0x19 (Re-authentication)'. The Client MUST set the authentication
method as 'ace' and transport the new token in the Authentication
Data. The Client and the RS go through the same steps for proof of
possession validation as described in Section 2.1.2. If the re-
authentication fails, the server MUST send a DISCONNECT with the
reason code '0x87 (Not Authorized)'. The Clients can also
proactively update their tokens before they receive a message with
'Not authorized' return code.
According to MQTT v3.1.1 - the OASIS Standard [MQTT-OASIS-Standard], 2.5. Handling Disconnections and Retained Messages
only Client DISCONNECT messages are allowed. In MQTT v5 - the OASIS
Standard [MQTT-OASIS-Standard-v5], server-side DISCONNECT messages
are possible, allowing to return '0x87 Not Authorized' return code to
the client.
In the case of a DISCONNECT, due to the Clean Session flag, the In the case of a Client DISCONNECT, due to the Clean Session flag,
broker deletes all session state but MUST keep the retained messages. the Broker deletes all session state but MUST keep the retained
By setting a RETAIN flag in a PUBLISH message, the publisher messages. By setting a RETAIN flag in a PUBLISH message, the
indicates to the broker that it should store the most recent message publisher indicates to the Broker that it should store the most
for the associated topic. Hence, the new subscribers can receive the recent message for the associated topic. Hence, the new subscribers
last sent message from the publisher for that particular topic can receive the last sent message from the publisher of that
without waiting for the next PUBLISH message. In the case of a particular topic without waiting for the next PUBLISH message. The
disconnection, the broker MUST continue publishing the retained Broker MUST continue publishing the retained messages as long as the
messages as long as the associated tokens are valid. associated tokens are valid.
In case of disconnections due to network errors or server In case of disconnections due to network errors or server
disconnection due to a protocol error (which includes authorization disconnection due to a protocol error (which includes authorization
errors), the Will message must be sent if the client supplied a Will errors), the Will message must be sent if the Client supplied a Will
in the CONNECT request message. The token provided in the CONNECT in the CONNECT message. The Client's token scopes MUST include the
request must cover the Will topic. The Will message MUST be Will Topic. The Will message MUST be published to the Will Topic
published to the Will topic when the network connection is closed when the network connection is closed regardless of whether the
regardless of whether the corresponding token has expired. corresponding token has expired. In the case of a server-side
DISCONNECT, the server returns the '0x87 Not Authorized' return code
to the Client.
3. Improved Protocol Interactions with MQTT v5 3. Reduced Protocol Interactions for MQTT v3.1.1
In the new MQTT v5 - the OASIS Standard [MQTT-OASIS-Standard-v5], This section describes a reduced set of protocol interactions for the
several new capabilities are introduced, which enable better MQTT v3.1.1 Client.
integration with ACE. The newly enhanced authentication and re-
authentication methods support a wider range of authentication flows
beyond username and password. With the MQTT v5, there is a clearly
defined approach for using token-based authorization. Also, it is
possible for a client to request a re-authentication avoiding
disconnection. Finally, MQTT v5 generally improves error reporting,
enabling better response to authorization failures during publishing
messages to the subscribers.
3.1. Token Transport via Authentication Exchange (AUTH) 3.1. Token Transport
To initiate the authentication and authorization flow, as before, the To transport the token to the Broker, the Clients use the username
CAS initiates the token request as in Section 2.1. When the client and password fields of the CONNECT control message after the TLS
wishes to connect to the RS (broker), it uses the CONNECT message of handshake. Figure 5 shows the structure of the MQTT CONNECT message.
MQTT. Figure 4 shows the structure of the MQTT CONNECT control
message used in MQTT v5.
0 8 16 24 32 0 8 16 24 32
+------------------------------------------------------+ +------------------------------------------------------+
|CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 | |CPT=1 | Rsvd.|Remaining len.| Protocol name len. = 4 |
+------------------------------------------------------+ +------------------------------------------------------+
| 'M' 'Q' 'T' 'T' | | 'M' 'Q' 'T' 'T' |
+------------------------------------------------------+ +------------------------------------------------------+
| Proto.level=5|Connect flags| Keep alive | | Proto.level=4|Connect flags| Keep alive |
+------------------------------------------------------+ +------------------------------------------------------+
| Property length | | Payload |
| Auth. Method (0x15) | 'ace' | | Client Identifier |
| Auth. Data (0x16) | empty or token or | | Username as access token (UTF-8) |
| token + PoP data | | Password length (2 Bytes) |
| Password data as signature/MAC (binary) |
+------------------------------------------------------+ +------------------------------------------------------+
Figure 4: MQTT CONNECT control message. (CPT=Control Packet Type, Figure 5: MQTT CONNECT control message. (CPT=Control Packet Type,
Rsvd=Reserved, len.=length, Proto.=Protocol) Rsvd=Reserved, len.=length, Proto.=Protocol)
To communicate the necessary connection parameters, the client uses Figure 6 shows how the MQTT connect flags MUST be set to initiate a
the appropriate flags of the CONNECT message. To achieve a clean connection with the Broker.
session (i.e., the session should start without an existing session),
the new MQTT v5 session flags MUST be set appropriately: the Clean
Start Flag MUST be set to 1 and Session Expiry Interval MUST be set
to 0.
With the enhanced authentication capabilities, it is not necessary to +-----------------------------------------------------------+
overload the username and password fields in the CONNECT message for |User name|Pass.|Will retain|Will QoS|Will Flag|Clean| Rsvd.|
ACE authentication. Nevertheless, the RS MUST support both methods | flag |flag | | | | | |
for supporting the token: (1) Token transport via username and +-----------------------------------------------------------+
password and (2) using the new AUTH (Authentication Exchange) method. | 1 | 1 | X | X X | X | 1 | 0 |
The token transport via username and password is as described in +-----------------------------------------------------------+
Section 2.1.2. The rest of this section describes the AUTH method.
To use the AUTH method, the username flag MUST be set to 0, and the Figure 6: MQTT CONNECT flags. (Rsvd=Reserved)
password flag MUST be set to 0. The client can set the
Authentication Method as a property of a CONNECT packet by setting
Auth Properties (with the property identifier 0x15). The client must
MUST set the UTF-8 encoded string containing the name of the
authentication method as 'ace'. If the RS does not support this
profile, it sends a CONNACK with a Reason Code of '0x8C (Bad
authentication method)'
The Authentication Method is followed by the Authentication Data, The Clean Session Flag MUST be set to 1. The Client may set the Will
which has a property identifier 0x16. Authentication data is binary Flag as desired (marked as 'X' in Figure 6). Username and Password
data and is defined by the authentication method. The RS MAY support flags MUST be set to 1 to ensure that the Payload of the CONNECT
different implementations for transporting the authentication data. message includes both Username and Password fields.
The first option is that Authentication data contains both the token
and the keyed message digest (MAC) or signature as described in
Section 2.1.2. The encoding of this field MAY use CBOR and COSE. In
this case, the token validation proceeds as described in
Section 2.1.3 and the server responds with a CONNACK. The reason
code of the CONNACK is '0x00 (Success)' if the authentication is
successful. In case of an invalid PoP token, the CONNACK reason code
is '0x87 (Not Authorized)'.
The second option that RS may accept is a challenge/response The CONNECT message defaults to ACE for authentication and
protocol. If the Authentication Data only includes the token, the RS authorization. The Username field MUST be set to the access token.
MUST respond with an AUTH packet, with the Authenticate Reason Code
set to '0x18 (Continue Authentication)'. This packet includes the
Authentication Method, which MUST be set to 'ace' and Authentication
Data. The Authentication Data MUST NOT be empty and contains a
challenge for the client. The client responds to this with an AUTH
packet, with a reason code '0x18 (Continue Authentication)'.
Similarly, the client packet sets the Authentication Method to 'ace'.
The Authentication Data in the client's response contains the
signature or MAC computed over the RS's challenge. To this, the
server responds with a CONNACK and return code '0x00 (Success)' if
the authentication is successful. In case of an invalid PoP token,
the CONNACK reason code is '0x87 (Not Authorized)'.
Finally, this document allows the CONNECT message to have an empty The Password field MUST be set to the keyed message digest (MAC) or
Authentication Data field. This is the AS discovery option and the signature associated with the access token for proof-of-possession.
RS responds with the CONNACK reason code '0x87 (Not Authorized)' and The Client MUST apply the PoP key to the payload as described in
includes a User Property for the AS information. AS Information Section 2.1.2.1.
contains the absolute URI of AS, and MAY also contain a cnonce as
described in the Section 5.1 of the ACE framework
[I-D.ietf-ace-oauth-authz]. This information MAY be CBOR encoded.
3.2. Authorization Errors and Client Re-authentication In MQTT v3.1.1, the MQTT Username as a UTF-8 encoded string (i.e., is
prefixed by a 2-byte length field followed by UTF-8 encoded character
data) and may be up to 65535 bytes. Therefore, an access token that
is not a valid UTF-8 MUST be Base64 [RFC4648] encoded. (The MQTT
Password allows binary data up to 65535 bytes.)
MQTT v5 allows better error reporting. To take advantage of this for 3.2. Handling Authorization Errors
PUBLISH messages, the QoS level should be set to greater than or
equal to 1. This guarantees that RS responds with either a PUBACK or
PUBREC packet with reason code '0x87 (Not authorized)' in the case of
an authorization error. Similarly, for the SUBSCRIBE case, the
SUBACK packet has a reason code set to '0x87 (Not authorized)' for
the unauthorized topic(s). When RS is forwarding PUBLISH messages to
the subscribed clients, it may discover that some of the subscribers
are no more authorized due to expired tokens. In this case, the RS
SHOULD send a DISCONNECT message with the reason code '0x87 (Not
authorized)'. Note that the server-side DISCONNECT is a new feature
of MQTT v5 (in MQTT v3.1.1, the server needed to drop the
connection). RS MUST stop forwarding messages to the unauthorized
subscribers.
In the case of a PUBACK with '0x87 (Not authorized)', the client can Handling errors are more primitive in MQTT v3.1.1 due to not having
update its token using the Re-authentication feature of MQTT v5. appropriate error fields, error codes, and server-side DISCONNECTS.
In the following, we list how errors are handled without such
protocol support.
Also, the clients can proactively update their tokens without waiting o CONNECT without a token: It is not possible to support AS
for such a PUBACK. To re-authenticate, the client sends an AUTH discovery via sending a tokenless CONNECT message to the Broker.
packet with reason code '0x19 (Re-authentication)'. The client MUST This is because a CONNACK packet in MQTT v3.1.1 does not include a
set the authentication method as 'ace' and transport the new token in means to provide additional information to the Client. Therefore,
the Authentication Data. The client and the RS go through the same AS discovery needs to take place out-of-band. CONNECT attempt
steps for proof of possession validation as described in the previous MUSY fail.
section. If the re-authentication fails, the server MUST send a
DISCONNECT with the reason code '0x87 (Not Authorized)'. o Client-RS PUBLISH authorization failure: In case of a failure, it
is not possible to return an error in MQTT v3.1.1.
Acknowledgement messages only indicate success. In the case of an
authorization error, the Broker SHOULD disconnect the Client.
Otherwise, it MUST ignore the PUBLISH message. Also, DISCONNECT
messages are only sent from a Client to the Broker. So, server
disconnection needs to take place below the application layer.
o SUBSCRIBE authorization failure: In the SUBACK packet, the return
code must be 0x80 indicating 'Failure' for the unauthorized
topic(s). Note that, in both MQTT versions, a reason code is
returned for each Topic Filter.
o RS-Client PUBLISH authorization failure: When RS is forwarding
PUBLISH messages to the subscribed Clients, it may discover that
some of the subscribers are no more authorized due to expired
tokens. These token expirations SHOULD lead to disconnecting the
Client, rather than silently dropping messages.
4. IANA Considerations 4. IANA Considerations
The following registrations are done for the ACE OAuth Profile The following registrations are done for the ACE OAuth Profile
Registry following the procedure specified in Registry following the procedure specified in
[I-D.ietf-ace-oauth-authz]. [I-D.ietf-ace-oauth-authz].
Note to the RFC editor: Please replace all occurrences of "[RFC- Note to the RFC editor: Please replace all occurrences of "[RFC-
XXXX]" with the RFC number of this specification and delete this XXXX]" with the RFC number of this specification and delete this
paragraph. paragraph.
Profile name: mqtt_tls Profile name: mqtt_tls
Profile description: Profile for delegating client authentication and Profile description: Profile for delegating Client authentication and
authorization using MQTT as the application protocol and TLS For authorization using MQTT as the application protocol and TLS For
transport layer security. transport layer security.
Profile ID: Profile ID:
Change controller: IESG Change controller: IESG
Reference: [RFC-XXXX] Reference: [RFC-XXXX]
5. Security Considerations 5. Security Considerations
This document specifies a profile for the Authentication and This document specifies a profile for the Authentication and
Authorization for Constrained Environments (ACE) framework Authorization for Constrained Environments (ACE) framework
[I-D.ietf-ace-oauth-authz]. Therefore, the security considerations [I-D.ietf-ace-oauth-authz]. Therefore, the security considerations
outlined in [I-D.ietf-ace-oauth-authz] apply to this work. outlined in [I-D.ietf-ace-oauth-authz] apply to this work.
In addition, the security considerations outlined in MQTT v3.1.1 - In addition, the security considerations outlined in MQTT v5.0 - the
the OASIS Standard [MQTT-OASIS-Standard] and MQTT v5 - the OASIS OASIS Standard [MQTT-OASIS-Standard-v5] and MQTT v3.1.1 - the OASIS
Standard [MQTT-OASIS-Standard-v5] apply. Mainly, this document Standard [MQTT-OASIS-Standard] apply. Mainly, this document provides
provides an authorization solution for MQTT, the responsibility of an authorization solution for MQTT, the responsibility of which is
which is left to the specific implementation in MQTT v5 - the OASIS left to the specific implementation in MQTT v5.0 standard. In the
Standard [MQTT-OASIS-Standard-v5]. In the following, we comment on a following, we comment on a few relevant issues based on the current
few relevant issues based on the current MQTT specifications. MQTT specifications.
In this document, RS uses the PoP access token to authenticate the In this document, RS uses the PoP access token to authenticate the
client. If the client is able, TLS certificates sent from the client Client. If the Client is able, TLS certificates sent from the Client
can be used by the RS to authenticate the client. The TLS can be used by the RS to authenticate the Client. The Client may
certificate from the RS MUST be used by the client to authenticate authenticate the RS either using a server cerficate or the RPK
the RS. method. In the case of RPK, client needs to use this raw public key
in the TLS handshake together with an out-of-band validation
technique (see [RFC7250] for details).
To authorize a client's publish and subscribe requests in an ongoing To authorize a Client's publish and subscribe requests in an ongoing
session, the RS caches the access token after accepting the session, the RS caches the access token after accepting the
connection from the client. However, if some permissions are revoked connection from the Client. However, if some permissions are revoked
in the meantime, the RS may still grant publish/subscribe to revoked in the meantime, the RS may still grant publish/subscribe to revoked
topics until the session ends or the token expires. When permissions topics. If the RS caches the token introspection responses, then the
change dynamically, it is expected that AS follows a reasonable RS should use a reasonable cache timeout to introspect tokens
expiration strategy for the access tokens. regularly. When permissions change dynamically, it is expected that
AS also follows a reasonable expiration strategy for the access
tokens.
The RS may monitor client behaviour to detect potential security The RS may monitor Client behaviour to detect potential security
problems, especially those affecting availability. These include problems, especially those affecting availability. These include
repeated token transfer attempts to the public "authz-info" topic, repeated token transfer attempts to the public "authz-info" topic,
repeated connection attempts, abnormal terminations, and clients that repeated connection attempts, abnormal terminations, and Clients that
connect but do not send any data. If the RS supports the public connect but do not send any data. If the RS supports the public
"authz-info" topic, described in Appendix B, then this may be "authz-info" topic, described in Appendix B, then this may be
vulnerable to a DDoS attack, where many clients use the "authz-info" vulnerable to a DDoS attack, where many Clients use the "authz-info"
public topic to transport fictitious tokens, which RS may need to public topic to transport fictitious tokens, which RS may need to
store indefinitely. store indefinitely.
6. Privacy Considerations 6. Privacy Considerations
The privacy considerations outlined in [I-D.ietf-ace-oauth-authz] The privacy considerations outlined in [I-D.ietf-ace-oauth-authz]
apply to this work. apply to this work.
In MQTT, the RS is a central trusted party and may forward In MQTT, the RS is a central trusted party and may forward
potentially sensitive information between clients. Clients may potentially sensitive information between Clients. Clients may
choose to encrypt the payload of their messages. However, this would choose to encrypt the payload of their messages. However, this would
not provide privacy for other properties of the message such as topic not provide privacy for other properties of the message such as Topic
name. Name.
7. References 7. References
7.1. Normative References 7.1. Normative References
[I-D.gerdes-ace-dtls-authorize] [I-D.gerdes-ace-dtls-authorize]
Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and
L. Seitz, "Datagram Transport Layer Security (DTLS) L. Seitz, "Datagram Transport Layer Security (DTLS)
Profile for Authentication and Authorization for Profile for Authentication and Authorization for
Constrained Environments (ACE)", draft-gerdes-ace-dtls- Constrained Environments (ACE)", draft-gerdes-ace-dtls-
skipping to change at page 19, line 20 skipping to change at page 20, line 13
(work in progress), March 2019. (work in progress), March 2019.
[MQTT-OASIS-Standard] [MQTT-OASIS-Standard]
Banks, A., Ed. and R. Gupta, Ed., "OASIS Standard MQTT Banks, A., Ed. and R. Gupta, Ed., "OASIS Standard MQTT
Version 3.1.1 Plus Errata 01", 2015, <http://docs.oasis- Version 3.1.1 Plus Errata 01", 2015, <http://docs.oasis-
open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html>. open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html>.
[MQTT-OASIS-Standard-v5] [MQTT-OASIS-Standard-v5]
Banks, A., Ed., Briggs, E., Ed., Borgendale, K., Ed., and Banks, A., Ed., Briggs, E., Ed., Borgendale, K., Ed., and
R. Gupta, Ed., "OASIS Standard MQTT Version 5.0", 2017, R. Gupta, Ed., "OASIS Standard MQTT Version 5.0", 2017,
<http://docs.oasis-open.org/mqtt/mqtt/v5.0/os/ <http://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-
mqtt-v5.0-os.html>. v5.0-os.html>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>. <https://www.rfc-editor.org/info/rfc4648>.
[RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J.,
Weiler, S., and T. Kivinen, "Using Raw Public Keys in
Transport Layer Security (TLS) and Datagram Transport
Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250,
June 2014, <https://www.rfc-editor.org/info/rfc7250>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
7.2. Informative References 7.2. Informative References
[fremantle14] [fremantle14]
Fremantle, P., Aziz, B., Kopecky, J., and P. Scott, Fremantle, P., Aziz, B., Kopecky, J., and P. Scott,
"Federated Identity and Access Management for the Internet "Federated Identity and Access Management for the Internet
of Things", research International Workshop on Secure of Things", research International Workshop on Secure
Internet of Things, September 2014, Internet of Things, September 2014,
<http://dx.doi.org/10.1109/SIoT.2014.8>. <http://dx.doi.org/10.1109/SIoT.2014.8>.
[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-07 (work in
progress), October 2018.
[I-D.ietf-ace-cwt-proof-of-possession] [I-D.ietf-ace-cwt-proof-of-possession]
Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. Jones, M., Seitz, L., Selander, G., Erdtman, S., and H.
Tschofenig, "Proof-of-Possession Key Semantics for CBOR Tschofenig, "Proof-of-Possession Key Semantics for CBOR
Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of- Web Tokens (CWTs)", draft-ietf-ace-cwt-proof-of-
possession-06 (work in progress), February 2019. possession-08 (work in progress), October 2019.
[RFC4949] Shirey, R., "Internet Security Glossary, Version 2", [RFC4949] Shirey, R., "Internet Security Glossary, Version 2",
FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007,
<https://www.rfc-editor.org/info/rfc4949>. <https://www.rfc-editor.org/info/rfc4949>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-
Possession Key Semantics for JSON Web Tokens (JWTs)", Possession Key Semantics for JSON Web Tokens (JWTs)",
RFC 7800, DOI 10.17487/RFC7800, April 2016, RFC 7800, DOI 10.17487/RFC7800, April 2016,
<https://www.rfc-editor.org/info/rfc7800>. <https://www.rfc-editor.org/info/rfc7800>.
Appendix A. Checklist for profile requirements Appendix A. Checklist for profile requirements
o AS discovery: For the basic protocol using either MQTT v3.1.1 or o AS discovery: AS discovery is possible with the MQTT v5.0
MQTT v5, the clients/client authorization servers need to be described in Section 2.1.2.
configured out-of-band. RS does not provide any hints to help AS
discovery. AS discovery is possible with the MQTT v5 extensions
described in Section 3.
o The communication protocol between the client and RS: MQTT o The communication protocol between the Client and RS: MQTT
o The security protocol between the client and RS: TLS o The security protocol between the Client and RS: TLS
o Client and RS mutual authentication: RS provides a server o Client and RS mutual authentication: RS provides a server
certificate during TLS handshake. Client transports token and MAC certificate or RPK during TLS handshake. Client transports token
via the MQTT CONNECT message. Other methods for transporting the and MAC via the MQTT CONNECT message.
token with the MQTT v5 extensions described in Section 3.
o Content format: For the HTTPS interactions with AS, "application/ o Content format: For the HTTPS interactions with AS, "application/
json". The MQTT payloads may be formatted JSON or CBOR. ace+json". The MQTT payloads may be formatted in JSON.
o PoP protocols: Either symmetric or asymmetric keys can be o PoP protocols: Either symmetric or asymmetric keys can be
supported. supported.
o Unique profile identifier: mqtt_tls o Unique profile identifier: mqtt_tls
o Token introspection: RS uses HTTPS /introspect interface of AS. o Token introspection: RS uses HTTPS /introspect interface of AS.
o Token request: CAS uses HTTPS /token interface of AS. o Token request: CAS uses HTTPS /token interface of AS.
o /authz-info endpoint: It MAY be supported using the method o /authz-info endpoint: It MAY be supported using the method
described in Appendix B, not protected. described in Appendix B, but is not protected.
o Token transport: In MQTT CONNECT message or using the AUTH o Token transport: In MQTT CONNECT message for both versions of
extensions for MQTT v5 described in Section 3. MQTT. AUTH extensions also used for authentication and re-
authentication for MQTT v5.0 as described in Section 2.1.2.
Appendix B. The Authorization Information Endpoint Appendix B. The Authorization Information Endpoint
The main document described a method for transporting tokens inside The main document described a method for transporting tokens inside
MQTT CONNECT messages. In this section, we describe an alternative MQTT CONNECT messages. In this section, we describe an alternative
method to transport an access token. method to transport an access token.
The method consists of the MQTT broker accepting PUBLISH messages to The method consists of the MQTT Broker accepting PUBLISH messages to
a public "authz-info" topic. A client using this method MUST first a public "authz-info" topic. A Client using this method MUST first
connect to the broker, and publish the access token using the "authz- connect to the Broker, and publish the access token using the "authz-
info" topic. The broker must verify the validity of the token (i.e., info" topic. The Broker must verify the validity of the token (i.e.,
through local validation or introspection). After publishing the through local validation or introspection). After publishing the
token, the client disconnects from the broker and is expected to try token, the Client disconnects from the Broker and is expected to try
reconnecting over TLS. reconnecting over TLS.
In MQTT v3.1.1, after the client published to the "authz-info" topic, In MQTT v5.0, the Broker can return 'Not authorized' error to a
it is not possible for the broker to communicate the result of the PUBLISH request for QoS greater or equal to 1. In MQTT v3.1.1, after
token verification. In MQTT v5, the broker can return 'Not the Client published to the "authz-info" topic, it is not possible
authorized' error to a PUBLISH request for QoS greater or equal to 1. for the Broker to communicate the result of the token verification.
In any case, any token authorization failure affect the subsequent In any case, any token authorization failure affect the subsequent
TLS handshake, which can prompt the client to obtain a valid token. TLS handshake, which can prompt the Client to obtain a valid token.
Appendix C. Document Updates
Version 00 to 01:
o Present the MQTTv5 as the RECOMMENDED version, and MQTT v3.1.1 for
backward compatibility.
o Clarified Will message.
o Improved consistency in the use of terminology, and upper/lower
case.
o Defined Broker and MQTTS.
o Clarified HTTPS use for C-AS and RS-AS communication. Removed
reference to actors document, and clarified the use of client
authorization server.
o Clarified the Connect message payload and Client Identifier.
o Presented different methods for passing the token, and PoP.
o Added new figures for AUTH methods, updated CONNECT message
figure.
Acknowledgements Acknowledgements
The authors would like to thank Ludwig Seitz for his review and his The authors would like to thank Ludwig Seitz for his review and his
input on the authorization information endpoint, presented in the input on the authorization information endpoint, presented in the
appendix. appendix.
Authors' Addresses Authors' Addresses
Cigdem Sengul Cigdem Sengul
Nominet Nominet
2 Kingdom Street 4 Kingdom Street
London W2 6BD London W2 6BD
UK UK
Email: Cigdem.Sengul@nominet.uk Email: Cigdem.Sengul@nominet.uk
Anthony Kirby Anthony Kirby
Oxbotica Oxbotica
1a Milford House, Mayfield Road, Summertown 1a Milford House, Mayfield Road, Summertown
Oxford OX2 7EL Oxford OX2 7EL
UK UK
Email: anthony@anthony.org Email: anthony@anthony.org
Paul Fremantle Paul Fremantle
University of Portsmouth University of Portsmouth
 End of changes. 136 change blocks. 
512 lines changed or deleted 600 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/