Compartilhar via

Tutorial: Adicionar entrada no aplicativo Android usando a autenticação nativa

  • Artigo

Este tutorial demonstra como fazer um usuário entrar e sair usando a senha de uso único por email em seu aplicativo móvel Android usando a autenticação nativa.

Neste tutorial, você aprenderá a:

  • Conecte um usuário usando senha única por email ou nome de usuário (email) e senha.
  • Desconecte um usuário.
  • Como lidar com erros de entrada

Pré-requisitos

Conectar um usuário

Para conectar um usuário usando a senha de uso único, colete o email e envie um email contendo uma senha de uso único para o usuário a fim de verificar o email dele. Quando o usuário insere uma senha de uso único válida, o aplicativo o conecta.

Para conectar um usuário usando o nome de usuário (email) e a senha, colete o email e a senha do usuário. Se o nome de usuário e a senha forem válidos, o aplicativo conectará o usuário.

Para conectar um usuário, você precisa:

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

    • Coletar um email do usuário. Adicionar validação à interface do usuário para garantir que o usuário insira um endereço de email válido.
    • Colete uma senha se você entrar com o nome de usuário (email) e a senha.
    • Colete uma senha de uso único por email do usuário se você usar a senha de uso único por email para entrada.
    • Reenviar a senha única (recomendada) se você usar a senha de uso único por email para entrada.

  2. Na interface do usuário, adicione um botão, cujo evento de seleção inicia uma entrada, conforme mostrado no seguinte trecho de código:

     CoroutineScope(Dispatchers.Main).launch {
     val actionResult = authClient.signIn(
         username = emailAddress
         //password = password, Pass 'password' param if you sign in with username (email) and password
     )
     if (actionResult is SignInResult.CodeRequired) {
         val nextState = actionResult.nextState
         val submitCodeActionResult = nextState.submitCode(
             code = code
         )
         if (submitCodeActionResult is SignInResult.Complete){
             // Handle sign in success
             val accountState = submitCodeActionResult.resultValue
             val accessTokenResult = accountState.getAccessToken()
             if (accessTokenResult is GetAccessTokenResult.Complete) {
                 val accessToken = accessTokenResult.resultValue.accessToken
                 val idToken = accountState.getIdToken()
             }
         }
     }
 }

    Se o usuário não for obrigado a enviar uma senha, como quando o usuário entra com email e senha, use o seguinte snippet de código:

        CoroutineScope(Dispatchers.Main).launch {
        val actionResult = authClient.signIn(
            username = emailAddress,
            password = password
        )
        if (actionResult is SignInResult.Complete) -> {
            // Handle sign in success
            val accountState = actionResult.resultValue
            val accessTokenResult = accountState.getAccessToken()
            if (accessTokenResult is GetAccessTokenResult.Complete) {
                    val accessToken = accessTokenResult.resultValue.accessToken
                    val idToken = accountState.getIdToken()
                }
        }
    }
    • Para iniciar o fluxo de entrada, use o método signIn(username) ou signIn(username, password) do SDK.
    • O parâmetro do método username é, em seguida, o endereço de email coletado do usuário.
    • Se o método de entrada for nome de usuário (email) e senha, o parâmetro do método password será a senha coletada do usuário.
    • No cenário mais comum, o signIn(username) ou signIn(username, password) retorna um resultado, SignInResult.CodeRequired, 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 SignInResult.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.

Como lidar com erros de entrada

Durante a entrada, nem todas as ações são bem-sucedidas. Por exemplo, o usuário pode tentar entrar com um endereço de email que não existe ou enviar um código inválido.

Como lidar com erros de início de entrada

Para lidar com erros no método signIn(username) ou signIn(username, password), use o seguinte trecho de código:

val actionResult = authClient.sign(
    username = emailAddress
    //password = password, Pass 'password' param if you sign in with username (email) and password
)
if (actionResult is SignInResult.CodeRequired) {
    // Next step: submit code
} else if (actionResult is SignInError) {
    // Handle sign in errors
    when {
         actionResult.isUserNotFound() -> {
             // Handle "user not found" error
         }
         actionResult.isAuthNotSupported() -> {
         // Handle "authentication type not support" error
         }
         actionResult.isInvalidCredentials() -> {
             // Handle specific errors
         }
         else -> {
             // Handle other errors
         }
     }
}
  • SignInError indica um resultado de ação malsucedido retornado por signIn(), portanto, o resultado da ação não inclui uma referência ao novo estado.
  • Se actionResult is SignUpError, o SDK do Android fornecerá métodos utilitários para habilitar a análise mais detalhada dos erros específicos:
    • O método isUserNotFound() verifica se o usuário entra com um nome de usuário (endereço de email) que não existe.
    • O método 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.
    • O método 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 e senha. Saiba mais sobre tipos de desafio.
    • Para entrada de nome de usuário (email) e senha, o método isInvalidCredentials() verifica se a combinação de nome de usuário e senha está incorreta.

Manipular erros de código de envio

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

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignInResult.Complete) {
    // Sign in flow complete, handle success state.
} else if (submitCodeActionResult is SubmitCodeError && submitCodeActionResult.isInvalidCode()) {
    // Handle "invalid code" error
}
  • O erro SubmitCodeError indica um resultado de ação malsucedido retornado por submitCode() e, portanto, o resultado da ação não inclui uma referência ao novo estado.
  • isInvalidCode() verifica o erro específico. Nesse caso, a referência de estado anterior deve ser usada para executar a ação novamente.

Para recuperar a nova senha de uso único por email, use o seguinte trecho de código:

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignInError && submitCodeActionResult.isInvalidCode) {
    // Inform the user that the submitted code was incorrect or invalid, then ask them to input a new email one-time passcode
    val newCode = retrieveNewCode()
    nextState.submitCode(
        code = newCode
    )
}

Você concluiu todas as etapas necessárias para conectar um usuário com êxito em seu aplicativo. Compile e execute seu aplicativo. Se estiver tudo bem, você deverá ser capaz de fornecer um email, receber um código no email e usá-lo para conectar o usuário com êxito.

Ler declarações de token de ID

Depois que seu aplicativo adquirir um token de ID, você poderá recuperar as declarações associadas à conta atual. Para fazer isso, use o trecho de código a seguir.

val preferredUsername = accountState.getClaims()?.get("preferred_username")
val city = accountState.getClaims()?.get("City")
val givenName = accountState.getClaims()?.get("given_name")
//custom attribute
val loyaltyNumber = accountState.getClaims()?.get("loyaltyNumber")

A chave que você usa para acessar o valor da declaração é o nome que você especifica ao adicionar o atributo de usuário como uma declaração de token.

Saiba como adicionar atributos internos e personalizados como declarações de token no artigo Adicionar atributos de usuário a declarações de token.

Desconectar um usuário

Para desconectar um usuário, você precisa remover a conta atualmente armazenada no cache.

  1. Crie sua IU (interface do usuário) personalizada, que inclui:

    • Um botão de saída que o usuário seleciona para enviar uma solicitação de saída.

  2. Para desconectar um usuário, use o seguinte código:

    private fun performSignOut(accountState: AccountState) {
     CoroutineScope(Dispatchers.Main).launch {
        val accountResult = authClient.getCurrentAccount()
         if (accountResult is GetAccountResult.AccountFound) {
             val signOutResult = accountResult.resultValue.signOut()
             if (signOutResult is SignOutResult.Complete) {
                 // Show sign out successful UI
             }
         }
     }
 }

Lidar com erros de saída

A saída não deve gerar erros. Se eles ocorrerem, inspecione o resultado do erro usando o seguinte snippet de código:

val actionResult = accountResult.signOut()
if (actionResult is SignOutResult.Complete) {
    // Show sign out successful UI
} else {
    // Handle errors
}

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 com sucesso todas as etapas necessárias para desconectar um usuário no seu aplicativo. Compile e execute seu aplicativo. Se tudo estiver certo, você poderá selecionar o botão Sair para se desconectar com sucesso.

Configurar provedor de declarações personalizado

Se você quiser adicionar declarações a partir de um sistema externo ao token emitido para seu aplicativo, use um provedor de declarações personalizado. Um provedor de declarações personalizado é composto por uma extensão de autenticação personalizada que chama uma API REST externa para buscar declarações de sistemas externos.

Siga as etapas em Configurar um provedor de declarações personalizado para adicionar declarações de um sistema externo aos seus tokens de segurança.

Conteúdo relacionado