# Keycloak + Lutril: setup guide

> Lutril governs Keycloak as an application, not as your identity provider. You point it at one realm, and Lutril creates the account with the realm role that was requested, then disables it at the deadline. Most teams point it at master, because the population worth governing is the people who can reach the Keycloak admin console, not the end users a business realm holds for your own products. Lutril governs the account lifecycle, not individual role mappings. A request from somebody who already has a working Keycloak account is refused and sent to a human, because adding a realm role to an account Lutril did not create would be permanent, and a grant that cannot be taken back is not a time-boxed grant. Removal disables the account and ends its open sessions, and never deletes, so the person's sub, their federated identity links, their consents and their group memberships all survive and the account is switched back on for the next approved request. No password is ever generated: accounts are created with no credentials at all, so they authenticate through the realm's own identity providers. Two things to know about what you will see in Lutril. Accounts from a user federation provider such as LDAP are flagged, because a provider in read-only edit mode refuses the disable and Lutril reports the removal as failed rather than marking the grant expired. And Keycloak records no last sign-in on the account, so Lutril reads the realm's LOGIN events where that store is switched on and shows nothing where it is off, rather than a zero that would read as a stale account.

Source: https://www.lutril.com/integrations/keycloak
Category: Security
Auth: service_account
Last verified: 2026-09-29

---

## Setup

1. Lutril's Keycloak form has four required fields: Keycloak URL, Realm to govern, Service account client ID and Client Secret. Everything below is about finding those four, in that order, and checking them before you paste them.
2. Sign in to the Keycloak admin console. The root of that console is your Keycloak URL, for example https://sso.example.com. It must be https. If your server runs under a relative path, include it: Keycloak before version 17 serves under /auth, so the value would be https://sso.example.com/auth. That is the Keycloak URL field.
3. Pick the realm with the selector at the top of the left sidebar. Choose master to govern the people who administer Keycloak itself, which is what most teams want. The name shown in that selector, exactly as written, is the Realm to govern field. It is case sensitive.
4. Staying in that realm, go to Clients → Create client. Leave the client type as OpenID Connect and set the Client ID to lutril-governance. That is the Service account client ID field. Click Next.
5. On the capability config step, turn Client authentication ON and Service accounts roles ON. Turn Standard flow and Direct access grants OFF: nobody signs in through this client, it only authenticates as itself. Click Next, then Save. On Keycloak older than version 19 the same two settings are called Access Type, which you set to confidential, and Service Accounts Enabled.
6. Open the client's Credentials tab and copy the Client secret. That is the Client Secret field, and it is the last of the four. If there is no Credentials tab, Client authentication was left off in the previous step: that is the single most common reason this setup stalls. You can regenerate the secret here at any time, which invalidates the old one immediately.
7. Open the client's Service accounts roles tab → Assign role → change the filter to Filter by clients. Assign view-users, manage-users and view-clients from realm-management. Add query-groups too if you want the group picker when granting.
8. [object Object]
9. [object Object]
10. In Lutril, open Settings → Integrations → Keycloak. Paste the four values into Keycloak URL, Realm to govern, Service account client ID and Client Secret. Leave Client's own realm blank.
11. Fill in Client's own realm only if the service account client lives somewhere other than the realm it governs, for example a client in master that administers a business realm. In that case also assign that business realm's realm-management roles to the same service account.
12. Name your access levels after Keycloak's own realm roles, so the two lists are the same words. Lutril grants the realm role by name, and no further mapping is needed.
13. If you want just-in-time requests approved automatically, preset a default realm role for this app in Lutril's catalogue editor. Lutril refuses an automatic grant with no role rather than creating an account that reaches nothing, and sends that request to a human instead.
14. Save. Lutril exchanges the secret for a token, counts the realm's users and reads back the realm roles, so a connection that cannot do the job is refused now rather than at the first request.

## Access requested

- view-users, from the realm-management client, so Lutril can list the realm's accounts and read one back after a change.
- manage-users, from the realm-management client, so Lutril can create an account, assign a realm role and disable the account at the deadline.
- view-clients, from the realm-management client, so Lutril can tell which accounts hold administrative roles and flag them in access reviews.
- query-groups, from the realm-management client, only if you want the group picker on the provisioning card.
- Never requested and never used: any permission to delete a user. Lutril's removal path disables; permanent deletion stays a human action in the Keycloak console.

## References

- [Keycloak documentation](https://www.keycloak.org/docs-api/latest/rest-api/index.html)
- [Keycloak console](https://www.keycloak.org/docs/latest/server_admin/index.html#_service_accounts)
- [Admin REST API reference](https://www.keycloak.org/docs-api/latest/rest-api/index.html)
- [Service accounts (client credentials)](https://www.keycloak.org/docs/latest/server_admin/index.html#_service_accounts)
- [Realm roles and role mappings](https://www.keycloak.org/docs/latest/server_admin/index.html#assigning-permissions-using-roles-and-groups)
- [Dedicated admin clients and realm-management roles](https://www.keycloak.org/docs/latest/server_admin/index.html#_per_realm_admin_permissions)