Partilhar 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 única de e-mail ou nome de usuário (e-mail) e senha, e coletar atributos de usuário em seu aplicativo móvel Android usando autenticação nativa.

Neste tutorial, irá aprender a:

  • Inscreva um usuário usando e-mail, senha única ou nome de usuário (e-mail) e senha.
  • Colete atributos de usuário durante a inscrição.
  • Lidar com erros de inscrição.

Pré-requisitos

Inscrever um utilizador

Para inscrever um usuário usando a senha única de e-mail ou nome de usuário (e-mail) e senha, você coleta um e-mail do usuário e, em seguida, envia um e-mail contendo uma senha única de e-mail para o usuário. O usuário insere uma senha única de e-mail válida para validar seu nome de usuário.

Para inscrever um usuário, você precisa:

  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.
    • Colete uma senha se você se inscrever com nome de usuário (e-mail) e senha.
    • Colete uma senha única de e-mail do usuário.
    • Se necessário, colete atributos de usuário.
    • Reenvie uma senha única (recomendado).
    • Inicie o fluxo de inscrição.

  2. Em seu aplicativo, adicione um botão, cujo evento select dispara o seguinte trecho de código:

    CoroutineScope(Dispatchers.Main).launch {
     val parameters = NativeAuthSignUpParameters(username = email)
     // Assign 'password' param if you sign in with username (email) and password
     // parameters.password = password
     val actionResult: SignUpResult = authClient.signUp(parameters)

     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 signUp(parameters) de instância do SDK para iniciar o fluxo de inscrição.
    • Para se inscrever usando nome de usuário (endereço de e-mail) e senha, crie uma instância de NativeAuthSignUpParameters classe e atribua seu nome de usuário e senha.
    • O parâmetro de inscrição, username, é o endereço de e-mail que você coleta do usuário.
    • No cenário mais comum, o signUp(parameters) retorna um resultado, SignUpResult.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 SignUpResult.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.
    • O submitCode() retorna SignUpResult.Complete, que indica que o fluxo está concluído e o usuário foi inscrito.
    • O signUp(parameters) 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 única de e-mail ou nome de usuário (e-mail) e senha, você pode coletar atributos de usuário antes que a conta de um usuário seja criada:

  • A instância NativeAuthSignUpParameters aceita um parâmetro attributes:

        CoroutineScope(Dispatchers.Main).launch {
        val parameters = NativeAuthSignUpParameters(username = email)
        // Assign 'password' param if you sign in with username (email) and password
        // parameters.password = password
        parameters.attributes = userAttributes
        val actionResult: SignUpResult = authClient.signUp(parameters)
        //...
    }

  • O SDK do Android fornece uma classe UserAttribute.Builder de utilitário que você usa para criar atributos de usuário. Por exemplo, para enviar atributos de usuário de cidade e país , use o seguinte trecho de código para criar a userAttributes variável:

         val userAttributes = UserAttributes.Builder ()
    .country(country) 
    .city(city) 
    .build()

    Os nomes de UserAttribute.Builder método na classe 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(parameters) 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 SignUpResult.AttributesRequired resultado contém um requiredAttributes parâmetro. requiredAttributes é uma lista de objetos que contém detalhes sobre os atributos de RequiredUserAttribute usuário que o aplicativo precisa enviar. Para manipular actionResult is SignUpResult.AttributesRequired, use o seguinte trecho de código:

    val parameters = NativeAuthSignUpParameters(username = email)
// Assign 'password' param if you sign in with username (email) and password
// parameters.password = password
parameters.attributes = userAttributes
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpResult.AttributesRequired) {
        val requiredAttributes = actionResult.requiredAttributes 
        // Handle "attributes required" result 
        val nextState = actionResult.nextState
        nextState.submitAttributes(
            attributes = moreAttributes
        )
}

Lidar com 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 e-mail já usado ou enviar uma senha única de e-mail inválida.

Manipular erro de inscrição de início

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

 val parameters = NativeAuthSignUpParameters(username = email)
 // Assign 'password' param if you sign in with username (email) and password
 // parameters.password = password
val actionResult: SignUpResult = authClient.signUp(parameters)

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(parameters) pode voltar SignUpError.

  • SignUpError indica um resultado de ação malsucedido retornado por signUp() e não incluirá uma referência ao novo estado.

  • Se actionResult is SignUpErroro MSAL Android SDK fornecer métodos de utilidade 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 enviados pelo aplicativo falharam na validação, como tipo de dados errado. Ele contém um invalidAttributes parâmetro, que é uma lista de todos os atributos que os aplicativos enviaram, mas falharam na validação.
    • isInvalidPassword() Verifique se a senha é inválida, por exemplo, 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() Verifique se o nome de usuário é inválido, como quando o e-mail do usuário é inválido.
    • isBrowserRequired() Verifica a necessidade de um navegador (web fallback), 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.
    • 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 ou senha. Saiba mais sobre os 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 manipular o erro de atributos inválidos, use o seguinte trecho de código:

    val parameters = NativeAuthSignUpParameters(username = email)
// Assign 'password' param if you sign in with username (email) and password
// parameters.password = password
parameters.attributes = userAttributes
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpError && actionResult.isInvalidAttributes()) {
    val invalidAttributes = actionResult.invalidAttributes

    // Handle "invalid attributes" error, this time submit valid attributes
    val parameters = NativeAuthSignUpParameters(username = email)
    // Assign 'password' param if you sign in with username (email) and password
    // parameters.password = password
    parameters.attributes = userAttributes
    authClient.signUp(parameters)
} 
//...

Lidar com o erro de senha única de envio de e-mail

Para manipular erros para o submitCode() método, 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 voltar SubmitCodeError.

  • Use o isInvalidCode() método para verificar o erro específico, como, por exemplo, o código enviado é inválido. Nesse caso, a referência de estado anterior deve ser usada para executar novamente a ação.

  • Para recuperar uma nova senha única de e-mail, 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 em seu aplicativo com sucesso. Crie e execute seu aplicativo. Se tudo bem, você deve ser capaz de inscrever com sucesso o usuário usando e-mail senha única ou e-mail e senha.

Opcional: Entrar após um fluxo de inscrição

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

Próximos passos

Tutorial: Adicione login e logout com senha única de e-mail no aplicativo Android.