OIDC + PKCE for Web and Android (Keycloak)

    1

    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

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    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

    ClientTypeFlowRedirectNotes
    acme-webconfidentialcode + PKCE S256https://app.example.com/auth/callbacksecret in the secret manager as KEYCLOAK_ACME_WEB_SECRET; implicit and direct grants off; post-logout URI registered
    acme-androidpubliccode + PKCE S256com.example.acme:/oauth2redirectaudience 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)

    CaseResult
    Staff sign-inrole home screen, /me returns membership
    Identity with no membershipexplicit no-access screen, no data
    Client-portal-only identity on the staff gatewaydenied (the inverted case)
    Expired tokenone silent refresh, then success
    Injected Remote-User header on the native prefixignored

    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.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for APIs & Backend.

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

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    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

    Software
    Node.js 20+
    Keycloak
    oranother OIDC issuer
    Optional
    Kotlin Android app
    AppAuth
    orsimilar library

    You need admin access to the OIDC issuer. The Kotlin app and AppAuth-style library are only for Android.

    Permissions

    Terminal / Shell
    Read Files
    Write Files
    Network Access
    Listed19 days ago

    What's inside

    Frequently Asked Questions

    This skill eliminates common OIDC vulnerabilities—such as weak nonce validation or insecure realm configurations—by providing a dependency-free Node.js client and a 'policy-as-code' test suite that ensures your Keycloak settings remain hardened against configuration drift.

    The package includes a hardened Keycloak realm policy, a native Node.js OIDC client module (no external NPM dependencies), Android-specific integration templates, and a security-focused gateway runbook.

    Yes, the Node.js client is built using native modules (node:crypto and fetch) and is compatible with Node.js 20+, while the realm policies are optimized for Keycloak 26+; it can be integrated into any AI agent workflow that supports these environments.

    The integration is designed to be developer-friendly: you first run the policy test against your Keycloak export, register your clients using the provided templates, and then initialize the Node.js module within your application logic.

    While this skill provides a robust implementation for Web and Android (Kotlin) platforms, it does not currently include specific snippets or templates for iOS development.

    The skill focuses on the core authentication and token validation logic; session persistence, cookie management, and global logout propagation are left to the host application to allow for maximum architectural flexibility.

    New in APIs & Backend