Tutorial: Incorporar registro en una aplicación móvil Android mediante la autenticación nativa

Se aplica a: Círculo verde con un símbolo de marca de verificación blanca que indica que el siguiente contenido se aplica a los inquilinos externos. Inquilinos externos (más información)

En este tutorial se muestra cómo registrar a un usuario mediante el código de acceso de un solo uso de correo electrónico o el nombre de usuario (correo electrónico) y la contraseña en la aplicación móvil Android mediante la autenticación nativa. También aprenderá a recopilar atributos de usuario durante el registro, incluido un nombre de usuario (alias) y controlar los errores.

En este tutorial, harás lo siguiente:

  • Registre un usuario mediante el código de acceso de un solo uso de correo electrónico o el nombre de usuario (correo electrónico) y la contraseña.
  • Recopile atributos de usuario durante el registro, incluido un nombre de usuario (alias).
  • Control de errores de registro.

Prerrequisitos

Registro de un usuario

Para registrar a un usuario mediante el código de acceso de un solo uso de correo electrónico o el nombre de usuario (correo electrónico) y la contraseña, recopila un correo electrónico del usuario y, a continuación, envía un correo electrónico que contiene un código de acceso de un solo uso al usuario. El usuario escribe un código de acceso de un solo uso de correo electrónico válido para validar su nombre de usuario.

Para registrar un usuario, debe hacer lo siguiente:

  1. Cree una interfaz de usuario (UI) para:

    • Recopilar un correo electrónico del usuario. Agregar validación a las entradas para asegurarse de que el usuario escribe una dirección de correo electrónico válida.
    • Recopilar una contraseña si se registra con el nombre de usuario (correo electrónico) y la contraseña.
    • Recopile un nombre de usuario (alias) si la aplicación admite el inicio de sesión basado en alias.
    • Recopilar una contraseña de un solo uso por correo electrónico del usuario.
    • Si es necesario, recopile atributos de usuario.
    • Vuelva a enviar el código de acceso de un solo uso (recomendado).
    • Inicie el flujo de registro.

  2. En la aplicación, agregue un botón, cuyo evento de selección desencadene el siguiente fragmento de código:

    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
         }
    }
}
    • Use el método de instancia del SDK, signUp(parameters) para iniciar el flujo de registro.
    • Para registrarse con el nombre de usuario (dirección de correo electrónico) y la contraseña, cree una instancia de NativeAuthSignUpParameters clase y asigne su nombre de usuario y contraseña.
    • El parámetro de registro, username, es la dirección de correo electrónico que recopila del usuario.
    • En el escenario más habitual, signUp(parameters) devuelve un resultado, SignUpResult.CodeRequired, que indica que el SDK espera que la aplicación envíe el código de un solo uso enviado a la dirección de correo electrónico del usuario.
    • El SignUpResult.CodeRequired objeto contiene una nueva referencia de estado, que puede recuperar a través de actionResult.nextState.
    • El nuevo estado proporciona acceso a dos métodos nuevos:
      • submitCode() envía el código de acceso de un solo uso de correo electrónico que recopila la aplicación del usuario.
      • resendCode() vuelve a enviar el código de acceso de un solo uso por correo electrónico si el usuario no recibe el código.
    • El submitCode() devuelve SignUpResult.Complete, que indica que el flujo está completo y que el usuario se ha registrado.
    • El signUp(parameters) también puede devolver SignUpError para indicar que se ha producido un error.

Recopilación de atributos de usuario durante el registro

Tanto si registras a un usuario mediante un código de un solo uso de correo electrónico o un nombre de usuario (correo electrónico) y contraseña, puedes recopilar atributos de usuario antes de que se cree la cuenta del usuario.

  • La instancia de NativeAuthSignUpParameters acepta un parámetro 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)
        //...
    }

  • El Android SDK proporciona una clase de utilidad UserAttribute.Builder que se usa para crear atributos de usuario. Por ejemplo, para enviar atributos de usuario de ciudad y país, use el siguiente fragmento de código para compilar la variable userAttributes:

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

    Los nombres de método de la clase UserAttribute.Builder son los mismos que los nombres programables de los atributos de usuario que compilan. Obtenga más información sobre generador de atributos de Android SDK.

  • El método signUp(parameters) puede devolver SignUpResult.AttributesRequired para indicar que la aplicación debe enviar uno o varios atributos necesarios antes de que Microsoft Entra cree una cuenta. El administrador configura estos atributos como obligatorios en el Centro de administración Microsoft Entra. Microsoft Entra no solicita explícitamente atributos de usuario opcionales.

  • El resultado del SignUpResult.AttributesRequired contiene un parámetro requiredAttributes. requiredAttributes es una lista de objetos RequiredUserAttribute que contiene detalles sobre los atributos de usuario que la aplicación debe enviar. Para controlar actionResult is SignUpResult.AttributesRequired, use el siguiente fragmento de código:

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

Recopilar un nombre de usuario (alias) durante el registro

El nombre de usuario (alias) es un atributo de usuario especial. Al igual que otros atributos, como la ciudad o el país, se recopila al registrarse. A diferencia de esos atributos, el usuario puede usar posteriormente el alias para iniciar sesión. El alias (por ejemplo, "johndoe") proporciona a los usuarios una manera más corta y fácil de iniciar sesión que su dirección de correo electrónico.

El nombre de usuario (alias) no reemplaza el nombre de usuario (correo electrónico). Durante el registro, la aplicación siempre debe recopilar el nombre de usuario (correo electrónico) como identificador principal y recopila el alias como atributo junto con el correo electrónico. Al iniciar sesión, el usuario puede elegir iniciar sesión con su nombre de usuario (correo electrónico) o con su nombre de usuario (alias).

Cuando el atributo de usuario integrado Username está habilitado en el flujo de usuario de registro, el SDK lo acepta a través del mismo UserAttributes generador usado para otros atributos, mediante el flatUsername() método . Puede pasar el nombre de usuario (alias) directamente en la llamada de registro para que el usuario no tenga que pasar por un paso independiente requerido por atributos.

Para recopilar un nombre de usuario (alias), agregue un campo de entrada para el nombre de usuario en la interfaz de usuario de registro junto con el campo de correo electrónico y, a continuación, pase el alias como atributo en la llamada de registro:

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

Para los flujos de código de acceso de un solo uso (sin contraseña) de correo electrónico, use signUp en lugar de signUpUsingPassword:

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

Manejo de errores de inscripción

Durante el registro, no todas las acciones se realizan correctamente. Por ejemplo, el usuario podría intentar registrarse con una dirección de correo electrónico ya usada o enviar un código de acceso de un solo uso de correo electrónico no válido.

Control del error de inicio de registro

Para controlar los errores del método signUp(), use el siguiente fragmento de código:

 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) puede devolver SignUpError.

  • SignUpError indica un resultado de acción incorrecto devuelto por signUp() y no incluirá una referencia al nuevo estado.

  • Si actionResult is SignUpError, el SDK de Android de la Biblioteca de autenticación de Microsoft (MSAL) proporciona métodos de utilidad para analizar más a fondo los errores específicos:

    • El método isUserAlreadyExists() comprueba si el nombre de usuario o alias ya se ha usado para crear una cuenta.
    • isInvalidAttributes() comprueba si uno o varios atributos que la aplicación envió no han podido validarse, por ejemplo, si el tipo de datos es incorrecto. Contiene un parámetro invalidAttributes, que es una lista de todos los atributos que envió la aplicación, pero que no superaron la validación.
    • isInvalidPassword() comprueba si la contraseña no es válida, como cuando la contraseña no cumple todos los requisitos de complejidad de la contraseña. Obtenga más información sobre las directivas de contraseña de Microsoft Entra
    • isInvalidUsername() comprueba si el nombre de usuario no es válido, como cuando el correo electrónico del usuario no es válido.
    • isBrowserRequired() comprueba si se necesita un navegador (alternativa web) para completar el flujo de autenticación. Este escenario se produce cuando la autenticación nativa no es suficiente para completar el flujo de autenticación. Por ejemplo, un administrador configura el correo electrónico y la contraseña como método de autenticación, pero la aplicación no puede enviar la contraseña como un tipo de desafío o no la admite. Sigue los pasos de Implementar el mecanismo alternativo web en la aplicación Android para gestionar este caso.
    • isAuthNotSupported() comprueba si la aplicación envía un tipo de desafío que Microsoft Entra no admite, es decir, un valor de tipo de desafío distinto de oob o password. Obtenga más información sobre los tipos de desafío.

    Notifique al usuario que el correo electrónico ya está en uso o que algunos atributos no son válidos mediante un mensaje descriptivo en la interfaz de usuario de la aplicación.

  • Para controlar el error de atributos no válidos, use el siguiente fragmento de código:

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

Control del error de código de acceso de un solo uso de envío de correo electrónico

Para controlar los errores del método submitCode(), use el siguiente fragmento de código:

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() puede devolver SubmitCodeError.

  • Use el método isInvalidCode() para comprobar si hay un error específico, por ejemplo, el código enviado no es válido. En este caso, se debe usar la referencia de estado anterior para volver a ejecutar la acción.

  • Para recuperar un nuevo código de acceso de un solo uso de correo electrónico, use el siguiente fragmento de código:

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

Asegúrese de incluir las instrucciones de importación. Android Studio debe incluir automáticamente las instrucciones de importación.

Ha completado todos los pasos necesarios para registrar un usuario en la aplicación. Compile y ejecute su aplicación. Si todo está configurado correctamente, debería poder registrar al usuario mediante el código de acceso de un solo uso de correo electrónico o correo electrónico y contraseña, y recopilar atributos de usuario, incluido un nombre de usuario (alias).

Opcional: Iniciar sesión después de un flujo de registro

Después de un flujo de registro correcto, puede iniciar sesión de un usuario sin iniciar un flujo de inicio de sesión. Si el usuario se registró con un nombre de usuario (alias), puede iniciar sesión mediante su dirección de correo electrónico o su alias. Obtenga más información en el artículo Tutorial: Iniciar sesión del usuario después de registrarse en Android.

Pasos siguientes

Tutorial: Adición de inicio y cierre de sesión con código de acceso de un solo uso por correo electrónico en una aplicación Android.

  • Last updated on