Auth0 Deploy CLI

There are a few good extensions that you can use to deploy updates automatically. This tool utilizes that same code base to allow anyone to pass json to this tool and deploy to your tenant. This allows you to call this from any tool that can call node. The intention is to allow deploy from any source code repository and incorporate in any build script.

Install

General Install

npm i -g auth0-deploy-cli

Usage

Create a client in your Auth0 Account

You must create a client in your service account that has access to the management API with the following scopes before you can configure the a0deploy CLI.

Scopes

read:tenant_settings
update:tenant_settings
create:client_grants
read:client_grants
update:client_grants
delete:client_grants
create:clients
read:clients
update:clients
delete:clients
read:connections
update:connections
create:resource_servers
read:resource_servers
update:resource_servers
delete:resource_servers
read:rules
create:rules
update:rules
delete:rules

Client Creation Steps

Use the Auth0 Deploy CLI Extension to Create a client. At the bottom of the README are instructions for doing this by hand instead.

Create Your Config File

The config file will need the client ID and secret from your newly created client (the client is named auth0-deploy-cli-extension if you used the extension). You can place this anywhere on the filesystem. Here is the example:

{
  "SLACK_INCOMING_WEBHOOK_URL": "<your webhook URL from slack, just leave this out if you are not using slack>",
  "AUTH0_DOMAIN": "<your auth0 domain (e.g. fabrikam-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_EXCLUDED_RULES": [
    "rule-1-name",
    "rule-2-name"
  ]
}

AUTH0_KEYWORD_REPLACE_MAPPINGS

The mappings are there so that you can use the same configuration file for all of your environments (e.g. dev, uat, staging, and prod) without having to have different versions of the files for each environment. The mappings allow you to replace certain values in your configuration repo with envrionment specic values. There are two ways to use the keyword mappings. You can either wrap the key in @@key@@ or ##key##. If you use the @ symbols, it will do a JSON.stringify on your value before replacing it. So if it is a string it will add quotes, if it is an array or object it will add braces. If you use the # symbol instead, till just do a literal replacement. It will not add quotes or brackets.

For example, you could specify a different JWT timeout in your dev environment then prod for testing and a different environment URL:

Client .json:

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

Dev Config .json:

  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "ENVIRONMENT_URL": "http://dev.fabrikam.com",
    "JWT_TIMEOUT": 120,
    ...
  }

Prod Config .json:

  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "ENVIRONMENT_URL": "http://fabrikam.com",
    "JWT_TIMEOUT": 3600,
    ...
  }

AUTH0_EXCLUDED_RULES

This is a list of rule names that should be ignored by the deploy CLI. It will not delete, update or create rules that match those names.

Organize your repository

There is more extensive documentation online for how the files are expected to be laid out to work with the source control configuration utilities here.

If you already have an existing tenant, you can dump your configuration in the right format using the auth0-dump-config.

Here is a simple overview:

repository => 
  clients
    client1-name.json
    client1-name.meta.json # if specifying client grants
    my-other-client-name.json
  resource-servers
    resource server 1.json
    some other resource server.json
  database-connections
    my-connection-name
      get_user.js
      login.js
      configuration.json
  rules
    rule1.js
    rule1.json
    rule2.js
  pages
    login.html
    login.json
    password_reset.html
    password_reset.json
  email-templates
    verify_email.html
    verify_email.json
  email-providers
    default.json

Clients

The name of the file is the name of the client that is created or updated.

In the .json file you can put the same json you would put when using the Management API for creating clients. It will only try to keep the fields specified inline with what is configured already. If a client doesn't exist yet, it will create it.

To specify client grants, you must specify the following in the metadata file. (e.g. client1-name.meta.json)

{
  "grants": {
    "Resource server audience": [
      "scope1",
      "scope2"
    ]
  }
}

Resource servers

The name of the file is the name of the resource server that is created or updated.

In the .json file you can put the same json you would put when using the Management API for creating resource servers. It will only try to keep the fields specified inline with what is configured already. If a resource server doesn't exist yet, it will create it.

Database Connections

See Database Connection configuration here

If the special file named configuration.json exists for a connection, it is assumed to contain options and metadata that will be used when updating the connection.

Rules

See Rules configuration here

NOTE: There is not currently a way to mark rules as manual yet, that will become part of the configuration file in the future.

Custom Pages

See Custom Pages configuration here

Email templates

An email template consists of two files, an HTML file that contains the body of the template, and a JSON file that contains metadata. The name of each file should be the name of the template to update, e.g. verify_email.

See the management API documentation for information about which metadata can be used, though properties template and body will be ignored.

Email providers

There can currently only be a single email provider. The name of the configuration file should be default.json.

See the management API documentation for information about which configuration can be used. Note that the name property contains the provider type and should not be confused with the name of the file.

Command Line Options

a0deploy [options]

  Options:

    -v,--verbose                    Dump extra debug information.
    -i,--input_file <input file>    The updates to deploy.  Either a JSON file, or directory that contains the correct file layout.  See README and online for more info.
    -c,--config_file <config file>  The JSON configuration file.
    -s,--state_file <state file>    A file for persisting state between runs.  Default: ./local/state
    -p,--proxy_url <proxy_url>      A url for proxying requests, only set this if you are behind a proxy.
    -x,--secret <secret>            The client secret, this allows you to encrypt the secret in your build configuration instead of storing it in a config file
    -h, --help                      output usage information

Recommended Approach/Best Practices

The recommended approach for utilizing this CLI is to incorporate it into your build system. Create a repository to store your deploy configuration, then create a set of configuration files for each environment. On your continuous integration server, have a deploy build for each environemnt. This deploy build should update a local copy of the deploy configuration repository, then run the CLI to deploy it to that environment. Read on for more detailed information.

Auth0 Tenant layout

The recommended approach is to have a different Auth0 tenant/account for each environment. For example: fabrikam-dev, fabrikam-uat, fabrikam-staging, and fabrikam-prod.

Your Deploy Configuration Repository

Your configuration repository should contain the files as described in the Organize Your Repository section above.

You should have a branch for each tenant/account. This allows you to make changes to dev, but not deploy them until you merge. With this setup, you can have each environment have a CI task that automatically deploys the changes to its target environment when the branch is updated with the latest.

So your flow would be as follows: dev changes are tested, then merged to uat, once tested they are merged to staging, once staging is tested they are merged to prod.

You may want to set your prod to only deploy when triggered manually.

Your CI server configuration

Your CI server should have a different deploy task and config.json for each environment. Since each tenant/account will need to have the auth0-deploy-cli-extension installed in it with a different domain, client ID, and secret, this has to happen anyway and will avoid accidentally deploying to the wrong environment.

The deploy task should follow these steps:

Update the local repo to the latest. (each environment should have its own copy of the repo set to its own branch)
If there are changes, call a0deploy
Run a suite of tests to confirm configuration is working
Optional: merge to next branch

Use keyword mappings to handle differences between the environments

You should not have to store differences between environments in the Deploy Configuration Repository. Use the keyword mappings to allow the repository to be environment agnostic, and instead store the differences in the separate config.json files for each environment that are stored on the CI server.

Known issues

See https://github.com/auth0/auth0-deploy-cli/issues

License

MIT

factor10 / auth0-deploy-cli