Adicionar início de sessão na aplicação Android utilizando autenticação nativa - Microsoft Entra External ID

Artigo
08/02/2024

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

Inicie sessão num utilizador utilizando um código de acesso ou nome de utilizador (e-mail) e palavra-passe por e-mail.
Saia de um usuário.
Manipular erro de entrada

Pré-requisitos

Conclua as etapas em Tutorial: Preparar seu aplicativo Android para autenticação nativa. Este tutorial mostra como preparar seu projeto ou aplicativo Android para autenticação nativa.

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 num utilizador, tem de:

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.
- Colete uma senha única de e-mail do usuário se você entrar com uma senha única de e-mail.
- Reenvie uma senha única (recomendado) se você entrar com uma senha única por e-mail.

Na interface do usuário, adicione um botão, cujo evento select 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 onde um usuário entra com e-mail e senha, use o seguinte trecho 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 ou signIn(username, password) SDK.signIn(username)
O parâmetro do método, username é então 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 é então a senha que você coleta do usuário.
No cenário mais comum, o signIn(username) ou signIn(username, password)retorna um resultado, SignInResult.CodeRequiredque 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 SignInResult.CodeRequired objeto contém uma nova referência de estado, que podemos recuperar através do 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 o código de acesso único do e-mail se o usuário não receber o código.

Durante o início de sessão, nem todas as ações são bem-sucedidas. 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.

Para manipular erros no signIn(username) método or 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 pelo signIn(), portanto, o resultado da ação não inclui uma referência ao novo estado.
Se actionResult is SignUpErroro SDK do Android fornecer métodos utilitários 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 (fallback da 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 a senha como um tipo de desafio ou simplesmente não a suporta. Use as etapas em Suporte ao fallback da 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 suporta, que é um valor de tipo de desafio diferente de oob e senha. Saiba mais sobre os tipos de desafio.
- Para login com 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 de código de envio

Para manipular erros no submitCode() método, 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 SubmitCodeError erro 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.
A 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 entrar com êxito em um usuário em seu aplicativo. Crie e execute seu aplicativo. Se tudo bem, você deve ser capaz de fornecer um e-mail, receber um código no e-mail e usá-lo para entrar com sucesso no usuário.

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

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

Sair de um usuário

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

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.

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

Manipular erros de saída

Sair 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 sair com êxito de um usuário em seu aplicativo. 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.

Tutorial: Inscreva-se usuário com nome de usuário e atributos de usuário.
Configure um provedor de declarações personalizado.
Adicione atributos de usuário como declarações de token.

Partilhar via

Pré-requisitos

Manipular erros de código de envio

Ler declarações de token de ID

Sair de um usuário

Manipular erros de saída

Configurar provedor de declarações personalizado

Comentários

Recursos adicionais

Partilhar via

Tutorial: Adicionar início de sessão na aplicação Android utilizando autenticação nativa

Pré-requisitos

Iniciar sessão num utilizador

Manipular erros de entrada

Manipular erros de início de sessão

Manipular erros de código de envio

Ler declarações de token de ID

Sair de um usuário

Manipular erros de saída

Configurar provedor de declarações personalizado

Conteúdos relacionados

Comentários

Recursos adicionais