Actions NPM

プロジェクトのActionを@auth0/actions NPMパッケージを使用してコーディングします。

@auth0/actions NPMパッケージは、Auth0 Actions TypeScriptの定義を助ける公式のActionライブラリーです。外部のエディターやIDEでプロジェクトのActionをコーディングしたりテストしたりするときに役立ちます。

​

利点

このライブラリーは以下のユースケースに役立ちます。

• IDE / コードエディターのアシスタンス：開発者はこのライブラリーを参照することで、IDEやコードエディターで自動補完、オブジェクトと関数の定義、エラーチェックを使ったコーディングを行えます。
• TypeScript Development：ActionはあくまでもNode.js CommonJSを使用してコーディングされ、動作しますが、このライブラリーを活用することで、TypeScriptを使用して外部プロジェクトでActionを開発できるようになり、Auth0テナントにCommon JSとしてビルトおよびデプロイすることが可能になります。
• ユニットテストの改善：外部プロジェクトでのTypeScript開発が可能になることで、開発者はベストプラクティスに沿い、TypeScriptの定義に基づいてユニットテストを改善できるようになります。
• AIでのAction生成：このライブラリーで、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

importステートメントは、以前のライブラリー構造を考慮して、各トリガー名とバージョン番号に基づく必要があります。

パターンに従う：@auth0/actions/[trigger_name]/[trigger_version]

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

使用するテクノロジーに応じて、次のいずれかの方法でTypeScriptの定義をActionにインポートします。

既存の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

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

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ファイルにトランスパイルしてください。また、ダッシュボードで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"
  ]
}

​

ログイン後のアクセスコントロールとIDトークンのカスタムクレーム

以下の例のActionは、ログイン後のフロー中に実行されます。ユーザーにロールが割り当てられているかを確認し、何もない場合は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を参照してください。

Actionsの作成について詳しくは、「初めてのActionを作成する」をお読みください。