Migrer de Hooks vers Actions

Découvrez comment migrer votre code Hooks Auth0 existant vers du code Actions Auth0.

Lorsque vous convertissez des Hooks existants en Actions, vous devez associer la nouvelle Action au déclencheur correspondant au type de Hook. Si vous suivez les étapes ci-dessous et utilisez les correspondances que nous y indiquons, vous obtiendrez un comportement identique.

​

Planifiez votre migration

Les Actions déployées s’exécutent après les Hooks actifs. Vous pouvez donc convertir les Hooks un par un dans le Dashboard, ou tous en même temps à l’aide de la Management API.

Vous devrez convertir le code, puis activer l’Action et désactiver le Hook. L’activation de l’Action et la désactivation du Hook peuvent se faire rapidement l’une après l’autre, mais selon l’ordre, il pourrait y avoir une courte période pendant laquelle les deux s’exécutent, ou aucun des deux.

C’est pourquoi nous vous recommandons de migrer votre pipeline étape par étape : convertissez des portions du code de vos Hooks en code d’Action, testez-les dans un environnement de préproduction, puis mettez-les en production une portion à la fois. Comme les Hooks actifs s’exécutent avant les Actions déployées, vous pouvez conserver une partie de la logique dans les Hooks pendant que vous développez et testez d’autres éléments de logique dans les Actions.

Conseils pour planifier votre migration

• Utilisez des indicateurs pour éviter de dupliquer des opérations coûteuses ou ponctuelles.
• Assurez-vous d’effectuer les changements à un moment où l’impact et le trafic seront au plus bas.
• Envisagez d’utiliser Auth0 Deploy CLI pour automatiser par script, tester et mettre en œuvre rapidement la migration, en une seule fois ou de façon itérative.

​

Comprendre les limites

Bien que les Actions puissent prendre en charge la grande majorité des cas couverts par les Hooks, vous devriez connaître certaines limites avant de commencer votre migration. (Rappel : vous pouvez exécuter à la fois des Hooks et des Actions pendant la migration.)

• Les Actions ne peuvent pas conserver des données, comme des jetons d’accès ou des réponses d’API, d’une exécution à l’autre.
• Les Actions ne disposent ni d’un jeton d’accès pour la Management API ni d’un accès à l’objet global auth0, contrairement aux Hooks.

Pour obtenir la liste complète des limites, consultez Limites des Actions.

​

Convertir le code

Pour convertir un Hook en Action, vous devez remplacer le code propre aux Hooks par le code d’Actions. Cette section présente les tâches à effectuer pour transformer un Hook fonctionnel en son Action équivalente.

Conseils pour convertir le code

• En général, recherchez les propriétés en lecture seule des objets transmis à la fonction Hooks dans l’objet event d’Actions.
• Utilisez l’éditeur de code d’Actions dans Auth0 Dashboard pour écrire votre code; il vous aidera en mettant les erreurs en évidence et en proposant des suggestions d’autocomplétion.
• Avant la mise en production, testez soigneusement vos nouvelles Actions dans un environnement de préproduction ou de test.

​

Copier le code d’un Hook dans une nouvelle Action

Nous vous recommandons de copier le code de votre Hook dans une nouvelle Action et d’utiliser l’éditeur de code d’Actions dans Auth0 Dashboard ; cela vous aidera à repérer les problèmes non résolus dans votre code.

1. Connectez-vous à votre locataire de production, puis copiez le code du Hook que vous souhaitez convertir.

2. Basculez vers un locataire hors production, puis accédez à Auth0 Dashboard > Actions > Library.

3. Sélectionnez Build Custom, puis :

   • Saisissez un Name pour votre Action qui correspond au nom du Hook que vous convertissez.

   • Repérez Trigger, puis sélectionnez le déclencheur d’Actions approprié** :**

     Type de Hook	Déclencheur d’Actions
     Client Credentials Exchange	M2M/Client-Credentials
     Pre-User-Registration	Pre User Registration
     Post-User-Registration	Post User Registration
     Post-Change-Password	Post Change Password
     Envoi d’un message téléphonique	Envoi d’un message téléphonique

   • Repérez Runtime, puis sélectionnez Node 18.

   • Sélectionnez Create.

4. Dans le bloc de code de l’éditeur de code d’Actions, collez le code du Hook que vous souhaitez convertir sous la fonction exportée.

5. Apportez les modifications décrites dans le reste de cet article à mesure que vous déplacez le code dans la fonction. Vous devriez aussi consulter l’objet event associé au nouveau déclencheur d’Actions ; vous verrez des liens vers la documentation pertinente plus loin dans ce guide, lorsque vous arriverez à la section Modifier la façon dont les données sont accessibles.

​

Modifier la déclaration de fonction

Les fonctions Hooks sont exportées par défaut, tandis que les fonctions Actions utilisent des exports nommés. Selon le type de Hook que vous convertissez, l’export nommé change. Les correspondances sont les suivantes :

Type de Hook	Export nommé
Échange d’identifiants d’application	onExecuteCredentialsExchange
Préinscription de l’utilisateur	onExecutePreUserRegistration
Post-inscription de l’utilisateur	onExecutePostUserRegistration
Après le changement de mot de passe	onExecutePostChangePassword
Envoi d’un message téléphonique	onExecuteSendPhoneMessage

Avant

module.exports = async function myHooksFunction(){}

Après

// Échange de justificatifs d'application
exports.onExecuteCredentialsExchange = async (event, api) => {}

// Pré-inscription de l'utilisateur
exports.onExecutePreUserRegistration = async (event, api) => {}

// Post-inscription de l'utilisateur
exports.onExecutePostUserRegistration = async (event) => {}

// Post-changement de mot de passe
exports.onExecutePostChangePassword = async (event) => {}

// Envoi d'un message téléphonique
exports.onExecuteSendPhoneMessage = async (event) => {}

​

Convertir les dépendances

Hooks et Actions gèrent les dépendances de façon similaire. Dans les deux cas, les dépendances sont ajoutées séparément dans l’interface utilisateur ou par la Management API, puis incluses dans le code. Dans les deux cas également, vous pouvez utiliser require avec n’importe quel package disponible dans le registre npm.

Si vos modules npm ne sont pas à la dernière version, c’est le moment idéal pour les mettre à jour!

1. Recherchez les instructions require dans le code de votre Hook.
2. Supprimez les numéros de version, mais prenez-en note.
3. Ajoutez la dépendance en suivant les étapes de la section « Add a Dependency » de Write Your First Action (si la dépendance n’est pas un module de base de Node.js; si c’est un module de base de Node.js, vous n’avez pas besoin de l’inclure).
4. Déplacez les instructions require trouvées à l’extérieur de la déclaration function.

​

Convertir les secrets

Hooks et Actions gèrent les secrets de façon semblable. Dans les deux cas, les secrets sont ajoutés à chaque Hook/Action au moyen de l’interface utilisateur ou de la Management API, puis inclus dans le code.

Pour convertir des secrets de Hooks vers Actions :

1. Enregistrez les valeurs nécessaires pour l’Action sur laquelle vous travaillez.
2. Ajoutez un secret pour chaque valeur à laquelle vous devez accéder depuis l’Action. Pour savoir comment faire, consultez la section Ajouter un secret dans Write Your First Action.
3. Convertissez votre code :

Avant

async function (user, context, cb) {
    const { SECRET_NAME } = context.webtask.secrets;

    // ... code supplémentaire
}

Après

async (event, api) => {
    const { SECRET_NAME } = event.secrets;

	// ... code supplémentaire
};

Comme pour Hooks, Auth0 chiffre toutes les valeurs secrètes au repos.

​

Modifier la façon d’accéder aux données

Avec Hooks, les données sur l’utilisateur, l’application, la requête et d’autres éléments de contexte sont stockées dans plusieurs arguments transmis à la fonction Hook. Dans Actions, ces données ont été réorganisées et déplacées vers l’objet event. Bon nombre des propriétés ont été reprises telles quelles, mais certaines ont été regroupées pour plus de clarté.

Selon le type de Hook que vous convertissez, l’objet event sera différent :

• Échange d’identifiants d’application - objet d’événement d’Actions
• Après le changement de mot de passe - objet d’événement d’Actions
• Après l’inscription de l’utilisateur - objet d’événement d’Actions
• Préinscription de l’utilisateur - objet d’événement d’Actions
• Envoi d’un message téléphonique - objet d’événement d’Actions

Avant

async function (user, context, cb) {
	const clientId = context.clientID;
	const tenant = context.connection.tenant

	// ... code supplémentaire
}

Après

async (event, api) => {
	const clientId = event.client.client_id;
	const tenant = event.tenant.id;

	// ... code supplémentaire
};

Contrairement à l’objet context de Hooks, les données stockées dans les propriétés de l’objet event ou modifiées dans celles-ci ne sont pas conservées dans les Actions suivantes. Si votre Hook définit des données dans ces propriétés pour déclencher des fonctionnalités principales, vous devrez utiliser l’interface api offerte dans les flux Actions Machine to Machine et Pre User Registration afin de conserver les données d’une Action à l’autre.

​

Convertir les fonctions de rappel

Lorsqu’un Hook a terminé son traitement, il doit appeler la fonction callback() pour terminer son exécution. À l’inverse, Actions n’utilise pas de mécanisme de fonction de rappel; vous devrez donc supprimer toutes les occurrences de callback() de votre fonction Actions.

Si vous utilisiez auparavant la fonction callback() dans un Hook Échange d’identifiants d’application ou Pre User Registration pour faire échouer la requête ou mettre à jour un utilisateur, vous pourrez toujours le faire dans Actions au moyen d’une nouvelle interface api.

​

Échange d’identifiants d’application

Si vous ajoutiez des revendications supplémentaires au jeton d’accès dans un Hook d’échange d’identifiants d’application :

// Hook d'échange de justificatifs d'identité d'application
module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token.scope = scope;

  access_token['https://example.com/claim'] = 'bar';
  cb(null, access_token);
};

Vous pouvez maintenant utiliser l’objet API d’échange des identifiants d’application des Actions Client Credentials Exchange API Object :

// Action d'échange de justificatifs d'identité client
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim("https://example.com/claim", 'bar');  
};

​

Préinscription de l’utilisateur

Si vous ajoutiez des revendications supplémentaires au jeton d’accès dans un hook Pre User Registration :

// Hook de pré-inscription d'utilisateur
module.exports = function (user, context, cb) {
	if (user.app_metadata.condition === "success") {
      var response = {};
      response.user = { user_metadata: { favorite_color: "purple" } };
      // Ce Hook a réussi, passer au Hook suivant.
	  return callback(null, response);
	}

	if (user.app_metadata.condition === "failure") {
		// Ce Hook a échoué, arrêter la connexion avec une réponse d'erreur.
		return callback(new Error("Failure message"));
	}

	// ... code supplémentaire
};

Vous pouvez maintenant utiliser l’objet API « Pre User Registration » :

// Action de pré-inscription d'utilisateur
exports.onExecutePreUserRegistration = async (event, api) => {
	if (event.user.app_metadata.condition === "success") {
		// Cette Action a réussi, passer à l'Action suivante.
		api.user.setUserMetadata("favorite_color", "purple");
		return;
	}

	if (event.user.app_metadata.condition === "failure") {
		// Cette Action a échoué, arrêter l'appel avec une réponse d'erreur.
		return api.access.deny("Failure message");
	}

	// ... code supplémentaire
};

​

Terminer la migration

Une fois votre nouveau code Actions rédigé et testé, vous devez activer l’Action et désactiver le Hook. Ces deux tâches peuvent être effectuées rapidement l’une à la suite de l’autre, mais selon l’ordre, il pourrait y avoir une courte période pendant laquelle soit les deux s’exécutent, soit aucun des deux ne s’exécute. Étant donné que les Hooks actifs s’exécutent avant les Actions déployées, vous pouvez conserver une partie de la logique dans Rules pendant que vous créez et testez une autre logique dans Actions.