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

Dotyczy: iOS (Swift) macOS (Swift)

W tym samouczku pokazano, jak zarejestrować użytkownika przy użyciu jednorazowego kodu dostępu lub nazwy użytkownika (adresu e-mail) i hasła oraz zbierać atrybuty użytkownika w aplikacji systemu iOS/macOS przy użyciu uwierzytelniania natywnego.

• Zarejestruj użytkownika przy użyciu jednorazowego kodu dostępu lub nazwy użytkownika (e-mail) i hasła.
• Zbierz atrybuty użytkownika podczas rejestracji.
• Obsługa błędów rejestracji.

Wymagania wstępne

• Samouczek: przygotowywanie aplikacji systemu iOS/macOS do uwierzytelniania natywnego.
• Jeśli chcesz zbierać atrybuty użytkownika podczas rejestracji, skonfiguruj atrybuty użytkownika podczas tworzenia przepływu użytkownika rejestracji i logowania.

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 jednorazowy kod dostępu wiadomości 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
       }
   
       nativeAuth.signUp(username: email, delegate: self)
   }
   

   • Aby zarejestrować użytkownika przy użyciu jednorazowego kodu dostępu poczty e-mail, użyjemy metody biblioteki signUp(username:delegate) , która reaguje asynchronicznie, wywołując jedną z metod w przekazanym obiekcie delegata, który musi zaimplementować SignUpStartDelegate protokół. Poniższy wiersz kodu inicjuje proces rejestracji użytkownika:

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

     W metodzie signUp(username:delegate) przekazujemy adres e-mail użytkownika z formularza przesyłania i delegata (klasa, która implementuje SignUpStartDelegate protokół).

   • Aby zarejestrować użytkownika przy użyciu adresu e-mail 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
         }
     
         nativeAuth.signUp(username: email,password: password,delegate: self)
     }
     

     Używamy metody biblioteki signUp(username:password:delegate) , która reaguje asynchronicznie, wywołując jedną z metod w przekazanym obiekcie delegata, który musi implementować SignUpStartDelegate protokół. Poniższy wiersz kodu inicjuje proces rejestracji użytkownika:

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

     W metodzie signUp(username:password:delegate) przekazujemy adres e-mail użytkownika, hasło i delegat (klasę, która implementuje SignUpStartDelegate protokół).

   • 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 metody signUp(username:password:delegate) lub signUp(username:delegate) powoduje wywołanie onSignUpCodeRequired() metody lub onSignUpStartError() delegowania. Element onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) jest wywoływany, aby wskazać, że kod został wysłany w celu zweryfikowania adresu e-mail użytkownika. Wraz ze szczegółowymi informacjami o tym, gdzie został wysłany kod i ile cyfr zawiera, ta metoda delegata ma newState również parametr typu SignUpCodeRequiredState, który daje nam 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 musimy zaimplementować wymagane metody w protokole SignUpVerifyCodeDelegate . W najbardziej typowym scenariuszu otrzymujemy wywołanie onSignUpCompleted(newState) wskazujące, że użytkownik został zarejestrowany, a przepływ został ukończony.

Zbieraj atrybuty 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. Metoda signUp(username:attributes:delegate) akceptuje atrybuty jako parametr.

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

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

   Metoda signUp(username:attributes:delegate) lub ignUp(username:password:attributes:delegate) powoduje wywołanie onSignUpCodeRequired() metod lub onSignUpStartError() delegowania albo wywołanie metody , jeśli onSignUpAttributesInvalid(attributeNames: [String]) jest zaimplementowane w delegatu.

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 tym przypadku wyświetlamy listę nieprawidłowych atrybutów dla użytkownika. W przeciwnym razie element jest wywoływany w celu wskazania, onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) ż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 daje nam 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 co najmniej jedną stronę, musimy ustawić atrybuty, które zamierzamy zebrać na różnych stronach jako obowiązkowe w konfiguracji dzierżawy zarządzania tożsamościami i dostępem klienta (CIAM).

Wywołujemy signUp(username:password:delegate) bez przekazywania żadnych atrybutów. Następnym krokiem będzie wywołanie newState.submitCode(code: userSuppliedCode, delegate: self) metody w celu zweryfikowania poczty e-mail użytkownika.

Zaimplementujemy SignUpVerifyCodeDelegate protokół jako rozszerzenie klasy tak jak poprzednio, ale tym razem musimy 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 daje nam 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)

Zaimplementujemy SignUpAttributesRequiredDelegate również protokół jako rozszerzenie do naszej 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 atrybut, który został wysłany, nie powiodło się sprawdzanie 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 dzierżawy. Ten wynik zawiera parametr atrybutów, który jest listą MSALNativeAuthRequiredAttribute obiektów, które zawierają szczegółowe informacje o atrybutach użytkownika, których wymaga interfejs API.

Obie metody delegata zawierają nowe odwołanie do stanu. Użyjemy parametru newState , aby wywołać submitAttributes(attributes:delegate) ponownie nowe atrybuty.

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 po prostu wyświetliliśmy błąd 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 przepływie rejestracji

Po pomyślnym przepływie rejestracji możesz zalogować się do użytkownika bez inicjowania przepływu logowania. Dowiedz się więcej w artykule Samouczek: logowanie użytkownika automatycznie po zarejestrowaniu się w aplikacji systemu iOS/macOS.

Następny krok

Samouczek: dodawanie logowania i wylogowywanie w aplikacji dla systemu iOS/macOS przy użyciu uwierzytelniania natywnego