Skip to content

Commit 30a24c6

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #271854 from spelluru/egridmqtt0410
Reorganizing the MQTT client authentication content
2 parents 6c39850 + 808e8d3 commit 30a24c6

File tree

4 files changed

+126
-83
lines changed

4 files changed

+126
-83
lines changed

‎articles/event-grid/mqtt-client-authentication.md

Lines changed: 8 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -13,89 +13,18 @@ ms.subservice: mqtt
1313

1414
# Client authentication
1515

16-
We support authentication of clients using X.509 certificates. X.509 certificate provides the credentials to associate a particular client with the tenant. In this model, authentication generally happens once during session establishment. Then, all future operations using the same session are assumed to come from that identity.
16+
Azure Event Grid's MQTT broker supports the following authentication modes.
1717

18+
- Certificate-based authentication
19+
- Microsoft Entra ID authentication
1820

21+
## Certificate-based authentication
22+
You can use Certificate Authority (CA) signed certificates or self-signed certificates to authenticate clients. For more information, see [MQTT Client authentication using certificates](mqtt-client-certificate-authentication.md).
1923

20-
## Supported authentication modes
21-
22-
- Certificates issued by a Certificate Authority (CA)
23-
- Self-signed client certificate - thumbprint
24-
- Microsoft Entra ID token
25-
26-
### Certificate Authority (CA) signed certificates:
27-
28-
In this method, a root or intermediate X.509 certificate is registered with the service. Essentially, the root or intermediary certificate that is used to sign the client certificate, must be registered with the service first.
29-
30-
> [!IMPORTANT]
31-
> - Ensure to upload the root or intemediate certificate that is used to sign the client certificate. It is not needed to upload the entire certificate chain.
32-
> - For example, if you have a chain of root, intermediate, and leaf certificates, ensure to upload the intermediate certificate that signed the leaf/client certificates.
33-
34-
:::image type="content" source="./media/mqtt-client-authentication/mqtt-creating-certificate-chain.png" alt-text="Screenshot showing the CA certificates page with root and intermediate certificates used to sign the client certificates.":::
35-
36-
While registering clients, you need to identify the certificate field used to hold the client's authentication name. The service matches the authentication name from the certificate with the client's authentication name in the client metadata to validate the client. The service also validates the client certificate by verifying whether it is signed by the previously registered root or intermediary certificate.
37-
38-
:::image type="content" source="./media/mqtt-client-authentication/mqtt-client-certificate-chain-authentication-options.png" alt-text="Screenshot showing the client metadata with the five certificate chain based validation schemes.":::
39-
40-
### Self-signed client certificate - thumbprint
41-
42-
In this method of authentication, the client registry stores the exact thumbprint of the certificate that the client is going to use to authenticate. When client tries to connect to the service, service validates the client by comparing the thumbprint presented in the client certificate with the thumbprint stored in client metadata.
43-
44-
:::image type="content" source="./media/mqtt-client-authentication/mqtt-client-metadata-thumbprint.png" alt-text="Screenshot showing the client metadata with thumbprint authentication scheme.":::
45-
46-
> [!NOTE]
47-
> - We recommend that you include the client authentication name in the username field of the client's connect packet. Using this authentication name along with the client certificate, service will be able to authenticate the client.
48-
> - If you do not provide the authentication name in the username field, you need to configure the alternative source fields for the client authentication name at the namespace scope. Service looks for the client authentication name in corresponding field of the client certificate to authenticate the client connection.
49-
50-
In the configuration page at namespace scope, you can enable alternative client authentication name sources and then select the client certificate fields that have the client authentication name.
51-
52-
:::image type="content" source="./media/mqtt-client-authentication/mqtt-configuration-client-authentication.png" alt-text="Screenshot showing namespace configuration page with client authentication name alternate source settings.":::
53-
54-
The order of selection of the client certificate fields on the namespace configuration page is important. Service looks for the client authentication name in the client certificate fields in the same order.
55-
56-
For example, if you select the Certificate DNS option first and then the Subject Name option -
57-
while authenticating the client connection,
58-
- service checks the subject alternative name DNS field of the client certificate first for the client authentication name
59-
- if the DNS field is empty, then service checks the Subject Name field of the client certificate
60-
- if client authentication name isn't present in either of these two fields, client connection is denied
61-
62-
In both modes of client authentication, we expect the client authentication name to be provided either in the username field of the connect packet or in one of the client certificate fields.
63-
64-
**Supported client certificate fields for alternative source of client authentication name**
65-
66-
You can use one of the following fields to provide client authentication name in the client certificate.
67-
68-
| Authentication name source option | Certificate field | Description |
69-
| ------------ | ------------ | ------------ |
70-
| Certificate Subject Name | tls_client_auth_subject_dn | The subject distinguished name of the certificate. |
71-
| Certificate Dns | tls_client_auth_san_dns | The dNSName SAN entry in the certificate. |
72-
| Certificate Uri | tls_client_auth_san_uri | The uniformResourceIdentifier SAN entry in the certificate. |
73-
| Certificate Ip | tls_client_auth_san_ip | The IPv4 or IPv6 address present in the iPAddress SAN entry in the certificate. |
74-
| Certificate Email | tls_client_auth_san_email | The rfc822Name SAN entry in the certificate. |
75-
76-
77-
78-
### Microsoft Entra ID token
79-
80-
You can authenticate MQTT clients with Microsoft Entra JWT to connect to Event Grid namespace. You can use Azure role-based access control (Azure RBAC) to enable MQTT clients, with Microsoft Entra identity, to publish or subscribe access to specific topic spaces.
81-
82-
83-
## High level flow of how mutual transport layer security (mTLS) connection is established
84-
85-
To establish a secure connection with MQTT broker, you can use either MQTTS over port 8883 or MQTT over web sockets on port 443. It's important to note that only secure connections are supported. The following steps are to establish secure connection prior to the client authentication.
86-
87-
1. The client initiates the handshake with MQTT broker. It sends a hello packet with supported TLS version, cipher suites.
88-
2. Service presents its certificate to the client.
89-
- Service presents either a P-384 EC certificate or an RSA 2048 certificate depending on the ciphers in the client hello packet.
90-
- Service certificates are signed by a public certificate authority.
91-
3. Client validates that it's connected to the correct and trusted service.
92-
4. Then the client presents its own certificate to prove its authenticity.
93-
- Currently, we only support certificate-based authentication, so clients must send their certificate.
94-
5. Service completes TLS handshake successfully after validating the certificate.
95-
6. After completing the TLS handshake and mTLS connection is established, the client sends the MQTT CONNECT packet to the service.
96-
7. Service authenticates the client and allows the connection.
97-
- The same client certificate that was used to establish mTLS is used to authenticate the client connection to the service.
24+
## Microsoft Entra ID authentication
25+
You can authenticate MQTT clients with Microsoft Entra JWT to connect to Event Grid namespace. You can use Azure role-based access control (Azure RBAC) to enable MQTT clients, with Microsoft Entra identity, to publish or subscribe access to specific topic spaces. For more information, see [Microsoft Entra JWT authentication and Azure RBAC authorization to publish or subscribe MQTT messages](mqtt-client-microsoft-entra-token-and-rbac.md).
9826

9927
## Next steps
10028
- Learn how to [authenticate clients using certificate chain](mqtt-certificate-chain-client-authentication.md)
10129
- Learn how to [authenticate client using Microsoft Entra ID token](mqtt-client-azure-ad-token-and-rbac.md)
30+
- See [Transport layer security with MQTT broker](mqtt-transport-layer-security-flow.md)

‎articles/event-grid/mqtt-client-certificate-authentication.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: Azure Event Grid MQTT client certificate authentication
3+
description: This article describes how MQTT clients are authenticated using certificates - Certificate Authority (CA) signed certificates and self-signed certificates.
4+
ms.topic: conceptual
5+
ms.date: 11/15/2023
6+
author: george-guirguis
7+
ms.author: geguirgu
8+
ms.subservice: mqtt
9+
---
10+
11+
# MQTT client authentication using certificates
12+
13+
Azure Event Grid's MQTT broker supports authentication of clients using X.509 certificates. X.509 certificate provides the credentials to associate a particular client with the tenant. In this model, authentication generally happens once during session establishment. Then, all future operations using the same session are assumed to come from that identity.
14+
15+
Supported authentication modes are:
16+
17+
- Certificates issued by a Certificate Authority (CA)
18+
- Self-signed client certificate - thumbprint
19+
- Microsoft Entra ID token
20+
21+
This article focuses on certificates. To learn about authentication using Microsoft Entra ID tokens, see [authenticate client using Microsoft Entra ID token](mqtt-client-azure-ad-token-and-rbac.md).
22+
23+
## Certificate Authority (CA) signed certificates
24+
25+
In this method, a root or intermediate X.509 certificate is registered with the service. Essentially, the root or intermediary certificate that is used to sign the client certificate, must be registered with the service first.
26+
27+
> [!IMPORTANT]
28+
> - Ensure to upload the root or intermediate certificate that is used to sign the client certificate. It is not needed to upload the entire certificate chain.
29+
> - For example, if you have a chain of root, intermediate, and leaf certificates, ensure to upload the intermediate certificate that signed the leaf/client certificates.
30+
31+
:::image type="content" source="./media/mqtt-client-authentication/mqtt-creating-certificate-chain.png" alt-text="Screenshot showing the CA certificates page with root and intermediate certificates used to sign the client certificates.":::
32+
33+
While registering clients, you need to identify the certificate field used to hold the client's authentication name. The service matches the authentication name from the certificate with the client's authentication name in the client metadata to validate the client. The service also validates the client certificate by verifying whether it's signed by the previously registered root or intermediary certificate.
34+
35+
:::image type="content" source="./media/mqtt-client-authentication/mqtt-client-certificate-chain-authentication-options.png" alt-text="Screenshot showing the client metadata with the five certificate chain based validation schemes.":::
36+
37+
## Self-signed client certificate - thumbprint
38+
39+
In this method of authentication, the client registry stores the exact thumbprint of the certificate that the client is going to use to authenticate. When client tries to connect to the service, service validates the client by comparing the thumbprint presented in the client certificate with the thumbprint stored in client metadata.
40+
41+
:::image type="content" source="./media/mqtt-client-authentication/mqtt-client-metadata-thumbprint.png" alt-text="Screenshot showing the client metadata with thumbprint authentication scheme.":::
42+
43+
> [!NOTE]
44+
> - We recommend that you include the client authentication name in the username field of the client's connect packet. Using this authentication name along with the client certificate, service will be able to authenticate the client.
45+
> - If you do not provide the authentication name in the username field, you need to configure the alternative source fields for the client authentication name at the namespace scope. Service looks for the client authentication name in corresponding field of the client certificate to authenticate the client connection.
46+
47+
In the configuration page at namespace scope, you can enable alternative client authentication name sources and then select the client certificate fields that have the client authentication name.
48+
49+
:::image type="content" source="./media/mqtt-client-authentication/mqtt-configuration-client-authentication.png" alt-text="Screenshot showing namespace configuration page with client authentication name alternate source settings.":::
50+
51+
The order of selection of the client certificate fields on the namespace configuration page is important. Service looks for the client authentication name in the client certificate fields in the same order.
52+
53+
For example, if you select the Certificate DNS option first and then the Subject Name option -
54+
while authenticating the client connection,
55+
- service checks the subject alternative name DNS field of the client certificate first for the client authentication name
56+
- if the DNS field is empty, then service checks the Subject Name field of the client certificate
57+
- if client authentication name isn't present in either of these two fields, client connection is denied
58+
59+
In both modes of client authentication, we expect the client authentication name to be provided either in the username field of the connect packet or in one of the client certificate fields.
60+
61+
**Supported client certificate fields for alternative source of client authentication name**
62+
63+
You can use one of the following fields to provide client authentication name in the client certificate.
64+
65+
| Authentication name source option | Certificate field | Description |
66+
| ------------ | ------------ | ------------ |
67+
| Certificate Subject Name | tls_client_auth_subject_dn | The subject distinguished name of the certificate. |
68+
| Certificate Dns | tls_client_auth_san_dns | The `dNSName` SAN entry in the certificate. |
69+
| Certificate Uri | tls_client_auth_san_uri | The `uniformResourceIdentifier` SAN entry in the certificate. |
70+
| Certificate Ip | tls_client_auth_san_ip | The IPv4 or IPv6 address present in the iPAddress SAN entry in the certificate. |
71+
| Certificate Email | tls_client_auth_san_email | The `rfc822Name` SAN entry in the certificate. |
72+
73+
## Next steps
74+
- Learn how to [authenticate clients using certificate chain](mqtt-certificate-chain-client-authentication.md)
75+
- Learn how to [authenticate client using Microsoft Entra ID token](mqtt-client-azure-ad-token-and-rbac.md)

‎articles/event-grid/mqtt-transport-layer-security-flow.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: 'Azure Event Grid Transport Layer Security flow'
3+
description: 'Describes how mTLS connection is established when a client connects to Azure Event Grid’s Message Queueing Telemetry Transport (MQTT) broker feature.'
4+
ms.topic: conceptual
5+
ms.custom:
6+
- build-2023
7+
- ignite-2023
8+
ms.date: 11/15/2023
9+
author: george-guirguis
10+
ms.author: geguirgu
11+
ms.subservice: mqtt
12+
---
13+
14+
# Transport Layer Security (TLS) connection with MQTT broker
15+
To establish a secure connection with MQTT broker, you can use either MQTTS over port 8883 or MQTT over web sockets on port 443. It's important to note that only secure connections are supported. The following steps are to establish secure connection before the authentication of clients.
16+
17+
18+
## High level flow of how mutual transport layer security (mTLS) connection is established
19+
20+
1. The client initiates the handshake with MQTT broker. It sends a hello packet with supported TLS version, cipher suites.
21+
2. Service presents its certificate to the client.
22+
- Service presents either a P-384 EC certificate or an RSA 2048 certificate depending on the ciphers in the client hello packet.
23+
- Service certificates signed by a public certificate authority.
24+
3. Client validates that it connected to the correct and trusted service.
25+
4. Then the client presents its own certificate to prove its authenticity.
26+
- Currently, we only support certificate-based authentication, so clients must send their certificate.
27+
5. Service completes TLS handshake successfully after validating the certificate.
28+
6. After completing the TLS handshake and mTLS connection is established, the client sends the MQTT CONNECT packet to the service.
29+
7. Service authenticates the client and allows the connection.
30+
- The same client certificate that was used to establish mTLS is used to authenticate the client connection to the service.
31+
32+
## Next steps
33+
- Learn how to [authenticate clients using certificate chain](mqtt-certificate-chain-client-authentication.md)
34+
- Learn how to [authenticate client using Microsoft Entra ID token](mqtt-client-azure-ad-token-and-rbac.md)

‎articles/event-grid/toc.yml

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,6 @@ items:
4343
items:
4444
- name: Terminology
4545
href: mqtt-event-grid-namespace-terminology.md
46-
- name: MQTT client authentication
47-
href: mqtt-client-authentication.md
4846
- name: Access control for MQTT clients
4947
href: mqtt-access-control.md
5048
- name: MQTT clients
@@ -66,8 +64,15 @@ items:
6664
href: mqtt-support.md
6765
- name: MQTT clients life cycle events
6866
href: mqtt-client-life-cycle-events.md
69-
- name: JWT authentication and RBAC authorization for clients with Microsoft Entra identity
70-
href: mqtt-client-microsoft-entra-token-and-rbac.md
67+
- name: MQTT client authentication
68+
href: mqtt-client-authentication.md
69+
items:
70+
- name: MQTT client authentication using certificates
71+
href: mqtt-client-certificate-authentication.md
72+
- name: JWT authentication and RBAC authorization for clients with Microsoft Entra identity
73+
href: mqtt-client-microsoft-entra-token-and-rbac.md
74+
- name: Transport Layer Security connection with MQTT broker
75+
href: mqtt-transport-layer-security-flow.md
7176
- name: High availability and disaster recovery
7277
href: high-availability-disaster-recovery.md
7378
- name: Security

0 commit comments

Comments
 (0)