設定客戶端驗證的 Microsoft Entra 識別碼

  • 發行項

警告

目前，Microsoft Entra 用戶端驗證和受控識別令牌服務在Linux上互不相容。

針對在 Azure 上執行的叢集，建議使用 Microsoft Entra ID 來保護管理端點的存取。 本文說明如何設定 Microsoft Entra ID 來驗證 Service Fabric 叢集的用戶端。

在 Linux 上，您必須先完成下列步驟，才能建立叢集。 在 Windows 上，您也可以選擇 為現有的叢集設定 Microsoft Entra 驗證。

在本文中，「應用程式」一詞是指 Microsoft Entra 應用程式，而非 Service Fabric 應用程式;必要時會進行區分。 Microsoft Entra ID 可讓組織（稱為租使用者）管理應用程式的使用者存取權。

Service Fabric 叢集提供數個其管理功能的進入點，包括 Web 型 Service Fabric Explorer 和 Visual Studio。 因此，您將建立兩個 Microsoft Entra 應用程式來控制叢集的存取：一個 Web 應用程式和一個原生應用程式。 建立應用程式之後，您會將使用者指派給唯讀和系統管理員角色。

注意

目前，Service Fabric 不支援儲存裝置的 Microsoft Entra 驗證。

注意

在 Azure 入口網站中無法檢視已啟用 Linux 的 Microsoft Entra 識別符叢集上的應用程式和節點，這是已知 問題 。

注意

Microsoft Entra ID 現在需要驗證或使用預設配置的應用程式（應用程式註冊）發行者網域。 如需詳細資訊，請參閱 在單一租使用者應用程式中設定應用程式的發行者網域 和 AppId Uri 需要使用預設配置或已驗證網域 。

注意

從 Service Fabric 11.0 開始，Service Fabric Explorer 需要單頁應用程式重新導向 URI，而不是 Web 重新導向 URI。

必要條件

在本文中，我們假設您已建立租使用者。 如果您尚未這麼做，請先閱讀 如何取得 Microsoft Entra 租使用者。 為了簡化使用 Service Fabric 叢集設定 Microsoft Entra ID 所涉及的一些步驟，我們已建立一組 Windows PowerShell 腳本。 某些動作需要 Microsoft Entra 識別子的系統管理層級存取權。 如果腳本發生 401 或 403 「Authorization_RequestDenied」錯誤，系統管理員必須執行腳本。

  1. 使用 Azure 系統管理許可權進行驗證。
  2. 將存放庫 複製到您的電腦。
  3. 請確定您已安裝文稿的所有必要條件 。

建立 Microsoft Entra 應用程式，並將使用者指派給角色

我們將使用腳本來建立兩個 Microsoft Entra 應用程式來控制叢集的存取：一個 Web 應用程式和一個原生應用程式。 建立應用程式來代表叢集之後，您將為 Service Fabric 支援的角色建立使用者：只讀和系統管理員。

SetupApplications.ps1

執行 SetupApplications.ps1 並提供租用戶標識碼、叢集名稱、Web 應用程式 URI 和 Web 應用程式回復 URL 作為參數。 使用 -remove 移除應用程式註冊。 使用 -logFile <log file path> 會產生文字記錄。 如需詳細資訊，請參閱腳本說明（help .\setupApplications.ps1 -full）。 腳本會建立 Web 和原生應用程式來代表 Service Fabric 叢集。 這兩個新應用程式註冊專案的格式如下：

  • ClusterName_Cluster
  • ClusterName_Client

注意

針對國家雲端（例如 Azure Government，由 21Vianet 運作的 Microsoft Azure），您也應該指定 -Location 參數。

參數

  • tenantId：您可以藉由執行 PowerShell 命令Get-AzureSubscription來尋找 TenantId。 執行此命令會顯示每個訂用帳戶的 TenantId。

  • clusterName：ClusterName 是用來在腳本所建立的 Microsoft Entra 應用程式前面加上前置詞。 它不需要完全符合實際的叢集名稱。 其目的只是為了讓 Microsoft Entra 成品更容易對應至其正在使用的 Service Fabric 叢集。

  • SpaApplicationReplyUrl：SpaApplicationReplyUrl 是 Microsoft Entra ID 在使用者完成登入之後傳回的預設端點。 將此端點設定為叢集的 Service Fabric Explorer 端點。 如果您要建立 Microsoft Entra 應用程式來代表現有的叢集，請確定此 URL 符合您現有的叢集端點。 如果您要為新的叢集建立應用程式，請規劃叢集的端點，並確定不要使用現有叢集的端點。 Service Fabric Explorer 端點預設為： https://<cluster_domain>:19080/Explorer/index.html

  • webApplicationUri：WebApplicationUri 是「已驗證網域」的 URI，或是使用 api 配置格式 API://{{租用戶標識符}}/{{叢集名稱}}} 的 URI。 如需詳細資訊，請參閱 單一租用戶應用程式中的AppId URI需要使用預設配置或已驗證的 網域。

    範例 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變數以供後續命令使用，並列印 Azure Resource Manager 範本所需的 JSON。 複製 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"
},

azureActiveDirectory 參數物件 JSON

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

SetupUser.ps1

SetupUser.ps1 可用來使用上述的輸出變數 $configObj，將用戶帳戶新增至新建立的應用程式註冊。 針對要設定應用程式註冊的用戶帳戶指定用戶名稱，並針對系統管理許可權指定 『is 管理員』。 如果用戶帳戶是新的，也提供新用戶的暫時密碼。 第一次登入時必須變更密碼。 如果您使用 '-remove'，您將移除使用者帳戶，而不只是應用程式註冊。

SetupUser.ps1 使用者 （read） 範例

.\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 Commandlet 'New-AzResourceGroupDeployment' 來部署範本。

SetupClusterResource.ps1 範例

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

注意

使用新的叢集資源 Microsoft Entra 組態變更來更新叢集布建 ARM 範本或腳本。

可能需要針對所設定的「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 設定

流覽至 Service Fabric Explorer （SFX） URL。 這應該與參數 spaApplicationReplyUrl 相同。 應顯示 [Azure 驗證] 對話框。 使用使用新的 Microsoft Entra 組態設定的帳戶登入。 確認系統管理員帳戶具有讀取/寫入許可權，且使用者具有讀取許可權。 對叢集所做的任何修改，例如執行動作，都是系統管理動作。

設定 Microsoft Entra 識別碼的疑難解答說明

設定 Microsoft Entra ID 並使用它可能會很困難，因此以下是一些指標，說明您可以執行哪些動作來偵錯問題。 您可以在 'SetupApplications.ps1' 和 'SetupUser.ps1' 腳本上使用 '-logFile' 自變數來啟用 PowerShell 文字記錄，以檢閱輸出。

注意

移轉身分識別平臺 （ADAL 至 MSAL），取代 AzureRM 有利於 Azure AZ，並支援多個 PowerShell 版本，相依性不一定正確或最新，導致腳本執行錯誤。 從 Azure Cloud Shell 執行 PowerShell 命令和腳本，可降低會話自動驗證和受控識別發生錯誤的可能性。

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 的特定要求上重試，預設會提供 '-timeoutMin'，預設為 5 分鐘。 您可以視需要重新執行文稿。

Service Fabric Explorer 會提示您選取憑證

問題

在 Service Fabric Explorer 中成功登入 Microsoft Entra ID 之後，瀏覽器會返回首頁，但訊息會提示您選取憑證。

SFX certificate dialog

原因

使用者未在 Microsoft Entra ID 叢集中指派角色。 因此，Service Fabric 叢集上的 Microsoft Entra 驗證失敗。 Service Fabric Explorer 會回復為憑證驗證。

方案

請遵循設定 Microsoft Entra ID 並指派使用者角色的指示。 此外，建議您開啟「存取應用程式所需的使用者指派」，如下所示 SetupApplications.ps1 。

具有 PowerShell 的 連線 失敗，並出現錯誤：「指定的認證無效」

問題

當您使用 PowerShell 使用 “AzureActiveDirectory” 安全性模式連線到叢集時，當您成功登入 Microsoft Entra ID 之後，聯機會失敗，並出現錯誤：「指定的認證無效」。

方案

此解決方案與上述解決方案相同。

當您登入時，Service Fabric Explorer 會傳回失敗：“AADSTS50011”

問題

當您嘗試在 Service Fabric Explorer 中登入 Microsoft Entra ID 時，頁面會傳回失敗：「AADSTS50011：回復位址 <URL> 不符合為應用程式設定的回覆位址： <guid>」。

SFX reply address doesn't match

原因

代表 Service Fabric Explorer 的叢集 （Web） 應用程式會嘗試根據 Microsoft Entra ID 進行驗證，並在要求中提供重新導向傳回 URL。 但是 URL 不會列在 Microsoft Entra 應用程式 REPLY URL 清單中。

方案

在叢集的 [Microsoft Entra 應用程式註冊] 頁面上，選取 [驗證]，然後在 [重新導向 URI] 區段底下，將 Service Fabric Explorer URL 新增至清單。 儲存您的變更。

Web application reply URL

透過 PowerShell 使用 Microsoft Entra 驗證對叢集進行 連線 會在您登入時發生錯誤：“AADSTS50011”

問題

當您嘗試透過PowerShell使用 Microsoft Entra ID 連線到 Service Fabric 叢集時，登入頁面會傳回失敗：「AADSTS50011：要求中指定的回復 URL 不符合為應用程式設定的回復 URL： <guid>」。

原因

與上述問題類似，PowerShell 會嘗試針對 Microsoft Entra 標識符進行驗證，以提供未列在 Microsoft Entra 應用程式 回復 URL 清單中的重新導向 URL 。

方案

使用與上述問題相同的程式，但 URL 必須設定為 urn:ietf:wg:oauth:2.0:oob，這是命令行驗證的特殊重新導向。

執行腳本會導致授權錯誤

問題

PowerShell 腳本可能無法執行完成 Microsoft Entra 設定所需的所有 REST 命令，並出現「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/Manage/Write 許可權，就會發生這種情況。

方案

請與 Azure 租使用者或 Microsoft Entra 識別碼的 管理員 istrator 合作，以完成所有剩餘的動作。 提供的腳本具有等冪性，因此可以重新執行以完成程式。

透過PowerShell使用 Microsoft Entra 驗證 連線 叢集

若要連線 Service Fabric 叢集，請使用下列 PowerShell 命令範例：

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

若要深入瞭解，請參閱 連線-ServiceFabricCluster Cmdlet。

我可以在多個叢集中重複使用相同的 Microsoft Entra 租使用者嗎？

是。 但請記得將 Service Fabric Explorer 的 URL 新增至您的叢集 （Web） 應用程式。 否則，Service Fabric Explorer 無法運作。

為什麼啟用 Microsoft Entra ID 時，我仍然需要伺服器證書？

FabricClient 和 FabricGateway 會執行相互驗證。 在 Microsoft Entra 驗證期間，Microsoft Entra 整合會將用戶端身分識別提供給伺服器，而用戶端會使用伺服器證書來驗證伺服器的身分識別。 如需 Service Fabric 憑證的詳細資訊，請參閱 X.509 憑證和 Service Fabric。

下一步

設定 Microsoft Entra 應用程式和設定使用者的角色之後， 請設定及部署叢集。