Single Sign On

Whittle supports single sign-on with any OpenID Connect provider: Authentik, Keycloak, Authelia, Zitadel, Pocket ID, Kanidm, Google, Microsoft Entra ID, Okta, Auth0 and others.

What you need

• Whittle reachable at a fixed address, ideally over HTTPS (HTTPS and Reverse Proxy).
• An application (client) registered with your provider.

1. Register Whittle with your provider

Create an OAuth2 / OpenID Connect application with:

Setting	Value
Type	Confidential (web application), authorization code flow
Redirect URI	https://cad.example.com/api/auth/oidc/callback (your address + /api/auth/oidc/callback)
Scopes	openid, email, profile

Copy the client ID, the client secret and the issuer URL.

2. Configure Whittle

Add to /etc/whittle/whittle.env (or your Docker settings):

WHITTLE_AUTH=local,oidc            # or just: oidc
WHITTLE_PUBLIC_URL=https://cad.example.com
WHITTLE_OIDC_ISSUER=<issuer URL>
WHITTLE_OIDC_CLIENT_ID=<client ID>
WHITTLE_OIDC_CLIENT_SECRET=<client secret>
WHITTLE_OIDC_NAME=Authentik        # the text on the sign-in button

Restart Whittle. The sign-in screen now has a Sign in with Authentik button (or whatever name you chose).

With local,oidc you keep username-and-password sign-in as well, which is handy as a fallback administrator account.

Issuer URLs for common providers

Provider	Issuer URL
Authentik	https://auth.example.com/application/o/<application-slug>/ (with the trailing slash)
Keycloak	https://kc.example.com/realms/<realm>
Authelia	https://auth.example.com
Zitadel	https://<instance>.zitadel.cloud
Pocket ID	https://id.example.com
Google	https://accounts.google.com
Microsoft Entra ID	https://login.microsoftonline.com/<tenant-id>/v2.0
Okta	https://<org>.okta.com
Auth0	https://<tenant>.auth0.com/

Tip: the issuer URL is the address that has /.well-known/openid-configuration under it. Open <issuer>/.well-known/openid-configuration in a browser: if you see JSON, it's right.

Authentik

1. Applications ▸ Providers ▸ Create ▸ OAuth2/OpenID Provider. Client type Confidential, redirect URI as above, signing key: any certificate.
2. Applications ▸ Applications ▸ Create, slug whittle, provider: the one you just made.
3. Issuer: https://auth.example.com/application/o/whittle/

Keycloak

1. In your realm: Clients ▸ Create client, type OpenID Connect, client ID whittle.
2. Turn on Client authentication; leave Standard flow on.
3. Valid redirect URIs: the redirect URI above. Copy the secret from the Credentials tab.
4. Issuer: https://kc.example.com/realms/<realm>

Authelia

identity_providers:
  oidc:
    clients:
      - client_id: whittle
        client_name: Whittle
        client_secret: '<hashed secret>'
        authorization_policy: two_factor
        redirect_uris: [https://cad.example.com/api/auth/oidc/callback]
        scopes: [openid, email, profile]
        token_endpoint_auth_method: client_secret_basic

Google

In Google Cloud Console: APIs & Services ▸ Credentials ▸ Create credentials ▸ OAuth client ID, type Web application, add the redirect URI. Issuer https://accounts.google.com. Use WHITTLE_OIDC_AUTO_CREATE=false and add people first if you don't want every Google account to be able to sign up.

Microsoft Entra ID

App registrations ▸ New registration, platform Web, redirect URI as above. Create a secret under Certificates & secrets. Issuer https://login.microsoftonline.com/<tenant-id>/v2.0.

Who gets in

• By default, anyone your provider lets sign in to Whittle gets an account on first sign-in. Restrict access at the provider (Authentik policies, Keycloak roles, Google's internal app setting…), or invite people one by one:

  1. Set WHITTLE_OIDC_AUTO_CREATE=false.
  2. In Account ▸ Manage users ▸ Add a user, enter their username and the email address they sign in with, and leave the password empty.
  3. The first time they use single sign-on, Whittle links the sign-in to that account. The provider must send the email with email_verified: true. Most do (Google, Keycloak and Authentik with verified emails); some, such as Microsoft Entra ID, may not. In that case keep automatic account creation on and restrict access at the provider instead.

  Only these password-less invited accounts are ever linked by email, so nobody can sign up with someone else's address and capture their sign-in.

• The very first account on a new server becomes the administrator, whichever way it signs in.

• Accounts are matched by the provider's issuer and user ID, never by email address, so a changed email at the provider can't take over someone else's account.

Security

Whittle uses the authorization code flow with PKCE and a nonce, checks the ID token's signature, issuer, audience and expiry, and only redirects back to its own pages.

Troubleshooting

Symptom	Fix
Server won't start: "WHITTLE_PUBLIC_URL is required for OIDC"	Set WHITTLE_PUBLIC_URL.
Provider says the redirect URI is invalid	It must match exactly, including https and no trailing slash: <WHITTLE_PUBLIC_URL>/api/auth/oidc/callback.
"Couldn't reach the sign-in provider"	Check WHITTLE_OIDC_ISSUER (try the .well-known URL above from the server: curl <issuer>/.well-known/openid-configuration).
Signed in at the provider but back at Whittle's sign-in screen with an error	Read the message on the sign-in screen and the server log (journalctl -u whittle). "The sign-in provider rejected the login" usually means a wrong client secret; "The ID token couldn't be verified" often means the server's clock is off.
"You don't have an account here yet"	WHITTLE_OIDC_AUTO_CREATE=false is set and there's no invited account for this person's email. Add them with the exact email their provider reports, and no password.
"The sign-in took too long or was already used"	Start the sign-in again. Sign-in attempts expire after 10 minutes.
"This account is disabled"	An administrator disabled the account in Manage users.