Freigeben über

Verwenden von OAuth 2.0 JSON-Webtoken (JWT) zur Authentifizierung mit Namespaces

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

Der MQTT-Broker von Azure Event Grid unterstützt die OAuth 2.0 JWT-Authentifizierung, mit der Clients eine Verbindung mit einem Event Grid-Namespace herstellen und authentifizieren können, indem JSON-Webtoken verwendet werden, die von jedem Identitätsanbieter ausgestellt werden, abgesehen von der Microsoft Entra-ID.

Voraussetzungen

Um die OAuth 2.0 JWT-Authentifizierung für Namespaces zu verwenden, müssen Sie die folgenden Voraussetzungen haben:

  • Identitätsanbieter, der JSON-Webtoken ausstellen kann.
  • Zertifizierungsstellenzertifikat, das Ihre öffentlichen Schlüssel enthält, die zum Überprüfen der Clienttoken (Key Vault) oder PEM-Datei Ihrer Public Key-Zertifikate (direkter Upload) verwendet werden.

Übergeordnete Schritte

Führen Sie die folgenden Schritte aus, um die OAuth 2.0 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. Konfigurieren Sie OAuth 2.0-Authentifizierungseinstellungen in Ihrem Event Grid-Namespace, indem Sie die folgenden Schritte ausführen:

    1. Erstellen Sie ein Azure Key Vault-Konto, das das Zertifizierungsstellenzertifikat hostet, das Ihre öffentlichen Schlüssel enthält, und fügen Sie eine Rollenzuweisung in Key Vault für die verwaltete Identität des Namespaces hinzu.
    2. Oder laden Sie die PEM-Datei Ihrer Öffentlichen Schlüsselzertifikate in den Namespace hoch.

  4. 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.

Konfigurieren von OAuth 2.0 JWT-Authentifizierungseinstellungen im Event Grid-Namespace -Key Vault

Erstellen Sie zunächst ein Azure Key Vault-Konto, laden Sie Ihr Serverzertifikat hoch, und weisen Sie der verwalteten Identität des Namespace eine entsprechende Rolle im Schlüsseltresor zu. Anschließend konfigurieren Sie benutzerdefinierte Authentifizierungseinstellungen im Event Grid-Namespace mithilfe des Azure-Portals oder der Azure CLI. Sie müssen zuerst den Namespace erstellen und ihn dann mit den folgenden Schritten aktualisieren.

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 "centraluseuap"

  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.

Verwenden des Azure-Portals zum Konfigurieren der Authentifizierung

  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. Token-Aussteller: Geben Sie den Wert der Ausstelleransprüche der JWTs ein, die von den MQTT-Clients präsentiert werden.

    3. Wählen Sie für das AusstellerzertifikatAus Azure Key Vault aus.

      Screenshot der Auswahl der Azure Key Vault-Option der Konfigurationsseite 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, statt 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.

Azure CLI verwenden

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/1111a1a1-bb2b-cc3c-dd4d-ffffee5e5e5e/resourceGroups/sample-rg/providers/Microsoft.EventGrid/namespaces/sample-namespace \
  --set properties.topicSpacesConfiguration.clientAuthentication='{
    \"customJwtAuthentication\":{
      \"tokenIssuer\":\"sample-issuer\",
      \"issuerCertificates\":[
        {
          \"certificateUrl\":\"https://sample-vault.vault.azure.net/certificates/sample-cert/12345abcdef67890\",
          \"identity\":{
            \"type\":\"UserAssigned\",
            \"userAssignedIdentity\":\"/subscriptions/1111a1a1-bb2b-cc3c-dd4d-ffffee5e5e5e/resourceGroups/sample-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/sample-identity\"
          }
        }
      ]
    }
  }'

Format der JSON-Webtoken

JSON-Webtoken müssen über JWT-Header-, JWT-Nutzlast- und JWT-Signaturabschnitte verfügen.

JWT-Header

Die Kopfzeile muss mindestens die Felder typ und alg enthalten.  typ muss immer JWS und alg immer RS256 sein. Der Token-Header 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 ist ein Array von Zeichenfolgen. 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 Ablaufdatum 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"
    }
}

Konfigurieren von OAuth 2.0 JWT-Authentifizierungseinstellungen im Event Grid-Namespace – Direkter Upload

In diesem Schritt konfigurieren Sie benutzerdefinierte JWT-Authentifizierungseinstellungen in Ihrem 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" die Option "Konfiguration" im linken Menü 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. Token-Aussteller: Geben Sie den Wert der Ausstelleransprüche der JWTs ein, die von den MQTT-Clients präsentiert werden.

    3. Wählen Sie die Option "Ausstellerzertifikat" aus – "Direkter Upload".

      Screenshot der Auswahl der Option

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

    1. Zertifikat: Laden Sie Ihr Serverzertifikat im PEM-Format hoch.

    2. KID: Ein eindeutiger Schlüsselbezeichner für das Zertifikat.

    3. Wählen Sie Hinzufügen aus.

      Screenshot: Seite zum Hochladen eines Ausstellerzertifikats

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

Azure CLI verwenden

Verwenden Sie den folgenden Befehl, um Ihren Namespace mit der OAuth 2.0 JWT-Authentifizierungskonfiguration zu aktualisieren.

az eventgrid namespace update \ 
    --resource-group <resource-group-name> \ 
    --name <namespace-name> \ 
    --api-version 2024-12-15-preview \ 
    --set customJwtAuthenticationSettings='{ 
        "tokenIssuer": "issuer-name", 
        "encodedIssuerCertificates": [
            { 
                "kid": "key1", 
                "encodedCertificate": "-----BEGIN CERTIFICATE-----\n<certificate-in-PEM-format>\n-----END CERTIFICATE-----" 
            } 
        ] 
    }
  • Ersetzen Sie <resource-group-name>, <namespace-name>, <location>, <key-vault-name>, <certificate-name> und <certificate-in-PEM-format> durch Ihre tatsächlichen Werte.
  • Der encodedCertificate-Wert muss das vollständige Zertifikat und den öffentlichen Schlüssel im PEM-Format enthalten, einschließlich Header ( "-----BEGIN CERTIFICATE-----", "-----END CERTIFICATE----, ``-----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----).
  • Stellen Sie sicher, dass das bereitgestellte Öffentliche Schlüsselzertifikat von Ihrem Identitätsanbieter gültig und vertrauenswürdig ist.
  • Aktualisieren Sie regelmäßig „encodedIssuerCertificates“, wenn Zertifikate rotiert werden oder abgelaufen sind.

Format der JSON-Webtoken

JSON-Webtoken müssen über JWT-Header-, JWT-Nutzlast- und JWT-Signaturabschnitte verfügen.

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

  • kid ist optional. Ist ein Wert angegeben, wird das Zertifikat mit dem übereinstimmenden kid-Wert für die Validierung verwendet.
  • Liste der Standardansprüche, die nicht als Attribute verwendet werden - iss, , subaudexp, nbf, iat. jti.
  • Alle Felder, die den korrekten Datentyp aufweisen (eine Zahl, die in int32 passt, eine Zeichenfolge oder ein Array von Zeichenfolgen), werden als Attribute verwendet. Im Beispiel verfügen die Ansprüche num_attr_pos, num_attr_neg, str_attr, str_list_attr über richtige Datentypen und werden als Attribute verwendet.
  • Im Beispiel bool_attr, num_attr_to_big, num_attr_float haben die obj_attr Claims falsche Datentypen und dürfen nicht als Attribute verwendet werden.
{ 
  "typ": "JWT", 
  "alg": "RS256", 
  "kid": "keyId1" 
}.{ 
  "iss": "some-issuer", 
  "sub": "device1", 
  "aud": "event-grid-namespace.ts.eventgrid.azure.net", 
  "exp": 1770426501, 
  "nbf": 1738886901, 
  "bool_attr": true, 
  "num_attr_pos": 1, 
  "num_attr_neg": -1, 
  "num_attr_to_big": 9223372036854775807, 
  "num_attr_float": 1.23, 
  "str_attr": "str_value", 
  "str_list_attr": [ 
    "str_value_1", 
    "str_value_2" 
  ], 
  "obj_attr": { 
      "key": "value" 
  } 
}

Zugehöriger Inhalt

  • Last updated on