Tutorial: Adicionar inscrição em um aplicativo iOS/macOS usando autenticação nativa

Aplica-se a: iOS (Swift) macOS (Swift)

Este tutorial demonstra como inscrever um usuário usando senha única de e-mail ou nome de usuário (e-mail) e senha, e coleta atributos de usuário em seu aplicativo iOS/macOS usando autenticação nativa.

Pré-requisitos

• Tutorial: Prepare seu aplicativo iOS/macOS para autenticação nativa.
• Se você quiser coletar atributos de usuário durante a inscrição, configure os atributos de usuário ao criar seu fluxo de usuário de inscrição e entrada.

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 se o usuário não a receber.
   • Inicie o fluxo de inscrição.

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

   @IBAction func signUpPressed(_: Any) {
       guard let email = emailTextField.text else {
           resultTextView.text = "Email or password not set"
           return
       }
   
       nativeAuth.signUp(username: email, delegate: self)
   }
   

   • Para inscrever um usuário usando a senha única de e-mail, usamos o método da signUp(username:delegate) biblioteca, que responde de forma assíncrona chamando um dos métodos no objeto delegado passado, que deve implementar o SignUpStartDelegate protocolo. A seguinte linha de código inicia o processo de inscrição do usuário:

     nativeAuth.signUp(username: email, delegate: self)
     

     signUp(username:delegate) No método, passamos o endereço de e-mail do usuário do formulário de envio e o delegado (uma classe que implementa o SignUpStartDelegate protocolo).

   • Para inscrever um usuário usando o Email com senha, use os seguintes trechos de código:

     @IBAction func signUpPressed(_: Any) {
         guard let email = emailTextField.text, let password = passwordTextField.text else {
             resultTextView.text = "Email or password not set"
             return
         }
     
         nativeAuth.signUp(username: email,password: password,delegate: self)
     }
     

     Usamos o método da signUp(username:password:delegate) biblioteca, que responde de forma assíncrona chamando um dos métodos no objeto delegado passado, que deve implementar o SignUpStartDelegate protocolo. A seguinte linha de código inicia o processo de inscrição do usuário:

     nativeAuth.signUp(username: email, password: password, delegate: self)
     

     signUp(username:password:delegate) No método, passamos o endereço de e-mail do usuário, sua senha e o delegado (uma classe que implementa o SignUpStartDelegate protocolo).

   • Para implementar SignUpStartDelegate o protocolo como uma extensão para a nossa classe, use:

     extension ViewController: SignUpStartDelegate {
         func onSignUpStartError(error: MSAL.SignUpStartError) {
             resultTextView.text = "Error signing up: \(error.errorDescription ?? "no description")"
         }
     
         func onSignUpCodeRequired(
             newState: MSAL.SignUpCodeRequiredState,
             sentTo: String,
             channelTargetType: MSAL.MSALNativeAuthChannelType,
             codeLength: Int
         ) {
             resultTextView.text = "Verification code sent to \(sentTo)"
         }
     }
     

     A chamada para signUp(username:password:delegate) ou signUp(username:delegate) resulta em uma chamada para um ou onSignUpStartError() onSignUpCodeRequired() delegar métodos. O onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) é chamado para indicar que um código foi enviado para verificar o endereço de e-mail do usuário. Juntamente com alguns detalhes de onde o código foi enviado e quantos dígitos ele contém, este método delegado também tem um newState parâmetro de tipo SignUpCodeRequiredState, que nos dá acesso a dois novos métodos:

     • submitCode(code:delegate)
     • resendCode(delegate)

     Para enviar o código que o usuário nos forneceu, use:

     newState.submitCode(code: userSuppliedCode, delegate: self)
     

     • Para implementar SignUpVerifyCodeDelegate o protocolo como uma extensão para a nossa classe, use:

       extension ViewController: SignUpVerifyCodeDelegate {
           func onSignUpVerifyCodeError(error: MSAL.VerifyCodeError, newState: MSAL.SignUpCodeRequiredState?) {
               resultTextView.text = "Error verifying code: \(error.errorDescription ?? "no description")"
           }
       
           func onSignUpCompleted(newState: SignInAfterSignUpState) {
               resultTextView.text = "Signed up successfully!"
           }
       }
       

       O submitCode(code:delegate) aceita um parâmetro delegado e devemos implementar os métodos necessários no SignUpVerifyCodeDelegate protocolo. No cenário mais comum, recebemos uma chamada para onSignUpCompleted(newState) indicar que o usuário foi inscrito e o fluxo está completo.

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. O signUp(username:attributes:delegate) método, aceita atributos como um parâmetro.

1. Para coletar atributos de usuário, use o seguinte trecho de código:

   let attributes = [
       "country": "United States",
       "city": "Redmond"
   ]
   
   nativeAuth.signUp(username: email, attributes: attributes, delegate: self)
   

   O signUp(username:attributes:delegate) ou ignUp(username:password:attributes:delegate) resulta em uma chamada para um ou onSignUpStartError() onSignUpCodeRequired() delegar métodos, ou em uma chamada para onSignUpAttributesInvalid(attributeNames: [String]) se for implementado no delegado.

2. Para implementar o SignUpStartDelegate protocolo como uma extensão para nossa classe, use o seguinte trecho de código:

   extension ViewController: SignUpStartDelegate {
       func onSignUpStartError(error: MSAL.SignUpStartError) {
           resultTextView.text = "Error signing up: \(error.errorDescription ?? "no description")"
       }
   
       func onSignUpCodeRequired(
           newState: MSAL.SignUpCodeRequiredState,
           sentTo: String,
           channelTargetType: MSAL.MSALNativeAuthChannelType,
           codeLength: Int
       ) {
           resultTextView.text = "Verification code sent to \(sentTo)"
       }
   
       func onSignUpAttributesInvalid(attributeNames: [String]) {
          resultTextView.text = "Invalid attributes  \(attributeNames)"
       }
   }
   

   Se os atributos forem inválidos, o método onSignUpAttributesInvalid(attributeNames: [String]) será chamado. Nesse caso, exibimos a lista de atributos inválidos para o usuário. Caso contrário, o onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) é chamado para indicar que um código foi enviado para verificar o endereço de e-mail do usuário. Além de detalhes como o destinatário do código e o número de dígitos do código, este método delegado tem um newState parâmetro de tipo SignUpCodeRequiredState, que nos dá acesso a dois novos métodos:

   • submitCode(code:delegate)
   • resendCode(delegate)

Atributos do usuário em uma ou mais páginas

Para distribuir os atributos por uma ou mais páginas, devemos definir os atributos que pretendemos coletar em diferentes páginas como obrigatórios na configuração de locatário de gerenciamento de acesso e identidade do cliente (CIAM).

Ligamos signUp(username:password:delegate) sem passar nenhum atributo. O próximo passo será ligar newState.submitCode(code: userSuppliedCode, delegate: self) para verificar o e-mail do usuário.

Implementamos o SignUpVerifyCodeDelegate protocolo como uma extensão para a nossa classe como antes, mas desta vez devemos implementar o método onSignUpAttributesRequired(attributes:newState) opcional, além dos métodos necessários:

extension ViewController: SignUpVerifyCodeDelegate {
    func onSignUpAttributesRequired(newState: SignUpAttributesRequiredState) {
        resultTextView.text = "Attributes required"
    }

    func onSignUpVerifyCodeError(error: MSAL.VerifyCodeError, newState: MSAL.SignUpCodeRequiredState?) {
        resultTextView.text = "Error verifying code: \(error.errorDescription ?? "no description")"
    }

    func onSignUpCompleted(newState: SignInAfterSignUpState) {
        resultTextView.text = "Signed up successfully!"
    }
}

Este método delegado tem um newState parâmetro do tipo SignUpAttributesRequiredState, que nos dá acesso a um novo método:

• submitAttributes(attributes:delegate)

Para enviar os atributos que o usuário nos forneceu, use o seguinte trecho de código:

let attributes = [
    "country": "United States",
    "city": "Redmond"
]

newState.submitAttributes(attributes: attributes, delegate: self)

Também implementaremos o SignUpAttributesRequiredDelegate protocolo como uma extensão da nossa classe:

extension ViewController: SignUpAttributesRequiredDelegate {
    func onSignUpAttributesRequiredError(error: AttributesRequiredError) {
        resultTextView.text = "Error submitting attributes: \(error.errorDescription ?? "no description")"
    }

    func onSignUpAttributesRequired(attributes: [MSALNativeAuthRequiredAttribute], newState: SignUpAttributesRequiredState) {
        resultTextView.text = "Attributes required"
    }

    func onSignUpAttributesInvalid(attributeNames: [String], newState: SignUpAttributesRequiredState) {
        resultTextView.text = "Attributes invalid"
    }

    func onSignUpCompleted(newState: SignInAfterSignUpState) {
        resultTextView.text = "Signed up successfully!"
    }
}

Quando o usuário não fornece todos os atributos necessários, ou os atributos são inválidos, esses métodos delegados são chamados:

• onSignUpAttributesInvalid: indica que um ou mais atributos que foram enviados falharam na validação de entrada. Este erro contém um parâmetro attributeNames, que é uma lista de todos os atributos que foram enviados pelo desenvolvedor que falharam na validação de entrada.
• onSignUpAttributesRequired: indica que o servidor requer um ou mais atributos a serem enviados, antes que a conta de usuário possa ser criada. Isso acontece quando um ou mais atributos são definidos como obrigatórios na configuração do locatário. Esse resultado contém o parâmetro attributes, que é uma lista de MSALNativeAuthRequiredAttribute objetos, que descreve detalhes sobre os atributos de usuário que a API exige.

Ambos os métodos delegados contêm uma nova referência de estado. Usamos o newState parâmetro para chamar submitAttributes(attributes:delegate) novamente com os novos atributos.

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 que já está em uso ou enviar um código inválido.

Em nossa implementação anterior do SignUpStartDelegate protocolo, simplesmente exibimos o erro quando manipulamos a onSignUpStartError(error) função delegada.

Para melhorar a experiência do usuário gerenciando o tipo de erro específico, use o seguinte trecho de código:

func onSignUpStartError(error: MSAL.SignUpStartError) {
    if error.isUserAlreadyExists {
        resultTextView.text = "Unable to sign up: User already exists"
    } else if error.isInvalidPassword {
        resultTextView.text = "Unable to sign up: The password is invalid"
    } else if error.isInvalidUsername {
        resultTextView.text = "Unable to sign up: The username is invalid"
    } else {
        resultTextView.text = "Unexpected error signing up: \(error.errorDescription ?? "no description")"
    }
}

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 automaticamente após se inscrever em um aplicativo iOS/macOS.

Próximo passo