Samouczek: dodawanie rejestracji w aplikacji systemu iOS/macOS przy użyciu uwierzytelniania natywnego

Dotyczy: Dzierżawy zewnętrzne (dowiedz się więcej)

W tym samouczku pokazano, jak zarejestrować użytkownika za pomocą jednorazowego kodu przesyłanego e-mailem albo nazwy użytkownika (adresu e-mail) i hasła w aplikacji na iOS/macOS przy użyciu uwierzytelniania natywnego. Dowiesz się również, jak zbierać atrybuty użytkownika podczas rejestracji, w tym nazwę użytkownika (alias) i obsługiwać błędy.

W tym samouczku nauczysz się następujących rzeczy:

Warunki wstępne

• Wykonaj kroki opisane w artykule Samouczek: przygotowywanie aplikacji systemu iOS/macOS do uwierzytelniania natywnego.
• Jeśli chcesz zebrać atrybuty użytkownika podczas rejestracji, skonfiguruj je, kiedy tworzysz przepływ rejestracji i logowania użytkownika.
• Aby zebrać nazwę użytkownika (alias) podczas rejestracji, włącz wbudowany atrybut użytkownika Nazwa użytkownika w przepływie użytkownika rejestracji dzierżawy.

Tworzenie konta użytkownika

Aby zarejestrować użytkownika przy użyciu jednorazowego kodu dostępu lub nazwy użytkownika (adresu e-mail) i hasła, należy zebrać wiadomość e-mail od użytkownika, a następnie wysłać wiadomość e-mail zawierającą jednorazowy kod dostępu do użytkownika. Użytkownik wprowadza prawidłowy kod dostępu jednorazowego wiadomości e-mail, aby zweryfikować swoją nazwę użytkownika.

Aby zarejestrować użytkownika, musisz:

1. Utwórz interfejs użytkownika w celu:

   • Zbierz wiadomość e-mail od użytkownika. Dodaj walidację do danych wejściowych, aby upewnić się, że użytkownik wprowadzi prawidłowy adres e-mail.
   • Zbierz hasło, jeśli zarejestrujesz się przy użyciu nazwy użytkownika (e-mail) i hasła.
   • Zbierz nazwę użytkownika (alias), jeśli aplikacja obsługuje logowanie oparte na aliasach.
   • Zbierz jednorazowy kod dostępu z adresu e-mail od użytkownika.
   • W razie potrzeby zbierz atrybuty użytkownika.
   • Wyślij ponownie jednorazowy kod dostępu, jeśli użytkownik go nie otrzyma.
   • Uruchom przepływ rejestracji.

2. W aplikacji dodaj przycisk, którego wybranie powoduje wyzwolenie następującego fragmentu kodu:

   @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)
   }
   

   • Aby zarejestrować użytkownika przy użyciu jednorazowego kodu wysyłanego e-mailem, użyj metody biblioteki signUp(parameters:delegate), która zwraca wynik asynchronicznie, wywołując jedną z metod przekazanego obiektu delegata, który musi implementować protokół SignUpStartDelegate. Poniższy wiersz kodu inicjuje proces rejestracji użytkownika:

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

     W metodzie signUp(parameters:delegate) przekaż instancję MSALNativeAuthSignUpParameters, zawierającą adres e-mail użytkownika z formularza zgłoszeniowego, wraz z delegatem (klasą implementującą protokół SignUpStartDelegate).

   • Aby zarejestrować użytkownika przy użyciu Email z hasłem, użyj następujących fragmentów kodu:

     @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)
     }
     

     Metoda signUp(parameters:delegate) biblioteki odpowiada asynchronicznie, wywołując jedną z metod obiektu delegata przekazanego jako argument, który musi implementować protokół SignUpStartDelegate. Poniższy wiersz kodu inicjuje proces rejestracji użytkownika:

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

     W metodzie signUp(parameters:delegate) przekaż instancję MSALNativeAuthSignUpParameters zawierającą adres e-mail użytkownika i jego hasło wraz z delegatem (klasą implementującą protokół SignUpStartDelegate).

   • Aby zaimplementować SignUpStartDelegate protokół jako rozszerzenie klasy, użyj:

     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)"
         }
     }
     

     Wywołanie signUp(parameters:delegate) powoduje wywołanie metod delegatów onSignUpCodeRequired() lub onSignUpStartError(). onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) jest wywoływana, aby wskazać, że kod został wysłany w celu zweryfikowania adresu e-mail użytkownika. Oprócz informacji o tym, dokąd kod został wysłany i ile zawiera cyfr, ta metoda delegata ma także parametr newState typu SignUpCodeRequiredState, który daje dostęp do dwóch nowych metod:

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

     Aby przesłać kod dostarczony przez użytkownika, użyj:

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

     • Aby zaimplementować SignUpVerifyCodeDelegate protokół jako rozszerzenie klasy, użyj:

       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!"
           }
       }
       

       Element submitCode(code:delegate) akceptuje parametr delegata i należy zaimplementować wymagane metody w protokole SignUpVerifyCodeDelegate . W najczęstszym scenariuszu otrzymujesz wywołanie onSignUpCompleted(newState), informujące, że użytkownik został zarejestrowany, a przepływ został zakończony.

Zbieranie atrybutów użytkownika podczas rejestracji

Niezależnie od tego, czy rejestrujesz użytkownika przy użyciu jednorazowego kodu dostępu e-mail, czy nazwy użytkownika (e-mail) i hasła, możesz zbierać atrybuty użytkownika przed utworzeniem konta użytkownika. Metodę signUp(parameters:delegate) można wywołać przy użyciu MSALNativeAuthSignUpParameters, która ma właściwość atrybutów.

1. Aby zebrać atrybuty użytkownika, użyj następującego fragmentu kodu:

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

   signUp(parameters:delegate)powoduje wywołanie metod delegata onSignUpCodeRequired() lub onSignUpStartError(), albo metody onSignUpAttributesInvalid(attributeNames: [String]), jeśli jest zaimplementowana w delegacie.

2. Aby zaimplementować SignUpStartDelegate protokół jako rozszerzenie klasy, użyj następującego fragmentu kodu:

   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)"
       }
   }
   

   Jeśli atrybuty są nieprawidłowe, wywoływana jest metoda onSignUpAttributesInvalid(attributeNames: [String]). W takim przypadku wyświetl listę nieprawidłowych atrybutów dla użytkownika. W przeciwnym razie wywoływana jest onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) wskazująca, że kod został wysłany w celu zweryfikowania adresu e-mail użytkownika. Oprócz szczegółów, takich jak odbiorca kodu i liczba cyfr kodu, ta metoda delegata ma newState parametr typu SignUpCodeRequiredState, który zapewnia dostęp do dwóch nowych metod:

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

Atrybuty użytkownika na co najmniej jednej stronie

Aby rozłożyć atrybuty na jednej lub większej liczbie stron, ustaw jako obowiązkowe w konfiguracji dzierżawy zarządzania tożsamością i dostępem klienta (CIAM) te atrybuty, które mają być zbierane na różnych stronach.

Wywołaj signUp(parameters:delegate) bez przekazywania żadnych atrybutów w instancji MSALNativeAuthSignUpParameters. Następnym krokiem jest wywołanie newState.submitCode(code: userSuppliedCode, delegate: self), aby zweryfikować adres e-mail użytkownika.

Zaimplementuj SignUpVerifyCodeDelegate protokół jako rozszerzenie do klasy tak jak poprzednio, ale tym razem należy zaimplementować opcjonalną metodę onSignUpAttributesRequired(attributes:newState) oprócz wymaganych metod:

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!"
    }
}

Ta metoda delegata ma newState parametr typu SignUpAttributesRequiredState, który zapewnia dostęp do nowej metody:

• submitAttributes(attributes:delegate)

Aby przesłać atrybuty dostarczone przez użytkownika, użyj następującego fragmentu kodu:

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

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

Również zaimplementuj protokół SignUpAttributesRequiredDelegate jako rozszerzenie swojej klasy:

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!"
    }
}

Jeśli użytkownik nie udostępnia wszystkich wymaganych atrybutów lub atrybuty są nieprawidłowe, te metody delegata są wywoływane:

• onSignUpAttributesInvalid: wskazuje, że co najmniej jeden z wysłanych atrybutów nie przeszedł pomyślnie sprawdzania poprawności danych wejściowych. Ten błąd zawiera parametr attributeNames, który jest listą wszystkich atrybutów wysłanych przez dewelopera, który zakończył się niepowodzeniem weryfikacji danych wejściowych.
• onSignUpAttributesRequired: wskazuje, że serwer wymaga wysłania co najmniej jednego atrybutu, zanim będzie można utworzyć konto użytkownika. Dzieje się tak, gdy co najmniej jeden atrybut jest ustawiany jako obowiązkowy w konfiguracji najemcy. Ten wynik zawiera parametr atrybutów, który jest listą obiektów MSALNativeAuthRequiredAttribute, które zawierają szczegółowe informacje o atrybutach użytkownika, których wymaga interfejs API.

Obie metody delegata zawierają nową referencję stanu. Użyj parametru newState, aby ponownie wywołać submitAttributes(attributes:delegate) z nowymi atrybutami.

Zbieranie nazwy użytkownika (aliasu) podczas rejestracji

Nazwa użytkownika (alias) jest specjalnym atrybutem użytkownika. Podobnie jak inne atrybuty, takie jak miasto lub kraj, zbierasz je podczas rejestracji. W przeciwieństwie do tych atrybutów użytkownik może później używać aliasu do logowania. Alias (na przykład "johndoe") daje użytkownikom krótszy, bardziej przyjazny sposób logowania się niż ich adres e-mail.

Nazwa użytkownika (alias) nie zastępuje nazwy użytkownika (adresu e-mail). Podczas tworzenia konta aplikacja musi zawsze zbierać nazwę użytkownika (adres e-mail) jako identyfikator podstawowy i zbiera alias jako atrybut obok wiadomości e-mail. Podczas logowania użytkownik może następnie zdecydować się na zalogowanie się przy użyciu nazwy użytkownika (adresu e-mail) lub nazwy użytkownika (aliasu).

Gdy w przepływie rejestracji użytkownika jest włączony wbudowany atrybut użytkownika Username, pakiet SDK przyjmuje go za pośrednictwem tego samego słownika atrybutów, który jest używany dla innych atrybutów, pod kluczem flatusername. Możesz przekazać nazwę użytkownika (alias) bezpośrednio w wywołaniu signUp , aby użytkownik nie musiał przechodzić przez oddzielny krok wymagany przez atrybuty.

Aby pobrać nazwę użytkownika (alias), dodaj pole nazwy użytkownika w interfejsie rejestracji obok pola adresu e-mail, a następnie przekaż alias jako atrybut w wywołaniu rejestracji:

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)

W przypadku jednorazowych przepływów kodu dostępu wiadomości e-mail (bez hasła) przekaż atrybuty bez ustawiania hasła:

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

Podczas obsługi błędów rejestracji nazwy użytkownika (aliasu) error.isUserAlreadyExists właściwość obejmuje również zduplikowany alias i error.isInvalidAttributes wyświetla nieprawidłową wartość aliasu.

Obsługa błędów rejestracji

Podczas rejestracji nie każda akcja kończy się powodzeniem. Na przykład użytkownik może spróbować zarejestrować się przy użyciu adresu e-mail, który jest już używany, lub przesłać nieprawidłowy kod.

We wcześniejszej implementacji SignUpStartDelegate protokołu błąd był po prostu wyświetlany podczas obsługi funkcji delegata onSignUpStartError(error) .

Aby ulepszyć środowisko użytkownika, zarządzając określonym typem błędu, użyj następującego fragmentu kodu:

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")"
    }
}

Opcjonalnie: Zaloguj się po procesie rejestracji

Po pomyślnym przepływie rejestracji możesz zalogować użytkownika bez inicjowania przepływu logowania. Jeśli użytkownik zarejestrował się przy użyciu nazwy użytkownika (aliasu), może zalogować się przy użyciu adresu e-mail lub aliasu. Dowiedz się więcej w artykule Tutorial: Sign in user automatically after sign-up in an iOS/macOS app article (Samouczek: logowanie użytkownika automatycznie po zarejestrowaniu się w aplikacji systemu iOS/macOS).

Następny krok