Cursor Rules Template: OAuth2/OIDC with Keycloak Integration for Cursor AI

Overview

This Cursor Rules Template provides a copyable .cursorrules configuration for integrating OAuth2/OIDC using Keycloak within a Node.js/Express backend, guided by Cursor AI. It defines a secure token validation flow, Keycloak interaction, and production-ready defaults tailored for Cursor AI powered workflows.

When to Use These Cursor Rules

• Adding Keycloak-based OAuth2/OIDC authentication to a Node.js/Express API
• Validating access tokens issued by Keycloak against your resource server
• Configuring secure, auditable authentication flows in Cursor AI projects

Copyable .cursorrules Configuration

framework: nodejs-express; version: 1; role_and_context: backend api engineer integrating Keycloak for OAuth2/OIDC; context: Cursor AI guided code construction; style: language TypeScript; lint_tools: eslint, prettier; architecture_and_dir: root src; dirs: config, controllers, middleware, routes, services; auth_security: keycloak_adapter: true; token_validation: jwks; issuer: https://{your-keycloak-domain}/auth/realms/{your-realm}; audience: {your-api-audience}; client_id: {your-client-id}; client_secret: {your-secret-if-confidential-client}; db_patterns: database: postgresql; client_lib: pg; orm: none; testing_and_ci: unit_tests: jest; api_tests: supertest; ci: github-actions; anti_patterns: - do_not_hardcode_secrets - do_not_disable_tls - do_not_log_tokens - do_not_bypass_ssl_check

Recommended Project Structure

oauth2-keycloak-app/

oauth2-keycloak-app/

  src/

    config/

      keycloak.ts

    controllers/

      authController.ts

    middleware/

      keycloakAuth.ts

    routes/

      authRoutes.ts

    services/

      keycloakService.ts

  tests/

  .env.example

  package.json

  tsconfig.json

  .eslintrc.json

  .prettierrc

Core Engineering Principles

• Prefer explicit token validation against the JWKS endpoint and issuer/audience checks.
• Isolate Keycloak logic in dedicated modules; avoid leaking secrets into code paths.
• Treat external config (URLs, realms, audience) as environment-driven.
• Keep the code generation flow deterministic and auditable with Cursor AI.
• Limit surface area of authenticated endpoints and apply least privilege.

Code Construction Rules

• Use a dedicated Keycloak adapter pattern and verify tokens with JWKS at runtime.
• Do not bypass TLS or accept self-signed certificates in production.
• Do not hardcode client secrets; fetch from environment or secret manager.
• Keep Keycloak realm, client_id, and audience in env vars and validate at startup.
• Validate token scopes and permissions before granting access to resources.
• Document dependency versions and pin them to compatible ranges.

Security and Production Rules

• Enforce TLS termination at the edge and enable HSTS in production.
• Use secure cookies for session-related data and disable client-side storage for tokens when possible.
• Regularly rotate Keycloak client credentials and monitor token audit events.
• Implement CSRF protection for any session-based endpoints and ensure CORS is restricted.
• Log access attempts with minimal sensitive data and redact tokens in logs.

Testing Checklist

• Unit test token validation utilities and JWKS fetch logic.
• Integration test the Keycloak login flow against a mock or test realm.
• End-to-end test API endpoints with valid and invalid tokens.
• Static analysis and linting in CI; fail on warnings that violate rules.
• Test production-like configurations for TLS and environment-based secrets.

Common Mistakes to Avoid

• Hardcoding client secrets or tokens in repository.
• Disabling TLS or skipping token validation for performance.
• Over-permissive token scopes or misconfigured audience.
• Neglecting token refresh and session management in public clients.
• Ignoring Keycloak realm or issuer URL drift across environments.

FAQ

What is the purpose of this Cursor Rules Template?

This template provides a copyable .cursorrules block and stack-specific guidance for integrating OAuth2/OIDC with Keycloak in a Cursor AI workflow using Node.js/Express. It defines authentication flows, security constraints, and testing patterns.

Which stack does this template target?

Node.js/Express backend with Keycloak as the OIDC provider. The template focuses on configuring Keycloak adapters, token validation via JWKS, and secure API endpoints in Cursor AI.

How should I structure the project?

Follow the Recommended Project Structure in the template: target code under src/, with clear separation for config, routes, controllers, and services. Keep Keycloak config in config/keycloak.ts and migrate to production vaults for secrets.

What are the security checks included?

Token validation, issuer and audience checks, JWKS fetching, TLS enforcement, secure cookies, and avoidance of hardcoded secrets. The template also highlights anti-patterns and logging guidelines.

How do I test this integration?

Use unit tests for token validation utilities, integration tests against a mock Keycloak server, and CI workflows for end-to-end checks when starting the API and performing login flows.