Migrer des Hooks vers les 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.

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.

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.

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.

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.

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 :

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) => {}

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.

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.

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.

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
};

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.

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');  
};

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
};

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.