{"error":"invalid_grant","error_description":"Code not valid"}

invalid_grant is OAuth's designated bucket for "the grant you presented is no good", so Keycloak uses it for expired codes, replayed codes, PKCE mismatches, rotated refresh tokens, dead sessions, revoked offline tokens, and bad passwords alike. Read the description, find it in the table below, stop guessing.

Everything here was run against Keycloak 26.7.3 on 2026-09-07, with realm defaults except where a test says otherwise.

The whole map, in one table​

Every string below came out of a live server. error was invalid_grant and the status was 400 for all of them.

The rest of this post is the eight causes those strings group into, in the order you are likely to hit them.

1. The code was already redeemed — and it just killed the session​

Redeem an authorization code twice and the second attempt fails, which is what you would expect. What nobody expects is what happens to the tokens from the first, successful exchange:

# 1. exchange the code — succeeds, we keep the refresh token
curl -s -X POST "$TOKEN_URL" -d grant_type=authorization_code -d client_id=web \
  -d client_secret=$SECRET -d code=$CODE -d redirect_uri=http://localhost:3000/callback

# 2. exchange the same code again
{"error":"invalid_grant","error_description":"Code not valid"}

# 3. now use the refresh token that worked ten seconds ago
{"error":"invalid_grant","error_description":"Session doesn't have required client"}

Keycloak treats a redeemed code turning up a second time as a stolen code, and detaches the client from the user session. The legitimate client — the one that redeemed correctly — is logged out as collateral.

This is why Session doesn't have required client shows up in bug reports as "users get randomly logged out". It is almost never random. Something replayed a grant. The usual culprits are a React effect firing twice under StrictMode, a callback route that runs on both server and client, or a user refreshing the callback page.

2. The code expired​

Same message, different cause. Authorization codes live for accessCodeLifespan, which the admin console calls Client login timeout under Realm settings → Tokens, and which the server admin guide describes as the maximum time before clients must finish the authorization code flow. It ships at 60 seconds.

Sixty seconds is generous for a redirect and a back-channel call, and mean if your callback handler blocks on something slow — a user lookup against a legacy directory, a cold Lambda, a provisioning call. Do the token exchange first, everything else after.

Telling the two apart​

The response is identical, and so is the server log: both produce type="CODE_TO_TOKEN_ERROR", error="invalid_code" with no distinguishing reason. The code_id detail is what separates them. Turn on event storage and read the sequence:

kcadm.sh update events/config -r demo \
  -s eventsEnabled=true \
  -s 'enabledEventTypes=["LOGIN","CODE_TO_TOKEN","CODE_TO_TOKEN_ERROR"]'
kcadm.sh get events -r demo -q max=10

# replayed code — a successful exchange for the same code_id
LOGIN                code_id=KP3veSsloJww7HFfIJF_5A4r
CODE_TO_TOKEN        code_id=KP3veSsloJww7HFfIJF_5A4r
CODE_TO_TOKEN_ERROR  code_id=KP3veSsloJww7HFfIJF_5A4r  error=invalid_code

# expired code — nothing ever redeemed it
LOGIN                code_id=oqgn0iFSvrCod8rFFN4jPXmJ
CODE_TO_TOKEN_ERROR  code_id=oqgn0iFSvrCod8rFFN4jPXmJ  error=invalid_code

A CODE_TO_TOKEN between the LOGIN and the error means replay. No CODE_TO_TOKEN means expiry. That single check has settled more of these arguments than any amount of reading application logs.

3. The redirect_uri changed between the two calls​

{"error":"invalid_grant","error_description":"Incorrect redirect_uri"}

The redirect_uri in the token request must be byte-identical to the one in the authorization request. Registering both on the client is not enough — we sent http://localhost:3000/callback to /auth and http://localhost:3000/cb2 to the token endpoint with both registered, and it was rejected. Omitting the parameter entirely gives the same error.

The server log spells it out where the response does not:

error="invalid_redirect_uri", reason="Parameter 'redirect_uri' did not match originally
saved redirect URI used in initial OIDC request. Saved redirectUri:
http://localhost:3000/callback, redirectUri parameter: http://localhost:3000/cb2"

This is a different failure from the one that stops you at the login screen. If you never got a code at all, you want Invalid parameter: redirect_uri instead.

4. PKCE — three failures, three distinct messages​

Keycloak is unusually helpful here, and the three messages mean genuinely different things.

The syntax rule is a verifier of 43–128 characters from the unreserved set. We confirmed the boundary against a live server: a 43-character verifier that is simply wrong returns Code mismatch, and the same wrong verifier at 42 characters returns Invalid code verifier.

That distinction is worth knowing, because it tells you which bug you have. Invalid code verifier means your generator is broken — usually base64 instead of base64url, or truncating to 32 characters. Code mismatch means the generator is fine and you lost the verifier between the two requests: regenerated it, stored it in a cookie that got dropped on the cross-site redirect, or ran the two halves of the flow on different instances of a horizontally scaled app.

A missing code_challenge on the authorization request is not an invalid_grant at all. Keycloak fails it earlier, redirecting back with error=invalid_request&error_description=Missing+parameter%3A+code_challenge_method.

5. Refresh token rotation and the concurrency trap​

This one is worth measuring, because the setting that causes it is frequently turned on for good reasons by someone who then spends a week debugging the result.

With Revoke Refresh Token (revokeRefreshToken) enabled, each refresh invalidates the token you presented. Refresh Token Max Reuse (refreshTokenMaxReuse) controls how many replays are tolerated, and defaults to 0 — none. Replay a superseded token and you get:

{"error":"invalid_grant","error_description":"Maximum allowed refresh token reuse exceeded"}

Now fire three refreshes concurrently with the same token, which is exactly what a browser app with three tabs, or a service with a connection pool, does the moment an access token expires:

Read the middle row carefully. The third request does not merely fail — by the time it arrives the reuse has already detached the client session, so the new refresh token returned to the first caller is dead too. One racing tab logs the user out of all of them.

Rotation is a real security control and we are not telling you to leave it off. But if you turn it on, either serialise refreshes behind a single-flight lock in every client, or set refreshTokenMaxReuse to a small non-zero number and accept a narrow replay window. Turning rotation on and changing nothing else is the option that produces support tickets.

6. The session is gone​

Four different messages, all meaning "the session behind this refresh token no longer exists":

• Session not active — someone hit the logout endpoint, or an admin removed the session.
• Token is not active — the session passed ssoSessionIdleTimeout (default 30 minutes) or ssoSessionMaxLifespan (default 10 hours). We reproduced this by dropping idle timeout to 60 seconds and waiting it out.
• Stale token — a not-before policy was pushed. Realm settings → Sessions → Revocation, or the per-client equivalent, sets a timestamp and every token issued before it dies instantly. Easy to forget you clicked it.
• Offline user session not found — an offline token whose session was revoked, either by the revocation endpoint or by the user removing consent.

Token is not active is also what clock skew looks like. If it appears immediately after issuing a token, on a multi-node cluster, on tokens that should have 29 minutes left, check that the nodes agree on the time before you touch any Keycloak setting. We did not reproduce that case directly — it needs two nodes with genuinely divergent clocks — but the failure mode is the same message, and comparing date across nodes rules it in or out in a second.

7. The direct grant, where the message is deliberately unhelpful​

The password grant returns three messages, and one of them is a lie by design:

wrong password:      {"error":"invalid_grant","error_description":"Invalid user credentials"}
unknown user:        {"error":"invalid_grant","error_description":"Invalid user credentials"}
disabled user:       {"error":"invalid_grant","error_description":"Account disabled"}
required action:     {"error":"invalid_grant","error_description":"Account is not fully set up"}

Invalid user credentials covers wrong password and non-existent user identically, so the endpoint cannot be used to enumerate accounts. It also covers a brute-force lockout. With bruteForceProtected=true and failureFactor=3, we sent four bad passwords and then the correct one:

attempt 4 (bad):                 {"error_description":"Invalid user credentials"}
attempt 5 (CORRECT password):    {"error_description":"Invalid user credentials"}

The admin guide is explicit that this masking is intentional, so an attacker cannot tell a locked account from a wrong password. Neither can your support team. The server log does distinguish them:

error="invalid_user_credentials"   ← wrong password
error="user_temporarily_disabled"  ← locked out

And you can check and clear a specific user's lockout state directly:

kcadm.sh get attack-detection/brute-force/users/$USER_ID -r demo
kcadm.sh delete attack-detection/brute-force/users/$USER_ID -r demo

Account is not fully set up is the one people misdiagnose most. It means a required action is pending — and on a fresh realm, VERIFY_PROFILE fires for any user missing an email, first name, or last name. Users created by script or by a migration hit this constantly while looking perfectly fine in the console.

8. That is not this client's refresh token​

Two messages, both meaning the token you presented is not the thing the endpoint wanted:

• Invalid refresh token — you sent something that is not a refresh token. Posting an access token here is the single most common version, usually a variable mix-up. Decode the typ claim; a refresh token says Refresh (or Offline), an access token says Bearer.
• Invalid refresh token. Token client and authorized client don't match — the token is real but was issued to a different client_id. Common when a gateway and a frontend share token storage, or when someone copies a token between environments.

If you are not sure what you are holding, decode it. Our token walkthrough tutorial covers reading every claim, including the ones that make valid tokens get rejected.

Things that look like invalid_grant and are not​

Worth stating plainly, because the outline for this post originally listed the first one as an invalid_grant cause and testing said otherwise:

If you are looking at unauthorized_client or invalid_client, stop reading this post — the problem is client authentication, not the grant.

The short version​

1. Read error_description, not error. It names the cause.
2. Code not valid is expired or replayed; check the event log for a CODE_TO_TOKEN with the same code_id to tell which.
3. Session doesn't have required client means something replayed a grant a moment earlier. Find the double request; do not raise a timeout.
4. Three PKCE messages, three different bugs. Invalid code verifier is your generator, Code mismatch is your storage.
5. If you enable refresh token rotation, fix concurrent refreshes at the same time.
6. Invalid user credentials might be a lockout. Only the server log knows.

Keep docker logs on the Keycloak container open in a second terminal while you debug any of this. The response is deliberately vague; the log is not.

Most of these are one-line configuration answers once you know which of the eight you are looking at — the expensive part is the afternoon spent finding out. If you would rather not spend it, Phase Two runs managed Keycloak with a 30-day Starter trial from $149/month, and the session and token settings above already tuned. If you are staying self-hosted, the Keycloak tutorials and the securing applications docs cover the client-side half of this.

Two commands to install. Works against any Keycloak — and gets sharper the closer you get to ours. Don't have a Keycloak yet? The agent can provision one for you and it's free for 30 days.

The problem with asking an AI about Keycloak​

Keycloak is enormously powerful, and enormously easy to misconfigure in ways that produce no error at all. Ask a general-purpose model to "set up passwordless login" and you will usually get something that looks right, returns 204 No Content from every call, and is quietly broken.

A few real examples, all of which we've fixed in production for customers:

• Mix ALTERNATIVE and REQUIRED executions at the same level of an authentication flow and Keycloak silently erases the alternatives. This is how "primary login, then a choice of second factors" gets built wrong.
• The Admin REST calls that create flow executions do not establish their order. You have to read the flow back and repair it. Order is the behavior in an ALTERNATIVE block — first to succeed wins.
• Put stock auth-username-form in front of an email-OTP step and it rejects unknown addresses with "Invalid username or email" before the OTP step runs — leaking which email addresses have accounts.
• Copy a generic OIDC attribute mapper into a "Sign in with GitHub" setup and it maps nothing: GitHub sends login, not preferred_username, and needs its own github-user-attribute-mapper.
• Keycloak's partialImport endpoint accepts authentication flows with an HTTP 200 and creates none of them.
• For an IdP-initiated SSO tile, two client attributes silently outrank the redirect you configured, and RelayState — which looks exactly like the routing mechanism — is discarded outright.
• CONFIGURE_TOTP ships registered but disabled. A required action you set on a user is accepted by the API and then never prompts.

None of that is guessable. It's the accumulated scar tissue of years of running Keycloak, and it's exactly what we've distilled into these skills — 30 reference chapters for realm administration, 18 for application integration, roughly 12,000 lines of verified guidance.

Install it​

claude plugin marketplace add p2-inc/keycloak-skills

claude plugin install phasetwo@keycloak-skills

Or interactively inside a Claude Code session: /plugin marketplace add p2-inc/keycloak-skills, then /plugin install phasetwo. Restart Claude Code afterwards — skills load at session start.

The plugin declares the MCP server for you, so there's nothing else to run. The first tool call opens a browser to authorize; check the connection any time with /mcp. If you want the server on its own, without the skills:

claude mcp add --transport http keycloak https://mcp.phasetwo.io/mcp

Then just ask for what you want — "add passwordless login by magic link", "connect our customer's Okta by email domain", "add login to this React app". The skill figures out which of its chapters applies, asks the one or two questions it actually needs, and goes.

Watch it work​

Razvan from our team takes an unsecured Angular app and simply says "I want to secure this app" — and the skill does the rest: it asks the one question that matters (Phase Two hosted, or self-managed?), picks the cluster and realm over MCP, registers the OIDC client, rewrites the app's own configuration to match, and then the protected route logs in for real against the cluster. No documentation, no admin console, no copy-pasting a client secret between two browser tabs.

What the walkthrough covers:

• Prerequisites — an agent, the plugin installed, and a Phase Two subscription with a cluster. (The cluster can be created through the plugin too, as above; the demo uses an existing one to keep things moving.)
• Authorizing against Phase Two — the MCP server's OAuth login, so every subsequent call is made as him.
• The skill routing the request — securing-apps recognizing an Angular app and asking the hosted-vs-self-managed question before touching anything.
• Driving the cluster over MCP — listing his clusters, choosing the target realm, and registering the client in it.
• The payoff — the app's config updated in place, and a real login completed at the protected endpoint.

Any Keycloak — and better the closer you get to ours​

There are three rungs here, and you get real value on the first one.

Rung 1 — any Keycloak at all​

The skills work against any Keycloak installation. Bare metal, Docker, Kubernetes, someone else's managed offering. Every chapter ships in two variants and the skill asks you one question to pick between them: rest drives the Keycloak Admin REST API with your own admin token, mcp drives the Phase Two MCP server. The Keycloak knowledge is identical either way.

Plenty of the catalogue is pure stock Keycloak with no extensions involved: passkey-only WebAuthn login, credential enrollment for existing users, social login buttons, enterprise IdP federation, IdP-initiated SSO tiles, and every last thing in securing-apps.

Rung 2 — Phase Two's enhanced Keycloak distribution​

Swap your image for quay.io/phasetwo/phasetwo-keycloak and the rest of the catalogue opens up. It's Keycloak with our popular open-source extensions already bundled — organizations, magic link, events and webhooks, attribute-driven themes, admin UI and portal customizations. One line of Helm values or one docker run; examples live in phasetwo-containers.

That single change unlocks magic-link login, emailed OTP both passwordless and as a second factor, organizations with all three membership-gated login variants, and corporate SSO routed by email domain — none of which exist in stock Keycloak at any price.

And this is exactly where the skills earn their keep, because these flows are assembled from authenticators (ext-magic-form, ext-email-otp, ext-select-org, ext-auth-username-auth-note, ext-auth-home-idp-discovery) whose order relative to one another is the behavior, and which no amount of general Keycloak knowledge will teach you. Put the organization check after the magic-link step and a non-member still gets a login email. Reach for stock auth-username-form instead of the identifier-only authenticator and you leak which addresses have accounts. The skills know these orderings because we've gotten them wrong first.

Rung 3 — Phase Two hosted​

On a hosted cluster the MCP server is there too, and Claude stops writing curl commands for you to run and starts operating the realm directly:

158 tools in all. Two details worth calling out:

Every call is authorized as you. The MCP server stores no admin credentials of its own — it acts as an OAuth 2.1 resource server, and control-plane calls are made with the bearer token of the human logged into the MCP client. Reaching into a cluster deployment mints a short-lived, deployment-scoped admin token from that same authorization, so your existing roles and permissions apply and the audit trail shows you, not a shared robot.

It refuses to delete things that matter. Deleting a cluster, deployment or realm is irreversible — a deployment is a realm, so it takes every user, client and flow with it. deleteCluster refuses every call and never reaches the API, no tool deletes a deployment or realm at all, and the skill's very first instruction is to deny the request and point you at the dashboard rather than reach for curl. Changing a client that already serves traffic requires your confirmation, and the skills verify by reading configuration back rather than trusting a 204.

No Keycloak at all? Ask the agent for one​

Here's our favorite part. You don't need an existing cluster to start — the agent can provision you a Starter cluster, on a 30-day free trial, without you leaving the session.

Say "spin up a Phase Two cluster" and the skill walks the whole thing: identifies you from your token, finds the organization that will own the cluster, lists the available regions, checks your chosen name is free, and calls createCluster on the Starter tier — $149/month with a 30-day free trial. It hands you the Stripe checkout link to open yourself (it will never enter payment details on your behalf — that's an explicit rule in the skill, not a limitation), polls getCluster until the status goes BILLING_SETUP → PROVISIONING → ACTIVE, then offers to create your first deployment and point a custom domain at it.

And then it keeps going. Same session, same agent: "now add passwordless login by magic link" against the cluster it just built for you. From nothing to a running, observable, passwordless Keycloak in one conversation.

We run our support desk on this​

This isn't a demo we built for a launch post. Phase Two's support team uses these skills and this MCP server every day for customer support, debugging, and hands-on assistance across our fleet of Keycloak clusters, for hundreds of customers.

That's the real reason the guidance is shaped the way it is. Every silent failure in the list above cost somebody an afternoon before it became a paragraph in a reference file. When a customer opens a ticket saying "MFA isn't prompting" or "the SSO redirect goes to the wrong place," the fastest path to an answer is an agent that already knows the twelve ways each of those goes wrong.

Verified, not vibed​

Skill content is only as good as its testing. Each capability ships with a skillsbench task in the repo's benchmarks/ directory that stands up a real Keycloak in a sandbox and drives an actual login — magic links clicked, passkeys signed by a headless browser's virtual authenticator, a second realm standing in for a partner's IdP for genuine brokered SSO.

The assertions are deliberately adversarial, because the plausible-but-wrong answer is the enemy. The email-OTP-as-MFA task asserts that a wrong password sends no mail at all — a flow that merely puts a code step in front of a login passes a happy-path test while leaving the password irrelevant. The credential-enrollment task asserts that a user who had no password still has none at the end, because setting a temporary one satisfies a naive reading of the goal and defeats its entire point.

What it covers today​

Realm administration (the keycloak skill):

• Passwordless login — magic link, emailed OTP code, passkey-only WebAuthn, or the combined "0 password required" flow offering a passkey or a magic link
• Emailed OTP as a second factor behind a still-required password
• Credential enrollment for users who already exist — required actions, or an emailed enrollment link
• Corporate SSO routed by email domain (home realm discovery)
• Social login buttons — Google, GitHub, Microsoft, Facebook and the rest
• Enterprise IdP federation — Entra ID, Okta, Auth0, ADFS, AWS SSO, Google Workspace, PingOne, OneLogin, Oracle, Duo, CyberArk, JumpCloud, LastPass, Salesforce, Cloudflare Access, or any generic OIDC/SAML 2.0 IdP
• IdP-initiated SSO from an Okta or Entra portal tile into one specific app
• Organization-membership login restriction — for local password login, for federated/SSO login, and for magic-link login
• Phase Two cluster provisioning and new deployments

The magic-link, email-OTP, organization and domain-routed-SSO rows need our extensions — so rung 2 or 3 above. Everything else is stock Keycloak.

Application integration (the securing-apps skill): browser login, logout and route protection for React, Angular, Vue, Next.js and vanilla SPAs; bearer-JWT validation for Spring Boot, Express, FastAPI and Quarkus resource servers; native login for Android, iOS and React Native; plus registering the OIDC client each one needs — and diagnosing the classics (invalid redirect_uri, a 401 from your API, CORS on the token call, redirect loops, missing roles).

Not covered? Tell us — that's the point​

The router is deliberately honest about its edges. Ask for something it doesn't cover and it will say so rather than force your request into the nearest-looking recipe and hand you confidently wrong guidance. It will then offer to draft a GitHub issue for you, quoting your request verbatim — because the exact phrasing you used is precisely what the next version needs in order to recognize the case.

So: file an issue in p2-inc/keycloak-skills. Missing capability, a chapter that's wrong for your Keycloak version, a tool you wish the MCP server had — all of it is useful, and it's how this grows. New capabilities land as reference chapters under the same skill once they're genuinely written and verified.

Where this is going​

We're committing to this: distilling years of Keycloak expertise into skills and MCP tools, in the open, so everyone benefits. Keycloak's power has always come with a learning curve measured in months. Encoding that knowledge where your agent can read it is the most direct way we know to flatten it — for our customers, and for the much larger community running Keycloak themselves.

Two commands, and your agent knows Keycloak.

claude plugin marketplace add p2-inc/keycloak-skills
claude plugin install phasetwo@keycloak-skills

Star and fork the repo at p2-inc/keycloak-skills. Running your own Keycloak? Pull quay.io/phasetwo/phasetwo-keycloak and the whole catalogue becomes available. Don't have a Keycloak at all? Install the plugin and just ask for one — a Starter cluster comes with a 30-day free trial and the agent can provision it for you. Questions, or want to tell us what to build next? support@phasetwo.io.

That closes a gap that had nothing to do with Keycloak's capabilities and everything to do with where Keycloak sits in a mobile login flow.

The gap​

Mobile platforms decide whether an app may use a saved credential by checking the domain that served the login page. If your users sign in at auth.example.com, that is the origin the password manager files the credential under, and the origin iOS and Android will consult later.

Both platforms consult it the same way: they fetch a file from a fixed path at the root of that domain, out of band, and check whether it names your app.

https://auth.example.com/.well-known/apple-app-site-association
https://auth.example.com/.well-known/assetlinks.json

Which puts the identity provider in an awkward position. Keycloak serves paths under /realms/, /admin/ and /resources/ — it has never owned the root of the domain, and on deployments that run it under a path prefix it has no root to own at all. So the files could not come from Keycloak, and they could not come from the app team either, because the app team does not control the login domain.

The result was a silent failure. Autofill never appeared, nothing logged an error, and teams reasonably concluded it was a device setting.

What we changed​

Phase Two custom domains now serve three things at the root of the domain:

They are served at the edge rather than by the cluster, which has a few consequences worth knowing. Uploads apply in minutes instead of needing a restart, so correcting a fingerprint is not a deployment event. They keep serving during a cluster restart, which matters because a failed fetch gets cached by Apple for hours. And each domain on a cluster gets its own content, which is what makes this work for white-label products where every tenant has a different app.

Everything else under /.well-known/ still returns 404 — deliberately. The change-password specification relies on an unknown well-known URL not returning 200, and a catch-all would quietly break how password managers detect support.

Why we think this belongs in the platform​

Phase Two exists because running Keycloak well involves a long tail of work that has nothing to do with Keycloak itself. Certificates, custom domains, upgrades, themes, extension packaging — each is small, each is somebody's afternoon, and collectively they are the reason teams end up staffing an identity platform rather than using one.

App association files are a clean example. The requirement comes from Apple and Google, the fix is two small JSON files, and the only reason it is hard is that the files have to live somewhere Keycloak has never served from. Nothing about it is intellectually interesting. It is just infrastructure that has to exist, and it sits precisely at the boundary where a hosted provider can help and an app team cannot.

Passkeys make it more pressing. A passkey is bound to a relying party ID, which is a domain, and that binding is fixed when the credential is created — you cannot change it later without invalidating every passkey already enrolled. Teams planning passkeys in a native app need the domain and the association files settled before the first enrolment, not after.

Getting started​

Setting up the domain — adding a custom domain, DNS and certificate issuance, and where to upload the files in the dashboard: Custom Domains. Available on Premium and Enterprise plans.

Writing the files — Team IDs, package names, signing fingerprints, the entitlement on the app side, and how to verify with Apple's and Google's public validators before shipping a build: Write the App Association Files That Let Mobile Apps Autofill Your Login. That tutorial is vendor-neutral and works against any Keycloak.

One thing worth reading before you start, because it surprises most people: subdomains do not inherit. A file on example.com does not cover auth.example.com. iOS offers a wildcard entitlement and Android offers a delegating include, but as of this writing at least one file generally has to be served from the domain your login page actually runs on. Platform behaviour here does change — check the vendor documentation before relying on either exception.

If you sell to enterprises, you will be asked for it. This post covers what it is, when you actually need it, and a working walkthrough of Keycloak's native SCIM API — which arrived as a preview feature and is not enabled by default.

Everything here was run against Keycloak 26.7.3.

What problem SCIM solves​

Without it, enterprise onboarding looks like this: someone joins, IT adds them to Okta, and then a human logs into your app and creates their account too. Someone leaves, IT disables their Okta account — and the account in your app stays active until somebody remembers.

That gap is the whole reason SCIM exists. It is a security problem before it is a convenience problem: the leaver whose account never got deactivated is one of the most common ways access outlives employment.

SCIM standardises four operations across vendors:

Note the last one. SCIM deactivates; it usually does not delete. Most IdPs send active: false rather than DELETE, because audit trails need the record to survive. Systems that treat deprovisioning as deletion get this wrong and lose history.

SCIM vs SAML vs OIDC — they solve different problems​

This is the most common confusion, and the comparison is not apples to apples:

They are complementary, not alternatives. A typical enterprise deal wants both: SAML or OIDC so people can log in, SCIM so the account list stays correct.

Do you actually need it?​

Be honest about this, because SCIM is real work:

You probably need it if: you sell to companies with hundreds of employees; your buyers ask about "provisioning" or "deprovisioning"; you have per-seat pricing (customers want their seat count to track reality automatically); or you have compliance requirements around timely access removal.

You probably don't yet if: your customers are small teams; users self-register; or just-in-time provisioning at first login is sufficient. JIT provisioning — creating the account the first time someone logs in via SSO — covers a lot of ground and costs almost nothing. It just cannot deprovision, because a leaver simply never logs in again.

That is the honest dividing line: if you need deprovisioning, you need SCIM.

Keycloak's native SCIM API​

Keycloak ships a SCIM 2.0 server. Two things are not obvious:

1. It is a preview feature, off by default.
2. It must also be enabled per realm — the feature flag alone gets you a 404.

Enable it​

Start the server with the feature:

docker run -p 8081:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.7.3 start-dev --features=scim-api

You'll see it confirmed at boot:

INFO [org.keycloak.common.Profile] Preview features enabled: scim-api:v1

Then enable it on the realm:

kcadm.sh update realms/myrealm -s scimApiEnabled=true

Miss that second step and every SCIM request returns 404, while the server log says:

WARN [org.keycloak.scim.services.ScimRealmResourceFactory] SCIM API is not enabled for realm 'myrealm'

Your base URL is then:

{server}/realms/{realm}/scim/v2

Authenticate — and the audience trap​

SCIM clients authenticate with a bearer token from a service account:

kcadm.sh create clients -r myrealm \
  -s clientId=scim-client -s publicClient=false \
  -s serviceAccountsEnabled=true -s secret=CHANGEME

kcadm.sh add-roles -r myrealm --uusername service-account-scim-client \
  --cclientid realm-management \
  --rolename manage-users --rolename view-users --rolename query-users

Now the part that will cost you an afternoon. The token needs an audience mapper, and the audience is not the client id — it is the SCIM base URL itself:

kcadm.sh create clients/$CLIENT_UUID/protocol-mappers/models -r myrealm \
  -s name=scim-audience -s protocol=openid-connect \
  -s protocolMapper=oidc-audience-mapper \
  -s 'config."included.custom.audience"=http://localhost:8081/realms/myrealm/scim/v2' \
  -s 'config."access.token.claim"=true'

We tried scim, scim-api, urn:keycloak:scim, and the client id. All of them return:

{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],
 "status":"401","detail":"Invalid token audience"}

Only the full base URL works. Get a token the usual way:

curl -X POST {server}/realms/myrealm/protocol/openid-connect/token \
  -d grant_type=client_credentials -d client_id=scim-client -d client_secret=CHANGEME

Check what it supports before you build​

ServiceProviderConfig is the first call any SCIM client makes, and for Keycloak 26.7.3 it returns some limitations worth knowing up front:

{
  "patch":          { "supported": true },
  "bulk":           { "supported": false, "maxOperations": 0 },
  "filter":         { "supported": true, "maxResults": 100 },
  "changePassword": { "supported": false },
  "sort":           { "supported": false },
  "etag":           { "supported": false }
}

Read that carefully:

• bulk is not supported. An IdP syncing 10,000 users will make 10,000 calls. Plan for the rate, and for how your infrastructure handles a Monday-morning bulk sync.
• sort is not supported. Clients that assume stable ordering across pages need testing.
• filter caps at 100 results per page. Pagination is mandatory, not optional.
• changePassword is not supported — passwords stay with the IdP, which is correct.

It works​

Creating a user:

curl -X POST "$BASE/Users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName":"bob","active":true,
    "name":{"givenName":"Bob","familyName":"Example"},
    "emails":[{"value":"bob@example.com","primary":true}]
  }'

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "7b4b1d91-0ce6-44d0-9c77-766ae5dadcb3",
  "meta": {
    "resourceType": "User",
    "created": "2026-08-31T21:52:58.866Z",
    "location": ".../scim/v2/Users/7b4b1d91-0ce6-44d0-9c77-766ae5dadcb3"
  },
  "userName": "bob",
  "name": { "formatted": "Bob Example", "familyName": "Example", "givenName": "Bob" },
  "active": true,
  "emails": [{ "value": "bob@example.com", "type": "work", "primary": true }]
}

That user is a normal Keycloak user — kcadm.sh get users returns it immediately. SCIM is a protocol surface over the same user store, not a parallel one.

Filtering works as specified:

curl -G "$BASE/Users" -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'filter=userName eq "bob"'

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1, "itemsPerPage": 1, ... }

What "supports SCIM" should mean when a buyer asks​

Vendors claim SCIM support at wildly different depths. If you are evaluating — or being evaluated — these are the questions that separate a real implementation from a checkbox:

1. Users and groups, or users only? Group sync is where most implementations stop, and it is usually what the customer actually wants.
2. Does deactivation work? active: false must disable access immediately. This is the single most important operation and the most commonly half-implemented.
3. Is PATCH supported, or only PUT? Okta and Entra ID lean on PATCH. PUT-only support causes data loss when the IdP sends a partial update.
4. Which filters? eq is table stakes. Real IdPs use more.
5. How does it handle a user who already exists? Duplicate handling is where sync loops are born.
6. Is there rate limiting, and what happens on bulk sync? Especially with no bulk endpoint.

Where this leaves you​

Keycloak's native SCIM API is real, it works, and it is preview — which means it may change before it stabilises, and you should not assume the audience quirk above is permanent. For a new integration it is the right place to start.

The gap it does not close is multi-tenant provisioning: a B2B SaaS usually needs each customer organization to have its own SCIM endpoint and its own credentials, so one customer's IdP cannot see or touch another's users. That is a different shape of problem to realm-level SCIM, and it is why we built SCIM for Organizations as an extension.

If you're implementing SCIM against Keycloak, start with the native API above and reach for per-organization endpoints when you have more than one customer wanting to sync.

Further reading: RFC 7644 is the SCIM protocol specification and is unusually readable. Keycloak's own SCIM documentation covers the full endpoint surface.

Running Keycloak in production — including preview features you'd rather not operate yourself? That's what we do.

It was built in partnership with Gusto, who use Keycloak for user authentication and rely on Phase Two for enterprise Keycloak support. It has been running in their production environment for almost a year. The public repository is the extraction of that work into a standalone extension anyone can install.

The problem: there is no transaction around a flow change​

Authentication flows are the highest-stakes configuration in a Keycloak realm. If a flow is wrong, nobody logs in.

They are also the configuration that Keycloak gives you the least protection while changing. Both the admin console and the admin REST API mutate flows incrementally: adding an execution is one call, setting its requirement is another, reordering is another, creating a subflow and moving executions into it is several more. Each of those calls commits on its own, against a flow that is already bound as the realm's browser flow and already serving live login traffic.

That leaves a window — sometimes minutes long, if a human is clicking through the console — where the flow that real users are authenticating against is in a state nobody designed. A subflow that exists but is empty. A REQUIRED OTP execution added before its authenticator config. An ALTERNATIVE removed before its replacement was added. Every one of those intermediate states is a live flow, and some of them fail closed.

The usual workarounds don't close the window either:

• Realm partial import doesn't cover authentication flows in a way you can use for iterative updates.
• Copy the built-in flow, edit the copy, re-bind is the right instinct, and it's what careful operators do by hand. But it's a manual, multi-step, admin-console-driven process, and nothing about it is repeatable from a pipeline.
• Full realm export/import is far too blunt for a flow change and has its own consistency problems.

What the extension does​

The extension registers a realm admin REST resource that takes the whole flow tree as a single payload:

POST /admin/realms/{realm}/authentication-flow/import[?force=true]
Content-Type: application/json

The body carries everything needed for a complete change in one shot:

Three properties make this safe:

It's one transaction. Flows, configs, executions, and every binding are applied inside a single Keycloak transaction. Any failure — a dangling flow reference, a missing identity provider alias, an unknown client — rolls the entire import back. There is no half-applied flow, because there is no intermediate state visible to anyone outside the transaction. The caller needs manage-realm.

Flows are versioned by content, not mutated. The server hashes the flows and configs in the payload and prefixes every flow alias with that hash. An import never edits a flow that exists; it creates a new, independently-bindable set of flows and then moves the bindings onto them. The flow that was serving traffic a millisecond ago is untouched and still there.

It's idempotent. Because the aliases are derived from the payload's content hash, re-posting an identical tree is detected and rejected with 409 Conflict rather than silently creating a duplicate set of flows. Pass force=true to re-apply the bindings over an already-imported tree. A pipeline can run the import on every deploy without accumulating garbage or needing to diff state first.

Testing and rolling back​

The content-hash model gives you two things that are genuinely hard with mutable flows.

Canary a flow before it's the realm's flow. An import can bind its new flow as a per-client browser or direct grant override instead of the realm browser flow. The new flow is live and fully exercisable against one client — a staging app, an internal client, your own test harness — while every other client in the realm keeps authenticating against the current flow. Promote it by importing the same tree with the realm binding.

Roll back by re-binding, not by re-editing. A previous flow version is still present in the realm under its own hash prefix, with its executions and configs intact. Rolling back is re-posting that previous payload with force=true, which re-applies its bindings in one transaction. It's the same operation as rolling forward, it takes as long as one HTTP request, and it doesn't require reconstructing anything by hand in the admin console at 2am.

The tradeoff is deliberate and worth stating: imports are append-only in spirit, so old flow versions accumulate in the realm. That accumulation is the rollback capability. Pruning old versions is a separate, deliberate act — not something an import does behind your back.

Made for configuration as code​

Once flow updates are a single idempotent request, flows become an ordinary config-as-code artifact. The repository ships a complete worked toolchain in examples/ that mirrors how this runs in a real deployment:

1. Describe the flows in a small Ruby DSL (auth_flows_builder.rb) — the hand-edited source of truth, held in git.

2. Build two generated artifacts from it: auth_flows_tree.json, the exact import payload, and auth_flows_tree.txt, a tree rendering that makes flow changes legible in a pull request diff:

   demo-browser/  ← browserFlow
   ├── [ALTERNATIVE] auth-cookie
   ├── [ALTERNATIVE] identity-provider-redirector
   └── [ALTERNATIVE] demo-browser-forms/  (subflow)
       ├── [REQUIRED] auth-username-password-form
       └── [CONDITIONAL] demo-browser-conditional-otp/  (subflow)
           ├── [REQUIRED] conditional-user-configured
           └── [REQUIRED] auth-otp-form
   

3. Validate the payload before it ships. The validator catches dangling subflow, config, and IdP references, orphaned flows, inconsistent executions, and authenticator ids that exceed Keycloak's column length — mistakes that would otherwise only surface at runtime.

4. Apply it with the update script, which posts the payload to the import endpoint. Safe to re-run.

Reviewing an auth flow change becomes reading a diff. Shipping it becomes one request that either fully lands or fully doesn't.

Try it​

You need Docker and Ruby — no JDK, no Maven, no Keycloak install:

git clone https://github.com/p2-inc/keycloak-atomic-auth-flows.git
cd keycloak-atomic-auth-flows

# Keycloak (dev mode) with the extension loaded and a minimal `demo` realm
docker compose up --build

# In another shell — import the demo flows via the new endpoint
ruby examples/scripts/update_auth_flows.rb

Then open the admin console at http://localhost:8080 (admin / admin) → realm demo → Authentication, and you'll see the imported flows, alias-prefixed with their import hash, bound to the realm and to the demo identity provider. Run the script a second time to watch the 409.

As of publication, the extension targets Keycloak 26.7.3, builds with JDK 21 and Maven, and is licensed Apache 2.0. Integration tests run against a real Keycloak via Testcontainers.

Thanks to Gusto​

This extension exists because Gusto needed to change authentication flows on a schedule their business required, with a risk profile their security posture demanded, and the stock tooling couldn't offer either. They funded and co-designed the work, ran it in production, and agreed to open-source it so the rest of the Keycloak community gets the same guarantees. We're grateful for the partnership.

Want to go deeper?

1. Read the code and docs: github.com/p2-inc/keycloak-atomic-auth-flows
2. File issues and feature requests on the issue tracker
3. Reach out to our team: support@phasetwo.io
4. Talk to us about enterprise Keycloak support: phasetwo.io/contact

The short answer: the redirect_uri your application sent does not match, character for character after wildcard expansion, any entry in that client's Valid redirect URIs. The long answer is that Keycloak's matching rules are stricter and stranger than almost everyone assumes — in particular, it will reject any redirect_uri containing a query string, no matter what you registered.

Everything below was tested against Keycloak 26.7.3.

First: stop guessing, read the server log​

The browser deliberately shows you nothing useful. Keycloak will not echo the rejected URI back to the page, because doing so would make it an open redirector and a phishing tool.

The server log has no such constraint, and it tells you exactly what was sent:

WARN [org.keycloak.events] type="LOGIN_ERROR", realmName="demo", clientId="c-multi",
  error="invalid_redirect_uri", redirect_uri="http://localhost:3000/cb?tenant=acme"

docker logs <container> 2>&1 | grep invalid_redirect_uri

Put the redirect_uri="..." value next to your registered list and the mismatch is usually obvious in about five seconds. This one step solves most cases, and almost nobody knows the log line exists.

The matching rules, tested​

Here is what Keycloak 26.7.3 actually does. Every row was run against a live server.

Exact registration — http://localhost:3000/callback​

Wildcard registration — http://localhost:3000/*​

Trailing slashes are significant in both directions​

http://localhost:3000 and http://localhost:3000/ are different registrations. If you don't know which one your library sends, register both.

* is a substring wildcard, not a path wildcard​

Registered http://localhost:3000/cb*:

And registered http://localhost:3000/a/* accepts http://localhost:3000/a — the wildcard is generous at the prefix boundary but stops dead at a ?.

The query-string rule, which catches nearly everyone​

Keycloak 26.7.3 rejects any redirect_uri containing a ?, regardless of the registered pattern. We tried to register our way around it and could not:

If your app is sending its own query parameters on the callback URL — a tenant hint, a "return to this page" pointer, a feature flag — that is your bug, and no redirect URI configuration will fix it.

What to do instead​

Use the state parameter. That is what it is for: opaque round-tripped application state, returned to you untouched after login, and it doubles as CSRF protection.

// ❌ Keycloak will reject this
const redirectUri = "https://app.example.com/cb?returnTo=/reports";

// ✅ Same information, correct mechanism
const redirectUri = "https://app.example.com/cb";
const state = btoa(JSON.stringify({ returnTo: "/reports", nonce: crypto.randomUUID() }));

Read state back in your callback handler. Every mainstream OIDC library supports this; most will manage state for you if you stop fighting them.

The other causes, most common first​

1. Trailing slash mismatch. Your library appends /, your registration doesn't have one. See the table above. Register both forms.

2. Wrong port in development. Vite on 5173, Next on 3000, your registration says the other. The port is part of the match.

3. http vs https. Terminating TLS at a proxy and forwarding plain HTTP inside makes your app build an http:// callback while you registered https://. Fix the proxy headers (X-Forwarded-Proto) rather than registering the insecure URI.

4. The client isn't the one you think. Multiple clients, similar names, and you're editing the wrong one — or you're in the wrong realm entirely. The log line names the clientId; check it against what your app sends.

5. Configuration didn't reach the server you're testing. Realm imported into one instance, browser pointed at another. More common than it sounds with Docker Compose.

6. IdP-initiated or broker flows. The redirect_uri in play may be constructed by Keycloak's broker rather than your app, and needs registering on the client the broker finally lands on.

Verify your fix without a browser​

Ask the authorization endpoint directly:

CLIENT=demo-app
REDIRECT=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" \
  "http://localhost:3000/callback")

curl -s "http://localhost:8080/realms/demo/protocol/openid-connect/auth\
?client_id=$CLIENT&redirect_uri=$REDIRECT&response_type=code&scope=openid" \
  | grep -q "Invalid parameter" && echo "REJECTED" || echo "accepted"

That is exactly how the tables above were produced. It turns a ten-minute click-and-reload loop into a one-second check, and it is trivial to wrap in a loop over every URI your app might send.

Stop it recurring: register URIs as code​

Redirect URIs drift because they are edited by hand in a console, per environment, by whoever is unblocking themselves that afternoon. Put them in version control instead:

kcadm.sh update clients/$CLIENT_UUID -r demo \
  -s 'redirectUris=["https://app.example.com/callback","https://app.example.com/callback/"]' \
  -s 'webOrigins=["https://app.example.com"]'

Or with the Terraform provider, so every environment is derived from one definition rather than remembered.

A word on wildcards and security​

It is tempting to end the pain with * or https://app.example.com/* and move on. Resist the broad version.

Redirect URI validation is the control that stops an attacker turning your login endpoint into a credential-stealing redirector: they send a victim to a genuine Keycloak login, and the authorization code lands on a host they own. Every wildcard you add widens that.

Practical rules:

• Never register a bare *, or a wildcard covering a whole host you don't fully control.
• Avoid wildcards on anything that serves user-generated content.
• Prefer a small list of exact URIs. You usually need two or three, not a pattern.
• Wildcards in development are fine. Wildcards in production want a reason.

Keycloak has tightened wildcard handling over successive releases precisely because loose patterns were being exploited. If an upgrade broke a redirect that used to work, that is usually why — and the fix is a narrower URI, not a workaround.

The short version​

1. Read the server log for error="invalid_redirect_uri" — it names the exact URI.
2. Compare it to the registered list, watching for trailing slashes, port, and scheme.
3. If it has a ?, that's your problem — move the data into state.
4. Verify with curl against the authorization endpoint, not by clicking.
5. Register the URIs as code so it doesn't drift back.

Running Keycloak in production means owning these details across every environment and every upgrade. Phase Two runs managed Keycloak so you don't have to — including the upgrades that change wildcard behaviour. Or work through the Keycloak tutorials if you'd rather learn it yourself.

Should you upgrade?​

Security fixes​

Counted from the release notes: 20 security bullets, 20 CVE ids.

CVE-2026-18214 and CVE-2026-18215 (medium, 6.8) are the reason to move. If you restricted a Google broker to a Workspace domain or a Microsoft broker to one tenant, token exchange ignored that: a valid token from any other domain bought a Keycloak token.

CVE-2026-35563 (high, 8.8) does not reach a running server. The upstream issue calls it "present in Keycloak's development dependencies", the fix was an ApacheDS test-server upgrade, and org.apache.directory.api appears only under util/embedded-ldap/ and testsuite/. LDAP federation uses JNDI.

CVE-2026-19729 has no advisory, so it carries no severity. Keycloak calls it an incomplete fix for CVE-2026-9083 (GHSA-7pm9-g8jh-3m74) — filesystem probing by a manage-realm admin. Weigh it from NVD.

If you run 26.4, 26.5 or 26.6​

Every advisory here lists affected and patched versions as "Unknown". The upstream issues do better — each carries release/ labels naming the branches its fix is headed for. Checked 2 September:

Keycloak tags backports without publishing a release, so 26.6.6 and 26.4.15 are real despite nothing announcing them, and we publish container images for both. Both predate this work. If a row above applies, the answer is 26.7.3.

Breaking changes​

Two, both in the upgrading guide:

• OIDC parameters in redirect URIs are rejected by default — those containing state, code or session_state now fail. This is the hardening behind CVE-2026-18209. Escape hatches exist (allow-oidc-params-in-redirect-uris, per-client allow.oidc.params.in.redirect.uris) but are deprecated and go in Keycloak 27.
• Authorization services claim handling — the kc. prefix is reserved, and user claims using it are filtered before policy evaluation. On a collision, permission-ticket claims beat claim_token claims.

Also deprecated: inviteLink is no longer returned by the organization invitation endpoints — the fix for CVE-2026-16072.

What else changed​

Three of 19 bug fixes matter at many-realm scale: admin API cost growing super-linearly with realm count since 26.7.1 (#51554), lightweight access tokens resolving every role in every realm per admin request (#51707), and sustained high CPU on all nodes (#51523). If your cluster got hot after 26.7.1, this is it — the shape of problem behind our event-storage work.

How to upgrade​

Read the migration changes first; the release notes stop at 26.7.0. Test the redirect-URI change on a staging realm — the only thing here that breaks a working login. Our security docs cover controls several of these CVEs bypassed; Organizations users, note the invitation change.

Rather not schedule it? Our managed Keycloak clusters are patched in our maintenance windows, under SOC 2 Type II and ISO 27001. Talk to us.

The Problem: Your Auth Database Is Not an Analytics Database​

Out of the box, Keycloak stores events in the EVENT_ENTITY and ADMIN_EVENT_ENTITY tables via its JPA event store. This works fine for a small realm. It works a lot less fine when you're hosting many busy realms:

• Event writes ride the request transaction. The JPA event store persists events inside the same transaction as the request that produced them. Every login is now gated on an extra insert: if the database is slow, the request thread waits; if event persistence fails, it can take the whole request down with it. Your users are paying an event-storage tax on every authentication, and your busiest login day is also your busiest event-write day.
• Big tables are operationally fragile tables. Once EVENT_ENTITY grows into the tens or hundreds of millions of rows, routine maintenance becomes dangerous. A Keycloak upgrade that touches the event schema can hold a lock on a table that every in-flight request is trying to insert into — and now request threads are hanging behind a migration. The same goes for adding an index or any other DDL you'd normally consider harmless.
• Expiry is a bulk DELETE against your hot path. Keycloak's event expiry doesn't make old events quietly disappear — it runs mass deletes against the very tables your logins are writing to, generating lock contention, vacuum/bloat pressure, and I/O spikes. So you're stuck choosing between unbounded growth and periodic self-inflicted incidents, and either way you lose the long history your customers actually want.
• Queries that hurt. "Show me all failed logins for this user over the last 90 days" is an analytics query: a full scan over a huge, write-hot, row-oriented table. Running analytics queries against your production auth database during business hours is how you end up on a status page.

Our customers were asking good questions — How many active users did we have last month? When did failed logins spike? Who changed that client configuration? — and the honest answer was that the default event store isn't built to answer them at scale.

We wanted three things at once:

1. Keep the auth database small, fast, and boring.
2. Keep events forever (or at least long enough for real analytics and audit).
3. Make months of events queryable in milliseconds, with dashboards on top.

The Insight: Events Are Logs​

An authentication event is immutable, timestamped, and append-only. That's not a database row — that's a log line. And modern infrastructure is extremely good at moving, storing, and analyzing log lines cheaply.

So instead of treating the database as the system of record for events, we restructured the whole thing as a pipeline:

Each stage does one job, and each stage is independently scalable. Let's walk through them.

Step 1: An Open-Source EventStoreProvider That Writes Events as Structured Logs​

The foundation lives in our open-source keycloak-events extension (also on Maven Central). We added a new implementation of Keycloak's EventStoreProvider SPI: the MDC Logger Event Store (ext-event-mdc-logger-store).

Instead of (or in addition to) writing events to JPA, it flattens each user and admin event and emits it as a structured log line, with every field carried in the MDC (Mapped Diagnostic Context). When Keycloak logs to JSON on stdout — standard practice in containers — every event comes out as a machine-parseable record:

{
  "timestamp": "2026-06-22T14:03:11.402Z",
  "loggerName": "io.phasetwo.keycloak.EVENT_LOGGER",
  "message": "Event Logger",
  "mdc": {
    "event.class": "USER",
    "event.id": "a1b2c3d4-...",
    "event.type": "LOGIN",
    "event.realmName": "acme",
    "event.clientId": "web-app",
    "event.userId": "8f14e45f-...",
    "event.ipAddress": "203.0.113.7",
    "event.time": "1750601391402",
    "event.detailsJson": "{\"auth_method\":\"openid-connect\", ...}"
  }
}

A few design decisions turned out to matter a lot:

Dual write is a config flag, not a fork. The provider can wrap Keycloak's built-in JPA event store, so you can run both stores side by side while you build out your pipeline. Events land in the database (so the Admin Console and Events REST API keep working exactly as before) and in your logs. Once your downstream pipeline is trustworthy, flip use-jpa off and your database stops accumulating events entirely:

export EXT_EVENT_MDC_LOGGER_ENABLED=true
kc.sh build
kc.sh start \
  --spi-events-store-provider=ext-event-mdc-logger-store \
  --spi-events-store-ext-event-mdc-logger-store-use-jpa=true

Events are emitted post-commit. Events are queued in the Keycloak transaction and only logged after it commits. A rolled-back request never produces a phantom event, so your analytics never disagree with reality.

MDC context is scoped, not leaked. Keycloak reuses executor threads, and MDC state is thread-local. The provider sets the event.* MDC keys inside a try-with-resources scope and restores the previous values immediately after the log call, so event fields never bleed into unrelated log lines on the same thread.

Separate loggers for user and admin events. User events go to io.phasetwo.keycloak.EVENT_LOGGER and admin events to io.phasetwo.keycloak.ADMIN_EVENT_LOGGER, which makes downstream routing and filtering trivial — you match on the logger name, not on fragile message parsing.

Graceful degradation. When JPA is disabled, the provider returns empty query results rather than throwing, so the Admin Console's Events tab degrades quietly instead of erroring.

This provider is Elastic License 2.0 like the rest of the keycloak-events extension — free to use in your own deployments. Everything downstream of it is just standard logging infrastructure, which is exactly the point: once your events are structured log lines, the entire observability ecosystem becomes your event store.

Step 2: Filter and Ship — Fluent Bit, Loki, and S3​

On every node in our clusters, Fluent Bit tails the Keycloak container logs and does the routing:

• Full Keycloak logs go to Loki (itself backed by S3, with a 90-day retention policy) for operational debugging and ad-hoc log queries.
• Event lines only — matched by those two dedicated logger names — get a much more interesting treatment. Fluent Bit strips each record down to just the mdc payload, redacts PII fields like IP addresses and usernames before they ever leave the node, and writes the results as JSON-lines files to a dedicated S3 bucket, partitioned by cluster and date.

That filtering step is what keeps the pipeline lean. Loki holds everything for the ops team; the events bucket holds exactly one clean, structured record per event and nothing else. S3 becomes the durable, dirt-cheap, infinitely-retained system of record — and because it's just JSON in a bucket, we're never locked into any particular downstream consumer.

Step 3: ClickHouse Ingestion with S3Queue​

For the analytics layer we chose ClickHouse, running alongside each cluster. The ingestion mechanism is one of ClickHouse's best-kept secrets: the S3Queue table engine, which continuously watches an S3 prefix and streams new files in as they appear:

CREATE TABLE keycloak_events.s3_keycloak_event_queue (raw String)
ENGINE = S3Queue('https://<bucket>.s3.amazonaws.com/*/*/*', JSONAsString)
SETTINGS mode = 'unordered',
         keeper_path = '/clickhouse/s3queue/keycloak-events';

No Kafka, no scheduled batch jobs, no ingestion service to babysit. ClickHouse's Keeper tracks which S3 objects have been processed, giving us reliable exactly-once-style ingestion with zero moving parts beyond ClickHouse itself.

From the queue, a chain of materialized views does the shaping:

1. A raw landing table (MergeTree, partitioned by month) captures every line with its source file metadata and the extracted cluster, realm, and event class.
2. Typed tables for user and admin events extract each event.* field into a proper column — event_type, user_id, client_id, ip_address, operation_type, resource_path, and so on. These use ReplacingMergeTree keyed on ingest time, so if a file is ever re-delivered after a crash, duplicates collapse away at merge time.
3. Five-minute rollup tables (SummingMergeTree) pre-aggregate event counts by realm, event type, and error. Five minutes divides evenly into every interval our dashboards offer (15 minutes, 1 hour, 1 day), so a single rollup grain serves every zoom level.

One honest lesson from production: we initially experimented with S3-backed MergeTree storage for the ClickHouse tables themselves, and walked it back. Every part write, merge, and TTL operation turned into S3 PutObject churn — on the order of 150 requests per second per cluster — and the API request costs showed up on the bill fast. Local NVMe-backed volumes for the tables, with S3 as the ingestion source and archive, turned out to be the right split.

Step 4: A Lambda Gateway to Expose Queries as Web Services​

ClickHouse lives on a private network, and we didn't want dashboards talking SQL to it directly. So we put a small AWS Lambda behind an HTTP API Gateway in front of it, exposing a handful of purpose-built REST endpoints:

• /insights/user-events and /insights/admin-events — filtered, paginated event search (by realm, event type, user, client, IP, time range, plus full-text search over event details)
• /insights/metrics — named, pre-defined aggregations: successful and failed logins, registrations, password resets, MFA enrollment, lockouts, DAU/WAU/MAU, and a session-concurrency estimate

The security model is deliberately narrow. API Gateway validates a JWT on every request (issued, naturally, by Keycloak). The Lambda then checks a cluster claim in the token against the cluster being queried, so a tenant can only ever see their own events. And there is no free-form SQL anywhere in the API — every endpoint maps to a parameterized query using ClickHouse's native {param:Type} placeholders, which makes injection structurally impossible rather than merely filtered.

The metrics endpoints read from the rollup tables and re-bucket the five-minute grain to whatever interval the caller asks for, so even "show me a year of logins by day" comes back in tens of milliseconds.

Step 5: Dashboards People Actually Use​

The final layer is the UI in the Phase Two dashboard: an events section per cluster with two complementary views.

Metrics shows stacked charts of user events by type and admin events by resource and operation, plus a grid of the questions customers actually ask: successful vs. failed logins over time, daily active users, DAU/WAU/MAU tiles, new registrations, password resets, MFA enrollments and removals, login error breakdowns, and session concurrency. Drag-select on any chart zooms every chart on the page to the same window.

Event search is a virtualized table over the raw events with the full filter set — realm, event type, user, client, IP, time range, free-text search over event details — and a detail drawer showing the complete event payload with copy-to-clipboard JSON.

The little UX decision we're proudest of is the drill-down: click any segment of a stacked bar — say, the LOGIN_ERROR slice at 3 AM on Tuesday — and you land in the event search view, pre-filtered to that event type and that time bucket. Aggregate to instance in one click. That interaction is only cheap because the layers below it are: the chart is a rollup-table query and the drill-down is a typed-table query, both answered by the same gateway in milliseconds.

What We Got​

The scoreboard after moving event storage out of the database:

• The auth database does auth. Event writes, event expiry deletes, and analytics queries are gone from the hot path entirely.
• Retention is no longer a trade-off. S3 keeps the raw events indefinitely for peanuts; ClickHouse keeps them queryable.
• Analytics got fast. Questions that were previously unaskable — a year of login trends across a busy realm — return interactively.
• Every layer is replaceable. Because the contract between Keycloak and everything else is just structured JSON log lines, you could swap Loki for Elasticsearch, ClickHouse for BigQuery, or our dashboard for Grafana, and the provider wouldn't know or care.

Build It Yourself​

The piece that makes all of this possible — the MDC Logger EventStoreProvider — is open source in p2-inc/keycloak-events, alongside our webhook and scripting event listeners. If you run your own Keycloak, you can drop in the extension, enable the provider, and point whatever log pipeline you already have at those two logger names. The README covers configuration in detail, and we'd love to hear what you build on top of it.

And if you'd rather not run any of this yourself — the provider, the pipeline, the ClickHouse cluster, the dashboards — that's quite literally what we do. Every Phase Two hosted deployment gets this event analytics stack out of the box, along with a team that has already found the sharp edges for you.

Want to talk Keycloak event analytics, or scaling Keycloak in general?

• 📩 Reach out to the team →
• 👉 Get Started with Free Managed Keycloak

Log into the dashboard and click Create Cluster to pick the new tier and provision yours.

What you get​

A Starter cluster is a real dedicated Phase Two Keycloak cluster — not a shared realm carved out of someone else's resources. That means:

• Your own dedicated compute, network, and storage. No noisy neighbors, no shared connection limits, no contention for cache.
• The full Phase Two enhanced Keycloak distribution — Organizations, Magic Links, Webhooks, the IdP Wizard, and the rest of our open-source extension library bundled in.
• Custom domains (CNAME) for your login portals.
• Cluster observability — uptime, logs, and usage metrics surfaced through the new dashboard.
• The same managed CockroachDB tier powering our larger plans, in partnership with Cockroach Labs.
• All the regions we support — pick whichever is closest to your users.

Starter is built to be genuinely capable, with resource limits set where most early-stage teams actually need them — enough headroom for real production workloads and development environments. When you need more, our existing higher-capacity cluster offerings are ready for you. They've proven themselves capable for many teams pushing serious throughput, with a larger resource envelope and a matching SLA — and you can scale straight up from Starter into them without re-provisioning.

Who it's for​

We built Starter for two specific shapes of team:

1. Teams ready to move past evaluation. You've validated Phase Two on a free realm, you're getting close to a real launch, and you want to put your auth on its own infrastructure with a predictable monthly price.
2. Dev and staging environments. You're already running a dedicated cluster in production and want a matching environment that doesn't double your bill. Starter is intentionally priced so a team can comfortably run a cluster-per-environment without thinking twice.

If your use case is large or mission-critical from day one, our higher-capacity clusters remain the right choice. Starter is the on-ramp, not the destination — and clusters scale up from Starter into the larger tiers without a re-provision.

Try it for 30 days, free​

Every new Starter cluster includes a 30-day free trial. That's enough time to wire your application up against a real cluster, run integration tests, validate SSO connections, and decide whether it fits the way you work. If you're still validating at day 30, talk to us — we'd rather give you the runway than rush you.

How to provision one​

1. Open the dashboard.
2. Click Create Cluster.
3. Pick Starter as the tier.
4. Choose your region.
5. Watch it provision (most clusters are live within 30 minutes).

Detailed setup walkthroughs live in the Cluster docs.

What this means for our free shared realms​

Alongside the Starter launch, we are discontinuing our free, shared-realm offering. Free realms have served us well — they've onboarded thousands of teams over the years and given us a clear picture of how people validate Phase Two — but they've also become harder to operate sustainably as our paying-customer footprint has grown.

The Starter tier (with its 30-day trial) is now the path from "I want to try this" to "I'm running it in production." We think it's a clearer journey, and it gives us a single class of infrastructure we can invest in deeply rather than splitting effort between shared and dedicated systems.

Migration timeline​

If you currently have active realms on our free, shared infrastructure:

• You have 30 days from today (2026-06-30) — through 2026-07-30 — to upgrade and migrate your realms if you want to preserve them.
• After 2026-07-30, the shared infrastructure will be shut down and its data permanently deleted.

To migrate, create a Starter (or larger) cluster from the dashboard, export your realm config from the shared instance, and import it into your new cluster. Keycloak's realm import/export guide describes the underlying mechanics, and our team is happy to walk through the migration with you.

We're here to help​

• Technical or migration questions — email support@phasetwo.io.
• Pricing, upgrade paths, or help picking the right tier — email sales@phasetwo.io.

Whichever way you contact us, the actual humans who built and operate the infrastructure are the ones writing back.

Thank you​

If you've used Phase Two — free shared realm or dedicated cluster — you're part of the reason we're able to launch this tier today. We're grateful you picked us for your Keycloak hosting, and we're going to keep working to make the platform more reliable, more affordable, and more useful for what you're building.

If we've helped, we'd love a ⭐ on GitHub or a follow on LinkedIn. It genuinely matters.

— The Phase Two Team

This is the feature we're most excited about this year, because of what it changes about getting Keycloak into production. Standing up the observability layer around a Keycloak cluster — metrics pipelines, log aggregation, dashboards, alerting — is the kind of work that normally takes a devops team weeks to months. With Phase Two, it's already done. Getting up and running on a fully observable Keycloak cluster is now a matter of minutes.

See your whole system at a glance​

Start with the big picture: understanding what your cluster is doing, at a glance, without building a single chart yourself.

Event Metrics chart Keycloak authentication and admin activity over any time range: user events by type, successful and failed logins, active users per day, new registrations, password resets, MFA enrollment, and login-error reasons.

Request Metrics chart the HTTP traffic and performance of the cluster: requests by endpoint type and status class, error rate, cache hit ratio, latency and TTFB percentiles (p50 / p95 / p99), bytes served, top endpoints, and top user agents.

Spot an anomaly in a chart, then drop straight into the logs to find the exact requests and events behind it. The metrics tell you something changed; the logs tell you exactly what.

Debugging that takes minutes, not days​

When something goes wrong with an authentication flow — a login that fails intermittently, a theme that won't load, a token error that only some users hit — the slowest part has always been seeing what actually happened. Traditionally that meant SSH-ing into nodes, grepping through container logs, or waiting for someone with cluster access to pull the right files.

Phase Two Observability collapses that loop. Open the Logs section, filter to the realm and time window, and watch the relevant lines stream in live.

The streaming view gives you everything you need to chase down an issue without leaving the browser:

• Live streaming with auto-refresh, so new lines appear as they happen
• Realm and level filters (INFO, WARN, ERROR, DEBUG, TRACE, FATAL)
• LogQL-style search — |= to match, != to exclude, |~ for regex. For example, |= "LOGIN_ERROR" != "admin-cli" finds login failures while filtering out a known source, and |= "NullPointerException" surfaces Java exception lines instantly.
• Click into any line to open the full payload, logger name, and stack trace

What used to be a multi-hour, multi-person investigation becomes a few clicks.

What's included​

Observability is split into two sections in the dashboard, both fully time-range and realm filterable, with all timestamps in UTC:

• Metrics — Event Metrics and Request Metrics: aggregated, charted views of authentication activity and HTTP traffic.
• Logs — Cluster Logs (live streaming), Event Logs, Request Logs, and Download Logs for retained files you can pull for offline review, auditing, or support cases.

This is the full realization of the observability work we previewed back in February, which started with log downloads. Live streaming, structured event and request views, and the metrics charts are all here now.

Why this matters​

Running Keycloak yourself means running everything around it too — and the observability stack is one of the heaviest parts of that "everything." Phase Two gives you that layer for free, built in, from the moment your cluster comes up. Your team spends its time shipping authentication features and resolving issues, not building and babysitting monitoring infrastructure.

Zero setup. Requests, events, and logs in one place. Debugging in minutes. A production-ready, observable Keycloak cluster in the time it takes to read this post.

Ready to try it? Log in to the Phase Two Dash and open the Metrics and Logs sections on your cluster. Learn more in the Observability documentation. Questions? Reach us at support@phasetwo.io.

Then the renewal came in. The seat-based pricing, that sounded harmless when you had two customers using SSO, looks different when you have forty. Suddenly there's a line item on a board slide that scales linearly with your enterprise revenue — a parasite that eats into the very margin that the enterprise tier was supposed to fund. The CFO walks over and asks you to "fix it."

Here is the awkward truth nobody tells the engineer-on-the-spot: the WorkOS feature set has had a fully open-source equivalent for years. Keycloak handles SSO. Phase Two's organizations extension handles multi-tenant orgs. The identity provider wizard handles the same admin-portal flow your customers see in WorkOS today. The catch is that nobody wanted to spend the runway to migrate.

We've now built the tool that turns that "we'll deal with it later" debt into an afternoon of work. Why? Because WorkOS customers are starting to wake up to Keycloak, and they're coming to us in droves.

What we built​

The workos-keycloak-migrator is a small multi-module Maven project that does three things in lockstep:

Every entity we touch carries a workos.id attribute so the migrator can recognise it on every subsequent run — no duplicates, no drift.

How to use it​

We deliberately kept the runbook short. Here are the six steps:

1. Build the artifacts​

mvn -DskipTests package

This produces three jars:

• migrator/target/workos-keycloak-migrator.jar — the bulk runner.
• extensions/webhook-listener/target/workos-webhook-listener.jar — drop into Keycloak's providers/ directory.
• extensions/slow-migration/target/workos-slow-migration.jar — same place.

The build is plain Maven so it slots into whatever CI you already use.

2. Stand up a Phase Two-enabled Keycloak​

If you already run Phase Two's hosted offering or your own Phase Two containers, point at that. If you're trying this locally first, the repo ships a docker-compose.yml that brings up Postgres plus the phasetwo-keycloak image with both extension jars mounted:

docker compose up -d

3. Bootstrap the realm​

./scripts/bootstrap-realm.sh

This creates the migrate-target realm, flips a couple of Keycloak defaults that would otherwise eat our attributes (unmanagedAttributePolicy=ENABLED and sslRequired=NONE for local HTTP), and creates a migrator-cli service-account client with realm-admin. The script prints the client secret you need for step 4.

Why a service-account client? The bulk migrator authenticates against Keycloak using OAuth client-credentials. Putting it in its own client (instead of, say, reusing the admin master user) keeps the credential surface area small and auditable.

4. Run the bulk migrator​

java -jar migrator/target/workos-keycloak-migrator.jar \
  --workos-api-key=$WORKOS_API_KEY \
  --keycloak-url=https://your-keycloak.example.com \
  --keycloak-realm=migrate-target \
  --keycloak-client-id=migrator-cli \
  --keycloak-client-secret=$KC_CLIENT_SECRET \
  --source-label=production

The runner walks WorkOS in dependency order — environment roles first, then organizations, then per-org roles, then identity-provider stubs, then SCIM stubs, then users, then memberships, then directory users — and prints a summary at the end:

============= Migration summary =============
role:                    {CREATED=5}
organization:            {CREATED=7}
organization_role:       {CREATED=38}
identity_provider:       {PARTIAL=2}
user:                    {CREATED=10}
organization_membership: {CREATED=10}
Total failed: 0

Re-running picks up where the last run left off (cursors are persisted on the realm), and reports SKIPPED reason=unchanged for anything that hasn't drifted since the last sync. This is what lets you keep both systems in parallel — run the migrator daily in a cron job and the WorkOS state shows up in Keycloak each morning.

5. (Optional) Enable the extensions​

Both Keycloak extensions are opt-in per realm because we don't want a one-shot docker compose up to fan out across every realm in a shared cluster. Set:

KC_SPI_REALM_RESTAPI_EXTENSION_WORKOS_WEBHOOK_REALMS=migrate-target
KC_SPI_REALM_RESTAPI_EXTENSION_WORKOS_LEGACY_REALMS=migrate-target

(or * for "every realm") and restart Keycloak. The webhook listener will auto-register a WorkOS webhook endpoint on first boot; the slow-migration extension will install the federation component that asks our resource for users it doesn't recognise.

The webhook listener requires an HTTPS URL because WorkOS won't accept anything else for delivery. If you only have HTTP locally, the listener still serves traffic — it just skips the auto-provisioning step and waits for you to register an HTTPS endpoint yourself.

6. Re-run for reconciliation whenever you like​

The bulk migrator is idempotent and cheap to re-run. Many teams run it nightly during the parallel-operation window, then switch off WorkOS once they're happy with the diff.

What the migrator cannot import (and why)​

There are two pieces of WorkOS state that we cannot pull through the API:

SSO connection secrets and metadata.​

The WorkOS /connections endpoint exposes the connection's type (Okta SAML, Azure SAML, Google OIDC, etc.) and the organization it's attached to, but not the SAML metadata URL, the OIDC client_id/secret, or any of the SSO/SLO URLs. Those were entered into WorkOS through their admin portal by the customer's IT team and are not retrievable.

The migrator handles this honestly: it creates a Keycloak identity provider for every connection with the right providerId (saml, oidc, google, microsoft, etc.), copies the SAML signing certificate when WorkOS happens to expose it, and tags every record with workos.incomplete=true and workos.connection_id=<the original id>. You end up with a placeholder you can finish in two clicks via Phase Two's IdP Wizard — or even better, by sending a portal link to the customer's IT contact and letting them re-walk the same setup flow they already know.

SCIM directory connection auth​

Same shape: /directories tells you the directory exists, what provider (Okta SCIM, generic SCIM 2.0, Azure SCIM, etc.) and which organization it belongs to — but the bearer token your customer's IdP uses to push users is opaque to the WorkOS API. The migrator creates a Phase Two SCIM provider on the right org with a placeholder secret and the same workos.directory.incomplete=true tag so it stands out in the admin UI.

In both cases the customer's IT team has to re-establish the secret. The good news: they only have to do it once, and Phase Two's admin portal flow is the same one they already used for WorkOS, just with a different brand on it.

What happens after the migrator runs​

Three things you'll want to do in the days following the migration:

1. Walk the workos.incomplete=true records. Filter your Phase Two organizations by that attribute and you'll see exactly which connections need attention. Send a portal link to each affected customer's IT contact. They click through the same identity-provider wizard their team used in WorkOS; ten minutes later the IdP is live in Keycloak and the workos.incomplete tag goes away on the next reconciliation run.

2. Audit the scim-managed realm role. Every user that originated from a WorkOS Directory Sync gets the scim-managed realm role plus scim.directory_id / scim.directory_user_id attributes. That's your "do not deprovision" list — anyone with that role is being managed by upstream SCIM, so a manual admin deletion is going to get reversed. The role gives you an easy filter in the admin UI and a stable bit of state you can hook into your own provisioning logic.

3. Install the slow-migration extension (if you haven't already) before pointing your login UI at Keycloak. Without it, users whose passwords never made it through the migration (WorkOS doesn't let us export them — they're hashed, scoped to WorkOS's authentication endpoint) will fail their first login. With it, their first login gets verified against WorkOS by our extension, then their password hash is captured and stored in Keycloak. After that they look identical to a native Keycloak user.

Once those three things are done you can flip your AuthKit-style flows to Keycloak, point your application at the new realm, and start the WorkOS cancellation timer.

The bigger picture​

If you've made it this far you're probably nodding along — the technical migration is straightforward, the gotchas are small, and the math on the new cost line is much better. But it's worth saying out loud what the rest of the move looks like.

WorkOS's pitch was always "we make enterprise auth easy for SaaS developers." The pitch worked because, until recently, the open-source alternative had no admin portal, no IdP wizard, no SCIM Box, no domain verification flow — only the raw Keycloak primitives. To replicate WorkOS's developer experience you had to build the whole admin surface yourself.

Phase Two has built that admin surface. The organizations extension gives you multi-tenant orgs with role-based assignments. The IdP Wizard replaces the WorkOS connection setup flow. Phase Two SCIM gives you the same managed directory-sync experience. The portal link experience lets you delegate SSO/SCIM setup to your customer's IT team without giving them admin access to your Keycloak — exactly the same delegation model WorkOS uses, with the same UX, just running on Keycloak you control.

The crucial difference, and the reason the migration is worth doing: Phase Two's pricing doesn't grow with your enterprise revenue. SSO, SCIM, organizations, branding, the wizard — they're all part of the platform, not metered features. Your cost stays a predictable budget line item whether you have ten enterprise customers or ten thousand.

The migrator we just walked through is, in that sense, the smallest part of the story. It's the bridge that lets a team that originally chose WorkOS for time-to-market cross over to a platform that doesn't tax that decision forever.

If you've got a WorkOS migration on your roadmap and would like a hand, reach out — we've now done this end-to-end on a real WorkOS Sandbox tenant and the tooling is open source. We'd be happy to walk you through it.

This is the piece of the multi-tenant story that Keycloak's stock SCIM support doesn't address today, and it's been a heavily requested item from customers running Organizations in production.

How this differs from Keycloak's experimental SCIM​

Keycloak shipped its own experimental SCIM 2.0 capability in version 26.6, and it's worth being clear about how the two relate, because the names overlap but the scopes don't:

• Keycloak's SCIM is realm-level. An external IdP provisions users into the realm. There is one SCIM endpoint per realm and one population of users. That model is fine when a realm represents a single customer or a single workforce — it's the classic Keycloak deployment shape.
• Our SCIM is organization-level. An external IdP provisions users into a specific organization within a realm. There is one SCIM endpoint per organization, and each one has its own authentication configuration, its own optional IdP federation link, and its own member graph. The realm can host thousands of organizations, each backed by a different upstream identity system, without those populations bleeding into each other.

If you're running a B2B SaaS where each customer is an Organization, the realm-level model isn't what you want — you'd be asking every customer's IT department to provision into a shared pool. The per-organization model is the natural fit: each customer's IdP gets its own SCIM URL, its own credentials, and provisions only into its own tenant.

Both are experimental. They're not in competition — they're solving different problems at different layers — and over time we expect the realm-level and organization-level capabilities to coexist in the same Keycloak deployment.

What's in the release​

The capability ships disabled by default and is gated by a realm-level flag. Once enabled, each organization gets:

• A SCIM 2.0 endpoint at /realms/{realm}/scim/v2/organizations/{orgId}/ exposing the standard SCIM resources (/ServiceProviderConfig, /ResourceTypes, /Schemas, /Users, /Groups).
• A SCIM tab in the organization detail page of the admin UI for configuring authentication and provisioning behavior.
• A REST configuration API at /realms/{realm}/orgs/{orgId}/scim for the same operations.
• Four authentication modes for inbound provisioning calls: KEYCLOAK (Bearer access token), EXTERNAL_JWT (validated against an upstream issuer + JWKS), EXTERNAL_SECRET (shared bearer secret), and EXTERNAL_BASIC (HTTP Basic). Cleartext secrets and passwords are hashed with Argon2id before persistence.
• Optional federation to the organization's configured identity provider, so provisioned users can immediately sign in via the org's existing SSO.

The full surface is documented in docs/scim.md in the keycloak-orgs repo.

What "experimental" means here​

The API shape, the configuration schema, and the realm-level enablement flag may change in a backwards-incompatible way before we mark it stable. If you take a dependency, pin to a specific version of keycloak-orgs and read the changelog before upgrading.

That caveat isn't theoretical — we're still iterating on the authentication mode set, the configuration shape for credential rotation, and the exact semantics around the IdP linkage. We'd rather get those right than freeze them prematurely.

Credit where it's due: Metatavu's keycloak-scim-server​

The SCIM 2.0 server implementation underneath this is Metatavu's keycloak-scim-server — an open-source SCIM provider that handles the protocol-level work of speaking SCIM 2.0 to upstream IdPs. We've been building on top of it, contributing back, and maintaining a fork tuned for the per-organization model.

Metatavu's project is itself under active development, and so is our use of it. The two efforts are happening in parallel: Metatavu is iterating on the core SCIM server, and we're iterating on the organization-aware layer that sits on top. Neither codebase is "done."

What both projects do have, despite the experimental label, is active production users today. Metatavu has been running their SCIM server in real deployments, and Phase Two customers are already using the per-organization variant against real upstream IdPs. The "experimental" tag reflects the rate of change in the API surface, not the maturity of the underlying provisioning logic.

If you're evaluating this for a production rollout, the realistic posture is: it works, it's being used, and you should expect to update your integration when the configuration shape evolves. Pin versions and follow the changelog.

Getting started​

If you're already running Phase Two's Keycloak extensions, upgrade to the latest keycloak-orgs, enable the realm-level scimEnabled flag, and the SCIM tab will appear on each organization. The SCIM docs walk through the realm flag, the per-organization configuration, and each of the four authentication modes.

If you want to skip the self-host setup, you can try this on a Starter cluster in the Phase Two Dashboard, free for 30 days — the same Organization SCIM capability is available there.

Feedback, bug reports, and use-case stories are all welcome on the keycloak-orgs issue tracker or directly to support@phasetwo.io. The faster we hear from real integrations, the faster we get this to stable.

We've completely rebuilt our bundled Keycloak themes. What used to live as a tangle of custom pages inside a forked Keycloak repository is now a first-class Keycloakify-based React application that ships four themes: login, admin, account, and email. The result is faster to maintain, far more capable, and dramatically better out of the box for the organizations using Phase Two today.

Starting now, all Phase Two containers ship with this theme bundled. Any realm you create through the Phase Two Dashboard automatically gets the new login, admin, account, and email themes active—no configuration required. The first time a user hits your login page or receives an email from your realm, it already looks good.

Why We Did It​

The old setup worked, but it accumulated debt fast. We maintained a fork of the Keycloak repository with admin UI customizations living on branches named things like 26.3.0_orgs_adminui. Every Keycloak release meant rebasing those changes, resolving conflicts across thousands of lines of upstream JavaScript, and hoping nothing subtle broke. Testing required spinning up a full Keycloak image just to verify a button label.

Beyond the maintenance burden, the old approach had strong limits on what we could do. The login theme was limited by what you could do with PatternFly (RedHat's design framework). The email theme was limited to just overrides but you couldn't easily brand it. The admin console tweaks were limited to what we could fit into the existing UI without breaking things. And we had not even touched the account theme, which meant users had a completely different experience once they logged in. Lastly, when users jumped from our dashboard into the Keycloak admin console, the experience was jarring because it didn't reflect the product they had just been using.

We wanted:

• Maintainability that didn't require tracking every Keycloak release by hand
• Runtime configurability so customers can change logos and colors easily without needing to redeploy or write custom themes
• A richer admin experience for managing organizations, members, roles, and styles
• A modern, polished look that doesn't feel like enterprise software from 2015
• A proper dashboard for navigating what Phase Two adds on top of Keycloak
• Modern fonts, layouts, and components that look good. Something about the RedHat fonts didn't seem to have the polish that most modern products have

A combination of Keycloakify and Phase Two's large extension capabilities made it possible to build this without needing to fork Keycloak or maintain custom JARs with static templates.

If you want to start trying it now, grab our latest image from Quay.io or try it out on the Phase Two Dashboard.

The Stack​

The new theme, called phasetwo-ui, is a React application built with:

• Keycloakify 11 — bridges React components to Keycloak's theme SPI, handles JAR packaging automatically
• shadcn/ui + Tailwind CSS 4 — modern, composable component library for the login and account themes
• PatternFly 5 — used in the admin and account console to avoid a complete rewrite of those complex interfaces while still allowing us to inject our own styles and components
• Vite — fast builds and hot module replacement during development
• Storybook — isolated component development and visual testing
• Playwright — end-to-end tests that exercise the admin UI against a real Keycloak instance

The Java side extends the Keycloak SPI to handle runtime theme loading, dynamic CSS generation, Mustache template rendering, and a configurable email sender. All of it ships as a single JAR dropped into the Keycloak providers/ directory.

Login Theme​

Out of the box, Keycloak's default login pages are functional but bare. The new phasetwo-ui login theme replaces them entirely with something that looks like a product, not a framework demo. It's a two-column layout with the branding panel on the right on desktop and a mobile-optimized single-column view on smaller screens. It supports all 21+ standard Keycloak login flows: standard authentication, registration, password reset, TOTP setup, WebAuthn enrollment, account deletion, email verification, identity provider linking, OAuth consent, and error handling.

For new Phase Two realms, this is now the default. Your users will see this from day one.

The bigger story is runtime configurability. Every visual element of the login page is controlled by realm attributes—no redeploy required:

• Logo — set a URL and it shows up immediately
• Favicon and app icon — same approach, including PWA-ready app icons
• Primary, secondary, and background colors — picked in the admin UI, reflected instantly in login
• Custom CSS — inject arbitrary overrides without touching templates

These attributes are served through a dynamic /realms/<realm>/assets/css/login.css endpoint that the Java SPI generates on the fly, mapping realm attributes to the right CSS variables.

Dark mode is supported. Language switching is built in. Fallback logos handle the case where a custom logo URL fails to load.

Admin Theme​

This is where the most work went, some visual but a lot of it underlying plumbing. The admin theme extends Keycloak's native admin console with a dedicated Phase Two panel that surfaces everything our extensions add.

Organizations​

The organizations section is a full CRUD interface for everything the Keycloak Organizations extension provides:

• Organization list with creation and deletion
• Organization details — name, description, display name, attributes
• Members — add, remove, view member details and organization-scoped attributes
• Roles — create and manage roles that are scoped to a specific organization
• Identity Providers — assign IdPs to organizations and configure sync modes
• Domains — domain-based routing configuration
• Invitations — send and manage membership invitations by email
• Settings — enabled/disabled state and other org-level configuration

The API calls are fully typed against our OpenAPI schema, so the UI and the API stay in sync automatically.

Custom Styles​

The styles panel gives realm administrators direct control over branding without writing any code. It has four tabs:

1. General — upload URLs for logo, favicon, and app icon with live image previews
2. Login — color pickers for primary, secondary, and background colors plus a CSS editor for arbitrary overrides
3. Email — customize email template branding including footer text
4. Portal — portal-specific styling controls for the Admin Portal, a self-serve application for end users to manage their account and Organization memberships without needing access to the full Keycloak admin console

Everything saves directly to realm attributes. The login page picks up changes immediately because the CSS endpoint reads those attributes on every request.

Account Theme​

The account theme wraps Keycloak's standard account management UI in the same visual language as the login and admin themes. Users get a consistent branded experience whether they're logging in, managing their sessions, or updating their profile. A session expiration warning overlay prevents users from losing unsaved changes mid-session.

Email Theme​

The default Keycloak email templates are plain text in a minimal HTML shell. They get the job done, but they don't reflect well on the product they're sending from. Our new email theme replaces that with a professional, fully branded layout—clean typography, your logo embedded directly in the message, a structured content area with appropriate padding and shadow, and a configurable footer. All coupled with an in-page preview experience. Emails from your realm will look like they came from a real product from day one.

For realms created through the Phase Two Dashboard, this is now the default. No setup required.

Beyond the out-of-the-box look, we addressed the deeper problem: email was arguably the most rigid part of the old setup. Static Freemarker templates meant any copy or branding change required a build and deploy. We replaced that with two mechanisms.

Attribute-based template overrides — any .ftl template can be overridden by setting a realm attribute with the key _providerConfig.theme.email.templates.<template-name.ftl>. Message strings work the same way via _providerConfig.theme.email.messages.<message-key>. No redeploy, no file system access required.

Mustache template support — we ship an alternative EmailTemplateProvider implementation that renders Mustache templates in addition to Freemarker. This opens up a simpler, more readable template syntax and lets customers supply their own templates through the admin UI without needing to understand Freemarker's quirks.

The email layout is configurable without touching templates: set footer text lines and a logo URL from the Phase Two → Styles → Email panel in the admin console and they reflect immediately.

The Dashboard​

One of the additions we're most excited about is the Phase Two Dashboard—a dedicated view in the admin console that gives realm administrators a high-level picture of their deployment at a glance. Organizations, members, and activity stats surface immediately without having to drill into individual sections. It's the kind of overview that makes Keycloak feel less like a configuration interface and more like a product. We have started basic here, but will continue to expand the dashboard with more insights and actionable items over time.

Easier to Maintain​

The practical benefit for us is that upgrading Keycloak no longer means rebasing thousands of lines of forked admin UI JavaScript. Keycloakify handles the bridge between our React components and the Keycloak theme SPI. When Keycloak's admin UI packages update, we update our Keycloakify dependencies. Our customizations live in well-defined extension points, not in modified copies of upstream files.

We also get proper tooling for the first time: Storybook for developing components in isolation, Playwright tests that exercise the admin UI against a real Keycloak instance, and a docker compose up local environment that lets any developer work on the theme without needing deep Keycloak internals knowledge.

How to Get It​

Phase Two managed service — it's already there. All containers now ship with the phasetwo-ui theme bundled. New realms created through the Phase Two Dashboard have it active automatically. Existing realms can switch by setting phasetwo-ui as the theme for login, admin, account, and email in realm settings, then configuring branding from the Phase Two → Styles panel.

Self-hosted with the Phase Two image — the theme is included in the Phase Two Keycloak image. Pull the latest image and select phasetwo-ui in your realm theme settings.

Self-hosted with your own Keycloak — build and install from the open source keycloak-themes repository:

mvn clean install -DskipTests
cp target/keycloak-themes-*.jar /path/to/keycloak/providers/

Restart Keycloak and select phasetwo-ui for login, admin, account, and email in your realm configuration.

Looking Forward​

Visual editor for login and email​

The styles panel today gives you color pickers, a logo field, and a CSS editor. That covers a lot, but we want to go further. We're building a visual editor directly into the Phase Two Dashboard that lets you make fine-grained design changes to your login and email themes—adjusting layout, spacing, typography, background images, and component styles through a live preview interface rather than writing CSS by hand.

The goal isn't to replace a fully bespoke login experience. Some brands need total control, and the custom CSS path will always be there for that. But for the vast majority of teams, getting 95% of the way there without a designer or a build pipeline is exactly what's needed. Your login page should feel like it belongs to your product, and we think that should be achievable in an afternoon, not a sprint.

More capability in the Admin and Account UIs​

We're continuing to expand what the admin and account UIs can do. On the admin side, more of our extension capabilities will surface directly in the Phase Two panel as we add features—so you're managing everything through the console rather than through API calls or raw attribute editing.

On the account side, we're reworking several views to feel more like a modern product interface. One early change is moving the account list views from a table layout to a tile-based interface—easier to scan, more room for useful metadata, more familiar UX, and a look that fits better alongside the rest of the theme.

For email themes, we're adding more template variables and making it easier to customize the content and layout of emails without needing to write custom templates.

If you have feedback or run into anything, open an issue on GitHub or drop us a line.

Need help customizing your Keycloak experience?​

Whether you're trying to match your brand exactly, integrate a custom identity flow, or just figure out where to start—we're happy to help. Reach out to us and we'll point you in the right direction.

Keycloak is the easiest way to do that without inventing your own authorization layer. It already handles browser login, consent, token issuance, JWKS discovery, and OAuth metadata. Your MCP server just needs to behave like a protected resource and validate bearer tokens correctly.

In this guide, we will build a tiny calculator MCP server in Python, protect it with Keycloak, and connect to it from VS Code using Dynamic Client Registration (DCR). By the end, VS Code will open a browser to Keycloak, you will sign in, approve access to the mcp:run scope, and then call your MCP tools directly from chat.

This walkthrough uses:

• The official MCP Python SDK
• One MCP endpoint at http://localhost:8000/mcp
• Keycloak as the authorization server
• A Keycloak client scope named mcp:run
• An Audience mapper that sets aud = http://localhost:8000/mcp
• Include in token scope enabled for mcp:run
• Trusted Hosts removed from anonymous client registration policies so VS Code's DCR request is accepted

If you do not want to host and configure Keycloak yourself, you can create a Starter cluster in the Phase Two Dashboard — it comes with a 30-day free trial — and use that instead of a self-hosted local Keycloak instance. The rest of the MCP-side setup stays the same.

What you are building​

We will create a small MCP server that exposes three tools:

• add_numbers
• multiply_numbers
• divide_numbers

The server will run locally and expose its MCP endpoint at:

http://localhost:8000/mcp

VS Code will connect to that URL, discover the MCP server's protected-resource metadata, discover Keycloak as the authorization server, dynamically register itself, send you through the browser login flow, and then call the tools with an access token.

That is the key mental model: the MCP server is the protected resource, and Keycloak is the authorization server.

A high-level diagram of the topology looks like this:

with data flowing through it like this:

What you need installed​

Install these first:

• Python 3.11 or newer
• Docker Desktop
• VS Code
• GitHub Copilot or another model-enabled chat workflow in VS Code

Then create a virtual environment and install dependencies:

mkdir keycloak-mcp-demo
cd keycloak-mcp-demo

python -m venv .venv
source .venv/bin/activate

pip install "mcp[cli]" "pyjwt[crypto]>=2.8.0"

This setup uses the official MCP Python SDK and PyJWT to validate Keycloak-issued access tokens.

How the auth flow works​

When VS Code first hits your MCP endpoint, it does not already have a token. The server should reject that first request with 401 Unauthorized and include a WWW-Authenticate header pointing to a protected-resource metadata document.

VS Code then:

1. Fetches the protected-resource metadata
2. Learns which authorization server protects this MCP server
3. Discovers the authorization server metadata from Keycloak
4. Dynamically registers a public client
5. Opens your browser for login and consent
6. Gets an access token back
7. Retries the MCP request with Authorization: Bearer ...

For this to work, two endpoints have to behave correctly:

• GET /mcp must return a 401 challenge when no token is present
• GET /.well-known/oauth-protected-resource/mcp must advertise the Keycloak realm and the exact MCP resource URL

Step 1: Create the MCP server​

Download the complete example server here:

• server.py

This server:

• Validates the token signature against Keycloak's JWKS
• Checks the token issuer
• Checks that the token audience matches the exact MCP URL
• Checks that the mcp:run scope appears in the token's scope claim

Start the server:

python server.py

That scope check matters. If mcp:run exists as a Keycloak client scope but is not included in token scope, the access token can come back with the correct audience but an empty scope claim, and the server will reject it. If you hit this, paste the access token into our JWT Decoder — it surfaces the scope claim and aud so you can see exactly what Keycloak emitted.

Step 2: Verify the server before using VS Code​

Before touching Keycloak or VS Code, make sure the server is advertising the right OAuth metadata.

Check the protected-resource metadata:

curl -s http://localhost:8000/.well-known/oauth-protected-resource/mcp

You should get something like:

{
  "resource": "http://localhost:8000/mcp",
  "authorization_servers": ["http://localhost:8080/realms/mcp-demo"],
  "scopes_supported": ["mcp:run"],
  "bearer_methods_supported": ["header"]
}

Then check the unauthenticated MCP endpoint:

curl -i http://localhost:8000/mcp

You should get 401 Unauthorized, and the WWW-Authenticate header should point to:

resource_metadata="http://localhost:8000/.well-known/oauth-protected-resource/mcp"

If those two responses are correct, VS Code has the discovery information it needs.

Step 3: Start Keycloak locally​

Run Keycloak in development mode:

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak start-dev

Then open:

http://localhost:8080

Sign in as:

• Username: admin
• Password: admin

If you want to skip self-hosting, create a Starter cluster in the Phase Two Dashboard instead — it starts with a 30-day free trial. For this tutorial, that is usually the fastest route because you avoid local Keycloak setup, bootstrap admin credentials, and one-off realm configuration from scratch.

Step 4: Create the realm and a test user​

Create a realm named:

mcp-demo

Then create a test user such as alice, set a password, and make sure you can sign in with it.

The realm issuer your server expects is:

http://localhost:8080/realms/mcp-demo

That exact URL must match the issuer your Python server validates.

If you want a faster setup than clicking through each screen manually, you can also import the example realm configuration:

• realm-export.json

If you are using a hosted realm from Phase Two instead of local Keycloak, use the hosted realm's issuer URL everywhere the tutorial currently shows http://localhost:8080/realms/mcp-demo.

Step 5: Create the mcp:run client scope​

Create a new client scope named:

mcp:run

Then configure it like this:

• Include in token scope: ON
• Display on consent screen: ON is fine

That first setting is essential for this implementation. The server checks the access token's scope claim, so Keycloak must actually emit mcp:run into the token.

Add the Audience mapper​

Inside mcp:run, add an Audience mapper with:

• Included Custom Audience: http://localhost:8000/mcp
• Add to access token: ON
• Add to introspection: ON is fine
• Add to ID token: OFF is fine

This is what causes the access token to carry:

"aud": "http://localhost:8000/mcp"

That audience must exactly match the MCP server URL the Python server expects.

Step 6: Make mcp:run available to DCR-created clients​

For VS Code DCR to work smoothly, dynamically registered public clients must be able to get the mcp:run scope without any manual client editing.

There are two places to check.

Add mcp:run to the realm's default client scopes​

Make sure mcp:run is included in the realm's default client scopes.

That way, a newly registered public client will inherit it automatically.

Allow mcp:run in anonymous client registration​

In the realm's client registration policies, keep the anonymous Allowed Client Scopes policy and make sure it includes:

mcp:run

That tells Keycloak that anonymous DCR clients are allowed to request the MCP scope.

Step 7: Remove the Trusted Hosts policy​

This is the piece that tends to block VS Code.

VS Code's DCR request includes multiple URLs, including redirect URIs for vscode.dev, insiders.vscode.dev, localhost, and 127.0.0.1, plus a client URI for the VS Code website. Keycloak's default Trusted Hosts registration policy rejects that request.

For this local tutorial setup, remove the Trusted Hosts policy from the realm's anonymous client-registration policies.

That is what allows VS Code's DCR payload to succeed.

You can keep the other anonymous registration policies in place, especially:

• Allowed Client Scopes
• Allowed Registration Web Origins
• Allowed Protocol Mapper Types
• Consent Required
• Max Clients Limit

But Trusted Hosts needs to go for this workflow.

Step 8: Configure VS Code​

Create .vscode/mcp.json, or download the example file:

• mcp.json

The contents should look like:

{
  "servers": {
    "calculator-local": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Then in VS Code:

1. Open the project
2. Open the Command Palette
3. Run MCP: List Servers
4. Confirm calculator-local appears
5. Start it

If you previously had failed auth attempts cached, run:

• Authentication: Remove Dynamic Authentication Providers

Then restart VS Code before trying again.

Step 9: Sign in through Keycloak​

Once VS Code connects to the server, it should:

1. Discover the protected-resource metadata at /.well-known/oauth-protected-resource/mcp
2. Discover Keycloak as the authorization server
3. Dynamically register a public client
4. Open your browser
5. Send you to Keycloak login
6. Show a consent prompt for mcp:run
7. Redirect back to VS Code
8. Retry the MCP request with a bearer token

If all the values are aligned, the server will accept the token and VS Code will discover the three tools.

At that point you can try a prompt such as:

Use calculator-local to add 12.5 and 7.25, then multiply the result by 3.

What to do if it still fails​

If the browser flow works but the MCP server still responds with 401, the next thing to check is the token itself.

In practice, there are only three claims that matter most here:

• iss
• aud
• scope

Your server expects:

• iss = http://localhost:8080/realms/mcp-demo
• aud = http://localhost:8000/mcp
• scope contains mcp:run

The most common problems are:

aud is wrong​

The Audience mapper is missing or its custom audience value does not exactly match the MCP URL.

scope is empty​

mcp:run exists as a client scope, but Include in token scope is still off.

DCR fails before login​

The anonymous client registration policies still block VS Code's DCR payload. The first place to check is whether Trusted Hosts was actually removed.

VS Code behaves inconsistently​

Clear stale auth state with:

• Authentication: Remove Dynamic Authentication Providers

Then retry.

A few implementation notes worth remembering​

The MCP server is not the identity provider​

Your MCP server does not need to implement a full OAuth server. It only needs to behave like a protected resource:

• Advertise protected-resource metadata
• Challenge unauthenticated requests with 401
• Validate bearer tokens from Keycloak

VS Code cares about the metadata, not just the token endpoint​

If the MCP endpoint does not return the right 401 challenge, or the protected-resource metadata does not point at the Keycloak realm correctly, VS Code will never get to DCR.

Audience matching is exact​

http://localhost:8000/mcp is not the same as http://localhost:8000/mcp/ or http://localhost:8000/.

Use the exact same value everywhere:

• In VS Code
• In the server
• In Keycloak's Audience mapper
• In the protected-resource metadata

Final checklist​

Before you call this done, make sure all of these match:

• VS Code MCP URL: http://localhost:8000/mcp
• Protected-resource metadata resource: http://localhost:8000/mcp
• Keycloak audience mapper custom audience: http://localhost:8000/mcp
• Python MCP_SERVER_URL: http://localhost:8000/mcp
• Required scope: mcp:run
• mcp:run has Include in token scope enabled
• mcp:run is available to DCR-created clients
• Anonymous Trusted Hosts policy is removed

If those are true, you have a clean local setup for a Keycloak-protected MCP server that VS Code can discover, register against, and use.

Why Phase Two is the easiest way to run this for real​

If you like this pattern but do not want to spend time standing up and operating Keycloak, Phase Two's hosted Keycloak offering is the fastest way to get there. You get a managed realm, a production-ready control plane, and a much shorter path from prototype to deployed MCP authorization server.

You can start with a Starter cluster in the Phase Two Dashboard — free for 30 days — for testing, and when you are ready for a hosted setup with support, upgrades, and operational help, Phase Two's managed Keycloak offering is the easiest way to run an MCP authorization server without owning the infrastructure yourself.

This milestone reflects how seriously we take security and compliance across our platform, operations, and internal processes. We completed this as a fast follow to our September 17, 2025 SOC 2 Type II compliance milestone, reaching full ISO/IEC 27001 certification just over six months later as part of our commitment to building a mature, enterprise-ready security program.

Learn more at our Trust Center: trust.phasetwo.io.

What is ISO/IEC 27001 certification?​

ISO/IEC 27001 is an internationally recognized standard for establishing, implementing, maintaining, and continually improving an Information Security Management System (ISMS).

In practical terms, it provides a structured framework for identifying risk, applying appropriate controls, documenting security processes, and continuously improving how an organization protects systems and data. Full certification means this program has been evaluated against the standard rather than being described only as an internal compliance effort.

Why this matters​

• Structured security management: ISO/IEC 27001 formalizes how security risks are identified, assessed, treated, and reviewed over time.
• Independent confidence: Certification against a globally recognized standard gives customers and prospects greater confidence in our security posture.
• Faster vendor reviews: A stronger compliance foundation helps reduce friction during procurement, security questionnaires, and customer audits.
• Continuous improvement: ISO/IEC 27001 is designed around ongoing review and maturation, not a one-time checkpoint.

A Fast Follow After SOC 2 Type II​

We take security and compliance very seriously at Phase Two. Achieving full ISO/IEC 27001 certification just over six months after our September 17, 2025 SOC 2 Type II compliance milestone was an intentional investment in operational maturity, not a box-checking exercise.

This fast follow reflects the pace at which we have continued to strengthen our internal security program, including risk management, policy development, operational controls, documented procedures, and accountability across the organization.

What this means for customers​

• Higher confidence in our processes: Our security program is built around a clear, repeatable framework for managing information security.
• Better support for enterprise requirements: Customers with formal security review processes benefit from a stronger compliance posture and clearer documentation.
• Ongoing resilience: A mature ISMS helps support secure delivery, reliable operations, and a disciplined response to evolving risks.

What’s next​

Security and compliance are continuous commitments. We will keep investing in the controls, processes, and operational rigor required to support customers with demanding security and compliance expectations.

Phase Two’s hosting product continues to support organizations across healthcare, security, retail, public sector, and more. Milestones like ISO/IEC 27001 certification help us meet the expectations of customers who need strong identity infrastructure backed by strong operational discipline.

Thank you for trusting Phase Two with your business. If you would like to learn more, please visit trust.phasetwo.io or email sales@phasetwo.io.

For the full technical deep dive, we will release slides when the talk is published on Youtube.

This post focuses on the core technical content from the presentation and summarizes what we built, what we learned, and what comes next.

Watch the talk​

Why We Took This On​

The recurring operator pain points were clear: restart complexity, JGroups/Infinispan operational friction, and upgrade risk in high-availability environments.

Our goals for the proof-of-concept were practical:

1. Functional parity with Keycloak's distributed cache behavior.
2. At least 50% of embedded Infinispan performance.
3. Fast startup (sub-5s per pod) with reliable behavior.
4. Seamless upgrades and horizontal scaling without rebalance pain.
5. Extension-based implementation on current Keycloak, without forking.

We also set explicit non-goals, including replacing local Infinispan caches, integrating/migrating persistent sessions, supporting every Redis topology, and solving multi-region concerns in v1.

What We Implemented (High Level)​

We implemented a new DatastoreProvider-based approach to replace distributed caches while leaving the rest of Keycloak behavior intact.

At a high level:

1. Stored entities as Redis hashes (session and related objects).
2. Added secondary indexes with Redis sets for fast lookup paths (for example, user-to-sessions, client-to-sessions).
3. Built a changelog-based transaction implementation of KeycloakTransaction to batch and minimize writes at the appropriate stage of the Keycloak request lifecycle.
4. Used Redis MULTI/EXEC for batched commit behavior.
5. Implemented Lua-based CAS behavior for single-round-trip atomic updates.
6. Replaced the use of the replicated work cache, used for local cache invalidation, with a Redis PUBSUB-backed ClusterProvider.
7. Exposed Redis client and command metrics in Keycloak's Prometheus endpoint (vendor_jedis_*).

For detailed APIs, object mapping rules, and transaction semantics, the slide deck has the full implementation flow and diagrams.

Notable Engineering Details​

A few areas mattered most in practice:

1. Atomicity model: Lua CAS operations reduced contention and retry complexity versus WATCH-based optimistic workflows.
2. Expiration correctness: TTL handling required careful validation to avoid stale references (for example, refresh token edge cases).
3. Behavior parity: Reproducing nuanced Infinispan behavior (especially around offline session flows and invalidation semantics) required close reading of existing Keycloak internals.
4. Index discipline: Clean separation between hash storage and set-based secondary indexes kept lookups efficient and made invalidation predictable.

Benchmarks and Outcomes​

In our benchmark setup, the Redis implementation met and exceeded the original performance target. The result was parity or better across the tested flow, while also meeting the startup-speed and extension/no-fork constraints. We used the Keycloak provided keycloak-benchmark project to execute performance tests against a 3 node cluster using Redis caching, and compared the results to a standard Keycloak setup on the same number of nodes, using embedded Infinispan.

This approach hit the proof-of-concept goals, with room for additional optimization and broader validation.

Note: lower 99th percentile values are better. The "Browser to Log In Endpoint" row is the one regression shown in the original chart.

Benchmark screenshots​

Redis benchmark test results:

Infinispan benchmark test results:

Timeline and Context​

This work started in September 2025.

A successful implementation would not have been possible without years of prior work in Keycloak internals, extension development, and production operations. Existing knowledge around map-store patterns, DatastoreProvider internals, transaction behavior, and real-world customer requirements was the foundation that made this tractable.

What's Next​

Near-term next steps include broader performance validation across workloads, clearer packaging/licensing for source and images, and additional multi-region validation/documentation.

We also plan to release a full image soon at quay.io/repository/phasetwo/keycloak-redis, so stay tuned for more.

If you want all the implementation specifics, design tradeoffs, and diagrams, please stay tuned for the release of the slides and videos of our Keycloak DevDay presentation.

Want to go deeper?

1. Reach out to our team: support@phasetwo.io
2. Try our hosting and extensions: Phase Two Dash
3. Contact us for additional implementation details and architecture guidance: https://phasetwo.io/contact

Access to logs is essential for monitoring health, diagnosing incidents, and understanding performance. With this initial release, you can filter logs by time range and download them as a zip file for offline analysis. This helps teams quickly pinpoint issues and keep their services running smoothly.

Next up: live log streaming and exports to external systems, giving you more flexibility for centralized log management and analysis.

Learn more in the Observability and Logs documentation.

Ready to try it? Log in to the Phase Two Dash and view logs for your cluster. This feature is included with all dedicated cluster plans. Questions? Reach us at support@phasetwo.io.

In Deploying Keycloak on CockroachDB with Phase Two: A Complete Guide, Cockroach Labs walks through how Phase Two and CockroachDB work together to provide a strong foundation for secure, multi-tenant identity at scale. The post outlines why strong consistency, high availability, and horizontal scalability are critical requirements for modern SaaS identity systems—and how combining managed Keycloak with CockroachDB meets those needs in production environments.

The article also includes an overview of Phase Two’s managed Keycloak offering, highlighting how teams can offload operational complexity such as infrastructure management, upgrades, backups, and high-availability configuration. By pairing this with CockroachDB’s globally distributed SQL database, organizations can deploy enterprise-grade authentication and SSO while maintaining strong consistency and predictable performance.

We appreciate Cockroach Labs’ collaboration and the opportunity to showcase how this complementary stack helps SaaS teams move faster without compromising on reliability or security.

You can read the full post on the Cockroach Labs blog here: Deploying Keycloak on CockroachDB with Phase Two: A Complete Guide

New Security Features​

We have introduced the first of several new security features that can be easily configured through the Phase Two Dash. These features are designed to enhance the security posture of your Keycloak clusters and provide you with greater control over your authentication environment.

The initial set of security features includes the ability to configure IP level access to your Keycloak clusters. There are three types of IP restrictions you can apply:

1. Admin Paths: Restrict access to the administrative interfaces of your Keycloak instance (e.g., /admin, /auth/admin) to specific IP addresses or ranges. This ensures that only authorized personnel can access sensitive admin functions.
2. Public Allowed Paths: Specify IP addresses that are allowed to access public endpoints (e.g., /token). This is useful for limiting access to known clients while blocking all other traffic. Particularly useful for development and staging environments.
3. Public Blocked Paths: Block specific IP addresses from accessing public endpoints (e.g., /token). This allows you to prevent known malicious IPs from interacting with your Keycloak instance without affecting legitimate traffic. Or to just block abuse to your application for any reason.

How to Configure Security Features​

Visit your cluster's page > Config tab > Restrictions to manage IP restrictions for your Keycloak cluster. You can easily add or remove IP addresses or CIDR ranges for each type of restriction.

Learn more in the Cluster Restrictions documentation.

Want to learn more or have feedback? Log in to the Phase Two Dash and try adding your IP restriction now. This feature is included with all dedicated cluster plans. For any questions or concerns, please reach out to support@phasetwo.io.

Why Environment Variables?​

Environment variables are a crucial aspect of configuring and managing applications. They allow you to customize the behavior of your Keycloak instances without modifying the underlying code or configuration files. This is especially important for managing sensitive information such as API keys and other configuration settings. For customers building custom Keycloak extensions or integrating with third-party services, the ability to set environment variables is essential.

With this new feature, you can easily manage your Keycloak cluster's environment variables through a user-friendly interface, streamlining the deployment and configuration process. Updates are applied seamlessly, requiring no downtime for your authentication services.

How to Set Environment Variables​

Within your cluster, visit your cluster's page > Config tab > Keycloak features. From there, you can add new environment variables or remove existing ones. You have the option to set variables as plaintext or as secrets, ensuring that sensitive information remains secure.

Learn more in the Environment Variables documentation.

Want to learn more or have feedback? Log in to the Phase Two Dash and try adding your first environment variable. This feature is included with all dedicated cluster plans. For any questions or concerns, please reach out to support@phasetwo.io.