Skip to content

Commit 9ef21bb

Browse files
huypubhuypub
authored
Merge pull request #196072 from MicrosoftDocs/release-service-bus-tls
Release documentation for minimum TLS feature for Service Bus and Event Hubs
2 parents 854fe57 + 2ec9766 commit 9ef21bb

13 files changed

+696
-2
lines changed

‎articles/event-hubs/TOC.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,8 @@
145145
href: ./security-controls-policy.md
146146
- name: Security baseline
147147
href: /security/benchmark/azure/baselines/event-hubs-security-baseline?toc=/azure/event-hubs/TOC.json
148+
- name: Enforce minimum required TLS version
149+
href: transport-layer-security-enforce-minimum-version.md
148150
- name: Availability and consistency
149151
href: event-hubs-availability-and-consistency.md
150152
- name: Scalability
@@ -240,6 +242,12 @@
240242
href: private-link-service.md
241243
- name: Encrypt data using customer-managed keys
242244
href: configure-customer-managed-key.md
245+
- name: Configure minimum required TLS version
246+
href: transport-layer-security-configure-minimum-version.md
247+
- name: Audit minimum required TLS version
248+
href: transport-layer-security-audit-minimum-version.md
249+
- name: Configure TLS version for client
250+
href: transport-layer-security-configure-client-version.md
243251
- name: Troubleshoot
244252
items:
245253
- name: Troubleshoot connectivity issues

‎articles/event-hubs/index.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,4 +199,6 @@ landingContent:
199199
- text: Use private endpoints
200200
url: private-link-service.md
201201
- text: Configure customer-managed keys for encrypting data at rest
202-
url: configure-customer-managed-key.md
202+
url: configure-customer-managed-key.md
203+
- text: Enforce minimum required TLS version
204+
url: transport-layer-security-enforce-minimum-version.md

‎articles/event-hubs/transport-layer-security-audit-minimum-version.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: Use Azure Policy to audit for compliance of minimum TLS version for an Azure Event Hubs namespace
3+
titleSuffix: Event Hubs
4+
description: Configure Azure Policy to audit compliance of Azure Event Hubs for using a minimum version of Transport Layer Security (TLS).
5+
services: event-hubs
6+
author: EldertGrootenboer
7+
8+
ms.service: event-hubs
9+
ms.topic: article
10+
ms.date: 04/25/2022
11+
ms.author: egrootenboer
12+
---
13+
14+
# Use Azure Policy to audit for compliance of minimum TLS version for an Azure Event Hubs namespace (Preview)
15+
16+
If you have a large number of Microsoft Azure Event Hubs namespaces, you may want to perform an audit to make sure that all namespaces are configured for the minimum version of TLS that your organization requires. To audit a set of Event Hubs namespaces for their compliance, use Azure Policy. Azure Policy is a service that you can use to create, assign, and manage policies that apply rules to Azure resources. Azure Policy helps you to keep those resources compliant with your corporate standards and service level agreements. For more information, see [Overview of Azure Policy](../governance/policy/overview.md).
17+
18+
## Create a policy with an audit effect
19+
20+
Azure Policy supports effects that determine what happens when a policy rule is evaluated against a resource. The audit effect creates a warning when a resource is not in compliance, but does not stop the request. For more information about effects, see [Understand Azure Policy effects](../governance/policy/concepts/effects.md).
21+
22+
To create a policy with an audit effect for the minimum TLS version with the Azure portal, follow these steps:
23+
24+
1. In the Azure portal, navigate to the Azure Policy service.
25+
2. Under the **Authoring** section, select **Definitions**.
26+
3. Select **Add policy definition** to create a new policy definition.
27+
4. For the **Definition location** field, select the **More** button to specify where the audit policy resource is located.
28+
5. Specify a name for the policy. You can optionally specify a description and category.
29+
6. Under **Policy rule** , add the following policy definition to the **policyRule** section.
30+
31+
```json
32+
{
33+
"policyRule": {
34+
"if": {
35+
"allOf": [
36+
{
37+
"field": "type",
38+
"equals": "Microsoft.EventHub/namespaces"
39+
},
40+
{
41+
"not": {
42+
"field": " Microsoft.EventHub/namespaces/minimumTlsVersion",
43+
"equals": "1.2"
44+
}
45+
}
46+
]
47+
},
48+
"then": {
49+
"effect": "audit"
50+
}
51+
}
52+
}
53+
```
54+
55+
7. Save the policy.
56+
57+
### Assign the policy
58+
59+
Next, assign the policy to a resource. The scope of the policy corresponds to that resource and any resources beneath it. For more information on policy assignment, see [Azure Policy assignment structure](../governance/policy/concepts/assignment-structure.md).
60+
61+
To assign the policy with the Azure portal, follow these steps:
62+
63+
1. In the Azure portal, navigate to the Azure Policy service.
64+
2. Under the **Authoring** section, select **Assignments**.
65+
3. Select **Assign policy** to create a new policy assignment.
66+
4. For the **Scope** field, select the scope of the policy assignment.
67+
5. For the **Policy definition** field, select the **More** button, then select the policy you defined in the previous section from the list.
68+
6. Provide a name for the policy assignment. The description is optional.
69+
7. Leave **Policy enforcement** set to _Enabled_. This setting has no effect on the audit policy.
70+
8. Select **Review + create** to create the assignment.
71+
72+
### View compliance report
73+
74+
After you have assigned the policy, you can view the compliance report. The compliance report for an audit policy provides information on which Event Hubs namespaces are not in compliance with the policy. For more information, see [Get policy compliance data](../governance/policy/how-to/get-compliance-data.md).
75+
76+
It may take several minutes for the compliance report to become available after the policy assignment is created.
77+
78+
To view the compliance report in the Azure portal, follow these steps:
79+
80+
1. In the Azure portal, navigate to the Azure Policy service.
81+
2. Select **Compliance**.
82+
3. Filter the results for the name of the policy assignment that you created in the previous step. The report shows how many resources are not in compliance with the policy.
83+
4. You can drill down into the report for additional details, including a list of Event Hubs namespaces that are not in compliance.
84+
85+
## Use Azure Policy to enforce the minimum TLS version
86+
87+
Azure Policy supports cloud governance by ensuring that Azure resources adhere to requirements and standards. To enforce a minimum TLS version requirement for the Event Hubs namespaces in your organization, you can create a policy that prevents the creation of a new Event Hubs namespace that sets the minimum TLS requirement to an older version of TLS than that which is dictated by the policy. This policy will also prevent all configuration changes to an existing namespace if the minimum TLS version setting for that namespace is not compliant with the policy.
88+
89+
The enforcement policy uses the deny effect to prevent a request that would create or modify an Event Hubs namespace so that the minimum TLS version no longer adheres to your organization's standards. For more information about effects, see [Understand Azure Policy effects](../governance/policy/concepts/effects.md).
90+
91+
To create a policy with a deny effect for a minimum TLS version that is less than TLS 1.2, provide the following JSON in the **policyRule** section of the policy definition:
92+
93+
```json
94+
{
95+
"policyRule": {
96+
"if": {
97+
"allOf": [
98+
{
99+
"field": "type",
100+
"equals": " Microsoft.EventHub/namespaces"
101+
},
102+
{
103+
"not": {
104+
"field": " Microsoft.EventHub/namespaces/minimumTlsVersion",
105+
"equals": "1.2"
106+
}
107+
}
108+
]
109+
},
110+
"then": {
111+
"effect": "deny"
112+
}
113+
}
114+
}
115+
```
116+
117+
After you create the policy with the deny effect and assign it to a scope, a user cannot create an Event Hubs namespace with a minimum TLS version that is older than 1.2. Nor can a user make any configuration changes to an existing Event Hubs namespace that currently requires a minimum TLS version that is older than 1.2. Attempting to do so results in an error. The required minimum TLS version for the Event Hubs namespace must be set to 1.2 to proceed with namespace creation or configuration.
118+
119+
An error will be shown if you try to create an Event Hubs namespace with the minimum TLS version set to TLS 1.0 when a policy with a deny effect requires that the minimum TLS version be set to TLS 1.2.
120+
121+
## Next steps
122+
123+
See the following documentation for more information.
124+
125+
- [Enforce a minimum required version of Transport Layer Security (TLS) for requests to an Event Hubs namespace](transport-layer-security-enforce-minimum-version.md)
126+
- [Configure the minimum TLS version for an Event Hubs namespace](transport-layer-security-configure-minimum-version.md)
127+
- [Configure Transport Layer Security (TLS) for an Event Hubs client application](transport-layer-security-configure-client-version.md)

‎articles/event-hubs/transport-layer-security-configure-client-version.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Configure Transport Layer Security (TLS) for an Event Hubs client application
3+
titleSuffix: Event Hubs
4+
description: Configure a client application to communicate with Azure Event Hubs using a minimum version of Transport Layer Security (TLS).
5+
services: event-hubs
6+
author: EldertGrootenboer
7+
8+
ms.service: event-hubs
9+
ms.topic: article
10+
ms.date: 04/25/2022
11+
ms.author: egrootenboer
12+
---
13+
14+
# Configure Transport Layer Security (TLS) for an Event Hubs client application (Preview)
15+
16+
For security purposes, an Azure Event Hubs namespace may require that clients use a minimum version of Transport Layer Security (TLS) to send requests. Calls to Azure Event Hubs will fail if the client is using a version of TLS that is lower than the minimum required version. For example, if a namespace requires TLS 1.2, then a request sent by a client who is using TLS 1.1 will fail.
17+
18+
This article describes how to configure a client application to use a particular version of TLS. For information about how to configure a minimum required version of TLS for an Azure Event Hubs namespace, see [Enforce a minimum required version of Transport Layer Security (TLS) for requests to an Event Hubs namespace](transport-layer-security-configure-minimum-version.md).
19+
20+
## Configure the client TLS version
21+
22+
In order for a client to send a request with a particular version of TLS, the operating system must support that version.
23+
24+
The following example shows how to set the client's TLS version to 1.2 from .NET. The .NET Framework used by the client must support TLS 1.2. For more information, see [Support for TLS 1.2](/dotnet/framework/network-programming/tls#support-for-tls-12).
25+
26+
# [.NET](#tab/dotnet)
27+
28+
The following sample shows how to enable TLS 1.2 in a .NET client using the Azure.Messaging.ServiceBus client library of Event Hubs:
29+
30+
```csharp
31+
{
32+
// Enable TLS 1.2 before connecting to Event Hubs
33+
System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12;
34+
35+
// Connection string to your Event Hubs namespace
36+
string connectionString = "<NAMESPACE CONNECTION STRING>";
37+
38+
// Name of your Event Hub
39+
string eventHubName = "<EVENT HUB NAME>";
40+
41+
// The sender used to publish messages to the queue
42+
var producer = new EventHubProducerClient(connectionString, eventHubName);
43+
44+
// Use the producer client to send a message to the Event Hubs queue
45+
using EventDataBatch eventBatch = await producer.CreateBatchAsync();
46+
var eventData = new EventData("This is an event body");
47+
48+
if (!eventBatch.TryAdd(eventData))
49+
{
50+
throw new Exception($"The event could not be added.");
51+
}
52+
}
53+
```
54+
55+
---
56+
57+
## Verify the TLS version used by a client
58+
59+
To verify that the specified version of TLS was used by the client to send a request, you can use [Fiddler](https://www.telerik.com/fiddler) or a similar tool. Open Fiddler to start capturing client network traffic, then execute one of the examples in the previous section. Look at the Fiddler trace to confirm that the correct version of TLS was used to send the request.
60+
61+
## Next steps
62+
63+
See the following documentation for more information.
64+
65+
- [Enforce a minimum required version of Transport Layer Security (TLS) for requests to an Event Hubs namespace](transport-layer-security-enforce-minimum-version.md)
66+
- [Configure the minimum TLS version for an Event Hubs namespace](transport-layer-security-configure-minimum-version.md)
67+
- [Use Azure Policy to audit for compliance of minimum TLS version for an Event Hubs namespace](transport-layer-security-audit-minimum-version.md)

‎articles/event-hubs/transport-layer-security-configure-minimum-version.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Configure the minimum TLS version for an Event Hubs namespace using ARM
3+
titleSuffix: Event Hubs
4+
description: Configure an Azure Event Hubs namespace to use a minimum version of Transport Layer Security (TLS).
5+
services: event-hubs
6+
author: EldertGrootenboer
7+
8+
ms.service: event-hubs
9+
ms.topic: article
10+
ms.date: 04/25/2022
11+
ms.author: egrootenboer
12+
---
13+
14+
# Configure the minimum TLS version for an Event Hubs namespace using ARM (Preview)
15+
16+
To configure the minimum TLS version for an Event Hubs namespace, set the `MinimumTlsVersion` version property. When you create an Event Hubs namespace with an Azure Resource Manager template, the `MinimumTlsVersion` property is set to 1.2 by default, unless explicitly set to another version.
17+
18+
> [!NOTE]
19+
> Namespaces created using an api-version prior to 2022-01-01-preview will have 1.0 as the value for `MinimumTlsVersion`. This behavior was the prior default, and is still there for backwards compatibility.
20+
21+
## Create a template to configure the minimum TLS version
22+
23+
To configure the minimum TLS version for an Event Hubs namespace with a template, create a template with the `MinimumTlsVersion` property set to 1.0, 1.1, or 1.2. The following steps describe how to create a template in the Azure portal.
24+
25+
1. In the Azure portal, choose **Create a resource**.
26+
2. In **Search the Marketplace** , type **custom deployment** , and then press **ENTER**.
27+
3. Choose **Custom deployment (deploy using custom templates) (preview)**, choose **Create** , and then choose **Build your own template in the editor**.
28+
4. In the template editor, paste in the following JSON to create a new namespace and set the minimum TLS version to TLS 1.2. Remember to replace the placeholders in angle brackets with your own values.
29+
30+
```json
31+
{
32+
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
33+
"contentVersion": "1.0.0.0",
34+
"parameters": {},
35+
"variables": {
36+
"serviceBusNamespaceName": "[concat(uniqueString(subscription().subscriptionId), 'tls')]"
37+
},
38+
"resources": [
39+
{
40+
"name": "[variables('serviceBusNamespaceName')]",
41+
"type": "Microsoft.EventHub/namespaces",
42+
"apiVersion": "2022-01-01-preview",
43+
"location": "westeurope",
44+
"properties": {
45+
"minimumTlsVersion": "1.2"
46+
},
47+
"dependsOn": [],
48+
"tags": {}
49+
}
50+
]
51+
}
52+
```
53+
54+
5. Save the template.
55+
6. Specify resource group parameter, then choose the **Review + create** button to deploy the template and create a namespace with the `MinimumTlsVersion` property configured.
56+
57+
> [!NOTE]
58+
> After you update the minimum TLS version for the Event Hubs namespace, it may take up to 30 seconds before the change is fully propagated.
59+
60+
Configuring the minimum TLS version requires api-version 2022-01-01-preview or later of the Azure Event Hubs resource provider.
61+
62+
## Check the minimum required TLS version for multiple namespaces
63+
64+
To check the minimum required TLS version across a set of Event Hubs namespaces with optimal performance, you can use the Azure Resource Graph Explorer in the Azure portal. To learn more about using the Resource Graph Explorer, see [Quickstart: Run your first Resource Graph query using Azure Resource Graph Explorer](../governance/resource-graph/first-query-portal.md).
65+
66+
Running the following query in the Resource Graph Explorer returns a list of Event Hubs namespaces and displays the minimum TLS version for each namespace:
67+
68+
```kusto
69+
resources
70+
| where type =~ 'Microsoft.EventHub/namespaces'
71+
| extend minimumTlsVersion = parse\_json(properties).minimumTlsVersion
72+
| project subscriptionId, resourceGroup, name, minimumTlsVersion
73+
```
74+
75+
## Test the minimum TLS version from a client
76+
77+
To test that the minimum required TLS version for an Event Hubs namespace forbids calls made with an older version, you can configure a client to use an older version of TLS. For more information about configuring a client to use a specific version of TLS, see [Configure Transport Layer Security (TLS) for a client application](transport-layer-security-configure-client-version.md).
78+
79+
When a client accesses an Event Hubs namespace using a TLS version that does not meet the minimum TLS version configured for the namespace, Azure Event Hubs returns error code 400 error (Bad Request) and a message indicating that the TLS version that was used is not permitted for making requests against this Event Hubs namespace.
80+
81+
> [!NOTE]
82+
> Due to limitations in the confluent library, errors coming from an invalid TLS version will not surface when connecting through the Kafka protocol. Instead a general exception will be shown.
83+
84+
> [!NOTE]
85+
> When you configure a minimum TLS version for an Event Hubs namespace, that minimum version is enforced at the application layer. Tools that attempt to determine TLS support at the protocol layer may return TLS versions in addition to the minimum required version when run directly against the Event Hubs namespace endpoint.
86+
87+
## Next steps
88+
89+
See the following documentation for more information.
90+
91+
- [Enforce a minimum required version of Transport Layer Security (TLS) for requests to an Event Hubs namespace](transport-layer-security-enforce-minimum-version.md)
92+
- [Configure Transport Layer Security (TLS) for an Event Hubs client application](transport-layer-security-configure-client-version.md)
93+
- [Use Azure Policy to audit for compliance of minimum TLS version for an Event Hubs namespace](transport-layer-security-audit-minimum-version.md)

0 commit comments

Comments
 (0)