p2-inc/keycloak-skills / benchmarks/keycloak-app-add-login/environment/skills/securingAppsReactMcp
securingAppsReactMcp
UnverifiedWire Keycloak login into a React SPA with oidc-spa, and register or repair the OIDC client the app needs, driven through the Keycloak MCP server's tools. Use this whenever someone wants login added to a browser app - login/logout controls, route protection, reading the signed-in user - against a Keycloak realm. Covers the oidc-spa v10 builder API (which replaced the removed createReactOidc), why the registered redirect URI needs a trailing slash, why updating an existing client must be a merge rather than a rebuild, and why web origins are a separate setting from redirect URIs that fails only in a real browser.
React + Keycloak login — 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:
createOidcClient · deleteClient · listClients · updateOidcClient
- 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 skillsecuringAppsReactRestis 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
A browser-only React app logging users into Keycloak with authorization code + PKCE, using
oidc-spa. The client is public — a browser bundle cannot hold a
secret, so there is none, and PKCE replaces it.
Two halves, both required: the app's source, and the client registration in Keycloak. A correct app against a stale client does not log anyone in.
Half 1: the app
Verified against oidc-spa 10.2.11. oidcSpa is a builder, not a config function.
src/oidc.ts:
import { oidcSpa } from "oidc-spa/react-spa";
import { z } from "zod";
export const {
bootstrapOidc, useOidc, getOidc, withLoginEnforced, OidcInitializationGate
} = oidcSpa
.withExpectedDecodedIdTokenShape({
decodedIdTokenSchema: z.object({
sub: z.string(),
name: z.string().optional(),
preferred_username: z.string().optional()
})
})
.createUtils();
bootstrapOidc({
implementation: "real",
issuerUri: "http://localhost:8080/auth/realms/<realm>", // INCLUDES /realms/<realm>
clientId: "<client-id>"
});
src/main.tsx — the wrapper is OidcInitializationGate. There is no OidcProvider in v10.
<OidcInitializationGate>
<App />
</OidcInitializationGate>
Reading state, login, logout:
const { isUserLoggedIn } = useOidc();
const { login } = useOidc({ assert: "user not logged in" });
const { decodedIdToken, logout } = useOidc({ assert: "user logged in" });
// <button onClick={() => login()}> / <button onClick={() => logout({ redirectTo: "home" })}>
Claims live on decodedIdToken. Access token for API calls:
await (await getOidc()).getAccessToken().
If you remember a different API, you are remembering v8.
createReactOidcand the wholeoidc-spa/reactentry point were removed in v9.createOidcProvider/createUseOidcare v3-era. Importing any of them fails to resolve.
PKCE is automatic and cannot be disabled — the library enforces S256.
Half 2: the client
Tools: listClients to see what exists, createOidcClient for a new one, updateOidcClient to
repair one that already exists. Capture deploymentId and deploymentRealm and reuse them.
Check first, with listClients. If the app's client already exists, you are updating it.
updateOidcClient(deploymentId, deploymentRealm,
clientId = "<client-id>",
redirectUris = "<full intended list>",
webOrigins = "<full intended list>")
Three things that decide whether this works:
-
The redirect URI ends with a trailing slash. oidc-spa returns to the app's base URL, so a Vite app on port 5173 needs
http://localhost:5173/registered — with the slash. Keycloak matches redirect URIs exactly and rejects the callback outright without it (Invalid parameter: redirect_uri, before the login form). -
Web origins are a SEPARATE setting from redirect URIs, and they fail differently. The redirect URI authorizes where Keycloak sends the user back; the web origin authorizes the CORS origin of the browser's token call. Register only the redirect URI and login appears to succeed, then the token request is blocked in the browser — while every scripted, server-side test passes, because nothing in a script triggers a CORS preflight. Set
webOriginsto the app's origin (http://localhost:5173, no trailing slash) or"+". -
Both lists REPLACE, they do not append. Read the current values from
listClientsfirst and send the full intended list, or you drop whatever was already registered.
Never deleteClient a live client to change an attribute. Deleting and re-creating destroys
its protocol mappers, role mappings, secret and sessions — a rebuilt client can log a user in while
having silently lost configuration other systems depend on. updateOidcClient merges: it reads the
current representation and changes only what you pass, because Keycloak's underlying PUT replaces
the whole client.
Also confirm the client is public with standard flow enabled, and that PKCE is required
(S256).
Verify
npm run buildexits 0.listClientsshows the client enabled, public, with both the redirect URI and the web origin.- A real browser login from the app's origin completes and the token call succeeds — that last part is the half a scripted test cannot see.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Invalid parameter: redirect_uri before the login form | trailing slash missing | register http://host:port/ |
| Login works, then a CORS error on the token call | webOrigins not set | add the origin, or "+" |
Cannot find module 'oidc-spa/react' | v8 import on a v9/v10 install | use oidc-spa/react-spa |
decodedIdToken undefined | read without assert | narrow with assert: "user logged in" |
| Config that existed before the change is gone | client was rebuilt, not updated | updateOidcClient, never delete-and-re-create |
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: 467k | 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: 319k | 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: 319k | 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: 319k | Updated | Claude CodeCodex | Verified | Install |