p2-inc/keycloak-skills / benchmarks/keycloak-org-restrict-login/environment/skills/orgRestrictLoginMcp
orgRestrictLoginMcp
VerifiedRestrict login so only members of a specific organization can complete it, on a Phase Two hosted Keycloak, driven through the Keycloak MCP server. Use this whenever someone wants to "only let members of this org log in", "gate login by organization membership", or "restrict access to org X". Covers the p2-inc keycloak-orgs `ext-select-org` authenticator and its `match_by_org_name` setting (matching an organization by NAME vs by ID), authoring AND binding the flow in one call with `importAuthenticationFlow` (which needs the p2-inc keycloak-atomic-auth-flows extension — Keycloak's own partialImport endpoint silently ignores authentication flows entirely), and the fact that the gate only activates when the login request carries `account_hint` or `prompt=select_account`. Not domain-based auto-routing to a corporate IdP (a different mechanism entirely).
Restrict 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:
bindClientAuthenticationFlow · bindRealmAuthenticationFlow · 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 skillorgRestrictLoginRestis 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
This is a membership gate, not domain-based routing: only someone who is already a member of
a specific organization can complete login. It is the deliberate counterpart to
admin:corporate-sso's caveat — that intent auto-routes a user to their company's IdP by email
domain but never restricts who can log in; this one restricts, using Org Browser Flow (the
realm's built-in org-aware flow) or one of its custom variants, plus the ext-select-org
authenticator.
The trap bindRealmAuthenticationFlow itself warns about: binding Org Browser Flow
realm-wide does not, by itself, force every plain username/password login to require
organization membership. The org-selection/membership check inside the flow only runs when the
authorization request carries prompt=select_account or account_hint=<value> — a
client has to actually send one of those. A login with neither parameter skips the org-selection
step entirely and behaves like an ordinary login. If the goal is "every login to this client must
be gated by org membership," confirm the client is actually configured to send account_hint or
prompt=select_account — binding the flow is necessary but not sufficient.
Check the organizations extension is actually installed, first
Everything here depends on the
p2-inc keycloak-orgs extension — organizations
themselves, membership, and the ext-select-org authenticator that performs the gate. None of it
is part of stock Keycloak, and none of it can be reproduced without the extension: there is no
built-in equivalent to fall back to.
It is not the same thing as 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 for the extension versus
/admin/realms/{realm}/organizations for native. Don't substitute one for the other.
On a genuine Phase Two hosted deployment the extension is always present. If you're unsure, a
listOrganizations call erroring out (rather than returning an empty list) means it isn't
installed — say so plainly and stop, rather than working around it with the native API, which
ext-select-org does not read.
Tools this skill drives (Keycloak MCP server)
| Purpose | Tool |
|---|---|
| Identify caller / realm | whoAmI |
| Confirm which org-aware flow(s) already exist | listAuthenticationFlows |
| Author the flow and bind it, in one call | importAuthenticationFlow (needs the atomic-flows extension — see below) |
Inspect/adjust the ext-select-org step's matching mode | listFlowExecutions / setExecutionAuthenticatorConfig |
| Bind an already-existing flow | bindRealmAuthenticationFlow / bindClientAuthenticationFlow |
| Confirm bindings | getAuthenticationBindings |
Authoring a flow: two paths, and one that does NOT work
Keycloak's own partialImport endpoint cannot author authentication flows. It has no
handler for them at all (only clients, roles, identity providers, IdP mappers, groups and
users), so an authenticationFlows array sent to it is silently ignored — HTTP 200, added: 0, no error of any kind. Do not use it, and do not believe a 200 from it means a flow was
created. (This is why the bundled assets are named *.partial-import.json — that naming
predates this discovery and is now misleading; the files themselves are still correct.)
The two paths that do work:
| Path | Cost | Requires |
|---|---|---|
importAuthenticationFlow — authors the whole flow and applies bindings in one call | One call | The p2-inc keycloak-atomic-auth-flows extension installed on the target Keycloak |
| Manual REST sequence — create flow → create each sub-flow → add each execution → set each requirement → attach authenticator config → bind | Many calls, easy to get wrong | Nothing beyond stock Admin REST |
Offer the extension when it isn't installed. importAuthenticationFlow returns a clear 404
if the extension is missing. That is worth surfacing to the user as a real choice — installing
one jar collapses a long, error-prone sequence into a single call — rather than silently falling
into the manual path. If they decline (or can't install it), the manual sequence is legitimate;
just say upfront that it's substantially more calls.
The atomic import hash-prefixes every alias. The flow it creates is not named what the
asset says — it gets a generated prefix like 8esLlLB3D3YqVg-Org Browser Flow by Org Name. Read
the real alias back from the tool's response or getAuthenticationBindings; never assume it. That
prefix is also how it stays idempotent: re-importing identical content returns 409 and creates
nothing, unless force=true (which replaces in place rather than duplicating).
Stage 1 — Ask: match the organization by NAME or by ID?
Ask this explicitly — don't guess. account_hint can carry either an organization's name or
its id, and the flow has to be configured for exactly one interpretation via the
ext-select-org authenticator's match_by_org_name config key:
| The application will send… | Set match_by_org_name to | Asset |
|---|---|---|
The organization's name (human-readable, e.g. contoso) | "true" | assets/org-browser-flow-by-org-name.partial-import.json |
| The organization's ID (UUID) | "false" | assets/org-browser-flow-by-org-id.partial-import.json |
Both assets author a flow under the identical alias Org Browser Flow by Org Name — they are
two alternative configurations of the same flow, not two flows that can coexist. Import
whichever one matches the answer to this question. Importing the other afterward will not quietly
switch modes: via importAuthenticationFlow the differing config produces a different hash and
therefore a separate flow (leaving the first one bound), so decide the mode up front rather
than importing both and hoping.
Stage 2 — Confirm what's already there (usually: importing nothing is enough)
Start here, and expect not to need an import at all. A Phase Two Keycloak ships a built-in
Org Browser Flow that already contains the ext-select-org execution. In that case the
whole job is: set that execution's match_by_org_name to match Stage 1's answer
(setExecutionAuthenticatorConfig), then bind the flow (Stage 4). No import, no custom flow.
Call listAuthenticationFlows, then listFlowExecutions on any Org Browser Flow /
Org Browser Flow by Org Name you find, and check the ext-select-org execution's actual
match_by_org_name value — don't assume an existing flow is configured the way you want just
because its name looks right. Only fall through to Stage 3 if no flow with an ext-select-org
execution exists at all.
Stage 3 — Author the flow (and bind it), only if Stage 2 found nothing usable
If no flow with an ext-select-org execution exists, call importAuthenticationFlow with the authenticationFlows
and authenticatorConfig arrays from whichever asset matches Stage 1's answer, plus the binding
in the same payload — that's the whole point of the atomic import, and it means Stage 4's
separate bind call is unnecessary on this path:
{
"authenticationFlows": [ ...from the asset... ],
"authenticatorConfig": [ ...from the asset... ],
"browserFlowBinding": "Org Browser Flow by Org Name"
}
(The asset's own ifResourceExists field is not part of this payload and is ignored — it was for
the partialImport endpoint that doesn't work for flows.) For a single client instead of
realm-wide, use clientFlowBinding: {clientId, browserFlowBinding, directFlowBinding}; for
per-IdP first/post-broker flows, idpFlowBindings: [{alias, firstLoginFlowBinding, postLoginFlowBinding}].
If the extension isn't installed (404), offer it — see the two-paths section above — and fall back to the manual REST sequence only if the user declines.
To flip an already-imported flow's matching mode without re-importing, use
setExecutionAuthenticatorConfig on the ext-select-org execution instead (find it with
listFlowExecutions first) — set match_by_org_name to "true" or "false" directly. This is
usually better than importing the other asset, which creates a second, separate flow.
Stage 4 — Bind it (only if Stage 3 didn't already)
Skip this entirely if you bound in the import payload — that's the normal path. This stage is
for binding a flow that already existed (built-in Org Browser Flow, or one imported earlier), or
for re-binding after a change.
Same two surfaces as every other flow-binding intent in this router:
| Surface | When to use it | Tool |
|---|---|---|
| Realm-wide | Every client in the realm should require org membership (when account_hint/prompt=select_account is sent) | bindRealmAuthenticationFlow(bindingType="browser", flowAlias=...) |
| Single client | Only one application should require it | bindClientAuthenticationFlow |
Use the flow's real alias here — if it came from importAuthenticationFlow that's the
hash-prefixed one, not the name in the asset.
Then confirm the client(s) that need this gate are actually configured to send account_hint or
prompt=select_account on their authorization requests — see the trap at the top of this doc.
Verify with getAuthenticationBindings.
Verify by logging in, not by reading configuration
Nothing here reports whether the gate is actually active — behavior only shows up in a real login:
- A request without
account_hint/prompt=select_account: should behave like an ordinary login, unaffected by this flow. - A request with
account_hintset to a value matching Stage 1's chosen mode (a name or an ID), for a user who is a member of that organization: should complete login normally. - A request with
account_hintset to an org the user is not a member of: should be rejected — confirm it actually is, rather than assuming the flow enforces this correctly.
Common errors
- Bound the flow, but plain logins are unaffected either way — expected if the client never
sends
account_hint/prompt=select_account; this is not a bug, see the trap at the top. - Importing the "by ID" asset after "by name" (or vice versa) has no effect — same flow alias,
ifResourceExists: SKIPno-ops on an existing alias. UsesetExecutionAuthenticatorConfigto flip the mode, or re-import withOVERWRITE. account_hintset to a name butmatch_by_org_nameis"false"(or vice versa) — the mismatch between what the client sends and how the authenticator interprets it is silent; check both explicitly withlistFlowExecutionsrather than assuming they agree.- A required MCP tool is missing — report it and stop; do not switch to REST unsolicited.
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 |