Migration Guide: Legacy JWT to OIDC
===================================

1. Run the Database Migration
----------------------------

.. code-block:: bash

   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):

.. code-block:: text

   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:

.. code-block:: sql

   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.