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

Dotyczy: Najemcy Workforce Najemcy zewnętrzni (dowiedzieć się więcej)

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.

Warunki wstępne

• Poradnik: przygotowanie aplikacji iOS/macOS do uwierzytelniania natywnego.
• Jeśli chcesz zebrać atrybuty użytkownika podczas rejestracji, skonfiguruj atrybuty użytkownika podczas utworzyć przepływ rejestracji i logowania użytkownika.

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 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 zapisać użytkownika przy użyciu jednorazowego kodu z poczty e-mail, używamy metody signUp(parameters:delegate) z biblioteki, która asynchronicznie reaguje, wywołując jedną z metod na przekazanym obiekcie delegowanym, który musi zaimplementować protokół SignUpStartDelegate. Poniższy wiersz kodu inicjuje proces rejestracji użytkownika:

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

     W metodzie signUp(parameters:delegate) przekazujemy wystąpienie MSALNativeAuthSignUpParameters zawierające adres e-mail użytkownika z formularza przesyłania obok delegata (klasa, która implementuje 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)
     }
     

     Używamy metody signUp(parameters:delegate) biblioteki, która reaguje asynchronicznie, wywołując jedną z metod w przekazanym obiekcie 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) przekazujemy wystąpienie MSALNativeAuthSignUpParameters zawierające adres e-mail użytkownika i jego hasło obok delegata (klasa, która implementuje protokół SignUpStartDelegate).

   • Aby zaimplementować protokół SignUpStartDelegate 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(parameters:delegate)powoduje wywołanie metody onSignUpCodeRequired() lub onSignUpStartError() delegata. onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) jest wywoływana, aby wskazać, że kod został wysłany w celu zweryfikowania adresu e-mail użytkownika. Wraz z pewnymi szczegółami dotyczącymi miejsca, do którego został wysłany kod, oraz liczby cyfr, które zawiera, ta metoda delegata ma również parametr newState typu SignUpCodeRequiredState, który umożliwia 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ć protokół SignUpVerifyCodeDelegate 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!"
           }
       }
       

       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 proces 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ć protokół SignUpStartDelegate 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 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ółowych informacji, takich jak odbiorca kodu i liczba jego cyfr, ta metoda delegata ma parametr newState 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 jednej lub więcej stronach, musimy ustawić atrybuty, które zamierzamy zebrać na różnych stronach jako obowiązkowe w konfiguracji dzierżawy zarządzania tożsamością i dostępem klientów (CIAM).

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

Implementujemy protokół SignUpVerifyCodeDelegate 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 parametr typu newState o typie SignUpAttributesRequiredState, który umożliwia 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 również protokół SignUpAttributesRequiredDelegate 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 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żyjemy parametru newState do ponownego wywołania submitAttributes(attributes:delegate) przy użyciu nowych atrybutów.

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 protokołu SignUpStartDelegate po prostu wyświetliliśmy błąd, gdy obsłużyliśmy funkcję 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ć się do użytkownika bez inicjowania przepływu logowania. 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

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