metal-auth0-rbac-maintainer

Auth0 RBAC desired-state sync library and CLI. Keep permissions (API scopes), roles, and users in version-controlled YAML and sync them to your Auth0 tenant.

Extracted from the auth0-rbac-metalpay pattern so multiple tenant repos can share one implementation.

Install

npm install metal-auth0-rbac-maintainer

Consumer repo layout

Each Auth0 tenant repo keeps its own desired state and config:

your-tenant-repo/
  config/
    auth0.yaml              # managed APIs + user defaults
  desired-state/
    permissions.yaml        # API scopes
    roles/
      admin.yaml            # role definitions + user membership
    users/
      jane.yaml             # user account settings
  package.json

Copy config/auth0.example.yaml from this package as a starting point.

CLI

The package installs a metal-auth0-rbac binary. Add scripts in your consumer package.json:

{
  "scripts": {
    "validate": "metal-auth0-rbac validate",
    "preview": "metal-auth0-rbac sync",
    "apply": "metal-auth0-rbac sync --apply",
    "export": "metal-auth0-rbac export"
  }
}

Commands

| Command | Description | |---------|-------------| | validate [resource] | Offline structural validation (no Auth0 credentials) | | sync [resource] | Dry-run diff vs live Auth0 | | sync --apply | Push changes to Auth0 | | export [resource] | Bootstrap: pull live Auth0 state into YAML |

Resources: permissions, roles, users, or all (default). Sync order is always permissions → roles → users.

Options

| Flag / env | Purpose | |------------|---------| | --config <path> / AUTH0_CONFIG_PATH | Path to auth0.yaml (default: config/auth0.yaml) | | --desired-state-dir <dir> / AUTH0_DESIRED_STATE_PATH | Path to desired-state (default: desired-state) | | AUTH0_DOMAIN | Tenant hostname, e.g. your-tenant.us.auth0.com | | AUTH0_CLIENT_ID / AUTH0_CLIENT_SECRET | M2M application credentials |

export AUTH0_DOMAIN=your-tenant.us.auth0.com
export AUTH0_CLIENT_ID=...
export AUTH0_CLIENT_SECRET=...

metal-auth0-rbac validate
metal-auth0-rbac sync
metal-auth0-rbac sync --apply
metal-auth0-rbac export --prune

Programmatic API

Import sync, validation, and export functions directly:

import {
  configurePaths,
  getManagementClient,
  loadConfig,
  resolveConfigPathWithFallback,
  resolveDesiredStateDir,
  validateDesiredState,
  syncPermissions,
  syncRoles,
  syncUsers,
  fetchLiveRoles,
  resolveResourceServers,
} from "metal-auth0-rbac-maintainer";

configurePaths({
  configPath: "config/auth0.yaml",
  desiredStateDir: "desired-state",
});

const config = loadConfig(resolveConfigPathWithFallback());
const desiredStateDir = resolveDesiredStateDir();

// Offline validation
const validation = validateDesiredState(config, { resource: "all", desiredStateDir });

// Live sync (requires AUTH0_* env vars)
const management = getManagementClient();
const resourceServers = await resolveResourceServers(management, config);

const permissions = await syncPermissions(management, resourceServers, {
  apply: false,
  desiredStateDir,
});

const liveRoles = await fetchLiveRoles(management);
const roleNameToId = Object.fromEntries(
  Object.entries(liveRoles).map(([name, role]) => [name, role.id]),
);

const roles = await syncRoles(management, resourceServers, { apply: false, desiredStateDir });
const users = await syncUsers(management, roleNameToId, config, resourceServers, {
  apply: false,
  desiredStateDir,
});

Custom CLI

Extend or embed the CLI in your own tooling:

import { createProgram } from "metal-auth0-rbac-maintainer";

const program = createProgram();
await program.parseAsync(process.argv);

GitLab CI

In your tenant repo, install this package and call the CLI instead of vendoring src/:

.default:
  image: node:22-slim
  before_script:
    - npm ci --omit=dev

validate:permissions:
  script:
    - npx metal-auth0-rbac validate permissions

preview:permissions:
  script:
    - AUTH0_CLIENT_ID="$AUTH0_READ_CLIENT_ID" AUTH0_CLIENT_SECRET="$AUTH0_READ_CLIENT_SECRET" npx metal-auth0-rbac sync permissions

apply:permissions:
  script:
    - npx metal-auth0-rbac sync permissions --apply

See the auth0-rbac-metalpay .gitlab-ci.yml for the full validate → preview → apply pipeline pattern.

Auth0 setup

Requires a Machine-to-Machine application with the Client Credentials grant.

Read scopes: read:resource_servers, read:roles, read:users, read:permissions

Write scopes (for apply): update:resource_servers, create:roles, delete:roles, update:roles, create:users, delete:users, update:users, create:permissions, delete:permissions, create:user_tickets

Requirements

• Node.js 20+