auth0-tests

Overview

Tests against an Auth0 tenant fall into three layers:

1. Tenant-level config - connections, clients, APIs, tenants themselves; tested via Auth0 Deploy CLI for env parity.
2. Auth flow - tested by exercising the OIDC endpoints from the application against a dev tenant.
3. Custom serverless code - Actions (current), Rules + Hooks (legacy); unit-tested in Node.js with the Auth0 SDK mocks.

When to use

• The repo uses Auth0 as IdP.
• The team has multiple environments (dev / staging / prod) needing config parity.
• Custom Actions / Rules need unit-test coverage.
• Auth flow regression suites need to run pre-deploy.

How to use

1. Pick a tenant strategy (Step 1): per-PR tenant for tenant-config tests, mocked OIDC for fast app-side flow tests.
2. Export the source tenant with a0deploy and commit the YAML as fixtures for the config-drift check (Step 2).
3. Exercise the OIDC token endpoint for the grants the app uses - client-credentials for M2M, Universal Login via Playwright for interactive flows (Step 3).
4. Unit-test each Action handler by calling onExecutePostLogin with a stub api and asserting on api.access.deny (Step 4); apply the legacy callback signature for surviving Rules / Hooks (Step 5).
5. Cover session behavior - refresh-token rotation plus the nine-point checklist (Step 6).
6. Wire the unit run and the a0deploy config-drift diff into CI (Step 8).

Step 1 - Tenant strategy

Three patterns, per team scale:

Pattern	Pros	Cons
Per-PR tenant (Auth0 sandbox plan)	Full isolation; safe destructive tests	Requires Auth0 plan supporting many tenants
Shared dev tenant + namespaced fixtures	Cheap	Test interference risk; cleanup discipline
Mocked OIDC server (e.g., mock-oauth2-server)	No Auth0 dep; fast	Doesn't catch Auth0-side behavior

For tenant-level tests pick per-PR; for app-side flow tests, mocked OIDC is sufficient + faster.

Step 2 - Auth0 Deploy CLI for config parity

The a0deploy CLI exports tenant config to YAML/JSON, supports diff + apply across tenants. Pattern:

# Export dev tenant
a0deploy export -c config.json --output_folder tenant-fixtures/

# Diff against staging
a0deploy export -c config-staging.json --output_folder tenant-staging/
diff -r tenant-fixtures/ tenant-staging/

# Apply to staging from dev as source of truth
a0deploy import -c config-staging.json --input_file tenant-fixtures/tenant.yaml

Tests verify the export hasn't drifted unexpectedly:

a0deploy export -c config.json --output_folder tmp-current/
diff -r tenant-fixtures/ tmp-current/   # expect empty if no drift

Source: auth0.com/docs/deploy-monitor/deploy-cli-tool.

Step 3 - Test the OIDC token endpoint

Auth0's token endpoint:

https://{your-domain}.auth0.com/oauth/token

For client-credentials (M2M) flow:

import requests

def test_m2m_token(auth0_domain, client_id, client_secret, audience):
    response = requests.post(
        f"https://{auth0_domain}/oauth/token",
        json={
            "grant_type": "client_credentials",
            "client_id": client_id,
            "client_secret": client_secret,
            "audience": audience,
        },
    )
    assert response.status_code == 200
    body = response.json()
    assert "access_token" in body
    assert body["token_type"] == "Bearer"

For interactive flows (authz code), use Playwright to drive the Universal Login UI (Auth0-hosted login page) and capture the redirect.

Source: auth0.com/docs/api/authentication.

Step 4 - Test Auth0 Actions (current generation)

Actions are the current Auth0 serverless extension model (post-Hooks). Each Action exports a handler:

// post-login.js
exports.onExecutePostLogin = async (event, api) => {
  if (event.user.email_verified === false) {
    api.access.deny('Email not verified');
  }
};

Unit-test pattern with Auth0's testing library:

const { onExecutePostLogin } = require('./post-login');

describe('post-login Action', () => {
  it('denies access for unverified email', async () => {
    const api = {
      access: { deny: jest.fn() },
    };
    const event = {
      user: { email_verified: false },
    };
    await onExecutePostLogin(event, api);
    expect(api.access.deny).toHaveBeenCalledWith('Email not verified');
  });
});

Source: auth0.com/docs/customize/actions.

Step 5 - Test Rules + Hooks (legacy)

Rules + Hooks are deprecated as of 2024 (per Auth0 deprecation notices) but many production tenants still use them. Unit-test pattern is similar to Actions but with the legacy callback signature:

function emailVerifiedRule(user, context, callback) {
  if (!user.email_verified) {
    return callback(new UnauthorizedError('Email not verified'));
  }
  callback(null, user, context);
}

// Test
emailVerifiedRule(
  { email_verified: false },
  {},
  (err, user, ctx) => {
    expect(err.message).toBe('Email not verified');
  }
);

For Auth0 Hooks, similar pattern with the hook-specific event shape.

Step 6 - Test session management

Auth0-managed sessions (refresh tokens, silent auth): refresh-token rotation is configurable per-application; tests should verify the rotation behaves as configured. For the full nine-point session checklist (cookie attributes, fixation, idle / absolute timeout, concurrent-session policy, server-side logout, CSRF, session binding) against the app's own session cookie, see references/session-checklist.md. Cross-tool session patterns live in session-management-test-author.

Step 7 - Mock OIDC server alternative

For fast unit tests of the application's OIDC integration without Auth0 calls:

docker run -p 8080:8080 ghcr.io/navikt/mock-oauth2-server:0.5.10

Then point the application at http://localhost:8080/default/.well-known/openid-configuration. Tests run against the mock; per-PR Auth0 tenant unnecessary.

Step 8 - CI integration

- run: npm install
- run: npm test                      # unit tests including Actions
- run: a0deploy export -c .auth0/config.json --output_folder /tmp/auth0-current
- run: diff -r .auth0/tenant-fixtures /tmp/auth0-current   # config-drift check

Worked example

A team ships a post-login Action that blocks sign-in for unverified emails. On a shared dev tenant with namespaced fixtures (Step 1), they export config with a0deploy export -c config.json --output_folder tenant-fixtures/ and commit it (Step 2). They unit-test the handler by passing event.user.email_verified = false and a stub api, then assert api.access.deny was called with 'Email not verified' (Step 4). CI runs npm test, then re-exports and diff -rs against tenant-fixtures/; a stray dashboard change to the Action fails the drift diff before it reaches staging (Step 8).

Anti-patterns

Anti-pattern	Why it fails	Fix
Share a single Auth0 tenant for all envs	Config changes intermingle; staging breaks prod	Per-env tenants + a0deploy parity (Step 2)
Test Actions only via end-to-end	Slow; tests pass for wrong reasons	Unit-test Actions directly (Step 4)
Use password grant for new flows	Deprecated per RFC 9700	Auth Code + PKCE (Step 3)
Skip config-drift CI check	Manual changes in dashboards never reach prod	Always diff exports (Step 8)

Limitations

• Auth0 ToS prohibits load testing without explicit approval.
• Rules + Hooks are deprecated; new code should target Actions.
• Mock OIDC server doesn't catch Auth0-side custom logic (Action scripts, Rules); pair mock unit tests with at least one per-tenant integration test.
• Auth0 documentation evolves; cite specific URLs per skill use and verify against current docs.

References

• auth0.com/docs - Auth0 documentation root
• auth0.com/docs/api/authentication - Authentication API endpoints
• auth0.com/docs/customize/actions - Actions documentation
• auth0.com/docs/deploy-monitor/deploy-cli-tool - Deploy CLI
• ghcr.io/navikt/mock-oauth2-server - mock OIDC server
• IETF RFC 6749 / 7636 / 9700 - OAuth 2.0 + PKCE + Security BCP
• keycloak-tests, okta-tests - sister IdP tools
• oauth-flow-test-author, session-management-test-author - build-an-X authors