Руководство: Добавление регистрации в мобильном приложении Android с помощью нативной аутентификации

Применяется: Внешние клиенты (дополнительные сведения)

В этом руководстве показано, как зарегистрировать пользователя в мобильном приложении Android с помощью встроенной аутентификации, используя одноразовый код, отправляемый по электронной почте, или имя пользователя (адрес электронной почты) и пароль. Вы также узнаете, как собирать атрибуты пользователей во время регистрации, включая имя пользователя (псевдоним) и обрабатывать ошибки.

Изучив это руководство, вы:

• Зарегистрируйте пользователя с помощью однократного секретного кода электронной почты или имени пользователя (электронной почты) и пароля.
• Сбор атрибутов пользователей во время регистрации, включая имя пользователя (псевдоним).
• Обработка ошибок регистрации.

Необходимые условия

• Выполните шаги в руководстве : Подготовьте приложение Android для собственной проверки подлинности.
• Если вы хотите собирать атрибуты пользователей во время регистрации, настройте атрибуты пользователя при создании потока регистрации и входа в систему.
• Чтобы собирать имя пользователя (псевдоним) при регистрации, включите встроенный атрибут пользователя Имя пользователя в пользовательском потоке регистрации вашего клиента.

Регистрация пользователя

Чтобы зарегистрировать пользователя с помощью одноразового кода, отправленного по электронной почте, либо имени пользователя (адреса электронной почты) и пароля, вы запрашиваете у пользователя адрес электронной почты, а затем отправляете ему электронное письмо с одноразовым кодом. Пользователь вводит действительный одноразовый код электронной почты для проверки имени пользователя.

Чтобы зарегистрировать пользователя, необходимо выполнить следующие действия.

1. Создайте пользовательский интерфейс для:

   • Получение адреса электронной почты пользователя. Добавьте проверку в входные данные, чтобы убедиться, что пользователь вводит допустимый адрес электронной почты.
   • Соберите пароль при регистрации с помощью имени пользователя (электронной почты) и пароля.
   • Соберите имя пользователя (псевдоним), если ваше приложение поддерживает вход на основе псевдонима.
   • Соберите одноразовый секретный код электронной почты от пользователя.
   • При необходимости соберите атрибуты пользователя.
   • Повторно отправить одноразовый секретный код (рекомендуется).
   • Запустите поток регистрации.

2. В приложении добавьте кнопку, событие выбора которой активирует следующий фрагмент кода:

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

• Пакет SDK для Android предоставляет класс служебной программы UserAttribute.Builder, который используется для создания атрибутов пользователя. Например, чтобы отправить атрибуты города и страны пользователя, используйте следующий фрагмент кода для построения переменной userAttributes.

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

  Имена методов в классе UserAttribute.Builder совпадают с программируемыми именами создаваемых атрибутов пользователя. Дополнительные сведения об построителе атрибутов пакета SDK для Android.

• Метод 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
          )
  }
  

Сбор имени пользователя (псевдонима) во время регистрации

Имя пользователя (псевдоним) — это специальный атрибут пользователя. Как и другие данные, такие как город или страна, вы собираете эти данные при регистрации. В отличие от этих атрибутов, пользователь может позже использовать псевдоним для входа. Псевдоним (например, johndoe) дает пользователям более короткий, понятный способ входа, чем их адрес электронной почты.

Имя пользователя (псевдоним) не заменяет имя пользователя (электронная почта). Во время регистрации приложение всегда должно собирать имя пользователя (электронную почту) в качестве основного идентификатора, и он собирает псевдоним в качестве атрибута вместе с электронной почтой. При входе пользователь может выполнить вход с помощью имени пользователя (электронной почты) или имени пользователя (псевдонима).

Если в потоке регистрации пользователя включён встроенный атрибут пользователя Username, SDK позволяет передать его через тот же построитель UserAttributes, который используется для других атрибутов, с помощью метода flatUsername(). Вы можете передать имя пользователя (псевдоним) непосредственно при вызове регистрации, чтобы пользователю не пришлось проходить отдельный этап, на котором требуется указать атрибуты.

Чтобы собрать имя пользователя (псевдоним), добавьте поле ввода для имени пользователя в пользовательском интерфейсе регистрации вместе с полем электронной почты, а затем передайте псевдоним в качестве атрибута в вызове регистрации:

val email = binding.emailText.text.toString()
val password = binding.passwordText.text.toString()
val username = binding.usernameText.text.toString()

val attributes = UserAttributes.Builder()
    .flatUsername(username)
    .build()

CoroutineScope(Dispatchers.Main).launch {
    val actionResult = authClient.signUpUsingPassword(
        username = email,
        password = password,
        attributes = attributes
    )

    when (actionResult) {
        is SignUpResult.CodeRequired -> {
            // Navigate to code verification
            navigateToCodeVerification(actionResult.nextState)
        }
        is SignUpUsingPasswordError -> {
            handleSignUpError(actionResult)
        }
    }
}

Для однократных потоков секретного кода электронной почты (без пароля) используйте signUp вместо signUpUsingPassword:

val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
)

Обработка ошибок регистрации

Во время регистрации не все действия выполняются успешно. Например, пользователь может попытаться зарегистрироваться с уже использованным адресом электронной почты или отправить недопустимый секретный код электронной почты.

Обработка ошибки при начале регистрации

Чтобы обрабатывать ошибки для метода 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, пакет SDK Microsoft Authentication Library (MSAL) для Android предоставляет служебные методы для более детального анализа конкретных ошибок:

  • Метод 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.