Single Sign-On with Keycloak

This guide covers signing in to SWIRL with Keycloak (OpenID Connect), and obtaining each user's Microsoft 365 (Microsoft Graph) access through Keycloak so there is no separate Microsoft sign-in.

1. Assumptions and supported scope

1.1 What is supported

1.2 Environment assumptions

1.3 How Microsoft access arrives

• SWIRL does not run its own Microsoft OAuth sign-in for these users; the Microsoft token arrives through Keycloak.
• No application-only Graph access; everything is delegated to the signed-in user.
• This guide covers wiring Keycloak and SWIRL together, not installing either product.

2. Architecture at a glance

Four parties: the SWIRL Galaxy front end in the browser, the SWIRL backend, your Keycloak realm, and Microsoft Entra with Microsoft Graph brokered behind Keycloak.

2.1 Two configuration surfaces

SWIRL's Keycloak settings live in two places that must agree:

The clientId and issuer in oidcConfig, and the client_id and endpoints in the Authenticator row, must reference the same Keycloak client and realm. If the login button is missing, check the environment surface; if login starts but the backend rejects it, check the Authenticator row.

3. Phase 1: Login with Keycloak

Users log in by clicking a Login with Keycloak button on /galaxy/login. The button runs a browser-based OpenID Connect flow (Authorization Code with PKCE) against Keycloak; the browser obtains the token, hands it to the SWIRL backend for validation, and SWIRL provisions a standard, non-administrator account on first login.

3.1 Make the button appear (the environment surface)

The button shows on /galaxy/login only when the served oidcConfig lists Keycloak as active. That block is generated from two environment variables; setting the Authenticator row in the admin console does not add the button. In the SWIRL app's .env:

KEYCLOAK_ISSUER=https://<keycloak-host>/realms/<realm>
#   include the legacy path if your Keycloak uses it: https://<keycloak-host>/auth/realms/<realm>
KEYCLOAK_AUTH_CLIENT_ID=<keycloak-client-id>
KEYCLOAK_SCOPE=openid email profile      # optional; this is the default

python swirl.py config_default_api_settings   # writes oidcConfig.Keycloak; then hard-refresh /galaxy/login

services:
  swirl:
    environment:
      KEYCLOAK_ISSUER: ${KEYCLOAK_ISSUER}
      KEYCLOAK_AUTH_CLIENT_ID: ${KEYCLOAK_AUTH_CLIENT_ID}
      KEYCLOAK_SCOPE: ${KEYCLOAK_SCOPE}

A container restart then runs config_default_api_settings on startup. For a deployment that serves Django collected static, also run python manage.py collectstatic --noinput. Confirm the served default config now has oidcConfig.Keycloak.active = true.

3.2 Keycloak client

The button runs the flow in the browser and holds only the client id, never a secret, so:

1. Client authentication = Off (a public client). A confidential client cannot complete this browser flow.
2. PKCE Method: S256.
3. Valid redirect URIs include https://<swirl-fqdn>/galaxy/oidc-callback; Web origins https://<swirl-fqdn>.
4. Default scopes openid email profile; email claim present and verified.

3.3 SWIRL Authenticator (token validation)

After the browser posts the token, the SWIRL backend validates it by calling userinfo, so a Keycloak Authenticator row must exist. It ships in swirl/fixtures/DefaultAuthenticators.json (loaded by python swirl.py load_data); substitute the placeholders, or set the same values in the admin console:

user_data_url  https://<keycloak-host>/realms/<realm>/protocol/openid-connect/userinfo
jwks_uri       https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs
client_id      <keycloak-client-id>          # same as KEYCLOAK_AUTH_CLIENT_ID
app_uri        https://<swirl-fqdn>

For the login-page button the fields that matter are user_data_url and jwks_uri. The code-exchange fields (use_basic_auth, exchange_code_params, token_uri) are not used by this flow; they belong to the server-side flow in Section 3.5.

3.4 What the user sees

Keycloak users click Login with Keycloak, authenticate at Keycloak (password, MFA, whatever the realm requires), and are returned and logged in, with their SWIRL account created on first login. The username and password form on the same page is for local SWIRL accounts only (for example the admin); externally authenticated users have no local password and do not use it.

3.5 Alternate: the server-side flow

SWIRL also exposes a server-side redirect flow at /swirl/callback/keycloak-callback, used by the user-menu "connect" action and any code-exchange login. It uses the same Authenticator row but exchanges the code on the server. If you use it, register /swirl/callback/keycloak-callback as a redirect URI and match the client type:

4. Phase 2: Microsoft 365 token delegation

After a Keycloak login, SWIRL obtains the user's Microsoft Graph token through Keycloak and stores it under the Microsoft identity for the M365 connectors. Choose one method per Authenticator with broker_mode.

Use the exchange method unless token exchange is unavailable, or the Microsoft refresh issue in Section 4.6 affects your Keycloak version. The harvest method requires SWIRL to hold a copy of the broker's Azure application credentials, which exchange avoids.

4.1 The two methods

4.2 Keycloak shared prerequisites

1. Configure Microsoft Entra ID as a brokered identity provider in the realm SWIRL logs into. Note its alias, for example microsoft; it is reused exactly in Section 4.8.
2. Set the identity provider's default scopes to the Microsoft Graph delegated scopes SWIRL needs, plus offline_access. These broker scopes are distinct from the login scopes in Section 3; see Appendix A.

4.3 Keycloak exchange method

1. Enable token exchange on Keycloak. The exact feature flags depend on the major version: older versions use the preview features token-exchange and admin-fine-grained-authz; newer versions ship a generally-available standard token exchange with a different setup. This is the most version-sensitive step in the integration; confirm the procedure for the deployed version first.
2. Create a confidential client for SWIRL to perform the exchange, separate from the public login client. Record its client id and secret for Section 4.8.
3. Grant that confidential client the token-exchange permission targeting the Entra identity provider. Without this grant the exchange returns an authorization error.

4.4 Keycloak harvest method

1. On the Entra brokered identity provider, set Store Tokens and Stored Tokens Readable to on.
2. Grant the SWIRL login client the broker read-token role, for example by adding broker:read-token to the realm default roles, so its access token can read the stored broker token.

4.5 Microsoft Entra configuration

1. The Entra application Keycloak brokers must hold the delegated Microsoft Graph permissions SWIRL needs, with administrator consent. Typical sets:
   • OneDrive and SharePoint: Files.Read.All, Sites.Read.All
   • Outlook mail: Mail.Read
   • Teams, Calendar, and others: as required
2. Include offline_access so a refresh token can be issued.
3. Set the Entra application redirect URI to the Keycloak broker endpoint: https://<keycloak-host>/realms/<realm>/broker/<alias>/endpoint.

4.6 Microsoft token refresh and Keycloak version

4.7 Conditional Access, MFA, and token lifetimes

SWIRL refreshes tokens to run searches outside an active sign-in session, including scheduled and background searches. Confirm that no Conditional Access or MFA policy on the brokered Entra app forces interactive sign-in on token refresh, and that the access-token and refresh-token lifetimes are long enough for background use. A policy that requires a fresh interactive sign-in will break unattended Graph calls regardless of method.

4.8 SWIRL Authenticator brokering fields

Set these on the same Keycloak Authenticator from Section 3.3:

5. Validation and observability

5.1 What to verify

1. The Galaxy login page shows a Login with Keycloak button.
2. A Keycloak login creates a SWIRL user mapped from the email claim. Confirm it is not a superuser and lands in the standard auto-provisioned group (SWIRL admin, Users section).
3. After login, a per-user Microsoft token is stored under the Microsoft identity.
4. An M365 search returns content only if an M365 SearchProvider is active and configured to use the Microsoft identity. The token alone is not enough; confirm at least one M365 provider, such as OneDrive or SharePoint, is active before testing search.

5.2 Reading the logs

Every Keycloak interaction emits one structured line through a dedicated logger; token values are never logged, only lengths, booleans, and expiries:

grep 'KC ' logs/django.log logs/celery-*-worker.log

# example lines
KC login    status=ok  idp=Keycloak
KC exchange status=ok  idp=Keycloak alias=microsoft http=200 has_refresh=false expires_in=34
KC harvest  status=ok  idp=Keycloak alias=microsoft http=200

6. Troubleshooting

Appendix A: Environment variables and scopes

Applied with python swirl.py config_default_api_settings.

The three scopes

Appendix B: Authenticator fields reference

The Keycloak entry in DefaultAuthenticators.json ships these pre-set; in normal use an admin edits only the four placeholders in Section 3.3 and the brokering fields in Section 4.8.

Appendix C: References

• RFC 8693, OAuth 2.0 Token Exchange, the mechanism behind the exchange method.
• Keycloak issue 32361 (open), Microsoft token refresh fails due to a missing scope parameter; gates exchange-mode refresh for Microsoft. See Section 4.6.
• Keycloak issues 14644 and 46373, brokered external IdP tokens are not refreshed on retrieve; context for why harvest refreshes against Microsoft directly.