教學課程：準備 Android (Kotlin) 應用程式以進行驗證

發行項
07/29/2024

這是教學課程系列中的第二個教學課程，示範如何將適用於 Android 的 Microsoft 驗證程式庫 (MSAL) 新增至 Android (Kotlin) 應用程式。 MSAL 可讓 Android 應用程式使用 Microsoft Entra 來驗證使用者。

在本教學課程中，您將會：

新增 MSAL 相依性。
新增組態。

必要條件

Android Studio
如果您尚未這麼做，請遵循教學課程：註冊和設定 Android (Kotlin) 行動裝置應用程式中的指示，並在外部租用戶註冊應用程式。
Android 專案。如果您沒有 Android 專案，請加以建立。

新增 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 存放庫。 dependencies 區段會指定 MSAL 第 5 版和潛在其他相依性的實作。

在 Android Studio 中，選取 [檔案]>[同步專案與 Gradle 檔案]。

新增設定

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

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

在 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，並將其取代為目錄 (租用戶) 子網域。例如，若租用戶主要網域是 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 時所產生的簽章雜湊。

使用自訂 URL 網域 (選用)

使用自訂網域對驗證 URL 進行完整品牌化。就使用者而言，使用者在驗證過程中一直停留在您的網域中，而不會重新導向至 ciamlogin.com 網域名稱。

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

使用針對外部租用戶中的應用程式啟用自訂 URL 網域中的步驟，為外部租用戶啟用自訂 URL 網域。
開啟 auth_config_ciam_auth.json 檔案：
1. 將 authority_url 屬性的值更新為 https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here。以您的自訂 URL 網域取代 Enter_the_Custom_Domain_Here，並以您的租用戶識別碼取代 Enter_the_Tenant_ID_Here。如果您沒有租用戶識別碼，請了解如何讀取租用戶詳細資料。
2. 新增具有值 [Enter_the_Custom_Domain_Here] 的 knownAuthorities 屬性。

對 auth_config_ciam_auth.json 檔案進行變更之後，如果您的自訂 URL 網域為 login.contoso.com，且您的租用戶識別碼為 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 執行個體，請使用下列程式碼：

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

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

請確定您包含 import 陳述式。 Android Studio 應該會自動包含 import 陳述式。

下一步

教學課程：在 Android (Kotlin) 行動裝置應用程式中登入使用者

共用方式為