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

Aplica-se a: Círculo verde com um símbolo de marca de seleção branca que indica que o conteúdo a seguir se aplica a locatários externos. Locatários externos (saiba mais)

Este tutorial demonstra como inscrever um usuário usando senha única por email ou nome de usuário (email) e senha em seu aplicativo iOS/macOS usando autenticação nativa. Você também aprenderá como coletar atributos do usuário durante o cadastro, incluindo um nome de usuário (alias), e tratar erros.

Neste tutorial, você:

  • Inscrever um usuário usando uma senha de uso único por email ou um nome de usuário (email) e senha.
  • Colete atributos de usuário durante a inscrição, incluindo um nome de usuário (alias).
  • Lidar com erros de inscrição.

Pré-requisitos

Inscrever um usuário

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

Para inscrever um usuário, você precisa:

  1. Criar uma interface do usuário (IU) para:

    • Coletar um email do usuário. Adicionar validação às suas entradas de dados para garantir que o usuário insira um endereço de email válido.
    • Colete uma senha se você se inscrever com o nome de usuário (email) e a senha.
    • Colete um nome de usuário (alias) se o aplicativo der suporte à entrada baseada em alias.
    • Coletar uma senha de uso único por email do usuário.
    • Se necessário, coletar atributos de usuário.
    • Reenvie a senha de uso único se não for recebida pelo usuário.
    • Iniciar o fluxo de inscrição.

  2. Em seu aplicativo, adicione um botão, cujo evento de seleção 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 cadastrar um usuário usando código de uso único por e-mail, use o método signUp(parameters:delegate) da biblioteca, que responde de forma assíncrona chamando um dos métodos do objeto delegado fornecido, 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), passe uma instância de MSALNativeAuthSignUpParameters contendo o endereço de e-mail do usuário do formulário de envio, juntamente com o delegate (uma classe que implementa o protocolo SignUpStartDelegate).

    • Para inscrever um usuário usando Email com senha, use os seguintes snippets 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)
}

      O método signUp(parameters:delegate) da biblioteca responde de forma assíncrona chamando um dos métodos do objeto delegado fornecido, 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)

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

    • Para implementar o SignUpStartDelegate protocolo como uma extensão para sua 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 em uma chamada para 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 email do usuário. Juntamente com alguns detalhes de onde o código foi enviado e quantos dígitos ele contém, esse método delegado também tem um newState parâmetro de tipo SignUpCodeRequiredState, que fornece acesso a dois novos métodos:

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

      Para enviar o código fornecido pelo usuário, use:

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

      • Para implementar o SignUpVerifyCodeDelegate protocolo como uma extensão para sua 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!"
    }
}

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

Coletar atributos de usuário durante a inscrição

Independentemente de você inscrever um usuário usando senha de uso único por email ou nome de usuário (email) e senha, você poderá 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 snippet 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 em uma chamada aos métodos delegados onSignUpCodeRequired() ou onSignUpStartError(), ou em uma chamada a onSignUpAttributesInvalid(attributeNames: [String]) se o método estiver implementado no delegado.

  2. Para implementar o SignUpStartDelegate protocolo como uma extensão para sua classe, use o seguinte snippet 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, exiba a lista de atributos inválidos para o usuário. Caso contrário, onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) é chamado para indicar que um código foi enviado para verificar o endereço de email do usuário. Além de detalhes como o destinatário do código e o número de dígitos do código, esse método delegado tem um newState parâmetro de tipo SignUpCodeRequiredState, que fornece acesso a dois novos métodos:

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

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

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

Chame signUp(parameters:delegate) sem passar nenhum atributo na MSALNativeAuthSignUpParameters instância. A próxima etapa é chamar newState.submitCode(code: userSuppliedCode, delegate: self) para verificar o email do usuário.

Implemente o SignUpVerifyCodeDelegate protocolo como uma extensão para sua classe como antes, mas desta vez você deve 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!"
    }
}

Esse método delegado tem um newState parâmetro de tipo SignUpAttributesRequiredState, que fornece acesso a um novo método:

  • submitAttributes(attributes:delegate)

Para enviar os atributos fornecidos pelo usuário, use o seguinte snippet de código:

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

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

Implemente também o SignUpAttributesRequiredDelegate protocolo como uma extensão para sua 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 de delegado são chamados:

  • onSignUpAttributesInvalid: indica que um ou mais atributos que foram enviados falharam na validação da entrada de dados. Esse erro contém um parâmetro attributeNames, que é uma lista de todos os atributos que foram enviados pelo desenvolvedor e falharam na validação de entrada.
  • onSignUpAttributesRequired: indica que o servidor requer que um ou mais atributos sejam enviados antes de a conta de usuário poder 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 de atributos, que é uma lista de objetos MSALNativeAuthRequiredAttribute que descreve detalhes sobre os atributos de usuário requeridos pela API.

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

Coletar um nome de usuário (alias) durante a inscrição

O nome de usuário (alias) é um atributo de usuário especial. Como outros atributos, como cidade ou país, você a coleta durante a inscrição. Ao contrário desses atributos, o usuário pode usar posteriormente o alias para entrar. O alias (por exemplo, "johndoe") oferece aos usuários uma maneira mais curta e amigável de entrar do que seu endereço de email.

O nome de usuário (alias) não substitui o nome de usuário (email). Durante a inscrição, o aplicativo sempre deve coletar o nome de usuário (email) como o identificador primário e coleta o alias como um atributo junto com o email. Na entrada, o usuário pode optar por entrar com seu nome de usuário (email) ou seu nome de usuário (alias).

Quando o atributo de usuário interno Username está habilitado no fluxo de usuário de inscrição, o SDK o aceita por meio do mesmo dicionário de atributos usado para outros atributos, como a flatusername chave. Você pode passar o nome de usuário (alias signUp ) diretamente na chamada para que o usuário não precise passar por uma etapa separada exigida por atributos.

Para coletar um nome de usuário (alias), adicione um campo de entrada para o nome de usuário na interface do usuário de inscrição ao lado do campo de email e, em seguida, passe o alias como um atributo na chamada de inscrição:

guard let email = emailTextField.text, !email.isEmpty,
      let password = passwordTextField.text, !password.isEmpty,
      let username = usernameTextField.text, !username.isEmpty else {
    showResultText("Please fill in all fields")
    return
}

let attributes: [String: Any] = [
    "flatusername": username
]

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

Para fluxos de senha única de email (sem senha), passe os atributos sem definir uma senha:

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

Ao tratar erros de inscrição de nome de usuário (alias), a error.isUserAlreadyExists propriedade também abrange um alias duplicado e error.isInvalidAttributes apresenta um valor de alias inválido.

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

Na implementação anterior do SignUpStartDelegate protocolo, o erro foi simplesmente exibido ao manipular a onSignUpStartError(error) função delegada.

Para aprimorar 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 processo de cadastro

Após um processo de cadastro bem-sucedido, você pode autenticar um usuário sem iniciar um fluxo de login. Se o usuário se inscreveu com um nome de usuário (alias), ele poderá entrar usando seu endereço de email ou seu alias. Saiba mais no artigo Tutorial: conectar o usuário automaticamente após a inscrição em um aplicativo iOS/macOS.

Próxima etapa

Tutorial: adicionar o recurso de entrar e sair no aplicativo iOS/macOS usando autenticação nativa.

  • Last updated on