Skip to content

p2-inc/keycloak-skills / plugins/phasetwo/skills/securing-apps

securing-apps

Verified

Use 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.

Securing applications

Detect intent → detect framework → ask two questions → load references.

A router: no steps of its own, every instruction behind a Read: in Step 5. Its target is your application's source code. Configuring the realm — flows, passwordless, IdP federation, organizations — is the sibling keycloak skill. "Make login work in Keycloak" → hand off.


Detection is free, questions are expensive. Steps 1-2 read files and ask nothing. Steps 3-4 are the only two questions, in that order: Step 4 needs Step 2's answer. Don't ask either twice.


Step 0: Before you write to a live realm

Read before routing: Step 4's existing-client branch changes a client others may depend on.

  • Confirm before changing an existing client — say what changes, on which, and wait. Creating a new one needs no confirmation; altering one that serves traffic does.
  • Verify by re-reading, not by the return code. Keycloak's client PUT answers 204 while silently blanking every field the payload omitted. Read it back and check what you did not intend to change survived.
  • Never hardcode a secret. Public clients have none; a confidential client's stays server-side.

Step 1: Detect intent

What the developer wants (plain language)Intent
Log users in from a browser app — "add login to my React app", "sign in with Keycloak", "protect this route/page", "log out". The app renders UI and redirects a human to Keycloak. Not a backend that only checks a token (next row), not a native app (row after).app:add-login
Protect an API by validating a bearer token — "secure my API", "validate the JWT", "map Keycloak roles to authorities". No login UI, no redirect, no cookie session: the token arrives in an Authorization header. Not a server-rendered web app that logs users in, and not fixing an API that already validates (last row).app:protect-api
Log users in from a native mobile or desktop app — "add login to my Android/iOS app", "React Native + Keycloak", "custom URL scheme callback", "where do I store tokens". System browser, never an embedded WebView. Not a mobile-shaped web page (app:add-login).app:mobile-login
Diagnose an integration that already exists and is failing — "invalid redirect_uri", "401 from my API", "CORS on the token call", "redirect loop", "my roles are missing". Something is wired; find what is wrong. Not a fresh build (rows above) — look for existing auth code first.app:debug

The app speaks SAML, not OIDC

Never route a SAML app into an OIDC framework file — nothing in references/framework-*.md applies. Recognise it from the request ("SAML SSO", "ACS URL", "SP metadata", "assertion") or the manifest — passport-saml, @node-saml/node-saml, samlify, python3-saml, pysaml2, spring-security-saml2-service-provider, ruby-saml, simplesamlphp.

Split the answer. Keycloak side: available — createSamlClient takes spMetadataXml, and the org-level connectingkeycloakclient skill walks the registration (no SAML update tool exists, so changing one means the REST read-merge-PUT). App side — SP library, assertion handling, session — not covered in v1. Offer the first, say the second is uncovered, don't improvise SP code.

No intent matches

Don't force an uncovered request into app:add-login.

Out of scope: realm/flow/IdP config, passwordless, SSO, organizations → the keycloak skill. Running/deploying the server, or writing an SPI provider, theme or extension jar → neither yet.

Otherwise follow the keycloak router's gap procedure: say plainly it isn't covered, offer to open an issue in p2-inc/keycloak-skills quoting the developer's verbatim prompt, and show the draft before filing. If they decline, leave it — don't paper over the gap by answering anyway. The same offer applies when a covered reference file itself fails — name the file and what went wrong; keep helping either way.


Step 2: Detect framework

Read the project's manifests. Stop at the first tier that yields a framework.

Tier 1 — an OIDC/auth SDK is installed (strongest signal)

Top to bottom, stop at the first match — a superset carries the subset's dependency, so compound rows precede bare ones. An SDK installed but not yet configured still counts.

Dependency foundFramework
next-auth / @auth/*nextjs
oidc-spa + @angular/core · keycloak-angularangular
oidc-spa + reactreact
keycloak-js + vuevue
oidc-spa or keycloak-js, alonespa-js
react-native-app-auth / expo-auth-sessionreact-native
AppAuth (Package.swift, *.xcodeproj)ios-swift
net.openid:appauth (build.gradle(.kts))android
spring-boot-starter*-oauth2-resource-serverspringboot-api
quarkus-oidcquarkus-api
jose / express-jwt / jwks-rsaexpress-api
pyjwt / python-josefastapi-api

Manifests: package.json, requirements.txt / pyproject.toml, pom.xml / build.gradle(.kts), Package.swift / *.xcodeproj, pubspec.yaml, *.csproj.

Tier 2 — ordinary (non-auth) dependencies

Same order rule; * needs the variant rule below.

DependencyFrameworkDependencyFramework
nextnextjsexpress / fastifyexpress-api *
@angular/coreangularfastapi / flaskfastapi-api *
vue / nuxtvuespring-boot-starter-webspringboot-api *
react-native / exporeact-nativequarkusquarkus-api
reactreact

Tier 3 — the prompt

Map the developer's words to the same keys.

Variant disambiguation — web app vs API

Only when Tier 1 didn't already pin it — a Tier 1 match on one of the API rows is the API variant. This rule is for Tier 2/3 matches, where intent outranks the manifest. Web variants are v2.

Tier 2/3 baseAPI variantChoose it when…
express / fastifyexpress-apivalidating JWTs on routes, no server-rendered login UI
spring-boot-starter-webspringboot-apiresource server, no cookie-based login
fastapi / flaskfastapi-apitoken validation only

If the app genuinely has both a login UI and protected endpoints, state what was detected and ask which half to do first. Don't silently pick.

Conflicts and gaps

  • Tier 2 and Tier 3 disagree materially → state the conflict and ask. Workspace signals outrank the prompt when both are present and consistent.
  • Nothing matched → ask. Don't guess.
  • Detection must not outrun coverage. Flutter (pubspec.yaml), .NET (*.csproj), Go and reverse-proxy setups (oauth2-proxy, mod_auth_openidc, Envoy, NGINX) are recognised for disambiguation but have no reference file in v1. Say so and offer the generic OIDC shape from pattern-integration-decision.md — never a neighbouring framework's file, never a silent dead end.

Step 3 (first question): Phase Two, or self-managed?

This decides the tooling for client registration. Ask directly; don't infer it.

AnswerTooling
Yes — Phase Two hosted.mcp. The plugin declares it as keycloak (https://mcp.phasetwo.io/mcp). Missing tools usually mean an unauthorized OAuth connection, not a missing server — have them check /mcp.
No — self-managed (bare metal, Docker, Kubernetes; direct Admin REST access).rest.

If the answer is ambiguous, ask — don't guess and don't default to either side.

On mcp, rest is not a fallback. A hosted deployment has no self-service admin REST credential of any kind, so the rest file fails at its first step: there is no admin token to use. If the developer declines MCP, point them at reconnecting it or at the dashboard.

On rest: base URL and Admin token. The developer's configured base URL is ${user_config.keycloak_base_url} (an unexpanded placeholder or empty value means unset — ask). client-registration.md needs an admin token (<admin-access-token> in the snippets), a master-realm admin access token: ask the developer for the token itself — never for their admin password, and never read a password or token from files, environment variables or keychains on their machine. They mint it in their own terminal; it lasts about a minute by default, so on a 401 ask for a fresh one.

Tooling affects only client registration — never the app's library or wiring.


Step 4 (second question): a new client, or one that already exists?

Step 2 must have run first: the app's shape decides the client type.

On tooling=mcp, answer by detection, not by asking — listClients shows what exists. Check the app's own config too (.env, keycloak.json, application.properties): a clientId already there means "existing", and its value is the answer. Ask outright only if that's ambiguous, or on rest.

BranchWhat it means
New clientNothing exists yet. Create it; Step 2's framework decides public vs confidential.
Existing clientA clientId already exists and needs its redirect URIs or web origins widened. Update it; never delete and re-create a live client.

The client-registration reference carries both branches. Say which you're on.


Step 5: Load reference files

ReadWhen
pattern-integration-decision.mdbuild intents, first — pattern before library
references/framework-{framework}.mdwhenever Step 2 identified one
client-registration-mcp.md (mcp) / client-registration.md (rest)build intents, per Step 3
pattern-token-validation.mdapp:protect-api, or app:debug on an API symptom (401/403). The framework-*-api.md files don't repeat it.
pattern-common-errors.mdalways — and first for app:debug: symptom → cause

app:debug is diagnostic, not constructive: it skips Steps 3-4 until the diagnosis names the client. Don't ask someone with a broken flow which tooling they run before you know whether the fix is even in Keycloak.

Framework files

references/framework-{framework}.md. A framework key not listed here has no file — admit the gap rather than substituting a neighbour.

IntentFramework key → file
app:add-loginreact · angular · vue · spa-js · nextjs
app:protect-apispringboot-api · express-api · fastapi-api · quarkus-api
app:mobile-loginandroid · ios-swift · react-native

If a framework file and your recollection disagree about which library to use, the file is right. Keycloak removed its Java adapters in 25.0.0 and deprecated keycloak-connect; each framework file names the dead adapter it replaces. Emitting one is the most likely failure here — older training data suggests it, and it doesn't build.

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: 469kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall