設定 Microsoft Entra ID 以進行用戶端驗證

發行項
11/14/2024

警告

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

針對在 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 ID 的叢集上的應用程式和節點。

注意

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

注意

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

必要條件

在本文中，我們假設您已經建立租用戶。如果您尚未取得 Microsoft Entra 租用戶，請先閱讀如何取得 Microsoft Entra 租用戶。為了簡化與設定 Microsoft Entra ID 搭配 Service Fabric 叢集相關的一些步驟，我們建立了一組 Windows PowerShell 指令碼。某些動作需要 Microsoft Entra ID 的系統管理層級存取權。如果指令碼發生 401 或 403「Authorization_RequestDenied」錯誤，系統管理員就必須執行指令碼。

使用 Azure 系統管理權限進行驗證。
將存放庫複製到您的電腦。
確定您已安裝指令碼的所有必要條件。

建立 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://{{tenant Id}}/{{cluster name}} 的 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 輸出變數，將使用者帳戶新增至新建立的應用程式註冊。針對要設定應用程式註冊的使用者帳戶指定使用者名稱，並針對系統管理許可權指定 '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 Commandlet 'New-AzResourceGroupDeployment' 來部署範本。

SetupClusterResource.ps1 範例

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

注意

使用新的叢集資源 Microsoft Entra 組態變更來更新叢集佈建 ARM 範本或指令碼。

可能需要為所設定的「API 許可權」授與管理員同意。瀏覽至 Azure 應用程式註冊刀鋒視窗，並將叢集名稱新增至篩選。針對這兩個註冊，如果可行的話，請開啟 [API 許可權]，然後選取 [授與管理員同意]。

螢幕擷取畫面：顯示授與管理員同意的確認，並醒目醒目顯示 [是]。

驗證 Microsoft Entra 設定

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

針對設定 Microsoft Entra ID 的疑難排解說明

設定 Microsoft Entra ID 並加以使用並不容易，因此以下提供一些指標，供您對問題進行偵錯。您可以使用 'SetupApplications.ps1' 上的 '-logFile' 引數和 'SetupUser.ps1' 指令碼來檢閱輸出，藉此啟用 PowerShell 文字記錄。

注意

移轉身分識別平台 (ADAL 移轉至 MSAL)、淘汰 AzureRM 而改用 Azure AZ，以及支援多個版本的 PowerShell 時，相依性不一定是正確或最新的，可能導致執行指令碼時發生錯誤。從 Azure Cloud Shell 執行 PowerShell 命令和指令碼，可減少工作階段自動驗證和受控識別發生錯誤的可能性。

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 憑證對話方塊

原因

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

方案

請依照設定 Microsoft Entra ID 的指示進行操作，然後指派使用者角色。另外，建議您如 SetupApplications.ps1 所做的一樣，開啟 [存取應用程式需要使用者指派]。

使用 PowerShell 進行連線時失敗，發生錯誤：「指定的認證無效」

問題

在您順利登入 Microsoft Entra ID 之後，於使用 PowerShell 以 “AzureActiveDirectory” 安全性模式連接到叢集時連線失敗，發生錯誤：「指定的認證無效」。

方案

此解決方案與前一個相同。

問題

當您嘗試在 Service Fabric Explorer 中登入 Microsoft Entra ID 時，頁面傳回失敗：「AADSTS50011：回覆地址 <url> 與針對應用程式設定的回覆地址不符：<guid>」。

SFX 回覆地址不相符

原因

代表 Service Fabric Explorer 的叢集 (Web) 應用程式嘗試對照 Microsoft Entra ID 來進行驗證，而它在要求中提供重新導向傳回 URL。但該 URL 並未列在 Microsoft Entra 應用程式 [回覆 URL] 清單中。

方案

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

Web 應用程式回覆 URL

問題

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

原因

類似於先前的問題，PowerShell 會嘗試針對 Microsoft Entra ID 進行驗證，這會提供未在 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 呼叫的許可權時，就會傳回此錯誤。如果使用者沒有建立或修改物件的系統管理員/管理/寫入權限，就會發生此情況。

方案

請與 Azure 租用戶或 Microsoft Entra ID 的系統管理員合作，以完成所有剩餘的動作。提供的指令碼是等冪的，因此可以重新執行以完成流程。

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

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

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

若要深入了解，請參閱 Connect-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 應用程式並為使用者設定角色之後，請設定和部署叢集。

共用方式為