
Support
This integration is community supported. Learn more
Azure Pipelines
Use the Auth0 Deploy CLI with Azure Pipelines to manage Auth0
The Azure Pipelines supports automatically build and test of code projects to make them available to others. It works with just about any language or project type. Azure Pipelines combines continuous integration (CI) and continuous delivery (CD) to constantly and consistently test and build your code and ship it to any target.
The Auth0 Deploy CLI provides the ability to manage your Auth0 configuration from CLI and can easily be integrated into a Azure Pipeline. Instead of working through a UI, you can create, update, and manage your Auth0 applications, APIs, and more through code stored in a Git repository on Azure Cloud, managed by Auth0 Deploy CLI, and automated by Azure Pipelines.
Support
This integration is community supported. Learn more
Prerequisites
Before you get started, you'll need:
- An Auth0 account. You can sign up for free.
- An Azure account. You can sign up for free.
- A local development environment with tools including Git for source version control, and Node.js and
npm
to install and run the Auth0 Deploy CLI locally.
Configuring your Auth0 tenants
When building applications using Auth0, we recommend creating a dedicated Auth0 tenant per environment. Doing so allows you to isolate your production user base from your other environments and configure different administrators per environment (e.g., engineers might not have access to production configuration).
In this guide, we'll have three different Auth0 tenants:
- zerohr-dev.us.auth0.com: Tenant used by developers. This is where manual changes happen.
- zerohr-staging.us.auth0.com: Tenant used by the Product Manager and QA team.
- zerohr-prod.us.auth0.com: Tenant used by end users/customers.
The Auth0 Deploy CLI will need the client_id
and client_secret
credentials to get access to the Management API for each of the tenants. Please install and configure the Auth0 Deploy CLI and retrieve the credentials before moving on to the next step.
Initial export
Once we have the client credentials for the development tenant, we can use the Auth0 Deploy CLI to perform an initial export.
Let's start by creating a config file, which contains the client_id
and client_secret
in the development tenant. We can use the EXCLUDED_PROPS
setting to avoid exporting any secrets:
{
"AUTH0_DOMAIN": "zerohr-dev.us.auth0.com",
"AUTH0_CLIENT_ID": "fU8QR25rCTR8k7RhhURNqzUE0sBtJTSR",
"AUTH0_CLIENT_SECRET": "...",
"EXCLUDED_PROPS": {
"clients": ["client_secret"],
"connections": ["options.client_secret"]
}
}
Then create a directory, initialize it as a Git repo, and run the a0deploy
command to export your Auth0 configurations:
$ mkdir azure-pipelines-auth0-deploy
$ cd azure-pipelines-auth0-deploy
$ git init
$ a0deploy export -c config.json --strip --format yaml --output_folder .
The last command (a0deploy export
) calls the Auth0 Deploy CLI, which will iterate over all the resources in our Auth0 tenant and export them to a single yaml
file, and create some files for additional assets in the tenant (for example, a *.js
file for each of your rules and hooks).
The following is an excerpt that demonstrates what such an exported tenant.yaml
configuration file could look like:
rules:
- name: custom-claims
script: ./rules/custom-claims.js
stage: login_success
enabled: true
order: 1
resourceServers:
- name: ZeroHR API
identifier: 'https://api.dev.zerohr.app/'
allow_offline_access: false
signing_alg: RS256
skip_consent_for_verifiable_first_party_clients: true
token_lifetime: 86400
token_lifetime_for_web: 7200
Moving to Azure
We now have everything we need to create an Azure repository containing the following:
- The configuration for dev/staging/production
- The
yaml
file, and the other files created by the Auth0 Deploy CLI - The Azure Pipelines
We'll also create a dedicated config
folder containing all the configuration files:
./config/dev.json
./config/prod.json
./config/staging.json
Each configuration file will contain the domain and the client_id
. Note that the client_secret
should not be added here; we'll manage that using Azure Pipelines secret variables, not directly in source control.
{
"AUTH0_DOMAIN": "zerohr-staging.us.auth0.com",
"AUTH0_CLIENT_ID": "Y13eh0EhojdF1Bti06FLJJ1jZx0Pb0hJ",
"AUTH0_ALLOW_DELETE": true,
"AUTH0_KEYWORD_REPLACE_MAPPINGS": {
"APP_CALLBACKS": ["https://www.staging.zerohr.app", "https://staging.zerohr.app"],
"API_IDENTIFIER": "https://api.staging.zerohr.app/"
},
"EXCLUDED_PROPS": {
"clients": ["client_secret"],
"connections": ["options.client_secret"]
}
}
Also notice AUTH0_KEYWORD_REPLACE_MAPPINGS
, which allows us to include environment-specific settings that will be injected into the yaml
file. This can be useful if, for example, the applications in our environments have different URLs. The URLs can be managed here and then injected into the template as we deploy to a specific environment.
For this to work, we need to modify the yaml
file and replace the actual values of the URLs with variables. The ##var##
format will be replaced with a string literal, the @@var@@
format with a JSON representation of the variable (in this case, an actual array). Below is an example of the tenant.yaml
configuration file with the mapping enabled:
resourceServers:
- name: ZeroHR API
identifier: '##API_IDENTIFIER##'
allow_offline_access: false
signing_alg: RS256
skip_consent_for_verifiable_first_party_clients: true
token_lifetime: 86400
token_lifetime_for_web: 7200
clients:
- name: ZeroHR App
app_type: spa
callbacks: @@APP_CALLBACKS@@
client_aliases: []
cross_origin_auth: false
custom_login_page_on: true
grant_types:
- authorization_code
- refresh_token
is_first_party: true
You can read more about how environment variables and keyword mappings work with the Auth0 Deploy CLI in the Auth0 Deploy CLI documentation.
Azure Pipelines and Continuous Delivery
To make local testing easier, we can move the a0deploy
commands to a package.json
file:
{
"scripts": {
"export:dev": "a0deploy export --strip --format yaml --output_folder . --config_file ./config/dev.json",
"import:dev": "a0deploy import --input_file tenant.yaml --config_file ./config/dev.json",
"import:staging": "a0deploy import --input_file tenant.yaml --config_file ./config/staging.json",
"import:prod": "a0deploy import --input_file tenant.yaml --config_file ./config/prod.json"
}
}
This will allow us to use npm run import:prod
, for example, to import and deploy the configurations for the prod
environment.
We'll then create an Azure Pipelines YAML file for each environment to install and run the Auth0 Deploy CLI.
For example, we create a file named azure-pipeline-staging.yml
with the following content for the staging
environment:
trigger:
- staging
jobs:
- job: staging
displayName: 'Import changes to the Auth0 staging account'
pool:
vmImage: 'ubuntu-latest'
steps:
- task: NodeTool@0
inputs:
versionSpec: '14.x'
displayName: 'Install Node.js'
- script: |
npm install -g auth0-deploy-cli
displayName: 'Install Auth0 Deploy CLI'
- script: |
npm run import:staging
env:
AUTH0_CLIENT_SECRET: $(AUTH0_CLIENT_SECRET)
displayName: 'Importing changes'
As a final step, we will create the pipeline from Azure Pipelines Portal UI by selecting the above file as an existing Azure Pipelines YAML file:
The Auth0 Deploy CLI will need to use the client_id
and client_secret
for the given environment to access the Management API, which is used to create/update/delete resources. The client_secret
is aptly named--it is a secret and should not be stored in source control. So for each pipeline, we'll create a secret variable to store the client_secret
:
Deployment
The pipeline will run whenever there is a push to the branches dev
, staging
, and prod
. As a simple test, we can modify one setting in our Auth0 configuration and push the change to the staging branch:
$ git checkout -b staging
$ git add tenant.yaml
$ git commit -m "chore: multiple environment support"
$ git push -u origin staging
Immediately after pushing the change, we can see that a new run has started:
Further reading and documentation
Support
This integration is community supported. Learn more