Compartilhar via

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

Aplica-se a: Círculo branco com um símbolo de X cinza. Inquilinos da força de trabalho Círculo verde com um símbolo de verificação branca. Inquilinos externos (saiba mais)

Este tutorial demonstra como inscrever um usuário usando senha de uso único por email ou nome de usuário (email) e senha e coletar atributos de usuário em seu aplicativo móvel Android usando autenticação nativa.

Neste tutorial, você:

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

Pré-requisitos

Inscrever um usuário

Para inscrever um usuário usando a senha de uso único por email ou o nome de usuário (email) e senha, você coleta um email do usuário e, em seguida, envia um email contendo uma senha de uso único por 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. Adicione validação aos seus campos de entrada 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.
    • 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, o que indica que o SDK espera que o aplicativo envie a senha única de email enviada para o endereço de email do usuário.
    • O objeto SignUpResult.CodeRequired contém uma nova referência de estado, que podemos recuperar por meio de actionResult.nextState.
    • O novo estado nos dá 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
        )
}

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 Android da MSAL fornecerá métodos utilitários para permitir que você analise ainda mais os erros específicos:

    • O método isUserAlreadyExists() verifica se o nome de usuário 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 parâmetro invalidAttributes, que é uma lista de todos os atributos que os aplicativos enviaram, mas falharam 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 a necessidade de um navegador (fallback na 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 simplesmente não dá suporte a ela. Use as etapas descritas em Suporte a fallback na Web no aplicativo Android para lidar com o cenário quando isso acontecer.
    • 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 com êxito em seu aplicativo. Compile e execute seu aplicativo. Se estiver tudo correto, você deverá ser capaz de inscrever o usuário com sucesso, usando senha de uso único por email ou email e senha.

Opcional: entrar após um processo de cadastro

Após um fluxo de inscrição bem-sucedido, você pode conectar um usuário sem iniciar um processo de login. 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.