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.
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
204while 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 found | Framework |
|---|---|
next-auth / @auth/* | nextjs |
oidc-spa + @angular/core · keycloak-angular | angular |
oidc-spa + react | react |
keycloak-js + vue | vue |
oidc-spa or keycloak-js, alone | spa-js |
react-native-app-auth / expo-auth-session | react-native |
AppAuth (Package.swift, *.xcodeproj) | ios-swift |
net.openid:appauth (build.gradle(.kts)) | android |
spring-boot-starter*-oauth2-resource-server | springboot-api |
quarkus-oidc | quarkus-api |
jose / express-jwt / jwks-rsa | express-api |
pyjwt / python-jose | fastapi-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.
| Dependency | Framework | Dependency | Framework | |
|---|---|---|---|---|
next | nextjs | express / fastify | express-api * | |
@angular/core | angular | fastapi / flask | fastapi-api * | |
vue / nuxt | vue | spring-boot-starter-web | springboot-api * | |
react-native / expo | react-native | quarkus | quarkus-api | |
react | react |
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 base | API variant | Choose it when… |
|---|---|---|
express / fastify | express-api | validating JWTs on routes, no server-rendered login UI |
spring-boot-starter-web | springboot-api | resource server, no cookie-based login |
fastapi / flask | fastapi-api | token 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 frompattern-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.
| Answer | Tooling |
|---|---|
| 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.
| Branch | What it means |
|---|---|
| New client | Nothing exists yet. Create it; Step 2's framework decides public vs confidential. |
| Existing client | A 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
| Read | When |
|---|---|
pattern-integration-decision.md | build intents, first — pattern before library |
references/framework-{framework}.md | whenever Step 2 identified one |
client-registration-mcp.md (mcp) / client-registration.md (rest) | build intents, per Step 3 |
pattern-token-validation.md | app:protect-api, or app:debug on an API symptom (401/403). The framework-*-api.md files don't repeat it. |
pattern-common-errors.md | always — 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.
| Intent | Framework key → file |
|---|---|
app:add-login | react · angular · vue · spa-js · nextjs |
app:protect-api | springboot-api · express-api · fastapi-api · quarkus-api |
app:mobile-login | android · 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.
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: 469k | 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: 321k | 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: 321k | 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: 321k | Updated | Claude CodeCodex | Verified | Install |