Keyword Preservation Not Working With Action Secrets or Flow Actions

Knowledge Articles
1

Overview

This article explains why the keyword preservation feature in the Auth0 Deploy CLI might not work as expected for certain configurations, even when enabled.

When the AUTH0_PRESERVE_KEYWORDS setting is set to true in the config.json file, the intention is to preserve keywords formatted as ##KEYWORD## during the export process. However, this preservation fails for configurations such as Action Secrets and Flow Actions.

For example:

  1. Action Secrets: If an action secret is configured with a keyword:
secrets: [{ "name": "secret-name", "value": "##SECRET_VALUE##" }]
  1. Upon export, the value containing the keyword ##SECRET_VALUE## is removed instead of being preserved.
  2. Flow Actions: If a keyword is used within Flow Action parameters, like a URL:
{
  "name": "Test Flow",
  "actions": [
    {
      "id": "http_request_XhRz",
      "type": "HTTP",
      "action": "SEND_REQUEST",
      "allow_failure": false,
      "mask_output": false,
      "params": {
        "method": "POST",
        "url": "https://api.example.com/accounts/##TEST_KW##",
        "content_type": "JSON"
      }
    }
  ]
}

Upon export, the keyword ##TEST_KW## within the url parameter is not preserved.

Applies To

  • AUTH0_PRESERVE_KEYWORDS
  • Auth0 Deploy CLI
  • Keyword

Cause

This issue occurs due to a known limitation in the keyword preservation functionality of the Auth0 Deploy CLI.

The standard keyword preservation mechanism (using ##KEYWORD## syntax) is not designed to work for elements within arrays that lack unique identifiers (such as a name or id field for each item). The order of elements in these simple arrays can be non-deterministic, making it unreliable to target specific elements for keyword replacement during export/import operations.

For instance, consider an array of strings like:

["value1", "value2", "##KEYWORD_VALUE##"]

The keyword ##KEYWORD_VALUE## within this array cannot be preserved using the standard #...# syntax because its position relative to other elements is not guaranteed across operations. This limitation applies to configurations like Action Secrets (which are arrays of objects) and Flow Actions where keywords might be part of array structures without unique element identifiers.

Solution

To preserve array values for configurations like Action Secrets or Flow Actions where the standard ##KEYWORD## syntax does not work due to the limitation described in the Cause, use the @@ARRAY_REPLACE@@ keyword syntax instead. This method replaces the entire array during deployment.

Follow these steps:

  1. Replace the Array with a @@...@@ Placeholder: In the configuration file for the specific resource (e.g., the Action script file), locate the array that needs preservation (like secrets). Replace the entire array structure with a placeholder keyword using the @@...@@ format.Example (in an Action configuration):
"secrets": @@ACTION_SECRETS_PLACEHOLDER@@

Define the Keyword Mapping in config.json: Open the Auth0 Deploy CLI’s config.json file. Within the AUTH0_KEYWORD_REPLACE_MAPPINGS object, add an entry where the key is the placeholder name used in Step 1 (without the @@ symbols), and the value is the complete array structure that should be substituted during deployment.

Example (in config.json):

"AUTH0_KEYWORD_REPLACE_MAPPINGS": {
  "ACTION_SECRETS_PLACEHOLDER": [
    {
      "name": "secret-name-1",
      "value": "actual-value-for-secret-1"
    },
    {
      "name": "secret-name-2",
      "value": "actual-value-for-secret-2"
    }
    // Add other items to the array as needed
  ]
  // Add other keyword mappings here if needed
}

By using this @@ARRAY_REPLACE@@ method, the Auth0 Deploy CLI will substitute the entire defined array structure for the placeholder during deployment, effectively working around the limitation of preserving individual keywords within simple arrays.