Keycloak login
strazad trusts your Keycloak realm, people sign in to Straza with their own Keycloak identity, and Straza never holds a password.
- Who
- Keycloak admin and Straza admin
- Where
- Keycloak admin console, strazad config file, and a terminal with strazactl
- Profile
- Enterprise only
In short
strazad trusts the ID tokens of your Keycloak realm, so people sign in with their own Keycloak identity and Straza holds no password. You create a client without a secret and point strazad at the realm. Your IGA still decides who exists, and a sign-in finds the account your IGA provisioned.
On this page
You make Keycloak the login provider of an enterprise Straza, as the admin of both. You work in the Keycloak admin console, in strazad’s configuration file and in a terminal. At the end strazad trusts your realm, you have signed in to the console with your own Keycloak identity, and strazactl reads your account on an admin API token you minted there.
In the enterprise profile a person signs in at Keycloak, and strazad verifies the ID token Keycloak minted against the realm’s published keys. Straza holds no password, so passwords, second factors and session policy belong to Keycloak. Who exists still belongs to your identity manager, because a verified token opens a door only for an account that provisioning created. Keycloak is the login factor and never the source of record.
Before you start
- Keycloak administration for one realm.
- A shell with
strazactl, and access to strazad’s configuration.
The examples ran against the demo stack. Its realm straza at http://localhost:8480 is imported from a file in the repository, so every setting below is the one that file carries.
Create the client
In your realm, create a client with the client id
strazaand these settings. Every row but the last is what the demo stack’s realm ships.Setting Value Why Client authentication off straza enrollruns on people’s machines and the console in their browsers, and neither has a secret to keepStandard flow on the browser sign-in of straza enrolland of the consoleValid redirect URIs http://127.0.0.1/callbackthe browser hands the answer to a port on the person’s own machine. Registered without a port, the redirect matches any port in Keycloak 25 and 26 Valid redirect URIs the address people open the console at, normally your strazad public URL, followed by /console/signin, such ashttps://straza.example.com/console/signinKeycloak sends the console’s and the self-service page’s sign-in back to this address, which the browser builds from the origin it opened, so add one for each address people open the console at Proof Key for Code Exchange Code Challenge Method S256 Straza sends an S256 challenge with every browser sign-in OAuth 2.0 Device Authorization Grant on the sign-in with a code that straza enroll --use-device-codepicksWeb origins the origin people open the console at, normally your strazad public URL, such as https://straza.example.comthe console redeems its sign-in at Keycloak from the browser Direct access grants off no Straza login uses a password grant On the demo stack the console addresses are
http://localhost:8420/console/signinandhttp://127.0.0.1:8420/console/signin, with both origins under Web origins. The demo stack’s realm turns direct access grants on for its non-interactive seeder alone, and Straza itself never uses that grant. Keycloak signs with RS256 by default, and strazad accepts RS256, ES256 and EdDSA. Keycloak putsauth_timein its ID tokens by default, and Straza needs that claim to accept a browser sign-in for a machine. No fixed port is needed here, so leaveoidc.loopbackPortat 0.If this fails
identity provider ... does not advertise a device_authorization_endpoint. Enable the OAuth 2.0 device authorization grant for client "straza"straza enroll --use-device-codestops with this sentence when the device grant is off. Turn on OAuth 2.0 Device Authorization Grant on the client.- A sentence that starts
Your identity provider refused the sign-in and said: - Keycloak refused the browser sign-in and sent its reason, which the sentence quotes. When Standard flow is off, turn it on.
- Keycloak shows an error about
redirect_uriin the browser - The client has no loopback redirect, so Keycloak never sends the answer back and the command gives up after 5 minutes. Add
http://127.0.0.1/callbackunder Valid redirect URIs.
Point strazad at the realm
The
oidcblock of strazad’s configuration names the issuer and the client id. The demo stack sets these values on the strazad container:oidc: issuer: http://localhost:8480/realms/straza discoveryUrl: http://keycloak:8080/realms/straza/.well-known/openid-configuration clientId: straza jitProvision: falseSTRAZA_OIDC_ISSUERandSTRAZA_OIDC_CLIENT_IDare the environment forms of the first and third keys.CLI onlyThe console’s Settings, tab Configuration, shows Identity provider and Sign-in creates users and changes neither. You set them in the file.
jitProvisionstaysfalsein enterprise, because provisioning decides who exists. A person Keycloak knows and the identity manager has not provisioned is refused at login with the reason “identity not provisioned”. Standalone and enterprise compared shows the default of each profile.strazad runs OIDC discovery against the issuer at boot and refuses to start when the issuer is unreachable. Refusing to start is safer than serving logins it cannot verify.
Set
oidc.discoveryUrl, orSTRAZA_OIDC_DISCOVERY_URL, when strazad cannot reach the issuer’s own address. The demo stack needs it, because strazad runs in a container and reaches Keycloak by the internal namekeycloak. The document fetched there must nameoidc.issuerexactly, byte for byte, or strazad refuses to boot, and every token must still carry that issuer. Left empty, the default, strazad fetches the document at the issuer.A fresh enterprise deployment has no administrator.
oidc.bootstrapAdminnames one Keycloak username whose first verified login is provisioned despitejitProvision: falseand assignedstraza-admin. It works only while nostraza-adminassignment exists, so the setting goes inert as soon as your identity manager manages that role. Remove the line after the bootstrap. The demo stack points it at a transientseed-bootstrapuser, which its seeder locks once the admin the identity manager assigned has landed.
How a token finds its account
strazad maps a verified ID token to a local account in this order:
- The token’s
subis matched against the account’sexternalId. - If nothing matches,
preferred_usernameis matched against the account’suserName. A match fills inexternalIdwith thissub, which links the account once. A username already bound to a different subject is refused with a sentence that says the account “is linked to another identity at your identity provider”, and is never taken over. - If nothing matches and JIT is off, the login is refused.
Keep Keycloak usernames equal to the userName your identity manager provisions, and midPoint keeps them equal when it masters both sides. If your identity manager sends externalId, it must be the Keycloak subject. Otherwise leave it out, and the first login links the account.
Sign in
Clients never hardcode the identity provider. They ask strazad where to sign in, read the realm’s discovery document, and open the browser at the realm’s sign-in page.
Open your strazad address followed by
/console/and press Sign in. The line above the button names the realm’s host, such asYou sign in at your identity provider, localhost:8480, and come back to this page.The tab goes to Keycloak. Sign in as yourself, and Keycloak sends the tab back to the console, which saysSigning you in. When the browser is still signed in at Keycloak, it can send you straight back without asking for your password. The console admits a person who holds an admin role, and anyone else lands on the self-service page.
The console’s sign-in card, taken on a standalone server, where the line names the server’s own sign-in page. Show the whole screen A console sign-in opens a session in the browser tab and enrolls no device.
curl -s http://localhost:8420/.well-known/straza/idp.jsonYou should see
Your realm as
issuer,strazaasclient_id, andbrowserasmin_sign_in, the lowest sign-in the server accepts for a person’s machine.strazactl has no sign-in of its own. It runs on an admin API token that a person mints in the console, so sign in at
http://localhost:8420/console/as the console form of this step shows, then open the mint sheet:- Settings
- API tokens
- New API token
Pick
expires in 30 days, then Custom under The job, and set theidentityarea to read, which the next step needs. Mint an admin API token walks the sheet. Copy the token, which is shown once, and hand it to strazactl in your terminal:export STRAZA_SERVER=http://localhost:8420 read -rs STRAZA_API_TOKEN && export STRAZA_API_TOKENread -rsreads the token you paste without showing it and keeps it out of the shell history. Never put the token where an agent runs as you, such as a shell profile or a file an agent can read. A token is a bearer credential, so whoever holds it acts with its scope until it expires or is revoked.If this fails
Cookie not found- Keycloak shows this when the browser lost its login cookie mid-flow. On the demo stack Keycloak binds the cookie to the name
localhost, so a browser that opens the address as127.0.0.1loses it. Open the address exactly as printed. The sign-in did not come back from your identity provider. If it showed an error about a redirect address, your administrator must add https://straza.example.com/console/signin to Straza's registration there. Press Sign in to try again.- The console says this, with your server’s address, after Keycloak refused its redirect address. Add that address to the client’s Valid redirect URIs, as the client step shows.
- A sentence that starts
Your identity provider atand goes ondid not let this page finish the sign-in. - The browser could not redeem the sign-in at Keycloak, because the client’s Web origins lack the console’s origin. Add the origin people open the console at under Web origins.
Verify
Your Keycloak sign-in found your Straza account.
- Users
- alice
You should see
Your own account’s sheet. The console admitted you because your verified sign-in found that account and it holds an admin role.
strazactl users listYou should see
A row for
alicewith the statusactive, read on the token you minted after your Keycloak sign-in.Undo
Signing out ends the console’s session, and revoking the token ends what strazactl can do with it.
Sign out in the header menu ends the console’s tab session. The card then says
Signed out. The session was revoked on the server. Your identity provider may still have you signed in, so on a shared computer sign out there too.unset STRAZA_API_TOKENtakes the token out of your terminal. Then revoke it in the console, because the token holds no right to revoke itself:- Settings
- API tokens
- Revoke
- Revoke token
Press Revoke on the token’s row, then Revoke token. The next call on it is refused.
Caveats
Disabling a person in Keycloak stops new logins and enrollments and nothing more. strazad verifies the Keycloak token at login only, and it verifies its own session tokens against its own keys. Your IGA’s SCIM deactivation cuts the person’s running Straza sessions and refuses every check-in from their machines until your IGA reactivates them. A leaver flow therefore triggers both: Keycloak for the authentication cut, and SCIM for the authorization cut.
While Keycloak is down, nobody signs in through it. The break-glass admin still signs in through Emergency sign-in on the console’s sign-in card, which opens Straza’s own sign-in page instead of your identity provider, and mints a token there when strazactl is needed. Standalone and enterprise compared shows the break-glass admin in both profiles.
The demo stack’s issuer is http://localhost:8480/realms/straza, the address your browser and the command-line tools use. Containers cannot reach that address, so strazad fetches the discovery document at keycloak:8080 through oidc.discoveryUrl. Keycloak serves the token and key endpoints of that document on the internal address.
Next
- midPoint provisions the accounts that Keycloak logins then sign in to.
- Enroll a machine signs a workstation in for an agent with
straza enroll. - Entra ID login and Okta login set up the same sign-in at those providers.
- People, agents and sponsors explains who exists and where each fact comes from.
Walked on v1.1.0 on 2026-09-28, except the browser sign-in of straza enroll and of the console, written from the code and not walked.
A Linux container on the demo stack's host, with Keycloak 26.0 and the shipped realm import. The device flow ran from the container, and the browser step was driven headless as alice. The client settings for the browser sign-in and its steps were written on 2026-10-22 from the code and from the shipped realm and were not walked. The console's browser sign-in, with its redirect address and web origin, was written from the code on 2026-10-22 and not walked. Console screenshots show strazad v1.0.0-1753-ga27c516c, standalone.