Keycloak Setup

By default variantgrid uses Django inbuilt authentication, but it can be configured to use OpenID Connect. The code is in the oidc_auth app; Shariant runs on this.

We have used Keycloak for our default installation.

Install Keycloak https://www.keycloak.org/guides

Version note: Keycloak 17+ runs on Quarkus rather than WildFly. That changed a lot of the operational detail from the older docs — configuration is now conf/keycloak.conf (or KC_* environment variables) and bin/kc.sh rather than standalone.xml, and the /auth path prefix was dropped from URLs. The sections below give the Quarkus form.

SSL Termination / Forwarding

We typically handle SSL via nginx and pass internal http requests to Keycloak, so Keycloak needs to trust the proxy's forwarded headers. In conf/keycloak.conf:

proxy-headers=xforwarded
hostname=https://auth.yourdomain.com

See https://www.keycloak.org/server/reverseproxy

Postgres Datastore

Make a new database on your database server called keycloak, then point Keycloak at it (rather than the dev-mode H2) in conf/keycloak.conf:

db=postgres
db-url=jdbc:postgresql://localhost/keycloak
db-username=keycloak
db-password=<password>

See https://www.keycloak.org/server/db

systemd

Keycloak no longer ships WildFly-derived systemd scripts. Write a unit that runs bin/kc.sh start --optimized as a dedicated keycloak user, eg:

[Unit]
Description=Keycloak
After=network.target postgresql.service

[Service]
User=keycloak
ExecStart=/opt/keycloak/bin/kc.sh start --optimized
Restart=on-failure

[Install]
WantedBy=multi-user.target

Run bin/kc.sh build after config changes that affect the optimized build.

Realm

Create a Realm (A realm is a silo of users and applications, adding a user to realm 1 is completely independent of adding them to realm 2). The realm we have gone for is "AGHA".

If this is on a test/dev machine, you'll need to configure the realm's login tab to say "Require SSL" none and hit "save".

For a production server you'll want to provide "Forgot password" functionality, potentially "Verify email" and then setup the connection to the Email server.

Client

Create a client of variantgrid, there will be 1 client per application that needs the login. Turn Client authentication on (this is what older Keycloak called Access Type "confidential").

Set Valid Redirect URLs to *

Base URL, Admin URL and Web Origins to be the root of the URL hosting variantgrid

In Credentials choose "Client Authenticator" of "Client Id and Secret", copy the secret as you'll need to add it to variantgrid to authenticate itself against Keycloak. Ensure Standard Flow is on, and Direct Access Grants Enabled

Mappers

Mappers allow us to add data more than just the absolute basics for OpenID Connect. variantgrid uses group membership to work out what data access the user will have. Inside variantgrid, create a Mapper called "groups" (hit the Create button, not Add builin) For Mapper Type, select "Group Membership"

For Token Claim Name, enter "groups"

Turn on Full group path

Turn on the other 3 toggles so the group data is sent when needed (TODO check to see if we really need this in all three)

Also add the built in properties of username email given name family name

Now repeat for a new client called "variantgrid-client-tools" except access is set to "public" (so no secret key is needed)

Groups

Create a group called variantgrid.

Select that group and create nested groups under it. oidc_auth/backend.py recognises these special ones:

• /variantgrid/admin → maps to is_superuser
• /variantgrid/bot → marks the account as a bot (bots are blocked during maintenance mode)
• /variantgrid/tester → testers are allowed to log in during maintenance mode

Lab membership comes from a separate top-level group tree, /associations/..., whose paths match Lab group_name values — see User / Lab Assignment. A user with no groups under either /variantgrid/ or /associations/ is deactivated on login with "This account doesn't belong to any labs".

All other groups under /variantgrid/ will be mapped to django groups and created on demand. Note that no nesting is supported.

settings.OIDC_REQUIRED_GROUP, if set, gates login on membership of that group — this is how separate demo/test/production environments keep each other's users out.

Note that any user in the system will be considered a valid Keycloak user who will automatically belong to "public" group. If need be this behaviour can be changed in oidc_auth/backend.py

See also

Keycloak Integration