Пользовательская проверка подлинности в статических веб-приложениях Azure

Статья
06/28/2024

Статические веб-приложения Azure обеспечивают управляемую проверку подлинности, которая использует регистрации поставщиков, управляемые Azure. Для обеспечения большей гибкости при регистрации можно переопределить значения по умолчанию с помощью пользовательской регистрации.

Пользовательская проверка подлинности позволяет также настроить параметры настраиваемых поставщиков, которые поддерживают OpenID Connect. Такая конфигурация позволяет регистрировать несколько внешних поставщиков.
Использование любых пользовательских регистраций отключает всех предварительно настроенных поставщиков.

Примечание.

Настраиваемая проверка подлинности доступна только в плане "Стандартный" статических веб-приложений Azure.

Настройка пользовательского поставщика удостоверений

Пользовательские поставщики удостоверений настраиваются в auth разделе файла конфигурации.

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

Чтобы создать регистрацию, начните с создания следующих параметров приложения:

Имя параметра	Значение
`AZURE_CLIENT_ID`	Идентификатор приложения (клиента) для регистрации приложения Microsoft Entra.
"AZURE_CLIENT_SECRET_APP_SETTING_NAME	Имя параметра приложения, который содержит секрет клиента для регистрации приложения Microsoft Entra.

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

Поставщики Microsoft Entra доступны в двух разных версиях. Версия 1 явно определяет userDetailsClaim, что позволяет возвращать в полезной нагрузке сведения о пользователе. Версия 2 по умолчанию возвращает сведения о пользователе и обозначается v2.0 в URL-адресе openIdIssuer.

Microsoft Entra версии 1

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Обязательно замените <TENANT_ID> идентификатор клиента Microsoft Entra.

Microsoft Entra версии 2

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Обязательно замените <TENANT_ID> идентификатор клиента Microsoft Entra.

Дополнительные сведения о настройке идентификатора Microsoft Entra см. в документации по Служба приложений аутентификации и авторизации с использованием существующей регистрации.

Сведения о настройке входа учетных записей см. в статье "Изменение учетных записей, поддерживаемых приложением " и ограничение приложения Microsoft Entra набору пользователей в клиенте Microsoft Entra.

Примечание.

Хотя раздел конфигурации для идентификатора Microsoft Entra id azureActiveDirectory, платформа псевдонимирует это aad в URL-адресе для входа, выхода и очистки сведений о пользователе. Дополнительные сведения см. в разделе проверки подлинности и авторизации .

Пользовательский сертификат

Чтобы добавить пользовательский сертификат в регистрацию приложения идентификатора Microsoft Entra, выполните следующие действия.

Если это еще не так, отправьте сертификат в Microsoft Key Vault.
Добавьте управляемое удостоверение в статическое веб-приложение.

Для управляемых удостоверений, назначенных пользователем, задайте keyVaultReferenceIdentity свойство статического объекта resourceId сайта управляемому удостоверению, назначенному пользователем.

Пропустите этот шаг, если управляемое удостоверение назначено системой.
Предоставьте управляемому удостоверению следующие политики доступа:
- Секреты: Get/List
- Сертификаты: Get/List
Обновите раздел конфигурации проверки подлинности раздела azureActiveDirectory конфигурации со clientSecretCertificateKeyVaultReference значением, как показано в следующем примере:
```
{
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/common/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretCertificateKeyVaultReference": "@Microsoft.KeyVault(SecretUri=https://<KEY_VAULT_NAME>.azure.net/certificates/<CERTIFICATE_NAME>/<CERTIFICATE_VERSION_ID>)",
          "clientSecretCertificateThumbprint": "*"
        }
      }
    }
  }
}
```
Обязательно замените значения для заполнителей, окруженных <>.

В URI секрета укажите имя хранилища ключей и имя сертификата. Если вы хотите закрепить версию, включите версию сертификата, в противном случае опустите версию, чтобы разрешить среде выполнения выбрать самую новую версию сертификата.

Задайте для параметра * "Всегда clientSecretCertificateThumbprint вытягивать последнюю версию отпечатка сертификатов".

Чтобы создать регистрацию, начните с создания следующих параметров приложения:

Имя параметра	Значение
`APPLE_CLIENT_ID`	Идентификатор клиента Apple.
`APPLE_CLIENT_SECRET_APP_SETTING_NAME`	Имя параметра приложения, в котором хранится секрет клиента Apple.

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

{
  "auth": {
    "identityProviders": {
      "apple": {
        "registration": {
          "clientIdSettingName": "APPLE_CLIENT_ID",
          "clientSecretSettingName": "APPLE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Дополнительные сведения о настройке Apple в качестве поставщика проверки подлинности см. в документации по проверке подлинности и авторизации службы приложений.

Чтобы создать регистрацию, начните с создания следующих параметров приложения:

Имя параметра	Значение
`FACEBOOK_APP_ID`	Идентификатор приложения Facebook.
`FACEBOOK_APP_SECRET_APP_SETTING_NAME`	Имя параметра приложения, в котором хранится секрет приложения Facebook.

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

{
  "auth": {
    "identityProviders": {
      "facebook": {
        "registration": {
          "appIdSettingName": "FACEBOOK_APP_ID",
          "appSecretSettingName": "FACEBOOK_APP_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Дополнительные сведения о настройке Facebook в качестве поставщика проверки подлинности см. в документации по проверке подлинности и авторизации службы приложений.

Чтобы создать регистрацию, начните с создания следующих параметров приложения:

Имя параметра	Значение
`GITHUB_CLIENT_ID`	Идентификатор клиента GitHub.
`GITHUB_CLIENT_SECRET_APP_SETTING_NAME`	Имя параметра приложения, в котором хранится секрет клиента GitHub.

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

{
  "auth": {
    "identityProviders": {
      "github": {
        "registration": {
          "clientIdSettingName": "GITHUB_CLIENT_ID",
          "clientSecretSettingName": "GITHUB_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Чтобы создать регистрацию, начните с создания следующих параметров приложения:

Имя параметра	Значение
`GOOGLE_CLIENT_ID`	Идентификатор клиента Google.
`GOOGLE_CLIENT_SECRET_APP_SETTING_NAME`	Имя параметра приложения, в котором хранится секрет клиента Google.

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

{
  "auth": {
    "identityProviders": {
      "google": {
        "registration": {
          "clientIdSettingName": "GOOGLE_CLIENT_ID",
          "clientSecretSettingName": "GOOGLE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Дополнительные сведения о настройке Google в качестве поставщика проверки подлинности см. в документации по проверке подлинности и авторизации службы приложений.

Чтобы создать регистрацию, начните с создания следующих параметров приложения:

Имя параметра	Значение
`X_CONSUMER_KEY`	Ключ потребителя X.
`X_CONSUMER_SECRET_APP_SETTING_NAME`	Имя параметра приложения, в котором хранится секрет потребителя X.

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

{
  "auth": {
    "identityProviders": {
      "twitter": {
        "registration": {
          "consumerKeySettingName": "X_CONSUMER_KEY",
          "consumerSecretSettingName": "X_CONSUMER_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Дополнительные сведения о настройке X в качестве поставщика проверки подлинности см. в документации по Служба приложений аутентификации и авторизации.

Вы можете настроить Статические веб-приложения Azure для использования пользовательского поставщика проверки подлинности, который соответствует спецификации OpenID Connect (OIDC). Для использования пользовательского поставщика OIDC необходимо выполнить следующие действия.

Допускается использование нескольких поставщиков OIDC.
Каждый поставщик должен иметь в конфигурации уникальное имя.
В качестве цели перенаправления по умолчанию может выступать только один поставщик.

Регистрация приложения в поставщике удостоверений

Необходимо зарегистрировать сведения о приложении с помощью поставщика удостоверений. Уточните у поставщика сведения о шагах, необходимых для создания идентификатора клиента и секрета клиента для приложения.

После регистрации приложения в поставщике удостоверений создайте приведенные ниже секреты приложения в параметрах статического веб-приложения.

Имя параметра	Значение
`MY_PROVIDER_CLIENT_ID`	Идентификатор клиента, созданный поставщиком проверки подлинности для статического веб-приложения.
`MY_PROVIDER_CLIENT_SECRET_APP_SETTING_NAME`	Имя параметра приложения, в котором хранится секрет клиента, созданный пользовательской регистрацией поставщика проверки подлинности для статического веб-приложения.

Если вы регистрируете других поставщиков, каждый из них нуждается в связанном идентификаторе клиента и хранилище секретов клиента в параметрах приложения.

Внимание

Секреты приложения — это конфиденциальные учетные записи для безопасного доступа. Не сообщайте этот секрет никому, не раскрывайте его в клиентском приложении и не проверяйте его в системе управления версиями.

После получения учетных данных для регистрации выполните следующие действия, чтобы создать пользовательскую регистрацию.

Вам понадобятся метаданные OpenID Connect для поставщика. Эту информацию можно найти в документе метаданных конфигурации, который представляет собой URL-адрес издателя с суффиксом /.well-known/openid-configuration. Получите этот URL-адрес конфигурации.

Добавьте раздел auth файла конфигурации с блоком конфигурации для поставщиков OIDC и вашим определением поставщика.

{
  "auth": {
    "identityProviders": {
      "customOpenIdConnectProviders": {
        "myProvider": {
          "registration": {
            "clientIdSettingName": "MY_PROVIDER_CLIENT_ID",
            "clientCredential": {
              "clientSecretSettingName": "MY_PROVIDER_CLIENT_SECRET_APP_SETTING_NAME"
            },
            "openIdConnectConfiguration": {
              "wellKnownOpenIdConfiguration": "https://<PROVIDER_ISSUER_URL>/.well-known/openid-configuration"
            }
          },
          "login": {
            "nameClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
            "scopes": [],
            "loginParameterNames": []
          }
        }
      }
    }
  }
}

Имя поставщика, в данном примере это myProvider, является уникальным идентификатором, который используют статические веб-приложения Azure.
Обязательно замените <PROVIDER_ISSUER_URL> значением URL-адрес издателя для поставщика.
Объект login позволяет предоставлять значения для пользовательских областей, входа в параметры или пользовательские утверждения.

Обратные вызовы проверки подлинности

Поставщики удостоверений требуют URL-адреса перенаправления для завершения запроса входа или выхода. Большинству поставщиков требуется добавить URL-адреса обратного вызова в список разрешений. Следующие конечные точки доступны в качестве назначений перенаправления.

Тип	Шаблон URL-адреса
Имя входа	`https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback`
Выход	`https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback`

Если вы используете идентификатор Microsoft Entra, используйте aad в качестве значения заполнителя <PROVIDER_NAME_IN_CONFIG> .

Примечание.

Эти URL-адреса предоставляются статическими веб-приложениями Azure для получения ответа от поставщика проверки подлинности. Вам не нужно создавать страницы на этих маршрутах.

Чтобы использовать настраиваемый поставщик удостоверений, используйте следующие шаблоны URL-адресов.

Действие	Расписание
Имя входа	`/.auth/login/<PROVIDER_NAME_IN_CONFIG>`
Выход	`/.auth/logout`
Сведения о пользователе	`/.auth/me`
Очистка сведений о пользователе	`/.auth/purge/<PROVIDER_NAME_IN_CONFIG>`

Если вы используете идентификатор Microsoft Entra, используйте aad в качестве значения заполнителя <PROVIDER_NAME_IN_CONFIG> .

Управление ролями

Каждому пользователю, обращающемуся к Статическому веб-приложению, присваивается одна или несколько ролей. Существует две встроенные роли, которые назначаются пользователям:

анонимный: все пользователи автоматически принадлежат анонимной роли.
проверка подлинности: все пользователи, вошедшие в систему, относятся к роли, прошедшей проверку подлинности .

Помимо встроенных ролей, можно назначить пользовательские роли пользователям и ссылаться на них в файле staticwebapp.config.json .

Приглашения
Функция (предварительная версия)

Добавление пользователя к роли

Чтобы добавить пользователя к роли, создаются приглашения, позволяющие ассоциировать пользователей с конкретными ролями. Роли определяются и сохраняются в файле staticwebapp.config.json.

Создание приглашения

Приглашения относятся к отдельным поставщикам авторизации, поэтому следует учитывать потребности приложения при выборе поставщиков для поддержки. Одни поставщики предоставляют адрес электронной почты пользователя, другие — только имя пользователя на сайте.

Поставщик авторизации	Предоставляет
Microsoft Entra ID	Адрес электронной почты.
GitHub	username
X	username

Чтобы создать приглашение, выполните следующие действия.

Перейдите к ресурсу Статические веб-приложения в портал Azure.
В разделе "Параметры" выберите "Управление ролями".
Выберите Пригласить.
В списке параметров выберите поставщика авторизации.
Добавьте имя пользователя или адрес электронной почты получателя в поле сведений о приглашенном.
- Для GitHub и X введите имя пользователя. Для остальных — адрес электронной почты получателя.
Выберите домен статического сайта в раскрывающемся меню "Домен ".
- Выбранный домен отображается в приглашении. Если у вас есть личный домен, связанный с сайтом, выберите личный домен.
Добавьте разделенный запятыми список имен ролей в поле Роль.
Введите максимальное количество часов, в течение которых приглашение будет действительным.
- Максимально возможное ограничение составляет 168 часов, что составляет семь дней.
Выберите Создать.
Скопируйте ссылку из поля Invite link (Ссылка приглашения).
Отправьте ссылку на приглашение пользователю, которому вы предоставляете доступ.

Когда пользователь выбирает ссылку в приглашении, им будет предложено войти с соответствующей учетной записью. После успешного входа пользователь связан с выбранными ролями.

Внимание

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

Обновление назначений ролей

Перейдите к ресурсу Статические веб-приложения в портал Azure.
В разделе "Параметры" выберите "Управление ролями".
Выберите пользователя в списке.
Измените список ролей в поле Роль.
Выберите Обновить.

Удалить пользователя

Перейдите к ресурсу Статические веб-приложения в портал Azure.
В разделе "Параметры" выберите "Управление ролями".
Найдите пользователя в списке.
Установите флажок в строке пользователя.
Выберите команду Удалить.

При удалении пользователя учитывайте следующие моменты:

Удаление пользователя сделает недействительными их разрешения.
Распространение по всему миру может занять несколько минут.
При обратном добавлении пользователя в приложение изменяется userId.

Вместо использования встроенной системы приглашений можно использовать бессерверную функцию для программного назначения ролей пользователям при входе.

Чтобы назначить пользовательские роли в функции, можно определить функцию API, которая автоматически вызывается после каждого успешного аутентификации пользователя с помощью поставщика удостоверений. Функция передает данные пользователя от поставщика. Он должен вернуть список пользовательских ролей, назначенных пользователю.

Пример использования этой функции:

Запросите базу данных, чтобы определить, какие роли необходимо назначить пользователю
Вызов API Microsoft Graph для определения ролей пользователя на основе членства в группах Active Directory
Определение ролей пользователя на основе утверждений, возвращаемых поставщиком удостоверений

Примечание.

Возможность назначать роли через функцию доступна только при настройке пользовательской проверки подлинности .

Если эта функция включена, все роли, назначенные через встроенную систему приглашений, игнорируются.

Настройка функции для назначения ролей

Чтобы настроить Статические веб-приложения использовать функцию API в качестве функции назначения ролей, добавьте rolesSource свойство в auth раздел файла конфигурации приложения. Значение rolesSource свойства — это путь к функции API.

{
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      // ...
    }
  }
}

Примечание.

После настройки функция назначения ролей больше не может быть доступ к внешним HTTP-запросам.

Создание функции для назначения ролей

После определения rolesSource свойства в конфигурации приложения добавьте функцию API в статическое веб-приложение по указанному пути. Вы можете использовать управляемое приложение-функцию или принести собственное приложение-функцию.

Каждый раз, когда пользователь успешно проходит проверку подлинности с помощью поставщика удостоверений, метод POST вызывает указанную функцию. Функция передает объект JSON в тексте запроса, содержащий сведения пользователя от поставщика. Для некоторых поставщиков удостоверений сведения о пользователе также содержат accessToken сведения о том, что функция может использовать для вызовов API с помощью удостоверения пользователя.

См. следующий пример полезных данных из идентификатора Microsoft Entra ID:

{
  "identityProvider": "aad",
  "userId": "72137ad3-ae00-42b5-8d54-aacb38576d76",
  "userDetails": "ellen@contoso.com",
  "claims": [
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
          "val": "ellen@contoso.com"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
          "val": "Contoso"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
          "val": "Ellen"
      },
      {
          "typ": "name",
          "val": "Ellen Contoso"
      },
      {
          "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier",
          "val": "7da753ff-1c8e-4b5e-affe-d89e5a57fe2f"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
          "val": "72137ad3-ae00-42b5-8d54-aacb38576d76"
      },
      {
          "typ": "http://schemas.microsoft.com/identity/claims/tenantid",
          "val": "3856f5f5-4bae-464a-9044-b72dc2dcde26"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
          "val": "ellen@contoso.com"
      },
      {
          "typ": "ver",
          "val": "1.0"
      }
  ],
  "accessToken": "eyJ0eXAiOiJKV..."
}

Функция может использовать сведения пользователя для определения ролей, назначенных пользователю. Он должен возвращать ответ HTTP 200 с текстом JSON, содержащим список имен пользовательских ролей для назначения пользователю.

Например, чтобы назначить пользователя Reader роли, Contributor верните следующий ответ:

{
  "roles": [
    "Reader",
    "Contributor"
  ]
}

Если пользователю не нужно назначать другие роли, верните пустой roles массив.

Дополнительные сведения см. в руководстве по назначению пользовательских ролей с помощью функции и Microsoft Graph.

Следующие шаги

Установка ролей пользователей программным способом

Поделиться через

Пользовательская проверка подлинности в статических веб-приложениях Azure

Настройка пользовательского поставщика удостоверений

Microsoft Entra версии 1

Microsoft Entra версии 2

Пользовательский сертификат

Регистрация приложения в поставщике удостоверений

Обратные вызовы проверки подлинности

Управление ролями

Добавление пользователя к роли

Создание приглашения

Обновление назначений ролей

Удалить пользователя

Настройка функции для назначения ролей

Создание функции для назначения ролей

Следующие шаги

Обратная связь

Дополнительные ресурсы

Поделиться через

Пользовательская проверка подлинности в статических веб-приложениях Azure

Настройка пользовательского поставщика удостоверений

Microsoft Entra версии 1

Microsoft Entra версии 2

Пользовательский сертификат

Обратные вызовы проверки подлинности

Сведения о входе, выходе и пользователе

Управление ролями

Добавление пользователя к роли

Создание приглашения

Обновление назначений ролей

Удалить пользователя

Следующие шаги

Обратная связь

Дополнительные ресурсы