Android Microsoft 驗證程式庫設定檔
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);