Поделиться через

Руководство: Добавление регистрации в мобильном приложении 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
        )
}

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

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

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

Чтобы обрабатывать ошибки для метода 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 для 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.

  • Last updated on