OpenID Connect (OIDC)
Zudoku supports any identity provider that implements the
OpenID Connect protocol via the generic
openid provider type. This includes Okta, Keycloak, Authentik, Ory, ZITADEL, AWS Cognito, Google
Identity, and most enterprise IdPs.
Configuration
Add the authentication property to your Zudoku configuration:
zudoku.config.ts
| Option | Required | Description |
|---|---|---|
clientId | Yes | The OAuth client ID issued by your provider. |
issuer | Yes | The issuer URL. Zudoku discovers endpoints from <issuer>/.well-known/openid-configuration. |
scopes | No | Scopes to request. Defaults to ["openid", "profile", "email"]. |
allowInsecureRequests | No | Allow discovery and token requests against an http:// issuer. Defaults to false. Intended only for local development — never enable this in production. |
disableUserInfo | No | Don't call the UserInfo endpoint and build the user profile from the ID token's claims instead. Defaults to false. See User Profile. |
Provider Setup
Register Zudoku as a public SPA / single page application client in your identity provider and set:
- Callback / Redirect URI to
https://your-site.com/oauth/callback - For local development, add
http://localhost:3000/oauth/callback - If your provider supports wildcards, add
https://*.your-domain.com/oauth/callbackfor preview environments - Add your site origin to the list of allowed CORS origins
- Enable the
Authorization Codegrant with PKCE and theRefresh Tokengrant
Okta
- In the Okta admin console go to Applications → Applications → Create App Integration.
- Select OIDC - OpenID Connect and Single Page Application.
- Set Sign-in redirect URIs to
https://your-site.com/oauth/callback(addhttp://localhost:3000/oauth/callbackfor local development). - Under Assignments, assign the users or groups that should have access.
- After creating the app, copy the Client ID. Your issuer is your Okta domain, for example
https://your-tenant.okta.comor a custom authorization server likehttps://your-tenant.okta.com/oauth2/default. - Under Security → API → Trusted Origins, add your site origin for both CORS and Redirect.
zudoku.config.ts
Keycloak
Use the realm issuer URL:
zudoku.config.ts
In the realm, create a client with Client type OpenID Connect, Access type public, and
enable Standard Flow (Authorization Code).
Verifying the Issuer
You can confirm your issuer URL is correct by opening <issuer>/.well-known/openid-configuration in
a browser. It should return a JSON document listing authorization_endpoint, token_endpoint,
userinfo_endpoint, and jwks_uri.
Customizing Sign-up
By default Register and Sign in both call the OIDC authorize endpoint, so users land on the same login page. Two options change that:
zudoku.config.ts
When disableSignUp is true, the Register button on the protected-route login dialog is hidden
and /signup shows an "Invitation required" page.
User Profile
After sign-in Zudoku calls the provider's
UserInfo endpoint and reads
name, email, picture, and email_verified from the response. Map these claims in your
provider if they are not emitted by default.
Without the UserInfo Endpoint
Some providers don't let a browser call the UserInfo endpoint, for example because it doesn't allow
cross-origin requests from your site. Set disableUserInfo to true and Zudoku never calls it:
zudoku.config.ts
Zudoku also skips UserInfo when the discovery document doesn't advertise a userinfo_endpoint. The
option works the same way for the entra and auth0 providers.
Without UserInfo, the profile is built from the claims of the ID token that the token endpoint returns at sign-in:
- The ID token must contain
name,email,picture, andemail_verified. Most providers add them for theprofileandemailscopes, but some only put them in the UserInfo response unless you configure them for the ID token. - Custom claims in the ID token, such as roles or groups, are part of the profile. Claims that
describe the token itself (
iss,aud,exp,nonceand the like) are not. - Sign-in fails if the token response contains no ID token, so keep the
openidscope.
In SSR mode the server checks the access
token on every request. Without UserInfo, the access token must be a JWT signed by your provider.
Zudoku verifies it against the provider's jwks_uri and requires:
- the issuer's
issand anexp; - that it was issued to your app: with
audienceset, itsaudmust matchaudience; without it, yourclientIdmust appear inaud,azp,client_idorcid(Okta). Setaudienceif your provider puts none of these in its access tokens.
The server-side profile then comes from the access token's claims, so add name and email to it
if you show them. Opaque access tokens can't be verified this way, so the server rejects them and
the user is signed out on the next page load.
Local Development with an HTTP Issuer
oauth4webapi (the library Zudoku uses under the hood) rejects issuers that don't use https:// by
default, since OIDC requires TLS in production. If you're running an identity provider locally over
plain HTTP (e.g. a dockerized Keycloak on http://localhost:9090), set allowInsecureRequests to
true so discovery and token requests are allowed to use http://:
zudoku.config.ts
Only enable this for local development. Never set allowInsecureRequests to true against a
production issuer.
Troubleshooting
- Discovery fails: verify
<issuer>/.well-known/openid-configurationresolves and matches theissuervalue in the document. - CORS errors on token / userinfo: add your site origin to the provider's allowed origins. If
your provider can't allow browser calls to the UserInfo endpoint, set
disableUserInfototrue(see Without the UserInfo Endpoint). - Redirect URI mismatch: the URI registered with the provider must match the Zudoku origin exactly, including protocol and port.
- Missing profile fields: ensure
profileandemailscopes are granted and that the provider includesname,email, andpictureclaims in the UserInfo response, or in the ID token whendisableUserInfoistrue.