Partilhar via

Tutorial: Adicionar login na app Android utilizando autenticação nativa

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

Este tutorial demonstra como entrar e sair de um usuário com senha única de e-mail ou nome de usuário e senha em seu aplicativo móvel Android usando autenticação nativa.

Neste tutorial, você:

  • Autentique um utilizador utilizando um código de acesso temporário por e-mail ou nome de utilizador (e-mail) e palavra-passe.
  • Terminar sessão de um utilizador.
  • Lidar com erro de início de sessão

Pré-requisitos

Iniciar sessão de um utilizador

Para iniciar sessão num utilizador utilizando o código de acesso único, recolha o e-mail e envie um e-mail contendo um código de acesso único para o utilizador verificar o seu e-mail. Quando o usuário insere uma senha única válida, o aplicativo faz login.

Para iniciar sessão num utilizador utilizando o nome de utilizador (e-mail) e a palavra-passe, recolha o e-mail e a palavra-passe do utilizador. Se o nome de utilizador e a palavra-passe forem válidos, a aplicação inicia sessão no utilizador.

Para iniciar sessão como um utilizador, tem de:

  1. Crie uma interface do usuário (UI) para:

    • Colete um e-mail do usuário. Adicione validação às suas entradas para garantir que o usuário insira um endereço de e-mail válido.
    • Recolha uma palavra-passe se iniciar sessão com o nome de utilizador (e-mail) e a palavra-passe.
    • Recolha uma senha única enviada por e-mail do utilizador se iniciar sessão com uma senha única enviada por e-mail.
    • Reenvie uma senha única (recomendado) se você entrar com uma senha única por e-mail.

  2. Na interface de utilizador, adicione um botão, cujo evento de seleção inicia um início de sessão, 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 onde um usuário entra com e-mail e senha, use o seguinte trecho 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, contendo o username que é o endereço de e-mail que você coleta do usuário.
    • Se o método de login for nome de usuário (e-mail) e senha, o parâmetro do método, password é a senha que você coleta do usuário.
    • No cenário mais comum, o signIn(parameters) retorna um resultado, SignInResult.CodeRequired, que indica que o SDK espera que o aplicativo envie a senha de e-mail enviada uma única vez para o endereço de e-mail do usuário.
    • O objeto SignInResult.CodeRequired contém uma nova referência de estado, que podemos recuperar através actionResult.nextState.
    • O novo Estado dá-nos acesso a dois novos métodos:
      • submitCode() envia a senha única de e-mail que o aplicativo coleta do usuário.
      • resendCode() reenvia a senha única do e-mail se o usuário não receber o código.

Lidar com erros de início de sessão

Ao iniciar sessão, não são todas as ações que têm sucesso. Por exemplo, o usuário pode tentar entrar com um endereço de e-mail que não existe ou enviar um código inválido.

Gerir erros de início de sessão

Para manipular erros no método signIn(parameters), use o seguinte trecho 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 fornece métodos de utilitário para permitir que você analise ainda mais os erros específicos:
    • O método isUserNotFound() verifica se o usuário entra com um nome de usuário (endereço de e-mail) que não existe.
    • O método isBrowserRequired() verifica a necessidade de um navegador (alternativa web) para concluir o fluxo de autenticação. Esse cenário acontece quando a autenticação nativa não é suficiente para concluir o fluxo de autenticação. Por exemplo, um administrador configura o e-mail 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 oferece suporte a ele. Use as etapas em Suporte ao contingente web no aplicativo Android para lidar com o cenário quando ocorrer.
    • O método isAuthNotSupported() verifica se o aplicativo envia um tipo de desafio que o Microsoft Entra não suporta, ou seja, um valor de tipo de desafio diferente de oob e senha. Saiba mais sobre os tipos de desafios .
    • Para login de nome de usuário (e-mail) e senha, o método isInvalidCredentials() verifica se a combinação de nome de usuário e senha está incorreta.

Manipular erros na submissão de código

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.
  • O isInvalidCode() verifica o erro específico. Nesse caso, a referência de estado anterior deve ser usada para executar novamente a ação.

Para recuperar a nova senha de e-mail de uso único, 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 iniciar sessão de um utilizador no seu aplicativo. Crie e execute seu aplicativo. Se tudo correr bem, deves ser capaz de introduzir um e-mail, receber um código no e-mail e usá-lo para iniciar sessão com sucesso.

Ler declarações de token de identificação

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

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 usada para aceder ao valor da declaração é o nome especificado ao adicionar o atributo de utilizador como uma declaração de token.

Para saber como adicionar atributos internos e personalizados às declarações de token no artigo Adicionar atributos do utilizador a declarações de token.

Terminar a sessão de um utilizador

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

  1. Crie sua 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 sair de 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 logout

O processo de encerramento deve estar livre de erros. Se ocorrer algum erro, 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 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 terminar a sessão de um utilizador na sua aplicação. Crie e execute seu aplicativo. Se tudo estiver bem, você deve ser capaz de selecionar o botão de saída para sair com êxito.

Configurar provedor de declarações personalizado

Se você quiser adicionar declarações 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.

Ativar início de sessão com um alias ou nome de utilizador

Pode permitir que os utilizadores que iniciam sessão com um endereço de e-mail e palavra-passe também iniciem sessão com um nome de utilizador e palavra-passe. O nome de utilizador, também chamado de identificador alternativo de entrada, pode ser um ID de cliente, número de conta ou outro identificador que escolha usar como nome de utilizador.

Pode atribuir nomes de utilizador manualmente à conta de utilizador através do centro de administração do Microsoft Entra ou automatizá-lo na sua aplicação através da API Microsoft Graph.

Siga os passos em Iniciar sessão com um alias ou nome de utilizador para permitir que os seus utilizadores iniciem sessão usando um nome de utilizador na sua aplicação:

  1. Ativar o nome de utilizador no início de sessão.
  2. Crie utilizadores com nome de utilizador no centro de administração ou atualize utilizadores existentes adicionando um nome de utilizador. Alternativamente, pode também automatizar a criação e atualização de utilizadores na sua aplicação usando a Microsoft Graph API.

Conteúdo relacionado

  • Last updated on