@auth0/auth0-checkmate

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 v20.18.3 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

• Clone the repository:

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

• Navigate into the project folder:

  cd auth0-checkmate
  

• Install dependencies:

  npm install
  

• 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

• In the Auth0 Dashboard, go to: Applications → Applications

• Click “Create Application”

• In the setup form:

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

• 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
  

• Click “Authorize” to complete setup.

• 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
  

✅ 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.