Keycloak SSO Setup
==================

Task Dashboard uses Keycloak as its OIDC provider via django-allauth. This page
walks through creating the Keycloak client and mapping groups so they sync to
Django groups on each login.


Keycloak is **optional** — if you only need local email/password accounts, leave
all ``KEYCLOAK_*`` variables empty and set ``ACCOUNT_ALLOW_REGISTRATION=True``.

Step 1: Create a Realm
----------------------

In the Keycloak Admin Console, create or select the realm you want to use.
The realm URL will be the base of your ``KEYCLOAK_SERVER_URL``.

Step 2: Create the Client
--------------------------

1. Navigate to **Clients → Create client**.
2. Set **Client type** to ``OpenID Connect``.
3. Set **Client ID** — this becomes your ``KEYCLOAK_CLIENT_ID``.
4. Enable **Client authentication** (confidential client).
5. Set **Valid redirect URIs** to ``https://<your-domain>/accounts/keycloak/login/callback/``.
6. Set **Valid post logout redirect URIs** to ``https://<your-domain>/``.
7. Save the client and copy the **Client secret** from the **Credentials** tab —
   this is your ``KEYCLOAK_CLIENT_SECRET``.

Step 3: Add the Groups Mapper
------------------------------

Task Dashboard reads a ``groups`` claim from the ID token to sync group
memberships. Add a mapper to include it:

1. Open the client → **Client scopes** → click the dedicated scope (e.g.
   ``<client-id>-dedicated``).
2. **Add mapper → By configuration → Group Membership**.
3. Set **Name** to ``groups``.
4. Set **Token Claim Name** to ``groups``.
5. Enable **Add to ID token** and **Add to access token**.
6. Set **Full group path** to ``Off`` so claim values are plain group names
   (e.g. ``support``, not ``/support``).
7. Save.

Step 4: Configure Environment Variables
-----------------------------------------

Add the following to your ``.env``::

    KEYCLOAK_CLIENT_ID=<your-client-id>
    KEYCLOAK_CLIENT_SECRET=<your-client-secret>
    # Base realm URL — no trailing slash
    KEYCLOAK_SERVER_URL=https://id.example.com/realms/myrealm

Step 5: Group Sync Behaviour
------------------------------

On each SSO login the ``SocialAccountAdapter`` reads the ``groups`` claim and:

* Creates any Django group that does not yet exist.
* Assigns the user to all groups listed in the claim.
* Removes the user from any groups that were previously synced via SSO but are
  no longer present in the claim.
* Groups that were manually assigned in the Django Admin are never touched by SSO.

Groups matching ``default-roles-*``, ``offline_access``, and
``uma_authorization`` are silently ignored.

If the Keycloak token contains no ``groups`` claim the user is placed in the
``sso-default-fallback`` group as a safe fallback.

Troubleshooting
---------------

**"Login failed: no token returned"** — Verify the redirect URI matches exactly
(including the trailing slash).

**Groups not syncing** — Check that the mapper is attached to the **dedicated
scope** of the client (not a shared scope) and that ``Full group path`` is off.

**Admin cannot log in via SSO** — By default ``DJANGO_ADMIN_FORCE_ALLAUTH=True``
routes all admin logins through SSO. Set it to ``False`` to allow the standard
Django admin login form as a fallback.