FabledGrimoire/docs/sso-oauth.md

OAuth / OIDC SSO Setup

Grimoire supports single sign-on via any OpenID Connect provider. This guide covers Authentik, but the same pattern works with Keycloak, Authelia, Zitadel, etc.

1. Create the provider in Authentik

1. Log in to the Authentik admin UI.
2. Go to Applications → Providers → Create → OAuth2/OpenID Provider.
3. Fill in:
   • Name: Grimoire (or whatever you like)
   • Authorization flow: your default authorization flow
   • Client type: Confidential
   • Redirect URIs: https://your-fabled-domain/api/auth/oauth/callback (must match BASE_URL exactly, including scheme and any path prefix)
4. Note the generated Client ID and Client Secret.
5. Go to Applications → Create, give it a name, and bind it to the provider you just created.
6. Note the Issuer URL from the provider detail page — it looks like:

   https://auth.example.com/application/o/fabled-assistant/
   

2. Configure Grimoire

Add the following environment variables to the app service in docker-compose.yml:

services:
  app:
    environment:
      # --- Required ---
      OIDC_ISSUER: "https://auth.example.com/application/o/fabled-assistant/"
      OIDC_CLIENT_ID: "abc123xyz"
      OIDC_CLIENT_SECRET: "supersecret"

      # --- Optional ---
      # Scopes to request (default: "openid profile email")
      # OIDC_SCOPES: "openid profile email"

      # Disable local username/password login once SSO is working
      # LOCAL_AUTH_ENABLED: "false"

      # Make sure BASE_URL matches the redirect URI you registered
      BASE_URL: "https://your-fabled-domain"

Docker Secrets alternative: Use OIDC_CLIENT_SECRET_FILE pointing to a Docker secret file instead of OIDC_CLIENT_SECRET.

Rebuild and restart:

docker compose up --build -d

3. Verify

1. Open /api/auth/status — it should return:

   { "oauth_enabled": true, "local_auth_enabled": true, ... }
   

2. Go to the login page — you should see a "Login with [Provider]" button.
3. Click it → redirected to provider → authenticate → redirected back → logged in.
4. Check /api/auth/me to confirm your user record.

4. Account Linking

When a user logs in via OAuth for the first time, Grimoire checks in this order:

1. Existing OAuth sub — returns that user immediately.
2. Matching email — if a local account already exists with the same email, the OAuth identity is linked to it automatically. The user retains all their notes and tasks.
3. New user — a fresh account is created. Username defaults to preferred_username from the provider; if taken, _2, _3, etc. is appended.

5. Disable Local Login (Optional)

Once everyone is using SSO:

LOCAL_AUTH_ENABLED: "false"

The backend will reject any POST /api/auth/login or POST /api/auth/register request with a 403. The login page will only show the SSO button.

Warning: Make sure at least one account has been linked via OAuth before disabling local login, or you will be locked out.

6. Other Providers

Provider	Issuer URL format
Authentik	https://auth.example.com/application/o/<app-slug>/
Keycloak	https://keycloak.example.com/realms/<realm>
Authelia	https://auth.example.com
Zitadel	https://your-instance.zitadel.cloud
Google	https://accounts.google.com

The OIDC discovery endpoint (<issuer>/.well-known/openid-configuration) must be publicly reachable from the Grimoire container (server-to-server call at login time).