auth0-tools-cli

A CLI tool for managing Auth0 resources.

Table of Contents

• Description
• Getting Started
  • Install
    • npm
    • yarn
  • CLI Configuration
    • Environment Variables
    • Actions
• Usage
  • CLI

Description

auth0-tools-cli is a CLI tool that calls auth0-tools. Its goal is to simplify the management of various Auth0 resources, specifically geared at running commands locally and in scripts for CI/CD.

Currently, we support:

• Resource Servers (APIs)
• Clients (Apps)
• Actions

Getting Started

Install

npm

npm i -g @outlinerisk/auth0-tools-cli

yarn

yarn global add @outlinerisk/auth0-tools-cli

CLI Configuration

Environment Variables

You'll need to set a few values to secure a connection to Auth0's Management API:

Domain          // The domain of your Auth0 tenant.
Client ID       // The client ID of the Management API M2M app.
Client Secret   // The client secret of the Management API M2M app.
Name Prefix     // An optional prefix for the names of all your Auth0 resources.

You can pass these values in as optional arguments...

auth0-tools api deploy api_name api_audience --domain=domain --client-id=client_id --client-secret=client_secret

...but this can be tedious. Without these optional arguments, the CLI will default to the following environment variables:

process.env.AUTH0_DOMAIN
process.env.AUTH0_MANAGEMENT_CLIENT_ID
process.env.AUTH0_MANAGEMENT_CLIENT_SECRET
process.env.AUTH0_NAME_PREFIX

Actions

Check out the Auth0 documentation on actions to learn more.

To deploy actions, you'll need to provide JSON files that describes each action's properties.

# sample `action.json`

{
    "code": "\nexports.onExecuteCredentialsExchange = async (event, api) => {\n    const greeting = 'Hello World!'\n}",
    "name": "My Action",
    "runtime": "node16",
    "supported_triggers": [
        {
            "id": "post-login",
            "version": "v2"
        }
    ]
}

To do this, create a .auth0-toolrc configuration file. You must keep this file in your project root directory.

In the config file, create a actionsDir variable and set it to the path of your actions directory, relative to the project's root directory.

# project
# ├---actions
# |   |   action1.json
# |   |   action2.json
# |   ├---action3
# |   |       action3.json
# |   └---action4
# |           action4.json   
# ├---folder1
# ... 

# sample `.auth0-toolsrc`

actionsDir='./actions'

The CLI will recursively look within the actionsDir for all JSON files. Note that if you have any non-action JSON files in the actionsDir, the CLI will break.

It can be messy keeping code as a string. Instead of manually creating action.json files, we recommend creating Action objects, parsing them using a tool such as JSON.stringify(), then writing the JSON string to a JSON file.

// create the action as an Action object
const action: Action = {
    code: `
exports.onExecuteCredentialsExchange = async (event, api) => {
    const greeting = 'Hello World!'
}`,
    name: 'My Action',
    runtime: 'node16',
    supported_triggers: [
        {
            id: 'credentials-exchange',
            version: 'v2',
        },
    ],
}

// parse the action as a JSON string
const actionJSONString = JSON.stringify(action)

// write the JSON string to a JSON file
import fs from 'fs'
fs.writeFile('./action/action1/action1.json', actionJSONString, (err) => {
    if (err) throw err
})

Usage

CLI

auth0-tools help

Usage: main [options] [command]

Pathpoint's CLI tool for managing Auth0 resources.

Options:
  -V, --version   output the version number
  -h, --help      display help for command

Commands:
  action          Run action commands.
  api             Run API commands.
  app             Run app commands.
  help [command]  display help for command