使用原生驗證在 Android 應用程式中新增註冊 - Microsoft Entra External ID

發行項
02/07/2025

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

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

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

必要條件

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

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

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

建立使用者介面 (UI)：
- 收集使用者的電子郵件。將驗證新增至您的輸入，以確保使用者輸入有效的電子郵件地址。
- 如果您使用使用者名稱 (電子郵件) 和密碼註冊，請收集密碼。
- 從使用者收集電子郵件一次性密碼。
- 如有需要，請收集使用者屬性。
- 重新傳送一次性密碼 (建議)。
- 啟動註冊流程。
在您的應用程式中，新增按鈕，其選取事件會觸發下列程式碼片段：
```
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 應用程式中支援 Web 後援中的步驟來處理此類狀況。
- isAuthNotSupported() 會檢查應用程式是否傳送 Microsoft Entra 不支援的查問類型，即 oob 或 password 之外的查問類型值。深入了解挑戰類型。
透過在應用程式的 UI 中使用易記訊息來通知使用者電子郵件已在使用或某些屬性無效。

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

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
    )
}

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

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

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

下一步

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

共用方式為

必要條件

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

下一步

意見反應

其他資源

共用方式為

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

必要條件

註冊使用者

在註冊期間收集使用者屬性

處理註冊錯誤

處理啟動註冊錯誤

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

選用：在註冊流程之後登入

下一步

意見反應

其他資源