Tutorial: Adicionar inscrição em um aplicativo móvel Android usando autenticação nativa.

Aplica-se a: Círculo verde com um símbolo de marca de seleção branca que indica que o conteúdo a seguir se aplica a locatários externos. Locatários externos (saiba mais)

Este tutorial demonstra como inscrever um usuário usando senha única por email ou nome de usuário (email) e senha em seu aplicativo móvel Android usando autenticação nativa. Você também aprenderá como coletar atributos do usuário durante o cadastro, incluindo um nome de usuário (alias), e tratar erros.

Neste tutorial, você:

  • Inscrever um usuário usando uma senha de uso único por email ou um nome de usuário (email) e senha.
  • Colete atributos de usuário durante a inscrição, incluindo um nome de usuário (alias).
  • Lidar com erros de inscrição.

Pré-requisitos

Inscrever um usuário

Para inscrever um usuário usando a senha única de email ou nome de usuário (email) e senha, você coleta um email do usuário e, em seguida, envia um email contendo uma senha única de email para o usuário. O usuário insere uma senha de uso único por email válida para validar seu nome de usuário.

Para inscrever um usuário, você precisa:

  1. Criar uma interface do usuário (IU) para:

    • Coletar um email do usuário. Adicionar validação às suas entradas de dados para garantir que o usuário insira um endereço de email válido.
    • Colete uma senha se você se inscrever com o nome de usuário (email) e a senha.
    • Colete um nome de usuário (alias) se o aplicativo der suporte à entrada baseada em alias.
    • Coletar uma senha de uso único por email do usuário.
    • Se necessário, coletar atributos de usuário.
    • Reenviar senha de uso único (recomendado).
    • Iniciar o fluxo de inscrição.

  2. Em seu aplicativo, adicione um botão, cujo evento de seleção dispara o seguinte trecho 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 o método de instância do SDK, signUp(parameters) para iniciar o fluxo de inscrição.
    • Para se inscrever usando o nome de usuário (endereço de email) e a senha, crie uma instância de NativeAuthSignUpParameters classe e atribua seu nome de usuário e senha.
    • O parâmetro de inscrição, username, é o endereço de email coletado do usuário.
    • No cenário mais comum, o signUp(parameters) retorna um resultado, SignUpResult.CodeRequired, que indica que o SDK espera que o aplicativo envie o código de uso único enviado por e-mail para o endereço de e-mail do usuário.
    • O SignUpResult.CodeRequired objeto contém uma nova referência de estado, que você pode recuperar por meio de actionResult.nextState.
    • O novo estado fornece acesso a dois novos métodos:
      • submitCode() envia a senha única de email que o aplicativo coleta do usuário.
      • resendCode() reenviará a senha única do email se o usuário não receber o código.
    • O submitCode() retorna SignUpResult.Complete, o que indica que o fluxo foi concluído e o usuário se inscreveu.
    • O signUp(parameters) também pode retornar SignUpError para indicar que ocorreu um erro.

Coletar atributos de usuário durante a inscrição

Se você inscrever um usuário usando senha de uso único por email ou nome de usuário (email) e senha, poderá coletar atributos de usuário antes que a conta de um usuário seja criada:

  • A instância de NativeAuthSignUpParameters aceita um 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)
        //...
    }

  • O SDK do Android fornece uma classe de utilitário UserAttribute.Builder que você usa para criar atributos de usuário. Por exemplo, para enviar os atributos de usuário cidade e país, use o snippet de código a seguir para criar a variável userAttributes:

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

    Os nomes de método na classe UserAttribute.Builder são iguais aos nomes programáveis dos atributos de usuário que eles criam. Saiba mais sobre o construtor de atributos do SDK do Android.

  • O método signUp(parameters) pode retornar SignUpResult.AttributesRequired para indicar que o aplicativo precisa enviar um ou mais atributos necessários antes que o Microsoft Entra crie uma conta. Esses atributos são configurados pelo administrador como obrigatórios no centro de administração do Microsoft Entra. O Microsoft Entra não solicita explicitamente atributos de usuário opcionais.

  • O resultado SignUpResult.AttributesRequired contém um parâmetro requiredAttributes. requiredAttributes é uma lista de objetos RequiredUserAttribute que contém detalhes sobre os atributos de usuário que o aplicativo precisa enviar. Para identificar actionResult is SignUpResult.AttributesRequired, use o seguinte snippet 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
        )
}

Coletar um nome de usuário (alias) durante a inscrição

O nome de usuário (alias) é um atributo de usuário especial. Como outros atributos, como cidade ou país, você a coleta durante a inscrição. Ao contrário desses atributos, o usuário pode usar posteriormente o alias para entrar. O alias (por exemplo, "johndoe") oferece aos usuários uma maneira mais curta e amigável de entrar do que seu endereço de email.

O nome de usuário (alias) não substitui o nome de usuário (email). Durante a inscrição, o aplicativo sempre deve coletar o nome de usuário (email) como o identificador primário e coleta o alias como um atributo junto com o email. Na entrada, o usuário pode optar por entrar com seu nome de usuário (email) ou seu nome de usuário (alias).

Quando o atributo de usuário interno Username está habilitado no fluxo de usuário de inscrição, o SDK o aceita por meio do mesmo UserAttributes construtor usado para outros atributos usando o flatUsername() método. Você pode passar o nome de usuário (alias) diretamente na chamada de inscrição para que o usuário não precise passar por uma etapa separada exigida por atributos.

Para coletar um nome de usuário (alias), adicione um campo de entrada para o nome de usuário na interface do usuário de inscrição ao lado do campo de email e, em seguida, passe o alias como um atributo na chamada de inscrição:

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 fluxos de senha única de email (sem senha), use signUp em vez de signUpUsingPassword:

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

Tratar erros de inscrição

Durante a inscrição, nem todas as ações são bem-sucedidas. Por exemplo, o usuário pode tentar se inscrever com um endereço de email já usado ou enviar uma senha única de email inválida.

Tratar um erro de inscrição inicial

Para lidar com erros para o método signUp(), use o seguinte trecho 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) pode retornar SignUpError.

  • SignUpError indica um resultado de ação malsucedido retornado por signUp() e não inclui uma referência ao novo estado.

  • Se actionResult is SignUpError, o SDK do Biblioteca do Microsoft Authenticator (MSAL) para Android fornece métodos utilitários para analisar mais detalhadamente os erros específicos:

    • O método isUserAlreadyExists() verifica se o nome de usuário ou alias já foi usado para criar uma conta.
    • isInvalidAttributes() verifica se um ou mais atributos que o aplicativo enviou falharam na validação, como tipo de dados incorreto. Ele contém um invalidAttributes parâmetro, que é uma lista de todos os atributos enviados pelo aplicativo, mas que falhou na validação.
    • isInvalidPassword() verifica se a senha é inválida, como quando a senha não atende a todos os requisitos de complexidade de senha. Saiba mais sobre as políticas de senha do Microsoft Entra
    • isInvalidUsername() verifica se o nome de usuário é inválido, como quando o email do usuário é inválido.
    • isBrowserRequired() verifica se é necessário um navegador (alternativa via Web) para concluir o fluxo de autenticação. Esse cenário ocorre quando a autenticação nativa não é suficiente para concluir o fluxo de autenticação. Por exemplo, um administrador configura o email e a senha como o método de autenticação, mas o aplicativo não envia senha como um tipo de desafio ou não dá suporte a ela. Use as etapas em Suporte a fallback da Web no app Android para lidar com esse cenário.
    • isAuthNotSupported() verifica se o aplicativo envia um tipo de desafio que o Microsoft Entra não dá suporte, que é um valor de tipo de desafio diferente de oob ou senha. Saiba mais sobre tipos de desafio.

    Notifique o usuário de que o email já está em uso ou que alguns atributos são inválidos usando uma mensagem amigável na interface do usuário do aplicativo.

  • Para lidar com o erro de atributos inválidos, use o seguinte snippet 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)
} 
//...

Tratar um erro de senha de uso único por email ao enviar

Para lidar com erros para o método submitCode(), use o seguinte trecho 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() pode retornar SubmitCodeError.

  • Use o método isInvalidCode() para verificar se o erro específico, como o código enviado, é inválido. Nesse caso, a referência de estado anterior deve ser usada para executar a ação novamente.

  • Para recuperar uma nova senha única de email, use o seguinte trecho 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
    )
}

Certifique-se de incluir as declarações de importação. O Android Studio deve incluir automaticamente para você as instruções de importação.

Você concluiu todas as etapas necessárias para inscrever um usuário em seu aplicativo. Compile e execute seu aplicativo. Se tudo estiver configurado corretamente, você deverá ser capaz de inscrever o usuário usando senha única de email ou email e senha e coletar atributos de usuário, incluindo um nome de usuário (alias).

Opcional: entrar após um processo de cadastro

Após um fluxo de cadastro bem-sucedido, você pode autenticar um usuário sem iniciar um fluxo de login. Se o usuário se inscreveu com um nome de usuário (alias), ele poderá entrar usando seu endereço de email ou seu alias. Saiba mais no Tutorial: conectar um usuário após o cadastro em um dispositivo Android.

Próximas etapas

Tutorial: Adicionar entrada e saída com senha de uso único por email no aplicativo Android.

  • Last updated on