Actions NPM

Programa las Actions de tu proyecto con el paquete NPM @auth0/actions.

El paquete NPM @auth0/actions es la biblioteca oficial de Actions e incluye las definiciones de TypeScript para Auth0 Actions. Esto te permite programar y probar las Actions de tu proyecto en editores externos e IDE.

El repositorio público @auth0/actions proporciona acceso al código en el que se basa el paquete NPM.

​

Beneficios

Esta biblioteca ayuda con los siguientes casos de uso:

• Asistencia del IDE / editor de código: Al usar esta biblioteca como referencia, los IDE y los editores de código pueden ayudar a los desarrolladores a escribir código con autocompletado, definiciones de objetos y funciones y comprobación de errores.
• Desarrollo con TypeScript: Aunque las Actions todavía se desarrollan y funcionan con Node.js CommonJS, esta biblioteca permite desarrollar Actions en proyectos externos con TypeScript, que luego pueden compilarse e implementarse como Common JS en el Tenant de Auth0.
• Mejoras en las pruebas unitarias: Al habilitar el desarrollo con TypeScript en proyectos externos, esta biblioteca permite a los desarrolladores seguir las prácticas recomendadas y mejorar sus pruebas unitarias basándose en las definiciones de TypeScript.
• Generación de Actions con IA: Esta biblioteca nos acerca un paso más a que la IA pueda generar ejemplos de Actions más precisos.

---

​

Cómo funciona

​

Instalación

Usa uno de los siguientes administradores de paquetes para instalar el paquete como una dependencia de desarrollo:

El paquete debe usarse como dependencia de desarrollo para complementar tus herramientas de desarrollo.

• NPM: npm install @auth0/actions --save-dev
• Yarn: yarn add @auth0/actions --dev
• Pnpm: pnpm add @auth0/actions --save-dev

---

​

Importación

La biblioteca tiene la siguiente estructura:

@auth0/actions
│
└───credentials-exchange
│   └───v1
│   └───v2
└───custom-email-provider
│   └───v1
└───custom-phone-provider
│   └───v1
└───custom-token-exchange
│   └───v1
└───event-stream
│   └───v1
└───password-reset-post-challenge
│   └───v1
└───post-change-password
│   └───v1
│   └───v2
└───post-login
│   └───v1
│   └───v2
│   └───v3
└───post-user-registration
│   └───v1
│   └───v2
└───pre-user-registration
│   └───v1
│   └───v2
└───send-phone-message
    └───v2

La instrucción de importación debe basarse en cada nombre del trigger y número de versión, teniendo en cuenta la estructura anterior de la biblioteca.

Siga este patrón: @auth0/actions/[trigger_name]/[trigger_version]

Por ejemplo: @auth0/actions/post-login/v3

Use una de las siguientes alternativas para importar las definiciones de TypeScript en sus Actions, según la tecnología que utilice:

Use esta alternativa cuando quiera IntelliSense sin cambiar la estructura actual de su código JavaScript:

JSDoc @import

Use esta alternativa cuando quiera IntelliSense sin cambiar la estructura actual de su código JavaScript:

/** @import {Event, PostLoginAPI} from "@auth0/actions/post-login/v3" */

/**
* Controlador que se llamará durante la ejecución de un flujo PostLogin.
*
* @param {Event} event - Detalles sobre el usuario y el contexto en el que está iniciando sesión.
* @param {PostLoginAPI} api - Interfaz cuyos métodos pueden usarse para cambiar el comportamiento del inicio de sesión.
*/
exports.onExecutePostLogin = async (event, api) => {
  // Su código
}

JSDoc @param

Use esta alternativa para obtener seguridad de tipos en archivos JavaScript que usan instrucciones de importación en comentarios JSDoc:

/**
* Controlador que se llamará durante la ejecución de un flujo PostLogin.
*
* @param {import('@auth0/actions/post-login/v3').Event} event - Detalles sobre el usuario y el contexto en el que está iniciando sesión.
* @param {import('@auth0/actions/post-login/v3').PostLoginAPI} api - Interfaz cuyos métodos pueden usarse para cambiar el comportamiento del inicio de sesión.
*/
exports.onExecutePostLogin = async (event, api) => {
  // Su código
};

TypeScript import

Use esta alternativa si desarrolla con TypeScript para obtener una comprobación de tipos completa y una sintaxis moderna:

import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

/**
* Controlador que se llamará durante la ejecución de un flujo PostLogin.
*
* @param {Event} event - Detalles sobre el usuario y el contexto en el que está iniciando sesión.
* @param {PostLoginAPI} api - Interfaz cuyos métodos pueden usarse para cambiar el comportamiento del inicio de sesión.
*/
exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
  // Su código
};

Al usar TypeScript, debe compilar su código a JavaScript antes de implementarlo en Auth0. El entorno de ejecución de Auth0 Actions solo ejecuta JavaScript. Use el compilador de TypeScript (tsc) para transpilar sus archivos .ts a archivos .js antes de implementarlos. También debe incluir comentarios JSDoc para habilitar IntelliSense en el Dashboard.

​

Ejemplos

Los siguientes ejemplos de Actions se presentan intencionalmente tanto en JavaScript como en TypeScript para ofrecer una comparación directa en paralelo.

​

Configuración

JavaScript

En tu package.json, define las dependencias de desarrollo necesarias para contar con ayuda de IntelliSense al escribir tu Action:

{
  "name": "actions-js",
  "version": "1.0.0",
  "description": "Actions JS",
  "main": "example.js",
  "author": "John Doe",
  "license": "ISC",
  "devDependencies": {
    "@auth0/actions": "^0.7.1"
  }
}

TypeScript

En tu package.json, define las dependencias de desarrollo necesarias para contar con ayuda de IntelliSense al escribir tu Action.

{
  "name": "actions-ts",
  "version": "1.0.0",
  "description": "Actions TS",
  "main": "example.ts",
  "author": "John Doe",
  "license": "ISC",
  "devDependencies": {
    "@auth0/actions": "^0.7.1",
    "@types/node": "22.14.0",
    "typescript": "^5.9.2"
  }
}

En tu tsconfig.json, configura las opciones necesarias para contar con ayuda de IntelliSense al escribir tu Action.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "nodenext",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "outDir": "dist",
    "declaration": true,
    "sourceMap": true,
    "allowJs": true,
    "checkJs": false,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true
  },
  "include": [
    "**/*.ts"
  ],
  "exclude": [
    "node_modules",
    "dist"
  ]
}

​

Control de acceso posterior al inicio de sesión y reclamaciones personalizadas del ID Token

El siguiente ejemplo de Action se ejecuta durante el flujo Post-Login. Comprueba si el usuario tiene roles asignados y llama a api.access.deny() si no encuentra ninguno. Si hay roles, establece la reclamación personalizada en el ID Token.

La instrucción de importación declara la disponibilidad de tipos externos para tu código. Esto permite que el editor conozca la estructura de los objetos event y api.

JavaScript

/** @import {Event, PostLoginAPI} from "@auth0/actions/post-login/v3" */

const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

/**
* Controlador que se llamará durante la ejecución de un flujo PostLogin.
*
* @param {Event} event - Detalles sobre el usuario y el contexto en el que inicia sesión.
* @param {PostLoginAPI} api - Interfaz cuyos métodos pueden usarse para cambiar el comportamiento del inicio de sesión.
*/
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles;

  if (roles === undefined || roles.length === 0) {
    api.access.deny('Restricted');
    return;
  }

  api.idToken.setCustomClaim(`${CUSTOM_CLAIM_NAMESPACE}/roles`, roles);
}

TypeScript

import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

/**
* Controlador que se llamará durante la ejecución de un flujo PostLogin.
*
* @param {Event} event - Detalles sobre el usuario y el contexto en el que inicia sesión.
* @param {PostLoginAPI} api - Interfaz cuyos métodos pueden usarse para cambiar el comportamiento del inicio de sesión.
*/
exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
  const roles = event.authorization?.roles;

  if (roles === undefined || roles.length === 0) {
    api.access.deny('Restricted');
    return;
  }

  api.idToken.setCustomClaim(`${CUSTOM_CLAIM_NAMESPACE}/roles`, roles);
};

Para obtener más información sobre @auth0/actions, visita: https://www.npmjs.com/package/@auth0/actions.

Para obtener más información sobre el código de @auth0/actions, visita el repositorio de Auth0 Actions.

Para obtener más información sobre cómo escribir Actions, consulta Write Your First Action.