Migration Guide: Legacy JWT to OIDC

1. Run the Database Migration

alembic upgrade head

This migration adds oidc_sub and oidc_issuer columns to the users table and makes hashed_password nullable, allowing users without a local password.

2. Configure OIDC Environment Variables

Set the following in your environment (see .env.example for the full list):

OIDC_ENABLED=true
OIDC_PROVIDER=standard
OIDC_ISSUER=https://idp.example.eu/realms/ai4drpm
OIDC_CLIENT_ID=ai4drpm
OIDC_CLIENT_SECRET=<your-client-secret>
OIDC_REDIRECT_URI=https://app.example.eu/api/auth/callback

3. First OIDC Login — Automatic Account Linking

On first OIDC login, provision_from_oidc_claims matches existing users by email and automatically sets oidc_sub. No manual data migration is required for existing users who log in via OIDC.

4. Verify All Users Are Linked

Before removing legacy login, confirm all active users have oidc_sub populated:

SELECT username, email, oidc_sub FROM users WHERE oidc_sub IS NULL AND disabled = false;

Users who have not logged in via OIDC yet will still have oidc_sub = NULL. Notify them to log in once before the legacy endpoint is removed.

5. Optional: Remove Legacy Login

Once all users have oidc_sub populated:

  1. Set OIDC_ENABLED=true permanently in your deployment configuration.

  2. Remove SECRET_KEY from the environment if legacy JWT tokens are no longer needed.

  3. The POST /api/auth/login endpoint remains available but can be disabled at the reverse-proxy level if desired.