Actions NPM

公式の @auth0/actions NPM パッケージを開発用依存関係としてインストールすると、外部エディターでトリガーとバージョンごとに Auth0 Actions を作成して単体テストする際に、TypeScript 型定義、IntelliSense、エラーチェックを追加できます。

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

@auth0/actions の公開リポジトリでは、この NPM パッケージの元になっているコードを参照できます。

​

利点

このライブラリは、次のユースケースで役立ちます。

• IDE / コードエディター支援: このライブラリを参照することで、IDE やコードエディターは、自動補完、オブジェクトや関数の定義、エラーチェックなどを通じて、開発者のコーディングを支援できます。
• TypeScript 開発: Actions は引き続き Node.js CommonJS を使って記述・実行されますが、このライブラリを使うことで、外部プロジェクトで TypeScript による Actions 開発が可能になり、その後 Auth0テナント向けの CommonJS としてビルドおよびデプロイできます。
• 単体テストの改善: 外部プロジェクトでの 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

インポート文は、以前のライブラリ構造を踏まえ、各トリガー名とバージョン番号に基づいて指定する必要があります。

次のパターンに従ってください: @auth0/actions/[trigger_name]/[trigger_version]

例: @auth0/actions/post-login/v3

利用している技術に応じて、次のいずれかの方法で TypeScript の型定義を Actions にインポートしてください。

既存の JavaScript コード構造を変更せずに IntelliSense を利用したい場合は、この方法を使用します。

JSDoc @import

既存の JavaScript コード構造を変更せずに IntelliSense を利用したい場合は、この方法を使用します。

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

/**
* PostLogin フローの実行中に呼び出されるハンドラー。
*
* @param {Event} event - ユーザーに関する詳細情報と、ログイン時のコンテキスト。
* @param {PostLoginAPI} api - ログインの挙動を変更するためのメソッドを提供するインターフェース。
*/
exports.onExecutePostLogin = async (event, api) => {
  // コードを記述
}

JSDoc @param

JSDoc コメント内の import 文を使って、JavaScript ファイルで型安全性を確保したい場合は、この方法を使用します。

/**
* PostLogin フローの実行中に呼び出されるハンドラー。
*
* @param {import('@auth0/actions/post-login/v3').Event} event - ユーザーに関する詳細情報と、ログイン時のコンテキスト。
* @param {import('@auth0/actions/post-login/v3').PostLoginAPI} api - ログインの挙動を変更するためのメソッドを提供するインターフェース。
*/
exports.onExecutePostLogin = async (event, api) => {
  // コードを記述
};

TypeScript import

TypeScript で開発し、完全な型チェックとモダンな構文を利用したい場合は、この方法を使用します。

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

/**
* PostLogin フローの実行中に呼び出されるハンドラー。
*
* @param {Event} event - ユーザーに関する詳細情報と、ログイン時のコンテキスト。
* @param {PostLoginAPI} api - ログインの挙動を変更するためのメソッドを提供するインターフェース。
*/
exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
  // コードを記述
};

TypeScript を使用する場合は、Auth0 にデプロイする前にコードを JavaScript にコンパイルする必要があります。Auth0 Actions ランタイムが実行できるのは JavaScript のみです。デプロイ前に、TypeScript コンパイラ (tsc) を使用して .ts ファイルを .js ファイルにトランスパイルしてください。また、Dashboard で IntelliSense を有効にするには、JSDoc コメントも含める必要があります。

​

例

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

​

設定

JavaScript

package.json では、Action の作成時に IntelliSense の支援を受けられるよう、開発用の依存関係を定義します。

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

package.json では、Action の作成時に IntelliSense の支援を受けられるよう、開発用の依存関係を定義します。

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

tsconfig.json では、Action の作成時に IntelliSense の支援を受けられるよう、必要な設定を定義します。

{
  "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 トークンにカスタムクレームを設定します。

// インポート文は、外部の型をコード内で利用できることを宣言するものです。これにより、エディターは 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 リポジトリをご覧ください。

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