Migrer des Hooks vers les Actions

Apprenez à migrer votre code Hooks Auth0 existant vers le code Auth0 Actions.

Lorsque vous convertissez des Hooks existants en Actions, vous devez associer la nouvelle Action au Déclencheur correspondant au type du hook. Si vous suivez les étapes ci-dessous et que vous utilisez les mappages que nous avons identifiés, la fonctionnalité devrait être identique.

​

Planifier votre migration

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

Vous devrez convertir le code, puis activer l’action et désactiver le hook. Il est possible d’activer l’action et de désactiver le hook rapidement l’une après l’autre, mais en fonction de l’ordre, un court laps de temps peut s’écouler pendant lequel l’une ou l’autre des actions ou aucune d’entre elles n’est en cours d’exécution.

Pour cette raison, nous vous recommandons de migrer votre pipeline étape par étape : convertissez des éléments de votre code Hooks en code Action, testez dans un environnement de préproduction, puis passez à la production avec un élément à la fois. Comme les Hooks actifs s’exécutent préalablement aux Actions déployées, vous pouvez conserver une partie de la logique dans les Hooks pendant que vous élaborez et testez d’autres logiques dans les Actions.

Conseils pour la planification de la migration

• Utilisez des indicateurs pour éviter de dupliquer des opérations coûteuses ou ponctuelles.
• Veillez à effectuer les changements à un moment où l’impact et le traffic seront les plus faibles.
• Envisagez d’utiliser l’outil Auth0 Deploy CLI afin de rédiger des scripts, de tester et de mettre en œuvre rapidement la migration en une seule fois ou de manière itérative.

​

Comprendre les limites

Bien que les Actions puissent gérer la grande majorité des tâches effectuées par les Hooks, vous devez être conscient de certaines limites avant de commencer votre migration. (Rappelez-vous : les Hooks et les Actions peuvent être en cours d’exécution pendant la migration).

• Les Actions ne peuvent pas conserver les données, comme les jetons d’accès ou les réponses d’API, entre les exécutions.
• Les actions ne sont pas fournies avec un jeton d’accès à Management API ou d’accès à l’objet auth0 global comme pour les Hooks.

Pour obtenir la liste complète des limitations, veuillez consulter la section Limitations des actions.

​

Conversion du code

Pour convertir un Hook en Action, vous devez remplacer le code spécifique à le Hook par le code de l’Action. Cette section couvre les tâches que vous devrez effectuer pour transformer un Hook fonctionnel en Action équivalente.

Conseils pour la conversion du code

• En général, il faut rechercher les propriétés en lecture seule des objets passés dans la fonction Hooks sur l’objet d’Actions event (évèvement).
• Utilisez l’Éditeur de code d’actions dans le Auth0 Dashboard pour écrire votre code; il vous aidera en mettant en évidence les erreurs et en fournissant des suggestions d’auto-remplissage.
• Avant de mettre en ligne, vous devez soigneusement tester vos nouvelles Actions dans un environnement d’essai ou de test.

​

Copier le code du 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 le Auth0 Dashboard; cela vous aidera à identifier les problèmes en suspens dans votre code.

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

2. Passez à un locataire hors production et accédez à Auth0 Dashboard > Actions > Bibliothèque.

3. Sélectionner Construire une action personnalisée, puis :

   • Saisissez un Nom pour votre action qui correspond au nom du Hook que vous convertissez.

   • Accédez à Déclencheur et sélectionnez le déclencheur approprié :

     Type du hook	Déclencheur d’actions
     Échange identifiants client	Identifiants M2M/Client
     Enregistrement pré-utilisateur	Enregistrement pré-utilisateur
     Enregistrement post-utilisateur	Enregistrement post-utilisateur
     Mot de passe post-changement	Mot de passe post-changement
     Envoyer message téléphonique	Envoyer message téléphonique

   • Accédez à Durée d’exécution, et sélectionnez Node 18.

   • Sélectionnez Créer.

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étaillées dans la suite de cet article à mesure que vous déplacez le code dans la fonction. Il est également recommandé de consulter l’objet event associé au nouveau déclencheur d’actions. Vous trouverez des liens vers la documentation correspondante lorsque vous atteindrez la section Modifier l’accès aux données, plus loin dans ce guide.

​

Modifier la déclaration de fonction

Les fonctions du hook sont exportées à l’aide de l’export par défaut, tandis que les fonctions d’action utilisent des exports nommés. L’export nommé change en fonction du type de hook que vous convertissez. Le mappage est le suivant :

Type de hooks	Exportation nommée
Échange d’identifiant du client	onExecuteCredentialsExchange
Enregistrement pré-utilisateur	onExecutePreUserRegistration
Enregistrement post-utilisateur	onExecutePostUserRegistration
Mot de passe après changement	onExecutePostChangePassword
Envoyer un message par téléphonee	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

Les Hooks et les Actions gèrent les dépendances de la même manière. Dans les deux cas, les dépendances sont ajoutées séparément via l’interface utilisateur ou Management API et incluses dans le code. Avec les deux, vous pouvez également demander n’importe quel package disponible dans le registre npm.

Si la version de vos modules npm n’est pas la plus récente, c’est le bon moment pour une mise à jour!

1. Rechercher les déclarations require à l’intérieur de votre code du Hook.
2. Supprimez les numéros de version, après les avoir notés.
3. Ajoutez la dépendance en suivant les étapes de la section « Ajouter une dépendance » de Programmer votre première Action (si la dépendance n’est pas une module de base NodeJS; si la dépendance est un module NodeJS de base, vous n’avez pas besoin de l’inclure).
4. Déplacez les déclarations require que vous avez trouvées en dehors de la déclaration function.

​

Convertir les secrets

Les Hooks et les Actions traitent les secrets de la même manière. Dans les deux cas, les secrets sont ajoutés par Hook/Action via l’interface utilisateur ou Management API et inclus dans le code.

Pour convertir les secrets des Hooks en Actions :

1. Enregistrez les valeurs nécessaires à l’action spécifique sur laquelle vous travaillez.
2. Ajoutez un secret pour chaque valeur à laquelle vous devez accéder à l’intérieur de l’action. Pour en savoir plus, consultez la section Ajouter un secret dans Programmer votre première Action.
3. Convertir votre code :

Avant

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

    // ... additional code
}

Après

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

	// ... additional code
};

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

​

Modifier l’accès aux données

Avec les Hooks, les données concernant l’utilisateur, le client, la requête et d’autres données contextuelles sont stockées dans plusieurs arguments transmis à la fonction hook. Dans les actions, ces données ont été remodelées et déplacées vers l’objet event. De nombreuses propriétés ont été transférées telles quelles, tandis que d’autres ont été combinées pour plus de clarté.

Selon le type du Hook que vous convertissez, l’objet event changera :

• Échange d’identifiants clients - Objet d’événement d’action
• Objet d’événement d’actions post-modification du mot de passe
• Objet d’événement d’actions post-inscription de l’utilisateur
• Objet d’événement d’actions pré-inscription
• Envoi de message téléphonique - Objet d’événement d’action

Avant

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

	// ... additional code
}

Après

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

	// ... additional code
};

Contrairement à l’objet context lié aux hooks, les données stockées ou modifiées dans les propriétés de l’objet event ne persistent pas dans les Actions suivantes. Si votre Hook définit des données sur ces propriétés pour déclencher des fonctionnalités de base, vous devrez utiliser l’interface api disponible dans les flux d’action machine-machine et Enregistrement pré-utilisateur pour que les données persistent sur les Actions.

​

Convertir les rappels

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

Si vous utilisiez auparavant la fonction Callback() dans un échange d’informations d’identification client ou un Hook de pré-enregistrement d’utilisateur pour faire échouer la demande ou mettre à jour un utilisateur, vous pourrez toujours le faire dans Actions via une nouvelle interface api.

​

Échange d’identifiants clients

Si vous avez ajouté des demandes supplémentaires au jeton d’accès lors d’un hook d’échange d’identifiants clients :

// Client Credentials Exchange Hook
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 désormais utiliser les actions Objet API Échange d’identifiants clients :

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

​

Pré-enregistrement de l’utilisateur

Si vous avez ajouté des revendications supplémentaires au jeton d’accès lors d’un Hook de pré-enregistrement d’utilisateur :

// Pre User Registration Hook
module.exports = function (user, context, cb) {
	if (user.app_metadata.condition === "success") {
      var response = {};
      response.user = { user_metadata: { favorite_color: "purple" } };
      // This Hook succeeded, proceed with the next Hook.
	  return callback(null, response);
	}

	if (user.app_metadata.condition === "failure") {
		// This Hook failed, stop the login with an error response.
		return callback(new Error("Failure message"));
	}

	// ... additional code
};

Vous pouvez désormais utiliser le Objet API Pré-enregistrement de l’utilisateur :

// Pre User Registration Action
exports.onExecutePreUserRegistration = async (event, api) => {
	if (event.user.app_metadata.condition === "success") {
		// This Action succeeded, proceed with next Action.
		api.user.setUserMetadata("favorite_color", "purple");
		return;
	}

	if (event.user.app_metadata.condition === "failure") {
		// This Action failed, stop the call with an error response.
		return api.access.deny("Failure message");
	}

	// ... additional code
};

​

Achever la migration

Une fois que votre nouveau code d’action a été écrit et testé, vous devez activer l’action et désactiver le Hook. Vous pouvez effectuer ces deux tâches rapidement l’une après l’autre, mais en fonction de l’ordre, il se peut qu’il y ait un court laps de temps pendant lequel l’une ou l’autre ou aucune des deux actions n’est en cours d’exécution. Comme les Hooks actifs s’exécutent préalablement aux Actions déployées, vous pouvez conserver une partie de la logique dans les Règles pendant que vous élaborez et testez d’autres logiques dans les Actions.