auth0-deploy-cli
Advanced tools
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.
npm i -g auth0-deploy-cli
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.
Use the Auth0 Deploy CLI Extension to Create a client. At the bottom of the README are instructions for doing this by hand instead.
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"
]
}
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,
...
}
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.
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
rules
rule1.js
rule1.json
rule2.js
pages
login.html
login.json
password_reset.html
password_reset.json
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"
]
}
}
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.
See Database Connection configuration here
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.
See Custom Pages configuration here
a0deploy [ options ]
-h, --help output usage information
-v,--verbose Dump extra debug information.
-i,--input_dir <input directory> The directory where you checked out the repository. See 'Organize your repository'.
-c,--config_file <config file> The JSON configuration file. See JSON Format for more information.
-p,--proxy <proxy> The proxy URL if behind a proxied firewall. e.g. http://192.168.2.24:8080
-s,--state_file <state file> A file for persisting state between runs. Default: ./local/state
-x,--secret <the client secret> This allows you to create a configuration file that does not include a secret
and instead store that secret encrypted in your build system and pass it on the
command line. Please beware that this may log that secret somewhere, so you may
need to cleanse your logs. You can also set the AUTH0_CLIENT_SECRET in the
environment.
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.
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 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 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:
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.
Clone the github repo and install globally
git clone git@github.com:auth0/auth0-deploy-cli
cd auth0-deploy-cli
npm install
npm run test
log into your dashboard
click the clients tab
click the "New Client" button
If you haven't already enabled API's, you may have to toggle the switch to enable API's
Use the "Select an API" dropdown to choose: "Auth0 Management API"
Click the Settings tab
Copy the client ID, you'll need it for a couple steps down
Click the "Documentation->Management API" link from the top menu
Using the left navigation click "Client Grants" then "Create a client grant"
Click the "create:client_grants" scope to create the token
In the Body section put the following:
{
"client_id": "<your client ID copied above>",
"audience": "https://<your domain: (e.g. fabrikam-dev.auth0.com)>/api/v2/",
"scope": [
"read:client_grants",
"create:client_grants",
"delete:client_grants",
"update:client_grants",
"read:clients",
"update:clients",
"delete:clients",
"create:clients",
"read:connections",
"update:connections",
"read:resource_servers",
"update:resource_servers",
"delete:resource_servers",
"create:resource_servers",
"read:rules",
"update:rules",
"delete:rules",
"create:rules",
"read:tenant_settings",
"update:tenant_settings"
]
}
Click the "Try" button
See https://github.com/auth0/auth0-deploy-cli/issues
MIT
FAQs
A command line tool for deploying updates to your Auth0 tenant
The npm package auth0-deploy-cli receives a total of 23,730 weekly downloads. As such, auth0-deploy-cli popularity was classified as popular.
We found that auth0-deploy-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.