Usare JSON Web Token OAuth 2.0 (JWT) per autenticarsi con i namespace

Questo articolo illustra come eseguire l'autenticazione con Azure Event Grid usando JSON Web Tokens (OAuth 2.0).

Il broker MQTT di Griglia di eventi di Azure supporta l'autenticazione JWT OAuth 2.0, che consente ai client di connettersi ed eseguire l'autenticazione con uno spazio dei nomi di Griglia di eventi usando token Web JSON rilasciati da qualsiasi provider di identità, a parte Microsoft Entra ID.

Prerequisiti

Per usare l'autenticazione JWT OAuth 2.0 per gli spazi dei nomi, è necessario disporre dei prerequisiti seguenti:

• Fornitore di identità che può emettere JSON Web Token.
• Certificato CA che include le chiavi pubbliche usate per convalidare i token client (Key Vault) o il file PEM dei certificati di chiave pubblica (caricamento diretto).

Procedura generale

Per usare l'autenticazione JWT OAuth 2.0 per gli spazi dei nomi, seguire questa procedura:

1. Creare uno spazio dei nomi e configurare le relative sotto-risorse.

2. Abilitare l'identità gestita nello spazio dei nomi Griglia di eventi.

3. Configurare le impostazioni di autenticazione OAuth 2.0 nel namespace di Event Grid seguendo questi passaggi:

   1. Creare un account di Azure Key Vault che ospita il certificato dell'Autorità di Certificazione che include le chiavi pubbliche e aggiungere un'assegnazione di ruolo in Key Vault per l'identità gestita dello spazio dei nomi.
   2. In alternativa, caricare il file PEM dei certificati di chiave pubblica nello spazio dei nomi.

4. I client possono connettersi allo spazio dei nomi Griglia di eventi usando i token forniti dal provider di identità.

Creare uno spazio dei nomi e configurare le relative sotto-risorse

Seguire le istruzioni riportate in Avvio rapido: pubblicare e sottoscrivere messaggi MQTT nello spazio dei nomi Griglia di eventi con il portale di Azure per creare uno spazio dei nomi e configurare le relative sotto-risorse. Ignorare i passaggi di creazione del certificato e del client man mano che le identità client provengono dal token fornito. Gli attributi client sono basati sulle attestazioni personalizzate nel token client. Gli attributi client vengono usati nella query del gruppo client, nelle variabili del modello di argomento e nella configurazione dell'arricchimento del routing.

Abilitare l'identità gestita nello spazio dei nomi Griglia di eventi

Lo spazio dei nomi usa l'identità gestita per accedere all'istanza di Azure Key Vault per ottenere il certificato del server per il dominio personalizzato. Usare il comando seguente per abilitare l'identità gestita assegnata dal sistema nello spazio dei nomi Griglia di eventi:

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

Per informazioni sulla configurazione delle identità assegnate dal sistema e dall'utente tramite il portale di Azure, vedere Abilitare l'identità gestita per uno spazio dei nomi Griglia di eventi.

Configurare le impostazioni di autenticazione JWT OAuth 2.0 nel namespace di Event Grid -Key Vault

Innanzitutto, crea un account di Azure Key Vault, carica il certificato del server e assegna all'identità gestita del namespace un ruolo appropriato nel key vault. Quindi, configura le impostazioni di autenticazione personalizzate nel namespace di Event Grid usando il portale di Azure o l'interfaccia della riga di comando di Azure. È prima necessario creare lo spazio dei nomi e quindi aggiornarlo seguendo questa procedura.

Creare un account Azure Key Vault e caricare il certificato del server

1. Usare il comando seguente per creare un account Azure Key Vault:

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

2. Usare il comando seguente per importare un certificato in Azure Key Vault

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

   Nota

   Il certificato deve includere il nome di dominio nel nome alternativo del soggetto per DNS. Per ulteriori informazioni, vedere Esercitazione: Importare un certificato in Azure Key Vault.

Aggiungere l'assegnazione di ruolo in Azure Key Vault per l'identità gestita dello spazio dei nomi

È necessario fornire l'accesso allo spazio dei nomi per accedere all'account Azure Key Vault attenendosi alla procedura seguente:

1. Ottenere l'ID dell'entità di sicurezza dell'identità gestita del sistema dello spazio dei nomi Griglia di eventi usando il comando seguente

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

2. Ottenere l'ID della risorsa di Azure Key Vault.

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

3. Aggiungere l'assegnazione di ruolo in Key Vault per l'identità gestita dello spazio dei nomi.

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

   Per ulteriori informazioni sull'accesso a Key Vault e sull'esperienza con il portale, vedere Fornire l'accesso a chiavi, certificati e segreti di Key Vault con il controllo degli accessi in base al ruolo di Azure.

Usare il portale di Azure per configurare l'autenticazione

1. Passare allo spazio dei nomi Griglia di eventi nel portale di Azure.

2. Nella pagina Spazio dei nomi Griglia di eventi, selezionare Configurazione nel menu a sinistra.

3. Nella sezione Autenticazione JWT personalizzata specificare i valori per le proprietà seguenti:

   1. Selezionare Abilita autenticazione JWT personalizzata.

   2. Emittente dei token: immettere il valore delle attestazioni dell'emittente dei token JWT, presentate dai client MQTT.

   3. Per Certificato autorità di certificazione, è necessario selezionare Da Azure Key Vault.

      

   4. Nella nuova pagina specificare i valori per le proprietà seguenti.

      1. URL certificato: identificatore del certificato del server dell'autorità di certificazione in Azure Key Vault creato. È possibile scegliere Seleziona un certificato usando un insieme di credenziali delle chiavi per selezionare il certificato e l'insieme di credenziali delle chiavi dalle sottoscrizioni.

      2. Identità: identità usata per l'autenticazione con Key Vault per accedere al certificato dell'autorità di certificazione creato.

      3. Selezionare Aggiungi.

         

4. Una volta tornai alla pagina Configurazione selezionare Applica.

   Nota

   È possibile aggiungere fino a due certificati issa scopo di rotazione di certificati/chiavi.

Utilizzare l'interfaccia della riga di comando di Azure

Usare il comando seguente per aggiornare lo spazio dei nomi con la configurazione dell'autenticazione JWT personalizzata.

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

Formato del token JSON Web

I JSON Web Tokens devono includere le sezioni dell'intestazione JWT, del payload JWT e della firma JWT.

Intestazione JWT

L'intestazione deve contenere almeno i campi typ e alg.  typ deve essere sempre JWS e alg deve essere sempre RS256. L'intestazione del token deve essere la seguente:

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

Payload JWT

Griglia di eventi richiede le attestazioni seguenti: iss, sub, aud, exp, nbf.

Nome	Descrizione
iss	Autorità emittente. Il valore in JWT deve corrispondere all'autorità di certificazione nella configurazione dello spazio dei nomi Griglia di eventi per l'autenticazione JWT personalizzata.
sub	Oggetto. Il valore viene usato come nome dell'identità di autenticazione.
aud	Destinatari. Value è una matrice di stringhe. Il valore deve contenere il nome host e/o il dominio personalizzato standard dello spazio dei nomi Griglia di eventi (se configurato). I destinatari possono contenere altre stringhe, ma è necessario che almeno una di queste stringhe sia un nome host standard di Griglia di eventi o un dominio personalizzato per questo spazio dei nomi.
exp	Scadenza. Tempo Unix alla scadenza di JWT.
nbf	Non prima. Tempo unità in cui il token JWT diventa valido.

Griglia di eventi esegue il mapping di tutte le attestazioni agli attributi client se hanno uno dei tipi seguenti: int32, string, array of strings. Le attestazioni standard iss, sub, aud,exp e nbf vengono escluse dagli attributi client. Nell'esempio JWT seguente vengono convertite solo tre attestazioni in attributi client, num_attr, str_attr, str_list_attr, perché hanno tipi corretti int32, string e array of strings.  incorrect_attr_1, incorrect_attr_2, incorrect_attr_3 non vengono convertiti in attributi client, perché hanno tipi errati: 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"
    }
}

Configurare le impostazioni di autenticazione JWT OAuth 2.0 nel namespace di Event Grid - Caricamento diretto

In questo passaggio si configurano le impostazioni di autenticazione JWT personalizzate nell'Event Grid namespace utilizzando il portale di Azure e l'Azure CLI. È prima necessario creare lo spazio dei nomi e quindi aggiornarlo seguendo questa procedura.

Usare il portale di Azure

1. Passare al namespace Event Grid nel portale di Azure.
2. Nella pagina Spazio dei nomi Event Grid, selezionare Configurazione dal menu a sinistra.
3. Nella sezione Autenticazione JWT personalizzata specificare i valori per le proprietà seguenti:

   1. Selezionare Abilita autenticazione JWT personalizzata.

   2. Emittente dei token: immettere il valore delle attestazioni dell'emittente dei token JWT, presentate dai client MQTT.

   3. Selezionare l'opzione certificato dell'emittente - Caricamento diretto.

      

4. Nella nuova pagina specificare i valori per le proprietà seguenti.

   1. Certificato: caricare il certificato del server in formato PEM.

   2. Kid: identificatore di chiave univoco per il certificato.

   3. Selezionare Aggiungi.

      

5. Una volta tornai alla pagina Configurazione selezionare Applica.

Utilizzare l'interfaccia della riga di comando di Azure

Usare il comando seguente per aggiornare lo spazio dei nomi con la configurazione di autenticazione JWT OAuth 2.0.

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

• Sostituire <resource-group-name>, <namespace-name>, <location><key-vault-name>, <certificate-name>, e <certificate-in-PEM-format> con i valori effettivi.
• Il valore encodedCertificate deve includere il certificato completo e la chiave pubblica in formato PEM, incluse le intestazioni ( "-----BEGIN CERTIFICATE-----", "-----END CERTIFICATE----, ``-----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----).
• Verificare che il certificato di chiave pubblica fornito sia valido e considerato attendibile dal provider di identità.
• Aggiornare regolarmente i certificati di encodedIssuerCertificates quando i certificati vengono ruotati o scaduti.

Formato del token JSON Web

I JSON Web Tokens devono includere le sezioni dell'intestazione JWT, del payload JWT e della firma JWT.

Griglia di eventi richiede le attestazioni seguenti: iss, sub, aud, exp, nbf.

• kid è facoltativo. Se è presente, per la convalida viene usato il certificato con corrispondenza kid .
• Elenco di attestazioni standard non usate come attributi - iss, subaudexpnbfiat. jti
• Tutte le attestazioni con tipo di dati corretto (numero che si adatta a int32, stringa, matrice di stringhe) vengono usate come attributi. Nell'esempio num_attr_pos, num_attr_neg, str_attrle str_list_attr attestazioni hanno tipi di dati corretti e vengono usate come attributi.
• Nell'esempio bool_attr, num_attr_to_bignum_attr_float, obj_attr le attestazioni hanno tipi di dati non corretti e non vengono usate come attributi.

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

Contenuto correlato

• Autenticazione del client MQTT
• Autenticare il client con JWT personalizzato