CheckMate for Auth0

CheckMate for Auth0 is a command-line utility that performs configuration checks on your Auth0 tenant. It helps ensure your tenant is securely and correctly configured by validating key settings and generating a detailed report.

🚀 Features

• Validates your Auth0 tenant configuration
• Generates comprehensive audit reports
• Simple and intuitive CLI interface

⚠️ Auth0 Management API Use Notice

This tool makes use of the Auth0 Management API, which consumes your tenant’s rate limits. Use it thoughtfully to avoid throttling.

CheckMate for Auth0 is designed to provide visibility into its behavior through your Auth0 tenant's log events. Tracking its use is important for monitoring and debugging purposes. You can track its use in several ways, including:

• The User-Agent string in the HTTP request header, which will have a value in the form of ${packageName}/${packageVersion} (e.g. @auth0/auth0-checkmate/1.4.0). Keep in mind that if the User-Agent string is modified on the client side, then CheckMate for Auth0 usage cannot be tracked this way.
• The client_name and scopes assigned to CheckMate when configuring initial access
• seccft events (Successful exchange of Access Token for a Client Credentials Grant) in Auth0 logs

As an example, CheckMate activity might result in a log entry like the one shown below. Each field in the log entry provides valuable information for troubleshooting or auditing, such as the client_name identifying the application, the scope showing granted permissions, and the user_agent indicating the tool version used.

{
  "date": "2025-08-05T19:19:43.071Z",
  "type": "seccft",
  "description": "Client Credentials for Access Token",
  "connection_id": "",
  "client_id": "{CHECKMATE_CLIENT_ID}",
  "client_name": "{CHECKMATE_CLIENT_NAME}",
  "ip": "{REQUEST_IP}",
  "client_ip": "{REQUEST_IP}",
  "user_agent": "{CHECKMATE_USER_AGENT}",
  "hostname": "{TENANT_HOSTNAME}",
  "user_id": "",
  "user_name": "",
  "audience": "https://{TENANT_HOSTNAME}/api/v2/",
  "scope": "{CHECKMATE_SCOPES}",
  "$event_schema": {
    "version": "1.0.0"
  },
  "environment_name": "{AUTH0_ENVIRONMENT}",
  "log_id": "{LOG_ID}",
  "tenant_name": "{AUTH0_TENANT}",
  "_id": "{ID}",
  "isMobile": false,
  "location_info": {},
  "id": "{ID}"
}

📦 Prerequisites

• Node.js v22.12.0 or higher
• A valid Auth0 tenant

🛠️ Installation Options

Option 1 – Global Installation

Install CheckMate for Auth0 globally to use it as a standalone CLI tool:

npm install -g @auth0/auth0-checkmate

Then run it with:

a0checkmate

Follow the interactive prompts to get started.

To update CheckMate:

npm update -g @auth0/auth0-checkmate

Option 2 – Run from Source

1. Clone the repository:

   git clone https://github.com/auth0/auth0-checkmate
   

2. Navigate into the project folder:

   cd auth0-checkmate
   

3. Install dependencies:

   npm install
   

4. Run the tool:

   npm start
   

🔐 Auth0 Setup Instructions

To use CheckMate for Auth0, you need a dedicated Auth0 Application to authorize calls to the Management API.

Create a Machine-to-Machine Application

1. In the Auth0 Dashboard, go to: Applications → Applications

2. Click “Create Application”

3. In the setup form:

   • Name: Auth0 CheckMate (or similar)
   • Application Type: Machine to Machine Applications
   • Click “Create”

4. On the "Authorize Machine to Machine Application" screen:

   • Select Auth0 Management API
   • Grant only the following scopes:

   read:tenant_settings
   read:custom_domains
   read:prompts
   read:clients
   read:connections
   read:connections_options
   read:resource_servers
   read:client_grants
   read:roles
   read:branding
   read:email_provider
   read:email_templates
   read:phone_providers
   read:phone_templates
   read:shields
   read:attack_protection
   read:self_service_profiles
   read:guardian_factors
   read:mfa_policies
   read:actions
   read:log_streams
   read:logs
   read:network_acls
   read:event_streams
   read:hooks
   read:rules
   

5. Click “Authorize” to complete setup.

6. Optional: the following environment variables can be used to provide a CI friendly configuration

    AUTH0CHECKMATE_DISABLE_PDF_REPORTING=true|false
    AUTH0CHECKMATE_DOMAIN=your_domain
    AUTH0CHECKMATE_CLIENT_ID=your_client_id
    AUTH0CHECKMATE_CLIENT_SECRET=your_client_secret
    AUTH0CHECKMATE_FILE_PATH="./reports"
    AUTH0CHECKMATE_SHOW_VALIDATORS=false
    AUTH0CHECKMATE_SKIP_APPLICATIONS=true|false
    RUN_VALIDATORS=checkCustomDomain,checkRules
   

   Note: Tenants with more than 1,500 applications skip application (client) checks; fetching stops once the limit is exceeded and all other checks still run.

🎯 Running a Subset of Validators

By default every validator runs. Set RUN_VALIDATORS to a comma-separated list of validator names to run only those checks — useful for iterating on a single finding or keeping CI runs fast.

RUN_VALIDATORS=checkCustomDomain,checkRules a0checkmate

To print the available validator names and exit:

RUN_VALIDATORS=list a0checkmate

Notes:

• Names are case-sensitive and must match exactly. An unrecognized name stops the run before authenticating and suggests the closest match, rather than producing a report that silently checked nothing.
• Surrounding whitespace, duplicates and trailing commas are ignored, so RUN_VALIDATORS=" checkRules, checkCustomDomain, " is valid.
• Leave the variable unset (or empty) to run all validators.
• The tenant configuration is still fetched in full. RUN_VALIDATORS controls which validators run, not which data is retrieved.

✅ You're All Set

With your Auth0 application configured and the CLI installed, you’re ready to run CheckMate for Auth0 and ensure your tenant setup is secure and complete.