應用程式設定選項

發行項
07/01/2024

若要驗證和取得權杖，您必須在程式碼中初始化新的公用或機密用戶端應用程式。當您在 Microsoft 驗證程式庫 (MSAL) 中初始化用戶端應用程式時，您可以設定數個設定選項。這些選項分為兩個群組：

註冊選項，包括：
- 授權 (由應用程式的識別提供者執行個體和登入對象所組成，可能還包含租用戶識別碼)
- 用戶端識別碼
- 重新導向 URI
- 用戶端密碼 (適用於機密用戶端應用程式)
記錄選項，包括記錄層級、個人資料的控制，以及使用程式庫的元件名稱

授權單位

授權單位是一個 URL，指出 MSAL 可以向其要求權杖的目錄。

一般授權單位為：

一般授權單位 URL	使用時機
`https://login.microsoftonline.com/<tenant>/`	僅限將使用者登入特定組織。 URL 中的 `<tenant>` 是 Microsoft Entra 租用戶 (GUID) 或其租用戶網域的租用戶識別碼。
`https://login.microsoftonline.com/common/`	使用公司與學校帳戶或個人 Microsoft 帳戶登入使用者。
`https://login.microsoftonline.com/organizations/`	使用公司和學校帳戶登入使用者。
`https://login.microsoftonline.com/consumers/`	僅使用個人 Microsoft 帳戶 (MSA) 登入使用者。

您在程式碼中指定的授權單位，必須與您在 Azure 入口網站的應用程式註冊中為應用程式指定的支援帳戶類型一致。

授權單位可以是：

Microsoft Entra 雲端授權單位。
Azure AD B2C 授權單位。請參閱 B2C 特性。
Active Directory 同盟服務 (AD FS) 授權單位。請參閱 AD FS 支援。

Microsoft Entra 雲端授權單位有兩個部分：

識別提供者執行個體
應用程式的登入對象

執行個體和對象可以串連並提供為授權單位 URL。下圖顯示授權單位 URL 的組成方式：

授權單位 URL 的組成方式

雲端執行個體

執行個體可用來指定您的應用程式是從 Azure 公用雲端或從國家雲端簽署使用者。在您的程式碼中使用 MSAL，您可以使用列舉來設定 Azure 雲端執行個體，或將 URL 傳遞至國家雲端執行個體作為 Instance 成員。

如果同時指定了 Instance 和 AzureCloudInstance，則 MSAL.NET 會擲回明確的例外狀況。

如果您未指定執行個體，您的應用程式將會以 Azure 公用雲端執行個體 (URL https://login.onmicrosoftonline.com 的執行個體) 為目標。

應用程式對象

登入對象取決於您應用程式的商務需求：

如果您是企業營運 (LOB) 開發人員，您可能會產生只在您的組織中使用的單一租用戶應用程式。在這種情況下，請依據租用戶識別碼 (您 Microsoft Entra 執行個體的識別碼) 或與 Microsoft Entra 執行個體相關聯的網域名稱，來指定組織。
如果您是 ISV，您可能會想要以任何組織或某些組織中的公司和學校帳戶 (多租用戶應用程式) 登入使用者。但是您也可能想要讓使用者使用他們的個人 Microsoft 帳戶登入。

如何在您的程式碼/設定中指定對象

在程式碼中使用 MSAL，您可以使用下列其中一個值來指定對象：

Microsoft Entra 授權單位對象列舉
租用戶識別碼，可以是：
- 單一租用戶應用程式的 GUID (Microsoft Entra 執行個體的識別碼)
- 與您的 Microsoft Entra 執行個體相關聯的網域名稱 (也適用於單一租用戶應用程式)
其中一個預留位置作為租用戶識別碼，以取代 Microsoft Entra 授權單位對象列舉：
- organizations 適用於多租用戶應用程式
- consumers 僅透過使用者的個人帳戶登入使用者
- common 使用公司與學校帳戶或其個人 Microsoft 帳戶登入使用者

如果您同時指定 Microsoft Entra 授權單位對象和租用戶識別碼，MSAL 會擲回有意義的例外狀況。

建議指定對象，因為許多租用戶與部署在其中的應用程式將會有來賓使用者。如果您的應用程式會有外部使用者，最好避免 common 和 organization 的端點。如果您未指定對象，您的應用程式將會以 Microsoft Entra ID 和個人 Microsoft 帳戶作為目標對象，並且其行為就像已指定 common 一樣。

有效對象

您的應用程式的有效對象是在應用程式中設定的對象和在應用程式註冊中指定的對象最低規格 (如果有交集)。事實上，應用程式註冊體驗可讓您為應用程式指定對象 (支援的帳戶類型)。如需詳細資訊，請參閱快速入門：使用 Microsoft 身分識別平台註冊應用程式。

目前，讓應用程式僅使用個人 Microsoft 帳戶登入使用者的唯一方法，就是設定這兩項設定：

將應用程式註冊對象設定為 Work and school accounts and personal accounts。
在您的程式碼/設定中將對象設定為 AadAuthorityAudience.PersonalMicrosoftAccount (或 TenantID ="consumers")。

Client ID

用戶端識別碼是在註冊應用程式時，Microsoft Entra ID 指派給您應用程式的唯一應用程式 (用戶端) 識別碼。您可以在 身分識別>>的 [概觀] 頁面上找到應用程式的 應用程式 (用戶端) 識別碼。

重新導向 URI

重新導向 URI 是識別提供者用來傳回安全性權杖的 URI。

公用用戶端應用程式的重新導向 URI

如果您是使用 MSAL 的公用用戶端應用程式開發人員：

您想要在桌面或通用 Windows 平台 (UWP) 應用程式 (MSAL.NET 4.1+) 使用 .WithDefaultRedirectUri()。 .WithDefaultRedirectUri() 方法會將公用用戶端應用程式的重新導向 URI 屬性設定為公用用戶端應用程式的預設建議重新導向 URI。

平台	重新導向 URI
傳統型應用程式 (.NET Framework)	`https://login.microsoftonline.com/common/oauth2/nativeclient`
UWP	`WebAuthenticationBroker.GetCurrentApplicationCallbackUri()` 的值。這會將值設定為您需要註冊的 WebAuthenticationBroker.GetCurrentApplicationCallbackUri() 結果，以使用瀏覽器來啟用單一登入 (SSO)
.NET	`https://localhost` 可讓使用者使用系統瀏覽器進行互動式驗證，因為 .NET 目前沒有內嵌式 Web 檢視的 UI。

您可以使用 RedirectUri 屬性來覆寫重新導向 URI (例如，如果您使用訊息代理程式)。以下是該案例的一些重新導向 URI 範例：

RedirectUriOnAndroid = “msauth-00001111-aaaa-2222-bbbb-3333cccc4444：//com.microsoft.identity.client.sample”;
RedirectUriOnIos = $"msauth.{Bundle.ID}://auth";

如需其他 Android 詳細資料，請參閱 Android 中的代理驗證。

使用 MSAL Android 建置應用程式時，您可以在初始 redirect_uri 步驟期間設定，或之後再新增應用程式。
- 重新導向 URI 的格式為：msauth://<yourpackagename>/<base64urlencodedsignature>
- 範例: redirect_uri = msauth://com.azuresamples.myapp/6/aB1cD2eF3gH4iJ5kL6-mN7oP8qR=
若要尋找 MSAL Android 應用程式組態的詳細資訊，請參閱 MSAL Android 設定。
在應用程式註冊中設定重新導向 URI：

機密用戶端應用程式的重新導向 URI

針對 Web 應用程式，重新導向 URI (或回覆 URL) 是 Microsoft Entra ID 用來將權杖傳回給應用程式的 URI。如果機密應用程式是其中一種，則此 URI 可以是 Web 應用程式/Web API 的 URL。重新導向 URI 必須在應用程式註冊中註冊。當您部署一開始在本機測試的應用程式時，此註冊特別重要。然後，您必須在應用程式註冊入口網站中新增已部署應用程式的回覆 URL。

針對精靈應用程式，您不需要指定重新導向 URI。

用戶端密碼

此選項會指定機密用戶端應用程式的用戶端密碼。用戶端祕密 (應用程式密碼) 是由應用程式註冊入口網站所提供，或在使用 PowerShell Microsoft Entra ID、PowerShell AzureRM 或 Azure CLI 進行應用程式註冊期間提供給 Microsoft Entra ID。

記錄

為協助偵錯和驗證失敗疑難排解案例，MSAL 提供內建的記錄支援。下列各文章涵蓋每個程式庫中的記錄：

下一步

了解使用 MSAL.NET 來具現化用戶端應用程式和使用 MSAL.js 來具現化用戶端應用程式。

共用方式為