Använd OAuth 2.0 JSON Web Tokens (JWT) för att autentisera med namnområden

Den här artikeln visar hur du autentiserar med Azure Event Grid-namnområdet med hjälp av OAuth 2.0 JSON-webbtoken.

Azure Event Grids MQTT-mäklare stöder OAuth 2.0 JWT-autentisering, vilket gör det möjligt för klienter att ansluta och autentisera med ett Event Grid-namnområde med hjälp av JSON Web Tokens som utfärdas av någon identitetsleverantör, förutom Microsoft Entra ID.

Förutsättningar

Om du vill använda OAuth 2.0 JWT-autentisering för namnområden måste du ha följande förutsättningar:

• Identitetsprovider som kan utfärda JSON-webbtoken.
• CA-certifikat som innehåller dina offentliga nycklar som används för att verifiera klienttoken (Key Vault) eller PEM-filen för dina offentliga nyckelcertifikat (direkt uppladdning).

Steg på hög nivå

Följ dessa steg om du vill använda OAuth 2.0 JWT-autentisering för namnområden:

1. Skapa ett namnrymd och konfigurera dess delresurser.

2. Aktivera hanterad identitet i Event Grid-namnområdet.

3. Konfigurera OAuth 2.0-autentiseringsinställningar i Event Grid-namnområdet genom att följa dessa steg:

   1. Skapa ett Azure Key Vault-konto som är värd för CA-certifikatet som innehåller dina offentliga nycklar och lägg till rolltilldelning i Key Vault för namnområdets hanterade identitet.
   2. Eller ladda upp PEM-filen för dina offentliga nyckelcertifikat till namnområdet.

4. Dina klienter kan ansluta till Event Grid-namnområdet med hjälp av de token som tillhandahålls av din identitetsleverantör.

Skapa ett namespace och konfigurera dess underresurser.

Följ instruktionerna från Snabbstart: Publicera och prenumerera på MQTT-meddelanden i Event Grid Namespace med Azure-portalen för att skapa ett namnområde och konfigurera dess underresurser. Hoppa över stegen för att skapa certifikat och klient eftersom klientidentiteterna kommer från det angivna tokenet. Klientegenskaper är baserade på de anpassade anspråken i klienttoken. Klientattributen används i klientgruppsförfrågan, ämnesmallvariabler och konfigurering av routningförbättringar.

Aktivera hanterad identitet i ditt Event Grid-namnområde

Namnområdet använder den hanterade identiteten för att få åtkomst till din Azure Key Vault-instans för att hämta servercertifikatet för din anpassade domän. Använd följande kommando för att aktivera systemtilldelad hanterad identitet på ditt Event Grid-namnutrymme:

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

För information om hur du konfigurerar system- och användartilldelade identiteter med hjälp av Azure-portalen, se Aktivera hanterad identitet för ett Event Grid-namnutrymme.

Konfigurera inställningarna för OAuth 2.0 JWT-autentisering i Event Grid-namnområdet -Key Vault

Skapa först ett Azure Key Vault-konto, ladda upp servercertifikatet och tilldela namnområdets hanterade identitet en lämplig roll i nyckelvalvet. Sedan konfigurerar du anpassade autentiseringsinställningar i Event Grid-namnområdet med antingen Azure-portalen eller Azure CLI. Du måste först skapa namnområdet och sedan uppdatera det med hjälp av följande steg.

Skapa ett Azure Key Vault-konto och ladda upp ditt servercertifikat

1. Använd följande kommando för att skapa ett Azure Key Vault-konto:

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

2. Använd följande kommando för att importera ett certifikat till Azure Key Vault

   az keyvault certificate import --vault-name "<your-key-vault-name>" -n "<cert name>" -f "<path to your certificate pem file> " 
   

   Anmärkning

   Ditt certifikat måste inkludera domännamnet i fältet för Subject Alternative Name för DNS. Mer information finns i Självstudie: Importera ett certifikat i Azure Key Vault.

Lägg till rolltilldelning i Azure Key Vault för namnrymmets hanterade identitet

Du måste ge åtkomst till namnområdet för att få åtkomst till ditt Azure Key Vault-konto med hjälp av följande steg:

1. Hämta Event Grid namespaces systemhanterade identitets primärnyckel-ID med följande kommando

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

2. Hämta ditt Resurs-ID för Azure Key Vault.

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

3. Lägg till rolltilldelning i Key Vault för namnområdets hanterade identitet.

   az role assignment create --role "Key Vault Certificate User" --assignee $principalId --scope $keyVaultResourceId 
   

   För mer information om åtkomst till Key Vault och portalupplevelsen, se Ge åtkomst till Key Vault-nycklar, certifikat och hemligheter med hjälp av Azure-rollbaserad åtkomstkontroll.

Använda Azure-portalen för att konfigurera autentisering

1. Gå till Event Grid-namnområdet i Azure-portalen.

2. På sidan Event Grid Namespace, välj Konfiguration i menyn till vänster.

3. I avsnittet Anpassad JWT-autentisering anger du värden för följande egenskaper:

   1. Välj Aktivera anpassad JWT-autentisering.

   2. Token issuer: Ange värdet för utfärdaranspråken för JWT:erna som presenteras av MQTT-klienterna.

   3. För Utfärdarcertifikat väljer du Från Azure Key Vault.

      

   4. På den nya sidan, ange värden för följande egenskaper.

      1. Certifikatets URL: certifikatidentifieraren för utfärdarcertifikatet i Azure Key Vault som du skapade. Du kan istället välja Välj ett certifikat med hjälp av en nyckelvalv för att välja certifikatet och nyckelvalvet från dina prenumerationer.

      2. Identitet: identiteten som används för att autentisera med Key Vault för att få tillgång till det utfärdande certifikatet som skapades.

      3. Välj Lägg till.

         

4. På sidan Konfiguration väljer du Använd.

   Anmärkning

   Du kan lägga till upp till två iss certifikat för certifikat-/nyckelrotation.

Använda Azure CLI

Använd följande kommando för att uppdatera din namnrymd med den anpassade JWT-autentiseringskonfigurationen.

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\"
          }
        }
      ]
    }
  }'
 

JSON Web Token-format

JSON-webbtoken måste ha avsnitten JWT-huvud, JWT-nyttolast och JWT-signatur.

JWT-huvud

Rubriken måste innehålla minst typ och alg fält.  typ måste alltid vara JWS och alg måste alltid vara RS256. Tokenhuvudet måste vara som följer:

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

JWT nyttolast

Event Grid kräver följande krav: iss, sub, aud, exp, nbf.

Event Grid mappar alla anspråk till klientattribut om de har en av följande typer: int32, string, array of strings. Standardfordringar iss, sub, aud, exp, nbf är undantagna från klientattribut. I följande JWT-exempel konverteras endast tre krav till klientattribut, num_attr, str_attr, str_list_attr, eftersom de har korrekta typer int32, string, array of strings.  incorrect_attr_1, incorrect_attr_2, incorrect_attr_3 konverteras inte till klientattribut eftersom de har fel typer: 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"
    }
}

Konfigurera inställningarna för OAuth 2.0 JWT-autentisering i Event Grid-namnområdet – Direktuppladdning

I det här steget konfigurerar du anpassade JWT-autentiseringsinställningar i Event Grid-namnområdet med hjälp av Azure-portalen och Azure CLI. Du måste först skapa namnområdet och sedan uppdatera det med hjälp av följande steg.

Använda Azure-portalen

1. Gå till Event Grid-namnområdet i Azure-portalen.
2. På sidan Event Grid-namnområde väljer du Konfiguration på den vänstra menyn.
3. I avsnittet Anpassad JWT-autentisering anger du värden för följande egenskaper:

   1. Välj Aktivera anpassad JWT-autentisering.

   2. Token issuer: Ange värdet för utfärdaranspråken för JWT:erna som presenteras av MQTT-klienterna.

   3. Välj certifikatalternativet utfärdare – Direktuppladdning.

      

4. På den nya sidan, ange värden för följande egenskaper.

   1. Certifikat: ladda upp servercertifikatet i PEM-format.

   2. Kid: En unik nyckelidentifierare för certifikatet.

   3. Välj Lägg till.

      

5. På sidan Konfiguration väljer du Använd.

Använda Azure CLI

Använd följande kommando för att uppdatera ditt namnområde med OAuth 2.0 JWT-autentiseringskonfigurationen.

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-----" 
            } 
        ] 
    } 

• Ersätt <resource-group-name>, <namespace-name>, <location>, <key-vault-name>, <certificate-name>och <certificate-in-PEM-format> med dina faktiska värden.
• Värdet encodedCertificate måste innehålla det fullständiga certifikatet och den offentliga nyckeln i PEM-format, inklusive rubriker ( "-----BEGIN CERTIFICATE-----", "-----END CERTIFICATE----, ``-----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----).
• Kontrollera att certifikatet för den offentliga nyckeln är giltigt och betrott av din identitetsleverantör.
• Uppdatera regelbundet kodade utfärdarcertifikat om certifikaten roteras eller har gått ut.

JSON Web Token-format

JSON-webbtoken måste ha avsnitten JWT-huvud, JWT-nyttolast och JWT-signatur.

Event Grid kräver följande krav: iss, sub, aud, exp, nbf.

• kid är valfritt. Om den finns används certifikat med matchning kid för validering.
• Lista över standardanspråk som inte används som attribut - iss, sub, , aud, exp, nbf, iat, . jti
• Alla anspråk som har rätt datatyp (tal som passar int32, sträng, strängmatris) används som attribut. I exemplet num_attr_pos, num_attr_neg, str_attrstr_list_attr har anspråk rätt datatyper och används som attribut.
• I exemplet bool_attr, num_attr_to_big, num_attr_float har obj_attr anspråk felaktiga datatyper och kan inte användas som attribut.

{ 
  "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" 
  } 
} 

Relaterat innehåll

• MQTT-klientautentisering
• Autentisera klient med anpassad JWT