將服務主體設定檔替換為服務主體

如果您的解決方案使用服務主體設定檔(SPP),且其身分識別、治理、API 或營運限制無法滿足您的需求,本指南將協助您評估並實作以專用 Microsoft Entra 服務主體為基礎的替代方案。 如果你現有的基於設定檔的解決方案符合需求,你就可以繼續使用它。

對於選擇遷移的客戶,本指南建議在符合託管與信任要求的情況下使用受控識別與聯邦憑證。 直接服務主體身分驗證仍是另一種選擇。 這兩條路徑都提供專用的客戶身分,用於目錄治理、獨立登入監控,以及存取支援的服務,不僅限於具個人設定檔感知的介面。

Note

如果你正在建置新應用程式,建議先從 具有專用服務主體的多租用戶開始,然後依照 身份模式 和 實作指南操作。 設定檔盤點與退役階段僅適用於現有的以設定檔為基礎的應用程式。

為什麼要從個人檔案移轉

當以下限制會限制你的解決方案時,請考慮更換設定組態:

  • 設定檔設定不符合 Microsoft Entra ID 對可治理工作負載身分識別的最佳實務。 該設定檔在 Microsoft Entra ID 中沒有任何對應項目。 它不會產生獨立的登入日誌,無法承載自己的條件式存取原則,也無法由用於其餘身分識別環境的工具來管理。

例如,你無法將設定檔設定為從語意模型到湖屋或倉庫的 Direct Lake 連線 所使用的身分。 你也不能授權它作為獨立的 Microsoft Entra 身分,存取應用程式或其工作負載需要存取的其他下游服務。 專屬的服務主體可以在該服務支援此做法的情況下獲得這些權限。

你不能在 Fabric REST API 中使用設定。 設定檔案僅由具備設定檔案感知的 REST API、其 .NET SDK 以及支援的 XMLA/TOM 介面支援。 Fabric REST API 不支援設定檔,且目前沒有計畫支援。 請在進行這些 API 呼叫時使用受支援的身分識別,而不是設定檔。 建立專用的服務主體可以解決身份要求,但每個 API 和操作仍必須支援該身份並授予必要的權限。

  • 驗證仍與父身分綁定。 當父方使用秘密或憑證時,請保護並輪替該認證資料。 推薦的替換模式避免儲存客戶應用程式憑證。 設定檔也可以使用受控識別的父設定檔,因此單純無密碼驗證不需要替換設定檔。 受管理身分的上層資源不會讓設定檔擁有獨立的目錄身分或更廣泛的 API 支援。

設定檔解決的是尺度問題,而非獨立身分問題。 一個父服務主體最多可建立 100,000 個設定檔,每個設定檔最多可存取或建立 1,000 個工作空間。 在此模型中,服務主體最多可屬於 1,000 個工作空間。 專用的客戶身分則改為使用 Microsoft Entra 目錄物件。 在決定遷移前,先根據你的客戶數量核對適用的限制。

Note

安全邊界: 設定檔並非加密編譯安全邊界:其父服務主體可透過其任一設定檔行動。 推薦的模式也允許執行階段受控識別以任何信任它的客戶應用程式身分進行驗證。 工作區與資源權限仍是強制授權邊界。 保護任一模型中的執行階段及客戶到身分對應。

其他需要考慮的設定檔限制

Limitation 移轉影響
沒有獨立的審計或政策身分 設定檔沒有獨立的 Microsoft Entra 登入記錄或工作負載身份條件存取目標。 專用服務主體提供這些功能,但須符合原則資格和授權條件。
永久的設定檔與父項目耦合 個人檔案不能轉移給另一個父服務主體。 取代父系統需要新的設定檔、新的工作空間授權,以及更新的客戶映射。
沒有身分管理入口網站 設定檔僅支援 API,且不在 Microsoft Entra 管理工具中呈現。 專用應用程式與服務主體則具備目錄可視性與管理介面。

管理身份與聯邦憑證模式

此模式可用於新的專用主體身分解決方案,或在選擇替換設定檔時使用,前提是你的執行時符合受控識別的託管需求。

模式

給每位客戶一個真實的 Microsoft Entra 服務主體身分,並以應用程式的受控識別作為斷言來源。 此方法取代了共享應用程式憑證與設定檔抽象。 你可以記錄、管理並將每個客戶身分納入適用於工作負載身分的條件式存取,並且可以呼叫支援的 Fabric REST API。

此方法是推薦的遷移路徑,因其 Azure 託管與信任需求符合解決方案。 它移除了儲存的客戶應用程式憑證及其輪替流程,卻不改變工作區與資源授權的強制執行位置。

該架構顯示應用程式的執行時操作、三個客戶應用程式身分以及信任關係,以及一對一的客戶工作空間關係。 它代表預設的共享執行時安排,而非新的隔離邊界。

圖示顯示 ISV 應用程式取得受控識別權杖,將其交換為所選客戶應用程式權杖,並呼叫目標 API。個別的客戶 A、B 和 C 服務主體對應用程式受控識別具有同盟信任,且只能存取各自對應的客戶工作區。

圖 1. 一個應用程式受控識別會以專用的客戶服務主體身分進行驗證。

運作原理

  1. 應用程式受控識別。 將使用者指派的受控識別指派給在受支援的 Azure 計算服務上執行的 ISV 應用程式,例如 App Service、容器應用程式、適當設定的 AKS 工作負載或虛擬機器。 應用程式應該使用一個受控識別,而不是每個客戶各用一個。 它沒有自己的客戶工作空間或目標服務權限;它在這裡的角色只是提供一個聲明。

  2. 每個客戶、使用者或群組的服務主體。 對於每個現有的客戶或授權邊界,在 ISV 的目錄租戶中建立一個 Microsoft Entra 應用程式註冊與服務主體。 邏輯客戶不一定代表有獨立的 Microsoft Entra 租戶,且除非現有的存取設計要求,否則不需要為每位終端使用者建立個別身分。

  3. 同盟識別認證。 在每個客戶應用程式註冊項目上設定聯邦身分識別憑證,以信任該應用程式的受控識別。 執行階段可利用其受控識別權杖作為判斷提示,取得該客戶的應用程式的存取權杖,無需用戶端密碼或憑證。

  4. 執行階段權杖交換。 當使用者 A 或特定客戶的工作呼叫應用程式時,透過受信任的伺服器端映射來解析客戶 A。 取得受眾為 api://AzureADTokenExchange 的受控身分識別權杖;以 SP-A 交換存取權杖;然後使用 SP-A 的權杖呼叫目標 API,管理工作區、執行資源操作,或在需要時要求特定應用程式的權杖。

    在前一步的交換中,.NET Azure Identity ClientAssertionCredential 會接受受控識別權杖作為客戶端聲明。 這是 Azure Identity 的憑證類型,不是 MSAL 類別。 存取權杖必須針對資源 API 的受眾,而非代幣交換受眾。

  5. 工作空間的存取權。 僅在需要這些角色時,授與每個服務主體成員或管理員其指定工作區的存取權限,或授與執行所需作業時可用的最低權限支援角色。 該授權界定了資源存取範圍。 由於應用程式的託管身分可以以每個信任它的客戶應用程式身分進行驗證,因此應將它及其運算主機視為高價值的身分與基礎設施。

  • 較少長期有效的憑證。 你不需要儲存、檢索或分發任何客戶應用程式的應用程式密碼或憑證私密金鑰提供給執行階段。

  • 旋轉相關工作較少。 Azure 管理受控識別憑證並發行短效權杖。 你不需要為每個使用此信任的客戶應用程式設置獨立的秘密或憑證續期流程。

  • 一致的新手引導。 配置客戶應用程式與服務主體,定義明確信任,並授予客戶資源存取權限。 新客戶不需要新的長效憑證。

這些好處並不免除信任管理、客戶授權、審核監控或目錄容量規劃的需求。

替代方案:直接服務主體認證

如果你不想使用受控識別和同盟認證,則可以建立相同的專用客戶應用程式註冊和服務主體物件,但改為直接使用憑證或其他支援的應用程式認證來驗證。 在支援的情況下,優先使用憑證而非用戶端秘密。 保護私鑰與秘密,限制對其的存取,並自動化輪替。

直接認證保留目錄可見性、依主體區分的登入記錄,以及對支援的 API 的存取權。 它不需要受控識別代管或信任關係,但也不會消除儲存的客戶憑證。

關鍵概念

區分建立信任的憑證與執行時使用的權杖。

聯邦身份憑證

在作為客戶服務服務主體後端的 Microsoft Entra 應用程式註冊上設定聯邦身分識別憑證(FIC)。 它定義了與代幣發行者的信任關係,並指定應用程式接受哪一種斷言,而非用戶端秘密或憑證。

在此架構中,目標身分是客戶應用程式與服務主體;應用程式受控識別是判斷提示來源。 這就是為什麼你應該在應用程式註冊上設定用戶端認證,而不是在服務主體物件或來源受控識別上。

Note

配置區分: 在其他同盟情境中,使用者指派的受控識別也支援同盟識別憑證。 這並不會改變這裡的做法:在每個客戶應用程式註冊時設定信任。 本指南所述的應用程式信任架構中,僅支援使用者指派的受控識別作為受控識別判斷提示來源。

信任欄位 全球雲端的價值
Issuer https://login.microsoftonline.com/{directory-tenant-id}/v2.0
主旨 使用者指派的管理身份的主體(物件)ID。 不要使用用戶端 ID。
觀眾 api://AzureADTokenExchange

當應用程式呈現受管理身分識別權杖並請求客戶應用程式的存取權杖時,Microsoft Entra ID 會根據聯邦憑證驗證該斷言。 發行者、主題與受眾必須相符。 若驗證成功,會發出代表目標客戶服務主體、用於所要求資源的存取權杖。

受控識別與信任應用程式註冊必須位於同一個 Microsoft Entra 租用戶中。 資源受眾與斷言受眾是分開的選擇。 對於 Azure Identity,全球雲端權杖交換範圍為 api://AzureADTokenExchange/.default;目標 API 範圍通常是資源識別碼後接 /.default。

令牌交換流程:使用聯邦斷言的用戶端憑證

這個流程包含三位參與者和六個步驟。 SP-A 是客戶 A 的應用程式與服務主體。 管理身份斷言令牌與回傳的 SP-A 資源存取令牌具有不同的功能。

序列圖顯示 Azure 應用程式請求與接收受控識別權杖,傳送用戶端認證要求,其中包含 SP-A 的用戶端 ID,並將受控識別權杖作為判斷提示,Microsoft Entra ID 驗證聯邦信任,回傳 SP-A 的存取權杖,以及應用程式以 SP-A 呼叫目標 API 的過程。

圖 2. 由受控識別聲明支援的用戶端憑證權杖交換。

  1. 請求受控識別權杖。 Azure 上的應用程式會請求一個帶有 audience api://AzureADTokenExchange 的受控識別權杖。

  2. 回傳 assertion 權杖。 Microsoft Entra ID 會發出受控識別權杖,該應用程式透過其 Azure 主機環境的受控識別機制接收該權杖。

  3. 提交客戶權杖請求。 向目錄租戶/oauth2/v2.0/token的端點發送請求,包含 grant_type=client_credentials、client_id=<SP-A-client-id>、client_assertion=<MI-token> 和 scope=<target-resource>/.default。 完整的 OAuth 請求也會提供 client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer;身分識別程式庫會處理此參數。

  4. 驗證此斷言。 Microsoft Entra ID 會驗證受控識別權杖是否符合 SP-A 應用程式註冊上的聯邦憑證。

  5. 傳回客戶存取權杖。 Microsoft Entra ID 會以目標資源為受眾,回傳給 SP-A 一個存取權杖。

  6. 呼叫目標的 REST API。 應用程式會將 SP-A 的存取權杖傳送到目標 API。 它不會將斷言權杖作為資源持有人權杖,也不會選擇設定檔。

架構比較

替代資料行通常涵蓋專責服務主體。 託管身份與聯邦是推薦的認證方式,但也可以使用直接憑證或其他支援的憑證認證。

層面 服務主體描述檔 專用服務主體
每位客戶一個身分 邏輯設定檔,不是 Microsoft Entra 物件。 應用程式註冊與服務主體身分代表客戶授權邊界。
強制執行的邊界 工作空間和資源權限。 工作空間和資源權限。
根身分可及範圍 父服務主體可以以其任一設定檔的身分運作。 執行階段可使用其擁有憑證或受信任斷言的所有身分;MI 可以以任何信任它的應用程式身分進行驗證。
秘密輪換 當父方使用密碼或憑證時,必須如此。 受控識別憑證並非必要條件;對於直接路徑上的儲存憑證或用戶端秘密,則為必要條件。
縮放上限 每個父 SP 最多可有 100,000 個設定檔;每個設定檔最多可支援 1,000 個工作區。 母 SP 本身的成員資格僅限於 1,000 個工作區。 每個客戶有應用程式註冊與服務主體,並受目錄物件配額及每個目標服務資源限制限制。
稽核線索 設定資料 ID 可能會出現在資源日誌中,但這些設定資料不會有獨立的 Microsoft Entra 登入記錄。 Microsoft Entra 以服務主體為準,並與應用程式及資源稽核日誌相互關聯的登入紀錄。
條件式存取 沒有每個設定檔的工作負載身分原則。 適用於具備 Microsoft Entra 工作負載 ID Premium 的合格服務主體;原則必須直接針對每個主體。
入口網站可見性 未在 Microsoft Entra ID 中呈現。 應用程式註冊 中的應用程式註冊;Enterprise applications 中的服務主體名稱。
Fabric REST API 支援 不支援;目前沒有支援計畫。 在特定 API 與操作接受服務主體,且具備必要權限的情況下,才支援。
憑證轉移與父項耦合 個人檔案不能在父服務主體之間轉移。 聯邦信任可以重新配置;直接憑證可以被替換,而無需重新建立設定檔的抽象層。

如何閱讀此表:這兩種安排都無法提供客戶的加密隔離。 資源授與會強制執行存取控制,執行階段可能可跨客戶間接觸及。 個人檔案提供輕量級的身分擴展。 專用的主體識別能提升目錄治理、登入可見性及 API 相容性。 建議的受控識別與同盟路徑也會移除已儲存的客戶應用程式憑證。

遷移路徑

以下路徑將以專屬客戶服務主體取代個人檔案。 讓遷移與回滾決策分別針對每位客戶。

從設定檔到受控識別與聯邦憑證

使用以下遷移階段,搭配小型試點群組及按客戶控制推出的切換。 在驗證及約定回滾期結束前,保持設定檔路由可用。

階段 0:建立應用程式受控識別

  • 建立使用者指派的受控識別給應用程式,並將其指派給運算資源。 實作指南展示了建立與指派指令。

  • 記錄其安全性主體(物件)ID。 每個客戶應用程式的聯邦憑證都以此值作為主體。 同時記錄客戶端 ID、目錄租戶 ID 和 Azure 資源 ID。

應用程式應該使用一個受控識別,而不是每個客戶各用一個。 在此模式中,每個客戶不需要獨立的 MI:客戶識別身分是服務主體,而 MI 提供斷言。 對於較大的部署或較小的受損範圍,將客戶劃分為少數幾個執行時身分,每個身分只被其指定的客戶應用程式子集信任。

第一階段:盤點

透過 設定檔管理 API 列出所有現有設定檔:

GET {profile-api-base}/v1.0/myorg/profiles

每個設定檔請記錄:

  • 設定檔 ID 與顯示名稱、父服務主體,以及客戶對應。

  • 相關的工作空間與角色分配。

  • 相關的語意模型或資料集、報告及其他資源。

  • 連線、資料來源憑證、所有權相依性、背景工作,以及依賴此設定檔的 API 作業。

在更改客戶的設定前,請記錄現有的工作區角色、語意模型所有權、連線身分、憑證設定,以及回滾所需的客戶與設定檔對應。 記錄的是對憑證的安全參考,而非秘密值。

記錄客戶數量,並在繼續前將所需的應用程式物件和服務主體物件與你的 Microsoft Entra 目錄物件配額做比較。 同時驗證 1,000 個工作空間的成員數量上限以及任何資源特定的限制。 若數量超過單一目錄的配額,則計畫增加支援的配額或刻意管理多目錄設計;這個模式不會自動解決此問題。

Note

端點符號:{profile-api-base} 表示您的解決方案已使用的現有 PROFILE 感知 REST API 基底網址。 請保留該網址在你的部署設定中。 這些範例保留了操作路徑;執行前先替換所有佔位符。 「設定檔感知」一詞描述的是 API 支援,而非棄用狀態。

第二階段:佈建新身分

對於每個設定檔,或屬於同一客戶授權邊界的設定檔群組:

  1. 建立應用程式註冊與服務主體。 分別記錄應用程式客戶端 ID、應用程式物件 ID 及服務主體物件 ID。

  2. 在客戶應用程式註冊上設定一個聯邦身分識別憑證,該憑證信任在 Phase 0 建立的應用程式 MI。

  3. 授權新的服務主體存取相同的客戶工作空間和資源。 在盤點操作需要時使用 Member,或是權限最低的受支援角色。 只有必要時才授予管理員權限。

只要支援就保留現有的工作區和資源 ID。 工作空間授予不會自動轉移資源所有權、連線身分或資料來源憑證。 在轉換作業前完成這些特定服務的更新。

第三階段:更新應用程式碼

  • 將設定檔選擇標頭與 SDK 設定檔設定配置替換為受管理身分識別支援、用於所選客戶應用程式的權杖交換。

  • 更新應用程式資料庫中的客戶與身份對應。

之前 之後
customerId -> profileId 共用一個 SP 憑證和一個設定檔標頭資訊。 customerId -> spClientId 透過管理身份憑證交換實現每位客戶的 SP 認證。 同時保留目錄租戶 ID、認證設定及允許的資源 ID。

客戶 ID 是 ISV 客戶的邏輯識別碼,不一定是 Microsoft Entra 租戶 ID。 在選擇身分前,先驗證已驗證身分之使用者的客戶會員資格。 按目錄租戶、用戶端 ID 及資源或範圍為權杖快取建立索引。

  • 更新應用程式專用的令牌產生,以使用客戶服務主體存取權杖。 如果你的解決方案嵌入了報告或其他內容,也要更新該代幣產生;嵌入是現有的遷移工作負載,並非本指南的前提。

  • 更新工作區管理、下游連線、配置、排程工作,以及所有其他使用舊的設定檔設定的入口點。

第四階段:驗證

對每位客戶,請驗證:

  • 工作空間與資源存取透過新的服務主體成功實現。

  • 管理身分識別權杖取得與同盟權杖交換對預期的客戶應用程式成功。

  • 應用程式專用的代幣在使用時能成功產生,現有報告或其他嵌入內容在適用時也能正確呈現。

  • 新的服務主體登入會出現在 Microsoft Entra ID 中,並可與應用程式及資源稽核日誌相關聯。

  • 跨客戶存取被拒絕:呼叫者無法選擇其他客戶的應用程式識別碼或資源 ID。

在生產切換前,為試點客戶記錄並測試回滾程序。 包含恢復遷移過程中更改的任何語意模型所有權、連線身份、資料來源憑證及權限。 確認先前設定檔在回滾後能執行所需操作,包括刷新設定與參數更新。

只有在通過審核標準後,才可切換客戶的應用程式路由。 在擴展部署前,監控故障、效能及權限。

若驗證失敗,請暫停受影響的背景工作,並依照各服務支援的程序恢復先前設定。 僅將應用程式路由切換回個人資料,可能無法恢復依賴擁有權或憑證的操作。 恢復所需設定後,切回基於設定檔的路由,並在恢復工作前驗證資源存取與相依操作。 在回滾期間保留原始設定及所需權限。

第五階段:除役設定檔

  • 回滾期結束後,確認專屬客戶服務主體擁有所需權限後,移除過時的原始父項和設定檔工作空間授權。

透過設定檔管理 API 刪除每個遷移的設定檔:

DELETE {profile-api-base}/v1.0/myorg/profiles/{profileId}
  • 如果沒有客戶、作業或無關工作負載仍在使用,則可選擇性地刪除原本的共享應用程式註冊與服務主體。 依照保留需求,停用過時的憑證並保留遷移映射與稽核紀錄。

Note

不使用受控識別或聯邦識別的替代移轉方式: 建議使用受控識別與聯邦憑證,但非強制。 如果你不想用,就省略 Phase 0。 在第二階段,為每個客戶應用程式設定證書或其他支援的憑證,而不是使用聯邦憑證。 在第三階段和第四階段,直接以該應用程式的身分取得並驗證存取權杖。 維持相同的資產清單、資源授權、客戶授權、部署與退役步驟,並安全管理憑證儲存與輪換。

實作指南

本指南實作建議的受控識別與聯邦憑證路徑。 直接驗證替代方案遵循相同的身份與權限設定,並在主要步驟後說明。 Azure CLI 範例使用 Bash 語法;請先替換佔位符,並登入預定的租用戶與訂用帳戶,再執行這些範例。

Prerequisites

  • 一個 Azure 訂閱,以及為建議做法建立及指派受控識別的權限。

  • Microsoft Entra ID 中建立應用程式註冊與服務主體,以及更新應用程式憑證的權限。 Azure 資源權限和目錄權限是分開的。

  • 託管於支援的 Azure 運算系統上的應用程式,如 App Service、容器應用程式、適當配置的 AKS 工作負載或虛擬機器。 此模式中,由 MI 支撐的斷言來源依賴於該 Azure 主機配置。

  • 管理權限,可授予客戶工作空間與資源存取權、設定所需服務設定,以及在目標服務需要時授予 API 權限或提供同意。

  • 已安裝 Azure CLI,並已登入正確的目錄租用戶。 在建立 Azure 資源前,請先確認訂閱上下文。

開發者租戶設定

請在服務的管理介面中,於租戶設定和開發者設定下檢視相關設定。 將服務主體的存取權限限定於包含客戶服務主體的允許安全性群組。 關於具體標籤和目前行為,請參見 開發人員租用戶設定。

針對您的解決方案所需的每個群組範圍設定,在測試或切換前,將所有替代的服務主體加入允許的安全性群組。 授予原始母服務主體的存取權,並不會自動授權替代的服務主體。 公開 API 存取設定同時適用於現有的 profile-aware REST API 與 Fabric REST API;僅遷移身份並不會移除此先決條件。

以下公開 API 設定使用產品中立標籤;管理介面可能會包含服務名稱。

Setting 已發佈的預設值 在下列情況下為必填
服務主體可以呼叫公開 API 已為新客戶啟用。 客戶服務主體身分會呼叫現有的設定檔感知 REST API 或 Fabric REST API。 當設定為群組範圍時,將每個替換主體納入允許的安全群組中。
服務主體可以建立工作區、連線和部署管線 已對新客戶停用。 應用程式會佈建這些資源。
在應用程式中內嵌內容 可在現有配置中啟用;確認你的租用戶。 你現有的應用程式會透過適用的 REST API 嵌入內容。
允許服務主體建立及使用設定檔 不要假設有預設值。 只有在客戶仍使用設定檔路徑時,遷移的客戶則不需。

驗證實際數值,而不是假設預設值。 新舊租戶可能有所不同,管理員也可以更改設定。 設定檔設定一直維持,直到所有相依客戶和作業都遷移。 不要為非嵌入工作負載啟用嵌入設定。

步驟 1:建立並指派使用者指派的受控識別

此管理身份代表的是 ISV 應用程式,而非個別客戶。 使用現有的資源群組:

az identity create \
  --name "mi-customer-app" \
  --resource-group "<resource-group>" \
  --location "<azure-region>"

記錄它的客戶端 ID、主體(物件)ID、目錄租戶 ID 和 Azure 資源 ID。 把它指派給運算資源。 針對現有的 App Service 應用程式:

az webapp identity assign \
  --resource-group "<resource-group>" \
  --name "<web-app-name>" \
  --identities "<managed-identity-resource-id>"

其他計算服務則使用相應的身分指派程序。 在執行時明確選擇這個使用者指派的身份。 由於身份獨立於主機資源,重新部署主機不必取代所有客戶的信任關係。

步驟二:為每位客戶建立服務主體名稱

對於現有設定檔所代表的每個客戶、使用者或群組邊界,建立一個應用程式註冊及其服務主體。 此範例在 ISV 目錄中建立一個單租戶應用程式:

APP_CLIENT_ID=$(az ad app create \
  --display-name "customer-a-application" \
  --sign-in-audience AzureADMyOrg \
  --query appId --output tsv)

az ad sp create --id "$APP_CLIENT_ID"

APP_OBJECT_ID=$(az ad app show \
  --id "$APP_CLIENT_ID" --query id --output tsv)

SP_OBJECT_ID=$(az ad sp show \
  --id "$APP_CLIENT_ID" --query id --output tsv)
識別碼 使用
應用程式客戶端識別碼 申請存取權杖時,請識別客戶應用程式。
應用程式物件識別碼 在應用程式註冊中設定聯邦憑證。
服務主體物件識別碼 當 API 需要主體物件 ID 時,授予工作空間或資源角色。

Note

建議路徑的認證資訊: 不要為此驗證路徑建立用戶端密碼或憑證。 客戶應用程式的聯邦信任提供認證機制。

步驟 3:設定聯邦身份憑證

取得受控識別主體識別碼及其目錄租用戶 ID。 使用該身分識別的租用戶,而不是假設另一個目前的訂用帳戶具有相同的租用戶:

MI_PRINCIPAL_ID=$(az identity show \
  --name "mi-customer-app" \
  --resource-group "<resource-group>" \
  --query principalId --output tsv)

DIRECTORY_TENANT_ID=$(az identity show \
  --name "mi-customer-app" \
  --resource-group "<resource-group>" \
  --query tenantId --output tsv)

在每個客戶應用程式註冊中加入聯邦身分識別憑證。 以下 global-cloud 指令使用 Step 2 的應用程式物件 ID 及剛取得的 MI 值:

az ad app federated-credential create \
  --id "$APP_OBJECT_ID" \
  --parameters "{
    \"name\": \"trust-application-mi\",
    \"issuer\": \"https://login.microsoftonline.com/$DIRECTORY_TENANT_ID/v2.0\",
    \"subject\": \"$MI_PRINCIPAL_ID\",
    \"audiences\": [\"api://AzureADTokenExchange\"],
    \"description\": \"Trust the ISV application managed identity\"
  }"

或者,將含有替換後值的相同 JSON 儲存到本機 credential.json 檔案,然後傳遞 --parameters credential.json。 對每個客戶申請重新套用 trust。 在驗證權杖交換前,先等待設定傳播完成。

步驟 4:授予每個服務主體工作空間存取權

在需要該角色時,僅將客戶服務主體以成員或管理員身分新增至其指定的工作區。 如果符合操作需求,偏好較低層級的受支援角色。 這項授權實際上是決定客戶資源存取範圍的部分。

請使用工作區管理介面或工作區角色指派 REST 作業。 以下範例使用可配置的 API 與資源識別碼。 它需要授權的配置識別碼;執行時的 MI 本身並未獲得用於權杖交換的客戶資源權限。

PROFILE_API_BASE="<existing-profile-aware-api-base-url>"
PROFILE_RESOURCE="<existing-api-resource-identifier>"
WORKSPACE_ID="<customer-workspace-id>"

TOKEN=$(az account get-access-token \
  --resource "$PROFILE_RESOURCE" \
  --query accessToken --output tsv)

curl --fail-with-body --request POST \
  "$PROFILE_API_BASE/v1.0/myorg/groups/$WORKSPACE_ID/users" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data "{
    \"identifier\": \"$SP_OBJECT_ID\",
    \"groupUserAccessRight\": \"Member\",
    \"principalType\": \"App\"
  }"

使用擁有現有工作空間之服務所記錄的端點和請求格式。 顯示的操作適用於設定檔感知的工作空間 API;其他 API 可能會使用不同的角色指派架構。 不要在操作預期使用服務主體物件 ID 的地方改用客戶端 ID。 避免記錄 Bearer Token,並允許權限傳播。

步驟 5:執行時驗證並呼叫 API

  1. 從可信的伺服器端設定中解析已驗證客戶的應用程式客戶端 ID 及允許的資源。

  2. 利用選取的使用者指派受控識別及全球雲端中的 api://AzureADTokenExchange/.default 範圍,取得斷言權杖。

  3. 將 MI 權杖作為客戶租用戶應用程式的用戶端聲明。 請求一個存取權杖,使用資源 API 的應用程式範圍,而非斷言受眾。

  4. 使用該客戶應用程式存取權杖呼叫目標 API,且不進行設定檔選取設定。 管理工作區、申請任何所需的應用程式特定權杖,並透過客戶身分識別執行其他已列出的作業。

對於 .NET,使用 Azure Identity ClientAssertionCredential,並以受控識別權杖作為其判斷提示回呼。 六步驟流程與官方配置範例展示了交換流程,且不需嵌入專用的應用程式程式碼範例。

自動化入職與離職

在您的佈建流程中納入這四個佈建步驟:建立應用程式註冊、建立其服務主體、設定其聯邦信任,以及授予工作區角色。 同時建立對應的停用流程:移除資源存取授與、撤銷過時的信任或憑證,並在檢查相依關係後刪除應用程式身分。

替代實作方式:直接驗證服務主體身分

如果你不想使用 MI 和 federation,可以跳過步驟 1 和 3。 為每位客戶完成第 2 步,並設定支援的應用程式憑證,而非使用聯邦信任。

在支援的地方使用憑證,並依照 應用程式憑證設定指引操作。 上傳公開憑證,將私鑰保護在適當的憑證儲存庫中,並將續期流程自動化。 如果需要用戶端密鑰,請保護它並在到期前續期。

完成第四步,使用相同的最低權限客戶權限授予。 在第 5 步,使用客戶客戶端 ID 及其憑證直接請求客戶端憑證存取權杖。 保持相同的客戶路由、令牌快取分離、驗證和遷移清理控制。

安全性、限制與考量

對你選擇的認證路徑套用以下控制措施,並規劃其運作限制。

安全性建議

  • 使用穩定的使用者指派的受控識別。 這避免了僅因更換運算資源而失去客戶信任關係。 請勿使用系統指派的身分識別作為此應用程式信任模式的斷言來源。

  • 將應用程式 MI 視為高度特權的身分識別。 它可以以每個信任它的客戶應用程式身分進行驗證。 限制運算部署權限、受控識別指派、應用程式擁有者及憑證管理。 如有需要,可分割執行時身分以減少受損範圍。

  • 不要給 MI 任何其自身的客服權限。 這是一個宣告來源;客戶服務主管則獲得工作空間及下游服務授權。

  • 使用安全性群組限定租用戶設定的適用範圍。 將每個相關的客戶的服務主體納入允許的群組,而不是讓整個組織都啟用服務主體存取權限。

  • 監視並對每個服務主體的登入發出警示。 與應用程式和資源記錄建立關聯。 沒有針對客戶的調查與警示就收集日誌,無法帶來營運上的效益。

  • 同時將入職與離職流程自動化。 移除工作區角色、淘汰憑證或信任關係,以及刪除過時的服務主體,必須像配置這些項目一樣受控且可重複。

將客戶映射保留在伺服器端,在選擇身份前驗證成員資格,並拒絕任意客戶端提供的身份或資源 ID。 權杖重用意味著一個登入記錄不代表每個 API 呼叫的紀錄。 不要記錄秘密、斷言、存取權杖或憑證私鑰。

限制與操作需求

考慮事項 需要規劃的事項
縮放上限與設定檔的比較 設定檔允許每個父服務主體 100,000 個設定檔,每個設定檔最多可支援 1,000 個工作空間。 專用的應用程式註冊與服務主體會消耗目錄物件。 在提交前,請檢查目錄配額、服務主體工作空間限制及佈建吞吐量。
聯邦認證限制 應用程式註冊最多支援 20 個聯邦身分識別憑證。 通常此架構需要在每個客戶應用程式上,為每個受信任執行階段受控識別各一個,而不是在共用應用程式上為每個客戶各一個。
同租戶要求 受控識別與每個信任應用程式註冊必須屬於同一個 Microsoft Entra 租用戶。 存取其他租戶的資源還需要支援的應用程式設定、同意授權及資源權限。
無跨雲端權杖交換 請勿在不同 Azure 雲端間交換代幣,例如全球雲端與美國政府雲端。 在目標雲端中使用正確的受眾與授權端點。
Azure 運算需求 由受管理身分作為後盾的斷言流程需要受支援 Azure 主機環境的受管理身分機制。 如果應用程式在其他地方執行,或你不想使用此模式,請使用直接驗證的替代方案或其他支援的聯盟設計。
條件式存取 建立或修改工作負載身份條件存取政策時,必須使用 Microsoft Entra 工作負載 ID Premium。 原則涵蓋符合資格的組織擁有單一租用戶服務主體,且必須直接針對這些主體。 它們不涵蓋受控識別,也不會僅透過群組成員資格生效。
開發者租戶設定 每個使用群組範圍設定的客戶服務主體都必須在其允許的安全群組中。 檢視實施前提條件中的四個設定;不要假設預設。
Automation 手動管理數百甚至數千個客戶身份是不切實際的。 自動化佈建、授權變更、監控、輪替或信任更新,以及停用。 用有界重試和退避來處理節流。
僅限委派的體驗仍不在範圍內 當工作負載需要委派的使用者權杖時,替換設定檔並不會啟用僅限應用程式驗證。 在 Real-Time 儀表板嵌入預覽中,僅支援該項目類型及委派的使用者認證;不支援 app-only 和 app-owns-data 權杖。 現有的報告嵌入則採用其適用的服務專屬機制。

在最終確定容量與權限前,請參考 Microsoft Entra 的服務限制及目標服務的 API 身份支援。

關於目前的信任限制與傳播行為,請參見 聯邦身份憑證的考量。

有關現行原則資格與授權,請參閱 工作負載身分識別的條件式存取。

可依情況使用全球雲端權杖交換對象 api://AzureADTokenExchange、美國政府對象 api://AzureADTokenExchangeUSGov或中國對象 api://AzureADTokenExchangeChina。 將授權端點與雲端匹配。 本文中的範例使用了全域雲端。

使用支援的身分識別程式庫來進行權杖快取與重新整理。 允許信任與權限傳播,以有限退避方式重試暫時性失敗,並調查持續存在的發行者、主體或受眾不匹配。 為了直接認證,請輪換有重疊期的憑證與祕密值,並監控過期情況。

不要以為刪除個人檔案、移除憑證或更改信任就能立刻使先前發出的代幣失效。 在規劃切換與停用時,考慮代幣壽命及每個資源服務的授權與撤銷行為。

利用這些參考資料查閱 API 專屬權限、目前的身分限制及現有工作負載設定。

配置檔、服務主體與現有工作負載

工作負載身分同盟與受控識別

SDK、API 與服務限制