Skip to content

p2-inc/keycloak-skills / benchmarks/keycloak-corporate-sso-login/environment/skills/corporateSsoLoginMcp

corporateSsoLoginMcp

Verified

Set 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 skill corporateSsoLoginRest is 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:

  1. Broker the customer's identity provider so their staff authenticate there, not here.
  2. Route to it automatically, by email domain — a user typing someone@customer.example must never see your password form or a menu of providers.
  3. 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)

PurposeTool
Identify caller / realmwhoAmI
Find or create the customer's organizationadmin:organizations intent
Create the corporate IdPcreateOidcIdp / createSamlIdp / settingOktaIdentityProvider
Link the IdP to the organizationlinkIdentityProviderToOrganization
See what flows existlistAuthenticationFlows
Bind the flowbindRealmAuthenticationFlow / bindClientAuthenticationFlow
Confirm bindingsgetAuthenticationBindings

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:

MissingSymptom
The organization does not hold the customer's email domainDiscovery has nothing to match
The domain is present but not verifiedDiscovery never matches that domain
The IdP is created but not linked to the organizationThe 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…FlowAsset
Just the corporate-IdP redirecthomeIdpassets/home-idp.partial-import.json
The redirect and to be treated as a member of that organizationhomeIdp with orgs-checkassets/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 pageExpect
an address at the customer's verified domainno password field; the browser is sent to the customer's IdP
an address at any other domaina 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_ID and KC_RESTART as Secure; SameSite=None. Browsers send them over http://localhost anyway — loopback is a secure context — but HTTP clients typically refuse, and every form POST then returns 400 "Cookie not found. Please make sure cookies are enabled in your browser." Clear the flag on each response (cookie.secure = False in Python requests).
  • 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 — IMPORT copies profile fields on first login only; FORCE refreshes 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 trustEmail and a provider sending email, given_name and family_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

SymptomCause
Matched domain still shows the password formforwardToLinkedIdp left at its false default, or the IdP is not linked to the organization
SSO button shown to everyone, nothing routesProvider created but not linked to an organization
Domain never matchesThe organization's domain is not marked verified
Everyone gets forwarded to the providerAn identity-provider-redirector execution in the bound flow
Matched domain gets neither password nor routehideOnLogin is true on the provider
A required MCP tool is missingReport it and stop; do not switch to REST unsolicited
400 "Cookie not found" while scriptingSecure cookies not sent over http by the client
invalid_redirect_uri at the customer's providerThey 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.

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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall