Android Microsoft 驗證連結庫組態檔

Android Microsoft 驗證連結庫 (MSAL) 隨附預設 組態 JSON 檔案 ,您可以自定義來定義公用用戶端應用程式的行為,例如預設授權單位、您將使用哪些授權單位等等。

本文將協助您了解組態檔中的各種設定,以及如何指定要在 MSAL 型應用程式中使用的組態檔。

組態設定

一般設定

屬性 資料類型 必要 備註
client_id String Yes 來自應用程式註冊頁面的應用程式用戶端標識碼
redirect_uri String Yes 從應用程式註冊頁面的 [重新導向 URI]
broker_redirect_uri_registered 布林值 No 可能的值: truefalse
authorities 清單<授權單位> No 您的應用程式所需的授權單位清單
authorization_user_agent AuthorizationAgent (列舉) No 可能的值: WEBVIEWBROWSER
http HttpConfiguration No 設定 HttpUrlConnectionconnect_timeoutread_timeout
logging LoggingConfiguration No 指定記錄詳細數據的層級。 選擇性組態包括: pii_enabled,其接受布林值,以及 log_level,接受 ERRORWARNINGINFOVERBOSE

client_id

註冊應用程式時所建立的用戶端標識碼或應用程式標識碼。

redirect_uri

註冊應用程式時所註冊的重新導向 URI。 如果重新導向 URI 是代理程式應用程式,請參閱 公用用戶端應用程式 的重新導向 URI,以確保您使用代理程式應用程式的正確重新導向 URI 格式。

broker_redirect_uri_registered

如果您要使用代理驗證, broker_redirect_uri_registered 屬性必須設定為 true。 在代理驗證案例中,如果應用程式的格式不正確,與訊息代理程序通訊,如公用用戶端應用程式的重新導向 URI 中所述,應用程式會驗證您的重新導向 URI,並在啟動時擲回例外狀況。

當局

您已知且信任的授權單位清單。 除了此處所列的授權單位之外,MSAL 也會查詢 Microsoft 以取得 Microsoft 已知的雲端和授權單位清單。 在此授權單位清單中,指定授權單位的類型,以及任何其他選擇性參數,例如 "audience",應根據您的應用程式註冊來配合您應用程式的物件。 以下是授權單位的範例清單:

// Example AzureAD and Personal Microsoft Account
{
    "type": "AAD",
    "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
    },
    "default": true // Indicates that this is the default to use if not provided as part of the acquireToken call
},
// Example AzureAD My Organization
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMyOrg",
        "tenant_id": "contoso.com" // Provide your specific tenant ID here
    }
},
// Example AzureAD Multiple Organizations
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMultipleOrgs"
    }
},
//Example PersonalMicrosoftAccount
{
    "type": "AAD",
    "audience": {
        "type": "PersonalMicrosoftAccount"
    }
}

將 Microsoft Entra 授權單位和對象對應至 Microsoft 身分識別平台 端點

類型 對象 租用戶識別碼 Authority_Url 產生的端點 備註
Microsoft Entra ID AzureADandPersonalMicrosoftAccount https://login.microsoftonline.com/common common 是帳戶所在位置的租用戶別名。 例如特定的 Microsoft Entra 租使用者或 Microsoft 帳戶系統。
Microsoft Entra ID AzureADMyOrg contoso.com https://login.microsoftonline.com/contoso.com 只有存在於 contoso.com 中的帳戶可以取得令牌。 任何已驗證的網域或租使用者 GUID 都可用來作為租用戶標識碼。
Microsoft Entra ID AzureADMultipleOrgs https://login.microsoftonline.com/organizations 只有 Microsoft Entra 帳戶可以搭配此端點使用。 Microsoft 帳戶可以是組織的成員。 若要針對組織中的資源使用 Microsoft 帳戶取得令牌,請指定您想要令牌的來源組織租使用者。
Microsoft Entra ID PersonalMicrosoftAccount https://login.microsoftonline.com/consumers 只有 Microsoft 帳戶可以使用此端點。
B2C 請參閱產生的端點 https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/B2C_1_SISOPolicy/ 只有存在於 contoso.onmicrosoft.com 租使用者中的帳戶才能取得令牌。 在此範例中,B2C 原則是授權單位 URL 路徑的一部分。

注意

無法在 MSAL 中啟用和停用授權單位驗證。 授權單位是透過組態指定的開發人員,或透過元數據向 Microsoft 已知。 如果 MSAL 收到權杖要求給未知授權單位, MsalClientException 則類型 UnknownAuthority 為 的 。 代理驗證不適用於 Azure AD B2C。

授權單位屬性

屬性 資料類型 必要 備註
type String Yes 鏡像物件或帳戶類型您的應用程式目標。 可能的值: AADB2C
audience Object No 僅適用於 type=AAD。 指定您的應用程式目標身分識別。 使用應用程式註冊中的值
authority_url String Yes 只有在 type=B2C時才需要。 type=AAD的選擇性。 指定應用程式應使用的授權單位 URL 或原則
default boolean Yes 指定一或多個授權單位時,需要單 "default":true 一。

物件屬性

屬性 資料類型 必要 備註
type String Yes 指定應用程式想要設為目標的物件。 可能的值:AzureADandPersonalMicrosoftAccount、、PersonalMicrosoftAccountAzureADMultipleOrgsAzureADMyOrg
tenant_id String Yes 只有在 時 "type":"AzureADMyOrg"才需要 。 其他 type 值的選擇性。 這可以是租使用者網域,例如 contoso.com, 或租使用者識別碼,例如 72f988bf-86f1-41af-91ab-2d7cd011db46

authorization_user_agent

指出登入帳戶或授權存取資源時,是否要使用裝置上的內嵌網頁檢視或默認瀏覽器。

可能的值:

  • WEBVIEW:使用內嵌網頁檢視。
  • BROWSER:在裝置上使用預設瀏覽器。

multiple_clouds_supported

針對支援多個國家雲端的用戶端,指定 true。 接著,Microsoft 身分識別平台 會在授權和令牌兌換期間自動重新導向至正確的國家雲端。 您可以檢查與 AuthenticationResult相關聯的授權單位,以判斷已登入帳戶的國家/地區雲端。 請注意, AuthenticationResult 不會提供您要求令牌之資源的國家雲端特定端點位址。

broker_redirect_uri_registered

布爾值,指出您是否使用與代理程式內重新導向 URI 相容的 Microsoft Identity Broker。 false如果您不想在應用程式內使用訊息代理程式,請將 設定為 。

如果您使用 Microsoft Entra Authority 搭配物件設定為 "MicrosoftPersonalAccount",則不會使用訊息代理程式。

HTTP

設定 HTTP 逾時的全域設定,例如:

屬性 資料類型 必要 備註
connect_timeout int No 以毫秒為單位的時間
read_timeout int No 以毫秒為單位的時間

logging

下列全域設定用於記錄:

屬性 資料類型 必要 備註
pii_enabled boolean No 是否發出個人資料
log_level string No 要輸出的記錄訊息。 支援的記錄層級包括 ERRORWARNINGINFOVERBOSE
logcat_enabled boolean No 是否要輸出至記錄 cat,以及記錄介面

account_mode

指定一次可在您的應用程式內使用多少個帳戶。 可能的值是:

  • MULTIPLE (預設值)
  • SINGLE

PublicClientApplication使用不符合此設定的帳戶模式建構 會導致例外狀況。

如需單一帳戶與多個帳戶之間差異的詳細資訊,請參閱 單一和多個帳戶應用程式

browser_safelist

與 MSAL 相容的瀏覽器允許清單。 這些瀏覽器正確地處理重新導向至自定義意圖。 您可以新增至此清單。 默認設定提供於如下所示的預設組態中。 ``

預設 MSAL 組態檔

隨附於 MSAL 的預設 MSAL 組態如下所示。 您可以在 GitHub看到最新版本。

此設定會以您提供的值來補充。 您提供的值會覆寫預設值。

{
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      },
      "default": true
    }
  ],
  "authorization_user_agent": "DEFAULT",
  "multiple_clouds_supported": false,
  "broker_redirect_uri_registered": false,
  "http": {
    "connect_timeout": 10000,
    "read_timeout": 30000
  },
  "logging": {
    "pii_enabled": false,
    "log_level": "WARNING",
    "logcat_enabled": false
  },
  "shared_device_mode_supported": false,
  "account_mode": "MULTIPLE",
  "browser_safelist": [
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "7fmduHKTdHHrlMvldlEqAIlSfii1tl35bxj1OXN5Ve8c4lU6URVu4xtSHc3BVZxS6WWJnxMDhIfQN0N0K2NDJg=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "45"
    },
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "7fmduHKTdHHrlMvldlEqAIlSfii1tl35bxj1OXN5Ve8c4lU6URVu4xtSHc3BVZxS6WWJnxMDhIfQN0N0K2NDJg=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "2gCe6pR_AO_Q2Vu8Iep-4AsiKNnUHQxu0FaDHO_qa178GByKybdT_BuE8_dYk99G5Uvx_gdONXAOO2EaXidpVQ=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "2gCe6pR_AO_Q2Vu8Iep-4AsiKNnUHQxu0FaDHO_qa178GByKybdT_BuE8_dYk99G5Uvx_gdONXAOO2EaXidpVQ=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "57"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "ABi2fbt8vkzj7SJ8aD5jc4xJFTDFntdkMrYXL3itsvqY1QIw-dZozdop5rgKNxjbrQAd5nntAGpgh9w84O1Xgg=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "4.0"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "ABi2fbt8vkzj7SJ8aD5jc4xJFTDFntdkMrYXL3itsvqY1QIw-dZozdop5rgKNxjbrQAd5nntAGpgh9w84O1Xgg=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.cloudmosa.puffinFree",
      "browser_signature_hashes": [
        "1WqG8SoK2WvE4NTYgr2550TRhjhxT-7DWxu6C_o6GrOLK6xzG67Hq7GCGDjkAFRCOChlo2XUUglLRAYu3Mn8Ag=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.duckduckgo.mobile.android",
      "browser_signature_hashes": [
        "S5Av4cfEycCvIvKPpKGjyCuAE5gZ8y60-knFfGkAEIZWPr9lU5kA7iOAlSZxaJei08s0ruDvuEzFYlmH-jAi4Q=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.explore.web.browser",
      "browser_signature_hashes": [
        "BzDzBVSAwah8f_A0MYJCPOkt0eb7WcIEw6Udn7VLcizjoU3wxAzVisCm6bW7uTs4WpMfBEJYf0nDgzTYvYHCag=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.ksmobile.cb",
      "browser_signature_hashes": [
        "lFDYx1Rwc7_XUn4KlfQk2klXLufRyuGHLa3a7rNjqQMkMaxZueQfxukVTvA7yKKp3Md3XUeeDSWGIZcRy7nouw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.microsoft.emmx",
      "browser_signature_hashes": [
        "Ivy-Rk6ztai_IudfbyUrSHugzRqAtHWslFvHT0PTvLMsEKLUIgv7ZZbVxygWy_M5mOPpfjZrd3vOx3t-cA6fVQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.browser",
      "browser_signature_hashes": [
        "FIJ3IIeqB7V0qHpRNEpYNkhEGA_eJaf7ntca-Oa_6Feev3UkgnpguTNV31JdAmpEFPGNPo0RHqdlU0k-3jWJWw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.mini.native",
      "browser_signature_hashes": [
        "TOTyHs086iGIEdxrX_24aAewTZxV7Wbi6niS2ZrpPhLkjuZPAh1c3NQ_U4Lx1KdgyhQE4BiS36MIfP6LbmmUYQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "mobi.mgeek.TunnyBrowser",
      "browser_signature_hashes": [
        "RMVoXuK1sfJZuGZ8onG1yhMc-sKiAV2NiB_GZfdNlN8XJ78XEE2wPM6LnQiyltF25GkHiPN2iKQiGwaO2bkyyQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "org.mozilla.focus",
      "browser_signature_hashes": [
        "L72dT-stFqomSY7sYySrgBJ3VYKbipMZapmUXfTZNqOzN_dekT5wdBACJkpz0C6P0yx5EmZ5IciI93Q0hq0oYA=="
      ],
      "browser_use_customTab" : false
    }
  ]
}

範例基本設定

下列範例說明基本設定,指定用戶端標識符、重新導向 URI、是否已註冊訊息代理程式重新導向,以及授權單位清單。

{
  "client_id" : "4b0db8c2-9f26-4417-8bde-3f0e3656f8e0",
  "redirect_uri" : "msauth://com.microsoft.identity.client.sample.local/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "broker_redirect_uri_registered": true,
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      }
      "default": true
    }
  ]
}

如何使用組態檔

  1. 建立組態檔。 建議您在 中 res/raw/auth_config.json建立自定義組態檔。 但是,你可以把它放在你想要的任何地方。

  2. 當您建構 時,請告知 MSAL 在何處尋找您的組 PublicClientApplication態。 例如:

    //On Worker Thread
    IMultipleAccountPublicClientApplication sampleApp = null; 
    sampleApp = new PublicClientApplication.createMultipleAccountPublicClientApplication(getApplicationContext(), R.raw.auth_config);