GitLab Pipelines

GitLab is a web-based DevOps lifecycle tool that provides a Git-repository manager providing wiki, issue-tracking and continuous integration and deployment pipeline features, using an open-source license, developed by GitLab Inc.

The Auth0 Deploy CLI provides the ability to manage your Auth0 configuration from CLI and can easily be integrated into a GitHub Action. 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 GitHub, managed by Auth0 Deploy CLI, and automated by GitHub Actions.

Prerequisites

Before you get started, you'll need:

• An Auth0 account. You can sign up for free.
• A GitLab 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 gitlab-pipelines-auth0-deploy
$ cd gitlab-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 GitLab

We now have everything we need to create a GitLab repository containing the following:

• The configuration for dev/staging/production
• The yaml file, and the other files created by the Auth0 Deploy CLI
• The GitLab Pipelines jobs

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 GitLab CI/CD environment 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.

GitLab 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.

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 environment, we'll create a GitLab CI/CD Environment in the repository and add a GitLab CI/CD environment variable to store the client_secret scoped for each environment.

For example, two environments named staging and prod are created as below:

In addition, for the staging environment, a variable AUTH0_CLIENT_SECRET is created:

As a final step, we'll create a GitLab CI configuration file .gitlab-ci.yml in the repository to install and run the Auth0 Deploy CLI as shown in the example below:

image: node:14

# This folder is cached between builds
# http://docs.gitlab.com/ee/ci/yaml/README.html#cache
cache:
  paths:
    - node_modules/

dev:
  only:
    - dev
    # Run this job when commits are pushed or merged to the dev branch
  script:
    - npm install -g auth0-deploy-cli
    - npm run import:dev

staging:
  only:
    - staging
    # Run this job when commits are pushed or merged to the staging branch
  environment:
    name: staging
  script:
    - npm install -g auth0-deploy-cli
    - npm run import:staging

production:
  only:
    - prod
    # Run this job when commits are pushed or merged to the prod branch
  environment:
    name: prod
  script:
    - npm install -g auth0-deploy-cli
    - npm run import:prod

Please refer to Get started with GitLab CI/CD for more details on GitLab Pipelines.

Deployment

The GitLab Pipelines 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 job for the staging environment has started:

Further reading and documentation

• Auth0 Deploy CLI Tool
• Get started with GitLab CI/CD