Zuweisen von benutzerdefinierten Domänennamen an den MQTT- und HTTP-Hostnamen des Event Grid-Namespace

Artikel
05/21/2024

Der Event Grid-Namespace wird zum Zeitpunkt der Erstellung automatisch einem HTTP-Hostnamen zugewiesen. Wenn MQTT für den Namespace aktiviert ist, wird der MQTT-Hostname auch dem Namespace zugewiesen. Ihre Clients verwenden diese Hostnamen, um mit dem Event Grid-Namespace zu kommunizieren.

Sie können Ihre benutzerdefinierten Domänennamen zusammen mit den Standardhostnamen des MQTT- und HTTP-Hostnamens Ihres Event Grid-Namespace zuweisen. Benutzerdefinierte Domänenkonfigurationen helfen Ihnen nicht nur bei der Erfüllung Ihrer Sicherheits- und Complianceanforderungen, sondern beseitigt auch die Notwendigkeit, Ihre Clients zu ändern, die bereits mit Ihrer Domäne verknüpft sind.

Voraussetzungen

Um benutzerdefinierte Domänen für Namespaces zu verwenden, müssen Sie über die folgenden Voraussetzungen verfügen:

Benutzerdefinierte Domäne, die Sie besitzen und ihre DNS-Einträge (Domain Name System) ändern können. Zum Ändern von DNS-Einträgen benötigen Sie Zugriff auf die DNS-Registrierung für Ihren Domänenanbieter, wie etwa GoDaddy.
SSL-Zertifikat (Secure Sockets Layer) für Ihre benutzerdefinierte Domäne von einer öffentlichen oder privaten Zertifizierungsstelle.
Azure Key Vault-Konto zum Hosten des SSL-Zertifikats für Ihre benutzerdefinierte Domäne.

Wesentliche Schritte

Führen Sie die folgenden Schritte aus, um benutzerdefinierte Domänen für Namespaces zu verwenden:

Fügen Sie DNS-Einträge hinzu, um Ihre benutzerdefinierte Domäne auf den Event Grid-Namespace-Endpunkt zu verweisen.
Aktivieren Sie die verwaltete Identität für Event Grid-Namespace.
Erstellen Sie ein Azure Key Vault-Konto, das das Serverzertifikat für Ihre benutzerdefinierte Domäne hosten soll.
Fügen Sie Rollenzuweisungen in Azure Key Vault für die verwaltete Identität des Namespaces hinzu.
Ordnen Sie den Event Grid-Namespace der benutzerdefinierten Domäne zu, und geben Sie den benutzerdefinierten Domänennamen, den Zertifikatnamen und den Verweis zum Key Vault an.
Der Event Grid-Namespace generiert einen TXT-Eintrag, den Sie zum Nachweis des Besitzes der benutzerdefinierten Domäne verwenden.
Beweisen Sie Ihren Domänenbesitz, indem Sie einen TXT-Eintrag basierend auf dem Wert erstellen, den Event Grid im vorherigen Schritt generiert hat.
Das Ereignisraster überprüft die TXT-Einträge der benutzerdefinierten Domäne, bevor die benutzerdefinierte Domäne für die Verwendung Ihrer Clients aktiviert wird.
Ihre Clients können über die benutzerdefinierte Domäne eine Verbindung mit dem Event Grid-Namespace herstellen.

Begrenzungen

Die Konfiguration benutzerdefinierter Domänen ist pro Region über MQTT- und HTTP-Hostnamen hinweg eindeutig.
Die Konfiguration benutzerdefinierter Domänen kann für die MQTT- und HTTP-Hostnamen unter demselben Namespace nicht identisch sein.
Die Konfiguration benutzerdefinierter Domänen kann nicht mit einem MQTT- oder HTTP-Hostnamen für einen Namespace in derselben Region zusammentreffen.

Hinzufügen von DNS-Einträgen

Erstellen Sie DNS-Einträge in Ihrer Domäne, um auf den Hostnamen Ihres Event Grid-Namespace zu verweisen, dem Sie Ihre Domäne zuordnen möchten. Weitere Informationen finden Sie unter Konfigurieren eines benutzerdefinierten Domänennamens für einen Azure-Clouddienst.

Ihr HTTP-Hostname für Ihren Namespace weist das folgende Format auf: <namespace name>.centraluseuap-1.eventgrid.azure.net

Ihr MQTT-Hostname für Ihren Namespace weist das folgende Format auf: <namespace name>.centraluseuap-1.ts.eventgrid.azure.net

Aktivieren der verwalteten Identität für Ihren Event Grid-Namespace

Der Namespace verwendet die verwaltete Identität, um auf Ihre Azure Key Vault-Instanz zuzugreifen, um das Serverzertifikat für Ihre benutzerdefinierte Domäne abzurufen. Verwenden Sie den folgenden Befehl, um die vom System zugewiesene verwaltete Identität im Event Grid-Namespace zu aktivieren:

az eventgrid namespace update --resource-group <resource group name> --name <namespace name> --identity "{type:systemassigned}"

Informationen zum Konfigurieren von System- und vom Benutzer zugewiesenen Identitäten mithilfe des Azure-Portals finden Sie unter Aktivieren der verwalteten Identität für einen Event Grid-Namespace.

Erstellen eines Azure Key Vault-Kontos und Hochladen Ihres Serverzertifikats

Führen Sie den folgenden Befehl aus, um ein Azure Key Vault-Konto zu erstellen:

az keyvault create --name "<your-unique-keyvault-name>" --resource-group "<resource group name>" --location "centraluseaup"

Verwenden Sie den folgenden Befehl, um ein Zertifikat in Azure Key Vault zu importieren.
```
az keyvault certificate import --vault-name "<your-key-vault-name>" -n "<cert name>" -f "<path to your certificate pem file> " 
```
Hinweis

Ihr Zertifikat muss den Domänennamen im alternativen Antragstellernamen für DNS enthalten. Weitere Informationen finden Sie unter Tutorial: Importieren eines Zertifikats in Azure Key Vault.

Hinzufügen von Rollenzuweisungen in Azure Key Vault für die verwaltete Identität des Namespace

Sie müssen mit den folgenden Schritten Zugriff auf den Namespace gewähren, um auf Ihr Azure Key Vault-Konto zuzugreifen:

Rufen Sie die Prinzipal-ID der systemseitig verwalteten Identität des Event Grid-Namespace mithilfe des folgenden Befehls ab:

$principalId=(az eventgrid namespace show --resource-group <resource group name> --name <namespace name> --query identity.principalId -o tsv)

Rufen Sie Ihre Azure Key Vault-Ressourcen-ID ab.

$keyVaultResourceId=(az keyvault show --resource-group <resource group name> --name <your key vault name> --query id -o tsv)

Fügen Sie eine Rollenzuweisung in Key Vault für die verwaltete Identität des Namespace hinzu.
```
az role assignment create --role "Key Vault Certificate User" --assignee $principalId --scope $keyVaultResourceId 
```
Weitere Informationen zum Key Vault-Zugriff und zur Portalerfahrung finden Sie unter Bereitstellen des Zugriffs auf Key Vault-Schlüssel, Zertifikate und Geheimnisse mit einer rollenbasierten Azure-Zugriffssteuerung.

Zuordnen des Event Grid-Namespace zur benutzerdefinierten Domäne

In diesem Schritt ordnen Sie Ihre nicht überprüfte benutzerdefinierte Domäne dem Namespace zu, können sie jedoch erst verwenden, wenn Sie den Besitz der benutzerdefinierten Domäne im nächsten Schritt nachweisen.

Verwenden des Azure-Portals

Führen Sie die folgenden Schritte aus, um Ihre benutzerdefinierten Domänen hinzuzufügen:

Navigieren Sie im Azure-Portal zu Ihrem Event Grid-Namespace
Wählen Sie auf der Seite Event Grid Namespace die Option Benutzerdefinierte Domänen im linken Navigationsmenü aus.
Wählen Sie auf der Seite Benutzerdefinierte Domänen die Option + Benutzerdefinierte Domäne aus.
Geben Sie auf der Seite Benutzerdefinierte Domäne hinzufügen Werte für die folgenden Eigenschaften an:
1. Domänenname: Der vollqualifizierte Domänenname, der einem Ihrer Event Grid Namespace-Hostnamen zugewiesen werden soll.
2. Zugeordneter Hostnamentyp: Der Standardmäßige Hostnamentyp, der Ihrem benutzerdefinierten Domänennamen zugeordnet werden soll.
3. Zertifikat-URL: Der Zertifikatbezeichner des Serverzertifikats in Ihrem Azure Key Vault. Schließen Sie nur den Basisbezeichner des Zertifikats ein, indem Sie den letzten Abschnitt des Zertifikatbezeichners ausschließen. Sie können stattdessen ein Zertifikat mit einem Key Vault auswählen, um das Zertifikat und den Key Vault aus Ihren Abonnements auszuwählen.
4. Verwaltete Identität: Die verwaltete Identität, die für die Authentifizierung mit dem Key Vault verwendet wird, um auf das erstellte Serverzertifikat zuzugreifen.
5. Wählen Sie Hinzufügen aus.
Speichern Sie die TXT-Einträge, da Sie diese Werte verwenden müssen, um ihren benutzerdefinierten Domänenbesitz zu beweisen.

Azure CLI-Beispiel

Verwenden Sie den folgenden Befehl, um Ihren Namespace mit der benutzerdefinierten Domänenkonfiguration zu aktualisieren. Das folgende Objekt enthält zwei verschiedene customDomains Konfigurationen: die Konfiguration unter topicSpacesConfiguration wird Ihrem MQTT-Endpunkt zugewiesen, und die Konfiguration unter topicsConfiguration wird Ihrem HTTP-Endpunkt zugewiesen.

Hinweis

Jede benutzerdefinierte Domänenkonfiguration muss innerhalb derselben Region eindeutig sein.

az resource create --resource-type Microsoft.EventGrid/namespaces --id /subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/namespaces/<Namespace Name> --is-full-object --properties @./resources/NS.json

NS.json

{
    "properties": {
        "topicsConfiguration": {
            "hostname": "HOSTNAME",
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.HTTPDOMAINNAME.com",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        },
        "topicSpacesConfiguration": {
            "state": " Enabled",
            "routeTopicResourceId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.EventGrid/namespaces/NAMESPACENAME/topics/TOPICNAME",
            "hostname": "NAMESPACENAME.westus2-1.ts.eventgrid.azure.net",
            "routingIdentityInfo": {
                "type": "None"
            },
            "customDomains": [
                {
                    "fullyQualifiedDomainName": " www.MQTTDOMAINNAME.com ",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": "/subscriptions/SUBSCRIPTIONNAME/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        }
    }
}

Ersetzen Sie die folgenden Platzhalter durch entsprechende Werte, speichern Sie sie in einer Datei mit dem Namen NS.json, und führen Sie den CLI-Befehl aus.

Platzhalter	Beschreibung
`HOSTNAME`	Sie können den Hostnamen über die Seite Übersicht Ihres Event Grid-Namespace im Azure-Portal abrufen.
`NAMESPACENAME`	Name des Event Grid-Namespace.
`TOPICNAME`	Name des Themas im Namespace.
`HTTPDOMAINNAME`	Name der HTTP-Domäne.
`MQTTDOMAINNAME`	Name der MQTT-Domäne.
`SUBSCRIPTIONID`	Die Azure-Abonnement-ID.
`RESOURCEGROUPNAME`	Der Name der Azure-Ressourcengruppe.
`KEYVAULTNAME`	Der Name des Schlüsseltresors.
`CERTIFICATENAME`	Name des Zertifikats.

Der Identitätstyp (type) kann entweder SystemAssigned oder UserAssigned sein. Wenn UserAssigned ausgewählt ist, geben Sie die vom Benutzer zugewiesene Identität mithilfe der userAssignedIdentity Eigenschaft an.

Die Antwort auf diesen Vorgang enthält die DNS-Informationen in Form der folgenden Eigenschaften: expectedTxtRecordName und expectedTxtRecordValue. Speichern Sie diese Informationen, da Sie diese Werte verwenden müssen, um ihren benutzerdefinierten Domänenbesitz zu beweisen. Hier sehen Sie eine Beispielantwort:

{
    "properties": {
        "topicsConfiguration": {
            "hostname": "HOSTNAME",
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.HTTPDOMAINNAME.com",
                    "validationState": "Pending",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    },
                    "expectedTxtRecordName": "_eg. www.contoso-http.com",
                    "expectedTxtRecordValue": "<random string>"
                }
            ]
        },
        "topicSpacesConfiguration": {
            "state": " Enabled",
            "routeTopicResourceId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.EventGrid/namespaces/MSNS/topics/TOPICNAME",
            "hostname": "HOSTNAME",
            "routingIdentityInfo": {
                "type": "None"
            },
            "customDomains": [
                {
                    "fullyQualifiedDomainName": " www.MQTTDOMAINNAME.com ",
                    "validationState": "Pending",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": "/subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    },
                    "expectedTxtRecordName": "_eg. www.contoso-mqtt.com",
                    "expectedTxtRecordValue": "<random string>"
                }
            ]
        }
    }
}

Nachweisen ihres benutzerdefinierten Domänenbesitzes

Führen Sie die folgenden Schritte aus, um den Besitz Ihrer Domäne zu beweisen:

Fügen Sie die DNS-Informationen hinzu.

Navigieren Sie zurück zu Ihrer Domänenregistrierungsstelle, und erstellen Sie basierend auf den kopierten DNS-Informationen aus dem vorherigen Schritt einen neuen TXT-Eintrag für Ihre Domäne. Durch die Erstellung dieses TXT-Eintrags wird der Besitz des Domänennamens überprüft. Legen Sie die Gültigkeitsdauer (Time to Live, TTL) auf 3,600 Sekunden (60 Minuten) fest, und speichern Sie den Datensatz.

Überprüfen des benutzerdefinierten Domänennamens.

Führen Sie zum Verwenden des Azure-Portals die folgenden Schritte aus, um Ihre benutzerdefinierten Domänen zu überprüfen:
1. Wählen Sie auf der Seite Benutzerdefinierte Domänen die Option Domänen überprüfen aus.
2. Wählen Sie auf der Seite Domänen überprüfen die Option Überprüfen aus.

Verwenden Sie den folgenden Befehl, um Ihren Namespace mit einer identischen benutzerdefinierten Domänenkonfiguration zu aktualisieren. Dieser Befehl löst die Überprüfung des benutzerdefinierten Domänenbesitzes aus. Die DNS-Einträge müssen weitergegeben werden, bevor Sie die Domäne überprüfen können, und die Verteilungszeit Ihrer DNS-Einstellungen hängt von Ihrer Domänenregistrierungsstelle ab.

Vergewissern Sie sich in der Antwort auf Ihren Befehl, dass validationState Approved ist.

az resource create --resource-type Microsoft.EventGrid/namespaces --id /subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/namespaces/<Namespace Name> --is-full-object --properties @./resources/NS.json

NS.json:

{
    "properties": {
        "topicsConfiguration": {
            "hostname": "HOSTNAME",
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.HTTPDOMAINNAME.com",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": " /subscriptions/AZURESUBCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        },
        "topicSpacesConfiguration": {
            "state": " Enabled",
            "routeTopicResourceId": " /subscriptions/AZURESUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.EventGrid/namespaces/NAMESPACENAME/topics/TOPICNAME",
            "hostname": "HOSTNAME",
            "routingIdentityInfo": {
                "type": "None"
            },
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.MQTTDOMAINNAME.com ",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": "/subscriptions/AZURESUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        }
    }
}

Freigeben über