Uso de OAuth 2.0 JSON Web Tokens (JWT) para autenticarse con espacios de nombres

En este artículo se muestra cómo autenticarse con el espacio de nombres de Azure Event Grid mediante tokens web JSON de OAuth 2.0.

El agente MQTT de Azure Event Grid admite la autenticación JWT de OAuth 2.0, que permite a los clientes conectarse y autenticarse con un espacio de nombres de Event Grid mediante tokens web JSON emitidos por cualquier proveedor de identidades, aparte del identificador de Microsoft Entra.

Requisitos previos

Para usar la autenticación JWT de OAuth 2.0 para los espacios de nombres, necesita tener los siguientes requisitos previos.

• Proveedor de identidades que puede emitir tokens web JSON.
• Certificado de autoridad de certificación que incluye tus claves públicas usadas para validar los tokens de cliente (Key Vault) o el archivo PEM de tus certificados de clave pública (carga directa).

Pasos generales

Para usar la autenticación JWT de OAuth 2.0 para espacios de nombres, siga estos pasos:

1. Cree un espacio de nombres y configure sus subrecursos.

2. Habilite la identidad administrada en el espacio de nombres de Event Grid.

3. Para configurar la autenticación de OAuth 2.0 en el espacio de nombres de Event Grid, siga estos pasos:

   1. Cree una cuenta de Azure Key Vault que hospede el certificado de entidad de certificación que incluya las claves públicas y agregue la asignación de roles en Key Vault para la identidad administrada del espacio de nombres.
   2. O bien cargue el archivo PEM de los certificados de clave pública en el namespace.

4. Los clientes pueden conectarse al espacio de nombres de Event Grid mediante los tokens proporcionados por el proveedor de identidades.

Cree un espacio de nombres y configure sus subrecursos

Siga las instrucciones de Inicio rápido: Publicación y suscripción a mensajes MQTT en el espacio de nombres de Event Grid con Azure Portal para crear un espacio de nombres y configurar sus subrecursos. Omita los pasos de creación de certificados y clientes, ya que las identidades del cliente proceden del token proporcionado. Los atributos de cliente se basan en las notificaciones personalizadas del token de cliente. Los atributos de cliente se usan en la consulta del grupo de clientes, las variables de plantilla de tema y la configuración de enriquecimiento de enrutamiento.

Habilitación de la identidad administrada en el espacio de nombres de Event Grid

El espacio de nombres usa la identidad administrada para acceder a la instancia de Azure Key Vault para obtener el certificado de servidor del dominio personalizado. Use el siguiente comando para habilitar la identidad administrada asignada por el sistema en el espacio de nombres de Event Grid:

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

Para obtener información sobre cómo configurar identidades asignadas por el sistema y el usuario mediante Azure Portal, vea Habilitación de la identidad administrada para un espacio de nombres de Event Grid.

Configuración de la autenticación JWT de OAuth 2.0 en el espacio de nombres de Event Grid -Key Vault

En primer lugar, cree una cuenta de Azure Key Vault, cargue el certificado de servidor y asigne a la identidad administrada del espacio de nombres un rol adecuado en el almacén de claves. Después, configure las opciones de autenticación personalizadas en el espacio de nombres de Event Grid mediante Azure Portal o la CLI de Azure. Primero debe crear el espacio de nombres y actualizarlo mediante los pasos siguientes.

Creación de una cuenta de Azure Key Vault y carga del certificado de servidor

1. Use el comando siguiente para crear una cuenta de Azure Key Vault:

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

2. Use el siguiente comando para importar un certificado en Azure Key Vault

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

   Nota:

   El certificado debe incluir el nombre de dominio en el nombre alternativo del firmante para DNS. Para más información, vea Tutorial: Importación de un certificado en Azure Key Vault.

Adición de la asignación de roles en Azure Key Vault para la identidad administrada del espacio de nombres

Debe proporcionar acceso al espacio de nombres para acceder a la cuenta de Azure Key Vault mediante los pasos siguientes:

1. Obtención del identificador de entidad de seguridad de identidad administrada del sistema del espacio de nombres de Event Grid mediante el comando siguiente

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

2. Obtenga el identificador de recurso de Azure Key Vault.

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

3. Agregue la asignación de roles en Key Vault para la identidad administrada del espacio de nombres.

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

   Para más información sobre el acceso a Key Vault y la experiencia del portal, vea Proporcionar acceso a claves, certificados y secretos de Key Vault con un control de acceso basado en rol de Azure.

Uso de Azure Portal para configurar la autenticación

1. Vaya al espacio de nombres de Event Grid en Azure Portal.

2. En la página Espacio de nombres de Event Grid, seleccione Configuración en el menú de la izquierda.

3. En la sección Autenticación JWT personalizada, especifique valores para las siguientes propiedades:

   1. Seleccione Habilitar autenticación JWT personalizada.

   2. Emisor de tokens: Introduzca el valor de las declaraciones del emisor de los JWT que presentan los clientes MQTT.

   3. En Certificado del emisor, seleccione Desde Azure Key Vault.

      

   4. En la nueva página, especifique los valores de las siguientes propiedades.

      1. Dirección URL del certificado: el identificador de certificado del certificado de emisor en Azure Key Vault que creó. Puede elegir Seleccionar un certificado mediante un almacén de claves en su lugar para seleccionar el certificado y el almacén de claves de las suscripciones.

      2. Identidad: la identidad que se usa para autenticarse con Key Vault para acceder al certificado de emisor que se creó.

      3. Seleccione Agregar.

         

4. De nuevo en la página Configuración, seleccione Aplicar.

   Nota:

   Puede agregar hasta dos iss certificados con fines de rotación de clave/certificado.

Uso de CLI de Azure

Use el comando siguiente para actualizar el espacio de nombres con la configuración de autenticación JWT personalizada.

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 JSON Web Token

Los tokens web JSON deben contener secciones de encabezado JWT, contenido JWT y firma JWT.

Encabezado del JWT

El encabezado debe contener al menos campos typ y alg.  typ debe ser siempre JWS y alg debe ser siempre RS256. El encabezado del token debe ser el siguiente:

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

Carga de JWT

Event Grid requiere las siguientes notificaciones: iss, sub, aud, exp, nbf.

Event Grid asigna todas las notificaciones a los atributos de cliente si tienen uno de los siguientes tipos: int32, string, array of strings. Las notificaciones estándar iss, sub, aud, exp, nbf se excluyen de los atributos de cliente. En el siguiente ejemplo de JWT, solo se convierten tres notificaciones en atributos de cliente, num_attr, str_attr, str_list_attr, porque tienen tipos correctos int32, string, array of strings.  incorrect_attr_1, incorrect_attr_2, incorrect_attr_3 no se convierten en atributos de cliente, porque tienen tipos incorrectos: 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"
    }
}

Configuración de la autenticación JWT de OAuth 2.0 en el espacio de nombres de Event Grid: Carga directa

En este paso, configurará las opciones de autenticación JWT personalizadas en el espacio de nombres de Event Grid mediante Azure Portal y la CLI de Azure. Primero debe crear el espacio de nombres y actualizarlo mediante los pasos siguientes.

Usar Azure Portal

1. Vaya al espacio de nombres de Event Grid en Azure Portal.
2. En la página Espacio de nombres de Event Grid, seleccione Configuración en el menú de la izquierda.
3. En la sección Autenticación JWT personalizada, especifique valores para las siguientes propiedades:

   1. Seleccione Habilitar autenticación JWT personalizada.

   2. Emisor de tokens: Introduzca el valor de las declaraciones del emisor de los JWT que presentan los clientes MQTT.

   3. Seleccione la opción de certificado del emisor: Carga directa.

      

4. En la nueva página, especifique los valores de las siguientes propiedades.

   1. Certificado: cargue el certificado de servidor en formato PEM.

   2. Kid: un identificador de clave único para el certificado.

   3. Seleccione Agregar.

      

5. De nuevo en la página Configuración, seleccione Aplicar.

Uso de CLI de Azure

Use el comando siguiente para actualizar el espacio de nombres con la configuración de autenticación JWT de 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-----" 
            } 
        ] 
    } 

• Reemplace <resource-group-name>, <namespace-name>, <___location>, <key-vault-name>, <certificate-name>y <certificate-in-PEM-format> por los valores reales.
• El valor codificadoCertificate debe incluir el certificado completo y la clave pública en formato PEM, incluidos los encabezados ( "-----BEGIN CERTIFICATE-----", "-----END CERTIFICATE----, ``-----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----).
• Asegúrese de que el certificado de clave pública proporcionado es válido y de confianza para el proveedor de identidades.
• Actualice periódicamente los certificados codificados de emisor si estos se renuevan o expiran.

Formato JSON Web Token

Los tokens web JSON deben contener secciones de encabezado JWT, contenido JWT y firma JWT.

Event Grid requiere las siguientes notificaciones: iss, sub, aud, exp, nbf.

• kid es opcional. Si está presente, el certificado con coincidencia kid se usa para la validación.
• Lista de reclamaciones estándar que no se usan como atributos: iss, sub, aud, exp, nbf, iat, jti.
• Todas las reclamaciones que tienen el tipo de datos correcto (número que se ajusta a int32, cadena de texto, arreglo de cadenas de texto) se usan como atributos. En el ejemplo num_attr_pos, num_attr_neg, str_attr, las str_list_attr declaraciones tienen tipos de datos correctos y se usan como atributos.
• En el ejemplo bool_attr, num_attr_to_big, num_attr_float, las obj_attr reclamaciones tienen tipos de datos incorrectos y no pueden ser utilizados como atributos.

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

Contenido relacionado

• Autenticación de cliente MQTT
• Autenticación del cliente mediante JWT personalizado