p2-inc/keycloak-skills / plugins/phasetwo/skills/securing-apps
securing-apps
VerifiedUse when wiring Keycloak/OIDC login into your own app's source, or protecting an API with it. Browser login, logout and route protection for React, Angular, Vue, Next.js or a vanilla SPA (oidc-spa, keycloak-js, Auth.js); bearer-JWT validation in a Spring Boot, Express, FastAPI or Quarkus resource server (JWKS, issuer, audience); native login on Android, iOS or React Native (AppAuth, PKCE). Also registers or updates the app's OIDC client — redirect URIs, web origins, public vs confidential. Triggers: "add login to my React/Angular/Vue/Next.js app", "secure/protect my API", "validate a JWT", "invalid redirect_uri", "401 from my API", "CORS on the token call". **OIDC/OAuth2 only, not SAML.** Not realm, flow or IdP admin, not passwordless/SSO setup — that is the `keycloak` skill.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.5 KB |
| references/README.md | markdown | 8.0 KB |
| references/client-registration-mcp.md | markdown | 9.2 KB |
| references/client-registration.md | markdown | 19.3 KB |
| references/framework-android.md | markdown | 18.0 KB |
| references/framework-angular.md | markdown | 15.8 KB |
| references/framework-express-api.md | markdown | 16.5 KB |
| references/framework-fastapi-api.md | markdown | 17.2 KB |
| references/framework-ios-swift.md | markdown | 21.0 KB |
| references/framework-nextjs.md | markdown | 18.4 KB |
| references/framework-quarkus-api.md | markdown | 17.8 KB |
| references/framework-react-native.md | markdown | 21.0 KB |
| references/framework-react.md | markdown | 9.4 KB |
| references/framework-spa-js.md | markdown | 18.4 KB |
| references/framework-springboot-api.md | markdown | 23.1 KB |
| references/framework-vue.md | markdown | 16.7 KB |
| references/pattern-common-errors.md | markdown | 5.6 KB |
| references/pattern-integration-decision.md | markdown | 4.5 KB |
| references/pattern-token-validation.md | markdown | 7.9 KB |
references/framework-react.md
View on GitHub<!-- Copyright 2026 Phase Two, Inc. -->
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
# React SPA — login, logout and route protection with `oidc-spa`
## What this is
A browser-only React app (Vite, CRA, React Router) logging users into Keycloak with authorization
code + PKCE. The client is **public** — no secret ever reaches the bundle.
`oidc-spa` is Phase Two's house choice for SPAs. `keycloak-js` remains a supported alternative and
is the right call if you need its imperative API or already have it wired.
**Verified against `oidc-spa` 10.2.11** (npm `latest`, published 2026-08-01). Check the installed
version before trusting the API shape below — this library has had two breaking renames, see
"If you have seen a different API" at the end.
## Install
```bash
npm install oidc-spa zod
```
`zod` is optional but recommended — it validates the ID token's shape so a missing claim fails at
the boundary instead of as `undefined` three components deep. There are no required peer
dependencies.
## Step 1: The Keycloak client
A public client. See [`client-registration-mcp.md`](client-registration-mcp.md) or
[`client-registration.md`](client-registration.md) for the calls; what this framework needs:
| Setting | Value |
|---|---|
| Client authentication | **off** (public) |
| Standard flow | **on** |
| Valid redirect URIs | **must end with `/`** — e.g. `http://localhost:5173/` |
| Web origins | the app's origin, e.g. `http://localhost:5173` |
> ⚠️ **The trailing slash on the redirect URI is not optional for this library.** `oidc-spa`
> redirects back to a URL under the app's base path, and a redirect URI registered without the
> trailing slash fails to match. This produces `Invalid redirect_uri` on the Keycloak error page
> before login — see [`pattern-common-errors.md`](pattern-common-errors.md).
PKCE needs no configuration. It is automatic and cannot be disabled — the library enforces `S256`.
## Step 2: `src/oidc.ts`
`oidcSpa` is a **builder**, not a config function. Chain each method at most once, then
`createUtils()`:
```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(),
email: z.string().email().optional(),
preferred_username: z.string().optional(),
realm_access: z.object({ roles: z.array(z.string()) }).optional()
})
})
.createUtils();
bootstrapOidc({
implementation: "real",
issuerUri: import.meta.env.VITE_OIDC_ISSUER_URI,
clientId: import.meta.env.VITE_OIDC_CLIENT_ID
});
```
```bash
# .env.local
VITE_OIDC_ISSUER_URI=https://auth.example.com/realms/myrealm
VITE_OIDC_CLIENT_ID=my-web-app
```
**`issuerUri` includes `/realms/<realm>`.** Shape:
`https://<host><relative-path>/realms/<realm>` — the relative path is empty on modern Keycloak and
`/auth` on pre-Quarkus versions. Getting this wrong is the most common setup failure; the library
discovers every endpoint from it.
Note `withLoginEnforced` and `enforceLogin` exist **only if you did not call `.withAutoLogin()`**.
With auto-login every route requires a session, so route-level enforcement is meaningless and those
helpers are removed from the returned type.
## Step 3: `src/main.tsx`
The wrapper is `OidcInitializationGate`. There is **no `OidcProvider`** in v10:
```tsx
import { OidcInitializationGate } from "./oidc";
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<OidcInitializationGate>
<BrowserRouter>
<App />
</BrowserRouter>
</OidcInitializationGate>
</React.StrictMode>
);
```
The gate holds rendering until the library has settled whether a session exists — which is why
components below it never see an indeterminate state.
## Step 4: Login, logout, and reading the user
```tsx
import { useOidc } from "./oidc";
function Header() {
const { isUserLoggedIn } = useOidc();
if (!isUserLoggedIn) {
const { login } = useOidc({ assert: "user not logged in" });
return <button onClick={() => login()}>Log in</button>;
}
const { decodedIdToken, logout } = useOidc({ assert: "user logged in" });
return (
<>
<span>{decodedIdToken.name}</span>
<button onClick={() => logout({ redirectTo: "home" })}>Log out</button>
</>
);
}
```
`assert` narrows the type so `decodedIdToken` and `logout` are available without optional chaining.
Claims live on **`decodedIdToken`** — `.sub`, `.name`, `.email`, `.preferred_username`, and
`.realm_access?.roles` for Keycloak realm roles.
**Roles in the UI are for rendering, not for security.** Hiding a button is not authorization; the
API must validate independently — see [`pattern-token-validation.md`](pattern-token-validation.md).
## Step 5: Protecting a route
```tsx
import { withLoginEnforced } from "./oidc";
const Dashboard = withLoginEnforced(function Dashboard() {
const { decodedIdToken } = useOidc({ assert: "user logged in" });
return <h1>Hello {decodedIdToken.name}</h1>;
});
```
An unauthenticated visitor is redirected to Keycloak and returned to this route afterwards.
## Step 6: Calling your API
```ts
import { getOidc } from "./oidc";
export const fetchWithAuth: typeof fetch = async (input, init) => {
const oidc = await getOidc();
if (oidc.isUserLoggedIn) {
const accessToken = await oidc.getAccessToken();
const headers = new Headers(init?.headers);
headers.set("Authorization", `Bearer ${accessToken}`);
(init ??= {}).headers = headers;
}
return fetch(input, init);
};
```
`getAccessToken()` refreshes if needed, so call it per request rather than caching the string.
> The `react-spa` adapter exposes `getAccessToken()`. The **framework-agnostic core** adapter
> (`oidc-spa/core`, used by `framework-spa-js.md`) exposes `getTokens()` instead. Both are correct
> for their own adapter — don't mix them.
## Keycloak extras
`oidc-spa/keycloak` carries Keycloak-specific helpers:
```ts
import { createKeycloakUtils } from "oidc-spa/keycloak";
const keycloakUtils = createKeycloakUtils({ issuerUri });
keycloakUtils.getAccountUrl({ clientId, validRedirectUri, locale }); // account console
keycloakUtils.transformUrlBeforeRedirectForRegister; // "Register" button
```
Account actions (change password, update profile) go through
`goToAuthServer({ extraQueryParams: { kc_action: "UPDATE_PASSWORD" } })`.
## Verify
1. `npm run build` succeeds.
2. Click login → you land on Keycloak → after authenticating you return to the app **logged in**.
3. The user's name renders from `decodedIdToken`.
4. A protected route redirects when logged out and renders when logged in.
5. **In a real browser**, an API call carries `Authorization: Bearer …` and does not fail CORS.
Step 5 is the one a scripted test cannot do for you. A server-side script never triggers a CORS
preflight, so a wrong `webOrigins` passes every automated check and fails only in the browser.
## If you have seen a different API
This library renamed its React entry point twice. If your memory or an older example disagrees with
the code above, the code above is right for v10:
| Old | Status |
|---|---|
| `createReactOidc` from `oidc-spa/react` | **Removed.** The entire `oidc-spa/react` entry point was deleted in v9. v8 and earlier only. |
| `createOidcProvider`, `createUseOidc` | v3-era. Gone. |
| `<OidcProvider>` | Never existed in v10 — the wrapper is `OidcInitializationGate`. |
| `trustedThirdPartyResourceServers` | Renamed to `trustedExternalResourceServers` in v10. |
| `enableTokenSubstitution` | Now `tokenSubstitution`, from `oidc-spa/token-substitution`. |
Two live documentation hazards, current as of 10.2.11:
- The docs' Keycloak page has typos — it prints `clientId! "myclient"` (should be `clientId:`) and
misspells a realm as `myeralm`. Don't copy from it verbatim.
- The docs describe a `createUser` / `withUser` API that **does not exist in 10.2.11** — it is only
in the `10.3.0-rc.4` prerelease. The docs are ahead of the stable release there.
## Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| `Invalid redirect_uri` before the login form | redirect URI missing its **trailing slash** | register `http://localhost:5173/`, with the slash |
| Login works, then CORS error on the token call | `webOrigins` not set on the client | add the exact origin; redirect URIs do not imply origins |
| `Cannot find module 'oidc-spa/react'` | v8 import against a v9/v10 install | use `oidc-spa/react-spa` and the builder API above |
| `decodedIdToken` is `undefined` | read without `assert: "user logged in"` | narrow with `assert`, or check `isUserLoggedIn` first |
| A claim is missing from `decodedIdToken` | the claim isn't in the **ID token** | add a mapper in Keycloak (realm config — the `keycloak` skill), or read it from the access token |
| `withLoginEnforced` is not exported | `.withAutoLogin()` was called | with auto-login every route already requires a session; drop the wrapper |
| Zod validation throws on login | the schema demands a claim Keycloak doesn't send | mark it `.optional()`, or add the mapper |
| Session drops after a few minutes | third-party cookie blocking | see the silent-renew section in [`pattern-common-errors.md`](pattern-common-errors.md) |
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 |