Azure Pipelines

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.

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

• Auth0 Deploy CLI Tool
• Azure Pipelines