教學課程：準備 Android 行動應用程式以進行原生驗證

發行項
06/21/2024

本教學課程示範如何將 Microsoft 驗證程式庫 (MSAL) 原生驗證 SDK 新增至 Android 行動應用程式。

在本教學課程中，您會了解如何：

新增 MSAL 相依性。
建立設定檔。
建立 MSAL SDK 執行個體。

必要條件

如果您尚未這麼做，請遵循使用原生驗證來登入範例 Android (Kotlin) 行動應用程式中的使用者中的指示，並在外部租用戶註冊應用程式。請務必完成下列步驟：
- 註冊應用程式。
- 啟用公用用戶端和原生驗證流程。
- 授與 API 權限。
- 建立使用者流程。
- 將應用程式與使用者流程建立關聯。
一個 Android 專案。如果您沒有 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.+'
    //...
}

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

建立設定檔

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

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

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

在 auth_config_native_auth.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 
  } 
} 
 //...

將下列預留位置取代為您從 Microsoft Entra 系統管理中心取得的租用戶值：
- 將 Enter_the_Application_Id_Here 取代為您稍早所註冊應用程式的應用程式 (用戶端) 識別碼。
- 將 Enter_the_Tenant_Subdomain_Here 取代為目錄 (租用戶) 子網域。例如，如果您的租用戶主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶名稱，請了解如何讀取租用戶詳細資料。
挑戰類型是值清單，應用程式會使用這些值，來通知 Microsoft Entra 有關其支援的驗證方法。
- 針對具有電子郵件一次性密碼的註冊和登入流程，請使用 ["oob"]。
- 針對具有電子郵件和密碼的註冊和登入流程，請使用 ["oob","password"]。
- 針對自助式密碼重設 (SSPR)，請使用 ["oob"]。
深入了解挑戰類型。

選用：記錄設定

藉由建立記錄回呼以在應用程式建立時開啟記錄，讓 SDK 可以輸出記錄。

import com.microsoft.identity.client.Logger

fun initialize(context: Context) {
        Logger.getInstance().setExternalLogger { tag, logLevel, message, containsPII ->
            Logs.append("$tag $logLevel $message")
        }
    }

若要設定記錄器，您必須在設定檔 auth_config_native_auth.json 中新增區段：

    //...
   { 
     "logging": { 
       "pii_enabled": false, 
       "log_level": "INFO", 
       "logcat_enabled": true 
     } 
   } 
    //...

logcat_enabled：啟用程式庫的記錄功能。
pii_enabled：指定是否記錄包含個人資料或組織資料的訊息。設定為 false 時，記錄不會包含個人資料。設定為 true 時，記錄可能包含個人資料。
log_level：用來決定要啟用的記錄層級。 Android 支援下列記錄層級：
1. 錯誤
2. 警告
3. INFO
4. VERBOSE

如需 MSAL 記錄的詳細資訊，請參閱 Android 版 MSAL 中的記錄。

建立原生驗證 MSAL SDK 執行個體

在 onCreate() 方法中，建立 MSAL 執行個體，讓應用程式可以透過原生驗證搭配您的租用戶執行驗證。 createNativeAuthPublicClientApplication() 方法會傳回稱為 authClient 的執行個體。以參數形式傳遞您稍早建立的 JSON 設定檔。

    //...
    authClient = PublicClientApplication.createNativeAuthPublicClientApplication( 
        this, 
        R.raw.auth_config_native_auth 
    )
    //...

您的程式碼看起來應該與下列程式碼片段類似：

    class MainActivity : AppCompatActivity() { 
        private lateinit var authClient: INativeAuthPublicClientApplication 
 
        override fun onCreate(savedInstanceState: Bundle?) { 
            super.onCreate(savedInstanceState) 
            setContentView(R.layout.activity_main) 
 
            authClient = PublicClientApplication.createNativeAuthPublicClientApplication( 
                this, 
                R.raw.auth_config_native_auth 
            ) 
            getAccountState() 
        } 
 
        private fun getAccountState() {
            CoroutineScope(Dispatchers.Main).launch {
                val accountResult = authClient.getCurrentAccount()
                when (accountResult) {
                    is GetAccountResult.AccountFound -> {
                        displaySignedInState(accountResult.resultValue)
                    }
                    is GetAccountResult.NoAccountFound -> {
                        displaySignedOutState()
                    }
                }
            }
        } 
 
        private fun displaySignedInState(accountResult: AccountState) { 
            val accountName = accountResult.getAccount().username 
            val textView: TextView = findViewById(R.id.accountText) 
            textView.text = "Cached account found: $accountName" 
        } 
 
        private fun displaySignedOutState() { 
            val textView: TextView = findViewById(R.id.accountText) 
            textView.text = "No cached account found" 
        } 
    }

使用 getCurrentAccount() 擷取快取帳戶，這會傳回物件 accountResult。
如果發生帳戶處於持續性狀態，請使用 GetAccountResult.AccountFound 來顯示已登入狀態。
否則，請使用 GetAccountResult.NoAccountFound 來顯示已登出狀態。

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

後續步驟

教學課程：使用原生驗證在 Android 行動應用程式中新增註冊

共用方式為