Skip to content

p2-inc/keycloak-skills / benchmarks/keycloak-corporate-sso-login/environment/skills/corporateSsoLoginRest

corporateSsoLoginRest

Verified

Set up corporate SSO / enterprise SSO on a self-managed Keycloak — send a user to their own company's identity provider based on the domain of the email address they type, while everyone else keeps password login — using the Admin REST API only (no MCP server involved). Use this whenever someone says "I want corporate SSO login", "we need enterprise SSO", "SSO for our customer", "let our customer log in with their company account", "log in with my company's SSO automatically", "redirect to my corporate IdP", "authenticate to my corporate IdP", "home realm discovery", "IdP discovery by email domain", "onboard an enterprise customer's SSO" — even if they only say "corporate SSO". Covers the organization + verified-domain + linked-IdP mechanism that performs the discovery, why an identity-provider-redirector execution is the wrong answer, and how to verify the routing by actually logging in.

Corporate SSO by email domain — via raw Admin REST

What is actually being asked for

"I want corporate SSO login" decomposes into three requirements. Only the first is obvious, and the third rules out the tempting answer:

  1. Broker the customer's identity provider so their staff authenticate there, not here.
  2. Route to it automatically, by email domain — a user typing someone@customer.example must never see your password form or a menu of providers.
  3. Leave everyone else alone — your own staff, and every other customer, keep the login they already had.

Keycloak has an Identity Provider Redirector execution that sends users to a provider with no prompt. It is not domain-based discovery: it forwards everyone (or only when the client passes kc_idp_hint, which a plain browser login does not). It satisfies 1 and 2 and breaks 3. Do not offer it as the answer to this request.

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

The mechanism: organizations, not the flow editor

Keycloak has exactly one built-in way to route by email domain, and it lives in the organizations feature, not the authentication-flow editor where someone would look for it. Three things must all be true, and each fails silently on its own:

MissingSymptom
The realm's organization support isn't switched onNo domain-based routing exists at all
An organization doesn't hold the customer's email domain, verifiedDiscovery has nothing to match (an unverified domain is stored happily and never matches)
The IdP is created but not linked to the organizationThe provider works, but the login page just shows an SSO button to everybody — no routing

Stage 1 — Switch on organization support (a realm-representation PUT)

curl -s "$BASE/admin/realms/$REALM" -H "$H" > /tmp/realm.json
# set "organizationsEnabled": true in /tmp/realm.json, then PUT it back
curl -s -X PUT "$BASE/admin/realms/$REALM" -H "$H" \
  -H 'Content-Type: application/json' --data-binary @/tmp/realm.json

# Confirm it stuck - a realm PUT that omits fields resets them, so verify rather than assume.
curl -s "$BASE/admin/realms/$REALM" -H "$H" | jq '.organizationsEnabled'

Stage 2 — Broker the customer's identity provider

Use the connection details the customer's IT team supplied (endpoints, client ID, client secret, email domain):

curl -s -X POST "$BASE/admin/realms/$REALM/identity-provider/instances" -H "$H" \
  -H 'Content-Type: application/json' -d '{
    "alias": "<idp-alias>",
    "displayName": "<Customer> SSO",
    "providerId": "oidc",
    "enabled": true,
    "trustEmail": true,
    "storeToken": false,
    "linkOnly": false,
    "config": {
      "clientId": "<client-id-from-customer>",
      "clientSecret": "<client-secret-from-customer>",
      "clientAuthMethod": "<client-auth-method>",
      "authorizationUrl": "<authorization-endpoint>",
      "tokenUrl": "<token-endpoint>",
      "userInfoUrl": "<userinfo-endpoint>",
      "jwksUrl": "<jwks-uri>",
      "issuer": "<issuer>",
      "defaultScope": "<scopes>",
      "syncMode": "IMPORT",
      "useJwksUrl": "true"
    }
  }'

trustEmail: true matters here: without it, a brokered user is asked to verify an email the customer already verified, stalling first login.

Stage 3 — Create the organization, with a verified domain

curl -s -X POST "$BASE/admin/realms/$REALM/organizations" -H "$H" \
  -H 'Content-Type: application/json' -d '{
    "name": "<org-name>",
    "alias": "<org-name>",
    "enabled": true,
    "description": "<Customer> - federated enterprise customer",
    "domains": [{"name": "<customer-email-domain>", "verified": true}]
  }'

# Get the org's id - the next step needs it.
curl -s "$BASE/admin/realms/$REALM/organizations" -H "$H" \
  | jq -r --arg n "<org-name>" '.[] | select(.name==$n) | .id'

verified: true is not optional. An unverified domain is accepted without complaint and silently never matches during discovery — there is no error to tip you off.

Stage 4 — Link the IdP to the organization — the step that gets skipped

# The body is a bare JSON STRING holding the provider alias, not an object.
curl -s -X POST "$BASE/admin/realms/$REALM/organizations/<org-id>/identity-providers" \
  -H "$H" -H 'Content-Type: application/json' -d '"<idp-alias>"'

# Verify the link actually took - don't assume it from a 204 on the create call.
curl -s "$BASE/admin/realms/$REALM/organizations/<org-id>/identity-providers" -H "$H" \
  | jq -r '.[].alias'

Creating an IdP does not associate it with any organization. Without this call, discovery will never find the IdP for that domain no matter how correct everything else is — the provider just sits there, visible as a generic SSO button to everyone, routing nobody.

Do you need a custom flow at all?

Often not: once organizations are enabled and an IdP is linked to a verified-domain organization, the realm's default built-in browser flow already performs Home IdP Discovery — no flow authoring or binding required. Confirm this by testing (below) before assuming you need more.

If the default flow on this deployment does not already discover by organization (older versions, a customized default flow), or if you specifically want "with orgs-check" behavior (the user is also treated as an organization member, not just redirected), author a custom flow from assets/home-idp.partial-import.json or assets/home-idp-with-orgs-check.partial-import.json. Both assets set forwardToLinkedIdp=true — the authenticator's factory default is false, which silently prevents any redirect at all.

Note on authoring: Keycloak's partialImport endpoint does not handle authentication flows — it has no handler for them, so an authenticationFlows array is silently ignored (HTTP 200, added: 0, no error). The admin console's "Partial import" action and kcadm.sh create partialImport hit that same endpoint and fail the same way. Author flows with the explicit sequence instead: POST .../authentication/flows to create the flow, POST .../authentication/flows/<flow>/executions/execution per step, PUT .../authentication/flows/<flow>/executions to set each requirement, and POST .../authentication/executions/<exec-id>/config to attach authenticator config. Then bind via the realm representation's browserFlow field (realm-wide) or the client's authenticationFlowBindingOverrides (single client).

Verify by logging in, not by reading configuration

Every setting here can be correct-looking and inert, and no endpoint reports routing — routing is behaviour. Perform a real login twice:

Submit on the login pageExpect
an address at the customer's verified domainno password field; the browser is sent to the customer's IdP
an address at any other domaina password field, and password login still completes

The second row is not optional — it's what distinguishes correct domain discovery from a redirector that hijacks every login.

scripts/browser_login.py drives the whole round trip over plain HTTP and prints where each step went:

python3 scripts/browser_login.py --realm acme --client acme-portal \
  --redirect-uri http://localhost:9999/callback \
  --username someone@customer.example --idp-username u --idp-password p

Two client-side details that otherwise cost an afternoon:

  • Keycloak sets AUTH_SESSION_ID and KC_RESTART as Secure; SameSite=None. Browsers send them over http://localhost anyway (loopback is a secure context); most HTTP client libraries will not, and every form POST then returns 400 "Cookie not found." Clear the flag on each response (cookie.secure = False in Python requests).
  • A user who has never federated and one who already has a federated identity are sent onward differently (an offered link versus an immediate redirect with login_hint). Test both, or a check passes on the first login and fails on the second.

Afterwards, a correctly federated user has a non-empty federated identity and no password credential in your realm — hand-creating a local account with a matching email reproduces some of the behavior while being the opposite of federation.

Provider settings that bite

  • The redirect URI the customer must whitelist is {base}/realms/{realm}/broker/{alias}/endpoint — it contains the alias, so choose the alias before asking them to whitelist anything.
  • hideOnLogin — tempting, to keep one customer's button off a shared login page. Measured: setting it true removes the route for the matched domain too, leaving those users with no password field and no way forward. Leave it visible unless you've verified the matched-domain path still works.
  • syncMode — IMPORT copies profile fields on first login only; FORCE refreshes them on every login, usually right when the customer's directory is authoritative.

Not organization restriction

This is an automatic redirect, not a membership gate. A user whose email domain matches no organization falls through to the password fallback. "Only members of this organization may log in at all" is a different, related mechanism not covered here.

Troubleshooting

SymptomCause
Matched domain still shows the password formforwardToLinkedIdp left at its false default (custom-flow path), or the IdP is not linked to the organization
SSO button shown to everyone, nothing routesProvider created but not linked to an organization
Domain never matchesThe organization's domain is not marked verified
Everyone gets forwarded to the providerAn identity-provider-redirector execution in the bound flow
Matched domain gets neither password nor routehideOnLogin is true on the provider
400 "Cookie not found" while scriptingSecure cookies not sent over http by the client
invalid_redirect_uri at the customer's providerThey whitelisted a different alias than the one created
organizationsEnabled doesn't stickA realm PUT omitting fields resets them — re-fetch and re-PUT the full representation
partialImport returned 200 but no flow existsThat endpoint ignores authentication flows entirely — author them explicitly
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: 472kUpdated 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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated 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: 323kUpdated Claude CodeCodexVerifiedInstall