Auth0 OIDC

Audience: Auth0 administrators wiring OpenID Connect for TokenTimer Enterprise.

Multi-provider SSO: Configure Auth0 under System Settings → Manage SSO providers (or bootstrap via sso-providers.json / Helm ssoProviders[]). Sign-in and callback URLs are slug-scoped. See the OIDC quickstart first.

Auth0 is an OIDC/OAuth2 provider. TokenTimer acts as a confidential web client (authorization code). Auth0 also supports SAML SP integrations; for new deployments prefer OIDC unless you have a SAML-only requirement (SAML SP).

See the SSO identity provider guides for prerequisites and callback URLs.

URLs to register

Replace <slug> with your provider slug (e.g. auth0).

Purpose	Value
Allowed Callback URLs	https://tokentimer.example.com/auth/oidc/<slug>/callback
Allowed Logout URLs (optional)	https://tokentimer.example.com/login
Allowed Web Origins (optional)	https://tokentimer.example.com

---

1. Create application

1. Auth0 Dashboard, Applications, Create Application.
2. Type: Regular Web Applications (application settings).
   • Not Single Page Application (public client without secret).
3. Settings tab:

Auth0 field	Value
Allowed Callback URLs	https://tokentimer.example.com/auth/oidc/<slug>/callback
Application Login URI (optional)	https://tokentimer.example.com/login
Token Endpoint Authentication Method	Post (default; client secret in POST body)

4. Copy Domain, Client ID, Client Secret into SSO Providers (or your bootstrap manifest).

2. Issuer and discovery

For tenant domain your-tenant.us.auth0.com (or custom domain), set Issuer in SSO Providers (config.issuer in bootstrap JSON) to:

https://your-tenant.us.auth0.com/

Discovery (note trailing slash on issuer is common in Auth0 docs; use the exact issuer from discovery):

https://your-tenant.us.auth0.com/.well-known/openid-configuration

With a custom domain (login.example.com), issuer is typically:

https://login.example.com/

TokenTimer uses discovery by default. Auth0-shaped path fallbacks apply when discovery is disabled or unreachable (per-provider Disable discovery or network failure): /authorize, /oauth/token, /userinfo. Explicit endpoint overrides in SSO Providers always win.

3. Scopes and API

APIs: ensure Auth0 Management API is not required for login. User login needs only:

openid profile email

Add offline_access only if you plan refresh-token behavior (TokenTimer SSO session uses its own cookie, not Auth0 refresh tokens by default).

4. Groups / roles in tokens

Auth0 does not add application groups to the ID token by default.

1. Actions, Flows, Login: add Add Group Roles to Tokens or a custom Action that sets a groups (or https://your-app.example.com/groups) claim (Rules/Actions migration).
2. Or use Authorization Extension / RBAC with Roles included in the token via Dashboard API authorization settings.

In SSO Providers under Claim mapping (or bootstrap claim_mapping):

Field	Paths
Email	email
Display name	name
Groups	groups, https://your-namespace/groups
Subject	sub

Use the exact claim name your Action emits. Namespace URIs work with dot paths if configured in claim mapping.

5. Connections

Under Authentication, Database / Social / Enterprise, enable the connections this application may use (e.g. Username-Password-Authentication, google-oauth2, waad for Entra).

6. TokenTimer configuration

In SSO Providers (or sso-providers.json / Helm ssoProviders[]):

Field	Value
Issuer	https://your-tenant.us.auth0.com/
Client ID	<client-id>
Scopes	openid profile email

Secret env (slug auth0 gives SSO_AUTH0_OIDC_CLIENT_SECRET):

SSO_AUTH0_OIDC_CLIENT_SECRET=<client-secret>
API_URL=https://tokentimer.example.com
APP_URL=https://tokentimer.example.com

Helm: start from helm/examples/values-sso-basic-oidc.yaml in the delivery.

7. Verify

1. Try the application from the Auth0 Dashboard (runs authorize flow).
2. TokenTimer: GET /api/auth/features returns your slug in providers.oidc[] with signInReady: true.
3. Login via the provider button on the login page (e.g. Sign in with Auth0); check audit idp_groups_seen after adding group claims.

Troubleshooting

Symptom	Likely cause	Fix
Callback URL mismatch	Missing callback in app settings	Add exact URL
Invalid issuer	Custom domain vs tenant domain	Match discovery issuer
Discovery fails in private network	API cannot reach Auth0	Allow egress or set endpoint overrides + disable discovery on the provider
No groups	No Action/Rule	Add groups claim in Login flow
Unauthorized at token endpoint	Wrong client authentication	Use Post + secret for Regular Web App

Official references

• Application settings
• OpenID Connect protocol
• Configure SAML SP (if not using OIDC)