Compartilhar via

Tutorial: Adicionar entrada no aplicativo Android usando a 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 fazer login e logout de um usuário usando senha de uso único por email ou nome de usuário e senha em seu aplicativo móvel Android, utilizando autenticação nativa.

Neste tutorial, você:

  • 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 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ê entrar com o nome de usuário (email) e a senha.
    • Colete uma senha de uso único por email do usuário se você entrar com uma senha de uso único por email.
    • Reenvie uma senha de uso único (recomendado) se você se conectar com uma senha de uso único por email.

  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 parameters = NativeAuthSignInParameters(username = email)
     // Assign 'password' param if you sign in with username (email) and password
     // parameters.password = password
     val actionResult: SignInResult = authClient.signIn(parameters)

     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 getAccessTokenParameters = NativeAuthGetAccessTokenParameters()
             val accessTokenResult = accountState.getAccessToken(getAccessTokenParameters)

             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 parameters = NativeAuthSignInParameters(username = email)
    parameters.password = password
    val actionResult: SignInResult = authClient.signIn(parameters)

    if (actionResult is SignInResult.Complete) -> {
        // Handle sign in success
        val accountState = actionResult.resultValue

        val getAccessTokenParameters = NativeAuthGetAccessTokenParameters()
        val accessTokenResult = accountState.getAccessToken(getAccessTokenParameters)

        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(parameters) do SDK.
    • Uma instância da classe NativeAuthSignInParameters, que contém o username que é 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(parameters) retorna um resultado, SignInResult.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 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 o login, 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.

Lidar com erros de início de login

Para lidar com erros no método signIn(parameters), use o seguinte snippet de código:

 val parameters = NativeAuthSignInParameters(username = email)
 // Assign 'password' param if you sign in with username (email) and password
 // parameters.password = password
val actionResult: SignInResult = authClient.signIn(parameters)

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(parameters), 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 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.
    • 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.

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

Tratar erros de saída

A saída não deve gerar erros. Se ocorrerem erros, inspecione o resultado do erro usando o seguinte trecho 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 declarações de importação. O Android Studio deve incluir automaticamente para você as instruções de importação.

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ê deve conseguir selecionar o botão Sair para sair com sucesso.

Configurar provedor de declarações personalizado

Se você quiser adicionar declarações de um sistema externo ao token emitido ao 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ção personalizado para adicionar declarações de um sistema externo aos tokens de segurança.

Habilitar o login com um alias ou nome de usuário

Você pode permitir que os usuários que entrarem com um endereço de email e senha também entrem com um nome de usuário e senha. O nome de usuário também chamado de identificador de entrada alternativo pode ser uma ID do cliente, um número de conta ou outro identificador que você escolhe usar como nome de usuário.

Você pode atribuir nomes de usuário à conta de usuário manualmente por meio do Centro de administração do Microsoft Entra ou automatizá-la em seu aplicativo por meio da API do Microsoft Graph.

Use as etapas no artigo Entrar com um alias ou nome de usuário para permitir que os usuários façam login usando um nome de usuário no seu aplicativo.

  1. Habilitar nome de usuário no login.
  2. Crie usuários com nome de usuário no centro de administração ou atualize os usuários existentes adicionando um nome de usuário. Como alternativa, você também pode automatizar a criação e a atualização do usuário em seu aplicativo usando a API do Microsoft Graph.

Conteúdo relacionado

  • Last updated on