NPM Actions

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

Avantages

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

Assistance IDE/éditeur de code : en référençant cette bibliothèque, les IDE et les éditeurs de code peuvent assister les développeurs dans leur travail de codage grâce à des outils tels que le remplissage automatique, les définitions d’objets et de fonctionnalités, ainsi que la vérification des erreurs.
Développement TypeScript : bien que les actions soient toujours codées et fonctionnent à l’aide de Node.js CommonJS, cette bibliothèque permet le développement d’actions sur des projets externes à l’aide de TypeScript, qui peuvent ensuite être créées et déployées en tant que Common JS sur le locataire Auth0.
Améliorations des tests unitaires : en permettant le développement TypeScript sur des projets externes, cette bibliothèque permet aux développeurs de suivre les pratiques exemplaires et d’améliorer leurs tests unitaires sur la base des définitions TypeScript.
Génération d’actions par l’IA : cette bibliothèque nous rapproche de l’objectif de permettre à l’IA de générer des exemples d’actions plus pertinents.

Le fonctionnement

Installation

Veuillez utiliser l’un des gestionnaires de packages suivants pour installer le package en tant que dépendance de développement :

Le package doit être utilisé comme dépendance de développement pour enrichir 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

Importer

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’import 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 une des options suivantes pour importer les définitions TypeScript dans vos actions, en fonction de votre technologie : Utilisez cette option lorsque vous souhaitez utiliser IntelliSense sans modifier la structure de votre code JavaScript existant :

JSDoc @import
JSDoc @param
TypeScript import

Utilisez cette option lorsque vous souhaitez utiliser IntelliSense sans modifier la structure de votre code JavaScript existant :

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

/**
*Gestionnaire qui sera appelé pendant l'exécution d'un flux postconnexion.
*
*@param {Event} événement – Détails concernant 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
}

Utilisez cette option pour la sécurité des types dans les fichiers JavaScript à l’aide d’instructions d’import dans les commentaires JSDoc :

/**
*Gestionnaire qui sera appelé pendant l'exécution d'un flux postconnexion.
*
* @param {import('@auth0/actions/post-login/v3').Event} événement – Détails concernant 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
};

Utilisez cette option lorsque vous développez avec TypeScript pour une vérification complète des types et une syntaxe moderne :

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

/**
*Gestionnaire qui sera appelé pendant l'exécution d'un flux postconnexion.
*
* @param {Event} événement – Détails concernant 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
};

Si vous travaillez avec TypeScript, vous devez d’abord compiler votre code en JavaScript avant de le déployer sur Auth0. Le moteur d’exécution Auth0 Actions n’exécute que du JavaScript. Veuillez utiliser le compilateur TypeScript (tsc) pour transpiler vos fichiers .ts en fichiers .js avant de pouvoir les déployer. Il est également nécessaire d’inclure des commentaires JSDoc pour activer IntelliSense dans Auth0 Dashboard.

Exemples

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

Configuration

JavaScript
TypeScript

Dans votre package.json, définissez toutes les dépendances de développement afin d’obtenir l’aide d’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"
  }
}

Dans votre package.json, définissez toutes les dépendances de développement afin d’obtenir l’aide d’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 toutes les dépendances de développement afin d’obtenir l’aide d’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 postconnexion et demandes personnalisées de jetons d’identification

L’action de l’exemple suivant s’exécute pendant le flux postconnexion. Cette action vérifie si l’utilisateur dispose de rôles attribués et appelle api.access.deny() si aucun n’est trouvé. Si des rôles sont présents, elle procède à la définition de la demande personnalisée sur le jeton d’identification. L’instruction d’import indique que des types externes peuvent être utilisés dans votre code. Cela permet à l’éditeur de connaître la structure des objets event et api.

JavaScript
TypeScript

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

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

/**
*Gestionnaire qui sera appelé pendant l'exécution d'un flux postconnexion.
*
*@param {Event} événement – Détails concernant 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);
}

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

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

/**
*Gestionnaire qui sera appelé pendant l'exécution d'un flux postconnexion.
*
*@param {Event} événement – Détails concernant 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, rendez-vous sur : https://www.npmjs.com/package/@auth0/actions. Pour en savoir plus sur l’écriture d’actions, veuillez consulter Écrire votre première action.

Personnalisation de la marque

Personnalisation du code

Personnalisation tierce

Avantages

Le fonctionnement

Installation

Importer

Exemples

Configuration

Contrôle d’accès postconnexion et demandes personnalisées de jetons d’identification

​Avantages

​Le fonctionnement

​Installation

​Importer

​Exemples

​Configuration

​Contrôle d’accès postconnexion et demandes personnalisées de jetons d’identification

Avantages

Le fonctionnement

Installation

Importer

Exemples

Configuration

Contrôle d’accès postconnexion et demandes personnalisées de jetons d’identification