Skip to content

p2-inc/keycloak-skills / benchmarks/keycloak-idp-federation-login/environment/skills/idpFederationLoginMcp

idpFederationLoginMcp

Verified

Broker a partner company's own OIDC identity provider into a Phase Two hosted Keycloak realm as a plain "log in with <partner>" button - driven through the Keycloak MCP server. 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 createOidcIdp, mapping claims onto the brokered user with addIdpAttributeMapper, 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 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:

addIdpAttributeMapper · createOidcIdp · listIdentityProviders · 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 idpFederationLoginRest 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 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:

CapabilityExtra requirement beyond valid credentials
This oneNone. Any valid account at the partner's IdP gets in.
admin:corporate-sso-loginThe user must be routed there by their email domain (organization "verified domains" + Home IdP Discovery).
admin:org-restrict-login / admin:idp-org-restrict-loginThe 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.

Tools this skill drives (Keycloak MCP server)

PurposeTool
Identify caller / realmwhoAmI
Broker the partner's OIDC providercreateOidcIdp
Map claims onto the brokered useraddIdpAttributeMapper
VerifylistIdentityProviders

Capture deploymentId and deploymentRealm and reuse them on every call.

Step 1: create the identity provider

createOidcIdp(deploymentId, deploymentRealm, issuerOrDiscoveryUrl, clientId, clientSecret,
              realm?, alias?, displayName?, defaultScopes?, trustEmail?, syncMode?)

The partner's app must already exist with a client ID/secret before this call — the partner's IT team hands these over along with their issuer URL. Returns a redirectUri; if the partner's registered callback is a wildcard (e.g. .../broker/*) any alias works, otherwise the alias must be chosen to match whatever they whitelisted before calling this.

trustEmail: true is usually right when the partner has already verified their staff's addresses.

Step 2: map claims onto the brokered user

Every claim the partner's token carries that should land on the Keycloak user needs its own mapper call:

addIdpAttributeMapper(deploymentId, deploymentRealm, idpAlias, protocol="oidc",
                       mapperName, source, userAttribute, realm?, syncMode?)

For the common shape (email/given_name/family_name → email/firstName/lastName), call it three times — once per claim. source is the OIDC claim name the partner's ID token or userinfo response actually sends (verify against their documentation rather than assuming standard OIDC naming, especially for anything beyond these three).

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, or that happens to work only because the one test account is a member of some group. Drive at least two real logins, with two different partner accounts that are otherwise unrelated to each other, and confirm both land back at the application's redirect URI with an authorization code — with no account_hint or organization-hint parameter on the authorization request at all. If either user is rejected, something has been over-scoped.

If scripting rather than clicking: 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 the broker endpoint. Follow redirects manually and clear the flag after every response.

Common errors

  • "Invalid redirect_uri" — the redirectUri createOidcIdp returned isn't registered (or doesn't match a wildcard) on the partner's side.
  • A claim doesn't land on the user — source in addIdpAttributeMapper doesn't match the exact claim name the partner's token sends; check their documentation rather than assuming standard OIDC naming.
  • 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.
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