Comment créer votre premier Action Module

Pour commencer

Suivez le Quickstart pour créer un Action Module et l’utiliser dans une Action afin d’envoyer des logs à un service externe.

Créer un module d’action

Pour utiliser un Action Module dans une Action précise, vous devez d’abord créer l’Action Module, puis l’ajouter ou l’utiliser dans l’Action.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Accédez à Auth0 Dashboard > Actions > Library, puis sélectionnez Modules.
Sélectionnez Create Module.
Entrez un Name.
Sélectionnez Create.

Obtenez un jeton d’accès de la Management API avec la permission create:actions.
Appelez 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 retourne le nouvel Action Module, y compris son id, que vous utiliserez pour référencer le module aux étapes suivantes.

Les Actions Modules ne sont pas exposés nativement par l’ensemble de commandes auth0-cli; utilisez donc auth0 api pour appeler directement la Management API. Certains appels nécessitent des permissions supplémentaires — au besoin, exécutez d’abord auth0 login --scopes create:actions,read:actions,update:actions.

Appelez Create an Actions Module avec auth0 api :

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

Auth0 retourne le nouvel Action Module, y compris son id, que vous utiliserez pour référencer le module aux étapes suivantes.

Consultez la documentation de la ressource auth0_action_module pour en savoir plus.

Ajoutez la ressource suivante à un fichier .tf, en référençant le code du module à partir d’un fichier :

action-modules/logger.tf

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

Créez le fichier de code du module à l’emplacement action-modules/logger/code.js :

action-modules/logger/code.js

module.exports = {};

Exécutez terraform apply.

Vous enrichirez le fichier de code et cette ressource avec des secrets aux étapes suivantes.

YAML
Directory (JSON)

Créez le fichier de code du module à l’emplacement action-modules/logger/code.js :

action-modules/logger/code.js

module.exports = {};

Ajoutez une entrée actionModules dans tenant.yaml :

tenant.yaml

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

Déployez la configuration :

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

Créez le fichier de configuration du module à l’emplacement action-modules/logger.json :

action-modules/logger.json

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

Créez le fichier de code du module à l’emplacement action-modules/logger/code.js :

action-modules/logger/code.js

module.exports = {};

Déployez la configuration :

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

Ajouter un secret

Chaque module d’action peut contenir des paires clé-valeur secrètes. Utilisez-les pour stocker des renseignements sensibles, comme des clés API, des certificats et des valeurs qui peuvent varier d’un environnement à l’autre.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Déployer CLI

Ensuite, enregistrez l’URL du service externe comme Secret.

Sélectionnez l’icône dans la barre latérale gauche de l’éditeur de code.
Sélectionnez Add Secret.
Saisissez SERVICE_URL dans le champ Name.
Saisissez l’URL du service externe dans le champ Value.
Sélectionnez Create.

Auth0 ajoute le Secret à la liste des Secrets du module d’action.

Ensuite, enregistrez l’URL du service externe comme Secret. Appelez Update an Actions Module avec la permission update:actions :

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

Chaque appel PATCH remplace l’ensemble du tableau secrets dans le brouillon du module. Incluez donc tous les Secrets dont le module a besoin, et non seulement celui que vous ajoutez.

Ensuite, enregistrez l’URL du service externe comme Secret. Appelez Update an Actions Module avec auth0 api :

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

Chaque appel remplace l’ensemble du tableau secrets dans le brouillon du module; incluez donc tous les Secrets dont le module a besoin, et non seulement celui que vous ajoutez.

Ensuite, enregistrez l’URL du service externe comme Secret à l’aide d’un bloc secrets :

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

Nous ne prenons pas en charge la gestion partielle des secrets. Chaque terraform apply envoie la liste complète des secrets définis sur la ressource.

Ensuite, enregistrez l’URL du service externe comme Secret.

YAML
Directory (JSON)

Ajoutez un tableau secrets à l’entrée du module dans tenant.yaml :

tenant.yaml

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

Ajoutez un tableau secrets à action-modules/logger.json :

action-modules/logger.json

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

Le paramètre fictif ##SERVICE_URL## est résolu par remplacement de mots-clés au moment du déploiement, de sorte que la valeur réelle ne se trouve jamais dans votre fichier de configuration.

Étape supplémentaire : Répétez les étapes pour enregistrer un API_KEY comme Secret que vous enverrez dans les en-têtes au service externe avec chaque requête.

Une fois un Secret créé, Auth0 n’en révèle jamais la valeur. Auth0 chiffre tous les Secrets et les stocke de façon sécurisée.

Chaque Secret de module d’action est indépendant des autres Modules d’action et des Secrets des Actions.

Utilisez les Secrets dans le module d’action en saisissant actions.secrets.[secret_key].

Ajouter de la logique personnalisée

Maintenant, ajoutez le code suivant à votre module d’action.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Ajoutez le code suivant à votre module d’action :

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;
  }
};

Appelez Update an Actions Module avec la requête suivante :

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

Où code-update.json contient le code du module sous forme de chaîne échappée en 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};"
}

Enregistrez le code du module dans 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};"
}

Puis transmettez-le à Update an Actions Module au moyen de auth0 api :

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

Mettez à jour le fichier de code du module situé à 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;
  }
};

L’attribut code de la ressource auth0_action_module référence déjà ce fichier; exécutez donc terraform apply pour appliquer la modification.

Mettez à jour action-modules/logger/code.js avec la logique du module :

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;
  }
};

À noter :

Enregistrer le brouillon

Vous pouvez enregistrer un brouillon de votre Action Module.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Sélectionnez Save Draft.

Il n’existe pas d’appel “save” distinct. Chaque requête Update an Actions Module effectuée aux étapes précédentes a déjà enregistré vos modifications dans le brouillon du module. Vous pouvez le confirmer avec Get an Actions Module :

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

Le champ all_changes_published de la réponse est false, ce qui confirme que le brouillon contient des modifications non publiées.

Il n’existe pas d’appel “save” distinct. Chaque requête auth0 api patch actions/modules/{moduleId} effectuée aux étapes précédentes a déjà enregistré vos modifications dans le brouillon du module. Vous pouvez le confirmer avec Get an Actions Module :

auth0 api get actions/modules/{moduleId}

Le champ all_changes_published de la réponse est false, ce qui confirme que le brouillon contient des modifications non publiées.

Il n’existe pas d’étape “save” distincte. La commande terraform apply que vous avez exécutée aux étapes précédentes a déjà mis à jour le brouillon du module. Le brouillon n’a aucun effet sur les Actions qui utilisent déjà une version publiée du module.

Définissez all_changes_published à false dans l’entrée du module.

Il n’existe pas d’étape “save” distincte.

YAML
Directory (JSON)

Mettez à jour tenant.yaml :

tenant.yaml

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

Redéployez la configuration pour publier la modification :

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

Mettez à jour 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"
}

Redéployez la configuration pour publier la modification :

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

Cette opération enregistre votre Action Module sans publier de nouvelle version; elle n’aura donc aucun effet sur les Actions qui l’utilisent.

Publier le module Action

Une fois que vous êtes satisfait du code de l’Action Module, il est temps de le publier.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Sélectionnez Publier.

La publication d’un Action Module en crée un instantané à ce moment précis et l’enregistre comme une version d’Action Module.

Sélectionnez Afficher l’historique des versions.

Actions Modules - Historique des versions

Auth0 affiche la liste des versions d’Action Module, y compris le brouillon.

Appelez Create an Actions Module Version, qui crée un instantané du brouillon actuel et le publie :

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

Auth0 retourne la nouvelle version d’Action Module, y compris son id et son version_number. Vous référencerez cet id comme module_version_id lorsque vous ajouterez le module à une Action.

Appelez Create an Actions Module Version avec auth0 api, qui crée un instantané du brouillon actuel et le publie :

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

Définissez publish à true sur la ressource, puis exécutez 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"
  }
}

La publication crée une nouvelle version d’Action Module à partir du brouillon actuel. Terraform expose l’ID de la version publiée dans l’attribut calculé version_id, que vous référencez depuis les ressources auth0_action sous le nom module_version_id.

Définissez all_changes_published à true dans l’entrée du module.

YAML
Directory (JSON)

Mettez à jour tenant.yaml :

tenant.yaml

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

Redéployez la configuration pour publier le changement :

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

Mettez à jour 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"
}

Redéployez la configuration pour publier le changement :

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

Cette opération publie une nouvelle version d’Action Module à partir du brouillon actuel, après l’application de vos changements.

Vous pouvez maintenant utiliser l’Action Module dans une Action.

Chaque Action doit faire explicitement référence à la version d’Action Module, ce qui empêche les mises à niveau automatiques susceptibles d’introduire des erreurs inattendues.

Ajouter l’Action Module à une Action

Ensuite, ajoutez le module d’action dans une action.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Accédez à Auth0 Dashboard > Actions > Library, puis sélectionnez une Action spécifique.
Dans l’éditeur d’Action, sélectionnez l’icône dans la barre latérale gauche.
Sélectionnez Ajouter un module.
Sélectionnez un Nom et une Version de module.
Sélectionnez Ajouter.

Appelez Update an Action avec les valeurs module_id et module_version_id du module obtenues à l’étape précédente :

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 n’a aucun indicateur pour les Action Modules; appelez donc directement Update an Action avec auth0 api, en utilisant les module_id et module_version_id du module obtenus à l’étape précédente :

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

Ajoutez un bloc modules à la ressource auth0_action, en y référençant le module et sa version publiée. Laissez l’attribut code pointer vers le fichier de code propre à l’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"
  }
}

Ajoutez un tableau modules à la configuration de l’Action, en référençant le module par son nom et son numéro de version.

YAML
Directory (JSON)

Ajoutez le tableau modules à l’entrée de l’Action dans tenant.yaml :

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

Ajoutez le tableau modules au fichier de configuration de l’Action (par exemple, actions/my-action.json) :

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

Le Deploy CLI résout module_name et module_version_number en les véritables module_id et module_version_id du module au moment du déploiement.

Utilisez le module d’action dans l’Action

Maintenant, utilisons l’Action Module dans l’Action.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Ajoutez l’instruction require.

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

L’instruction require fait référence à l’Action Module au format actions:[module-name].

Ajoutez l’appel à logger.sendLog dans la fonction Action, à l’endroit où vous souhaitez envoyer des logs.

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

Sélectionnez Deploy pour déployer l’Action.

Appelez Update an Action pour ajouter l’instruction require et l’appel à logger.sendLog au code de l’Action :

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

Où code-update.json contient :

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

Appelez Deploy an Action :

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

Mettez à jour le fichier de code de l’Action situé à actions/my-action/code.js avec l’instruction require et l’appel à 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');
};

Mettez à jour l’Action avec auth0 actions update et déployez-la avec auth0 actions deploy :

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

Mettez à jour le fichier de code de l’Action situé à actions/my-action/code.js avec l’instruction require et l’appel à 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');
};

Définissez deploy à true sur la ressource auth0_action, puis exécutez 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"
  }
}

Définir deploy = true crée immédiatement une nouvelle version déployée de l’Action.

Ajoutez l’instruction require et l’appel à logger.sendLog dans actions/my-action/code.js :

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');
};

Redéployez la configuration :

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

N’oubliez pas d’associer l’Action à un Trigger.

VérificationVous devriez maintenant avoir un Action Module entièrement fonctionnel utilisé par une Action.

Utilisation avancée

Dépendances NPM

Chaque Action Module peut ajouter et utiliser des dépendances NPM.

Dashboard
Management API
Auth0 CLI
Terraform
CLI Auth0 Deploy

Sélectionnez l’icône dans la barre latérale gauche de l’éditeur de code.
Sélectionnez Add Dependency.
Saisissez le Name du package NPM.
Saisissez la Version du package NPM.
Sélectionnez Create.

Auth0 ajoute la dépendance à la liste des dépendances du Action Module.

Appelez Update an Actions Module avec un tableau dependencies :

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

Comme pour les secrets, chaque appel PATCH remplace l’intégralité du tableau dependencies; incluez donc toutes les dépendances dont le module a besoin.

Appelez Update an Actions Module avec auth0 api, en utilisant un tableau dependencies :

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

Comme pour secrets, chaque appel remplace l’ensemble du tableau dependencies : incluez donc toutes les dépendances dont le module a besoin.

Ajoutez un bloc dependencies à la ressource auth0_action_module, puis exécutez 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"
  }
}

Ajoutez un tableau dependencies à la configuration du module.

YAML
Directory (JSON)

Ajoutez le tableau dependencies à l’entrée du module dans tenant.yaml :

tenant.yaml

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

Ajoutez le tableau dependencies à action-modules/logger.json :

action-modules/logger.json

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

Utilisez les dépendances répertoriées dans le Action Module en les important avec require('[package-name]').

Lorsque vous enregistrez cette Action, Auth0 résout la version la plus récente de votre dépendance et la remplace par un numéro de version précis afin d’éviter que de futures mises à jour du package ne brisent votre Action.Vous pouvez fournir une version précise au lieu de latest.

Concepts

Procédures

Référence

Cas d’utilisation

Comment créer votre premier Action Module

Pour commencer

Créer un module d’action

Ajouter un secret

Ajouter de la logique personnalisée

Enregistrer le brouillon

Publier le module Action

Ajouter l’Action Module à une Action

Utilisez le module d’action dans l’Action

Utilisation avancée

​Pour commencer

Créer un module d’action

Ajouter un secret

Ajouter de la logique personnalisée

Enregistrer le brouillon

Publier le module Action

Ajouter l’Action Module à une Action

Utilisez le module d’action dans l’Action

​Utilisation avancée

Pour commencer

Utilisation avancée