Настройка идентификатора Microsoft Entra для проверки подлинности клиента

  • Статья

Предупреждение

В настоящее время проверка подлинности клиента Microsoft Entra и служба маркеров управляемого удостоверения несовместимы в Linux.

Для кластеров, работающих в Azure, идентификатор Microsoft Entra рекомендуется защитить доступ к конечным точкам управления. В этой статье описывается настройка идентификатора Microsoft Entra для проверки подлинности клиентов для кластера Service Fabric.

В Linux перед созданием кластера необходимо выполнить указанные ниже действия. В Windows также можно настроить проверку подлинности Microsoft Entra для существующего кластера.

В этой статье термин "приложение" относится к приложениям Microsoft Entra, а не к приложениям Service Fabric; при необходимости выполняется различие. Идентификатор Microsoft Entra позволяет организациям (клиентам) управлять доступом пользователей к приложениям.

Кластеры Service Fabric предлагают несколько точек входа для управления функциями кластеров, включая веб-интерфейс Service Fabric Explorer и Visual Studio. В результате вы создадите два приложения Microsoft Entra для управления доступом к кластеру: одним веб-приложением и одним собственным приложением. После создания приложений вы назначите пользователям роли только для чтения и администраторов.

Примечание.

В настоящее время Service Fabric не поддерживает проверку подлинности Microsoft Entra для хранения.

Примечание.

Известная проблема, из-за которую приложения и узлы в кластерах с поддержкой идентификатора Microsoft Microsoft Entra невозможно просмотреть на портале Azure.

Примечание.

Теперь идентификатор Microsoft Entra id требует, чтобы домен издателей приложений (регистрация приложений) проверялся или использовал схему по умолчанию. Дополнительные сведения см. в статье "Настройка домена издателя приложения и URI AppId в одном клиенте" для использования схемы по умолчанию или проверенных доменов .

Примечание.

Начиная с Service Fabric 11.0, service Fabric Обозреватель требует URI перенаправления одностраничного приложения вместо URI веб-перенаправления.

Необходимые компоненты

В этой статье предполагается, что клиент уже создан. Если вы этого не сделали, начните с чтения о том, как получить клиент Microsoft Entra. Чтобы упростить некоторые шаги, связанные с настройкой идентификатора Microsoft Entra с кластером Service Fabric, мы создали набор скриптов Windows PowerShell. Для некоторых действий требуется доступ на уровне администратора к идентификатору Microsoft Entra. Если сценарий возникает с ошибкой 401 или 403 "Authorization_RequestDenied", администратору необходимо выполнить скрипт.

  1. Выполните проверку подлинности с помощью административных разрешений Azure.
  2. Клонируйте репозиторий на компьютер.
  3. Убедитесь, что для установленных скриптов есть все необходимые компоненты.

Создание приложений Microsoft Entra и назначение ролей пользователям

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

SetupApplications.ps1

Выполните SetupApplications.ps1 и укажите идентификатор арендатора, имя кластера, URI веб-приложения и URL-адрес ответа веб-приложения в качестве параметров. Используйте -remove, чтобы удалить регистрации приложений. С помощью -logFile <log file path> создается журнал расшифровки. Дополнительные сведения см. в справке по скрипту (help .\setupApplications.ps1 -full). Скрипт создаст веб-приложение и собственное приложение для представления кластера Service Fabric. Две новые записи регистрации приложений находятся в следующем формате:

  • Имя_кластера_Cluster
  • Имя_кластера_Client

Примечание.

Для национальных облаков (например, Azure для государственных организаций, Microsoft Azure, управляемых 21Vianet), также следует указать -Location параметр.

Параметры

  • tenantId. Вы можете узнать TenantId, выполнив команду PowerShell Get-AzureSubscription. После выполнения этой команды для каждой подписки отображается TenantId.

  • clusterName:ClusterName используется для префикса приложений Microsoft Entra, созданных скриптом. Не нужно точно соответствовать фактическому имени кластера. Это предназначено только для упрощения сопоставления артефактов Microsoft Entra с кластером Service Fabric, с которыми они используются.

  • SpaApplicationReplyUrl:SpaApplicationReplyUrl — это конечная точка по умолчанию, которую идентификатор Microsoft Entra возвращает пользователям после завершения входа. Эту конечную точку следует назначить конечной точкой Service Fabric Explorer для кластера. Если вы создаете приложения Microsoft Entra для представления существующего кластера, убедитесь, что этот URL-адрес соответствует конечной точке существующего кластера. Если вы создаете приложения для нового кластера, запланируйте конечную точку кластера и не используйте конечную точку существующего кластера. По умолчанию Service Fabric Explorer использует конечную точку https://<cluster_domain>:19080/Explorer/index.html.

  • webApplicationUri:WebApplicationUri — это URI проверенного домена или URI с использованием формата схемы API API://{{идентификатор клиента}}/{{имя кластера}}. Дополнительные сведения см . в разделе URI AppId в приложениях с одним клиентом, где требуется использовать схему по умолчанию или проверенные домены .

    Пример схемы API: API://0e3d2646-78b3-4711-b8be-74a381d9890c/mysftestcluster

SetupApplications.ps1. Пример

# if using cloud shell
# cd clouddrive 
# git clone https://github.com/Azure-Samples/service-fabric-aad-helpers
# cd service-fabric-aad-helpers
# code .

$tenantId = '0e3d2646-78b3-4711-b8be-74a381d9890c'
$clusterName = 'mysftestcluster'
$spaApplicationReplyUrl = 'https://mysftestcluster.eastus.cloudapp.azure.com:19080/Explorer/index.html' # <--- client browser redirect url
#$webApplicationUri = 'https://mysftestcluster.contoso.com' # <--- must be verified domain due to AAD changes
$webApplicationUri = "API://$tenantId/$clusterName" # <--- doesn't have to be verified domain

$configObj = .\SetupApplications.ps1 -TenantId $tenantId `
  -ClusterName $clusterName `
  -SpaApplicationReplyUrl $spaApplicationReplyUrl `
  -AddResourceAccess `
  -WebApplicationUri $webApplicationUri `
  -Verbose

Скрипт выводит переменную $configObj для последующих команд и выводит содержимое JSON, требуемое для шаблона Azure Resource Manager. Скопируйте выходные данные JSON и используйте при создании или изменении существующего кластера , создайте кластер с включенным идентификатором Microsoft Entra ID.

SetupApplications.ps1. Пример выходных данных

Name                           Value
----                           -----
WebAppId                       f263fd84-ec9e-44c0-a419-673b1b9fd345
TenantId                       0e3d2646-78b3-4711-b8be-74a381d9890c
ServicePrincipalId             3d10f55b-1876-4a62-87db-189bfc54a9f2
NativeClientAppId              b22cc0e2-7c4e-480c-89f5-25f768ecb439

-----ARM template-----
"azureActiveDirectory": {
  "tenantId":"0e3d2646-78b3-4711-b8be-74a381d9890c",
  "clusterApplication":"f263fd84-ec9e-44c0-a419-673b1b9fd345",
  "clientApplication":"b22cc0e2-7c4e-480c-89f5-25f768ecb439"
},

JSON объекта параметров azureActiveDirectory

"azureActiveDirectory": {
  "tenantId":"<guid>",
  "clusterApplication":"<guid>",
  "clientApplication":"<guid>"
},

SetupUser.ps1

SetupUser.ps1 используется для добавления учетных записей пользователей в созданную регистрацию приложения с помощью выходной переменной $configObj (см. выше). Укажите имя пользователя для учетной записи пользователя, настроенной с регистрацией приложения, и укажите isAdmin для разрешений администратора. Если учетная запись пользователя является новой, укажите временный пароль для нового пользователя. Пароль необходимо изменить при первом входе. Если вы используете "-remove", вы удалите учетную запись пользователя, а не только регистрацию приложения.

SetupUser.ps1. Пример пользователя (чтение)

.\SetupUser.ps1 -ConfigObj $configobj `
  -UserName 'TestUser' `
  -Password 'P@ssword!123' `
  -Verbose

SetupUser.ps1. Пример администратора (чтение и запись)

.\SetupUser.ps1 -ConfigObj $configobj `
  -UserName 'TestAdmin' `
  -Password 'P@ssword!123' `
  -IsAdmin `
  -Verbose

SetupClusterResource.ps1

SetupClusterResource.ps1 можно дополнительно использовать для экспорта существующего шаблона ARM ресурса кластера, добавления или изменения конфигурации azureActiveDirectory и повторного развертывания шаблона. Используйте -Whatif для экспорта и изменения шаблона, но не изменения конфигурации повторного развертывания. Для этого скрипта требуется модуль Azure Az и имя группы ресурсов для кластера.

SetupClusterResource.ps1. Пример -Whatif

# requires azure module 'az'
# install-module az
$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
  -resourceGroupName $resourceGroupName `
  -WhatIf

Как только шаблон будет проверен и готов к обработке, перезапустите скрипт без параметра -WhatIf или используйте командлет PowerShell New-AzResourceGroupDeployment для развертывания шаблона.

SetupClusterResource.ps1. Пример

$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
  -resourceGroupName $resourceGroupName

Примечание.

Обновите шаблоны или скрипты подготовки кластера с изменениями конфигурации Microsoft Entra нового ресурса кластера.

Возможно, вам потребуется предоставить согласие администратора для настраиваемых разрешений API. Перейдите к колонке Регистрация приложений Azure и включите имя кластера в фильтр. Для обеих регистраций откройте раздел "Разрешения API" и выберите "Предоставить согласие администратора" (если применимо).

Screenshot that shows Grant admin consent selected on the Azure App registrations blade.

Screenshot that shows the Grant admin consent confirmation with Yes highlighted.

Проверка конфигурации Microsoft Entra

Перейдите по URL-адресу Service Fabric Explorer (SFX). Это должно совпадать с параметром spaApplicationReplyUrl. Должно отобразиться диалоговое окно проверки подлинности Azure. Войдите с помощью учетной записи, настроенной с помощью новой конфигурации Microsoft Entra. Убедитесь, что у учетной записи администратора есть доступ на чтение и запись, а у пользователя — доступ на чтение. Любое изменение кластера, например выполнение действия, является административным действием.

Справка по устранению неполадок при настройке идентификатора Microsoft Entra

Настройка идентификатора Microsoft Entra и его использование может быть сложной задачей, поэтому ниже приведены некоторые указатели на то, что можно сделать для отладки проблемы. Ведение журнала расшифровки PowerShell можно включить, используя аргумент -logFile в скриптах SetupApplications.ps1 и SetupUser.ps1 для просмотра выходных данных.

Примечание.

При выполнении миграции платформ удостоверений (из ADAL в MSAL), прекращении поддержки AzureRM в пользу Azure AZ и включении поддержки нескольких версий PowerShell зависимости могут быть не всегда правильными или актуальными, что приводит к ошибкам при выполнении скрипта. Выполнение команд и скриптов PowerShell из Azure Cloud Shell снижает вероятность возникновения ошибок при автоматической проверке подлинности сеанса и использовании управляемого удостоверения.

Button to launch the Azure Cloud Shell.

Request_BadRequest

Проблема.

Недопустимое обновление ссылки. Код состояния HTTP 400

VERBOSE: POST with 157-byte payload
VERBOSE: received -byte response of content type application/json
>> TerminatingError(Invoke-WebRequest): "{"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}"
confirm-graphApiRetry returning:True
VERBOSE: invoke-graphApiCall status: 400
exception:
Response status code doesn't indicate success: 400 (Bad Request).

Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
 239 |  …   $result = Invoke-WebRequest $uri -Method $method -Headers $headers  …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}

at invoke-graphApiCall, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 239
at invoke-graphApi, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 275
at add-roleAssignment, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 193
at add-user, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 244
at enable-AADUser, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 178
at main, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 136
at <ScriptBlock>, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 378
at <ScriptBlock>, /home/<user>/clouddrive/aad-test.ps1: line 43
at <ScriptBlock>, <No file>: line 1
WARNING: invoke-graphApiCall response status: 400
invoke-graphApi count:0 statuscode:400 -uri https://graph.microsoft.com/v1.0/0e3d2646-78b3-4711-b8be-74a381d9890c/servicePrincipals/3d10f55b-1876-4a62-87db-189bfc54a9f2/appRoleAssignedTo -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
confirm-graphApiRetry returning:True

Причина

Изменения конфигурации не распространялись. Скрипты повторяют определенные запросы с кодами состояния HTTP 400 и 404.

Решение

Скрипты повторяются на некоторых запросах с кодами состояния HTTP 400 и 404 upto, предоставленными "-timeoutMin", который по умолчанию составляет 5 минут. Скрипт можно повторно выполнить при необходимости.

Service Fabric Обозреватель предлагает выбрать сертификат

Проблема.

После успешного входа в Microsoft Entra ID в Service Fabric Обозреватель браузер возвращается на домашнюю страницу, но сообщение запрашивает выбор сертификата.

SFX certificate dialog

Причина

Пользователю не назначена роль в приложении кластера идентификатора Microsoft Entra ID. Таким образом, проверка подлинности Microsoft Entra завершается ошибкой в кластере Service Fabric. Service Fabric Explorer воспользуется проверкой подлинности на основе сертификата.

Решение

Следуйте инструкциям по настройке идентификатора Microsoft Entra и назначению ролей пользователей. Кроме того, рекомендуется включить параметр "Для доступа к приложению требуется назначение пользователей", как это делает скрипт SetupApplications.ps1.

Подключение ion с PowerShell завершается ошибкой: "Указанные учетные данные недопустимы"

Проблема.

При использовании PowerShell для подключения к кластеру с помощью режима безопасности AzureActiveDirectory после успешного входа в идентификатор Microsoft Entra подключение завершается ошибкой: "Указанные учетные данные недопустимы".

Решение

Решение этой проблемы такое же, как и в предыдущем случае.

Service Fabric Обозреватель возвращает сбой при входе: "AADSTS50011"

Проблема.

При попытке войти в идентификатор Microsoft Entra в Service Fabric Обозреватель страница возвращает сбой: "AADSTS50011: URL-адрес ответа не соответствует адресам> ответа<, настроенным для приложения: <guid>".

SFX reply address doesn't match

Причина

Приложение кластера (веб-), представляющее Service Fabric, Обозреватель пытается пройти проверку подлинности по идентификатору Microsoft Entra ID, а в рамках запроса он предоставляет URL-адрес возврата перенаправления. Но URL-адрес не указан в списке URL-адресов ответа приложения Microsoft Entra.

Решение

На странице регистрации приложения Microsoft Entra для кластера выберите "Проверка подлинности" и в разделе URI перенаправления добавьте URL-адрес service Fabric Обозреватель в список. Сохраните изменения.

Web application reply URL

Подключение при входе в кластер с помощью проверки подлинности Microsoft Entra через PowerShell возникает ошибка при входе: "AADSTS50011".

Проблема.

При попытке подключиться к кластеру Service Fabric с помощью идентификатора Microsoft Entra с помощью PowerShell страница входа возвращает ошибку: "AADSTS50011: URL-адрес ответа, указанный в запросе, не соответствует URL-адресам ответа, настроенным для приложения: <guid>".

Причина

Как и в приведенной выше проблеме, PowerShell пытается выполнить проверку подлинности в идентификаторе Microsoft Entra ID, который предоставляет URL-адрес перенаправления, который не указан в списке URL-адресов ответа приложения Microsoft Entra.

Решение

Используйте ту же процедуру, что и для предыдущей проблемы, но задайте для URL-адреса значение urn:ietf:wg:oauth:2.0:oob — перенаправление для проверки подлинности в командной строке.

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

Проблема.

Скрипт PowerShell может не выполнить все команды REST, необходимые для завершения настройки Microsoft Entra с ошибкой "Authorization_RequestDenied", "Недостаточно привилегий для завершения операции". Пример ошибки

Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
 239 |  …   $result = Invoke-WebRequest $uri -Method $method -Headers $headers  …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"error":{"code":"Authorization_RequestDenied","message":"Insufficient privileges to complete the
     | operation.","innerError":{"date":"2022-08-29T14:46:37","request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0","client-request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0"}}}
...
invoke-graphApi count:0 statuscode:403 -uri https://graph.microsoft.com/v1.0/72f988bf-86f1-41af-91ab-2d7cd011db47/oauth2PermissionGrants -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:364
Line |
 364 |      assert-notNull $result "aad app service principal oauth permissio …
     |      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | aad app service principal oauth permissions User.Read configuration failed

Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:656
Line |
 656 |  main
     |  ~~~~
     | exception:  exception: assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed  Exception:
     | /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:22 Line |   22 |          throw "assertion failure: object:$obj message:$msg"      |         
     | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      | assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed  
...

Причина

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

Решение

Чтобы завершить все оставшиеся действия, обратитесь к Администратор istrator клиента Azure или идентификатору Microsoft Entra. Предоставленные скрипты являются идемпотентными, поэтому их можно повторно выполнить для завершения процесса.

Подключение кластер с помощью проверки подлинности Microsoft Entra с помощью PowerShell

Чтобы подключить кластер Service Fabric, воспользуйтесь следующим примером команды PowerShell:

Connect-ServiceFabricCluster -ConnectionEndpoint <endpoint> -KeepAliveIntervalInSec 10 -AzureActiveDirectory -ServerCertThumbprint <thumbprint>

Дополнительные сведения о командлете Connect-ServiceFabricCluster см. в этой статье.

Можно ли повторно использовать один клиент Microsoft Entra в нескольких кластерах?

Да. Не забудьте добавить URL-адрес Service Fabric Explorer в (веб-)приложение кластера. В противном случае — Service Fabric Explorer не работает.

Почему вам по-прежнему нужен сертификат сервера, пока включен идентификатор Microsoft Entra?

FabricClient и FabricGateway выполняют взаимную аутентификацию. Во время проверки подлинности Microsoft Entra интеграция Microsoft Entra предоставляет удостоверение клиента серверу, а сертификат сервера используется клиентом для проверки удостоверения сервера. Дополнительные сведения о сертификатах Service Fabric см. в разделе Сертификаты X.509 и Service Fabric.

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

После настройки приложений Microsoft Entra и ролей для пользователей настройте и разверните кластер.