Samouczek: dodawanie rejestracji w aplikacji mobilnej systemu Android przy użyciu uwierzytelniania natywnego

W tym samouczku pokazano, jak zarejestrować użytkownika przy użyciu jednorazowego kodu dostępu lub nazwy użytkownika (adresu e-mail) oraz hasła oraz zbierać atrybuty użytkownika w aplikacji mobilnej systemu Android przy użyciu uwierzytelniania natywnego.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

• Zarejestruj użytkownika przy użyciu jednorazowego kodu dostępu lub nazwy użytkownika (e-mail) i hasła.
• Zbierz atrybuty użytkownika podczas rejestracji.
• Obsługa błędów rejestracji.

Wymagania wstępne

• Wykonaj kroki opisane w artykule Samouczek: przygotowywanie aplikacji systemu Android do uwierzytelniania natywnego.
• Jeśli chcesz zbierać atrybuty użytkownika podczas rejestracji, skonfiguruj atrybuty użytkownika podczas tworzenia przepływu użytkownika rejestracji i logowania.

Tworzenie konta użytkownika

Aby zarejestrować użytkownika przy użyciu jednorazowego kodu dostępu lub nazwy użytkownika (adresu e-mail) i hasła, należy zebrać wiadomość e-mail od użytkownika, a następnie wysłać wiadomość e-mail zawierającą jednorazowy kod dostępu do użytkownika. Użytkownik wprowadza prawidłowy kod dostępu jednorazowego wiadomości e-mail, aby zweryfikować swoją nazwę użytkownika.

Aby zarejestrować użytkownika, musisz:

1. Utwórz interfejs użytkownika w celu:

   • Zbierz wiadomość e-mail od użytkownika. Dodaj walidację do danych wejściowych, aby upewnić się, że użytkownik wprowadzi prawidłowy adres e-mail.
   • Zbierz hasło, jeśli zarejestrujesz się przy użyciu nazwy użytkownika (e-mail) i hasła.
   • Zbierz jednorazowy kod dostępu wiadomości e-mail od użytkownika.
   • W razie potrzeby zbierz atrybuty użytkownika.
   • Wyślij ponownie jednorazowy kod dostępu (zalecane).
   • Uruchom przepływ rejestracji.

2. W aplikacji dodaj przycisk, którego wybranie powoduje wyzwolenie następującego fragmentu kodu:

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

   • Użyj metody wystąpienia zestawu SDK, signUp(parameters) aby uruchomić przepływ rejestracji.
   • Aby zarejestrować się przy użyciu nazwy użytkownika (adresu e-mail) i hasła, utwórz wystąpienie klasy NativeAuthSignUpParameters i przypisz swoją nazwę użytkownika i hasło.
   • Parametr rejestracji, username, to adres e-mail zbierany od użytkownika.
   • W najczęstszym scenariuszu signUp(parameters) zwraca wynik SignUpResult.CodeRequired, który wskazuje, że zestaw SDK oczekuje przesłania przez aplikację jednorazowego kodu dostępu wysyłanego na adres e-mail użytkownika.
   • Obiekt SignUpResult.CodeRequired zawiera nowe odwołanie do stanu, które możemy pobrać za pomocą actionResult.nextStatepolecenia .
   • Nowy stan daje nam dostęp do dwóch nowych metod:
     • submitCode() przesyła jednorazowy kod dostępu wiadomości e-mail zbierany przez aplikację od użytkownika.
     • resendCode() wysyła ponownie kod dostępu jednorazowego wiadomości e-mail, jeśli użytkownik nie otrzyma kodu.
   • submitCode()Zwraca wartość SignUpResult.Complete , która wskazuje, że przepływ został ukończony, a użytkownik został zarejestrowany.
   • signUp(parameters) może również zwrócić SignUpError, aby określić, że wystąpił błąd.

Zbieraj atrybuty użytkownika podczas rejestracji

Niezależnie od tego, czy rejestrujesz użytkownika przy użyciu jednorazowego kodu dostępu e-mail, czy nazwy użytkownika (poczty e-mail) i hasła, możesz zbierać atrybuty użytkownika przed utworzeniem konta użytkownika:

• Wystąpienie NativeAuthSignUpParameters akceptuje parametr 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)
          //...
      }
  

• Zestaw Android SDK udostępnia klasę UserAttribute.Builder narzędzi używaną do tworzenia atrybutów użytkownika. Aby na przykład przesłać atrybuty użytkownika miasta i kraju , użyj następującego fragmentu kodu, aby skompilować zmienną userAttributes :

       val userAttributes = UserAttributes.Builder ()
      .country(country) 
      .city(city) 
      .build()   
  

  Nazwy metod w UserAttribute.Builder klasie są takie same jak programowalne nazwy atrybutów użytkownika, które tworzą. Dowiedz się więcej o konstruktorze atrybutów zestawu SDK systemu Android.

• Metoda signUp(parameters) może zwrócić SignUpResult.AttributesRequired, aby wskazać, że aplikacja musi przesłać co najmniej jeden wymagany atrybut, zanim Microsoft Entra utworzy konto. Te atrybuty są konfigurowane przez administratora jako obowiązkowe w centrum administracyjnym firmy Microsoft Entra. Firma Microsoft Entra nie żąda jawnie opcjonalnych atrybutów użytkownika.

• Wynik SignUpResult.AttributesRequired zawiera requiredAttributes parametr. requiredAttributes to lista RequiredUserAttribute obiektów, które zawierają szczegółowe informacje o atrybutach użytkownika, które aplikacja musi przesłać. Aby obsłużyć actionResult is SignUpResult.AttributesRequiredmetodę , użyj następującego fragmentu kodu:

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

Obsługa błędów rejestracji

Podczas rejestracji nie wszystkie akcje kończą się powodzeniem. Na przykład użytkownik może próbować zarejestrować się przy użyciu już używanego adresu e-mail lub przesłać nieprawidłowy kod dostępu jednorazowego wiadomości e-mail.

Błąd obsługi uruchamiania rejestracji

Aby obsłużyć błędy dla signUp() metody, użyj następującego fragmentu kodu:

 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) może zwrócić wartość SignUpError.

• SignUpError wskazuje wynik nieudanej akcji zwrócony przez signUp() element i nie będzie zawierać odwołania do nowego stanu.

• Jeśli actionResult is SignUpErrorzestaw SDK biblioteki MSAL dla systemu Android udostępnia metody narzędziowe umożliwiające dalsze analizowanie określonych błędów:

  • Metoda isUserAlreadyExists() sprawdza, czy nazwa użytkownika została już użyta do utworzenia konta.
  • isInvalidAttributes() Sprawdza, czy co najmniej jeden atrybut przesłany przez aplikację zakończył się niepowodzeniem weryfikacji, na przykład nieprawidłowy typ danych. Zawiera invalidAttributes parametr, który jest listą wszystkich atrybutów przesłanych przez aplikacje, ale nie powiodła się walidacja.
  • isInvalidPassword() Sprawdź, czy hasło jest nieprawidłowe, na przykład gdy hasło nie spełnia wszystkich wymagań dotyczących złożoności hasła. Dowiedz się więcej o zasadach haseł firmy Microsoft Entra
  • isInvalidUsername() sprawdź, czy nazwa użytkownika jest nieprawidłowa, na przykład gdy adres e-mail użytkownika jest nieprawidłowy.
  • isBrowserRequired() sprawdza potrzebę korzystania z przeglądarki (rezerwowej w sieci Web), aby ukończyć przepływ uwierzytelniania. Ten scenariusz występuje, gdy uwierzytelnianie natywne nie jest wystarczające do ukończenia przepływu uwierzytelniania. Na przykład administrator konfiguruje adres e-mail i hasło jako metodę uwierzytelniania, ale aplikacja nie może wysłać hasła jako typu wyzwania lub po prostu nie obsługuje go. Wykonaj kroki opisane w temacie Obsługa rezerwowego w internecie w aplikacji dla systemu Android, aby obsłużyć scenariusz w takim przypadku.
  • isAuthNotSupported() Sprawdza, czy aplikacja wysyła typ wyzwania, którego firma Microsoft Entra nie obsługuje, jest to wartość typu wyzwania innego niż oob lub hasło. Dowiedz się więcej o typach wyzwań.

  Powiadom użytkownika, że wiadomość e-mail jest już używana lub niektóre atrybuty są nieprawidłowe, używając przyjaznej wiadomości w interfejsie użytkownika aplikacji.

• Aby obsłużyć błąd nieprawidłowych atrybutów, użyj następującego fragmentu kodu:

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

Obsługa jednorazowego kodu dostępu do przesyłania wiadomości e-mail

Aby obsłużyć błędy dla submitCode() metody, użyj następującego fragmentu kodu:

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() może zwrócić wartość SubmitCodeError.

• isInvalidCode() Użyj metody , aby sprawdzić konkretny błąd, taki jak przesłany kod jest nieprawidłowy. W takim przypadku należy użyć poprzedniego odwołania do stanu w celu ponownego wykonania akcji.

• Aby pobrać nowy kod dostępu jednorazowego wiadomości e-mail, użyj następującego fragmentu kodu:

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

Upewnij się, że dołączysz instrukcje importowania. Program Android Studio powinien automatycznie dołączać instrukcje importowania.

Wszystkie kroki niezbędne do pomyślnego zarejestrowania użytkownika w aplikacji zostały wykonane. Skompiluj i uruchom aplikację. Jeśli wszystko jest dobre, powinno być możliwe pomyślne zarejestrowanie użytkownika przy użyciu jednorazowego kodu dostępu lub wiadomości e-mail i hasła.

Opcjonalnie: Zaloguj się po przepływie rejestracji

Po pomyślnym przepływie rejestracji możesz zalogować się do użytkownika bez inicjowania przepływu logowania. Dowiedz się więcej w artykule Samouczek: logowanie użytkownika po zarejestrowaniu się w systemie Android .

Następne kroki

Samouczek: dodawanie logowania i wylogowywanie przy użyciu jednorazowego kodu dostępu poczty e-mail w aplikacji systemu Android.