npm package: @outlinerisk/auth0-tools
Description: Pathpoint's internal Auth0 tooling.
Author: Pathpoint
Latest version: 0.1.20

# auth0-tools

A package for managing Auth0 resources.

# Table of Contents
- [Description](#description)
- [Getting Started](#getting-started)
    - [Install](#install)
        - [npm](#npm)
        - [yarn](#yarn)
    - [Build](#build)
        - [npm](#npm-1)
- [Usage](#usage)
  - [Management Client](#management-client)
    - [Creating a Client](#creating-a-client)
    - [Resource Name Prefixes](#resource-name-prefixes)
    - [Enforcing Unique Resource Names](#enforcing-unique-resource-names)

# Description

auth0-tools is a tool that wraps [Auth0's ManagementClient](https://auth0.github.io/node-auth0/ManagementClient.html), which is used to interact with the [Management API](https://auth0.com/docs/api/management/v2/). 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](https://github.com/outline-insurance/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.