Android Microsoft 驗證程式庫設定檔

發行項
07/01/2024

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

本文將協助您瞭解設定檔中的各種設定，以及如何指定要在以 MSAL 為基礎應用程式中使用的設定檔。

組態設定

一般設定

屬性	資料類型	必要	備註
`client_id`	String	Yes	應用程式註冊頁面中的應用程式用戶端識別碼
`redirect_uri`	String	Yes	應用程式註冊頁面中的應用程式重新導向 URI
`broker_redirect_uri_registered`	布林值	No	可能的值：`true`、`false`
`authorities`	清單<授權單位>	No	您應用程式所需的授權單位清單
`authorization_user_agent`	AuthorizationAgent (列舉)	No	可能的值：`WEBVIEW`、`BROWSER`
`http`	HttpConfiguration	No	設定 `HttpUrlConnection` `connect_timeout` 和 `read_timeout`
`logging`	LoggingConfiguration	No	指定記錄詳細資料的層級。選擇性設定包括：`pii_enabled` (接受布林值)，以及 `log_level` (接受 `ERROR`、`WARNING`、`INFO` 或 `VERBOSE`)。

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	鏡像您的應用程式目標對象或帳戶類型。可能的值：`AAD`、`B2C`
`audience`	Object	No	只有在 type=`AAD` 時才適用。指定應用程式目標的身分識別。使用您應用程式註冊中的值
`authority_url`	String	Yes	只在 type =`B2C` 時才需要。 type =`AAD` 時為選用。指定您應用程式應使用的授權單位 URL 或原則
`default`	boolean	Yes	當指定一個或多個授權單位時，需要單一的 `"default":true`。

對象屬性

屬性	資料類型	必要	備註
`type`	String	Yes	指定您應用程式要設為目標的對象。可能的值：`AzureADandPersonalMicrosoftAccount`、`PersonalMicrosoftAccount`、`AzureADMultipleOrgs`、`AzureADMyOrg`
`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	要輸出的記錄訊息。支援的記錄層級包括 `ERROR`、`WARNING`、`INFO` 和 `VERBOSE`。
`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
    }
  ]
}

如何使用設定檔

建立設定檔。建議您在 res/raw/auth_config.json 中建立自訂設定檔。但您可以將設定檔放在想要的任何位置。

告知 MSAL 在您建立 PublicClientApplication 時要在哪裡尋找您的設定。例如：

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

共用方式為

Android Microsoft 驗證程式庫設定檔

組態設定

一般設定

client_id

redirect_uri

broker_redirect_uri_registered

授權單位

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

授權單位屬性

對象屬性

authorization_user_agent

multiple_clouds_supported

broker_redirect_uri_registered

HTTP

logging

account_mode

browser_safelist

預設 MSAL 設定檔

範例基本組態

如何使用設定檔

意見反應

其他資源