使用Microsoft身分識別平臺登入Android應用程式中的使用者 - Microsoft identity platform

適用於：帶有白色核取記號符號的綠色圓圈，表示以下內容適用於員工租戶。員工租戶帶有白色核取記號符號的綠色圓圈，表示以下內容適用於外部租戶。外部租戶（深入瞭解）

在本教學課程中，您會如何將適用於Android的 Microsoft驗證連結庫（MSAL）新增至 Android 應用程式。 MSAL 可讓 Android 應用程式使用 Microsoft Entra 來驗證使用者。

在本教學課程中，您將;

新增 MSAL 相依性
新增組態
建立 MSAL SDK 實例

先決條件

勞動力租戶
外部租戶

員工租戶。您可以使用預設目錄或設定新的租戶。
在 Microsoft Entra 系統管理中心註冊新的應用程式， 僅針對此組織目錄中的帳戶進行設定。如需詳細資訊，請參閱註冊應用程式。從應用程式 [概觀 ] 頁面記錄下列值，以供稍後使用：
- 應用程式（用戶端）識別碼
- 目錄（租戶）識別碼
Android 專案。如果您沒有Android專案，請加以建立。

新增重定向 URI

您必須在應用程式註冊中設定特定的重新導向 URI，以確保與下載的程式碼範例相容。在使用者成功登入之後，這些 URI 對於將使用者重新導向回應用程式至關重要。

勞動力租戶
外部租戶

在 [管理] 底下，選取 [驗證]>[新增平台]>[Android]。
根據您下載的範例類型，輸入您的專案的套件名稱。
- JAVA 範例- com.azuresamples.msalandroidapp
- Kotlin 範例 - com.azuresamples.msalandroidkotlinapp
在 [設定您的 Android 應用程式] 頁面的 [簽章雜湊] 區段中，選取 [產生開發簽章雜湊。]，然後將 KeyTool 命令複製到命令列。
- KeyTool.exe 會安裝為 Java 開發套件 (JDK) 的一部分。您也必須安裝 OpenSSL 工具來執行 KeyTool 命令。如需詳細資訊，請參閱關於產生金鑰的 Android 文件。
請輸入由 KeyTool 產生的簽章雜湊。
選取 [設定] 並儲存出現在 [Android 組態] 窗格中的 [MSAL 組態]，以便稍後在設定應用程式時可加以輸入。
選擇完成。

若要在應用程式註冊中指定您的應用程式類型，請遵循下列步驟：

在 [管理] 底下，選取 [驗證]。
在 [平臺組態] 頁面上，選取 [新增平臺]，然後選取 [iOS / macOS] 選項。
輸入專案的套件組合識別碼。若已下載範例程式碼，則此值為 com.microsoft.identitysample.ciam.MSALiOS。
選取 [設定]，然後儲存 MSAL 組態，這會出現在 [iOS / macOS 組態] 窗格中，以便稍後設定應用程式時輸入。
選擇完成。

啟用公開客戶端流程

若要將您的應用程式識別為公用用戶端，請遵循下列步驟：

在 [管理] 底下，選取 [驗證]。
在 [進階設定] 下方的 [允許公用用戶端流程]，選取 [是]。
選取儲存以儲存變更。

將 MSAL 相依性和相關的連結庫新增至您的專案

若要在Android專案中新增 MSAL 相依性，請遵循下列步驟：

在 Android Studio 中開啟您的專案，或建立新的專案。
開啟應用程式的 build.gradle，並新增下列相依性：
```
allprojects {
repositories {
    //Needed for com.microsoft.device.display:display-mask library
    maven {
        url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
        name 'Duo-SDK-Feed'
    }
    mavenCentral()
    google()
    }
}
//...

dependencies { 
    implementation 'com.microsoft.identity.client:msal:5.+'
    //...
}
```
在 build.gradle 組態中，會針對專案相依性定義存放庫。這包括來自 Azure DevOps 的 com.microsoft.device.display:display-mask 函式庫的 Maven 存放庫 URL。此外，它會使用 Maven Central 和 Google 存放庫。相依性區段會指明 MSAL 第 5 版的實作，以及其他可能的相依性。
在 Android Studio 中，選取檔案>與 Gradle 文件同步專案。

新增組態

您可以透過 JSON 組態設定，將所需的租使用者識別碼，例如應用程式（用戶端）標識碼傳遞至 MSAL SDK。

使用下列步驟來建立組態檔：

Workforce 租戶設定
外部租戶配置

在 Android Studio 的專案窗格中，流覽至 app\src\main\res。
以滑鼠右鍵按下 res，然後選擇 [新增>目錄]。輸入 raw 作為新的目錄名稱，然後選取 [確定]。

在 應用程式中的>src>main>res>raw目錄下，建立名為 auth_config_single_account.json 的新 JSON 檔案，並貼上您稍早儲存的 MSAL 配置。

在重新導向 URI 下方貼上：

  "account_mode" : "SINGLE",

您的組態檔應該類似下列範例：

{
  "client_id": "00001111-aaaa-bbbb-3333-cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "redirect_uri": "msauth://com.azuresamples.msalandroidapp/00001111%cccc4444%3D",
  "broker_redirect_uri_registered": true,
  "account_mode": "SINGLE",
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

本教學課程僅示範如何在單一帳戶模式中設定應用程式，如需詳細資訊，請參閱單一與多個帳戶模式和設定應用程式

我們建議使用『WEBVIEW』。如果您想要在應用程式中將「authorization_user_agent」設定為『BROWSER』，您需要進行下列更新。 a）將 auth_config_single_account.json 更新為「authorization_user_agent」:「Browser」。 b）更新 AndroidManifest.xml。在應用程式中，移至 app>src>main>AndroidManifest.xml，將 BrowserTabActivity 活動新增為 <application> 項目的子系。此項目可讓Microsoft Entra ID 在完成驗證之後回呼您的應用程式：
```

<activity
    android:name="com.microsoft.identity.client.BrowserTabActivity"
    android:exported="true">
    <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="Enter_the_Package_Name"
            android:path="/Enter_the_Signature_Hash" />
    </intent-filter>
</activity>
```
- 使用 套件名稱 來取代 android:host=. 值。應該是 com.azuresamples.msalandroidapp。
- 使用 簽章哈希 來取代 android:path= 值。請確定簽章哈希開頭有前置 /。應該是 /aB1cD2eF3gH4+iJ5kL6-mN7oP8q=。
您也可以在應用程式註冊的驗證面板中找到這些值。

在 Android Studio 的專案窗格中，流覽至 app\src\main\res。
以滑鼠右鍵單擊 res，然後選取新增>目錄。輸入 raw 作為新的目錄名稱，然後選取 [確定]。
在 app\src\main\res\raw中，建立名為 auth_config_ciam_auth.json的新 JSON 檔案。
在 auth_config_ciam_auth.json 檔案中，新增下列 MSAL 組態：
```
{
  "client_id" : "Enter_the_Application_Id_Here",
  "authorization_user_agent" : "DEFAULT",
  "redirect_uri" : "Enter_the_Redirect_Uri_Here",
  "account_mode" : "SINGLE",
  "authorities" : [
    {
      "type": "CIAM",
      "authority_url": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/Enter_the_Tenant_Subdomain_Here.onmicrosoft.com/"
    }
  ]
}
```
JSON 組態檔會指定 Android 應用程式的各種設定。其中包含用戶端標識碼、授權使用者代理程式、重新導向 URI 和帳戶模式。此外，它會定義驗證的授權單位，並指定類型和授權單位 URL。

將下列佔位符取代為您從 Microsoft Entra 管理中心取得的租戶值：
- Enter_the_Application_Id_Here，並將它取代為您稍早註冊之應用程式的 應用程式（用戶端）標識碼。
- Enter_the_Redirect_Uri_Here，將其替換為您之前在新增平台重定向 URL 時所下載的 Microsoft 驗證程式庫（MSAL）組態檔中的 redirect_uri 值。
- Enter_the_Tenant_Subdomain_Here，並將它取代為 Directory （tenant）子域。例如，如果您的租用者的主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您不知道租戶子域名，請瞭解如何閱讀租戶資訊。
開啟 /app/src/main/AndroidManifest.xml 檔案。
在 AndroidManifest.xml中，將下列資料規格新增至意圖篩選：
```
<data
    android:host="ENTER_YOUR_PROJECT_PACKAGE_NAME_HERE"
    android:path="/ENTER_YOUR_SIGNATURE_HASH_HERE"
    android:scheme="msauth" />
```
尋找占位符：
- ENTER_YOUR_PROJECT_PACKAGE_NAME_HERE，並以 Android 的專案套件名稱取代它。
- ENTER_YOUR_SIGNATURE_HASH_HERE，並將它取代為您稍早新增平臺重新導向 URL 時所產生的簽章哈希。

使用自訂網址（選擇性）

使用自定義網域來實現完整的品牌化驗證網址。從使用者的角度來看，使用者在驗證過程中會停留在您的域名上，而不會被重新導向到 ciamlogin.com 域名。

使用下列步驟來使用自訂網域：

使用的步驟來為外部租用戶中的應用程式啟用自訂 URL 網域，為外部租用戶啟用自訂 URL 網域。
開啟 auth_config_ciam_auth.json 檔案：
1. 將 authority_url 屬性的值更新為 https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here。將 Enter_the_Custom_Domain_Here 替換為您的自定義 URL 網域，並將 Enter_the_Tenant_ID_Here 替換為您的租戶ID。如果您沒有租戶 ID，請了解如何查看租戶詳細資料。
2. 新增 knownAuthorities 屬性，其值為 [Enter_the_Custom_Domain_Here]。

在您對 auth_config_ciam_auth.json 檔案進行變更之後，如果您的自定義 URL 網域是 login.contoso.com，且您的租戶 ID 是 aaaabbbb-0000-cccc-1111-dddd2222eeee，那麼您的檔案應該看起來類似於下列程式碼片段：

{
    "client_id" : "Enter_the_Application_Id_Here",
    "authorization_user_agent" : "DEFAULT",
    "redirect_uri" : "Enter_the_Redirect_Uri_Here",
    "account_mode" : "SINGLE",
    "authorities" : [
    {
        "type": "CIAM",
        "authority_url": "https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "knownAuthorities": ["login.contoso.com"]
    }
    ]
}

建立 MSAL SDK 實例

若要初始化 MSAL SDK 實例，請使用下列程式代碼：

Workforce 租戶設定
外部租戶配置

PublicClientApplication.createSingleAccountPublicClientApplication(
    getContext(),
    R.raw.auth_config_single_account,
    new IPublicClientApplication.ISingleAccountApplicationCreatedListener() {
        @Override
        public void onCreated(ISingleAccountPublicClientApplication application) {
            // Initialize the single account application instance
            mSingleAccountApp = application;
            loadAccount();
        }

        @Override
        public void onError(MsalException exception) {
            // Handle any errors that occur during initialization
            displayError(exception);
        }
    }
);

此程式代碼會使用組態檔 auth_config_single_account.json建立單一帳戶公用用戶端應用程式。成功建立應用程式時，它會將實例指派給 mSingleAccountApp，並呼叫 loadAccount() 方法。如果在建立期間發生錯誤，它會呼叫 displayError（exception）方法來處理錯誤。

private suspend fun initClient(): ISingleAccountPublicClientApplication = withContext(Dispatchers.IO) {
    return@withContext PublicClientApplication.createSingleAccountPublicClientApplication(
        this@MainActivity,
        R.raw.auth_config_ciam_auth
    )
}

程式代碼會以異步方式初始化單一帳戶公用用戶端應用程式。它會使用提供的驗證組態檔，並在I/O 發送器上執行。

請確定您包含匯入陳述式。 Android Studio 應該會自動為你包含 import 語句。

後續步驟

教學課程：在 Android 應用程式中新增登入功能。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-04-22