Migrer des Hooks vers les Actions

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

Lorsque vous convertissez des Hooks existants en Actions, vous devez associer la nouvelle Action au Trigger correspondant au type de Hook. Si vous suivez les étapes ci-dessous et utilisez les correspondances que nous y indiquons, le fonctionnement devrait être 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 d’un coup au moyen 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 choisi, il peut y avoir une courte période pendant laquelle les deux s’exécutent, ou pendant laquelle aucun des deux ne s’exécute.

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 passez en production un élément à 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 logiques 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’apporter les changements à un moment où l’impact et le trafic seront au plus bas.
• Envisagez d’utiliser le Auth0 Deploy CLI pour écrire des scripts, tester et mettre rapidement en œuvre la migration en une seule fois ou de façon itérative.

​

Comprendre les limites

Bien qu’Actions puisse prendre en charge la grande majorité de ce que Hooks peut faire, vous devriez connaître quelques limites avant de commencer votre migration. (Rappelez-vous : vous pouvez exécuter à la fois Hooks et Actions pendant la migration.)

• Actions ne peut pas enregistrer de données, comme des jetons d’accès ou des réponses d’API, d’une exécution à l’autre.
• Actions ne reçoit pas de jeton d’accès pour la Management API ni d’accès à l’objet global auth0, comme c’est le cas avec Hooks.

Pour obtenir la liste complète des limites, consultez Limitations d’Actions.

​

Convertir le code

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

Conseils pour convertir le code

• De façon générale, recherchez les propriétés en lecture seule des objets transmis à la fonction Hooks dans l’objet event des Actions.
• Utilisez l’Actions Code Editor dans l’Auth0 Dashboard pour écrire votre code; il vous aidera à repérer les erreurs et à obtenir 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 du Hook dans une nouvelle Action

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

1. Connectez-vous à votre tenant de production et copiez le code du Hook que vous souhaitez convertir.

2. Passez à un tenant 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 Trigger approprié**:**

     Type de Hook	Trigger 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
     Send Phone Message	Send Phone Message

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

   • Sélectionnez Create.

4. Dans le bloc de code de l’Actions Code Editor, collez le code 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 Trigger Actions; vous verrez des liens vers la documentation pertinente lorsque vous arriverez plus loin à la section Changer la façon dont les données sont accessibles dans ce guide.

​

Modifier la déclaration de la fonction

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

Type de Hook	Export nommé
Client Credentials Exchange	onExecuteCredentialsExchange
Pre-User Registration	onExecutePreUserRegistration
Post-User Registration	onExecutePostUserRegistration
Post-Change Password	onExecutePostChangePassword
Send Phone Message	onExecuteSendPhoneMessage

Avant

module.exports = async function myHooksFunction(){}

Après

// Client Credentials Exchange
exports.onExecuteCredentialsExchange = async (event, api) => {}

// Pre-User Registration
exports.onExecutePreUserRegistration = async (event, api) => {}

// Post-User Registration
exports.onExecutePostUserRegistration = async (event) => {}

// Post-Change Password
exports.onExecutePostChangePassword = async (event) => {}

// Send Phone Message
exports.onExecuteSendPhoneMessage = async (event) => {}

​

Convertir les dépendances

Hooks et Actions gèrent les dépendances de manière 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 n’importe quel package offert dans le registre npm.

Si vos modules npm ne sont pas à la version la plus récente, 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 NodeJS intégré; si la dépendance est un module NodeJS intégré, 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’UI 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 Add a Secret de 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 les Hooks, Auth0 chiffre toutes les valeurs des secrets lorsqu’elles sont stockées.

​

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

Avec Hooks, les données sur l’utilisateur, le client, la requête et d’autres données contextuelles sont stockées dans plusieurs arguments transmis à la fonction Hook. Dans Actions, ces données ont été remaniées et déplacées dans 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 :

• Client Credentials Exchange - objet d’événement Actions
• Post-Change Password - objet d’événement Actions
• Post-User Registration - objet d’événement Actions
• Pre-User Registration - objet d’événement Actions
• Send Phone Message - objet d’événement 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 des Hooks, les données stockées dans les propriétés de l’objet event ou modifiées dans celles-ci ne sont pas enregistrées dans les Actions subséquentes. Si votre Hook définit des données dans ces propriétés pour déclencher une fonctionnalité principale, vous devrez utiliser l’interface api offerte dans les Flows d’Actions Machine to Machine et Pre User Registration afin d’enregistrer les données d’une Action à l’autre.

​

Convertir les callbacks

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

Si vous utilisiez auparavant la fonction callback() dans un Hook Client Credentials Exchange 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.

​

Client Credentials Exchange

Si vous ajoutiez des claims supplémentaires au jeton d’accès dans un hook Client Credentials Exchange :

// Hook Client Credentials Exchange
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 Client Credentials Exchange d’Actions :

// Action Client Credentials Exchange
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim("https://example.com/claim", 'bar');  
};

​

Pre User Registration

Si vous ajoutiez des claims supplémentaires à l’jeton d’accès dans un Hook Pre User Registration :

// Hook Pre User Registration
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 Pré-enregistrement 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 la requête avec une réponse d'erreur.
		return api.access.deny("Failure message");
	}

	// ... code supplémentaire
};

​

Terminez la migration

Une fois votre nouveau code Actions écrit et testé, vous devez activer l’Action et désactiver le Hook. Ces deux tâches peuvent être effectuées rapidement l’une après 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. Comme les Hooks actifs s’exécutent avant les Actions déployées, vous pouvez conserver une partie de la logique dans les Rules pendant que vous créez et testez d’autres éléments de logique dans les Actions.