auth0-tools

A package for managing Auth0 resources.

Table of Contents

• Description
• Getting Started
  • Install
    • npm
    • yarn
  • Build
    • npm
• Usage
  • Management Client
    • Creating a Client
    • Resource Name Prefixes
    • Enforcing Unique Resource Names

Description

auth0-tools is a tool that wraps Auth0's ManagementClient, which is used to interact with the Management API. Its goal is to simplify the management of various Auth0 resources. To do this, auth0-tools provides clients with generalized functions that make it easier to deploy resources with custom properties while enforcing rules such as unique resource names.

For a CLI tool that wraps this package, check out auth0-tools-cli.

Currently, we support:

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

Getting Started

Install

npm

npm i @outlinerisk/auth0-tools

yarn

yarn add @outlinerisk/auth0-tools

Build

npm

npm run build

Usage

Management Client

Creating a Client

import { APIClient } from '@outlinerisk/auth0-tools'

const domain = process.env.AUTH0_DOMAIN
const clientId = process.env.AUTH0_MANAGEMENT_CLIENT_ID
const clientSecret = process.env.AUTH0_MANAGEMENT_CLIENT_SECRET
const apiClient = new APIClient(domain, clientId, clientSecret)

const apiName = 'My API'
const apiAudience = 'https://my-website.com/my/api'
await apiClient.deployAPI(apiName, apiAudience)

Resource Name Prefixes

Passing a prefix to any client constructor will prepend all resources for that client with the prefix.

import { AppClient } from '@outlinerisk/auth0-tools'

const domain = process.env.AUTH0_DOMAIN
const clientId = process.env.AUTH0_MANAGEMENT_CLIENT_ID
const clientSecret = process.env.AUTH0_MANAGEMENT_CLIENT_SECRET
const prefix = 'dev'
const appClient = new AppClient(domain, clientId, clientSecret, prefix)

const appName = 'My App'
const clientSecret = 'TotallyLegitSecret'
await appClient.deployM2MApp(appName, clientSecret) // spins up a m2m app named 'dev-My App'

Enforcing Unique Resource Names

While names are not the unique identifiers for resources, they are the easiest property to identify resources with. As such, we believe that resources should have unique names to make the management of resources clearer. auth0-tools enforces this ideology by applying unique name constraints to all resources within a given type. That is, no API can share the same name, nor can any app, but an API and an app can share the same name, though we wouldn't recommend that either.

import { APIClient } from '@outlinerisk/auth0-tools'

const domain = process.env.AUTH0_DOMAIN
const clientId = process.env.AUTH0_MANAGEMENT_CLIENT_ID
const clientSecret = process.env.AUTH0_MANAGEMENT_CLIENT_SECRET
const apiClient = new APIClient(domain, clientId, clientSecret)

const apiName = 'My API'
const apiAudience = 'https://my-website.com/my/api'
await apiClient.deployAPI(apiName, apiAudience)         // successfully deploys 'My API'

const apiAudience2 = 'https://my-website.com/my/api/2'
await apiClient.deployAPI(apiName, apiAudience2)        // while valid within Auth0, auth0-tools throws an error

Note that while Auth0 does allow for resources to share names, there are complications. For instance, if you have multiple APIs deployed with the same name, you cannot manually delete the APIs with shared names in the web console--the delete button becomes grayed out. You'd have to change the names of the APIs until they are all unique, then delete them.