Partilhar via

Tutorial: Adicionar inscrição em um aplicativo móvel Android usando autenticação nativa

  • Artigo

Aplica-se a: Círculo branco com um símbolo X cinza. Inquilinos do Workforce Círculo verde com um símbolo de visto branco. Inquilinos externos (saber mais)

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, você 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 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) 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 objeto SignUpResult.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.
    • 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
        )
}

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 MSAL Android SDK fornece métodos utilitários 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 o tipo de dados errado. Ele contém um parâmetro invalidAttributes, que é uma lista de todos os atributos que os aplicativos enviaram, mas falharam na validação.
    • isInvalidPassword() verifique se a senha é inválida, como 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 (alternativa 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 senha como um tipo de desafio ou simplesmente não oferece suporte a ele. Utilize as etapas na substituição de suporte na Web na aplicação Android para gestionar o cenário quando este ocorrer.
    • 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.

Você concluiu todas as etapas necessárias para inscrever um usuário em seu aplicativo com sucesso. Crie e execute seu aplicativo. Se tudo estiver bem, deve conseguir registar o utilizador com sucesso usando código de uso único via e-mail ou e-mail e palavra-passe.

Opcional: Entrar após um processo de registo

Após um fluxo de inscrição bem-sucedido, pode autenticar um utilizador sem iniciar um processo de autenticação. 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.