How to Configure Client Signing Key Path and Algorithm in Auth0 Deploy CLI

TLDR: The Auth0 Deploy CLI supports RS256, RS384, and PS256 signing algorithms configured via AUTH0_CLIENT_SIGNING_KEY_PATH and AUTH0_CLIENT_SIGNING_ALGORITHM properties for Private Key JWT authentication to the Management API.

The auth0/auth0-deploy-cli repository provides tools to manage Auth0 tenant configurations as code. When authenticating to the Auth0 Management API using Private Key JWT, you must specify the client signing key path and algorithm. This guide explains the available options and their implementation in the source code.

Configuration Properties for Private Key JWT

The CLI accepts two specific environment variables or configuration file properties to enable Private Key JWT authentication.

AUTH0_CLIENT_SIGNING_KEY_PATH

The AUTH0_CLIENT_SIGNING_KEY_PATH property specifies the filesystem path to your private key file. According to the type definitions in src/types.ts (line 61), this is declared as a string representing a path relative to the working directory.

In src/context/index.ts (lines 176-199), the runtime validation logic ensures that either AUTH0_CLIENT_SECRET or AUTH0_CLIENT_SIGNING_KEY_PATH is provided. When the signing key path is supplied, the CLI uses fs.readFileSync to load the key content for JWT signing.

AUTH0_CLIENT_SIGNING_ALGORITHM

The AUTH0_CLIENT_SIGNING_ALGORITHM property defines the JWT signing algorithm. As documented in docs/configuring-the-deploy-cli.md (lines 77-84), the accepted values are:

• RS256 (default when omitted)
• RS384
• PS256

This property must be supplied together with AUTH0_CLIENT_SIGNING_KEY_PATH to configure the signing behavior correctly.

Implementation in the Source Code

The authentication flow is implemented across several key files in the auth0/auth0-deploy-cli repository.

In src/context/index.ts, the validation logic checks for the presence of credentials and loads the key:

if (!AUTH0_CLIENT_SECRET && !AUTH0_CLIENT_SIGNING_KEY_PATH) {
  throw new ValidationError(
    'You need to supply either `AUTH0_ACCESS_TOKEN`, `AUTH0_CLIENT_SECRET` or `AUTH0_CLIENT_SIGNING_KEY_PATH`'
  );
}

// Load the private key for JWT signing
const clientAssertionSigningKey = readFileSync(AUTH0_CLIENT_SIGNING_KEY_PATH, 'utf8');

The type definition in src/types.ts declares AUTH0_CLIENT_SIGNING_KEY_PATH as a string, ensuring type safety during configuration loading.

Configuration Examples

You can configure these options via JSON configuration files or environment variables.

JSON Configuration

Create a config.json file with the following structure:

{
  "AUTH0_DOMAIN": "my-tenant.auth0.com",
  "AUTH0_CLIENT_ID": "abc123",
  "AUTH0_CLIENT_SIGNING_KEY_PATH": "./keys/auth0-client.pem",
  "AUTH0_CLIENT_SIGNING_ALGORITHM": "RS384"
}

Environment Variables

Alternatively, export the variables in your shell:

export AUTH0_DOMAIN="my-tenant.auth0.com"
export AUTH0_CLIENT_ID="abc123"
export AUTH0_CLIENT_SIGNING_KEY_PATH="./keys/auth0-client.pem"
export AUTH0_CLIENT_SIGNING_ALGORITHM="PS256"

Supported Signing Algorithms

The CLI supports three RSA-based algorithms for Private Key JWT authentication:

1. RS256 - RSA with SHA-256 (default algorithm when AUTH0_CLIENT_SIGNING_ALGORITHM is not specified)
2. RS384 - RSA with SHA-384
3. PS256 - RSASSA-PSS with SHA-256 using MGF1 with SHA-256

These algorithms conform to the RSA standards required by Auth0's Management API for client assertion JWTs.

Summary

• The AUTH0_CLIENT_SIGNING_KEY_PATH property accepts a string path to your private key file relative to the working directory.
• The AUTH0_CLIENT_SIGNING_ALGORITHM property accepts RS256, RS384, or PS256, defaulting to RS256 when omitted.
• The CLI validates that either AUTH0_CLIENT_SECRET or AUTH0_CLIENT_SIGNING_KEY_PATH is present in src/context/index.ts.
• Private keys are loaded synchronously using fs.readFileSync during context initialization.

Frequently Asked Questions

What happens if I don't specify AUTH0_CLIENT_SIGNING_ALGORITHM?

If you omit the AUTH0_CLIENT_SIGNING_ALGORITHM property, the Auth0 Deploy CLI defaults to RS256. This is the most widely supported RSA algorithm and works with standard RSA private keys in PEM format.

Can I use both AUTH0_CLIENT_SECRET and AUTH0_CLIENT_SIGNING_KEY_PATH together?

No, you should provide only one authentication method. The validation logic in src/context/index.ts requires either AUTH0_CLIENT_SECRET (for client secret authentication) or AUTH0_CLIENT_SIGNING_KEY_PATH (for Private Key JWT), but not both simultaneously. Using both may cause authentication conflicts.

What file format should the private key be in?

The private key file must contain a valid RSA private key in PEM format. The CLI reads the file using fs.readFileSync with UTF-8 encoding, so the file should be a text-based PEM file containing the BEGIN RSA PRIVATE KEY or BEGIN PRIVATE KEY headers and Base64-encoded key data.

Where is the algorithm validation documented?

The accepted values for AUTH0_CLIENT_SIGNING_ALGORITHM are documented in docs/configuring-the-deploy-cli.md (lines 77-84) in the repository. The source code uses these values to configure the JWT signing mechanism when creating the client assertion for Auth0's Management API.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}