Lernprogramm: Hinzufügen der Registrierung in einer iOS/macOS-App mithilfe der systemeigenen Authentifizierung

Gilt für: Grüner Kreis mit einem weißen Häkchensymbol, das angibt, dass der folgende Inhalt für externe Mandanten gilt. Externe Mandanten (weitere Informationen)

In diesem Lernprogramm wird veranschaulicht, wie Sie einen Benutzer mithilfe der einmaligen E-Mail-Kennung oder des Benutzernamens (E-Mail) und des Kennworts in Ihrer iOS/macOS-App mithilfe der systemeigenen Authentifizierung registrieren. Außerdem erfahren Sie, wie Sie Benutzerattribute während der Registrierung sammeln, einschließlich eines Benutzernamens (Alias) und behandeln Fehler.

In diesem Tutorial lernen Sie:

  • Registrieren Sie einen Benutzer mithilfe eines E-Mail-Einmal-Passcodes oder mit Benutzername (E-Mail-Adresse) und Kennwort.
  • Sammeln Von Benutzerattributen während der Registrierung, einschließlich eines Benutzernamens (Alias).
  • Behandeln von Registrierungsfehlern

Voraussetzungen

Registrieren eines Benutzers

Um einen Benutzer mithilfe der Einmalkennung oder des Benutzernamens (E-Mail) und des Kennworts zu registrieren, sammeln Sie eine E-Mail vom Benutzer und senden dann eine E-Mail mit einer Einmalkennung an den Benutzer. Der Benutzer gibt einen gültigen E-Mail-Einmal-Passcode ein, um seinen Benutzernamen zu validieren.

Zum Registrieren eines Benutzers müssen Sie:

  1. Eine Benutzeroberfläche für Folgendes erstellen:

    • Erfassen einer E-Mail-Adresse des Benutzers. Fügen Sie eine Validierung für die Eingaben hinzu, um sicherzustellen, dass der Benutzer eine gültige E-Mail-Adresse eingibt.
    • Erfassen eines Kennworts, wenn die Registrierung mit Benutzername (E-Mail-Adresse) und Kennwort erfolgt
    • Erfassen Sie einen Benutzernamen (Alias), wenn Ihre App die Anmeldung mit Alias unterstützt.
    • Erfassen eines E-Mail-Einmal-Passcodes vom Benutzer
    • Erfassen von Benutzerattributen bei Bedarf
    • Erneutes Senden des Einmal-Passcodes, wenn der Benutzer ihn nicht empfängt
    • Starten des Registrierungsflows

  2. Fügen Sie in Ihrer App eine Schaltfläche hinzu, deren Auswahlereignis den folgenden Codeschnipsel auslöst:

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

    • Verwenden Sie zum Registrieren eines Benutzers per E-Mail-Einmalkennung die Methode der Bibliothek signUp(parameters:delegate) , die asynchron reagiert, indem Sie eine der Methoden für das übergebene Delegatenobjekt aufrufen, das das SignUpStartDelegate Protokoll implementieren muss. Die folgende Codezeile initiiert den Prozess für die Benutzerregistrierung:

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

      Übergeben Sie in der signUp(parameters:delegate) Methode eine MSALNativeAuthSignUpParameters Instanz, die die E-Mail-Adresse des Benutzers aus dem Übermittlungsformular zusammen mit dem Delegaten enthält (eine Klasse, die das SignUpStartDelegate Protokoll implementiert).

    • Wenn Sie einen Benutzer per E-Mail-Adresse mit Kennwort registrieren möchten, verwenden Sie die folgenden Codeschnipsel:

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

      Die Methode der signUp(parameters:delegate) Bibliothek reagiert asynchron, indem eine der Methoden für das übergebene Delegatenobjekt aufgerufen wird, das das SignUpStartDelegate Protokoll implementieren muss. Die folgende Codezeile initiiert den Prozess für die Benutzerregistrierung:

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

      Übergeben Sie in der signUp(parameters:delegate) Methode eine MSALNativeAuthSignUpParameters Instanz, die die E-Mail-Adresse des Benutzers und ihr Kennwort zusammen mit dem Delegaten enthält (eine Klasse, die das SignUpStartDelegate Protokoll implementiert).

    • Verwenden Sie Folgendes, um das SignUpStartDelegate Protokoll als Erweiterung für Ihre Klasse zu implementieren:

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

      Der Aufruf von signUp(parameters:delegate) führt zu einem Aufruf entweder der Delegatmethoden onSignUpCodeRequired() oder onSignUpStartError(). onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) wird aufgerufen, um anzugeben, dass ein Code gesendet wurde, um die Benutzer-E-Mail-Adresse zu überprüfen. Zusammen mit einigen Details dazu, wo der Code gesendet wurde und wie viele Ziffern sie enthält, verfügt diese Delegatmethode auch über einen newState Parameter vom Typ SignUpCodeRequiredState, der Ihnen Zugriff auf zwei neue Methoden ermöglicht:

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

      Um den vom Benutzer bereitgestellten Code zu übermitteln, verwenden Sie Folgendes:

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

      • Verwenden Sie Folgendes, um das SignUpVerifyCodeDelegate Protokoll als Erweiterung für Ihre Klasse zu implementieren:

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

        Der submitCode(code:delegate) akzeptiert einen Delegatenparameter, und Sie müssen die erforderlichen Methoden im Protokoll SignUpVerifyCodeDelegate implementieren. Im gängigsten Fall wird onSignUpCompleted(newState) aufgerufen, wodurch angezeigt wird, dass der Benutzer registriert wurde und der Vorgang abgeschlossen ist.

Sammeln von Benutzerattributen während der Registrierung

Unabhängig davon, ob Sie einen Benutzer mit einem E-Mail-Einmal-Passcode oder mit Benutzername (E-Mail-Adresse) und Kennwort registrieren, können Sie Benutzerattribute erfassen, bevor das Konto eines Benutzers erstellt wird: Die signUp(parameters:delegate)-Methode kann mithilfe einer MSALNativeAuthSignUpParameters aufgerufen werden, die über eine Attributeigenschaft verfügt.

  1. Verwenden Sie zum Erfassen von Benutzerattributen den folgenden Codeschnipsel:

    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) resultiert in einem Aufruf einer der Stellvertretungsmethoden onSignUpCodeRequired() oder onSignUpStartError() oder in einem Aufruf von onSignUpAttributesInvalid(attributeNames: [String]), wenn sie in der Stellvertretung implementiert ist.

  2. Verwenden Sie den folgenden Codeausschnitt, um das SignUpStartDelegate Protokoll als Erweiterung für Ihre Klasse zu implementieren:

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

    Wenn die Attribute ungültig sind, wird die Methode onSignUpAttributesInvalid(attributeNames: [String]) aufgerufen. Zeigen Sie in diesem Fall die Liste der ungültigen Attribute für den Benutzer an. Andernfalls wird onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) aufgerufen, um anzugeben, dass ein Code gesendet wurde, um die E-Mail-Adresse des Benutzers zu überprüfen. Neben Details wie dem Empfänger des Codes und der Anzahl der Ziffern des Codes verfügt diese Delegatmethode über einen newState Parameter vom Typ SignUpCodeRequiredState, der Ihnen Zugriff auf zwei neue Methoden ermöglicht:

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

Benutzerattribute auf einer oder mehreren Seiten

Um die Attribute auf einer oder mehreren Seiten zu verteilen, markieren Sie in der Mandantenkonfiguration für Kundenidentitäts- und Zugriffsverwaltung (CIAM) die Attribute, die Sie über verschiedene Seiten hinweg erfassen möchten, als obligatorisch.

Rufen Sie signUp(parameters:delegate) auf, ohne dabei Attribute in der Instanz MSALNativeAuthSignUpParameters zu übergeben. Der nächste Schritt besteht darin, newState.submitCode(code: userSuppliedCode, delegate: self) aufzurufen, um die E-Mail-Adresse des Benutzers zu überprüfen.

Implementieren Sie das SignUpVerifyCodeDelegate Protokoll wie zuvor als Erweiterung für Ihre Klasse, aber dieses Mal müssen Sie zusätzlich zu den erforderlichen Methoden die optionale Methode onSignUpAttributesRequired(attributes:newState) implementieren:

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

Diese Delegatmethode verfügt über einen newState Parameter vom Typ SignUpAttributesRequiredState, der Ihnen Zugriff auf eine neue Methode ermöglicht:

  • submitAttributes(attributes:delegate)

Verwenden Sie den folgenden Codeausschnitt, um die vom Benutzer bereitgestellten Attribute zu übermitteln:

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

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

Implementieren Sie das SignUpAttributesRequiredDelegate Protokoll auch als Erweiterung für Ihre Klasse:

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

Wenn der Benutzer nicht alle erforderlichen Attribute bereitstellt oder die Attribute ungültig sind, werden diese Delegatmethoden aufgerufen:

  • onSignUpAttributesInvalid: Gibt an, dass bei mindestens einem gesendeten Attribut die Eingabeüberprüfung fehlgeschlagen ist. Dieser Fehler enthält einen attributNames-Parameter, bei dem es sich um eine Liste aller Attribute handelt, die vom Entwickler gesendet wurden und bei denen die Eingabeüberprüfung fehlgeschlagen ist.
  • onSignUpAttributesRequired: Gibt an, dass an den Server mindestens ein Attribut gesendet werden muss, bevor das Benutzerkonto erstellt werden kann. Dies geschieht, wenn mindestens ein Attribut in der Mandantenkonfiguration als obligatorisch festgelegt ist. Dieses Ergebnis enthält einen Attributparameter, bei dem es sich um eine Liste von MSALNativeAuthRequiredAttribute-Objekten handelt, die Details zu den von der API benötigten Benutzerattributen enthalten.

Beide Stellvertretungsmethoden enthalten einen Verweis auf den neuen Status. Verwenden Sie den newState Parameter, um erneut mit den neuen Attributen aufzurufen submitAttributes(attributes:delegate) .

Benutzernamen (Alias) bei der Registrierung abfragen

Der Benutzername (Alias) ist ein spezielles Benutzerattribute. Wie bei anderen Attributen wie Stadt oder Land erfassen Sie sie während der Registrierung. Im Gegensatz zu diesen Attributen kann der Benutzer später den Alias verwenden, um sich anzumelden. Der Alias (z. B. "johndoe") bietet Benutzern eine kürzere, benutzerfreundlichere Möglichkeit, sich anzumelden als ihre E-Mail-Adresse.

Der Benutzername (Alias) ersetzt nicht den Benutzernamen (E-Mail). Während der Registrierung muss die App immer den Benutzernamen (E-Mail) als primären Bezeichner sammeln und den Alias als Attribut zusammen mit der E-Mail sammeln. Bei der Anmeldung kann sich der Benutzer dann entweder mit dem Benutzernamen (E-Mail) oder dem Benutzernamen (Alias) anmelden.

Wenn das integrierte Benutzerattribute "Benutzername " in Ihrem Benutzerablauf für die Registrierung aktiviert ist, akzeptiert das SDK es über dasselbe Attributverzeichnis, das für andere Attribute verwendet wird, wie der flatusername Schlüssel. Sie können den Benutzernamen (Alias) direkt im signUp Aufruf übergeben, damit der Benutzer keinen separaten erforderlichen Schritt für Attribute durchlaufen muss.

Um einen Benutzernamen (Alias) zu erfassen, fügen Sie in Ihrer Registrierungsoberfläche neben dem E-Mail-Feld ein Eingabefeld für den Benutzernamen hinzu und übergeben Sie dann den Alias als Attribut im Registrierungsaufruf:

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)

Für E-Mail-Einmalpasscode-Abläufe (ohne Passwort) übergeben Sie die Attribute, ohne ein Passwort festzulegen:

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

Bei der Behandlung von Fehlern bei der Registrierung von Benutzernamen (Alias) deckt die error.isUserAlreadyExists Eigenschaft auch einen doppelten Alias ab und error.isInvalidAttributes zeigt einen ungültigen Aliaswert an.

Behandeln von Registrierungsfehlern

Bei der Registrierung ist nicht jede Aktion erfolgreich. Beispielsweise versucht der Benutzer möglicherweise, sich mit einer E-Mail-Adresse anzumelden, die bereits verwendet wird, oder einen ungültigen Code übermitteln.

In der früheren Implementierung des SignUpStartDelegate Protokolls wurde der Fehler beim Behandeln der onSignUpStartError(error) Stellvertretungsfunktion einfach angezeigt.

Verwenden Sie den folgenden Codeschnipsel, um die Benutzererfahrung zu verbessern, indem Sie den jeweiligen Fehlertyp verwalten:

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

Optional: Anmelden nach einem Registrierungsflow

Nach einem erfolgreichen Registrierungsablauf können Sie sich bei einem Benutzer anmelden, ohne einen Anmeldeablauf zu initiieren. Wenn sich der Benutzer mit einem Benutzernamen (Alias) registriert hat, kann er sich entweder mit seiner E-Mail-Adresse oder ihrem Alias anmelden. Erfahren Sie mehr im Artikel Tutorial: Automatische Benutzeranmeldung nach der Registrierung in einer iOS/macOS App.

Nächster Schritt

Tutorial: An- und Abmeldung in iOS/macOS App mit nativer Authentifizierung hinzufügen

  • Last updated on