Compartilhar via

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

  • Artigo

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ê aprenderá a:

  • Inscrever um usuário usando senha de uso único por email ou nome de usuário (email) e senha.
  • Coletar atributos de usuário durante a inscrição.
  • Identificar 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 (IU) do usuário para:

    • Coletar um email do usuário. Adicionar validação às suas entradas para garantir que o usuário insira um endereço de email válido.
    • Coletar 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 actionResult = authClient.signUp(
        username = emailAddress
        //password = password, Pass 'password' param if you sign up with username (email) and password
    )
    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(username) para iniciar o fluxo de inscrição.
      • Para se inscrever usando o nome de usuário (endereço de email) e a senha, passe o parâmetro de senha para a função signUp, signUp(username, password).
    • O parâmetro do método, username, será o endereço de email coletado do usuário.
    • No cenário mais comum, o signUp(username) ou signUp(username, password) retorna um resultado, SignUpResult.CodeRequired, o que indica que o SDK espera que o aplicativo envie a senha de uso único por 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(username) ou signUp(username, password) 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:

  • O método signUp() aceita um parâmetro attributes, como signUp(username, attributes):

        CoroutineScope(Dispatchers.Main).launch {
        val actionResult = authClient.signUp(
            username = emailAddress,
            attributes = userAttributes
            //password = password, Pass 'password' param if you sign up with username (email) and password
        )
        //...
    }

  • 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(username, attributes) ou signUp(username, attributes, password) 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 actionResult = authClient.signUp(
    username = email,
    attributes = attributes
    //password = password, Pass 'password' param if you sign up with username (email) and password
)
if (actionResult is SignUpResult.AttributesRequired) {
        val requiredAttributes = actionResult.requiredAttributes 
        // Handle "attributes required" result 
        val nextState = actionResult.nextState
        nextState.submitAttributes(
            attributes = moreAttributes
        )
}

Manipular 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.

Manipular o erro de inscrição inicial

Para lidar com erros para o método signUp(), use o seguinte trecho de código:

val actionResult = authClient.signUp(
    username = email
)
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(username, attributes) ou signUp(username, password, attributes) podem 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 da 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 no fallback da Web de suporte 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 identificar o erro de atributos inválidos, use o seguinte snippet de código:

    val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
    //password = password, Pass 'password' param if you sign up with username (email) and password
)
if (actionResult is SignUpError && actionResult.isInvalidAttributes()) {
    val invalidAttributes = actionResult.invalidAttributes
    // Handle "invalid attributes" error, this time submit valid attributes
    authClient.signUp(
        username = emailAddress,
        attributes = resubmittedAttributes
        //password = password, Pass 'password' param if you sign up with username (email) and password
    )
} 
//...

Manipular o erro de senha de envio de email único

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 instruções de importação. O Android Studio deve incluir as instruções de importação para você automaticamente.

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 fluxo de inscrição

Após um fluxo de inscrição bem-sucedido, você pode conectar um usuário sem iniciar um fluxo de entrada. Saiba mais no Tutorial: conectar o usuário após a inscrição no artigo do Android.

Próximas etapas

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