Tutoriel : Ajouter une inscription dans une application iOS/macOS à l’aide de l’authentification native

S’applique à : Locataires externes (en savoir plus)

Ce tutoriel montre comment inscrire un utilisateur à l’aide du code secret à usage unique ou du nom d’utilisateur (e-mail) et du mot de passe dans votre application iOS/macOS à l’aide de l’authentification native. Vous découvrez également comment collecter des attributs utilisateur lors de l’inscription, y compris un nom d’utilisateur (alias) et gérer les erreurs.

Dans ce tutoriel, vous allez :

Conditions préalables

• Suivez les étapes du tutoriel : Préparer votre application iOS/macOS pour l’authentification native.
• Si vous souhaitez collecter les attributs utilisateur lors de l’inscription, configurez les attributs utilisateur lorsque vous créez votre flux utilisateur d’inscription et de connexion.
• Pour collecter un nom d’utilisateur (alias) lors de l’inscription, activez l’attribut utilisateur intégré nom d’utilisateur dans le flux d’utilisateur d’inscription de votre locataire.

Inscrire un utilisateur

Pour inscrire un utilisateur à l’aide du code secret à usage unique ou du nom d’utilisateur (e-mail) et du mot de passe, vous collectez un e-mail auprès de l’utilisateur, puis envoyez un e-mail contenant un code secret à usage unique à l’utilisateur. L’utilisateur entre un code secret à usage unique valide pour valider son nom d’utilisateur.

Pour inscrire un utilisateur, vous devez :

1. Créer une interface utilisateur pour :

   • Collecter une adresse e-mail de l’utilisateur. Ajouter une validation à vos entrées pour vérifier que l’utilisateur entre une adresse e-mail valide.
   • Collecter un mot de passe si vous vous inscrivez avec un nom d’utilisateur (e-mail) et un mot de passe.
   • Collectez un nom d’utilisateur (alias) si votre application prend en charge la connexion basée sur des alias.
   • Collecter auprès de l’utilisateur un code secret à usage unique envoyé par e-mail.
   • Collecter les attributs utilisateur, si besoin.
   • Renvoyez le code secret à usage unique si l’utilisateur ne l’a pas reçu.
   • Démarrer le flux d’inscription.

2. Dans votre application, ajoutez un bouton dont l’événement de sélection déclenche l’extrait de code suivant :

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

   • Pour inscrire un utilisateur à l’aide du code secret à usage unique de l’e-mail, utilisez la méthode de signUp(parameters:delegate) la bibliothèque, qui répond de façon asynchrone en appelant l’une des méthodes sur l’objet délégué transmis, qui doit implémenter le SignUpStartDelegate protocole. La ligne de code suivante lance le processus d’inscription de l’utilisateur :

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

     Dans la signUp(parameters:delegate) méthode, transmettez une MSALNativeAuthSignUpParameters instance contenant l’adresse e-mail de l’utilisateur à partir du formulaire de soumission en même temps que le délégué (classe qui implémente le SignUpStartDelegate protocole).

   • Pour inscrire un utilisateur avec une adresse e-mail et un mot de passe, utilisez les extraits de code suivants :

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

     La méthode de la signUp(parameters:delegate) bibliothèque répond de façon asynchrone en appelant l’une des méthodes sur l’objet délégué transmis, qui doit implémenter le SignUpStartDelegate protocole. La ligne de code suivante lance le processus d’inscription de l’utilisateur :

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

     Dans la signUp(parameters:delegate) méthode, transmettez une MSALNativeAuthSignUpParameters instance contenant l’adresse e-mail de l’utilisateur et son mot de passe en même temps que le délégué (classe qui implémente le SignUpStartDelegate protocole).

   • Pour implémenter le SignUpStartDelegate protocole en tant qu’extension à votre classe, utilisez :

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

     L’appel à signUp(parameters:delegate) entraîne un appel à la méthode déléguée onSignUpCodeRequired() ou onSignUpStartError(). La méthode onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) est appelée pour indiquer qu’un code a été envoyé pour vérifier l’adresse e-mail de l’utilisateur. En plus des détails de l’emplacement d’envoi du code et du nombre de chiffres qu’il contient, cette méthode déléguée a également un newState paramètre de type SignUpCodeRequiredState, ce qui vous donne accès à deux nouvelles méthodes :

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

     Pour soumettre le code fourni par l’utilisateur, utilisez :

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

     • Pour implémenter le SignUpVerifyCodeDelegate protocole en tant qu’extension à votre classe, utilisez :

       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) accepte un paramètre délégué et vous devez implémenter les méthodes requises dans le protocole SignUpVerifyCodeDelegate. Dans le scénario le plus courant, vous recevez un appel à onSignUpCompleted(newState) pour vous indiquer que l’utilisateur s’est inscrit et que le processus est terminé.

Collecter les attributs utilisateur lors de l’inscription

Que vous inscriviez un utilisateur à l’aide d’un code secret à usage unique envoyé par e-mail ou à l’aide d’un nom d’utilisateur (e-mail) et d’un mot de passe, vous pouvez collecter les attributs utilisateur avant la création du compte de l’utilisateur. La méthode signUp(parameters:delegate) peut être appelée à l’aide d’un MSALNativeAuthSignUpParameters qui a une propriété d’attributs.

1. Pour collecter les attributs utilisateur, utilisez l’extrait de code suivant :

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

   Les signUp(parameters:delegate)résultats dans un appel à l'une des méthodes déléguées onSignUpCodeRequired() ou onSignUpStartError(), ou dans un appel à onSignUpAttributesInvalid(attributeNames: [String]) si elle est implémentée dans le délégué.

2. Pour implémenter le SignUpStartDelegate protocole en tant qu’extension à votre classe, utilisez l’extrait de code suivant :

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

   Si les attributs ne sont pas valides, la méthode onSignUpAttributesInvalid(attributeNames: [String]) est appelée. Dans ce cas, affichez la liste des attributs non valides à l’utilisateur. Sinon, la méthode onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) est appelée pour indiquer qu’un code a été envoyé pour vérifier l’adresse e-mail de l’utilisateur. Outre les détails tels que le destinataire du code et le nombre de chiffres du code, cette méthode déléguée a un newState paramètre de type SignUpCodeRequiredState, ce qui vous donne accès à deux nouvelles méthodes :

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

Attributs utilisateur sur une ou plusieurs pages

Pour répartir les attributs sur une ou plusieurs pages, définissez les attributs que vous envisagez de collecter sur différentes pages comme obligatoires dans la configuration du client d’identité et d’accès (CIAM).

Appelez signUp(parameters:delegate) sans passer d’attributs dans l’instance MSALNativeAuthSignUpParameters . L’étape suivante consiste à appeler newState.submitCode(code: userSuppliedCode, delegate: self) pour vérifier l’e-mail de l’utilisateur.

Implémentez le SignUpVerifyCodeDelegate protocole comme extension à votre classe comme avant, mais cette fois, vous devez implémenter la méthode onSignUpAttributesRequired(attributes:newState) facultative en plus des méthodes requises :

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

Cette méthode de délégué a un newState paramètre de type SignUpAttributesRequiredState, qui vous donne accès à une nouvelle méthode :

• submitAttributes(attributes:delegate)

Pour envoyer les attributs fournis par l’utilisateur, utilisez l’extrait de code suivant :

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

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

Implémentez également le SignUpAttributesRequiredDelegate protocole en tant qu’extension à votre classe :

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

Lorsque l’utilisateur ne fournit pas tous les attributs requis ou que les attributs ne sont pas valides, ces méthodes déléguées sont appelées :

• onSignUpAttributesInvalid : indique qu’un ou plusieurs attributs envoyés ont échoué à la validation d’entrée. Cette erreur contient un paramètre attributeNames, qui est une liste de tous les attributs envoyés par le développeur qui a échoué la validation d’entrée.
• onSignUpAttributesRequired : indique que le serveur nécessite l’envoi d’un ou plusieurs attributs avant que le compte d’utilisateur puisse être créé. Cela se produit quand un ou plusieurs attributs sont définis comme obligatoires dans la configuration du locataire. Ce résultat contient le paramètre attributs, une liste d’objets MSALNativeAuthRequiredAttribute, qui décrit les détails sur les attributs utilisateur requis par l’API.

Les deux méthodes déléguées contiennent une nouvelle référence d’état. Utilisez le newState paramètre pour appeler submitAttributes(attributes:delegate) à nouveau avec les nouveaux attributs.

Collecter un nom d’utilisateur (alias) lors de l’inscription

Le nom d’utilisateur (alias) est un attribut utilisateur spécial. Comme d’autres attributs tels que la ville ou le pays, vous le collectez lors de l’inscription. Contrairement à ces attributs, l’utilisateur peut utiliser ultérieurement l’alias pour se connecter. L’alias (par exemple, « johndoe ») offre aux utilisateurs un moyen plus court et plus convivial de se connecter que leur adresse e-mail.

Le nom d’utilisateur (alias) ne remplace pas le nom d’utilisateur (e-mail). Lors de l’inscription, l’application doit toujours collecter le nom d’utilisateur (e-mail) comme identificateur principal, et il collecte l’alias en tant qu’attribut en même temps que l’e-mail. Lors de la connexion, l’utilisateur peut ensuite choisir de se connecter avec son nom d’utilisateur (e-mail) ou son nom d’utilisateur (alias).

Lorsque l’attribut utilisateur intégré Username est activé dans votre flux d’inscription de l’utilisateur, le SDK l’accepte via le même dictionnaire d’attributs que pour les autres attributs, sous la clé flatusername. Vous pouvez passer le nom d’utilisateur (alias) directement dans l’appel signUp afin que l’utilisateur n’ait pas besoin d’effectuer une étape distincte d’attributs requis.

Pour collecter un nom d’utilisateur (alias), ajoutez un champ d’entrée pour le nom d’utilisateur dans votre interface utilisateur d’inscription en même temps que le champ de messagerie, puis transmettez l’alias en tant qu’attribut dans l’appel d’inscription :

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)

Pour les flux de code secret à usage unique par e-mail (sans mot de passe), transmettez les attributs sans définir de mot de passe :

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

Lors du traitement des erreurs lors de l’inscription avec nom d’utilisateur (alias), la propriété error.isUserAlreadyExists couvre également le cas d’un alias en double, et error.isInvalidAttributes indique une valeur d’alias non valide.

Gérer les erreurs d’inscription

Lors de l’inscription, certaines actions peuvent échouer. Par exemple, l’utilisateur peut essayer de s’inscrire avec une adresse e-mail déjà utilisée ou envoyer un code non valide.

Dans l’implémentation antérieure du SignUpStartDelegate protocole, l’erreur s’affichait simplement lors de la gestion de la onSignUpStartError(error) fonction de délégué.

Pour améliorer l’expérience utilisateur en gérant le type d’erreur particulier, utilisez l’extrait de code suivant :

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

Facultatif : Se connecter après un flux d’inscription

Après un processus d’inscription réussi, vous pouvez connecter un utilisateur sans démarrer un processus de connexion. Si l’utilisateur s’est inscrit avec un nom d’utilisateur (alias), il peut se connecter à l’aide de son adresse e-mail ou de son alias. Pour plus d’informations, consultez l’article Tutoriel : connecter l’utilisateur automatiquement après son inscription dans une application iOS/macOS.

Étape suivante