p2-inc/keycloak-skills / benchmarks/keycloak-idp-federation-login/environment/skills/idpFederationLoginRest
idpFederationLoginRest
VerifiedBroker a partner company's own OIDC identity provider into a self-managed Keycloak realm as a plain "log in with <partner>" button, using the Admin REST API only (no MCP server involved). Use this whenever someone asks to "let our partner's staff log in with their own account", "add a login-with-X button", "federate a partner's identity provider", or "broker an external OIDC provider" - with NO organization membership requirement and NO domain-based auto-routing attached. Covers POST identity-provider/instances, mapping claims onto the brokered user with oidc-user-attribute-idp-mapper, and verifying with more than one real user so no hidden per-user gate slips in. Not admin:org-restrict-login / admin:idp-org-restrict-login (those gate on organization membership) and not admin:corporate-sso-login (that routes by email domain) - this is an unconditional login button, nothing more.
Broker a partner's OIDC identity provider as a plain login button — via raw Admin REST
What this is, and what it is NOT
The user authenticates at an external identity provider the partner company operates, and gets in with nothing more than valid credentials there. This is the simplest of three adjacent capabilities that all touch identity providers and are easy to conflate:
| Capability | Extra requirement beyond valid credentials |
|---|---|
| This one | None. Any valid account at the partner's IdP gets in. |
admin:corporate-sso-login | The user must be routed there by their email domain (organization "verified domains" + Home IdP Discovery). |
admin:org-restrict-login / admin:idp-org-restrict-login | The user must belong to a specific organization, checked via account_hint and a custom post-broker flow. |
The trap: an agent that has just solved (or read about) either of the other two
reaches reflexively for an account_hint requirement, an organization link, or a
domain check here. That produces something that looks done — a real user can log in —
but fails the actual ask, because it also blocks (or silently gates) users the caller
never meant to restrict. If the request doesn't mention organizations, teams, or
routing by email domain, don't add any of that machinery.
Step 1: create the identity provider
BASE=http://localhost:8080/auth # include the relative path if one is configured
H="Authorization: Bearer $ADMIN_TOKEN"
REALM=<realm>
ALIAS=<idp-alias>
curl -s -X POST "$BASE/admin/realms/$REALM/identity-provider/instances" -H "$H" \
-H 'Content-Type: application/json' -d '{
"alias": "'"$ALIAS"'", "displayName": "Log in with <partner>", "providerId": "oidc",
"enabled": true, "trustEmail": true, "storeToken": false, "linkOnly": false,
"config": {
"clientId": "<client-id>", "clientSecret": "<client-secret>",
"clientAuthMethod": "client_secret_post",
"authorizationUrl": "<authorization-endpoint>", "tokenUrl": "<token-endpoint>",
"userInfoUrl": "<userinfo-endpoint>", "jwksUrl": "<jwks-uri>", "issuer": "<issuer>",
"defaultScope": "openid profile email", "syncMode": "IMPORT", "useJwksUrl": "true"
}}'
Either construct config directly from what the partner's IT team handed over (as
above), or resolve the endpoints first with POST .../identity-provider/import-config
using {"providerId":"oidc","fromUrl":"<issuer>/.well-known/openid-configuration"} and
merge in clientId/clientSecret — both work; the direct-construction path has one
fewer round trip and no dependency on outbound discovery fetches succeeding.
The redirect URI Keycloak will use is {BASE}/realms/{REALM}/broker/{ALIAS}/endpoint.
If the partner's registered callback is a wildcard (e.g. .../broker/*) any alias
works; otherwise pick the alias to match whatever they whitelisted ahead of time.
Step 2: map claims onto the brokered user
curl -s -X POST "$BASE/admin/realms/$REALM/identity-provider/instances/$ALIAS/mappers" \
-H "$H" -H 'Content-Type: application/json' -d '{
"name": "email",
"identityProviderAlias": "'"$ALIAS"'",
"identityProviderMapper": "oidc-user-attribute-idp-mapper",
"config": {"syncMode":"INHERIT", "claim": "email", "user.attribute": "email"}
}'
Repeat once per claim — for the common shape that's three calls:
email→email, given_name→firstName, family_name→lastName. Verify the exact
claim names against the partner's documentation rather than assuming standard OIDC
naming; several providers emit non-standard names for anything beyond email.
Step 3: verify by logging in as more than one user
Nothing here reports whether the button quietly grew an extra gate. The obvious
check — "a valid user with valid credentials gets in" — passes even on a mis-scoped
setup that also (incorrectly) blocks a different valid user. Drive at least two real
logins, with two different partner accounts that are otherwise unrelated to each
other, forcing the provider with kc_idp_hint and with no account_hint or
organization-hint parameter anywhere on the request:
$BASE/realms/$REALM/protocol/openid-connect/auth
?client_id=<client>&response_type=code&scope=openid
&redirect_uri=<redirect>&state=<state>&kc_idp_hint=$ALIAS
Both users must land back at the redirect URI with a code. If either is rejected,
something has been over-scoped.
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
| Symptom | Cause |
|---|---|
| "Invalid redirect_uri" | The registered redirect URI on the partner's side doesn't match {BASE}/realms/{REALM}/broker/{ALIAS}/endpoint (or its wildcard). |
| A claim doesn't land on the user | claim in the mapper config doesn't match the exact name the partner's token sends. |
Redirect chain dead-ends at /broker/{alias}/login | Secure cookies not sent over http by the client. |
| One test user works but the task actually wanted "any valid account" | Resist the urge to add an account_hint / organization check "just in case" — only add it if the request actually asked for membership-based restriction or domain-based routing. |
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 |