Actions NPM

@auth0/actions NPM パッケージを使用して、プロジェクトの Actions を実装します。

@auth0/actions NPM パッケージ は、Auth0 Actions の TypeScript 定義を利用するための公式 Actions ライブラリです。これにより、外部エディターや IDE でプロジェクトの Actions を実装してテストできます。

@auth0/actions 公開リポジトリ では、この NPM パッケージの基盤となるコードを確認できます。

​

利点

このライブラリは、次のユースケースに対応します。

• IDE / コードエディターの支援: このライブラリを参照すると、IDE やコードエディターで 自動補完、オブジェクトや関数の定義表示、エラーチェックが利用でき、開発時の支援が向上します。
• TypeScript 開発: Actions は引き続き Node.js CommonJS で記述・実行されますが、このライブラリを使用すると、外部プロジェクトで TypeScript を使って Actions を開発し、その後 CommonJS としてビルドして Auth0 テナントにデプロイできます。
• ユニットテストの改善: 外部プロジェクトで TypeScript 開発を行えるようになることで、このライブラリを使えば、開発者はベストプラクティスに従い、TypeScript の定義に基づいてユニットテストを改善できます。
• AI による Actions 生成: このライブラリによって、AI がより正確な Action の例を生成できるようになることに一歩近づきます。

---

​

動作の仕組み

​

インストール

以下のいずれかのパッケージマネージャーを使用して、このパッケージを開発依存関係としてインストールします。

このパッケージは、開発ツールを補完するため、開発依存関係として使用する必要があります。

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

---

​

インポート

このライブラリの構造は次のとおりです。

@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

The import statement should be based on each trigger name and version number considering the previous library structure.

Follow the pattern: @auth0/actions/[trigger_name]/[trigger_version]

For example: @auth0/actions/post-login/v3

Use one of the following alternatives to import the TypeScript definitions into your Actions depending on your technology:

Use this alternative when you want IntelliSense without changing your existing JavaScript code structure:

JSDoc @import

Use this alternative when you want IntelliSense without changing your existing JavaScript code structure:

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

/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  // Your code
}

JSDoc @param

Use this alternative for type safety in JavaScript files using import statements in JSDoc comments:

/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {import('@auth0/actions/post-login/v3').Event} event - Details about the user and the context in which they are logging in.
* @param {import('@auth0/actions/post-login/v3').PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  // Your code
};

TypeScript import

Use this alternative when developing with TypeScript for full type checking and modern syntax:

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

/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
  // Your code
};

When using TypeScript, you must compile your code to JavaScript before deploying to Auth0. The Auth0 Actions runtime only executes JavaScript.Use the TypeScript compiler (tsc) to transpile your .ts files to .js files, before it can be deployed. You must also include JSDoc comments to enable IntelliSense in the Dashboard.

​

例

以下の Actions の例は、JavaScript と TypeScript を並べて直接比較できるよう、あえて両方で示しています。

​

設定

JavaScript

Action の作成時に IntelliSense の補完を利用できるように、package.json で開発時の依存関係を定義します。

{
  "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

Action の作成時に IntelliSense の補完を利用できるように、package.json で開発時の依存関係を定義します。

{
  "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"
  }
}

Action の作成時に IntelliSense の補完を利用できるように、tsconfig.json を定義します。

{
  "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"
  ]
}

​

Post-Login のアクセス制御と IDトークン のカスタムクレーム

次の Action の例は、Post-Login フロー中に実行されます。ユーザーにロールが割り当てられているかどうかを確認し、ロールが見つからない場合は api.access.deny() を呼び出します。ロールが存在する場合は、IDトークン にカスタムクレームを設定します。

import 文は、コード内で外部型を利用できることを宣言するものです。これにより、エディターは event オブジェクトと api オブジェクトの構造を認識できます。

JavaScript

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

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

/**
* PostLogin フローの実行中に呼び出されるハンドラー。
*
* @param {Event} event - ユーザーの詳細情報と、そのユーザーがログインしているコンテキスト。
* @param {PostLoginAPI} api - ログインの動作を変更するためのメソッドを提供するインターフェース。
*/
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';

/**
* PostLogin フローの実行中に呼び出されるハンドラー。
*
* @param {Event} event - ユーザーの詳細情報と、そのユーザーがログインしているコンテキスト。
* @param {PostLoginAPI} api - ログインの動作を変更するためのメソッドを提供するインターフェース。
*/
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);
};

@auth0/actions の詳細については、https://www.npmjs.com/package/@auth0/actions を参照してください。

@auth0/actions の実装コードの詳細については、Auth0 Actions repository を参照してください。

Actions の作成方法の詳細については、Write Your First Action を参照してください。