Auth0 Token Vault Setup CLI

An interactive CLI tool to configure Auth0 Token Vault for your applications. This script automates the setup process for storing and managing external identity provider tokens securely with Auth0.

What is Token Vault?

Token Vault is an Auth0 feature that securely stores access and refresh tokens from external identity providers (like Google, GitHub, Microsoft, etc.) after users authenticate. This allows your application to:

• Store external provider tokens securely in Auth0
• Retrieve tokens on behalf of users without re-authentication
• Exchange Auth0 tokens for external provider tokens
• Manage multiple linked accounts per user

Features

• 🚀 Interactive setup wizard
• 🔐 Automatic configuration of applications, connections, and APIs
• 📦 Support for multiple Token Vault patterns
• ✅ Idempotent - safe to run multiple times
• 🐛 Debug mode for troubleshooting
• 📝 Detailed usage instructions after setup

Prerequisites

1. Node.js

• Node.js 18 or higher

2. Auth0 CLI

Install and configure the Auth0 CLI:

brew tap auth0/auth0-cli && brew install auth0

3. Auth0 Tenant

• An Auth0 tenant with admin access

4. Social or Enterprise Connection

You must configure at least one social or enterprise connection before running this script.

To create a connection:

1. Go to the Auth0 Dashboard
2. Navigate to Authentication → Social
3. Click Create Connection
4. Select your identity provider (e.g., Google, GitHub, Microsoft)
5. Configure the connection settings
6. Important: Set the connection purpose to one of:
   • Connected Accounts for Token Vault - If this connection will only be used for linking accounts
   • Authentication and Connected Accounts for Token Vault - If this connection will be used for both user login and account linking

Supported providers:

• Google, GitHub, LinkedIn, Microsoft, Facebook, Twitter
• Dropbox, Box, Salesforce, Fitbit, Slack, Spotify, Stripe
• Custom OAuth2 or OIDC connections

Note: The connection must support Token Vault. Most social and enterprise OAuth2/OIDC connections are compatible.

Usage

Run the interactive setup:

npx configure-auth0-token-vault

Or with debug logging:

DEBUG=true npx configure-auth0-token-vault
# or
npx configure-auth0-token-vault -- --debug

Supported Application Types

Token Vault requires confidential clients that can securely store client secrets. This script supports:

• ✅ Regular Web Applications - Web apps with a secure backend server
• ✅ Machine to Machine - Backend services, APIs, and worker applications

❌ Not supported: Single Page Applications (SPAs) and Native apps are public clients and cannot use Token Vault directly. If you need Token Vault functionality in an SPA or mobile app, you must proxy requests through a backend API.

Token Vault Flavors

The script supports four Token Vault configurations:

1. Connected Accounts

Use case: Allow users to link and manage multiple external accounts through your application UI.

What it configures:

• My Account API activation
• Client grants for Connected Accounts scopes
• Multi-Resource Refresh Token (MRRT) policies
• Connection settings

Example: A social media dashboard where users link their Twitter, Facebook, and Instagram accounts.

2. Refresh Token Exchange

Use case: Backend services that need to retrieve external provider tokens using Auth0 refresh tokens, without active user sessions.

What it configures:

• Everything from Connected Accounts
• Usage instructions for token exchange endpoint

Example: A scheduled job that posts to users' social media accounts on their behalf.

Token Exchange:

POST https://{your-domain}/oauth/token
Content-Type: application/json

{
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token": "<auth0_refresh_token>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:refresh_token",
  "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "connection": "google-oauth2",
  "client_id": "<your_client_id>",
  "client_secret": "<your_client_secret>"
}

3. Access Token Exchange

Use case: Backend APIs that exchange Auth0 access tokens for external provider tokens when handling user requests.

What it configures:

• Everything from Connected Accounts
• Optional Custom API Client creation
• Usage instructions for access token exchange

Example: An API endpoint that reads a user's Google Calendar events when they make a request.

Token Exchange:

POST https://{your-domain}/oauth/token
Content-Type: application/json

{
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token": "<auth0_access_token>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "connection": "google-oauth2",
  "client_id": "<custom_api_client_id>",
  "client_secret": "<custom_api_client_secret>"
}

4. Privileged Worker Token Exchange

Use case: Machine-to-machine applications that need to retrieve external provider tokens for specific users without active sessions.

What it configures:

• Everything from Connected Accounts
• Private Key JWT authentication setup
• Usage instructions for JWT bearer token exchange

Example: A background worker that syncs data from users' Dropbox accounts to your system.

Token Exchange:

POST https://{your-domain}/oauth/token
Content-Type: application/json

{
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token": "<signed_jwt>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "connection": "google-oauth2",
  "client_id": "<worker_client_id>",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "client_assertion": "<client_jwt>"
}

What Gets Configured

The script automatically configures:

Application Settings

• ✅ Token Vault grant type (urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token)
• ✅ First-party application status
• ✅ OIDC conformance
• ✅ Confidential client authentication
• ✅ Required grant types (authorization_code, refresh_token)

Connections

• ✅ Connected Accounts activation
• ✅ Application enablement

My Account API

• ✅ API creation/activation
• ✅ Connected Accounts scopes
• ✅ Access policy configuration (require_client_grant)

Client Grants

• ✅ User-type client grant with Connected Accounts scopes:
  • create:me:connected_accounts
  • read:me:connected_accounts
  • delete:me:connected_accounts

Multi-Resource Refresh Token (MRRT)

• ✅ MRRT policies for My Account API

Supported Connections

The script works with these identity providers:

• Google (google-oauth2)
• GitHub (github)
• LinkedIn (linkedin)
• Microsoft (microsoft)
• Facebook (facebook)
• Twitter (twitter)
• Dropbox (dropbox)
• Box (box)
• Salesforce (salesforce)
• Fitbit (fitbit)
• Slack (slack)
• Spotify (spotify)
• Stripe (stripe-connect)
• Custom OAuth2 (oauth2)
• Custom OIDC (oidc)

Troubleshooting

My Account API Not Found

If the script can't create the My Account API automatically, you'll need to activate it manually:

1. Go to Auth0 Dashboard → Applications → APIs
2. Look for the My Account API banner
3. Click Activate
4. Run the script again

Authentication Issues

If you see "insufficient scopes" errors:

auth0 login --scopes "read:clients,update:clients,create:clients,read:resource_servers,create:resource_servers,update:resource_servers,read:client_grants,create:client_grants,update:client_grants,read:connections,update:connections"

Debug Mode

Enable debug logging to see detailed API calls:

DEBUG=true npm start

Security Considerations

• Confidential clients only: Token Vault requires confidential clients (Regular Web Applications or Machine-to-Machine). Public clients like SPAs or Native apps cannot use Token Vault directly without a backend proxy.
• Never commit credentials: The script displays client secrets - store them securely
• Refresh token rotation: The script does NOT enable refresh token rotation (as Token Vault doesn't support it)
• MFA policy: Token Vault requires MFA policy to NOT be "Always"

Resources

• Token Vault Documentation
• Connected Accounts
• Refresh Token Exchange
• Access Token Exchange
• Privileged Worker
• Auth0 CLI Documentation

License

MIT