certctl/docs/operator/oidc-runbooks/auth0.md

Auth0 OIDC runbook

Last reviewed: 2026-05-10

This runbook wires certctl's OIDC SSO surface against Auth0, a commercial cloud IdP (now part of Okta but operationally distinct). Auth0 has a free developer tier suitable for evaluation; production runs on a paid B2B / B2C plan.

For the canonical reference + mental model, read keycloak.md first; this runbook only documents the Auth0-specific deltas.

The big Auth0 quirk: namespaced custom claims

Auth0 imposes a hard rule: any custom claim emitted from an Action MUST use a namespaced URL-shape key (e.g. https://your-namespace/groups). Auth0 silently strips claims that look like standard OIDC claims (groups, roles, permissions, etc.) when emitted from an Action — this is a security feature to prevent claim-spoofing.

certctl handles this via the groups_claim_path config. If your Action emits https://your-namespace/groups, set OIDCProvider.groups_claim_path to that exact URL. The hand-rolled groupclaim resolver at internal/auth/oidc/groupclaim/resolver.go recognizes URL-shape paths (anything starting with http:// or https://) and treats the entire string as a single literal key — it does NOT split on /.

Set groups_claim_format to string-array; the underlying claim shape is still a JSON array of group-name strings, just stored under a URL-shape key.

Prerequisites

On the Auth0 side:

• An Auth0 tenant (free dev tier at https://auth0.com/signup works). Tenant URL looks like https://<tenant-name>.<region>.auth0.com.
• Owner or Auth0 Administrator role.
• Network reachability from certctl-server to https://<tenant>.auth0.com/.well-known/openid-configuration.

On the certctl side: same as Keycloak.

IdP-side configuration

1. Pick a namespace string

Decide on a unique URL-shape namespace for certctl's custom claims. It does NOT have to resolve to a real domain; Auth0 just requires it to be URL-shape and unique within your tenant. A reasonable choice:

https://certctl.example.com/auth/

Use that prefix for every custom claim; for groups specifically:

https://certctl.example.com/auth/groups

We'll refer to this as <NS>/groups in the rest of this runbook.

2. Create the Application

In the Auth0 dashboard:

Applications → Applications → Create Application:

• Name: certctl.
• Application Type: Regular Web Applications.
• Click Create.

On the saved app's Settings tab:

• Application Login URI: blank (Auth0 doesn't need it for the auth-code flow).
• Allowed Callback URLs: https://<your-certctl-host>:8443/auth/oidc/callback (one entry, exact match).
• Allowed Logout URLs: optional.
• Allowed Web Origins: https://<your-certctl-host>:8443.
• Token Endpoint Authentication Method: Post (default; matches the certctl service's expectation of client_secret_post).
• Save Changes.

Copy the Domain (this is the issuer base — https://<tenant>.auth0.com), Client ID, and Client Secret from the same Settings page.

3. Configure the connection (where users live)

If you're using Auth0's Database connection (default username + password), the existing Username-Password-Authentication connection works. For SSO to Google / Microsoft / SAML, configure those connections under Authentication → Enterprise or Authentication → Social and ensure the connection is enabled on the certctl Application (App → Connections tab).

4. Define the groups

Auth0 doesn't have a first-class "Groups" concept like Okta or Keycloak — you have THREE options to model groups, each with tradeoffs:

Option A: User app_metadata (simplest, recommended for dev tier).

Each user has a app_metadata JSON blob you can set via the Management API, the dashboard, or a post-registration script. Stick the groups in there:

{
  "groups": ["certctl-engineers"]
}

In the Auth0 dashboard, User Management → Users → → app_metadata: paste the JSON above and Save.

Option B: Auth0 Authorization Extension (paid plans, recommended for production).

Install the Authorization Extension from Marketplace → Extensions → Authorization. It adds a first-class "Groups" concept with UI for assignment + nested groups. Read the extension's docs; it emits groups under <NS>/groups automatically once enabled.

Option C: Roles + Permissions (Auth0's RBAC primitive).

Use User Management → Roles to define roles like certctl-engineer + certctl-viewer. Assign roles to users. Have your Action emit role names as a groups claim. This is what Auth0 documents as the canonical pattern; it's slightly heavier than Option A but more discoverable in the dashboard.

This runbook uses Option A for clarity; the Action below reads from app_metadata.groups.

5. Write the Action that emits the groups claim

Actions → Library → Create Action → Build from scratch:

• Name: certctl-emit-groups.
• Trigger: Login / Post Login.
• Runtime: Node 18.
• Click Create.

Paste this code:

exports.onExecutePostLogin = async (event, api) => {
  const namespace = "https://certctl.example.com/auth/";
  const groups = (event.user.app_metadata && event.user.app_metadata.groups) || [];
  if (groups.length > 0) {
    api.idToken.setCustomClaim(namespace + "groups", groups);
    api.accessToken.setCustomClaim(namespace + "groups", groups);
  }
};

Replace https://certctl.example.com/auth/ with your namespace from step 1. Click Deploy.

Then bind the Action to the Login flow:

Actions → Flows → Login: drag certctl-emit-groups from the Custom tab into the flow, between Start and Complete. Click Apply.

6. Verify the claim in a test login

Auth0's Authentication → Authentication Profile → Try It button or the Logs → Real-time Logs page can show you the issued ID token in real time. Decode at jwt.io to confirm <NS>/groups is present + populated.

certctl-side configuration

curl -X POST https://<your-certctl-host>:8443/api/v1/auth/oidc/providers \
  -H "Authorization: Bearer ${CERTCTL_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auth0",
    "issuer_url": "https://<tenant>.auth0.com/",
    "client_id": "<paste-from-step-2>",
    "client_secret": "<paste-from-step-2>",
    "redirect_uri": "https://certctl.example.com:8443/auth/oidc/callback",
    "groups_claim_path": "https://certctl.example.com/auth/groups",
    "groups_claim_format": "string-array",
    "fetch_userinfo": false,
    "scopes": ["openid", "profile", "email"],
    "iat_window_seconds": 300,
    "jwks_cache_ttl_seconds": 3600
  }'

Critical:

• issuer_url includes the trailing slash for Auth0 (https://<tenant>.auth0.com/). Auth0's iss claim emits with the trailing slash; mismatching trips ErrIssuerMismatch.
• groups_claim_path is the full namespaced URL, not the bare groups key. The certctl resolver treats this as a single literal lookup key against the ID token claims map (no path-walking through /).

Add the group→role mappings: certctl-engineers → r-operator, etc. The mapping table maps the group VALUES (the strings inside the claim's array), not the claim path.

Verification

End-to-end login + audit + Sessions checks are identical to Keycloak. The audit row's details.subject will be Auth0's user_id (e.g. auth0|abc123… for database users, google-oauth2|... for federated), stable across email changes.

Troubleshooting

ErrGroupsUnmapped even though I see groups in the ID token at jwt.io.

Check groups_claim_path exactly matches the namespaced key in the token. A common mistake: setting groups_claim_path to groups (the bare key) when the actual claim key is https://certctl.example.com/auth/groups (the namespaced version). The resolver's URL-shape detection is what makes the namespaced path work; if the claim path doesn't start with http:// or https://, the resolver tries to walk it as a dot-separated path and fails.

The <NS>/groups claim is missing from the ID token.

• Action not bound to the Login flow: revisit step 5's "Apply" step.
• Action returns early because event.user.app_metadata.groups is undefined: confirm the user has the metadata set.
• Trying to set the claim under a non-namespaced key (e.g. api.idToken.setCustomClaim("groups", groups)): Auth0 silently drops it. Always use the namespace prefix.

Auth0 returns "Service not found" or "Invalid audience".

This usually means the certctl client wasn't authorized to access the userinfo endpoint or the application's audience setting conflicts with the OIDC discovery doc. The certctl service uses the Application's client_id as the audience claim — confirm Auth0 is emitting tokens with aud = <client_id> (decode at jwt.io).

Login redirects loop between Auth0 and certctl.

Most often a callback-URL mismatch — Auth0's "Allowed Callback URLs" must contain the EXACT certctl callback URL including port + scheme. Wildcards aren't allowed in production.

email_verified is false and certctl rejects the user.

certctl doesn't currently gate on email_verified — the User row stores email regardless. If your operator policy requires verified-only, add an Action that throws on event.user.email_verified === false:

if (!event.user.email_verified) {
  api.access.deny("email-not-verified");
}

Validation checklist

Same as keycloak.md with Auth0-specific values, plus:

• The <NS>/groups claim is present in the ID token (verify via jwt.io decode).
• Removing a user's group from app_metadata.groups causes the next login to land on "no roles assigned".
• The Auth0 dashboard's Logs → Real-time Logs shows the certctl callback completing with HTTP 302 to the dashboard.

Sign-off: _______________ (operator) on _______________ (date).