p2-inc/keycloak-skills / benchmarks/keycloak-idp-initiated-sso/environment/skills/idpInitiatedSsoRest
idpInitiatedSsoRest
VerifiedWire IdP-initiated SSO ("portal tiles") from an already-federated SAML identity provider such as Okta or Microsoft Entra ID into ONE specific Keycloak client, using the Admin REST API only (no MCP server involved). Use this whenever someone asks for an Okta dashboard tile or an Entra "My Apps" tile that drops the user straight inside a particular application already logged in, for an app-embed link, or for "IdP-initiated SSO" / "unsolicited SAML response" into a named client. Covers the broker endpoint /realms/{realm}/broker/{alias}/endpoint/clients/{urlName}, the three CLIENT attributes that control it, Keycloak's strict binding-selection priority and the extra steps an OIDC target needs, and why RelayState cannot choose the client. Not plain "let our users log in with Okta/Entra" federation - that is ordinary SP-initiated brokering, one login button serving every client.
IdP-initiated SSO into one client (Okta / Entra tile) — via raw Admin REST
What this is, and what it is NOT
Normally the app starts the login (SP-initiated): the user hits the app, the app redirects to Keycloak, Keycloak may redirect on to a corporate IdP. IdP-initiated is the reverse: the user is already in an external portal — an Okta dashboard tile, an Entra ID "My Apps" tile — clicks it, and lands inside one specific application, already authenticated, with that app never having issued a request.
This is narrow and advanced. A plain "let our users log in with Okta/Entra" request is ordinary SP-initiated brokering (one login button serving every client) — not this. Use this only when the ask is a portal tile / app-embed link targeting one downstream client.
Two different endpoints — pick the right one first
Verified against Keycloak's source (org.keycloak.protocol.saml.SamlService,
org.keycloak.broker.saml.SAMLEndpoint):
| Who starts it | Endpoint | Client protocol allowed |
|---|---|---|
| Keycloak itself (a bookmark/portal link straight into Keycloak) | {base}/realms/{realm}/protocol/saml/clients/{urlName} | SAML clients only — SamlService.idpInitiatedSSO calls isClientProtocolCorrect() and rejects anything else with HTTP 400 "Wrong client protocol." |
| An external SAML IdP (Okta/Entra tile) POSTing an unsolicited SAML response through Keycloak | {base}/realms/{realm}/broker/{alias}/endpoint/clients/{urlName} | any enabled client, including OIDC — SAMLEndpoint.samlIdpInitiatedSSO resolves the target with searchClientsByAttributes and filters only on ClientModel::isEnabled; there is no protocol check |
That asymmetry is the single most useful fact here: it is the reason an OIDC application can be the target of a tile at all. A tile always uses the broker path.
The vendor must already be brokered as a SAML identity provider; the {alias} in that
URL is that provider. If it isn't federated yet, do that first — this mechanism is
SAML-only, there is no OIDC-broker equivalent.
The settings that matter — all on the CLIENT, not the identity provider
A SAML identity provider has no IdP-initiated settings. Verified by enumerating every
getter on org.keycloak.broker.saml.SAMLIdentityProviderConfig: there is no "IDP Initiated
SSO URL Name" and no "IDP Initiated SSO Relay State" there. Both are client attributes.
The provider's only contribution is its alias appearing in the URL above.
This is trap #1: the request arrives phrased entirely in terms of Okta and Entra, so the identity-provider representation is where everyone looks first. Nothing goes there.
| Client attribute | Admin console label | Role |
|---|---|---|
saml_idp_initiated_sso_url_name | IDP Initiated SSO URL Name | Mandatory. The {urlName} path segment. Keycloak resolves the target client by matching exactly this attribute. Empty ⇒ IdP-initiated login disabled for this client. |
saml_idp_initiated_sso_relay_state | IDP Initiated SSO Relay State | Optional. The outgoing RelayState Keycloak hands the downstream SP (a deep-link hint). Not routing — see below. |
saml.force.post.binding | Force POST Binding | Must be false for the OIDC-client recipe. |
RelayState: what it does and does not do
On the broker path, SAMLEndpoint.handleLoginResponse takes the {urlName} branch and
never reads the inbound RelayState the vendor sent; samlIdpInitiatedSSO passes null
downstream, so getOrCreateLoginSessionForIdpInitiatedSso falls back to the client's own
saml_idp_initiated_sso_relay_state attribute for the outgoing value. So:
- Okta's "Default RelayState", or any vendor-side relay value, is discarded on this path. Setting it to a client ID does nothing.
- RelayState cannot select which client the user lands in. Routing is 100% the
{urlName}path segment. One vendor-side tile therefore serves exactly one client; a second client needs its own vendor-side app whose ACS/Reply URL bakes in that client's own{urlName}.
This is trap #2: RelayState looks exactly like the routing mechanism, and Okta even gives you a field for it.
Binding selection — strict priority, and the OIDC-client recipe
SamlService.getUrlAndBindingForIdpInitiatedSso picks where and how to deliver, in order:
saml_assertion_consumer_url_postset → POST to that URL.- else client's Admin URL (
adminUrl; labeled Master SAML Processing URL — not "Home URL"/baseUrl, a naming trap) → POST. - else
saml_assertion_consumer_url_redirectset → REDIRECT (GET) to that URL. - else → error,
INVALID_REDIRECT_URI/ "SAML assertion consumer url not set up".
Then, when the response is built, SamlProtocol.isPostBinding() returns
POST.equals(clientNote(SAML_BINDING)) || samlClient.forcePostBinding() — so
forcePostBinding=true silently overrides a REDIRECT choice from case 3.
Trap #3: reaching case 3 means clearing two attributes that outrank it and a flag that overrides it afterwards. Any one of the three left set sends an HTML auto-POST form.
a. SAML client target
Set saml_idp_initiated_sso_url_name. POST binding via case 1 is correct and expected — a
SAML app can read the assertion.
b. OIDC client target
A plain web app cannot consume an incoming SAML POST body, but it can harmlessly ignore unknown query parameters on a GET. So force the REDIRECT branch:
- set
saml_assertion_consumer_url_redirect= the app's main page, - leave
saml_assertion_consumer_url_postunset/empty andadminUrlunset/empty (either one wins and forces POST), - set
saml.force.post.binding=false, - set
saml_idp_initiated_sso_url_name.
Be honest about what this is. Keycloak still builds and sends a real (and ignored) SAML artifact to that URL; the app gets nothing usable from the landing request itself. What makes it work is that the Keycloak SSO session cookie is already set by the time the browser arrives — so the app's own ordinary OIDC redirect, issued a moment later, completes silently with no login prompt. It is a session-bootstrap trick, not a native OIDC IdP-initiated flow. Say so rather than implying the tile hands the app tokens.
Trap #4: "a tile logs someone in" passes even when the shape is wrong, because Keycloak builds a SAML response for an OIDC client quite happily and the cookie is set either way. Check how the browser was delivered, not just that a session appeared.
Steps
BASE=http://localhost:8080/auth # include the relative path if configured
REALM=acme
H="Authorization: Bearer $ADMIN_TOKEN"
- Confirm the SAML IdP alias(es) — the tile URL needs one, and nothing on the provider
itself changes:
curl -s "$BASE/admin/realms/$REALM/identity-provider/instances" -H "$H" \ | jq '.[] | select(.providerId=="saml") | {alias, enabled}' - Set the client attributes. Keycloak's client update is a full-representation
PUT, so read, merge, write back — neverPUTa hand-built partial, it blanks every field it omits:ID=$(curl -s "$BASE/admin/realms/$REALM/clients?clientId=$CLIENT_ID" -H "$H" | jq -r '.[0].id') curl -s "$BASE/admin/realms/$REALM/clients/$ID" -H "$H" > /tmp/client.json # SAML client target: jq '.attributes["saml_idp_initiated_sso_url_name"]="my-reports-tile"' \ /tmp/client.json > /tmp/c2.json # OIDC client target - also clears the two POST-forcing settings and the flag: jq '.attributes["saml_idp_initiated_sso_url_name"]="my-portal-tile" | .attributes["saml_assertion_consumer_url_redirect"]="http://localhost:9999/" | .attributes["saml_assertion_consumer_url_post"]="" | .attributes["saml.force.post.binding"]="false" | .adminUrl=""' /tmp/client.json > /tmp/c2.json curl -s -X PUT "$BASE/admin/realms/$REALM/clients/$ID" -H "$H" \ -H 'Content-Type: application/json' --data-binary @/tmp/c2.json - Read the attribute back off the client — don't trust the write.
- Compute the URL to hand each vendor, one per client per provider:
That string goes into Okta's Single sign-on URL or Entra's Reply URL. For Entra, leave Sign on URL blank — a populated Sign on URL makes the tile do SP-initiated login instead. For Okta, leave Default RelayState blank; it is inert here.{BASE}/realms/{REALM}/broker/{ALIAS}/endpoint/clients/{urlName}
Verify
Fire an unsolicited response at the endpoint (POST binding: SAMLResponse is base64 of the
raw XML, not deflated; no InResponseTo, which is what makes it unsolicited) and look
at how the browser is delivered:
- OIDC target ⇒ a 302/303 whose
Locationis the app's main page. - SAML target ⇒ a 200 HTML auto-POST form whose action is the app's ACS.
Decoding the delivered SAMLResponse (redirect binding deflates before base64; POST binding
does not) shows a <saml:Audience> equal to the target client's clientId — that is the
unambiguous answer to "which client did the user land in".
Common errors
- HTTP 400 "Client not found." — the
{urlName}matches no client'ssaml_idp_initiated_sso_url_name(or that client is disabled). Re-read the attribute back. - HTTP 400 "Wrong client protocol." — the direct
/protocol/saml/clients/...endpoint was used against an OIDC client. Use the broker endpoint; only it skips the check. - "SAML assertion consumer url not set up" /
INVALID_REDIRECT_URI— none of the three binding sources is set. For an OIDC target,saml_assertion_consumer_url_redirectis the one you want. - App receives a POST it can't handle, or an auto-POST page appears —
saml.force.post.bindingis still true, orsaml_assertion_consumer_url_post/adminUrlis still set and outranks the redirect URL. - Developer set "Home URL" (
baseUrl) expecting it to matter — that field isn't read by this code path at all. The POST-forcing fallback isadminUrl. - A second tile for a second client doesn't work — expected; RelayState can't route. Each
client needs its own vendor-side app with its own
{urlName}.
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: 472k | 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 |