Partilhar via

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

  • Artigo

Aplica-se a: Círculo branco com um símbolo X cinza. Os locatários do Workforce círculo verde com um símbolo de marca de seleção 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 coleta atributos de usuário em seu aplicativo iOS/macOS usando autenticação nativa.

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

    let parameters = MSALNativeAuthSignUpParameters(username: email)
    nativeAuth.signUp(parameters: parameters, delegate: self)
}

    • Para registar um utilizador usando o código de uso único enviado por email , usamos o método signUp(parameters:delegate) da biblioteca, que responde de forma assíncrona chamando um dos métodos no objeto delegado passado, que deve implementar o protocolo SignUpStartDelegate. A seguinte linha de código inicia o processo de inscrição do usuário:

      nativeAuth.signUp(parameters: parameters, delegate: self)

      No método signUp(parameters:delegate), passamos uma instância MSALNativeAuthSignUpParameters contendo o endereço de e-mail do usuário do formulário de envio ao lado do delegado (uma classe que implementa o protocolo SignUpStartDelegate).

    • Para inscrever um usuário usando 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
    }

    let parameters = MSALNativeAuthSignUpParameters(username: email)
    parameters.password = password
    nativeAuth.signUp(parameters: parameters, delegate: self)
}

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

      nativeAuth.signUp(parameters: parameters, delegate: self)

      No método signUp(parameters:delegate), passamos uma instância MSALNativeAuthSignUpParameters contendo o endereço de e-mail do usuário e sua senha ao lado do delegado (uma classe que implementa o protocolo SignUpStartDelegate).

    • Para implementar SignUpStartDelegate protocolo como uma extensão para 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(parameters:delegate)resulta numa chamada para os métodos delegados onSignUpCodeRequired() ou onSignUpStartError(). 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 parâmetro newState do 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 protocolo como uma extensão para 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 de delegado e devemos implementar os métodos necessários no protocolo SignUpVerifyCodeDelegate. No cenário mais comum, recebemos uma chamada para onSignUpCompleted(newState) indicando 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 método signUp(parameters:delegate) pode ser chamado usando um MSALNativeAuthSignUpParameters que tem uma propriedade de atributos.

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

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

let parameters = MSALNativeAuthSignUpParameters(username: email)
parameters.password = password
parameters.attributes = attributes
nativeAuth.signUp(parameters: parameters, delegate: self)

    O signUp(parameters:delegate)resulta numa chamada para os métodos do delegado onSignUpCodeRequired() ou onSignUpStartError(), ou numa chamada para onSignUpAttributesInvalid(attributeNames: [String]) se estiver implementado no delegado.

  2. Para implementar o protocolo SignUpStartDelegate 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 parâmetro newState do 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 como obrigatórios, na configuração do tenant do Gestão de Identidades e Acesso de Clientes (CIAM), os atributos que pretendemos recolher em diferentes páginas.

Chamamos signUp(parameters:delegate) sem passar qualquer atributo na instância MSALNativeAuthSignUpParameters. O próximo passo será ligar para newState.submitCode(code: userSuppliedCode, delegate: self) para verificar o e-mail do usuário.

Implementamos o protocolo SignUpVerifyCodeDelegate como uma extensão para nossa classe como antes, mas desta vez devemos implementar o método opcional onSignUpAttributesRequired(attributes:newState) 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 parâmetro newState 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 protocolo SignUpAttributesRequiredDelegate 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 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 que um ou mais atributos sejam 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 objetos MSALNativeAuthRequiredAttribute, que descrevem 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 parâmetro newState 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 de SignUpStartDelegate protocolo, simplesmente exibimos o erro quando manipulamos a função de delegação onSignUpStartError(error).

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: Fazer login após o processo de inscrição

Após um processo de inscrição bem-sucedido, pode autenticar um utilizador sem iniciar um processo de autenticação. Saiba mais no artigo : Tutorial: Iniciar sessão automaticamente no utilizador após a inscrição em uma app iOS/macOS.

Próximo passo

Tutorial: Adicionar início de sessão e término de sessão na aplicação iOS/macOS usando autenticação nativa