Authentifizieren mit Namespaces mithilfe von JSON-Webtoken

  • Artikel

In diesem Artikel wird gezeigt, wie Sie sich mit dem Azure Event Grid-Namespace mithilfe von JSON-Webtoken authentifizieren.

MQTT Vermittler von Azure Event Grid unterstützt die benutzerdefinierte JWT-Authentifizierung, mit der Clients eine Verbindung mit einem Event Grid-Namespace herstellen und sich mithilfe von JSON-Webtoken authentifizieren können, die neben Microsoft Entra ID von einem beliebigen Identitätsanbieter ausgestellt werden.

Voraussetzungen

Um benutzerdefinierte JWT-Authentifizierung für Namespaces zu verwenden, müssen die folgenden Voraussetzungen erfüllt sein:

  • Identitätsanbieter, der JSON-Webtoken ausstellen kann.
  • Zertifizierungsstellenzertifikat, das Ihre öffentlichen Schlüssel enthält, die zum Überprüfen der Clienttoken verwendet werden.
  • Azure Key Vault-Konto zum Hosten des Zertifizierungsstellenzertifikats, das Ihre öffentlichen Schlüssel enthält.

Wesentliche Schritte

Führen Sie die folgenden Schritte aus, um die benutzerdefinierte JWT-Authentifizierung für Namespaces zu verwenden:

  1. Erstellen Sie einen Namespace, und konfigurieren Sie dessen Unterressourcen.
  2. Aktivieren Sie die verwaltete Identität für Ihren Event Grid-Namespace.
  3. Erstellen Sie ein Azure Key Vault-Konto, das das Zertifizierungsstellenzertifikat hostet, das Ihre öffentlichen Schlüssel enthält.
  4. Fügen Sie Rollenzuweisungen in Azure Key Vault für die verwaltete Identität des Namespaces hinzu.
  5. Konfigurieren von benutzerdefinierten Authentifizierungseinstellungen im Event Grid-Namespace
  6. Ihre Clients können mithilfe der von Ihrem Identitätsanbieter bereitgestellten Token eine Verbindung mit dem Event Grid-Namespace herstellen.

Erstellen eines Namespace und Konfigurieren dessen Unterressourcen

Befolgen Sie die Anweisungen unter Schnellstart: Veröffentlichen und Abonnieren von MQTT-Nachrichten im Event Grid-Namespace mit dem Azure-Portal, um einen Namespace zu erstellen und seine Unterressourcen zu konfigurieren: Überspringen Sie die Schritte zur Zertifikat- und Clienterstellung, wenn die Clientidentitäten aus dem bereitgestellten Token stammen. Clientattribute basieren auf den benutzerdefinierten Ansprüchen im Clienttoken. Die Clientattribute werden in der Clientgruppenabfrage, in Themenvorlagenvariablen und in der Routinganreicherungskonfiguration verwendet.

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 und das Serverzertifikat für Ihre benutzerdefinierte Domäne abzurufen. Verwenden Sie den folgenden Befehl, um die systemseitig 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 benutzerseitig 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

  1. 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"

  2. 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:

  1. 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)

  2. 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)

  3. 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 Gewähren des Zugriffs auf Key Vault-Schlüssel, -Zertifikate und -Geheimnisse mit der rollenbasierten Zugriffssteuerung in Azure.

Konfigurieren von benutzerdefinierten Authentifizierungseinstellungen im Event Grid-Namespace

In diesem Schritt konfigurieren Sie benutzerdefinierte Authentifizierungseinstellungen im Event Grid-Namespace mithilfe des Azure-Portals und der Azure CLI. Sie müssen zuerst den Namespace erstellen und ihn dann mit den folgenden Schritten aktualisieren.

Verwenden des Azure-Portals

  1. Navigieren Sie im Azure-Portal zu Ihrem Event Grid-Namespace.

  2. Wählen Sie auf der Seite Event Grid-Namespace im linken Menü die Option Konfiguration aus.

  3. Geben Sie im Abschnitt Benutzerdefinierte JWT-Authentifizierung Werte für die folgenden Eigenschaften an:

    1. Wählen Sie Benutzerdefinierte JWT-Authentifizierung aktivieren aus.

    2. Tokenaussteller: Geben Sie den Wert der Ausstelleransprüche der JWT-Token ein, die von den MQTT-Clients bereitgestellt werden.

    3. Wählen Sie Ausstellerzertifikat hinzufügen aus.

      Screenshot: Abschnitt „Benutzerdefinierte JWT-Authentifizierung“ auf der Seite „Konfiguration“ für einen Event Grid-Namespace

    4. Geben Sie auf der neuen Seite Werte für die folgenden Eigenschaften an.

      1. Zertifikat-URL: Der Zertifikatbezeichner des Ausstellerzertifikats in Azure Key Vault, das Sie erstellt haben. Sie können stattdessen Zertifikat mit einem Schlüsseltresor auswählen auswählen, um das Zertifikat und den Schlüsseltresor aus Ihren Abonnements auszuwählen.

      2. Identität: Die Identität, die für die Authentifizierung mit dem Key Vault verwendet wird, um auf das erstellte Ausstellerzertifikat zuzugreifen.

      3. Wählen Sie Hinzufügen aus.

        Screenshot: Seite zum Hinzufügen eines Ausstellerzertifikats

  4. Wählen Sie zurück auf der Seite Konfiguration die Option Anwenden aus.

    Hinweis

    Sie können bis zu zwei iss-Zertifikate für die Zertifikat-/Schlüsselrotation hinzufügen.

Mithilfe der Azure-Befehlszeilenschnittstelle

Verwenden Sie den folgenden Befehl, um Ihren Namespace mit der Konfiguration der benutzerdefinierten JWT-Authentifizierung zu aktualisieren.

az resource update --resource-type Microsoft.EventGrid/namespaces --api-version 2024-06-01-preview --ids /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dummy-cd-test/providers/Microsoft.EventGrid/namespaces/dummy-cd-test2 --set properties.topicSpacesConfiguration.clientAuthentication='{\"customJwtAuthentication\":{\"tokenIssuer\":\"dmpypin-issuer\",\"issuerCertificates\":[{\"certificateUrl\":\"https://dummyCert-cd-test.vault.azure.net/certificates/dummy-cd-test/4f844b284afd487e9bba0831191087br1\",\"identity\":{\"type\":\"SystemAssigned\"}}]}}'

Format der JSON-Webtoken

JSON-Webtoken sind in die Abschnitte für JWT-Header und JWT-Nutzlast unterteilt.

JWT-Header

Die Kopfzeile muss mindestens die Felder typ und alg enthalten. typ muss immer JWS und alg immer RS256 sein. Der Tokenheader muss wie folgt lauten:

{
    "typ": "JWT",
    "alg": "RS256"
}

JWT-Nutzlast

Event Grid erfordert die folgenden Ansprüche: iss, sub, aud, exp, nbf.

Name Beschreibung
iss Aussteller. Der Wert in JWT muss mit dem Aussteller in der Event Grid-Namespacekonfiguration für die benutzerdefinierte JWT-Authentifizierung übereinstimmen.
sub Betreff: Der Wert wird als Name für die Authentifizierungsidentität verwendet.
aud Zielgruppe. Der Wert kann eine Zeichenfolge oder ein Array mit Zeichenfolgen sein. Der Wert muss den standardmäßigen Hostnamen des Event Grid-Namespace und/oder die benutzerdefinierte Domäne für diesen Event Grid-Namespace enthalten (sofern konfiguriert). Die Zielgruppe kann andere Zeichenfolgen enthalten, aber mindestens eine dieser Zeichenfolgen muss ein standardmäßiger Hostname des Event Grid-Namespace oder eine benutzerdefinierte Domäne für diesen Namespace sein.
exp Expiration. Unix-Zeit, zu der JWT das abläuft.
nbf Nicht vor: Unix-Zeit, zu der das JWT gültig wird.

Event Grid ordnet alle Ansprüche Clientattributen zu, wenn sie über einen der folgenden Typen verfügen: int32, string, array of strings. Die Standardansprüche iss, sub, aud, exp, nbf werden aus Clientattributen ausgeschlossen. Im folgenden JWT-Beispiel werden nur drei Ansprüche in Clientattribute konvertiert (num_attr, str_attr, str_list_attr), da sie die korrekten Typen (int32, string, array of strings) aufweisen. incorrect_attr_1, incorrect_attr_2, incorrect_attr_3 werden nicht in Clientattribute konvertiert, da sie vom falschen Typ sind: float, array of integers, object.

{
    "iss": "correct_issuer",
    "sub": "d1",
    "aud": "testns.mqtt-broker-int.azure.net",
    "exp": 1712876224,
    "nbf": 1712869024,
    "num_attr": 1,
    "str_attr": "some string",
    "str_list_attr": [
        "string 1",
        "string 2"
    ],
    "incorrect_attr_1": 1.23,
    "incorrect_attr_2": [
        1,
        2,
        3
    ],
    "incorrect_attr_3": {
        "field": "value"
    }
}

Zugehöriger Inhalt