Skip to content

p2-inc/keycloak-skills / benchmarks/keycloak-magic-link-org-restrict-login/environment/skills/magicLinkOrgRestrictLoginMcp

magicLinkOrgRestrictLoginMcp

Verified

Restrict passwordless magic-link login so only members of a specific organization ever receive the login link, on a Phase Two hosted Keycloak, using the Keycloak MCP server. Use this whenever someone wants "magic link login restricted to org X", "passwordless login gated by organization membership", "only email the login link to people on this team", or describes a user logging in via magic link where whether they get in depends on their organization membership (as signalled by account_hint). This is NOT plain magic-link with no restriction (a simpler, different flow), and NOT the org gate on a password login (a different flow with no magic-link step at all) — it is the combination of both, via a custom flow authored with importAuthenticationFlow that runs the membership check BEFORE the login email is sent. Covers the load-bearing execution order and the `account_hint`/`prompt=select_account` trigger requirement.

Magic-link login restricted to one organization's members — 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 · setExecutionAuthenticatorConfig · setSmtpSettings · 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 magicLinkOrgRestrictLoginRest 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

Magic-link login (open an emailed link, you're in, no password) combined with a membership gate: only someone who belongs to the organization named in the request's account_hint ever receives the link. Neither half is new by itself — plain magic-link has no organization check, and the password-login org gate (Org Browser Flow + ext-select-org) has no magic-link step — so combining them needs a custom flow.

What makes this different from just adding a step: the membership check has to run before any mail goes out. Reveal "an account exists here" only after confirming the requester belongs to the hinted organization — never before. The flow below does this by collecting just an identifier first (setting it in the auth-session context, no credential check yet), running the org check against that, and only then reaching the magic-link step itself.

Tools this skill drives (Keycloak MCP server)

PurposeTool
Identify caller / realmwhoAmI
Create the organizationcreateOrganization
Add a memberthe org membership tool for this deployment (confirm the exact name with a tool listing)
Confirm no flow already does thislistAuthenticationFlows
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
Configure outgoing mailsetSmtpSettings
Bind an already-existing flowbindRealmAuthenticationFlow / bindClientAuthenticationFlow
Confirm bindingsgetAuthenticationBindings

Prerequisite: the keycloak-orgs extension

The real p2-inc keycloak-orgs extension, not Keycloak's native Organizations feature. If listOrganizations errors rather than returning an empty list, it isn't installed — say so and stop.

Stage 1 — Ask: match by organization NAME or ID?

account_hint can carry either, and match_by_org_name decides which is read. Ask what the application actually sends — don't guess.

Stage 2 — The organization and its member(s)

Create the organization, then add each intended member. Confirm membership actually stuck rather than assuming a successful add call means it did.

Stage 3 — Author the flow (and bind it)

Confirm with listAuthenticationFlows that no flow already does this. Authoring is not covered by any tool other than importAuthenticationFlow — it returns a clear 404 if the keycloak-atomic-auth-flows extension isn't installed; offer it rather than switching to REST unsolicited.

{
  "authenticationFlows": [ /* from assets/select-organization-magic-link.partial-import.json */ ],
  "authenticatorConfig": [ /* same asset */ ],
  "browserFlowBinding": "Select organization magic link"
}

The ordering inside the asset's forms sub-flow is load-bearing, not cosmetic — verify it matches this table if authoring by hand instead of using the asset:

ExecutionRequirementConfigWhy this position
ext-auth-username-auth-noteREQUIREDsetUserInContext=trueCollects an identifier and sets it in context — before any membership or credential check. ext-select-org needs a user to check.
ext-select-orgREQUIREDmatch_by_org_name=<true|false>The gate. A non-member fails here; ext-magic-form is never reached — no mail goes out to them.
ext-magic-formREQUIREDext-magic-create-nonexistent-user=falseOnly reached once membership passed. false here for the same reason plain magic-link sets it — the factory default (true) would provision an account for anyone reaching this point.

Putting ext-magic-form before ext-select-org would send mail regardless of membership and defeat the entire point of gating — this is the one thing not to improvise around. Read the real, hash-prefixed alias back from importAuthenticationFlow's response rather than assuming the asset's name.

Stage 4 — Realm mail settings

setSmtpSettings — same silent-failure trap as plain magic-link. Verify by checking what actually left (a capture point in test contexts), not by trusting a success response.

Stage 5 — The account_hint trap, again

ext-select-org only runs when the request carries account_hint or prompt=select_account — confirm the application actually sends one of those two parameters on every login that should be gated.

Stage 6 — Verify by logging in, not by reading configuration

  1. A member with the correct account_hint: should receive mail with an action-token link; completing it returns an authorization code.
  2. A non-member with the same account_hint: should receive no mail at all — check outgoing mail directly, since the identifier-collection step's page response may look identical either way.
  3. An account_hint matching no real organization, for a genuine member of some other organization: also rejected — this is what proves membership is actually checked.

Common errors

  • Everyone gets mail regardless of membership — executions are out of order, or the bound flow is missing ext-select-org entirely.
  • Nobody gets mail, even members — setUserInContext missing/false, or realm SMTP unconfigured.
  • account_hint set to a name but match_by_org_name is "false" (or vice versa) — check both explicitly rather than assuming agreement.
  • 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