Migrar de Hooks a Actions

Aprenda a migrar su código actual de Hooks de Auth0 a código de Actions de Auth0.

Al convertir Hooks existentes en Actions, debe asociar la nueva Action con el Trigger correspondiente al tipo de Hook. Si sigue los pasos a continuación y usa las correspondencias que identificamos en ellos, la funcionalidad debería ser idéntica.

​

Planifica tu migración

Las Actions desplegadas se ejecutan después de los Hooks activos, por lo que puedes convertir los Hooks uno a uno en el Dashboard o todos de una vez mediante la Management API.

Tendrás que convertir el código y, después, activar la Action y desactivar el Hook. Activar la Action y desactivar el Hook puede hacerse rápidamente en sucesión, pero, según el orden, podría haber un breve período de tiempo en el que se ejecuten ambos o ninguno.

Por eso, te recomendamos migrar tu pipeline paso a paso: convierte partes del código de tus Hooks en código de Action, pruébalas en un entorno de ensayo y luego pásalas a producción una a una. Como los Hooks activos se ejecutan antes que las Actions desplegadas, puedes mantener parte de la lógica en Hooks mientras desarrollas y pruebas otra lógica en Actions.

Consejos para planificar tu migración

• Usa indicadores para evitar duplicar operaciones costosas o que solo deben ejecutarse una vez.
• Asegúrate de aplicar los cambios en un momento en que el impacto y el tráfico sean mínimos.
• Considera usar Auth0 Deploy CLI para crear scripts, probar e implementar rápidamente la migración de una sola vez o de forma iterativa.

​

Comprenda las limitaciones

Aunque Actions puede gestionar la gran mayoría de las tareas que Hooks puede realizar, debe tener en cuenta algunas limitaciones antes de iniciar la migración. (Recuerde: puede tener tanto Hooks como Actions en ejecución mientras migra).

• Actions no puede conservar datos, como tokens de acceso o respuestas de API, entre ejecuciones.
• Actions no dispone de un token de acceso para la Management API ni de acceso al objeto global auth0, como sí ocurre en Hooks.

Para ver la lista completa de limitaciones, consulte Limitaciones de Actions.

​

Convertir código

Para convertir un Hook en una Action, debes sustituir el código específico de Hooks por código de Actions. En esta sección se describen las tareas que deberás realizar para convertir un Hook funcional en su Action equivalente.

Consejos para convertir código

• En general, busca en el objeto event de Actions las propiedades de solo lectura de los objetos que se pasan a la función de Hooks.
• Usa el editor de código de Actions en el Auth0 Dashboard para escribir tu código; te ayudará resaltando errores y ofreciendo sugerencias de autocompletado.
• Antes de pasar a producción, prueba exhaustivamente tus nuevas Actions en un entorno de preproducción o de prueba.

​

Copie el código del Hook en una nueva Action

Le recomendamos copiar el código de su Hook en una nueva Action y usar el editor de código de Actions en Auth0 Dashboard; esto le ayudará a identificar los problemas pendientes en su código.

1. Inicie sesión en su inquilino de producción y copie el código del Hook que desea convertir.

2. Cambie a un inquilino que no sea de producción y vaya a Auth0 Dashboard > Actions > Library.

3. Seleccione Build Custom y, a continuación:

   • Introduzca un nombre para su Action que coincida con el nombre del Hook que está convirtiendo.

   • Busque Trigger y seleccione el trigger adecuado**:**

     Tipo de Hook	Trigger de 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

   • Busque Runtime y seleccione Node 18.

   • Seleccione Create.

4. En el bloque de código del editor de código de Actions, pegue el código del Hook que desea convertir debajo de la función exportada.

5. Realice los cambios detallados en el resto de este artículo a medida que mueve el código a la función. También debería leer sobre el objeto event asociado al nuevo trigger de Actions; verá enlaces a la documentación pertinente cuando llegue más adelante, en esta guía, a la sección Cambiar cómo se accede a los datos.

​

Cambie la declaración de la función

Las funciones de Hooks se exportan mediante una exportación por defecto, mientras que las funciones de Actions usan exportaciones con nombre. Según el tipo de Hook que vaya a convertir, la exportación con nombre será diferente. Las correspondencias son:

Tipo de Hook	Exportación con nombre
Client Credentials Exchange	onExecuteCredentialsExchange
Pre-registro de usuario	onExecutePreUserRegistration
Posregistro de usuario	onExecutePostUserRegistration
Post-Change Password	onExecutePostChangePassword
Send Phone Message	onExecuteSendPhoneMessage

Antes

module.exports = async function myHooksFunction(){}

Después

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

// Registro previo de usuario
exports.onExecutePreUserRegistration = async (event, api) => {}

// Registro posterior de usuario
exports.onExecutePostUserRegistration = async (event) => {}

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

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

​

Convertir dependencias

Hooks y Actions gestionan las dependencias de forma similar. En ambos casos, las dependencias se agregan por separado mediante la UI o la Management API y se incluyen en el código. Además, en ambos casos, puede usar cualquier paquete disponible en el registro de npm.

Si sus módulos de npm no están en la versión más reciente, ¡este es un buen momento para actualizarlos!

1. Busque sentencias require en el código de su Hook.
2. Elimine los números de versión, pero anótelos.
3. Agregue la dependencia siguiendo los pasos de la sección “Add a Dependency” de Write Your First Action (si la dependencia no es un módulo principal de NodeJS; si la dependencia es un módulo principal de NodeJS, no necesita incluirla).
4. Mueva las sentencias require encontradas fuera de la declaración function.

​

Convertir secretos

Hooks y Actions manejan los secretos de forma similar. En ambos casos, los secretos se agregan para cada Hook/Action mediante la interfaz de usuario o la Management API y se incluyen en el código.

Para convertir secretos de Hooks a Actions:

1. Guarda los valores necesarios para la Action específica en la que estás trabajando.
2. Agrega un secreto para cada valor al que necesites acceder desde la Action. Para saber cómo hacerlo, consulta la sección Add a Secret en Write Your First Action.
3. Convierte tu código:

Antes

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

    // ... código adicional
}

Después

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

	// ... código adicional
};

Al igual que con Hooks, Auth0 cifra en reposo todos los valores secretos.

​

Cambiar cómo se accede a los datos

Con Hooks, los datos sobre el usuario, el cliente, la solicitud y otros datos contextuales se almacenan en varios argumentos que se pasan a la función Hook. En Actions, estos datos se han reorganizado y movido al objeto event. Muchas de las propiedades se trasladaron sin cambios, pero algunas se han combinado para mayor claridad.

Según el tipo de Hook que esté convirtiendo, el objeto event variará:

• Intercambio de credenciales de cliente: objeto de evento de Actions
• Post-Change Password: objeto de evento de Actions
• Después del registro de usuario: objeto de evento de Actions
• Antes del registro de usuario: objeto de evento de Actions
• Send Phone Message: objeto de evento de Actions

Antes

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

	// ... código adicional
}

Después

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

	// ... código adicional
};

A diferencia del objeto context de Hooks, los datos almacenados o modificados en las propiedades del objeto event no se conservan en las Actions posteriores. Si tu Hook establece datos en estas propiedades para activar funcionalidades principales, tendrás que usar la interfaz api disponible en los flujos de Actions Machine to Machine y Pre User Registration para conservar los datos entre Actions.

​

Convertir las callbacks

Cuando un Hook termina de procesarse, debe llamar a la función callback() para completar su ejecución. En cambio, Actions no usa un mecanismo de callback; por lo tanto, deberá eliminar todas las instancias de callback() de su función de Actions.

Si antes usaba la función callback() en un Hook de Client Credentials Exchange o Pre User Registration para hacer que falle la solicitud o actualizar un usuario, podrá seguir haciéndolo en Actions mediante una nueva interfaz api.

​

Client Credentials Exchange

Si agregabas claims adicionales al token de acceso en un Hook de Client Credentials Exchange:

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

Ahora puede usar el objeto de la API de Client Credentials Exchange de Actions:

// Action de intercambio de credenciales de cliente
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim("https://example.com/claim", 'bar');  
};

​

Pre User Registration

Si estaba agregando claims adicionales al token de acceso en un Hook de Pre User Registration:

// Hook de Pre User Registration
module.exports = function (user, context, cb) {
	if (user.app_metadata.condition === "success") {
      var response = {};
      response.user = { user_metadata: { favorite_color: "purple" } };
      // Este Hook se ejecutó correctamente; continuar con el siguiente Hook.
	  return callback(null, response);
	}

	if (user.app_metadata.condition === "failure") {
		// Este Hook falló; detener el inicio de sesión con una respuesta de error.
		return callback(new Error("Failure message"));
	}

	// ... código adicional
};

Ahora puede usar el objeto de la API Pre User Registration:

// Action de Pre User Registration
exports.onExecutePreUserRegistration = async (event, api) => {
	if (event.user.app_metadata.condition === "success") {
		// Esta Action se ejecutó correctamente; continúa con la siguiente Action.
		api.user.setUserMetadata("favorite_color", "purple");
		return;
	}

	if (event.user.app_metadata.condition === "failure") {
		// Esta Action falló; detén la llamada con una respuesta de error.
		return api.access.deny("Failure message");
	}

	// ... código adicional
};

​

Completa la migración

Una vez que hayas escrito y probado el nuevo código de Actions, debes activar la Action y desactivar el Hook. Estas dos tareas pueden realizarse rápidamente una tras otra, pero, según el orden, podría haber un breve período en el que se ejecuten ambas o ninguna. Como los Hooks activos se ejecutan antes que las Actions implementadas, puedes mantener parte de la lógica en Rules mientras desarrollas y pruebas otra lógica en Actions.