はじめてのAction Moduleを作成する

はじめに

Quickstartを使ってAction Moduleを作成し、Actionからそれを利用してログを外部サービスに送信します。

Action モジュールを作成

特定のActionからAction Moduleを使用するには、まずAction Moduleを作成し、その後Actionに追加して使用する必要があります。

Auth0 Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Auth0 Dashboard > Actions > Library に移動し、Modules を選択します。
Create Module を選択します。
Name を入力します。
Create を選択します。

create:actions スコープを付与した Management API アクセストークンを取得します。
Create an Actions Module を呼び出します。

curl -L 'https://{yourDomain}/api/v2/actions/modules' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d '{
    "name": "logger",
    "code": "module.exports = {};",
    "api_version": "1",
    "publish": false
  }'

Auth0 は新しい Action Module を返します。この中には id が含まれており、以降の手順でモジュールを参照する際に使用します。

Actions Modules は auth0-cli のコマンドセットでは直接サポートされていないため、auth0 api を使って Management API を直接呼び出します。一部の呼び出しには追加のスコープが必要です。必要に応じて、まず auth0 login --scopes create:actions,read:actions,update:actions を実行してください。

auth0 api で Create an Actions Module を呼び出します。

auth0 api post actions/modules --data '{
  "name": "logger",
  "code": "module.exports = {};",
  "api_version": "1",
  "publish": false
}'

Auth0 は新しい Action Module を返します。この中には id が含まれており、以降の手順でモジュールを参照する際に使用します。

詳しくは auth0_action_module リソースのドキュメントをご覧ください。

次のリソースを .tf ファイルに追加し、モジュールのコードをファイルから参照します。

action-modules/logger.tf

resource "auth0_action_module" "logger" {
  name = "logger"
  code = file("${path.module}/action-modules/logger/code.js")
}

モジュールのコードファイルを action-modules/logger/code.js に作成します。

action-modules/logger/code.js

module.exports = {};

terraform apply を実行します。

このコードファイルとリソースは、以降の手順で Secrets を追加して拡張していきます。

YAML
Directory (JSON)

モジュールのコードファイルを action-modules/logger/code.js に作成します。

action-modules/logger/code.js

module.exports = {};

tenant.yaml に actionModules のエントリーを追加します。

tenant.yaml

actionModules:
  - name: logger
    code: ./action-modules/logger/code.js

構成を導入します。

a0deploy import -c=config.json --input_file=tenant.yaml

モジュールの構成ファイルを action-modules/logger.json に作成します。

action-modules/logger.json

{
  "name": "logger",
  "code": "./action-modules/logger/code.js"
}

モジュールのコードファイルを action-modules/logger/code.js に作成します。

action-modules/logger/code.js

module.exports = {};

構成を導入します。

a0deploy import -c=config.json --input_file=local.

Secretを追加

各 Action Module には、シークレットのキーと値のペアを含めることができます。これらを使って、API キーや証明書、環境ごとに変わる可能性のある値などの機密情報を保持します。

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 導入 CLI

次に、外部サービスの URL を Secret として保存します。

コードエディターの左側のサイドバーにあるアイコンを選択します。
Add Secret を選択します。
Name に SERVICE_URL と入力します。
Value フィールドに外部サービスの URL を入力します。
Create を選択します。

Secret が Action Module の Secret 一覧に追加されます。

次に、外部サービスの URL を Secret として保存します。update:actions スコープを使って Update an Actions Module を呼び出します。

curl -L -X PATCH 'https://{yourDomain}/api/v2/actions/modules/{moduleId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d '{
    "secrets": [
      { "name": "SERVICE_URL", "value": "https://example.com/logs" }
    ]
  }'

PATCH を呼び出すたびに、モジュールの下書きにある secrets 配列全体が置き換えられます。そのため、今回追加するものだけでなく、モジュールに必要なすべての Secret を含めてください。

次に、外部サービスの URL を Secret として保存します。auth0 api で Update an Actions Module を呼び出します。

auth0 api patch actions/modules/{moduleId} --data '{
  "secrets": [
    { "name": "SERVICE_URL", "value": "https://example.com/logs" }
  ]
}'

呼び出しのたびにモジュールの下書きの secrets 配列全体が置き換えられるため、今回追加するものだけでなく、そのモジュールに必要なすべての Secret を含めてください。

次に、secrets ブロックを使って外部サービスの URL を Secret として保存します。

action-modules/logger.tf

resource "auth0_action_module" "logger" {
  name = "logger"
  code = file("${path.module}/action-modules/logger/code.js")

  secrets {
    name  = "SERVICE_URL"
    value = "https://example.com/logs"
  }
}

secrets の部分的な管理はサポートしていません。terraform apply を実行するたびに、リソースに定義されたシークレットの完全な一覧が送信されます。

次に、外部サービスの URL を Secret として保存します。

YAML
Directory (JSON)

tenant.yaml 内のモジュールのエントリに secrets 配列を追加します。

tenant.yaml

actionModules:
  - name: logger
    secrets:
      - name: SERVICE_URL
        value: ##SERVICE_URL##
    code: ./action-modules/logger/code.js

action-modules/logger.json に secrets 配列を追加します。

action-modules/logger.json

{
  "name": "logger",
  "secrets": [
    { "name": "SERVICE_URL", "value": "##SERVICE_URL##" }
  ],
  "code": "./action-modules/logger/code.js"
}

##SERVICE_URL## の placeholder は、導入時にキーワード置換によって解決されるため、実際の値が設定ファイルに残ることはありません。

追加の手順: 同じ手順で API_KEY も Secret として保存します。これは、各リクエストで外部サービスに送信するヘッダーに含めるためのものです。

Secret は一度作成すると、その値が Auth0 から再表示されることはありません。Auth0 はすべての Secrets を暗号化して安全に保存します。

各 Action Module Secret は、ほかの Actions Modules や Actions Secrets とは独立しています。

Action Module で Secrets を使用するには、actions.secrets.[secret_key] と入力します。

カスタムロジックを追加

次に、Action Module に以下のコードを追加します。

Auth0 Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Action Module に以下のコードを追加します。

module.exports = {
  sendLog: async (code, message) => {
    try {
      await fetch(actions.secrets.SERVICE_URL, {
        method: 'POST',
        headers: {
          'X-API-Key': actions.secrets.API_KEY,
        },
        body: JSON.stringify({
          code,
          message
        }),
      });

      console.log({
        code,
        message
      });
    } catch (err) {
      throw new Error('External service failure');
    }

    return;
  }
};

以下のリクエストで Update an Actions Module を呼び出します。

curl -L -X PATCH 'https://{yourDomain}/api/v2/actions/modules/{moduleId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d @code-update.json

ここで code-update.json には、モジュールの code が JSON エスケープされた文字列として含まれます。

code-update.json

{
  "code": "module.exports = {\n  sendLog: async (code, message) => {\n    try {\n      await fetch(actions.secrets.SERVICE_URL, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': actions.secrets.API_KEY,\n        },\n        body: JSON.stringify({ code, message }),\n      });\n\n      console.log({ code, message });\n    } catch (err) {\n      throw new Error('External service failure');\n    }\n\n    return;\n  }\n};"
}

モジュールのコードを code-update.json に保存します。

code-update.json

{
  "code": "module.exports = {\n  sendLog: async (code, message) => {\n    try {\n      await fetch(actions.secrets.SERVICE_URL, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': actions.secrets.API_KEY,\n        },\n        body: JSON.stringify({ code, message }),\n      });\n\n      console.log({ code, message });\n    } catch (err) {\n      throw new Error('External service failure');\n    }\n\n    return;\n  }\n};"
}

次に、auth0 api を使って Update an Actions Module にパイプで渡します。

cat code-update.json | auth0 api patch actions/modules/{moduleId}

action-modules/logger/code.js にあるモジュールのコードファイルを更新します。

action-modules/logger/code.js

module.exports = {
  sendLog: async (code, message) => {
    try {
      await fetch(actions.secrets.SERVICE_URL, {
        method: 'POST',
        headers: {
          'X-API-Key': actions.secrets.API_KEY,
        },
        body: JSON.stringify({
          code,
          message
        }),
      });

      console.log({
        code,
        message
      });
    } catch (err) {
      throw new Error('External service failure');
    }

    return;
  }
};

auth0_action_module リソースの code 属性はすでにこのファイルを参照しているため、terraform apply を実行して変更を適用します。

action-modules/logger/code.js をモジュールのロジックで更新します。

action-modules/logger/code.js

module.exports = {
  sendLog: async (code, message) => {
    try {
      await fetch(actions.secrets.SERVICE_URL, {
        method: 'POST',
        headers: {
          'X-API-Key': actions.secrets.API_KEY,
        },
        body: JSON.stringify({
          code,
          message
        }),
      });

      console.log({
        code,
        message
      });
    } catch (err) {
      throw new Error('External service failure');
    }

    return;
  }
};

以下の点に注意してください。

下書きを保存

Action Module のドラフトを保存できます。

Auth0 Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

下書きとして保存 を選択します。

“保存”のための個別の呼び出しはありません。前の手順で実行した Update an Actions Module のリクエストはすべて、変更内容をすでにモジュールのドラフトに保存しています。これは Get an Actions Module で確認できます。

curl -L 'https://{yourDomain}/api/v2/actions/modules/{moduleId}' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}'

レスポンスの all_changes_published フィールドが false になっており、ドラフトに未公開の変更があることが確認できます。

“保存”のための個別の呼び出しはありません。前の手順で実行した auth0 api patch actions/modules/{moduleId} のリクエストはすべて、変更内容をすでにモジュールのドラフトに保存しています。これは Get an Actions Module で確認できます。

auth0 api get actions/modules/{moduleId}

レスポンスの all_changes_published フィールドが false になっており、ドラフトに未公開の変更があることが確認できます。

“保存”のための個別の手順はありません。前の手順で実行した terraform apply によって、モジュールのドラフトはすでに更新されています。ドラフトは、モジュールの公開済みバージョンをすでに使用している Actions には影響しません。

モジュールのエントリで all_changes_published を false に設定します。

“保存”のための個別の手順はありません。

YAML
Directory (JSON)

tenant.yaml を更新します。

tenant.yaml

actionModules:
  - name: logger
    all_changes_published: false
    secrets:
      - name: SERVICE_URL
        value: ##SERVICE_URL##
    code: ./action-modules/logger/code.js

変更を公開するために構成を再デプロイします。

a0deploy import -c=config.json --input_file=tenant.yaml

action-modules/logger.json を更新します。

action-modules/logger.json

{
  "all_changes_published": false,
  "name": "logger",
  "secrets": [
    { "name": "SERVICE_URL", "value": "##SERVICE_URL##" }
  ],
  "code": "./action-modules/logger/code.js"
}

変更を公開するために構成を再デプロイします。

a0deploy import -c=config.json --input_file=local.

これにより、新しいバージョンを公開せずに Action Module が保存されるため、それを使用している Actions には影響しません。

Action モジュールを公開する

Action Module のコードに問題がなければ、公開します。

Auth0 Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

公開を選択します。

Action Module を公開すると、その時点のスナップショットが取得され、Action Module Version として記録されます。

バージョン履歴を表示を選択します。

下書きを含む Action Module Version の一覧が表示されます。

Create an Actions Module Version を呼び出します。これにより、現在の下書きのスナップショットが取得され、公開されます。

curl -L -X POST 'https://{yourDomain}/api/v2/actions/modules/{moduleId}/versions' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}'

Auth0 は、id と version_number を含む新しい Action Module Version を返します。モジュールを Action に追加する際は、この id を module_version_id として参照します。

auth0 api で Create an Actions Module Version を呼び出します。これにより、現在の下書きのスナップショットが取得され、公開されます。

auth0 api post actions/modules/{moduleId}/versions

リソースの publish を true に設定し、terraform apply を実行します。

action-modules/logger.tf

resource "auth0_action_module" "logger" {
  name    = "logger"
  code    = file("${path.module}/action-modules/logger/code.js")
  publish = true

  secrets {
    name  = "SERVICE_URL"
    value = "https://example.com/logs"
  }
}

公開すると、現在の下書きから新しい Action Module Version が作成されます。Terraform は、公開されたバージョンの ID を version_id という算出属性として公開します。これを auth0_action リソースから module_version_id として参照します。

モジュールのエントリーで all_changes_published を true に設定します。

YAML
Directory (JSON)

tenant.yaml を更新します。

tenant.yaml

actionModules:
  - name: logger
    all_changes_published: true
    secrets:
      - name: SERVICE_URL
        value: ##SERVICE_URL##
    code: ./action-modules/logger/code.js

変更を公開するために、構成を再デプロイします。

a0deploy import -c=config.json --input_file=tenant.yaml

action-modules/logger.json を更新します。

action-modules/logger.json

{
  "all_changes_published": true,
  "name": "logger",
  "secrets": [
    { "name": "SERVICE_URL", "value": "##SERVICE_URL##" }
  ],
  "code": "./action-modules/logger/code.js"
}

変更を公開するために、構成を再デプロイします。

a0deploy import -c=config.json --input_file=local.

これにより、変更が適用された後、現在の下書きから新しい Action Module Version が公開されます。

これで、Action で Action Module を使えるようになります。

各 Action では、Action Module Version を明示的に参照する必要があります。これにより、予期しないエラーにつながる自動アップグレードを防げます。

Action 内に Action Module を追加する

次に、ActionにAction Moduleを追加します。

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 導入 CLI

Auth0 Dashboard > Actions > ライブラリに移動して、特定の Action を選択します。
Action エディタに移動したら、左側のサイドバーにあるアイコンを選択します。
モジュールを追加を選択します。
モジュールの名前とバージョンを選択します。
追加を選択します。

前の手順で取得したモジュールの module_id と module_version_id を指定して、Update an Action を呼び出します。

curl -L -X PATCH 'https://{yourDomain}/api/v2/actions/actions/{actionId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d '{
    "modules": [
      {
        "module_id": "{moduleId}",
        "module_version_id": "{moduleVersionId}"
      }
    ]
  }'

auth0 actions update には Action Module 用のフラグがないため、前の手順で取得したモジュールの module_id と module_version_id を使い、auth0 api で Update an Action を直接呼び出してください。

auth0 api patch actions/actions/{actionId} --data '{
  "modules": [
    {
      "module_id": "{moduleId}",
      "module_version_id": "{moduleVersionId}"
    }
  ]
}'

auth0_action リソースに modules ブロックを追加し、モジュールとその公開済みバージョンを参照します。code 属性は、引き続き Action 自身のコードファイルを指すようにしておきます。

actions/my-action.tf

resource "auth0_action" "my_action" {
  name = "my-action"
  code = file("${path.module}/actions/my-action/code.js")

  modules {
    module_id         = auth0_action_module.logger.id
    module_version_id = auth0_action_module.logger.version_id
  }

  supported_triggers {
    id      = "post-login"
    version = "v3"
  }
}

Action の設定に modules 配列を追加し、モジュールを名前とバージョン番号で参照します。

YAML
Directory (JSON)

tenant.yaml の Action のエントリに modules 配列を追加します。

tenant.yaml

actions:
  - name: my-action
    code: ./actions/my-action/code.js
    supported_triggers:
      - id: post-login
        version: v3
    modules:
      - module_name: logger
        module_version_number: 1

Action の設定ファイル (例: actions/my-action.json) に modules 配列を追加します。

actions/my-action.json

{
  "modules": [
    { "module_name": "logger", "module_version_number": 1 }
  ],
  "name": "my-action",
  "code": "./actions/my-action/code.js",
  "supported_triggers": [
    { "id": "post-login", "version": "v3" }
  ]
}

Deploy CLI は、導入時に module_name と module_version_number をモジュールの実際の module_id と module_version_id に解決します。

Action で Action Module を使う

次に、Action 内で Action Module を使ってみましょう。

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 導入 CLI

require 文を追加します。

const logger = require('actions:logger');

require 文では、actions:[module-name] の形式で Action Module を参照します。

ログを送信したい箇所の Action 関数 に、logger.sendLog の呼び出しを追加します。

await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');

Action を Deploy します。

Update an Action を呼び出して、Action の code に require 文と logger.sendLog の呼び出しを追加します。

curl -L -X PATCH 'https://{yourDomain}/api/v2/actions/actions/{actionId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d @code-update.json

code-update.json の内容は次のとおりです。

code-update.json

{
  "code": "const logger = require('actions:logger');\n\nexports.onExecutePostLogin = async (event, api) => {\n  await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');\n};"
}

Deploy an Action を呼び出します。

curl -L -X POST 'https://{yourDomain}/api/v2/actions/actions/{actionId}/deploy' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}'

actions/my-action/code.js にある Action のコードファイルを更新し、require 文と logger.sendLog の呼び出しを追加します。

actions/my-action/code.js

const logger = require('actions:logger');

exports.onExecutePostLogin = async (event, api) => {
  await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');
};

auth0 actions update で Action を更新し、auth0 actions deploy で導入します。

auth0 actions update {actionId} --code "$(cat actions/my-action/code.js)"
auth0 actions deploy {actionId}

actions/my-action/code.js にある Action のコードファイルを更新し、require 文と logger.sendLog の呼び出しを追加します。

actions/my-action/code.js

const logger = require('actions:logger');

exports.onExecutePostLogin = async (event, api) => {
  await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');
};

auth0_action リソースの deploy を true に設定し、terraform apply を実行します。

actions/my-action.tf

resource "auth0_action" "my_action" {
  name    = "my-action"
  deploy  = true
  code    = file("${path.module}/actions/my-action/code.js")

  modules {
    module_id         = auth0_action_module.logger.id
    module_version_id = auth0_action_module.logger.version_id
  }

  supported_triggers {
    id      = "post-login"
    version = "v3"
  }
}

deploy = true を設定すると、Action の新しいバージョンが即座に作成され、導入されます。

actions/my-action/code.js に require 文と logger.sendLog の呼び出しを追加します。

actions/my-action/code.js

const logger = require('actions:logger');

exports.onExecutePostLogin = async (event, api) => {
  await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');
};

構成を再導入します:

a0deploy import -c=config.json --input_file=local.

Action をトリガーにバインドすることを忘れないでください。

チェックポイントこれで、完全に動作する Action Module を Action で使用できるようになっているはずです。

応用的な使い方

NPM依存関係

各 Action Module では、NPM依存関係 を追加して利用できます。

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

コードエディターの左側のサイドバーで、アイコンを選択します。
Add Dependency を選択します。
NPM package の Name を入力します。
NPM package の Version を入力します。
Create を選択します。

Auth0 によって、その依存関係が Action Module の依存関係一覧に追加されます。

dependencies 配列を指定して Update an Actions Module を呼び出します。

curl -L -X PATCH 'https://{yourDomain}/api/v2/actions/modules/{moduleId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d '{
    "dependencies": [
      { "name": "lodash", "version": "4.17.21" }
    ]
  }'

secrets と同様に、PATCH を呼び出すたびに dependencies 配列全体が置き換えられるため、モジュールに必要なすべての依存関係を含めてください。

dependencies 配列を使用して、auth0 api で Update an Actions Module を呼び出します:

auth0 api patch actions/modules/{moduleId} --data '{
  "dependencies": [
    { "name": "lodash", "version": "4.17.21" }
  ]
}'

secrets と同様に、呼び出しごとに dependencies 配列全体が置き換えられるため、モジュールに必要なすべての依存関係を含めてください。

auth0_action_module リソースに dependencies ブロックを追加し、terraform apply を実行します。

action-modules/logger.tf

resource "auth0_action_module" "logger" {
  name = "logger"
  code = file("${path.module}/action-modules/logger/code.js")

  dependencies {
    name    = "lodash"
    version = "4.17.21"
  }
}

モジュールの設定に dependencies 配列を追加します。

YAML
Directory (JSON)

tenant.yaml 内のモジュールのエントリーに dependencies 配列を追加します。

tenant.yaml

actionModules:
  - name: logger
    dependencies:
      - name: lodash
        version: 4.17.21
    code: ./action-modules/logger/code.js

action-modules/logger.json に dependencies 配列を追加します。

action-modules/logger.json

{
  "dependencies": [
    { "name": "lodash", "version": "4.17.21" }
  ],
  "name": "logger",
  "code": "./action-modules/logger/code.js"
}

一覧に表示されている 依存関係 は、require('[package-name]') で読み込むことで Action Module 内で使用できます。

この Action を保存すると、Auth0 は依存関係の最新バージョンを解決し、今後のパッケージ更新によって Action が壊れないよう、特定のバージョン番号に置き換えます。latest の代わりに、特定のバージョンを指定することもできます。

ブランドのカスタマイズ

コードをカスタマイズする

サードパーティによるカスタマイズ

はじめてのAction Moduleを作成する

はじめに

Action モジュールを作成

Secretを追加

カスタムロジックを追加

下書きを保存

Action モジュールを公開する

Action 内に Action Module を追加する

Action で Action Module を使う

応用的な使い方

​はじめに

Action モジュールを作成

Secretを追加

カスタムロジックを追加

下書きを保存

Action モジュールを公開する

Action 内に Action Module を追加する

Action で Action Module を使う

​応用的な使い方

はじめに

応用的な使い方