Does Keycloak Work in China? Data Residency, ICP & Cross-Border Rules

For a team standing up Keycloak for a China operation, the first instinct is to treat this as a speed question — will the login screen and token endpoints answer quickly from Shanghai. That is not where it is decided. Keycloak is your identity provider: it holds the directory of everyone you authenticate (usernames, emails, phone numbers, group and role membership), the credentials that unlock your systems (password hashes and recovery data), the multi-factor factors enrolled against each account, and the session and token store plus the access logs of who signed in to what, when. It is the single gate standing in front of your entire China estate. Where that identity data lives, and under what consent and filing, is the question — not latency.

The encouraging part is that Keycloak is open-source, self-hostable software. Keycloak’s own Getting Started guide tells you to download and extract the distribution from the Keycloak website and run it on a physical or virtual server you control; the project presents itself under an “Open Source” heading and as a Cloud Native Computing Foundation incubation project. Because you choose where it runs, an in-country, data-resident deployment is achievable — there is no vendor-imposed “no China region,” and the compliance path is open. Four prongs then decide it: the residency and cross-border status of the identity personal information; the concentrated security-governance exposure of the IdP as your access control plane; any biometric or ID-document MFA factor, which is sensitive personal information; and an ICP filing for any China-facing login or registration surface. Keycloak states the self-hosted deployment model plainly on its own Getting Started page.

Keycloak in China at a glance

What it actually holds — the keys to your China estate

It is easy to file an identity provider under “just the login box” and stop there, but a live Keycloak install holds the most security-sensitive dataset you have, and the one gate in front of everything else. It holds the identity directory — the record of every employee or customer you authenticate, with usernames, emails, phone numbers, and group and role membership. It holds the credentials: password hashes and recovery data. It holds the MFA factors enrolled against each account. And it holds the session and token store and the access logs — who signed in, to what, and when. Wherever your Keycloak instance runs, all of that runs there too — and because Keycloak is self-hostable, where it runs is a choice you control.

The half a reachability check never sees — the IdP as control plane

This is where a speed test and a compliance review part ways. A reachability check can tell you the login answers from Shanghai; it cannot see that your identity graph, credentials, session store and access logs — the concentrated, security-sensitive map of who can touch your China systems — are sitting on an offshore host. That control plane is both a cross-border data matter and, for sensitive operations, something that may implicate “important data” (重要数据) handling and the Multi-Level Protection Scheme (MLPS / 等级保护) duties that attach to the system guarding your estate. We frame that as a risk to confirm with counsel rather than a fixed classification — but it is exactly the exposure a latency measurement is blind to, and it is why “it loads fine” is the wrong axis for an identity provider.

The doors: residency, sensitive factors, control-plane governance, and ICP

The first door is the personal information. The directory, credentials and session data Keycloak holds are personal information under China’s Personal Information Protection Law; hold them on an offshore host and that is a cross-border transfer (数据出境). The duty lands on you, the handler: Articles 13 and 23 require notice and a basis to collect, and Articles 38–40 require a transfer mechanism to send it abroad — a CAC security assessment, the CAC standard contract, or certification — with separate consent for the overseas transfer. For a critical information infrastructure operator or a high-volume handler, the Cybersecurity Law’s Article 39 (formerly Article 37 — the 2025 amendment, in force January 1, 2026, renumbered the data-localization article from 37 to 39 with its substance unchanged), together with PIPL Article 40, requires personal information generated in China to be stored in the mainland.

The second door is the MFA factors. If you enroll biometric factors (face or fingerprint) or ID-document verification, that is sensitive personal information under PIPL Articles 28–29, which require a specific purpose and necessity, a separately obtained consent, and a protection impact assessment — on top of the residency analysis.

The third door is the ICP filing. A public, China-facing login or registration surface is an internet information service, so it carries an ICP filing (备案) duty bound to a mainland hosting resource — and you cannot file a login page that is hosted offshore.

Here is where Keycloak’s deployment model earns its keep: because it is open-source and self-hostable, you have a path to keep the directory, credentials, sessions and MFA data inside the mainland by design, give any login surface a mainland resource to file against, and govern the control plane on top. The risk is the default (teams run the IdP on an offshore cloud region or VM out of habit), not a ceiling the vendor imposed. An in-country self-host is necessary, not sufficient: ICP, consent, the sensitive-PI rules, and the MLPS duties on the control plane still have to be met.

Loading isn’t the question — a data-resident, ICP-filed, governed IdP is

So the productive question is not whether Keycloak paints quickly from the mainland. It is where the directory, credentials and session data live, whether a China-facing login carries its ICP filing, whether any biometric MFA is treated as sensitive personal information, and how the authentication control plane is governed as the single gate in front of your estate. Get those right and “does it load” takes care of itself; get them wrong and a fast login is still a non-compliant one. The lawful pattern is to keep the identity data in-country — self-hosted inside the mainland — file the ICP on the mainland hosting resource, and deliver the login compliantly, never routing the data back out. None of this is a verdict that Keycloak is “blocked” or “illegal” in China; it is open-source, self-hostable software, and much of the exposure dissolves the moment you choose a data-resident deployment. It is a risk map — whether you owe a separate consent, a transfer mechanism, in-country storage, a sensitive-PI assessment, an ICP filing, or some combination turns on your entity, your data volumes, your role as handler and who your users are, so settle the specifics with counsel before your China access depends on them.

The lawful path — map, localize, deliver

There is a compliant way to run Keycloak for a China operation, and because the platform is self-hostable, its middle step is unusually clean — one that sits in front of the install you already run, with no rebuild and no re-platform.

First, map: our China team inventories what your Keycloak holds — the identity directory, the credentials and recovery data, the enrolled MFA factors, the session and token store, the access and audit logs, and any China-facing login or registration surface — establishes where it is hosted today (often an offshore cloud region or VM), the ICP status of any public login page, whether the control plane is MLPS-relevant, and the consent and residency basis each flow relies on. We build the technical picture; the legal conclusions are settled with counsel.

Then localize: this is where the self-hostable design pays off. We help you keep the directory, credentials, session data and MFA factors inside the mainland — self-hosted on a China-resident footing — put the Article 13/23 notice-and-consent in place, treat any biometric factor as sensitive personal information under Articles 28–29, handle any CIIO or high-volume storage duty, and govern the authentication control plane as the single access gate (Multi-Level Protection Scheme / 等级保护 relevant). Localize means keeping the identity data on an in-country path — never a route that ships it offshore anyway.

Then deliver: a public China-facing login or registration surface is an internet information service, so it carries an ICP filing duty bound to a mainland hosting resource and needs compliant, in-country delivery. 21YunBox delivers it in-country — the 21YunBox Optimizer — set in front of the Keycloak you already run, so it runs legally and compliantly for your users in China. Making an offshore IdP merely reachable from the mainland is not the answer — the directory, credentials and logs would still be offshore and the login still unfiled; keeping the identity data in-country, filing the ICP, and governing the control plane is. 21YunBox never uses or suggests circumvention of any kind — we keep in-country what the law says must stay, deliver the rest compliantly from inside the mainland, and never move personal information across the border by stealth. 21YunBox is a compliance overlay and partner to the identity provider you already run, not a competitor to it.

Get a compliance assessment →

Related reading:

• How to get an ICP filing for China
• Cross-border data transfers under PIPL
• China’s Personal Information Protection Law (PIPL)
• China’s Cybersecurity Law (data localization, Article 39)

RELATED TECHNOLOGIES

BeyondTrust

BeyondTrust

Delinea

Delinea

Cisco Duo

Cisco Duo

ForgeRock

ForgeRock

Saviynt

Saviynt