適用於 Android 的 Microsoft 驗證程式庫

Android 版 Microsoft 驗證資源庫（MSAL）是一個函式庫，使 Android 應用程式能使用 Microsoft 身分識別平台（前身為 Azure Active Directory）驗證使用者，並使用 OAuth2 與 OpenID Connect 協定存取受保護的網頁 API。 MSAL Android 讓開發者能從 Microsoft 身分識別平台 取得安全憑證，以驗證使用者身份並存取其基於 Android 應用程式的安全網路 API。

MSAL Android 支援多種認證場景，例如單一登入（SSO）、條件存取及經紀驗證。 它讓你可以輕鬆鎖定多種身份，包括Microsoft Entra ID（工作與學校帳號）、Microsoft 帳號（Outlook.com、hotmail.com 及其他幾個），或 Azure AD B2C（社群與本地帳號）。

此處指引旨在記錄與 MSAL Android 相關的共同功能。 如果你想了解更多關於 Microsoft Entra ID、Microsoft Accounts 或 Azure AD B2C 的幫助，可以參考 Microsoft 身分識別平台 文件。如果你想了解更多關於 Microsoft Graph API 的資訊，可以參考 Microsoft Graph 文件。

MSAL 的原生驗證支援

MSAL Android 也讓你能在行動應用程式中實現端對端可自訂流程的原生認證體驗。 透過原生認證，使用者能在不離開應用程式的情況下，完成豐富、原生、以行動裝置為優先的註冊與登入旅程。 原生驗證功能僅適用於 External ID for customers 上的行動應用程式。

從 Azure Active Directory Authentication Library (ADAL) 移轉

Android 版 Azure Active Directory 認證函式庫（ADAL）已於 2023 年 6 月起被棄用。 如果您或您的組織正在使用 Android 版 Azure Active Directory 認證函式庫（ADAL），建議遷移至 MSAL Android，以避免您的應用程式安全受到風險。 適用於 Android 的 Microsoft 驗證資源庫（MSAL）是可用於驗證和權杖取得的受支援函式庫。

開始使用 MSAL Android

要在您的應用程式中使用 MSAL Android，您需要：

由於 MSAL Android 支援瀏覽器委派與原生認證體驗，請根據你的情境依照以下教學步驟操作。

Requirements

  • Min SDK Version 16+
  • Target SDK 版本 33+

步驟一：宣告對 MSAL 的依賴

在你的應用程式裡新增 build.gradle：

dependencies {
    implementation 'com.microsoft.identity.client:msal:4.9.+'
}

請在你的 gradle 腳本中，將以下幾行文字加入你的資料庫區塊：

maven { 
    url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1' 
}

步驟 2：建立你的 MSAL 設定檔

瀏覽器委派認證：

在專案中建立你的設定檔作為「原始」資源。 建構 PublicClientApplication 實例時，請使用產生的資源識別碼來參考它。 如果您是第一次在 Microsoft Entra 系統管理中心註冊您的應用程式，系統也會向您提供詳盡的 MSAL Android 設定檔

{
  "client_id" : "<YOUR_CLIENT_ID>",
  "redirect_uri" : "msauth://<YOUR_PACKAGE_NAME>/<YOUR_BASE64_URL_ENCODED_PACKAGE_SIGNATURE>",
  "broker_redirect_uri_registered": true,
}

在 redirect_uri 中，<YOUR_PACKAGE_NAME> 指的是由 context.getPackageName() 方法傳回的套件名稱。 這個套件名稱和 application_id 你 build.gradle 檔案中定義的名稱相同。

上述數值為最低要求配置。 MSAL 其他設定都依賴函式庫附帶的預設設定。 請參閱 MSAL Android 設定檔文件以 了解函式庫的預設值。

原生認證：

  1. 右鍵點擊 res，選擇新 > 目錄。 輸入 raw 作為新的目錄名稱，然後選擇確定。
  2. 在這個新資料夾（app > src > main > res > raw）中，建立一個名為 auth_config_native_auth.json 的新 JSON 檔案，並貼上以下 MSAL 配置範本：
{ 
  "client_id": "Enter_the_Application_Id_Here", 
  "authorities": [ 
    { 
      "type": "CIAM", 
      "authority_url": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/Enter_the_Tenant_Subdomain_Here.onmicrosoft.com/" 
    } 
  ], 
  "challenge_types": ["oob"], 
  "logging": { 
    "pii_enabled": false, 
    "log_level": "INFO", 
    "logcat_enabled": true 
  } 
 }

步驟 3：設定 AndroidManifest.xml 以進行瀏覽器委派認證

  1. 請透過 Android 清單申請以下權限
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  1. 在 Android Manifest 中設定一個意圖過濾器，使用你的 redirect URI

若未包含與你設定的重定向 URI 相符的意圖過濾器，則會導致互動式標記請求失敗。

    <!--Intent filter to capture authorization code response from the default browser on the device calling back to our app after interactive sign in -->
    <activity
        android:name="com.microsoft.identity.client.BrowserTabActivity">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data
                android:scheme="msauth"
                android:host="<YOUR_PACKAGE_NAME>"
                android:path="/<YOUR_BASE64_ENCODED_PACKAGE_SIGNATURE>" />
        </intent-filter>
    </activity>

你可以參考 MSAL Android 常見問題 集，了解更多常見的重定向 uri 問題。

ProGuard

MSAL 在執行時使用儲存在 .class 檔案中的反射與通用型態資訊，以支援各種持久化與序列化相關的功能。 函式庫對縮小與混淆的支援有限。 此函式庫附帶預設配置;如果你發現任何問題，請 提出問題 。

Recommendation

MSAL 是一個安全圖書館。 它控制使用者如何登入及存取服務。 我們建議你盡可能在應用程式中使用最新版本的圖書館。 我們使用 語意版本控制 ，讓您能控制更新應用程式的風險。 例如，隨時下載最新的次要版本號（例如 x.y.x），能確保你獲得最新的安全與功能增強，同時確保我們的 API 覆蓋範圍未曾改變。 你隨時可以在 GitHub 的 Releases 標籤下看到最新版本和發佈說明。

  • Last updated on