Actions NPM

Codez les Actions de votre projet à l’aide du package NPM @auth0/actions.

Le package NPM @auth0/actions est la bibliothèque officielle pour Actions qui prend en charge les définitions TypeScript d’Auth0 Actions. Il vous permet de coder et de tester les Actions de votre projet dans des éditeurs et des IDE externes.

Le dépôt public @auth0/actions donne accès au code source du package NPM.

​

Avantages

Cette bibliothèque prend en charge les cas d’utilisation suivants :

• Assistance dans l’IDE ou l’éditeur de code : En s’appuyant sur cette bibliothèque, les IDE et les éditeurs de code peuvent aider les développeurs grâce à l’autocomplétion, aux définitions d’objets et de fonctions et à la vérification des erreurs.
• Développement en TypeScript : Bien que les Actions soient encore codées et exécutées avec Node.js CommonJS, cette bibliothèque permet de développer des Actions dans des projets externes en TypeScript, puis de les compiler et de les déployer en CommonJS dans le locataire Auth0.
• Amélioration des tests unitaires : En permettant le développement en TypeScript dans des projets externes, cette bibliothèque aide les développeurs à suivre les pratiques exemplaires et à améliorer leurs tests unitaires à partir des définitions TypeScript.
• Génération d’Actions par l’IA : Cette bibliothèque nous rapproche d’une IA capable de générer des exemples d’Action plus précis.

---

​

Fonctionnement

​

Installation

Utilisez l’un des gestionnaires de paquets suivants pour installer le paquet en tant que dépendance de développement :

Le paquet doit être utilisé en tant que dépendance de développement pour compléter vos outils de développement.

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

---

​

Import

La bibliothèque présente la structure suivante :

@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

L’instruction d’importation doit être basée sur chaque nom de déclencheur et numéro de version, en tenant compte de la structure précédente de la bibliothèque.

Suivez le modèle : @auth0/actions/[trigger_name]/[trigger_version]

Par exemple : @auth0/actions/post-login/v3

Utilisez l’une des options suivantes pour importer les définitions TypeScript dans vos Actions, selon la technologie utilisée :

Utilisez cette option si vous souhaitez bénéficier d’IntelliSense sans modifier la structure existante de votre code JavaScript :

JSDoc @import

Utilisez cette option si vous souhaitez bénéficier d’IntelliSense sans modifier la structure existante de votre code JavaScript :

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

/**
* Gestionnaire appelé pendant l’exécution d’un flux PostLogin.
*
* @param {Event} event - Détails sur l’utilisateur et le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes peuvent être utilisées pour modifier le comportement de la connexion.
*/
exports.onExecutePostLogin = async (event, api) => {
  // Votre code
}

JSDoc @param

Utilisez cette option pour assurer la sécurité des types dans les fichiers JavaScript qui utilisent des instructions d’importation dans les commentaires JSDoc :

/**
* Gestionnaire appelé pendant l’exécution d’un flux PostLogin.
*
* @param {import('@auth0/actions/post-login/v3').Event} event - Détails sur l’utilisateur et le contexte dans lequel il se connecte.
* @param {import('@auth0/actions/post-login/v3').PostLoginAPI} api - Interface dont les méthodes peuvent être utilisées pour modifier le comportement de la connexion.
*/
exports.onExecutePostLogin = async (event, api) => {
  // Votre code
};

Importation TypeScript

Utilisez cette option si vous développez avec TypeScript afin de bénéficier d’une vérification complète des types et d’une syntaxe moderne :

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

/**
* Gestionnaire appelé pendant l’exécution d’un flux PostLogin.
*
* @param {Event} event - Détails sur l’utilisateur et le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes peuvent être utilisées pour modifier le comportement de la connexion.
*/
exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
  // Votre code
};

Lorsque vous utilisez TypeScript, vous devez compiler votre code en JavaScript avant de le déployer dans Auth0. L’environnement d’exécution des Actions d’Auth0 n’exécute que du JavaScript. Utilisez le compilateur TypeScript (tsc) pour transpiler vos fichiers .ts en fichiers .js avant le déploiement. Vous devez aussi inclure des commentaires JSDoc pour activer IntelliSense dans le Dashboard.

​

Exemples

Les exemples d’Actions suivants sont présentés délibérément en JavaScript et en TypeScript afin d’offrir une comparaison directe côte à côte.

​

Configuration

JavaScript

Dans votre package.json, définissez les dépendances de développement requises afin de bénéficier de l’aide IntelliSense lors de la rédaction de votre 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

Dans votre package.json, définissez les dépendances de développement requises afin de bénéficier de l’aide IntelliSense lors de la rédaction de votre 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"
  }
}

Dans votre tsconfig.json, définissez les dépendances de développement requises afin de bénéficier de l’aide IntelliSense lors de la rédaction de votre 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"
  ]
}

​

Contrôle d’accès post-connexion et revendications personnalisées du jeton d’identité

L’exemple d’Action suivant s’exécute pendant le flux Post-Login. Il vérifie si des rôles sont attribués à l’utilisateur et appelle api.access.deny() si aucun rôle n’est trouvé. Si des rôles sont présents, il définit ensuite la revendication personnalisée dans le jeton d’identité.

L’instruction d’importation déclare la disponibilité de types externes pour votre code. Cela permet à l’éditeur de connaître la structure des objets event et api.

JavaScript

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

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

/**
* Gestionnaire appelé lors de l’exécution d’un flux PostLogin.
*
* @param {Event} event - Détails sur l’utilisateur et le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes peuvent être utilisées pour modifier le comportement de la connexion.
*/
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';

/**
* Gestionnaire appelé lors de l’exécution d’un flux PostLogin.
*
* @param {Event} event - Détails sur l’utilisateur et le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes peuvent être utilisées pour modifier le comportement de la connexion.
*/
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);
};

Pour en savoir plus sur @auth0/actions, consultez : https://www.npmjs.com/package/@auth0/actions.

Pour en savoir plus sur le code source de @auth0/actions, consultez le dépôt Auth0 Actions.

Pour en savoir plus sur la création d’Actions, consultez Créer votre première Action.