p2-inc/keycloak-skills / benchmarks/keycloak-idp-org-restrict-login/environment/skills/identityProviderOrgRestrictLoginMcp
identityProviderOrgRestrictLoginMcp
VerifiedRestrict FEDERATED (external identity provider) login to members of one organization on a Phase Two hosted Keycloak - the user authenticates at their own company's IdP and only gets in when they belong to the organization the application named in account_hint - driven through the Keycloak MCP server. Use this whenever someone asks for "corporate organization restriction", "restrict SSO login to a team/tenant", "only let this customer's staff into their own org", "organization-restricted corporate login", "gate IdP login by org membership", or a "post-broker organization check". Covers the organization-owned IdP link that makes the gate work at all, authoring and binding a post-broker login flow containing ext-select-org (the stock post-broker flow has none, so binding it gates nothing), the match_by_org_name name-vs-ID choice, and verifying by driving real brokered logins. Requires the p2-inc keycloak-orgs extension. Not domain-based routing to an IdP (that restricts nobody) and not the local-password organization gate.
Restrict federated (IdP) login to members of one organization — via the Keycloak MCP server
Step 0 — Is the MCP surface actually here?
Do this before any tool call. Check your tool list once, now, for:
createOidcIdp · createOrganization · listOrganizations · setExecutionAuthenticatorConfig · 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 skillidentityProviderOrgRestrictLoginRestis 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 this is, and what it isn't
The user authenticates at an external identity provider, and only gets into your realm if
they belong to the organization the application asked for. Two things make this different from
admin:org-restrict-login, which gates a local password login:
- The gate runs after the IdP round-trip, so it lives on a third binding surface: the
identity provider's own
postBrokerLoginFlowAlias— not the realm'sbrowserFlow, not a client override. - Membership is normally established by the login itself:
ext-auth-org-add-useradds the arriving user to the organization that owns the IdP. The gate then discriminates between that organization and any other.
The trap that makes this silently do nothing: Keycloak ships a stock post-broker flow, and
it does not contain ext-select-org. Bind that one and account_hint is never evaluated —
every brokered login succeeds and the configuration looks complete. A custom flow containing
ext-select-org has to be authored and bound.
The second trap: every authenticator here keys off the IdP being organization-owned.
ext-auth-org-note and ext-auth-org-add-user both no-op on an IdP that isn't linked to an
organization, so the flow can be bound correctly and still gate nothing.
Check the organizations extension is actually installed, first
Everything here — organizations, membership, and all four ext-* authenticators — comes from
the p2-inc keycloak-orgs extension. None of it
is stock Keycloak, and there is no built-in equivalent to fall back to.
It is not Keycloak's own native, in-core Organizations feature. Phase Two deliberately does
not enable that one (see the extension's
note on this),
and the two have different REST surfaces — /realms/{realm}/orgs versus
/admin/realms/{realm}/organizations. ext-select-org reads the extension's, not the native
one; don't substitute.
On a genuine Phase Two deployment it's always present. If listOrganizations errors out rather
than returning an empty list, it isn't installed — say so and stop.
Tools this skill drives (Keycloak MCP server)
| Purpose | Tool |
|---|---|
| Identify caller / realm | whoAmI |
| Create the organizations | createOrganization |
| Broker the customer's IdP | createOidcIdp / createSamlIdp |
| Link the IdP to the owning organization | linkIdentityProviderToOrganization |
| Author the post-broker flow and bind it, in one call | importAuthenticationFlow (needs the atomic-flows extension — see below) |
Inspect/adjust the ext-select-org matching mode | listFlowExecutions / setExecutionAuthenticatorConfig |
| Bind the flow to the IdP separately | bindIdpBrokerLoginFlow(flowType="post_broker_login") |
| Confirm what's bound | listIdentityProviders |
Stage 1 — Ask: match the organization by NAME or by ID?
Ask explicitly. account_hint can carry either, and ext-select-org's match_by_org_name
config decides which is read. Whatever the application actually sends is the answer:
| The application sends… | match_by_org_name |
|---|---|
The organization's name (engineering) | "true" |
| The organization's ID (UUID) | "false" |
The bundled asset assets/post-org-broker-login-select-organization.partial-import.json
ships match_by_org_name: "true". If the application sends IDs, flip that value before or after
import — an application that never learns a server-generated UUID can only ever send a name.
Stage 2 — Organizations, IdP, and the link that makes it all work
- Create the organization that will own the IdP, plus any others the application may name.
- Broker the customer's provider (
createOidcIdp/createSamlIdp) with the endpoints, client ID and secret their IT team supplied.trustEmail: trueis usually right — the customer already verified those addresses. linkIdentityProviderToOrganization— this is the step that makes the IdP organization-owned, and without it the whole gate is inert (see the second trap above). Confirm the link rather than assuming it from a successful IdP creation.
Stage 3 — Author the post-broker flow, and bind it to the IdP
The flow's executions, in order — this is the shape the bundled asset produces:
| Authenticator | Requirement | Does what |
|---|---|---|
ext-auth-org-note | REQUIRED | Sets org_id session notes when an org-owned IdP was used |
ext-auth-org-id-verifier | DISABLED | Off in this shape |
ext-auth-validate-idp | REQUIRED | Validates newly created organization IdPs |
ext-auth-org-add-user | REQUIRED | Adds the arriving user to the IdP's organization |
ext-select-org (config match-by-org-name) | REQUIRED | The gate — matches account_hint against the user's real memberships |
Authoring paths, and one that does not work:
| Path | Cost | Requires |
|---|---|---|
importAuthenticationFlow — authors the flow and binds it to the IdP in one call | One call | The p2-inc keycloak-atomic-auth-flows extension |
Manual sequence, then bindIdpBrokerLoginFlow(flowType="post_broker_login") | Many calls | Nothing beyond stock Admin REST |
partialImport | — | Does not work. No handler for authentication flows: HTTP 200, nothing created, no error. |
Offer the extension when it isn't installed (it 404s clearly) — one jar collapses authoring plus binding into a single call.
Three payload details that each cost a 400 if wrong, verified against the extension's source:
- Strip
ifResourceExists. It's apartialImportfield;AuthenticationFlowPayloadrejects unknown fields outright. Use the?force=query parameter instead. - The IdP binding field is
postLoginFlowBinding, a flow-alias string — notpostBrokerLoginFlowAlias, and not a boolean. Shape:idpFlowBindings: [{alias: "<idp-alias>", postLoginFlowBinding: "<flow alias>"}]. - Pass the flow's original alias. The extension hash-prefixes both the flow it creates and
the binding value (e.g.
zBnfUvUxO3ifLw-post org broker login select organization), so they line up automatically. The IdP alias is passed through unprefixed. Read the resulting alias back off the IdP rather than assuming the name you supplied.
Stage 4 — Verify by logging in, not by reading configuration
Nothing here reports whether the gate is live, and the most obvious check — "a valid user with valid credentials gets in" — passes even when membership is never inspected. Drive three real brokered logins:
account_hint | Expect |
|---|---|
| the organization owning the IdP | login completes with an authorization code |
| a different real organization the user isn't in | rejected, no code |
| an organization that doesn't exist | rejected, no code |
The middle row is the one that actually proves membership is being checked. A flow that merely
requires some account_hint passes the first and third and fails the second.
If scripting rather than clicking: Keycloak marks AUTH_SESSION_ID / KC_RESTART as
Secure; SameSite=None. A browser sends them over http://localhost anyway (loopback is a
secure context); most HTTP clients will not, so an auto-following redirect chain silently loses
the session and dead-ends at the broker endpoint. Follow redirects manually and clear the flag
after every response.
Common errors
- Every brokered login succeeds regardless of
account_hint— the bound post-broker flow has noext-select-orgexecution (most likely Keycloak's stock one). Check the executions of the flow actually named by the IdP'spostBrokerLoginFlowAlias. - The gate never triggers and no membership is created — the IdP isn't linked to an
organization, so
ext-auth-org-add-user/ext-auth-org-noteno-op. account_hintnames an organization but never matches —match_by_org_namedisagrees with what the application sends (name vs. ID).- 400
Unrecognized field "ifResourceExists"— that field belongs topartialImport; strip it. - 400
Unrecognized field "postBrokerLoginFlowAlias"— the atomic payload's field ispostLoginFlowBinding. - Redirect chain dead-ends at
/broker/{alias}/login—Securecookies not being sent over http by the client.
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: 471k | 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: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |