Использование веб-маркеров JSON OAuth 2.0 (JWT) для проверки подлинности с помощью пространств имен

В этой статье показано, как пройти проверку подлинности в пространстве имен Сетки событий Azure с помощью веб-токенов OAuth 2.0 JSON.

Брокер MQTT в Службе "Сетка событий Azure" поддерживает проверку подлинности OAuth 2.0 JWT, которая позволяет клиентам подключаться и проходить проверку подлинности с помощью пространства имен Сетки событий с помощью веб-маркеров JSON, выданных любым поставщиком удостоверений, помимо идентификатора Microsoft Entra ID.

Чтобы использовать проверку подлинности OAuth 2.0 JWT для пространств имен, необходимо иметь следующие предварительные требования:

• Поставщик идентификации, который может выпускать JSON Web Tokens.
• Сертификат ЦС, включающий открытые ключи, используемые для проверки маркеров клиента (Key Vault) или PEM-файла сертификатов открытого ключа (прямая отправка).

Чтобы использовать проверку подлинности OAuth 2.0 JWT для пространств имен, выполните следующие действия.

1. Создайте пространство имен и настройте его подресурсы.
2. Включите управляемую идентичность в вашем пространстве имен Event Grid.
3. Настройте параметры проверки подлинности OAuth 2.0 в пространстве имен Сетки событий, выполнив следующие действия.
   1. Создайте учетную запись Azure Key Vault, включающую сертификат ЦС, содержащий открытые ключи, и добавьте назначение ролей в Key Vault для управляемого удостоверения пространства имен.
   2. Отправьте PEM-файл сертификатов открытого ключа в пространство имен.
4. Ваши клиенты могут подключаться к пространству имен Event Grid, используя токены, предоставленные вашим поставщиком удостоверений.

Следуйте инструкциям из Quickstart: Публикация и подписка на сообщения MQTT в пространстве имен Event Grid с порталом Azure, чтобы создать пространство имен и настроить его подресурсы. Пропустите этапы создания сертификата и клиента, так как идентификации клиентов поступают из предоставленного токена. Атрибуты клиента основаны на пользовательских утверждениях в токене клиента. Атрибуты клиента используются в запросе группы клиентов, переменных шаблонов тематики и конфигурации обогащения маршрутизации.

Пространство имен использует управляемую учетную запись для доступа к вашему экземпляру Azure Key Vault, чтобы получить серверный сертификат для вашего пользовательского домена. Используйте следующую команду, чтобы включить управляемую идентичность, назначенную системой, для вашего пространства имен Event Grid.

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

Для получения информации о настройке системных и пользовательских идентификаторов с использованием портала Azure, см. Включить управляемую идентификацию для пространства имен Event Grid.

Сначала создайте учетную запись Azure Key Vault, загрузите сертификат сервера и назначьте управляемую идентификацию пространства имен на соответствующую роль в хранилище ключей. Затем вы настроите пользовательские параметры авторизации в пространстве имен Event Grid с помощью портала Azure и Azure CLI. Сначала вам нужно создать пространство имен, а затем обновить его, следуя приведённым ниже шагам.

1. Используйте следующую команду для создания учетной записи Azure Key Vault.

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

2. Используйте следующую команду, чтобы импортировать сертификат в Azure Key Vault.

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

   Примечание

   Ваш сертификат должен включать доменное имя в поле альтернативного имени субъекта для DNS. Для получения дополнительной информации, см. Учебник: Импорт сертификата в Azure Key Vault.

Вам необходимо предоставить доступ к пространству имен, чтобы получить доступ к вашей учетной записи Azure Key Vault, следующим образом:

1. Получите идентификатор системы управляемой идентичности (ID principal) пространства имен Event Grid с помощью следующей команды

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

2. Получите идентификатор ресурса хранилища ключей Azure.

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

3. Добавьте назначение роли в Key Vault для управляемой идентификации пространства имен.

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

   Для получения дополнительной информации о доступе к Key Vault и использовании портала см. Предоставление доступа к ключам, сертификатам и секретам Key Vault с использованием управления доступом на основе ролей Azure.

1. Перейдите в пространство имен Event Grid в Azure portal.

2. На странице Event Grid Namespace выберите Конфигурация в левом меню.

3. В разделе Custom JWT authentication укажите значения для следующих свойств:

   1. Select Включить пользовательскую аутентификацию JWT.

   2. Эмитент токена: Введите значение для поля "issuer" JWT, представленных клиентами MQTT.

   3. Для сертификата издателя выберите из хранилища ключей Azure.

      

   4. На новой странице укажите значения для следующих свойств.

      1. URL сертификата: идентификатор сертификата издателя в Azure Key Vault, который вы создали. Вы можете выбрать Выбрать сертификат, используя ключевой хранилище, чтобы вместо этого выбрать сертификат и ключевое хранилище из ваших подписок.

      2. Идентификация: идентификатор, используемый для аутентификации с Key Vault для доступа к созданному сертификату издателя.

      3. Нажмите кнопку "Добавить".

         

4. Вернитесь на страницу "Конфигурация" и нажмите кнопку "Применить".

   Примечание

   Вы можете добавить до двух сертификатов iss для целей ротации сертификатов/ключей.

Используйте следующую команду, чтобы обновить ваш пространство имен с помощью настраиваемой конфигурации аутентификации JWT.

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 веб-токены делятся на секции заголовка JWT и секции полезной нагрузки JWT.

Заголовок должен содержать как минимум typ и alg поля.  typ всегда должно быть JWS, а alg всегда должно быть RS256. Заголовок токена должен быть следующим:

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

Event Grid требует наличия следующих заявок: iss, sub, aud, exp, nbf.

Event Grid сопоставляет все утверждения с атрибутами клиента, если они имеют один из следующих типов: int32, string, array of strings. Стандартные требования iss, sub, aud, exp, nbf исключены из атрибутов клиента. В следующем примере JWT только три утверждения преобразуются в клиентские атрибуты, num_attr, str_attr, str_list_attr, потому что они имеют правильные типы int32, string, array of strings.  incorrect_attr_1, incorrect_attr_2, incorrect_attr_3 не могут быть преобразованы в атрибуты клиента, потому что они имеют неверные типы: 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"
    }
}

На этом шаге вы настроите пользовательские настройки проверки подлинности JWT в пространстве имен Event Grid, используя портал Azure и Azure CLI. Сначала вам нужно создать пространство имен, а затем обновить его, следуя приведённым ниже шагам.

1. Перейдите к пространству имен Event Grid на портале Azure.
2. На странице пространства имен Event Grid выберите «Конфигурация» в меню слева.
3. В разделе пользовательской проверки подлинности JWT укажите значения для следующих свойств:

   1. Select Включить пользовательскую аутентификацию JWT.

   2. Эмитент токена: Введите значение для поля "issuer" JWT, представленных клиентами MQTT.

   3. Выберите параметр сертификата издателя — прямая отправка.

      

4. На новой странице укажите значения для следующих свойств.

   1. Сертификат: отправка сертификата сервера в формате PEM.

   2. Ребенок: уникальный идентификатор ключа для сертификата.

   3. Нажмите кнопку "Добавить".

      

5. Вернитесь на страницу "Конфигурация" и нажмите кнопку "Применить".

Используйте следующую команду, чтобы обновить пространство имен с помощью конфигурации проверки подлинности OAuth 2.0 JWT.

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

• Замените <resource-group-name>, , <namespace-name>, <certificate-name><location><key-vault-name>и <certificate-in-PEM-format> фактическими значениями.
• Значение encodedCertificate должно содержать полный сертификат в формате PEM, включая заголовки ( "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE----).
• Убедитесь, что предоставленный сертификат открытого ключа является допустимым и доверенным вашим поставщиком удостоверений.
• Регулярно обновляйте закодированные сертификаты издателя, если сертификаты заменяются или истекают.

полезная нагрузка JWT

Event Grid требует наличия следующих заявок: iss, sub, aud, exp, nbf.

• kid является необязательным. Если он имеется, то для проверки используется сертификат, соответствующий kid.
• Список стандартных утверждений, которые не используются в качестве атрибутов - iss, sub, aud, exp, nbf, iat, jti.
• Все утверждения, имеющие правильный тип данных (число, подходящее для int32, string, массив строк) используются в качестве атрибутов. В примере num_attr_pos, num_attr_negstr_attrstr_list_attr утверждения имеют правильные типы данных и используются в качестве атрибутов.
• В примере bool_attr, num_attr_to_bignum_attr_floatobj_attr утверждения имеют неправильные типы данных и не используются в качестве атрибутов.

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

• Проверка подлинности клиента MQTT
• Аутентификация клиента с использованием настраиваемого JWT