https://github.com/auth0/auth0-checkmate
https://github.com/auth0/auth0-checkmate
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/auth0/auth0-checkmate
- Owner: auth0
- License: apache-2.0
- Created: 2025-09-05T07:28:08.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-06-18T03:23:40.000Z (about 2 months ago)
- Last Synced: 2026-06-18T05:11:30.520Z (about 2 months ago)
- Language: JavaScript
- Size: 561 KB
- Stars: 41
- Watchers: 1
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Authors: AUTHORS
Awesome Lists containing this project
- awesome-auth0 - auth0-checkmate - A command-line utility that performs configuration checks on a given Auth0 tenant to ensure its configured securely and correctly. (Developer Ecosystem)
README
# 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](https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations)**. Use it thoughtfully to avoid throttling.
CheckMate for Auth0 is designed to provide visibility into its behavior through your Auth0 tenant's [log events](https://auth0.com/docs/deploy-monitor/logs). 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.
```json
{
"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](https://nodejs.dev/) **v20.18.3 or higher**
- A valid [Auth0 tenant](https://auth0.com/)
---
## 🛠️ Installation Options
### Option 1 – Global Installation
Install CheckMate for Auth0 globally to use it as a standalone CLI tool:
```bash
npm install -g @auth0/auth0-checkmate
```
Then run it with:
```bash
a0checkmate
```
Follow the interactive prompts to get started.
To update CheckMate:
```bash
npm update -g @auth0/auth0-checkmate
```
---
### Option 2 – Run from Source
1. **Clone the repository:**
```bash
git clone https://github.com/auth0/auth0-checkmate
```
2. **Navigate into the project folder:**
```bash
cd auth0-checkmate
```
3. **Install dependencies:**
```bash
npm install
```
4. **Run the tool:**
```bash
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:
```text
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
```text
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.