p2-inc/keycloak-skills / benchmarks/keycloak-corporate-sso-login/environment/skills/corporateSsoLoginMcp
corporateSsoLoginMcp
VerifiedSet up corporate SSO / enterprise SSO on a Phase Two hosted Keycloak — send a user to their own company's identity provider based on the domain of the email address they type, while everyone else keeps password login — using the Keycloak MCP server. Use this whenever someone says "I want corporate SSO login", "we need enterprise SSO", "SSO for our customer", "let our customer log in with their company account", "log in with my company's SSO automatically", "redirect to my corporate IdP", "authenticate to my corporate IdP", "home realm discovery", "IdP discovery by email domain", "onboard an enterprise customer's SSO", or "associate a corporate IdP with organization login" — even if they only say "corporate SSO". Covers the organization + verified-domain + linked-IdP mechanism that performs the discovery, the `homeIdp` / `homeIdp with orgs-check` flows and the `forwardToLinkedIdp=true` setting the redirect depends on, why an identity-provider-redirector execution is the wrong answer, and how to verify the routing by actually logging in. Not user federation (connectingUserStore), not plain identity brokering with a login-page button (connectingIdentityProvider), and not binding organization/passwordless flows generally (bindingAuthenticationFlow).
Corporate SSO by email domain
Step 0 — Is the MCP surface actually here?
Do this before any tool call. Check your tool list once, now, for:
bindClientAuthenticationFlow · bindRealmAuthenticationFlow · linkIdentityProviderToOrganization · listAuthenticationFlows · whoAmI
- All present → say "Using the Keycloak MCP tools", then follow this skill as written.
- Any missing → say "Keycloak MCP tools unavailable in this session (missing: …) — using the
Keycloak admin REST API instead", then keep reading. Every stage below still applies: the
behaviour it configures is a property of Keycloak, not of the transport. Only the calls change —
carry out each stage against the admin REST API (
$KC_URL/admin/realms/{realm}/...) with an admin token. If the sibling skillcorporateSsoLoginRestis loaded, use its exact REST recipes.
Decide once, here. Do not call an MCP tool to discover whether it exists, and do not alternate between the two paths afterwards — discovering the gap a step at a time is measurably more expensive than committing up front.
Say which path you took either way: a run that silently swaps tooling is indistinguishable from one that never had the tools.
What is actually being asked for
"I want corporate SSO login" decomposes into three requirements. Only the first is obvious, and the third rules out the tempting answer:
- Broker the customer's identity provider so their staff authenticate there, not here.
- Route to it automatically, by email domain — a user typing
someone@customer.examplemust never see your password form or a menu of providers. - Leave everyone else alone — your own staff, and every other customer, keep the login they already had.
Keycloak has an Identity Provider Redirector execution that sends users to a provider with
no prompt. It is not domain-based discovery: it forwards everyone (or only when the client
passes kc_idp_hint, which a plain browser login does not). It satisfies 1 and 2 and breaks 3.
Do not offer it as the answer to this request.
Tools this skill drives (Keycloak MCP server)
| Purpose | Tool |
|---|---|
| Identify caller / realm | whoAmI |
| Find or create the customer's organization | admin:organizations intent |
| Create the corporate IdP | createOidcIdp / createSamlIdp / settingOktaIdentityProvider |
| Link the IdP to the organization | linkIdentityProviderToOrganization |
| See what flows exist | listAuthenticationFlows |
| Bind the flow | bindRealmAuthenticationFlow / bindClientAuthenticationFlow |
| Confirm bindings | getAuthenticationBindings |
Capture deploymentId and deploymentRealm and reuse them on every call.
Drive this through the MCP tools. If a required tool is unavailable in this deployment, say so and stop. Do not silently substitute Admin REST calls — an unreported switch hides the fact that the tooling is incomplete, and leaves the user unable to reproduce what you did. Only fall back to REST if the user confirms this is not a Phase Two realm (see the appendix).
The hard prerequisite — establish this first
Discovery is organization-driven. The discoverer looks up an organization by the user's email domain and forwards to that organization's linked IdP. There is no standalone domain-to-IdP setting anywhere. So the first question is:
"Is the company modelled as an organization in this realm, with a verified email domain, and is the IdP linked to it?"
Three things must all be true, and each fails silently on its own:
| Missing | Symptom |
|---|---|
| The organization does not hold the customer's email domain | Discovery has nothing to match |
| The domain is present but not verified | Discovery never matches that domain |
| The IdP is created but not linked to the organization | The provider works, but the login page just shows an SSO button to everybody — no routing |
The third is the one that gets skipped: creating an IdP does not associate it with any
organization. linkIdentityProviderToOrganization takes the orgId, the idpAlias, and the
organization's email domains. Without that call, Home IdP Discovery will never find the IdP
for that domain, no matter how correct everything else is.
Confirm the link exists before moving on — do not assume it from a successful IdP creation.
Which flow to bind
| The user also wants… | Flow | Asset |
|---|---|---|
| Just the corporate-IdP redirect | homeIdp | assets/home-idp.partial-import.json |
| The redirect and to be treated as a member of that organization | homeIdp with orgs-check | assets/home-idp-with-orgs-check.partial-import.json |
Both are custom flows. Confirm with listAuthenticationFlows; if the one you need is missing,
apply the bundled asset via the admin console (Realm Settings → Action → Partial import) or
kcadm.sh create partialImport — there is no MCP tool that performs the import, so this is a
manual step you must hand to the user rather than perform.
Both assets deliberately set forwardToLinkedIdp=true. The authenticator's factory default
is false, which silently prevents any redirect at all — the single most likely cause of "I
configured everything and it still shows the password form".
Then bind exactly as in bindingAuthenticationFlow:
bindRealmAuthenticationFlow(bindingType="browser", flowAlias="homeIdp"), or
bindClientAuthenticationFlow for a single application. Binding alone does nothing if the
prerequisite above is not satisfied.
Verify by logging in, not by reading configuration
Every setting here can be correct-looking and inert, and no tool reports routing — routing is behaviour. Have the user (or a script) perform a real login twice:
| Submit on the login page | Expect |
|---|---|
| an address at the customer's verified domain | no password field; the browser is sent to the customer's IdP |
| an address at any other domain | a password field, and password login still completes |
The second row is not optional. It is what distinguishes correct domain discovery from a redirector that hijacks every login, and it is the check people skip.
If you are scripting this rather than clicking through it, two details will otherwise cost you an afternoon:
- Keycloak sets
AUTH_SESSION_IDandKC_RESTARTasSecure; SameSite=None. Browsers send them overhttp://localhostanyway — loopback is a secure context — but HTTP clients typically refuse, and every form POST then returns400"Cookie not found. Please make sure cookies are enabled in your browser." Clear the flag on each response (cookie.secure = Falsein Pythonrequests). - A user who has never federated and one who already has a federated identity are sent
onward differently (an offered link versus an immediate redirect with a
login_hint). Follow both, or a test passes on the first login and fails on the second.
scripts/browser_login.py drives the whole round trip and prints where each step went.
Afterwards, a correctly federated user has a non-empty federated identity and no password credential in your realm. That distinction matters: hand-creating local accounts with matching email addresses reproduces some of the behaviour while being the opposite of federation.
Provider settings that bite
trustEmail: true— without it a brokered user is asked to verify an email the customer already verified, stalling first login. Set it when you trust the provider.- The redirect URI the customer must whitelist is
{base}/realms/{realm}/broker/{alias}/endpoint. It contains the alias, so choose the alias before asking them to whitelist anything. hideOnLogin— tempting, to keep one customer's button off a shared login page. Measured: setting it true removes the route for the matched domain too, leaving those users with no password field and no way forward. Leave it visible unless you have verified the matched-domain path still works.syncMode—IMPORTcopies profile fields on first login only;FORCErefreshes them on every login, usually right when the customer's directory is authoritative.- First broker login — the default flow reviews the profile when fields are missing and can
prompt to link an existing local account with the same email. With
trustEmailand a provider sendingemail,given_nameandfamily_name, it passes through silently.
Not organization restriction
This is an automatic redirect, not a membership gate. A user whose email domain matches no
organization falls through to the password fallback. If the ask is "only members of this
organization may log in at all", that is a different mechanism with a significant caveat — see
bindingAuthenticationFlow, Stage 4.
Troubleshooting
| Symptom | Cause |
|---|---|
| Matched domain still shows the password form | forwardToLinkedIdp left at its false default, or the IdP is not linked to the organization |
| SSO button shown to everyone, nothing routes | Provider created but not linked to an organization |
| Domain never matches | The organization's domain is not marked verified |
| Everyone gets forwarded to the provider | An identity-provider-redirector execution in the bound flow |
| Matched domain gets neither password nor route | hideOnLogin is true on the provider |
| A required MCP tool is missing | Report it and stop; do not switch to REST unsolicited |
400 "Cookie not found" while scripting | Secure cookies not sent over http by the client |
invalid_redirect_uri at the customer's provider | They whitelisted a different alias than the one created |
Appendix — non-Phase Two realms
Stock Keycloak 26 has the same mechanism under a different name: the organization feature
flag, a realm organizationsEnabled switch, POST /admin/realms/{realm}/organizations with
domains:[{name,verified:true}], and
POST /admin/realms/{realm}/organizations/{orgId}/identity-providers (body is a bare JSON
string holding the alias). The built-in browser flow then routes without any custom flow.
Note the redirect there is not silent for a first-time user — they are shown the provider as a
link. Use this only when the user has confirmed there is no Phase Two deployment and no MCP
server; otherwise the tools above are the supported path.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |