Tutorial: Adicionar inscrição em um aplicativo móvel Android usando 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 registar um utilizador usando o código de acesso de email único ou nome de utilizador (email) e palavra-passe na sua aplicação móvel Android, utilizando autenticação nativa. Também aprende a recolher atributos de utilizador durante o registo, incluindo um nome de utilizador (alias), e a lidar com erros.

Neste tutorial, você:

  • Inscreva um usuário usando e-mail, senha única ou nome de usuário (e-mail) e senha.
  • Recolha atributos do utilizador durante o registo, incluindo um nome de utilizador (pseudónimo).
  • Lidar com erros de inscrição.

Pré-requisitos

Inscrever um utilizador

Para inscrever um utilizador usando o código de acesso único do email ou nome de utilizador (email) e palavra-passe, recolhe um email do utilizador e depois envia um email contendo um código de acesso único ao utilizador. 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.
    • Recolha um nome de utilizador (alias) se a sua aplicação suportar login baseado em alias.
    • 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 de instância do SDK, signUp(parameters) 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) devolve um resultado, SignUpResult.CodeRequired, que indica que o SDK espera que a aplicação submeta o código de acesso de email único enviado para o endereço de email do utilizador.
    • O SignUpResult.CodeRequired objeto contém uma nova referência de estado, que pode recuperar através de actionResult.nextState.
    • O novo estado dá-lhe 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.
    • O submitCode() retorna SignUpResult.Complete, o que indica que o fluxo está concluído e que 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 de utilitário UserAttribute.Builder que você usa para criar atributos de usuário. Por exemplo, para enviar os atributos de usuário de cidade e país , use o seguinte trecho de código para criar a variável userAttributes:

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

    Os nomes de método na classe UserAttribute.Builder 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 resultado SignUpResult.AttributesRequired contém um parâmetro requiredAttributes. requiredAttributes é uma lista de objetos RequiredUserAttribute que contém detalhes sobre os atributos de usuário que o aplicativo precisa enviar. Para lidar com 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
        )
}

Recolha um nome de utilizador (alias) durante o registo

O nome de utilizador (alias) é um atributo especial do utilizador. Tal como outros atributos, como a cidade ou o país, recolhe essa informação durante o processo de registo. Ao contrário desses atributos, o utilizador pode depois usar o alias para iniciar sessão. O pseudónimo (por exemplo, "johndoe") oferece aos utilizadores uma forma mais curta e amigável de iniciar sessão do que o seu endereço de email.

O nome de utilizador (alias) não substitui o nome de utilizador (email). Durante o registo, a aplicação deve sempre recolher o nome de utilizador (email) como identificador principal, e recolhe o alias como um atributo juntamente com o email. No início de sessão, o utilizador pode então escolher iniciar sessão com o seu nome de utilizador (email) ou com o seu nome de utilizador (alias).

Quando o atributo de utilizador incorporado Username está ativado no seu fluxo de utilizador de inscrição, o SDK aceita-o através do mesmo construtor UserAttributes utilizado para outros atributos, utilizando o método flatUsername(). Pode passar o nome de utilizador (alias) diretamente na chamada de inscrição para que o utilizador não precise de passar por um passo separado exigido por atributos.

Para recolher um nome de utilizador (alias), adicione um campo de entrada para o nome de utilizador na sua interface de inscrição ao lado do campo de email, depois passe o alias como um atributo na chamada de inscrição:

val email = binding.emailText.text.toString()
val password = binding.passwordText.text.toString()
val username = binding.usernameText.text.toString()

val attributes = UserAttributes.Builder()
    .flatUsername(username)
    .build()

CoroutineScope(Dispatchers.Main).launch {
    val actionResult = authClient.signUpUsingPassword(
        username = email,
        password = password,
        attributes = attributes
    )

    when (actionResult) {
        is SignUpResult.CodeRequired -> {
            // Navigate to code verification
            navigateToCodeVerification(actionResult.nextState)
        }
        is SignUpUsingPasswordError -> {
            handleSignUpError(actionResult)
        }
    }
}

Para fluxos de código de acesso único de email (sem palavra-passe), use signUp em vez de signUpUsingPassword:

val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
)

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.

Gerir erro de início do registo

Para manipular erros para o método signUp(), 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 retornar 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 SignUpError, o SDK Android da Biblioteca de Autenticação da Microsoft (MSAL) fornece métodos utilitários para analisar mais a fundo os erros específicos:

    • O método isUserAlreadyExists() verifica se o nome de utilizador ou alias já foi usado para criar uma conta.
    • isInvalidAttributes() verifica se um ou mais atributos enviados pelo aplicativo falharam na validação, como o tipo de dados errado. Contém um invalidAttributes parâmetro, que é uma lista de todos os atributos que a aplicação submeteu, mas que falhou na validação.
    • isInvalidPassword() verifica se a palavra-passe é inválida, como quando não cumpre todos os requisitos de complexidade da palavra-passe. Saiba mais sobre as políticas de senha do Microsoft Entra
    • isInvalidUsername() verifica se o nome de utilizador é inválido, como quando o email do utilizador é inválido.
    • isBrowserRequired() verifica se é necessário um navegador (web fallback) para completar 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 email e palavra-passe como método de autenticação, mas a aplicação não envia palavra-passe como tipo de desafio ou não a suporta. Utilize os passos no Suporte Web Fallback na aplicação Android para lidar com este cenário.
    • 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 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)
} 
//...

Gerir o erro na submissão do código de acesso único via e-mail

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

  • Use o método isInvalidCode() 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 declarações de importação. Android Studio deve incluir as declarações de importação para você automaticamente.

Já completou todos os passos necessários para registar um utilizador na sua aplicação. Crie e execute seu aplicativo. Se tudo estiver configurado corretamente, deverá conseguir inscrever o utilizador usando um código de acesso único por email ou email e palavra-passe, e recolher atributos de utilizador, incluindo um nome de utilizador (alias).

Opcional: Entrar após um processo de registo

Após um fluxo de registo bem-sucedido, pode iniciar a sessão de um utilizador sem iniciar um fluxo de início de sessão. Se o utilizador se inscrever com um nome de utilizador (alias), pode iniciar sessão usando o seu endereço de email ou o seu alias. Saiba mais no artigo Tutorial : Iniciar sessão como utilizador após o registo no Android.

Próximos passos

Tutorial: Adicionar acesso e saída com código de acesso único por e-mail na aplicação Android.

  • Last updated on