- Home
- Skills
- APIs & Backend
- OIDC + PKCE for Web and Android (Keycloak)
OIDC + PKCE for Web and Android (Keycloak)
Most OIDC integrations copy a library example, skip the nonce, accept whatever `alg` the token says, and leave the realm one console click from allowing registration.
$39
Works with the AI Agents you already use
OIDC + PKCE for Web and Android (Keycloak)
Example session with this skill installed
Wire our Express app and our Android app up to the company Keycloak at auth.example.com/realms/acme, and make sure nobody can quietly weaken the realm later.
- Read your context and instructions
- Compiled the oidc + pkce
Summary
Web sign-in runs through createLoginFlow as a confidential client with PKCE; the Android app is a public client in the system browser with its own API prefix whose gateway verifies tokens itself; the realm export now passes the policy test in CI (two settings were fixed). Both clients registered with exact redirect URIs and no wildcards.
Realm, before and after
$ REALM_FILE=./ops/keycloak/realm-export.json RP_ID=auth.example.com node --test scripts/realm-policy.test.mjs
✖ email-linked username and password baseline with brute-force protection
permanentLockout expected false, got true (permanent lockout is a denial-of-service vector)
✖ security events retained 90 days; admin events without detailed payloads
adminEventsDetailsEnabled expected false, got true (admin event details can contain credentials)
ℹ pass 6 fail 2
Fixed both in the realm (permanentLockout: false with maxFailureWaitSeconds: 900; adminEventsDetailsEnabled: false), re-exported, re-ran: 8 pass. The test is now in .github/workflows/ci.yml against ops/keycloak/realm-export.json.
Clients registered
| Client | Type | Flow | Redirect | Notes |
|---|---|---|---|---|
acme-web | confidential | code + PKCE S256 | https://app.example.com/auth/callback | secret in the secret manager as KEYCLOAK_ACME_WEB_SECRET; implicit and direct grants off; post-logout URI registered |
acme-android | public | code + PKCE S256 | com.example.acme:/oauth2redirect | audience mapper adds acme-android to aud; web origins none |
Web app
src/auth/oidc-client.mjs added; routes:
app.get('/auth/login', async (req, res) => res.redirect(await login.start(req.session)));
app.get('/auth/callback', async (req, res) => {
const user = await login.complete(req.session, req.originalUrl);
req.session.user = { sub: user.subject, email: user.email, name: user.name };
res.redirect('/');
});
Offline suite: node --test scripts/oidc-client.test.mjs → 9 pass (tampered signature, wrong nonce, state mismatch, foreign callback, HS256, wrong issuer, expired token all rejected).
Android gateway
/api/native/v1/* now uses verifyAccessToken (RS256/ES256 only, JWKS from the realm, aud = acme-android, email_verified required). nginx strips Remote-User, Remote-Email, Remote-Groups on that prefix. Membership and role checks run after the token is valid; a valid token alone returns nothing.
Acceptance (emulator + Pixel)
| Case | Result |
|---|---|
| Staff sign-in | role home screen, /me returns membership |
| Identity with no membership | explicit no-access screen, no data |
| Client-portal-only identity on the staff gateway | denied (the inverted case) |
| Expired token | one silent refresh, then success |
Injected Remote-User header on the native prefix | ignored |
Not done
SMTP is not verified, so registration, verify-email and password reset stay gated per reference/account-security-rules.md; enable them together when it is.
Connects securely to your tools. The creator never sees your data.
About this skill
Most OIDC integrations copy a library example, skip the nonce, accept whatever alg the token says, and leave the realm one console click from allowing registration. This skill closes those gaps.
Web: scripts/oidc-client.mjs (Node 20+, node:crypto and fetch only): discovery with issuer validation, PKCE S256, state and nonce with single-use pending logins, confidential or public code exchange, ID-token verification against JWKS with an algorithm allow-list (no HS256, no none), exact iss, aud, azp, exp/nbf/iat with bounded skew, nonce and max_age, and an exact callback-URI check. createLoginFlow is a two-function wrapper for Express or any Node server. scripts/oidc-client.test.mjs runs a fake issuer with a locally generated RSA key and rejects tampered signatures, wrong nonce, state mismatch, foreign callback, HS256, wrong issuer and expiry.
Android: reference/android-runbook.md for a public client in the system browser, an audience mapper, a dedicated API prefix whose gateway verifies RS256 tokens itself (verifyAccessToken: audience, verified email, Bearer type) and strips proxy identity headers, a Kotlin snippet, and an acceptance matrix including the inverted role case teams forget.
Keycloak: reference/realm.template.json (passkeys with user verification, brute-force protection without permanent lockout, 12-character minimum, registration off, verify email on, 90-day events, admin details off), confidential and public client templates, and scripts/realm-policy.test.mjs, a node --test file you run in CI against the export you deploy.
Rules: reference/account-security-rules.md for the shared-broker model: cross-subdomain SSO without widening the WebAuthn boundary, deliberately gated registration and recovery codes, and an audit boundary that never records secrets.
Keycloak-specific realm policy format. No iOS coverage. Requires Node 20+. Does not handle session storage or CSRF for application-specific forms.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 19 days ago
Requires