分享方式：

將單一租用戶應用程式轉換為 Microsoft Entra ID 上的多租用戶

  • 文章

如果您向許多組織提供「軟體即服務」(SaaS) 應用程式，則可以將應用程式轉換為多租用戶，以將應用程式設定為接受來自任何 Microsoft Entra 租用戶的登入。 任何 Microsoft Entra 租用戶中的使用者都能夠在同意將帳戶與您的應用程式搭配使用後，登入您的應用程式。

對於具自有帳戶系統的現有應用程式 (或有來自其他雲端提供者的其他登入)，您應該透過 OAuth2、OpenID Connect 或 SAML 新增登入程式碼，並在您的應用程式中放入 [使用 Microsoft 帳戶登入] 按鈕。

在本操作指南中，您將採取將單一租用戶應用程式轉換成 Microsoft Entra 多租用戶應用程式所需的四個步驟：

  1. 將您的應用程式註冊更新為多租用戶應用程式
  2. 更新您的程式碼，以將要求傳送給 /common 端點
  3. 更新您的程式碼以處理多個簽發者值
  4. 取得使用者和系統管理員的同意並進行適當的程式碼變更

如果您想嘗試使用我們的其中一個範例，請參閱建置使用 Microsoft Entra ID 和 OpenID Connect 呼叫 Microsoft Graph 的多租用戶 SaaS Web 應用程式

必要條件

將註冊更新成多租用戶

根據預設，Microsoft Entra ID 中的 Web 應用程式/API 註冊在建立時為單一租用戶。 若要進行多租用戶註冊，請登入 [Microsoft Entra 系統管理中心]，然後選取您要更新的應用程式註冊。 開啟應用程式註冊後，選取 [驗證] 窗格並瀏覽至 [支援的帳戶類型] 區段。 將設定變更為 [任何組織目錄中的帳戶]。

在 Microsoft Entra 系統管理中心建立單一租用戶應用程式時，[概觀] 頁面上所列的其中一個項目是 [應用程式識別碼 URI]。 這是應用程式在通訊協定訊息中識別的方式之一，可以隨時新增。 單一租用戶應用程式的應用程式識別碼 URI 在該租用戶內可以是全域唯一的。 相反，對於多租用戶應用程式，這在所有租用戶中都必須是全域唯一的識別碼，以確保 Microsoft Entra ID 可在所有租用戶中找到該應用程式。

例如，如果租用戶的名稱是 contoso.onmicrosoft.com，則有效的應用程式識別碼 URI 會是 https://contoso.onmicrosoft.com/myapp。 如果「應用程式識別碼 URI」未按照這個模式，將應用程式設定為多租用戶時就會失敗。

更新您的程式碼以將要求傳送至 /common

透過多租用戶應用程式，應用程式無法立即告知使用者來自哪個租用戶，所以無法將要求傳送至租用戶的端點。 反之，要求會傳送至為所有 Microsoft Entra 租用戶提供服務的通用端點 (https://login.microsoftonline.com/common)，作為處理要求的中央樞紐。

在 IDE 開啟您的應用程式，然後編輯程式碼，並將租使用者識別碼的值變更為 /common。 此端點不是租用戶或簽發者本身。 當 Microsoft 身分識別平台在 /common 端點收到要求時，會讓使用者登入，從而探索使用者來自哪個租用戶。 此端點可搭配 Microsoft Entra ID 支援的所有驗證通訊協定運作 (OpenID Connect、OAuth 2.0、SAML 2.0、WS-同盟)。

然後，傳給應用程式的登入回應會包含代表使用者的權杖。 權杖中的簽發者值會告知應用程式該使用者來自哪個租用戶。 從 /common 端點傳回回應時，權杖中的簽發者值會與使用者的租用戶對應。

注意

實際上，多租戶應用程式有 2 個權限：

  • https://login.microsoftonline.com/common 適用於處理任何組織目錄 (任何 Microsoft Entra 目錄) 中的帳戶以及個人 Microsoft 帳戶 (例如 Skype、XBox) 的應用程式。
  • https://login.microsoftonline.com/organizations 適用於處理任何組織目錄 (任何 Microsoft Entra 目錄) 中的帳戶的應用程式：

本文件中的說明使用 common。 但是，如果您的應用程式不支援 Microsoft 個人帳戶，則可以將其取代為 organizations。

將您的程式碼更新成可處理多個簽發者值

Web 應用程式與 Web API 會接收並驗證來自 Microsoft 身分識別平台的權杖。 原生用戶端應用程式不會驗證存取權杖，且必須將這些應用程式視為不透明。 其反而會要求並接收來自 Microsoft 身分識別平台的權杖，但這麼做是為了將權杖傳送給 API 進行驗證。

驗證權杖時，多租戶應用程式必須執行更多檢查。 多租用戶應用程式已設定為使用來自 /organizations 或 /common 金鑰 URL 的金鑰中繼資料。 除了一般檢查權杖中的 iss 宣告包含租用戶 ID (tid) 宣告之外，應用程式還必須確認 已發行中繼資料中的 issuer 屬性與權杖中的 iss 宣告相符。 如需詳細資訊，請參閱驗證權杖。

若要讓使用者登入 Microsoft Entra ID 中的應用程式，必須以使用者的租用戶代表該應用程式。 這可讓組織執行一些操作，例如在來自其租用戶的使用者登入應用程式時套用唯一原則。 對於單一租用戶應用程式，使用者可透過 [Microsoft Entra 系統管理中心] 使用註冊。

就多租用戶應用程式而言，應用程式的初始註冊程序則是在開發人員所使用的 Microsoft Entra 租用戶中進行。 在來自不同租用戶的使用者第一次登入應用程式時，Microsoft Entra ID 會要求他們同意應用程式所要求的權限。 如果他們同意，系統就會在使用者的租用戶中建立一個稱為「服務主體」的應用程式代表，然後登入便可繼續進行。 系統也會在記錄使用者對應用程式之同意意向的目錄中建立委派。 如需應用程式的 [Application 物件] 和 [ServicePrincipal 物件] 的詳細資料，請參閱應用程式物件和服務主體物件。

說明使用者同意單層式應用程式的圖表。

這個同意體驗會受到應用程式所要求的權限影響。 Microsoft 身分識別平台支援兩種權限：

  • 委派：此權限讓應用程式能夠作為登入使用者來執行該使用者可執行的一部分操作。 例如，您可以授與應用程式委派的權限來讀取登入之使用者的行事曆。
  • 僅限應用程式：此權限直接授與應用程式的身分識別。 例如，您可以將僅限應用程式的權限授與應用程式來讀取租用戶中的使用者清單，而且不論是誰登入此應用程式。

有些權限可以由一般使用者同意，有些則需要租用戶系統管理員的同意。

若要深入了解使用者與管理員同意，請參閱設定管理員同意工作流程。

僅限應用程式的權限一律需要租用戶系統管理員的同意。 如果您的應用程式要求僅限應用程式的權限，當使用者嘗試登入應用程式時，將會出現錯誤訊息，指出該使用者無法同意。

有些委派的權限也需要租用戶系統管理員的同意。 例如，若要能夠以登入使用者身分寫回 Microsoft Entra ID，就需要租用戶系統管理員的同意。 與僅限應用程式的權限一樣，如果一般使用者嘗試登入要求委派權限的應用程式，而該權限需要系統管理員同意，應用程式將會收到錯誤。 發佈資源的開發人員可以決定權限是否需要系統管理員的同意，而這項資訊也可在資源文件中找到。 Microsoft Graph API 的權限文件會指出哪些權限需要管理員同意。

若您的應用程式使用需要管理員同意的權限，請考慮新增可供管理員起始動作的按鈕或連結。 您的應用程式針對此動作傳送的要求是一個一般的 OAuth2/OpenID Connect 授權要求，其中也包含 prompt=consent 查詢字串參數。 在管理員同意且系統已在客戶的租用戶中建立服務主體之後，後續的登入要求就不再需要 prompt=consent 參數。 由於系統管理員已決定可接受要求的權限，因此從該時間點之後，就不會再提示租用戶中的任何其他使用者行使同意權。

租用戶系統管理員可以停用一般使用者對應用程式行使同意權的能力。 如果停用這項功能，就一律需要系統管理員同意，才能在租用戶中使用應用程式。 您可以在 Microsoft Entra 系統管理中心，使用已停用的使用者同意來測試應用程式。 在 [企業應用程式]>[同意和權限]中，勾選[不允許使用者同意]選項。

要求的權限不需要系統管理員同意的應用程式，也可以使用 prompt=consent 參數。 這項作業的使用時機範例如下：如果應用程式需要租用戶系統管理員「註冊」一次，之後就不會再提示其他使用者表示同意的情況。

如果應用程式需要系統管理員同意，但系統管理員登入時未傳送 prompt=consent 參數，則當系統管理員順利同意此應用程式時，只會針對其使用者帳戶套用該參數。 一般使用者將仍然無法登入此應用程式或對其行使同意權。 當您想要先讓租用戶系統管理員能夠瀏覽您的應用程式，然後才允許其他使用者存取時，這個功能相當有用。

您的應用程式可能會有多層，每一層皆由自己在 Microsoft Entra ID 中的註冊代表。 例如，一個呼叫 Web API 的原生應用程式，或是一個呼叫 Web API 的 Web 應用程式。 在這兩種情況下，用戶端 (原生應用程式或 Web 應用程式) 都會要求可呼叫資源 (Web API) 的權限。 若要讓用戶端順利獲得客戶同意新增到其租用戶中，則它要求權限的所有資源必須都已經存在於客戶的租用戶中。 如果不符合此條件，Microsoft Entra ID 會傳回錯誤，指出必須先新增資源。

單一租用戶中的多層

如果您的邏輯應用程式包含兩個或更多個應用程式註冊 (例如個別的用戶端和資源)，這可能會造成問題。 如何先將資源新增到外部租用戶？ Microsoft Entra ID 透過允許在單一步驟中同意用戶端和資源來解決這種情況。 使用者在同意頁面上會看到用戶端和資源所要求的權限總和。 若要啟用這項行為，在資源的應用程式資訊清單中，資源的應用程式註冊就必須以 knownClientApplications 的形式包含用戶端的「應用程式識別碼」。 例如：

"knownClientApplications": ["12ab34cd-56ef-78gh-90ij11kl12mn"]

這會在多租用戶應用程式範例中進行示範。 下圖為針對單一租用戶中註冊的多層應用程式表示同意的概觀。

說明同意多層式已知用戶端應用程式的圖表。

多個租用戶中的多層

如果在不同的租用戶中註冊不同的應用程式層，將會發生類似的情況。 例如，想像建置會呼叫 Exchange Online API 的原生用戶端應用程式的情況。 若要開發此原生應用程式，然後讓此原生應用程式在客戶的租用戶中執行，就必須要有 Exchange Online 服務主體。 在此情況下，開發人員和客戶必須購買 Exchange Online，如此才能在其租用戶中建立服務主體。

若是 Microsoft 以外的組織所建置的 API，則 API 的開發人員必須提供方式，使其客戶同意將應用程式新增至其客戶的租用戶中。 建議的設計是由協力廠商開發人員建置 API，使其也可作為實作註冊的 Web 用戶端。 若要這樣做：

  1. 遵循先前的章節，確保 API 實作多租用戶應用程式註冊/程式碼的需求。
  2. 除了公開 API 的範圍/角色之外，請確保註冊包含「登入及讀取使用者設定檔」權限 (依預設會提供)。
  3. 在 Web 用戶端實作登入/註冊頁面，並依照管理員同意指引操作。
  4. 當使用者同意應用程式後，就會在其租用戶中建立服務主體和同意委派連結，而原生應用程式可以取得 API 的權杖。

下圖為針對不同租用戶中註冊的多層應用程式表示同意的概觀。

說明同意多層式多方應用程式的圖表。

使用者和系統管理員可以隨時撤銷對您應用程式的同意：

  • 使用者可藉由將個別應用程式從其 [存取面板應用程式] 清單中移除，來撤銷對這些應用程式的存取權。
  • 系統管理員會使用 Microsoft Entra 系統管理中心的 [企業應用程式] 區段來移除這些應用程式，藉此撤銷其存取權。 選取應用程式並瀏覽至 [權限] 索引標籤，以撤銷存取權。

如果是由系統管理員代表租用戶中的所有使用者對應用程式行使同意權，使用者就不能個別撤銷存取權。 只有系統管理員才能撤銷存取權，並且只能針對整個應用程式撤銷。

多租用戶應用程式和快取存取權杖

多租用戶應用程式也可以取得存取權杖來呼叫受 Microsoft Entra ID 保護的 API。 使用具有多租用戶應用程式的 Microsoft Authentication Library (MSAL) 時的常見錯誤：一開始即使用 /common 為使用者要求權杖、接收回應，然後也使用 /common 為該相同使用者要求後續的權杖。 因為從 Microsoft Entra ID 傳回的回應來自租用戶而非 /common，所以 MSAL 在快取權杖時會將其視為來自租用戶。 後續為了為使用者取得存取權杖而進行的 /common 呼叫會遺漏快取項目，因此系統會再次提示使用者登入。 為了避免遺漏快取，請確定後續為已登入之使用者進行的呼叫是對租用戶的端點發出。

另請參閱