Import/Export Tenant Configuration to Directory Structure

The auth0-deploy-cli tool includes a directory option that allows you to export and import an existing Auth0 tenant configuration into a predefined directory structure.

To maintain a consistent state, the Deploy CLI tool will always do a full deployment of the contents of your folders. Any rules or database connection scripts that exist in Auth0 but not in your file structure will be deleted.

When AUTH0_ALLOW_DELETE is set to yes in your config.json file, existing settings are deleted only when corresponding folders are present and contain configuration files. Settings are not deleted for missing or empty folders.

To import an Auth0 tenant configuration with the directory option:

Copy config.json.example, making sure to replace the placeholder values with the values specific to your configuration.
{ "AUTH0_DOMAIN": "<YOUR_TENANT>.auth0.com", "AUTH0_CLIENT_ID": "<client_id>", "AUTH0_CLIENT_SECRET": "<client_secret>", "AUTH0_KEYWORD_REPLACE_MAPPINGS": { "AUTH0_TENANT_NAME": "<NAME>", "ENV": "DEV" }, "AUTH0_ALLOW_DELETE": false, "AUTH0_EXCLUDED_RULES": [ "rule-1-name", "rule-2-name" ], "INCLUDED_PROPS": { "clients": [ "client_secret" ] }, "EXCLUDED_PROPS": { "connections": [ "options.client_secret" ] } }
Was this helpful?/
Use the client ID and secret from your newly-created application. If you used the Deploy CLI Extension to create the application, the client is named auth0-deploy-cli-extension. By default, the tool merges with your current environment variables and overrides the config.json file (which has the same top key). You can use the --no-env option to disable the override via the command line. You can either set the environment variables, or you can place the values in a configuration file anywhere on the file system that is accessible by the Deploy CLI Tool.

Deploy using the following command:

a0deploy import --config_file config.json --input_file .

Was this helpful?/

Here is an example of a config.json file:

{
  "AUTH0_DOMAIN": "<your auth0 domain (e.g., travel0-dev.auth0.com) >",
  "AUTH0_CLIENT_SECRET": "<your deploy client secret>",
  "AUTH0_CLIENT_ID": "<your deploy client ID>",
  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "YOUR_ARRAY_KEY": [
      "http://localhost:8080",
      "https://somedomain.com"
    ],
    "YOUR_STRING_KEY": "some environment-specific string"
  },
  "AUTH0_ALLOW_DELETE": false,
  "INCLUDED_PROPS": {
    "clients": [ "client_secret" ]
  },
  "EXCLUDED_PROPS": {
    "connections": [ "options.client_secret" ],
    "emailProvider": ["name", "credentials", "default_from_address", "enabled"]
  },
  "AUTH0_EXCLUDED_RULES": [ "auth0-account-link-extension" ],
  "AUTH0_EXCLUDED_CLIENTS": [ "auth0-account-link" ],
  "AUTH0_EXCLUDED_RESOURCE_SERVERS": [ "SSO Dashboard API" ],
  "AUTH0_EXCLUDED_DEFAULTS": ["emailProvider"]
}

Was this helpful?/

Using the config.json file, you can exclude the following records from the deployment process:

rules (AUTHO_EXCLUDED_RULES)
clients (AUTH0_EXCLUDED_CLIENTS)
databases (AUTH0_EXCLUDED_DATABASES)
connections (AUTH0_EXCLUDED_CONNECTIONS)
resource servers (AUTH0_EXCLUDED_RESOURCE_SERVERS)

If excluded, records will not be modified by deployments.

Beginning with version 3.0.0, you can manage your secrets and tenant-based environment variables using keyword mapping. This is useful if you want to specify different variables across your environments. For example, you could specify different JWT timeouts for your Development, QA/Testing, and Production environments.

Set your keyword mappings in your config.json file using AUTH0_KEYWORD_REPLACE_MAPPINGS. For an example, see the example configuration file above.

To use keyword mapping, either wrap the key using:

@ symbols (e.g., @@key@@), which will cause your value to be converted from a Javascript object or value to a JSON string.
# symbols (e.g., ##key##), which will cause Auth0 to perform a literal replacement.

A sample implementation is as follows:

Client.json

{
  ...
  "callbacks": [
    "##ENVIRONMENT_URL##/auth/callback"
  ],
  "jwt_configuration": {
    "lifetime_in_seconds": ##JWT_TIMEOUT##,
    "secret_encoded": true
  }
  ...
}

Was this helpful?/

To add hook secrets to your environment, add secrets in the .json configuration file (in this example, hook1.json) as follows:

"secrets": { 
  "api-key": "my custom api key" 
}

Was this helpful?/

The secrets object cannot be nested, so remember to prefix your secrets.

To export your current tenant configuration, run a command that's similar to:

a0deploy export --config_file config.json --format directory --output_folder path/to/export

Was this helpful?/

When importing objects into Auth0 tenants, Auth0 generates new IDs. To avoid import failure, identifier fields are stripped from the Auth0 objects on export by default. To override this behavior, use --export_ids or AUTH0_EXPORT_IDENTIFIERS: true.

Some of the settings cannot be exported, such as rulesConfigs values. After exporting, you may need to update the values in tenant.yaml if you see schema-related errors during the import process.

To learn more, see Deploy CLI Tool Environment Variables and Keyword Mappings.

The following is a sample of what the export directory structure looks like. For full details on everything that can be included, see the extension's repository:

repository =>
  clients
    client1.json
    client2.json
  connections
    connection1.json
  database-connections
    connection1
      database.json
      create.js
      delete.js
      get_user.js
      login.js
      verify.js
  emails
    provider.json
    verify_email.json
    verify_email.html
    welcome_email.json
    welcome_email.html
  grants
    grant1.json
  pages
    login.html
    login.json
    password_reset.html
    password_reset.json
  resource-servers
    resource_server1.json
    resource_server2.json
  rules
    rule1.js
    rule1.json
    rule2.js
  rules-configs
    env_param1.json
    some_secret1.json
  hooks
     hook1.js
     hook1.json
  guardian
    factors
      sms.json
      email.json
      otp.json
      push-notification.json
    provider
      sms-twilio.json
    templates
      sms.json

Was this helpful?/

This works for only non-Auth0 connections (strategy !== auth0). For Auth0 connections, use database-connections.

To deploy a connection, create a JSON file under the connections directory in your file structure. For example:

facebook.json

{
  "name": "facebook",
  "strategy": "facebook",
  "enabled_clients": [
    "my-client"
  ],
  "options": {}
}

Was this helpful?/

The enabled_clients array, when used directly with the Management API v2, is a list of client IDs for which the connection is enabled. As an added convenience, the Deploy CLI tool will attempt to match entries in the enabled_clients array by client name and replace them with the appropriate client ID when a match is found, allowing you to specify "my-client-name" instead of "my-client-id" to refer to each application.

To learn more about allowed attributes for connections, see Auth0's Management API Post Connections endpoint.

This works for only Auth0 connections (strategy === auth0) . For non-Auth0 connections, use connections.

To deploy a database connection, create a subdirectory named [connection-name] under the database-connections directory in your file structure. The name of the subdirectory must exactly match the name of your database connection in Auth0. You can create as many subdirectories as you have database connections.

Create a JSON file named database.json under the corresponding database-connections/[connection-name] subdirectory in your file structure.

Support for using settings.json rather than database.json has been deprecated since extension v3.1.1 and may be dropped in a future release.

To learn more about allowed attributes for connections, see Auth0's Management API Patch Connections by ID endpoint.

To deploy a database connection script, create a JavaScript file under the corresponding database-connections/[connection-name] subdirectory in your file structure. The filename of the JavaScript file should correspond to the database connection script you want to deploy.

Allowed scripts include:

get_user.js
create.js
verify.js
login.js
change_password.js
delete.js

For a generic custom database connection, only the login.js script is required. However, if you enable the migration feature, you will also need to provide the get_user.js script.

To see examples, visit the Auth0 Samples GitHub repository.

Supported pages include:

error_page
guardian_multifactor
login
password_reset

To deploy a page, create an HTML file under the pages directory in your file structure. For each HTML page, you must also create a JSON file (with the same name) that controls whether the page is enabled or disabled.

For example, to deploy a password_reset page, you would create two files:

your-github-repo/pages/password_reset.html
your-github-repo/pages/password_reset.json

To enable the page, the password_reset.json would contain the following:

{
  "enabled": true
}

Was this helpful?/

The error_page cannot be enabled/disabled. To use the default error page, remove the content of error_page.html.

To deploy a rule, create a JavaScript file under the rules directory in your file structure. Each rule must be contained in its own JavaScript file. For each JavaScript file, you must also create a JSON file (with the same name) that controls the rule order, status, and stage during which the rule executes.

If you plan to use source control integration for an existing account, first rename your Rules in Auth0 to match the name of the files you will be deploying to this directory.

For example, to deploy a set-country rule, you would create two files:

your-github-repo/rules/set-country.js
your-github-repo/rules/set-country.json

set-country.js

function (user, context, callback) {
  if (context.request.geoip) {
    user.country = context.request.geoip.country_name;
  }
  callback(null, user, context);
}

Was this helpful?/

set-country.json

{
  "enabled": false,
  "order": 15,
  "stage": "login_success"
}

Was this helpful?/

To see an example for the login_success stage, visit the Auth0 Samples GitHub repository.

To avoid conflicts, multiple rules with the same order are not allowed. However, you can create a JSON file for each rule, and within each file, assign a value for order. We suggest using number values that allow for reordering with less risk of conflict. For example, assign a value of 10 to the first Rule and 20 to the second Rule, rather than using values of 1 and 2, respectively.

Once you deploy a rule, you cannot change the stage during which the rule executes. If you need the rule to execute during a different stage, you must create a new rule configured for that stage and delete the original rule.

The allowed values for the stage should be:

login_success
login_failure
pre_authorize

Only one rule may execute during the user_registration and login_failure stages.

See Create a Rule for details.

To deploy a rule config, create a JSON file under the rules-configs directory in your file structure. For example:

secret_number.json

{
  "key": "secret_number",
  "value": 42
}

Was this helpful?/

To deploy a client, create a JSON file under the clients directory in your file structure. For example:

my-client.json

{
  "name": "my-client"
}

Was this helpful?/

To learn more about allowed attributes for clients and client grants, see Auth0's Management API Post Clients endpoint.

To specify the client grants for each client, create a JSON file under the grants directory in your file structure. For example:

my-client-api.json

{
  "client_id": "my-client",
  "audience": "https://myapp.com/api/v1",
    "scope": [
      "read:users"
    ]
}

Was this helpful?/

The deployment extension accepts an application name instead of the client ID in the client_id property. It will try to match the name to an existing application before creating the Client Grant.

To deploy a resource server, create a JSON file under the resource-servers directory in your file structure. For example:

my-api.json

{
  "name": "my-api",
  "identifier": "https://myapp.com/api/v1",
  "scopes": [
    {
      "value": "read:users",
      "description": "Allows getting user information"
    }
  ]
}

Was this helpful?/

To learn more about allowed attributes for resource servers, see Auth0's Management API Post Resource Servers endpoint.

To deploy an email provider, create a provider.json file under the emails directory in your file structure. For example:

provider.json

{
    "name": "smtp",
    "enabled": true,
    "credentials": {
        "smtp_host": "smtp.server.com",
        "smtp_port": 25,
        "smtp_user": "smtp_user",
        "smtp_pass": "smtp_secret_password"
    }
}

Was this helpful?/

To learn more about allowed attributes for email providers, see Auth0's Management API Patch Provider endpoint.

Supported email templates include:

verify_email
reset_email
welcome_email
blocked_account
stolen_credentials
enrollment_email
mfa_oob_code

To deploy an email template, create an HTML file under the emails directory in your file structure. For each HTML file, you must also create a JSON file (with the same name) that contains additional options for that template.

For example, to deploy a blocked_account template, you would create two files:

your-github-repo/emails/blocked_account.html your-github-repo/emails/blocked_account.json

blocked_account.json

{
    "template": "blocked_account",
    "from": "",
    "subject": "",
    "resultUrl": "",
    "syntax": "liquid",
    "body": "./blocked_account.html",
    "urlLifetimeInSeconds": 432000,
    "enabled": true
}

Was this helpful?/

Docs