使用原生驗證在Android應用程式中新增註冊 - Microsoft identity platform

發行項
03/05/2025

適用於：白色圓圈，內有灰色 X 符號內部使用者綠色圓圈，內有白色勾選符號。外部使用者（深入了解）

本教學課程示範如何使用電子郵件一次性密碼或使用者名稱（電子郵件）和密碼註冊使用者，並使用原生驗證收集 Android 行動裝置應用程式中的使用者屬性。

在本教學課程中，您將瞭解如何：

使用電子郵件一次性密碼或使用者名稱（電子郵件）和密碼註冊使用者。
在註冊期間收集用戶屬性。
處理註冊錯誤。

先決條件

完成教學課程：準備Android應用程式以進行原生驗證一文中的步驟。
如果您要在註冊期間收集使用者屬性，請在建立註冊和登入使用者流程時設定使用者屬性，。

若要使用電子郵件一次性密碼或使用者名稱（電子郵件）和密碼註冊使用者，請從使用者收集電子郵件，然後將包含電子郵件一次性密碼的電子郵件傳送給使用者。使用者輸入有效的電子郵件一次性密碼來驗證其用戶名稱。

若要註冊使用者，您需要：

建立使用者介面（UI）以：
- 從使用者收集電子郵件。將驗證新增至您的輸入，以確保使用者輸入有效的電子郵件位址。
- 如果您使用使用者名稱（電子郵件）和密碼註冊，請收集密碼。
- 從使用者收集電子郵件一次性密碼。
- 如有需要，請收集用戶屬性。
- 重新傳送一次性密碼（建議）。
- 啟動註冊流程。
在您的應用程式中，新增按鈕，其 select 事件會觸發下列代碼段：
```
CoroutineScope(Dispatchers.Main).launch {
     val parameters = NativeAuthSignUpParameters(username = email)
     // Assign 'password' param if you sign in with username (email) and password
     // parameters.password = password
     val actionResult: SignUpResult = authClient.signUp(parameters)

     if (actionResult is SignUpResult.CodeRequired) {
         val nextState = actionResult.nextState
         val submitCodeActionResult = nextState.submitCode(
            code = code
         )
         if (submitCodeActionResult is SignUpResult.Complete) {
            // Handle sign up success
         }
    }
}
```
- 使用 SDK 的實例方法，signUp(parameters) 啟動註冊流程。
- 若要使用使用者名稱（電子郵件位址）和密碼註冊，請建立 NativeAuthSignUpParameters 類別的實例，並指派您的使用者名稱和密碼。
- 註冊參數 username是您從使用者收集的電子郵件位址。
- 在最常見的案例中，signUp(parameters) 會傳回結果，SignUpResult.CodeRequired，這表示 SDK 預期應用程式會提交傳送給使用者電子郵件地址的電子郵件一次性密碼。
- SignUpResult.CodeRequired 物件包含新的狀態參考，我們可以透過 actionResult.nextState來擷取。
- 新的狀態可讓我們存取兩個新的方法：
  - submitCode() 提交應用程式向使用者收集的電子郵件一次性密碼。
  - resendCode() 如果使用者未收到代碼，則重新傳送電子郵件一次性密碼。
- submitCode() 會傳回 SignUpResult.Complete，表示流程已完成且用戶已註冊。
- signUp(parameters) 也可以傳回 SignUpError，表示發生錯誤。

無論您是使用電子郵件一次性密碼或使用者名稱（電子郵件）和密碼註冊使用者，都可以在建立用戶帳戶之前收集使用者屬性：

NativeAuthSignUpParameters 實例接受 attributes 參數：

    CoroutineScope(Dispatchers.Main).launch {
        val parameters = NativeAuthSignUpParameters(username = email)
        // Assign 'password' param if you sign in with username (email) and password
        // parameters.password = password
        parameters.attributes = userAttributes
        val actionResult: SignUpResult = authClient.signUp(parameters)
        //...
    }

Android SDK 會提供公用程式類別 UserAttribute.Builder，讓您用來建立用戶屬性。例如，若要提交城市和 國家/地區 使用者屬性，請使用下列代碼段來建置 userAttributes 變數：
```
     val userAttributes = UserAttributes.Builder ()
    .country(country) 
    .city(city) 
    .build()   
```
UserAttribute.Builder 類別中的方法名稱與所建置之用戶屬性的可程式化名稱相同。深入瞭解 Android SDK 屬性產生器。
signUp(parameters) 方法可以傳回 SignUpResult.AttributesRequired，指出應用程式必須先提交一或多個必要的屬性，才能Microsoft Entra 建立帳戶。系統管理員會在 Microsoft Entra 系統管理中心中將這些屬性設定為必要屬性。 Microsoft Entra 不會明確要求選擇性用戶屬性。

SignUpResult.AttributesRequired 結果包含 requiredAttributes 參數。 requiredAttributes 是一份 RequiredUserAttribute 物件清單，其中包含應用程式需要提交之使用者屬性的詳細數據。若要處理 actionResult is SignUpResult.AttributesRequired，請使用下列代碼段：

val parameters = NativeAuthSignUpParameters(username = email)
// Assign 'password' param if you sign in with username (email) and password
// parameters.password = password
parameters.attributes = userAttributes
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpResult.AttributesRequired) {
        val requiredAttributes = actionResult.requiredAttributes 
        // Handle "attributes required" result 
        val nextState = actionResult.nextState
        nextState.submitAttributes(
            attributes = moreAttributes
        )
}

註冊期間，並非所有動作都成功。例如，使用者可能會嘗試使用已使用的電子郵件地址註冊，或提交無效的電子郵件一次性密碼。

若要處理 signUp() 方法的錯誤，請使用下列代碼段：

 val parameters = NativeAuthSignUpParameters(username = email)
 // Assign 'password' param if you sign in with username (email) and password
 // parameters.password = password
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpResult.CodeRequired) {
    // Next step: submit code
} else if (actionResult is SignUpError) {
     when {
         actionResult.isUserAlreadyExists() -> {
             // Handle "user already exists" error
         }
         else -> {
             // Handle other errors
         }
     }
}

signUp(parameters) 可以傳回 SignUpError。
SignUpError 表示 signUp() 傳回的動作結果失敗，且不包含新狀態的參考。
如果 actionResult is SignUpError，MSAL Android SDK 會提供公用程式方法，讓您進一步分析特定錯誤：
- 方法 isUserAlreadyExists() 會檢查用戶名稱是否已經用來建立帳戶。
- isInvalidAttributes() 檢查應用程式提交的一或多個屬性是否驗證失敗，例如錯誤的數據類型。它包含 invalidAttributes 參數，這是應用程式提交但驗證失敗的所有屬性清單。
- isInvalidPassword() 檢查密碼無效，例如當密碼不符合所有密碼複雜度需求時。深入瞭解 Microsoft Entra 的密碼原則
- isInvalidUsername() 檢查使用者名稱是否無效，例如當使用者電子郵件無效時。
- isBrowserRequired() 檢查是否需要使用瀏覽器（作為網頁備援）來完成驗證流程。當原生驗證不足以完成驗證流程時，就會發生此案例。例如，系統管理員將電子郵件和密碼設為驗證方法，但應用程式無法傳送密碼作為挑戰類型，或僅僅不支援這種挑戰類型。使用在 Android 應用程式中支援網頁後備方案的步驟來處理發生情況時的場景。
- isAuthNotSupported() 會檢查應用程式是否傳送 Microsoft Entra 不支援的挑戰類型，也就是除了 oob 或密碼之外的挑戰類型值。深入瞭解挑戰類型。
請在應用程式的介面中使用友善的訊息通知使用者，電子郵件已被使用或某些屬性無效。

若要處理無效屬性的錯誤，請使用下列代碼段：

val parameters = NativeAuthSignUpParameters(username = email)
// Assign 'password' param if you sign in with username (email) and password
// parameters.password = password
parameters.attributes = userAttributes
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpError && actionResult.isInvalidAttributes()) {
    val invalidAttributes = actionResult.invalidAttributes

    // Handle "invalid attributes" error, this time submit valid attributes
    val parameters = NativeAuthSignUpParameters(username = email)
    // Assign 'password' param if you sign in with username (email) and password
    // parameters.password = password
    parameters.attributes = userAttributes
    authClient.signUp(parameters)
} 
//...

處理提交電子郵件一次性密碼錯誤

若要處理 submitCode() 方法的錯誤，請使用下列代碼段：

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignUpResult.Complete) {
    // Sign up flow complete, handle success state.
} else if (submitCodeActionResult is SubmitCodeError) {
    // Handle errors under SubmitCodeError
     when {
         submitCodeActionResult.isInvalidCode() -> {
             // Handle "code invalid" error
         }
         else -> {
             // Handle other errors
         }
     }
}

submitCode() 可以傳回 SubmitCodeError。
使用 isInvalidCode() 方法來檢查特定錯誤，例如送出的程式代碼無效。在此情況下，必須使用先前的狀態參考來重新執行動作。

若要擷取新的電子郵件一次性密碼，請使用下列代碼段：

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SubmitCodeError && submitCodeActionResult.isInvalidCode()) {
    // Inform the user that the submitted code was incorrect or invalid and ask for a new code to be supplied
    val newCode = retrieveNewCode()
    nextState.submitCode(
        code = newCode
    )
}

請確保您包含匯入語句。 Android Studio 應該會自動幫您加入匯入語句。

您已完成所有必要步驟，以成功將用戶註冊到您的應用程式。建置並執行您的應用程式。如果一切順利，您應該能夠使用電子郵件一次性密碼或電子郵件和密碼成功註冊使用者。

成功註冊流程之後，您可以登入使用者，而不需要起始登入流程。若要進一步瞭解，請參閱教學課程：在 Android 文章中註冊後登入使用者的步驟。

後續步驟

教程：在 Android 應用程式中新增使用電子郵件一次性密碼的登入和登出功能。

共用方式為

先決條件

處理提交電子郵件一次性密碼錯誤

後續步驟

意見反應

其他資源

共用方式為

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

先決條件

註冊使用者

在註冊期間收集用戶屬性

處理註冊錯誤

處理啟動註冊錯誤

處理提交電子郵件一次性密碼錯誤

可以選擇在註冊流程後登入

後續步驟

意見反應

其他資源