Skip to content

p2-inc/keycloak-skills / benchmarks/keycloak-org-restrict-login/environment/skills/orgRestrictLoginMcp

orgRestrictLoginMcp

Verified

Restrict 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 skill orgRestrictLoginRest 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 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)

PurposeTool
Identify caller / realmwhoAmI
Confirm which org-aware flow(s) already existlistAuthenticationFlows
Author the flow and bind it, in one callimportAuthenticationFlow (needs the atomic-flows extension — see below)
Inspect/adjust the ext-select-org step's matching modelistFlowExecutions / setExecutionAuthenticatorConfig
Bind an already-existing flowbindRealmAuthenticationFlow / bindClientAuthenticationFlow
Confirm bindingsgetAuthenticationBindings

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:

PathCostRequires
importAuthenticationFlow — authors the whole flow and applies bindings in one callOne callThe 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 → bindMany calls, easy to get wrongNothing 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 toAsset
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:

SurfaceWhen to use itTool
Realm-wideEvery client in the realm should require org membership (when account_hint/prompt=select_account is sent)bindRealmAuthenticationFlow(bindingType="browser", flowAlias=...)
Single clientOnly one application should require itbindClientAuthenticationFlow

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:

  1. A request without account_hint/prompt=select_account: should behave like an ordinary login, unaffected by this flow.
  2. A request with account_hint set 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.
  3. A request with account_hint set 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: SKIP no-ops on an existing alias. Use setExecutionAuthenticatorConfig to flip the mode, or re-import with OVERWRITE.
  • account_hint set to a name but match_by_org_name is "false" (or vice versa) — the mismatch between what the client sends and how the authenticator interprets it is silent; check both explicitly with listFlowExecutions rather than assuming they agree.
  • A required MCP tool is missing — report it and stop; do not switch to REST unsolicited.
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: 471kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall