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 free realm in the Phase Two Dashboard — 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 free realm in the Phase Two Dashboard 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 free realm in the Phase Two Dashboard instead. 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 free realm in the Phase Two Dashboard 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.

Last Friday, Niko Köbler (aka "Mr. Keycloak"), invited us to demonstrate Auth.it and explain how we built it on his livestream, Keycloak Friday Chat. If you're interested in an overview of the new platform, and would like to know the details of how it was implemented as a set of Keycloak extensions, please watch the recording of the livestream.

TL;DR​

1. Clone our Keycloak fork and check out the matching Admin UI branch (e.g., 26.3.0_orgs_adminui).
2. Replace the default server script with our custom one (details below).
3. Start a Phase Two Keycloak container with the Admin UI in dev mode:

pnpm start --admin-dev --phasetwo --tag=latest

4. In a second terminal, run the Admin UI dev server:

pnpm i && pnpm dev

Open http://localhost:8080. You’ll get auto-refresh and modern DX while the backend runs in Docker.

Why this matters​

The Admin UI is the control center for Keycloak. Customizing it is powerful, but it’s tightly coupled to the core codebase and evolves quickly. Running the UI in dev mode against the exact server image you ship (e.g., Phase Two’s extended image) lets you:

• Catch breaking changes early when Keycloak releases.
• Iterate on UI changes instantly (no re-building JARs between edits).
• Validate that your extensions render and behave correctly with real data.

Our Keycloak Organizations extension, for example, adds new sections to the Admin Console. Each release we re-verify and adjust UI components; this workflow makes that practical.

How the stock setup works (and why we tweak it)​

Keycloak’s Admin UI is now a library inside the main repo. You can run it locally against a server, but the stock start script pulls the nightly image—great for core dev, not ideal when you need to test against a specific custom image.

To fix that, we use a small custom start script that runs a Phase Two Keycloak container (or any image—see below) and wires the Admin UI dev server to it.

Prerequisites​

• Node 20+
• pnpm 9+
• Docker Desktop / Docker 24+
• Ports 8080 (Keycloak) and 5174 (Admin UI) free

Step-by-step​

1) Get the right code​

• Clone our fork and check out the branch that matches your Keycloak target (we don’t publish a branch for every upstream release):

# example
git clone https://github.com/p2-inc/keycloak.git
cd keycloak
git checkout 26.3.0_orgs_adminui

• Admin UI lives under js/apps/admin-ui/. The embedded server project lives under js/apps/keycloak-server/.

2) Swap in the custom start script​

Copy the contents of js/apps/admin-ui/src/phaseII/start-server-custom.js into js/apps/keycloak-server/scripts/start-server.js replacing its contents.

The custom script adds flags like --phasetwo and --tag and starts quay.io/phasetwo/phasetwo-keycloak:<tag> via Docker with the right dev env vars.

3) (If needed) Align the theme output name​

Our Admin UI build emits a theme named phasetwo.v2. If your environment expects keycloak.v2, either:

• Duplicate the folder theme/phasetwo.v2 and name it keycloak.v2, or
• Update vite.config.ts to output to phasetwo.v2 and keep the server pointed at that name.

4) Start the server and the UI​

• Start the server container + wire the UI dev endpoints:

cd js/apps/keycloak-server
pnpm start --admin-dev --phasetwo --tag=latest

• In another terminal, start the Admin UI dev server:

cd ../admin-ui
pnpm i
pnpm dev

Now open http://localhost:8080.

Script flags​

Under the hood we enable features required by our extensions: login:v2, account:v3, admin-fine-grained-authz:v2, transient-users, organization, oid4vc-vci, declarative-ui, quick-theme.

Troubleshooting​

• Port 8080 already in use – Stop other Keycloak/containers or change the published port.
• White screen / 404s in the Admin UI – Make sure --admin-dev is set and the dev server is running on 5174.
• Missing strings/components – Verify you’re on the matching Admin UI branch for your Keycloak version.
• Theme not loading – Ensure the output theme name (phasetwo.v2 vs keycloak.v2) matches what the server expects.
• Cannot pull image – Confirm Docker can access quay.io and that the tag exists.

Conclusion​

This workflow keeps the Admin UI dev loop fast while staying faithful to the image you deploy. Although we demonstrate with Phase Two’s image, the same pattern works with any Keycloak distribution. If this saved you time, drop us a star ⭐️ on GitHub.

Want to learn more? Log in to the Phase Two Dash and try uploading your first resource today. This feature is included with all dedicated cluster plans. For questions, reach out to support@phasetwo.io.

Why this matters​

Traditionally, managing custom Keycloak resources in Kubernetes is complex, time-consuming, and error-prone. It often requires deep knowledge of deployment pipelines, containerization, and manual version tracking. With Self-Service Resource Management, Phase Two eliminates those hurdles by giving you a streamlined interface in the Dash to manage your resources safely and reliably.

Because this feature is only available for dedicated clusters, customers benefit from the highest level of flexibility, security, and control over their Keycloak environments.

Key Features​

• Direct uploads
  Upload .jar files (themes or extensions) directly through the dashboard, tied to your dedicated cluster.

• Versioning support
  Create and manage resource versions. You can pin versions to specific Keycloak builds, which is especially useful for testing compatibility with future major Keycloak releases.

• Cluster-safe updates
  Phase Two automatically manages cluster restarts to ensure resources are applied without risking downtime or instability.

• Faster release cycles
  Reduce dependency on Phase Two deployment reviews. Customers can move quickly, automate feature rollouts, and test updates on their own timeline.

• Simplified workflows
  Avoid the overhead of Kubernetes resource management, CI/CD pipeline adjustments, and manual rollbacks. Resource management is as simple as point-and-click.

What this means for customers​

This feature brings enterprise-grade flexibility and speed to teams that rely on custom Keycloak deployments. Whether you’re testing a new extension for an upcoming Keycloak version or rolling out an updated theme across environments, you can now do it in minutes—not days. And with Phase Two’s guardrails in place, you still benefit from the reliability and security of our managed hosting platform.

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

Learn more and request report access at our Trust Center: trust.phasetwo.io.

What is SOC 2 Type II?​

SOC 2 (System and Organization Controls 2) is an attestation standard for service organizations covering five Trust Services Criteria: security, availability, processing integrity, confidentiality, and privacy. A Type II report evaluates the operating effectiveness of controls across an audit period, rather than at a single point in time (Type I).

Why this matters to customers​

• Operational assurance: Independent attestation that access control, change management, monitoring, incident response, and data protection controls worked throughout the evaluation period.
• Faster vendor reviews: A current SOC 2 Type II report reduces back‑and‑forth during security assessments and procurement.
• Lower risk, higher resilience: Tested controls help prevent incidents and improve recovery, supporting higher availability and reliability.
• Transparent accountability: The auditor’s report provides objective evidence of our security posture and ongoing commitments.

How this validates Phase Two’s approach​

Our platform and operations are engineered for secure‑by‑default deployments, repeatable releases and change control, continuous monitoring, and documented incident response. The SOC 2 Type II result demonstrates these controls function in production—not just on paper.

What’s covered in the report​

While each report is tailored to the service and period, customers can expect details on:

• In‑scope systems and boundaries
• Control objectives and mapped Trust Services Criteria (with tests of operating effectiveness)
• Auditor’s testing procedures and results
• Complementary user entity controls (CUECs) relevant to your environment

Accessing the report​

Phase Two makes the SOC 2 Type II report available to customers and qualified prospects under NDA via our Trust Center. If you need access for a vendor review, please submit a request at trust.phasetwo.io or email sales@phasetwo.io.

What’s next​

Compliance is continuous. We’ll keep strengthening automation, observability, and control effectiveness, and maintain ongoing attestation to reflect our customers’ evolving needs and the changing threat landscape.

We are actively pursuing ISO 27001 certification to further demonstrate our commitment to information security management.

What this means for you​

• Stronger trust: Independent validation you can include in your own compliance artifacts.
• Faster assessments: Streamlined security questionnaires and procurement cycles.
• Operational confidence: Controls that demonstrably reduce operational risk and improve incident response.

Phase Two’s hosting product supports organizations across healthcare, CDN and security, retail, and more—delivering predictable, enterprise‑grade identity and access management.

Need the report or have questions? Contact sales@phasetwo.io or visit trust.phasetwo.io.

Custom domains are a key piece of branding and trust for your users. By using your own domain, you can ensure that your users see a familiar URL when interacting with your Keycloak instance.

Read more about how to set up custom domains in our Custom Domains documentation.

Custom Domains Overview​

Up until this point, custom domains were offered, but had to be setup and managed by Phase Two support. Now, you can configure and manage your own custom domains directly from the Dashboard. This allows for multiple custom domains to be used as required.

Why Use Custom Domains?​

Using a custom domain for your Keycloak instance provides several benefits:

1. Branding: A custom domain allows you to maintain consistent branding across your applications and services. This helps reinforce your brand identity and provides a seamless experience for your users.
2. Trust: Users are more likely to trust a familiar domain. By using your own domain, you can increase user confidence and reduce the likelihood of phishing attacks.
3. SSL/TLS: Phase Two provides free SSL/TLS certificates for your custom domains, ensuring that all communications are secure and encrypted.

What's next?​

Phase Two has many exciting features planned for the future. Stay tuned for more updates and improvements to our platform.

A shadcn theme starter for Keycloak using Tailwind CSS and Radix UI components. This starter provides a foundation for building a custom, component-based Keycloak theme.

Phase Two are sponsors of Keycloakify as we are deeply convinced by this project's value.

The Shadcn Keycloak Theme Starter​

We chose to use shadcn as the component library for this starter because it provides a set of modern, accessible, and customizable components that can be easily integrated into Keycloakify themes. shadcn is built on top of Tailwind CSS and Radix UI, which makes it a great fit for building custom Keycloak themes.

The starter provides a basic structure for building Keycloak themes using shadcn components, including:

• Initial Setup: A basic Keycloakify project setup with shadcn and Tailwind CSS configured.
• Login Page: A customized login page using shadcn components.
• Baseline Components: A set of reusable shadcn components that can be used throughout the theme.
• Baseline Ejections: Minimum set of pages ejected to get you started with customizing the login.

Since shadcn ejects components into the project, you can customize them (or replace) as needed. This makes it quick and easy to introduce styles or components.

Options for Customizing Keycloak UI​

1. FTL Templates: Keycloak's default theming system using FreeMarker templates. This is the traditional way to customize Keycloak's UI, but it can be cumbersome and lacks modern component-based design. Phase Two provides a simple CSS customization guide for basic styling changes to avoid having to go into FTL templates.
2. CSS Customization: You can override the default CSS styles to change the appearance of Keycloak's UI. This is a simple way to apply custom styles, but it doesn't provide the flexibility of a component-based approach. Phase Two provides a simple CSS customization guide for basic styling changes to base themes.
3. Keycloakify: A modern theming solution that allows you to build Keycloak themes using React components. It provides a more flexible and maintainable way to customize Keycloak's UI, leveraging the power of React and modern web development practices.

Built-in Keycloak Themes​

The built-in Keycloak themes are built using not just FTL templates, but use PatternFly as a design library. PatternFly provides a set of components and styles that are used to build the Keycloak UI. However, it can be difficult to customize these components to fit your specific design needs. The semantics and structure is not always clear, and the CSS can be difficult to override. Components use variables without consistency and getting that right can be a challenge, leaving you wondering if you covered all your use cases.

In addition, there is no easy way to "preview" all variations of the pages. Keycloakify provides a built-in Storybook preview for all page variations.

If you follow the official Guides for theme ui-customization you will quickly find that the dev experience is an after-thought. There is only one sentence about development: "During development you can copy the theme to the themes directory,...". Knowing how the theme inherits from the base, how to override styles, add components, what data is available, or preview a page, is not documented or easy.

As Keycloak releases new versions, the themes are not guaranteed to be compatible. This means that you will have to review and possibly update your custom theme with each Keycloak release, which can be a significant effort.

Lastly, adjusting the Account UI or the Emails, is documented to the extent of changing message templates. As something almost every Keycloak user needs, this leaves a major hole in the theming experience.

Where Keycloakify Fits In​

Keycloakify is a theming solution that allows you a couple methods, CSS or custom components, of configuration to customize the three main areas of Keycloak:

1. Login Pages
2. Account UI
3. Emails

It is backwards compatible so that as new Keycloak versions are released, you can continue to use your custom theme without having to worry about breaking changes. It also provides a built-in Storybook preview for all page variations, making it easy to see how your customizations will look in different scenarios.

Of the two methods that Keycloakify provides, we see that almost in all cases, the custom components method ends up being used. Dealing with PatternFly's CSS is difficult and error prone. That being said, Keycloakify requires some initial configuration to do custom component development: adding libraries, ejecting pages, etc. For this reason, we are taking a baseline starter and sharing it with the community in the hopes that it will help save people time in getting started with Keycloakify.

Also, we know that eventually there will be development to remove the need for this starter, but until then, we hope this will help you get started with Keycloakify and building custom themes for Keycloak.

Summary​

We look forward to seeing how the community uses this starter to build custom themes for Keycloak. If you have any questions or feedback, please feel free to file an issue on the GitHub repository or reach out.

Phase Two is thrilled to announce that we have been recognized as an official partner of CockroachDB. This partnership marks a significant milestone in our commitment to providing robust, scalable, and high-performance database solutions for our the Keycloak community and our customers.

Phase Two originally built our CockroachDB integration for Keycloak over two years ago, and since then we have been working closely with the CockroachDB team to ensure that our integration is optimized for performance and reliability. Our customers have seen significant improvements in database performance, scalability, and a overall cost savings by using CockroachDB with Keycloak.

Our commitment to CockroachDB is built on years of using the Cockroach Cloud to power all of our dedicated hosting.

What is CockroachDB?​

CockroachDB is a cloud-native, distributed SQL database designed for high availability, scalability, and resilience. It provides a single, unified database platform that can handle large volumes of data across multiple geographic locations while ensuring strong consistency and fault tolerance. CockroachDB is built on a distributed architecture that allows it to scale horizontally, making it an ideal choice for applications that require high performance and reliability. Payments systems, IAM, logistics, user accounts, and more — are powered by CockroachDB. Mission-critical applications rely on CockroachDB to deliver consistent performance and availability, scaling to meet demand and transaction heavy workloads.

Why Keycloak and CockroachDB?​

Keycloak is a powerful open-source identity and access management solution that provides authentication and authorization services for applications and services. It is designed to be flexible, extensible, and easy to use, making it a popular choice for organizations looking to implement secure user management.

When combined with CockroachDB, Keycloak benefits from the following:

• Scalability: CockroachDB's distributed architecture allows Keycloak to scale horizontally, handling large volumes of user data and authentication requests without compromising performance.
• Heavy Transaction Support: CockroachDB is designed to handle high transaction volumes, making it suitable for Keycloak deployments support millions of users and high-frequency authentication requests.
• High Availability: CockroachDB's fault-tolerant design ensures that Keycloak remains available even in the event of hardware failures or network issues, providing a reliable user experience.
• Strong Consistency: CockroachDB's distributed SQL capabilities ensure that Keycloak can maintain strong consistency across multiple nodes, preventing data inconsistencies and ensuring accurate user management.
• Cost Efficiency: CockroachDB's ability to scale horizontally means that organizations can optimize their infrastructure costs while still meeting the demands of their Keycloak deployments.

Real-World Latency Performance​

One of the key performance indicators we monitor in our production environments is query latency — a critical factor for identity systems like Keycloak, where responsiveness directly impacts user experience.

Over the past month (July 2025), our Keycloak deployments running on CockroachDB have consistently demonstrated impressive latency metrics:

• P99 Latency (99th percentile) consistently remained below 10ms, even during traffic spikes.
• P90 Latency (90th percentile) hovered well under 5ms across the board.
• Spikes: Occasional spikes up to 70ms (but usually below 35ms) for P99 and 15ms for P90 were observed lasting 5-60 mins with quick recovery afterward.

These low-latency metrics are a testament to the combined performance of CockroachDB’s distributed SQL engine and our infrastructure tuning, ensuring fast and reliable authentication and authorization at scale.

Phase Two's Commitment to CockroachDB​

As the original builders and continued maintainers of the Keycloak CockroachDB integration, Phase Two is committed to supporting the integration and ensuring that it meets the evolving needs of our customers. Our partnership with CockroachDB is a cementing of that commitment, and we are excited to work together to deliver the best possible experience for our users.

What This Means for Our Customers​

For customers already leveraging CockroachDB in their applications, this partnership ensures even deeper integration and support for running Keycloak on the same trusted, resilient database platform. You can expect streamlined operations, improved compatibility, and direct access to expertise from both the Phase Two and CockroachDB teams.

For those new to CockroachDB or considering it for the first time, our partnership means you can confidently adopt a modern, distributed database solution for your Keycloak deployments. Phase Two will guide you through best practices, migration strategies, and ongoing support to help you realize the benefits of CockroachDB’s scalability, reliability, and performance.

Customer Success Story - Grocery Store Chain​

A customer of Phase Two, a major US grocery store chain, had zero experience with CockroachDB before partnering with us. They were running on legacy Oracle systems and were looking for a modern, scalable, cloud solution. Leveraging our CRDB integration, we were able to migrate their Ping implementation to Keycloak with CockroachDB, resulting in a major cost reduction and improved performance. Their system is now running smoothly with millions of users and transactions. Those Friday coupon releases are now a breeze!

Customer Success Story - Global Leader in Rail Technology​

A global leader in rail technology partnered with Phase Two to modernize their identity infrastructure. With operations spanning continents and complex security requirements, they needed a scalable and resilient solution. Using our enhanced Keycloak distribution with native CockroachDB support, they migrated from their legacy system to a platform built for high availability and global scale. Today, their identity layer supports users across critical transportation systems—delivering performance, reliability, and peace of mind, even at full throttle.

Customer Success Story - Global Automobile and Tire Supplier​

What started as a open-source user of our CRDB integration, a global automobile and tire supplier, has now become a key customer of Phase Two. They started with using our CRDB integration for their Keycloak deployments and have since involved Phase Two in their enterprise Keycloak deployments. Working together, Phase Two has helped to optimize and scale their Keycloak + CockroachDB deployments. We have been able to streamline their deployment processes, integrate or upgrade custom SPI's (or migrate to more effective ones), and integrate use of the Phase Two Organization's extension to better manage their Keycloak users within their system. As a result of the CRDB partnership, we were able to optimize specific Keycloak queries and the CRDB dialect to improve performance within both systems, which would not have been possible without the close collaboration with CockroachDB.

Ready to Power Your Keycloak Deployment with CockroachDB?​

Contact us to learn how Phase Two can help you implement a scalable, resilient, and high-performing identity infrastructure with CockroachDB and Keycloak.

Or test it out for yourself at dash.phasetwo.io where you can deploy Keycloak with CockroachDB in minutes.

Frequently Asked Questions (FAQ)​

What is the advantage of using CockroachDB with Keycloak?​

Using CockroachDB with Keycloak improves horizontal scalability, high availability, and ensures strong consistency for identity data across distributed systems.

Can I migrate an existing Keycloak deployment to CockroachDB?​

Yes. Phase Two provides migration tools and support for transitioning your Keycloak deployment to CockroachDB.

Is CockroachDB a drop-in replacement for PostgreSQL in Keycloak?​

Yes. CockroachDB with Phase Two's integration, it can serve as a drop-in replacement in most Keycloak deployments default PostgreSQL implementation.

Does Phase Two offer support for running Keycloak on CockroachDB?​

Yes. As official CockroachDB partners, Phase Two offers enterprise-grade support, consulting, and managed services for Keycloak + CockroachDB.