Auth0

​

At a glance

npx @deploybaseline/cli start --service auth0

import { createEmulator } from "@deploybaseline/cli";

const auth0 = await createEmulator({ service: "auth0" });
// auth0.url is http://localhost:4000

{
  "auth0": {
    "domain": "baseline.us.auth0.com",
    "default_directory": "Username-Password-Authentication",
    "users": [
      {
        "email": "[email protected]",
        "password": "Passw0rd!",
        "name": "Ada Lovelace"
      }
    ],
    "apis": [
      {
        "identifier": "https://api.example.com",
        "name": "Example API",
        "scopes": ["read:items", "write:items"],
        "allow_offline_access": true
      }
    ],
    "clients": [
      {
        "client_id": "baseline-web-app",
        "client_secret": "baseline-web-secret",
        "name": "Web app",
        "callbacks": ["http://localhost:3000/callback"],
        "allowed_logout_urls": ["http://localhost:3000"],
        "grant_types": ["authorization_code", "refresh_token", "password"]
      },
      {
        "client_id": "baseline-m2m",
        "client_secret": "baseline-m2m-secret",
        "name": "Backend service",
        "app_type": "non_interactive"
      }
    ],
    "client_grants": [
      {
        "client_id": "baseline-m2m",
        "audience": "https://api.example.com",
        "scope": ["read:items"]
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service auth0

​

URL mapping

import * as client from "openid-client";

const config = await client.discovery(
  new URL(`${process.env.AUTH0_EMULATOR_URL}/`),
  "baseline-web-app",
  "baseline-web-secret",
  undefined,
  { execute: [client.allowInsecureRequests] }, // the emulator speaks plain http
);

import { ManagementClient } from "auth0";

const domain = "baseline.us.auth0.com"; // the seed's `domain`
const emulator = process.env.AUTH0_EMULATOR_URL!;
const toEmulator: typeof fetch = (input, init) => {
  const url = new URL(input instanceof Request ? input.url : String(input));
  return fetch(url.host === domain ? new URL(url.pathname + url.search, emulator) : input, init);
};

const management = new ManagementClient({
  domain,
  clientId: "baseline-m2m",
  clientSecret: "baseline-m2m-secret",
  fetch: toEmulator,
});

​

Tenant

• Domain. domain in the seed names the tenant as clients see it (default: the emulator’s host). It sets the Management API’s audience, https://{domain}/api/v2/. The emulator also accepts {emulator URL}/api/v2/ as the same API, and a client grant for either covers both.
• Default audience. default_audience is the audience for token requests that name none, as the tenant setting of that name is on Auth0.
• Default directory. default_directory names the connection the password grant signs in against. As on Auth0, a tenant has none until it is set, and the plain password grant fails with 500 server_error “Authorization server not configured with default connection.” until then.
• Connections. Every tenant has the Username-Password-Authentication database connection (password policy good). Seed more under connections.

​

Applications

​

Universal Login

• Callback. Without redirect_uri the client’s first callback URL is used. A redirect_uri outside the client’s callback URLs shows an error page (Callback URL mismatch), as Auth0 does. URLs are compared without the query string and a trailing slash.
• Errors after the callback is trusted go back to it with error, error_description, and state: invalid_request for a missing response_type, a bad code_challenge_method, or an unknown connection; unsupported_response_type for anything but code; unauthorized_client when the client lacks the authorization_code grant; access_denied with Service not found: {audience} for an unknown API.
• Scopes. OpenID Connect scopes stay; an API’s scopes stay when the API defines them; other scopes are dropped, as Auth0 drops them. offline_access stays only when a refresh token can be issued: the client has the refresh_token grant and the API allows offline access (allow_offline_access), or the request names no API.
• Sessions. A login sets the auth0 cookie. While the session lives, /authorize signs the user in again without the login page. prompt=login shows the page anyway; prompt=none answers login_required (Login required) without a session; max_age treats an older login as no session and puts auth_time in the ID token. Sessions end after 3 days idle or 30 days in all, Auth0’s defaults.
• Codes are single use and last 10 minutes (Auth0 says only that codes are short lived).

​

Token endpoint

​

Tokens

• Access tokens are JWTs with iss, sub (the user’s ID, or {client_id}@clients for client credentials), aud, iat, exp, azp, scope, and jti, plus gty (client-credentials or password) for those grants. The API decides how they are signed: signing_alg: RS256 (the default for seeded APIs) uses the tenant key in the JWKS; HS256 uses the API’s signing_secret, with no kid. An API with token_dialect: rfc9068_profile (or rfc9068_profile_authz) gets tokens in the RFC 9068 profile: the header says typ: at+jwt, and client_id replaces azp and gty. With an API the audience is the API’s identifier, joined by {issuer}userinfo when openid was granted. They last the API’s token_lifetime (default 86400 seconds), or its token_lifetime_for_web (default 7200) for single page apps. Without an API, Auth0 issues an opaque token for /userinfo; Baseline signs a JWT whose audience is {issuer}userinfo, lasting 86400 seconds.
• ID tokens carry sub, aud (the client ID), sid (for logins through /authorize), nonce, and the profile claims the scopes allow: profile adds name, nickname, picture, updated_at, given_name, and family_name; email adds email and email_verified. They last the client’s id_token_lifetime (default 36000 seconds).
• The token response has access_token, id_token (with openid), refresh_token (with offline_access), scope, expires_in, and token_type: "Bearer".

​

Signing key

​

Refresh tokens

• Non-rotating (the default): the token keeps working until revoked and never expires; a refresh answers without a new refresh token.
• Rotating (refresh_token.rotation_type: rotating): each refresh returns a new token and retires the old one. Using a retired token again is taken as theft and revokes the whole family, including the newest token, as Auth0’s automatic reuse detection does. With refresh_token.leeway (seconds), the token most recently retired still works inside that window. A family expires token_lifetime seconds after its first token (default 30 days); rotation does not extend it.
• Idle lifetime. An expiring token (expiration_type: expiring) that goes unused for idle_token_lifetime seconds stops working, unless infinite_idle_token_lifetime is set. Rotating clients default to 15 days; each use starts the clock again.
• Switching rotation. Turning rotation on makes the next refresh of a non-rotating token return a rotating one and delete the grant’s non-rotating tokens; turning it off swaps a rotating token for a non-rotating one and revokes the family, as Auth0 migrates them.
• Revocation. POST /oauth/revoke with client_id, the client’s secret, and token revokes the token (and its rotation family) and answers 200 with no body. Unknown tokens and other clients’ tokens answer 200 without effect. With revoke_refresh_token_grant: true it revokes every token of the same user, client, and audience, as the tenant setting “Refresh Token Revocation Deletes Grant” does.

​

Client credentials

​

Userinfo

​

Database connections

• POST /dbconnections/signup — Sign up: with connection, email, password, and optional client_id, username (only for connections with requires_username), given_name, family_name, name, nickname, picture, phone_number, and user_metadata (at most 10 string properties). Returns {_id, email_verified: false, email, ...}, where _id is the user ID without auth0|. New users get Auth0’s defaults: name is the email, nickname its local part, and picture a Gravatar URL.
• POST /dbconnections/change_password — Change password: with connection, email, and optional client_id. Answers We've just sent you an email to reset your password. whether or not the user exists. Baseline sends no email; the request appears in the inspector.

​

Logout

• GET /v2/logout — Log out: ends the session and redirects to returnTo, which must be one of the client’s allowed logout URLs (with client_id) or the tenant’s (allowed_logout_urls in the seed, without one). Without returnTo it goes to the client’s first allowed logout URL, or shows a logged out page.
• GET /oidc/logout — Log out with OIDC: OpenID Connect RP-initiated logout, also as POST /oidc/logout with form fields. It takes id_token_hint, logout_hint, client_id, post_logout_redirect_uri, and state, which is passed back on the redirect. An expired ID token is accepted as a hint. A hint from another tenant, a client_id that does not match the hint’s audience, or a logout_hint that does not match its session is refused. Without a hint naming the session, the user confirms on a page first, as Auth0 asks.

​

Management API

​

Users

​

User search

• Fields: user_id, email, email.domain, email_verified, name, given_name, family_name, nickname, username, phone_number, blocked, logins_count, created_at, updated_at, last_login, last_ip, last_password_reset, identities.connection, identities.provider, identities.user_id, and paths into user_metadata and app_metadata (arrays are stepped through, so user_metadata.addresses.cities:"Paris" finds a city in a list).
• Terms match whole values: name:"Ada Lovelace", blocked:true, logins_count:3. email, email.domain, name, given_name, family_name, and nickname ignore case; other fields do not. A term without a field searches user_id, email, name, nickname, given_name, family_name, and username.
• Wildcards * and ?: email:test*, name:*example*. A leading wildcard needs at least 3 other characters.
• Ranges: logins_count:[10 TO 100}, last_login:[2025-12-01 TO 2025-12-31], logins_count:[100 TO *]. A bare date covers its whole day.
• _exists_:field, and the operators AND, OR, NOT (also &&, ||, !, and a leading -) with parentheses and field groups (name:("Ada" OR "Sam")). Terms side by side are joined with OR.

​

Roles and permissions

​

Clients

​

Client grants

​

Resource servers

​

Connections

​

Sessions

​

Refresh tokens

​

Tokens for the current user

​

Role based access control

​

Seed config

{
  "auth0": {
    "domain": "baseline.us.auth0.com",
    "friendly_name": "Acme",
    "default_directory": "Username-Password-Authentication",
    "default_audience": "https://api.example.com",
    "allowed_logout_urls": ["http://localhost:3000"],
    "revoke_refresh_token_grant": false,
    "connections": [
      {
        "name": "staff",
        "display_name": "Staff",
        "password_policy": "excellent",
        "requires_username": true,
        "disable_signup": false,
        "enabled_clients": ["baseline-web-app"]
      }
    ],
    "users": [
      {
        "email": "[email protected]",
        "password": "Passw0rd!",
        "name": "Ada Lovelace",
        "given_name": "Ada",
        "family_name": "Lovelace",
        "user_metadata": {
          "plan": "pro"
        },
        "roles": ["reader"],
        "permissions": [
          {
            "api": "https://api.example.com",
            "scopes": ["write:items"]
          }
        ]
      },
      {
        "email": "[email protected]",
        "password": "Passw0rd!",
        "connection": "staff",
        "username": "sam",
        "blocked": false
      }
    ],
    "apis": [
      {
        "identifier": "https://api.example.com",
        "name": "Example API",
        "scopes": [
          "read:items",
          {
            "value": "write:items",
            "description": "Write items"
          }
        ],
        "allow_offline_access": true,
        "token_lifetime": 86400,
        "token_lifetime_for_web": 7200,
        "enforce_policies": true,
        "token_dialect": "access_token_authz",
        "signing_alg": "RS256"
      }
    ],
    "roles": [
      {
        "name": "reader",
        "description": "Reads items",
        "permissions": [
          {
            "api": "https://api.example.com",
            "scopes": ["read:items"]
          }
        ]
      }
    ],
    "clients": [
      {
        "client_id": "baseline-web-app",
        "client_secret": "baseline-web-secret",
        "name": "Web app",
        "app_type": "regular_web",
        "callbacks": ["http://localhost:3000/callback"],
        "allowed_logout_urls": ["http://localhost:3000"],
        "grant_types": ["authorization_code", "refresh_token", "password"],
        "id_token_lifetime": 36000
      },
      {
        "client_id": "baseline-spa",
        "name": "Single page app",
        "app_type": "spa",
        "callbacks": ["http://localhost:5173/callback"],
        "refresh_token": {
          "rotation_type": "rotating",
          "leeway": 0,
          "idle_token_lifetime": 1296000
        }
      },
      {
        "client_id": "baseline-m2m",
        "client_secret": "baseline-m2m-secret",
        "name": "Backend service",
        "app_type": "non_interactive"
      }
    ],
    "client_grants": [
      {
        "client_id": "baseline-m2m",
        "audience": "https://api.example.com",
        "scope": ["read:items"]
      },
      {
        "client_id": "baseline-m2m",
        "audience": "https://baseline.us.auth0.com/api/v2/",
        "scope": [
          "read:users",
          "update:users",
          "read:roles",
          "read:clients",
          "read:resource_servers",
          "read:connections"
        ]
      }
    ]
  }
}

• default_audience: optional
• display_name: the name when left out
• password_policy: none, low, fair, good, excellent
• enabled_clients: every client when left out
• roles: by name or id
• enforce_policies: role based access control
• token_dialect: adds the permissions claim; or rfc9068_profile(_authz)
• signing_alg: or HS256, signed with signing_secret
• app_type: regular_web, spa, native, non_interactive
• signing_secret (not set above, for example a-secret-of-16-characters-or-more).
• allow_all_scopes (not set above, for example true): every scope the API defines, now and later

​

Inspector

​

Limits

• The Management API serves users, roles, permissions, clients, client grants, resource servers, connections, sessions, and refresh tokens. Logs, tickets, organizations, actions, custom domains, tenant settings, and the rest are not served.
• Only response_type=code is supported: no implicit or hybrid flows.
• Not emulated: the device flow, passwordless, MFA, organizations, social and enterprise connections, Actions and Rules (so no custom claims), consent screens (every client is first party), HS256 ID tokens, RS512 and PS256 access tokens, private key JWT client authentication, DPoP, and rate limits.
• Change password requests are recorded, not emailed, and have no reset page.

​

Conformance