Actions NPM

Installez le package npm officiel @auth0/actions comme dépendance de développement afin d’ajouter des définitions de types TypeScript, IntelliSense et la vérification des erreurs lors de l’écriture et des tests unitaires d’Auth0 Actions par déclencheur et version dans des éditeurs externes.

Le @auth0/actions package npm est la bibliothèque officielle pour Actions qui comprend les définitions TypeScript d’Auth0 Actions. Vous pouvez ainsi coder et tester les Actions de votre projet dans des éditeurs externes et des EDI.

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

​

Avantages

Cette bibliothèque vous aide dans les cas d’usage suivants :

• Assistance IDE / éditeur de code : En utilisant 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 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 à l’aide de TypeScript, puis de les compiler et de les déployer en Common JS vers le tenant Auth0.
• Amélioration des tests unitaires : En permettant le développement TypeScript dans des projets externes, cette bibliothèque permet aux développeurs de suivre les meilleures pratiques et d’améliorer leurs tests unitaires à partir des définitions TypeScript.
• Génération d’Actions par l’IA : Cette bibliothèque nous rapproche un peu plus d’une IA capable de générer des exemples d’Action plus précis.

---

​

Comment ça fonctionne

​

Installation

Utilisez l’un des gestionnaires de paquets suivants pour installer le package comme dépendance de développement :

Le package doit être utilisé comme 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

---

​

Importation

La bibliothèque a 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 votre technologie :

Utilisez cette option si vous voulez IntelliSense sans modifier la structure actuelle de votre code JavaScript :

JSDoc @import

Utilisez cette option si vous voulez IntelliSense sans modifier la structure actuelle 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ûreté du typage dans des fichiers JavaScript au moyen d’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
};

TypeScript import

Utilisez cette option si vous développez avec TypeScript afin d’obtenir une vérification complète des types et 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 sur Auth0. L’environnement d’exécution d’Auth0 Actions exécute uniquement du JavaScript. Utilisez le compilateur TypeScript (tsc) pour transpiler vos fichiers .ts en fichiers .js avant le déploiement. Vous devez également inclure des commentaires JSDoc pour activer IntelliSense dans le Dashboard.

​

Exemples

Les exemples d’Actions suivants sont présentés intentionnellement en JavaScript et en TypeScript afin de permettre une comparaison directe, côte à côte.

​

Configuration

JavaScript

Dans votre fichier package.json, indiquez les dépendances de développement nécessaires pour bénéficier de l’aide IntelliSense lorsque vous rédigez 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 fichier package.json, indiquez les dépendances de développement nécessaires pour bénéficier de l’aide IntelliSense lorsque vous rédigez 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 fichier tsconfig.json, indiquez les dépendances de développement nécessaires pour bénéficier de l’aide IntelliSense lorsque vous rédigez 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-Login et claims personnalisés du jeton ID

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

L’instruction d’importation déclare la disponibilité de types externes dans 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é 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) => {
  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é 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) => {
  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.