Zelfstudie: Registreren toevoegen in een iOS-/macOS-app met behulp van systeemeigen verificatie

Van toepassing op: Externe tenants (meer informatie)

In deze zelfstudie wordt gedemonstreerd hoe u een gebruiker registreert met behulp van eenmalige wachtwoordcode of gebruikersnaam (e-mailadres) en wachtwoord in uw iOS-/macOS-app met behulp van systeemeigen verificatie. U leert ook hoe u gebruikerskenmerken verzamelt tijdens het registreren, inclusief een gebruikersnaam (alias) en fouten verwerkt.

In deze handleiding leert u:

Voorwaarden

• Voltooi de stappen in zelfstudie: Uw iOS-/macOS-app voorbereiden voor systeemeigen verificatie.
• Als u gebruikerskenmerken wilt verzamelen tijdens het registreren, configureert u de gebruikerskenmerken wanneer u de gebruikersstroom voor registratie en aanmelding maakt.
• Als u een gebruikersnaam (alias) wilt verzamelen tijdens het registreren, schakelt u het ingebouwde gebruikerskenmerk gebruikersnaam in de gebruikersstroom van uw tenant in.

Een gebruiker registreren

Als u een gebruiker wilt registreren met behulp van de eenmalige wachtwoordcode of gebruikersnaam (e-mailadres) en wachtwoord van e-mail, verzamelt u een e-mailbericht van de gebruiker en verzendt u vervolgens een e-mail met een eenmalige wachtwoordcode naar de gebruiker. De gebruiker voert een geldige eenmalige wachtwoordcode voor een e-mail in om de gebruikersnaam te valideren.

Als u zich wilt registreren voor een gebruiker, moet u het volgende doen:

1. Maak een gebruikersinterface (UI) om:

   • Verzamel een e-mailbericht van de gebruiker. Voeg validatie toe aan uw invoer om ervoor te zorgen dat de gebruiker een geldig e-mailadres invoert.
   • Verzamel een wachtwoord als u zich registreert met gebruikersnaam (e-mailadres) en wachtwoord.
   • Verzamel een gebruikersnaam (alias) als uw app ondersteuning biedt voor aanmelding op basis van aliassen.
   • Verzamel een eenmalige wachtwoordcode voor e-mail van de gebruiker.
   • Verzamel indien nodig gebruikerskenmerken.
   • Eenmalige wachtwoordcode opnieuw verzenden als de gebruiker deze niet ontvangt.
   • Aanmeldproces starten.

2. Voeg in uw app een knop toe waarvan de geselecteerde gebeurtenis het volgende codefragment activeert:

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

   • Als u een gebruiker wilt registreren met behulp van eenmalige wachtwoordcode voor e-mail, gebruikt u de methode van signUp(parameters:delegate) de bibliotheek, die asynchroon reageert door een van de methoden aan te roepen voor het doorgegeven gedelegeerde-object, dat het SignUpStartDelegate protocol moet implementeren. Met de volgende coderegel wordt het aanmeldproces van de gebruiker gestart.

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

     Geef in de signUp(parameters:delegate)-methode een MSALNativeAuthSignUpParameters-instantie door die het e-mailadres van de gebruiker uit het verzendformulier bevat, samen met de delegate (een klasse die het SignUpStartDelegate-protocol implementeert).

   • Als u een gebruiker wilt registreren met e-mail met wachtwoord, gebruikt u de volgende codefragmenten:

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

     De signUp(parameters:delegate)-methode van de bibliotheek reageert asynchroon door een van de methoden van het doorgegeven gedelegeerde object aan te roepen, dat het SignUpStartDelegate-protocol moet implementeren. Met de volgende coderegel wordt het aanmeldproces van de gebruiker gestart.

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

     Geef in de signUp(parameters:delegate) methode een MSALNativeAuthSignUpParameters exemplaar door met het e-mailadres van de gebruiker en hun wachtwoord naast de gemachtigde (een klasse die het SignUpStartDelegate protocol implementeert).

   • Als u het SignUpStartDelegate protocol wilt implementeren als een extensie voor uw klasse, gebruikt u:

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

     De aanroep van signUp(parameters:delegate) resulteert in een aanroep naar onSignUpCodeRequired() of onSignUpStartError() delegeringsmethoden. De onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) wordt aangeroepen om aan te geven dat er een code is verzonden om het e-mailadres van de gebruiker te verifiëren. Naast enkele details van waar de code is verzonden en hoeveel cijfers de code bevat, heeft deze gedelegeerdemethode ook een newState parameter van het type SignUpCodeRequiredState, waarmee u toegang krijgt tot twee nieuwe methoden:

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

     Als u de code wilt verzenden die de gebruiker heeft opgegeven, gebruikt u:

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

     • Als u het SignUpVerifyCodeDelegate protocol wilt implementeren als een extensie voor uw klasse, gebruikt u:

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

       De submitCode(code:delegate) parameter accepteert een gemachtigde en u moet de vereiste methoden in het SignUpVerifyCodeDelegate protocol implementeren. In het meest voorkomende scenario ontvangt u een callback naar onSignUpCompleted(newState) die aangeeft dat de gebruiker is aangemeld en dat het proces is voltooid.

Gebruikerskenmerken verzamelen tijdens het registreren

Of u nu een gebruiker registreert met eenmalige wachtwoordcode of gebruikersnaam (e-mailadres) en wachtwoord, u kunt gebruikerskenmerken verzamelen voordat het account van een gebruiker wordt gemaakt. De methode signUp(parameters:delegate) kan worden aangeroepen door een MSALNativeAuthSignUpParameters met een eigenschap attributen.

1. Gebruik het volgende codefragment om gebruikerskenmerken te verzamelen:

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

   De signUp(parameters:delegate)resulteert in een aanroep van de onSignUpCodeRequired()- of onSignUpStartError()-delegeermethoden, of in een aanroep van onSignUpAttributesInvalid(attributeNames: [String]) als deze is geïmplementeerd in de delegate.

2. Gebruik het volgende codefragment om het SignUpStartDelegate protocol als extensie voor uw klasse te implementeren:

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

   Als de kenmerken ongeldig zijn, wordt de methode onSignUpAttributesInvalid(attributeNames: [String]) aangeroepen. In dit geval geeft u de lijst met ongeldige kenmerken weer voor de gebruiker. Anders wordt de onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) aangeroepen om aan te geven dat er een code is verzonden om het e-mailadres van de gebruiker te verifiëren. Afgezien van details zoals de ontvanger van de code en het aantal cijfers van de code, heeft deze gemachtigde methode een newState parameter van het type SignUpCodeRequiredState, waarmee u toegang hebt tot twee nieuwe methoden:

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

Gebruikerskenmerken op een of meer pagina's

Als u de kenmerken wilt verspreiden over een of meer pagina's, stelt u de kenmerken in die u op verschillende pagina's wilt verzamelen als verplicht in de tenantconfiguratie van de klantidentiteit en toegangsbeheer (CIAM).

Roep signUp(parameters:delegate) aan zonder attributen door te geven in de MSALNativeAuthSignUpParameters-instantie. De volgende stap is het aanroepen newState.submitCode(code: userSuppliedCode, delegate: self) om het e-mailadres van de gebruiker te verifiëren.

Implementeer het SignUpVerifyCodeDelegate protocol als een uitbreiding voor uw klasse, maar deze keer moet u de optionele methode onSignUpAttributesRequired(attributes:newState) naast de vereiste methoden implementeren:

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

Deze gemachtigde methode heeft een newState parameter van het type SignUpAttributesRequiredState, waarmee u toegang krijgt tot een nieuwe methode:

• submitAttributes(attributes:delegate)

Als u de kenmerken wilt verzenden die de gebruiker heeft opgegeven, gebruikt u het volgende codefragment:

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

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

Implementeer het SignUpAttributesRequiredDelegate protocol ook als een extensie voor uw 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!"
    }
}

Wanneer de gebruiker niet alle vereiste kenmerken opgeeft of de kenmerken ongeldig zijn, worden deze gemachtigdenmethoden aangeroepen:

• onSignUpAttributesInvalid: geeft aan dat een of meer kenmerken die zijn verzonden, de invoervalidatie is mislukt. Deze fout bevat een parameter genaamd attributeNames, dit is een lijst van alle attributen die door de ontwikkelaar zijn verzonden en die de invoervalidatie niet hebben doorstaan.
• onSignUpAttributesRequired: geeft aan dat voor de server een of meer kenmerken moeten worden verzonden, voordat het gebruikersaccount kan worden gemaakt. Dit gebeurt wanneer een of meer kenmerken zijn ingesteld als verplicht in de tenantconfiguratie. Dit resultaat bevat kenmerkenparameter, een lijst met MSALNativeAuthRequiredAttribute objecten, waarin details worden beschreven over de gebruikerskenmerken die de API nodig heeft.

Beide delegatiemethoden bevatten een nieuwe toestandreferentie. Gebruik de newState parameter om opnieuw aan te roepen submitAttributes(attributes:delegate) met de nieuwe kenmerken.

Een gebruikersnaam (alias) verzamelen tijdens het registreren

De gebruikersnaam (alias) is een speciaal gebruikerskenmerk. Net als andere kenmerken, zoals plaats of land, verzamelt u deze tijdens de registratie. In tegenstelling tot deze kenmerken kan de gebruiker later de alias gebruiken om zich aan te melden. De alias (bijvoorbeeld 'johndoe') biedt gebruikers een kortere, gebruiksvriendelijkere manier om zich aan te melden dan hun e-mailadres.

De gebruikersnaam (alias) vervangt de gebruikersnaam (e-mail) niet. Tijdens de registratie moet de app altijd de gebruikersnaam (e-mail) verzamelen als primaire id en wordt de alias verzameld als een kenmerk naast de e-mail. Bij het aanmelden kan de gebruiker zich vervolgens aanmelden met de gebruikersnaam (e-mail) of de gebruikersnaam (alias).

Wanneer het ingebouwde gebruikerskenmerk Gebruikersnaam is ingeschakeld in uw gebruikersstroom voor registratie, accepteert de SDK deze via dezelfde kenmerkenwoordenlijst die wordt gebruikt voor andere kenmerken als de flatusername sleutel. U kunt de gebruikersnaam (alias) rechtstreeks in de signUp aanroep doorgeven, zodat de gebruiker geen afzonderlijke stap voor kenmerken hoeft te doorlopen.

Als u een gebruikersnaam (alias) wilt verzamelen, voegt u een invoerveld toe voor de gebruikersnaam in uw aanmeldingsgebruikersinterface naast het e-mailveld en geeft u de alias door als een kenmerk in de aanmeldingsoproep:

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)

Geef voor eenmalige wachtwoordcodestromen van e-mail (zonder wachtwoord) de kenmerken door zonder een wachtwoord in te stellen:

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

Bij het afhandelen van fouten bij het registreren van een gebruikersnaam (alias), behandelt de error.isUserAlreadyExists eigenschap ook een dubbele alias en error.isInvalidAttributes wordt een ongeldige aliaswaarde weergegeven.

Registratiefouten afhandelen

Tijdens de registratie lukt niet elke actie. De gebruiker kan bijvoorbeeld proberen zich aan te melden met een e-mailadres dat al in gebruik is of een ongeldige code verzenden.

In de eerdere implementatie van het SignUpStartDelegate protocol werd de fout gewoon weergegeven bij het verwerken van de onSignUpStartError(error) gedelegeerde functie.

Gebruik het volgende codefragment om de gebruikerservaring te verbeteren door het specifieke fouttype te beheren:

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

Optioneel: Aanmelden na een registratieproces

Nadat een geslaagde registratiestroom is voltooid, kunt u zich aanmelden bij een gebruiker zonder dat u een aanmeldingsstroom hoeft in teitiëren. Als de gebruiker zich heeft geregistreerd met een gebruikersnaam (alias), kan hij of zij zich aanmelden met het e-mailadres of de alias. Meer informatie vindt u in de Zelfstudie: Gebruiker automatisch aanmelden na aanmelding in een iOS-/macOS-app artikel.

Volgende stap