分享方式:


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 設定 HttpUrlConnection connect_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 接收到未知授權單位的權杖要求,則會產生類型 UnknownAuthority 結果的 MsalClientException。 代理驗證無法對 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 指定您應用程式要設為目標的對象。 可能的值:AzureADandPersonalMicrosoftAccountPersonalMicrosoftAccountAzureADMultipleOrgsAzureADMyOrg
tenant_id String Yes 只在 "type":"AzureADMyOrg" 時才需要。 對其他 type 值為選用項目。 這可以是租用戶網域,例如 contoso.com,或租用戶識別碼,例如 aaaabbbb-0000-cccc-1111-dddd2222eeee

authorization_user_agent

指出當您登入帳戶或授與資源的存取權時,是要使用內嵌的 Web 檢視,還是裝置上的預設瀏覽器。

可能的值:

  • WEBVIEW:使用內嵌的 Web 檢視。
  • BROWSER:使用裝置上的預設瀏覽器。

multiple_clouds_supported

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

broker_redirect_uri_registered

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

如果您使用 Microsoft Entra 授權單位設定為 "MicrosoftPersonalAccount" 的對象,則不會使用訊息代理程式。

HTTP

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

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

logging

下列全域設定適用於記錄:

屬性 資料類型 必要 備註
pii_enabled boolean No 是否要發出個人資料
log_level 字串 No 要輸出的記錄訊息。 支援的記錄層級包括 ERRORWARNINGINFOVERBOSE
logcat_enabled boolean No 是否除了記錄介面外,還會輸出到記錄目錄

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": [
        "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "45"
    },
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "cD2eF3gH4iJ5kL6mN7-oP8qR9sT=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "eF3gH4iJ5kL6mN7oP8-qR9sT0uV=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "gH4iJ5kL6mN7oP8qR9-sT0uV1wX=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "57"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "iJ5kL6mN7oP8qR9sT0-uV1wX2yZ=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "4.0"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "kL6mN7oP8qR9sT0uV1-wX2yZ3aB=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.cloudmosa.puffinFree",
      "browser_signature_hashes": [
        "mN7oP8qR9sT0uV1wX2-yZ3aB4dE="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.duckduckgo.mobile.android",
      "browser_signature_hashes": [
        "S5Av4...jAi4Q=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.explore.web.browser",
      "browser_signature_hashes": [
        "BzDzB...YHCag=="
      ],
      "browser_use_customTab" : false
    },

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

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

    {
      "browser_package_name": "com.opera.browser",
      "browser_signature_hashes": [
        "FIJ3I...jWJWw=="
      ],
      "browser_use_customTab" : false
    },

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

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

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

範例基本組態

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

{
  "client_id" : "00001111-aaaa-2222-bbbb-3333cccc4444",
  "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);