Skip to content

p2-inc/keycloak-skills / benchmarks/keycloak-idp-org-restrict-login/environment/skills/identityProviderOrgRestrictLoginRest

identityProviderOrgRestrictLoginRest

Verified

Restrict FEDERATED (external identity provider) login to members of one organization on a self-managed 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 - using the Admin REST API only (no MCP server involved). 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 raw Admin REST

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's browserFlow, not a client override.
  • Membership is normally established by the login itself: ext-auth-org-add-user adds 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.

The second trap: ext-auth-org-note and ext-auth-org-add-user both no-op unless the IdP is 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. It is not stock Keycloak, and it is not Keycloak's native in-core Organizations feature: different REST surface (/realms/{realm}/orgs, no /admin prefix), and ext-select-org reads the extension's, not the native one.

BASE=http://localhost:8080/auth       # include the relative path if one is configured
H="Authorization: Bearer $ADMIN_TOKEN"
REALM=<realm>
IDP=<idp-alias>

# If this 404s, the extension isn't installed - stop; there is no fallback.
curl -s "$BASE/realms/$REALM/orgs" -H "$H"

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 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 "true". An application that never learns a server-generated UUID can only send a name.

Stage 2 — Organizations, IdP, and the link that makes it all work

# 1. The organization that will OWN the IdP (plus any others the app may name).
#    Note: NO `enabled` field - the extension's Organization representation rejects
#    unknown fields outright with a 400.
curl -s -X POST "$BASE/realms/$REALM/orgs" -H "$H" \
  -H 'Content-Type: application/json' -d '{"name":"engineering"}'
curl -s -X POST "$BASE/realms/$REALM/orgs" -H "$H" \
  -H 'Content-Type: application/json' -d '{"name":"finance"}'

ORG_ID=$(curl -s "$BASE/realms/$REALM/orgs" -H "$H" \
  | jq -r '.[] | select(.name=="engineering") | .id')

# 2. Broker the customer's provider, using the details their IT team supplied.
curl -s -X POST "$BASE/admin/realms/$REALM/identity-provider/instances" -H "$H" \
  -H 'Content-Type: application/json' -d '{
    "alias": "'"$IDP"'", "displayName": "Partner SSO", "providerId": "oidc",
    "enabled": true, "trustEmail": true, "storeToken": false, "linkOnly": false,
    "config": {
      "clientId": "<client-id>", "clientSecret": "<client-secret>",
      "clientAuthMethod": "<client-auth-method>",
      "authorizationUrl": "<authorization-endpoint>", "tokenUrl": "<token-endpoint>",
      "userInfoUrl": "<userinfo-endpoint>", "jwksUrl": "<jwks-uri>", "issuer": "<issuer>",
      "defaultScope": "openid profile email", "syncMode": "IMPORT", "useJwksUrl": "true"
    }}'

# 3. THE STEP THAT MAKES IT ORGANIZATION-OWNED. Without it the post-broker
#    authenticators have nothing to act on and the gate is inert.
curl -s -X POST "$BASE/realms/$REALM/orgs/$ORG_ID/idps/link" -H "$H" \
  -H 'Content-Type: application/json' -d '{"alias":"'"$IDP"'"}'

# Verify the link rather than assuming it from a 2xx on the create call.
curl -s "$BASE/realms/$REALM/orgs/$ORG_ID/idps" -H "$H" | jq -r '.[].alias'

Stage 3 — Author the post-broker flow, and bind it to the IdP

The flow's executions, in order — the shape the bundled asset produces:

AuthenticatorRequirementDoes what
ext-auth-org-noteREQUIREDSets org_id session notes when an org-owned IdP was used
ext-auth-org-id-verifierDISABLEDOff in this shape
ext-auth-validate-idpREQUIREDValidates newly created organization IdPs
ext-auth-org-add-userREQUIREDAdds the arriving user to the IdP's organization
ext-select-org (config match-by-org-name)REQUIREDThe gate
PathCostRequires
POST /admin/realms/{realm}/authentication-flow/import?force={bool} — authors the flow and binds it to the IdP in one callOne callThe p2-inc keycloak-atomic-auth-flows extension
Manual sequence, then set postBrokerLoginFlowAlias on the IdPMany callsNothing beyond stock Admin REST
POST /admin/realms/{realm}/partialImport—Does not work. No handler for authentication flows: HTTP 200, added: 0, no error.

Atomic path — offer the extension when it isn't installed (it 404s clearly):

# Take the asset, STRIP ifResourceExists (a partialImport field - AuthenticationFlowPayload
# rejects unknown fields with a 400; use ?force= instead), and add the IdP binding.
jq --arg idp "$IDP" '
    del(.ifResourceExists)
    | .idpFlowBindings = [{alias: $idp, postLoginFlowBinding: .authenticationFlows[0].alias}]
  ' post-org-broker-login-select-organization.partial-import.json > /tmp/flow.json

curl -s -X POST "$BASE/admin/realms/$REALM/authentication-flow/import?force=false" \
  -H "$H" -H 'Content-Type: application/json' --data-binary @/tmp/flow.json

# The extension hash-prefixes BOTH the flow it creates and the binding value, so they line
# up automatically - pass the ORIGINAL alias, then read the real one back off the IdP.
curl -s "$BASE/admin/realms/$REALM/identity-provider/instances/$IDP" -H "$H" \
  | jq -r '.postBrokerLoginFlowAlias'

Payload details, each a 400 if wrong (verified against the extension's source):

  • The IdP binding field is postLoginFlowBinding — a flow-alias string, not postBrokerLoginFlowAlias, and not a boolean.
  • The IdP alias inside idpFlowBindings is passed through unprefixed; only the flow binding value gets the hash prefix.

Manual path — create the flow, add each execution above in order with its requirement, attach the match-by-org-name config to the ext-select-org execution, then bind by setting postBrokerLoginFlowAlias on the IdP representation and PUTting it back:

curl -s "$BASE/admin/realms/$REALM/identity-provider/instances/$IDP" -H "$H" > /tmp/idp.json
# set "postBrokerLoginFlowAlias": "<your flow alias>" in /tmp/idp.json
curl -s -X PUT "$BASE/admin/realms/$REALM/identity-provider/instances/$IDP" -H "$H" \
  -H 'Content-Type: application/json' --data-binary @/tmp/idp.json

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

Nothing here reports whether the gate is live, and the obvious check — "a valid user with valid credentials gets in" — passes even when membership is never inspected. Drive three real logins, forcing the provider with kc_idp_hint so this tests the post-broker gate specifically:

$BASE/realms/$REALM/protocol/openid-connect/auth
  ?client_id=<client>&response_type=code&scope=openid
  &redirect_uri=<redirect>&state=<state>
  &kc_idp_hint=$IDP&account_hint=<org>
account_hintExpect
the organization owning the IdPlogin completes with an authorization code
a different real organization the user isn't inrejected, no code
an organization that doesn't existrejected, no code

The middle row is what actually proves membership is checked — a flow that merely requires some account_hint passes the first and third and fails the second.

If scripting: 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 /broker/{alias}/login. Follow redirects manually and clear the flag after every response (cookie.secure = False in Python requests).

Troubleshooting

SymptomCause
Every brokered login succeeds regardless of account_hintThe bound post-broker flow has no ext-select-org execution (most likely Keycloak's stock one)
Gate never triggers, no membership createdThe IdP isn't linked to an organization, so ext-auth-org-add-user/ext-auth-org-note no-op
account_hint names a real org but never matchesmatch_by_org_name disagrees with what the app sends (name vs. ID)
400 Unrecognized field "ifResourceExists"That field belongs to partialImport; strip it, use ?force=
400 Unrecognized field "postBrokerLoginFlowAlias"The atomic payload's field is postLoginFlowBinding
400 Unrecognized field "enabled" on org createThe extension's Organization representation has no such field
Redirect chain dead-ends at /broker/{alias}/loginSecure cookies not sent over http by the client
partialImport returned 200 but no flow existsThat endpoint ignores authentication flows entirely
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