keycloak-express-middleware 6.1.2 → 6.2.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [6.2.0] - 2026-03-18
+
+### Added
+- **Helper Utilities for Auth & Scope Management** — New imperative methods to simplify common token/scope operations:
+  - `getTokenClaims(req)` — Extract decoded JWT claims from request
+  - `isAuthenticated(req)` — Check if user's access token is valid
+  - `getScopes(scopeInputOrReq)` — Normalize and retrieve scope list from string, array, or request
+  - `hasScopeFromRequest(req, requiredScope)` — Check single scope from request token
+  - `hasScopesFromRequest(req, requiredScopes, mode)` — Check multiple scopes from request token (all/any mode)
+  - `requireScopes(requiredScopes, mode)` — Middleware to enforce scope requirements (returns 403 JSON if missing)
+- **TypeScript Definitions** (`index.d.ts`) — Type coverage for all exported functions and middleware
+- **CHANGELOG.md** — Centralized changelog for release tracking
+- Comprehensive test coverage for all new methods (57 tests passing)
+
+### Documentation
+- Updated README with new API documentation and examples
+- Clarified Direct Access Grants prerequisites for password grant flow
+- Added OIDC integration guide notes
+
+### Dependencies
+- `express-session` ^1.19.0
+- `keycloak-connect` ^26.1.1
+
+## [6.1.3] - 2026-03-18
+
+### Added
+- Scope checking utilities (`hasScope`, `hasScopes`) for imperative token validation
+- Direct Access Grants documentation and clarification in guides
+
+### Fixed
+- Test workspace installation and execution flow
+- Package.json runtime dependencies minimized to reduce surface area
+
+## [6.1.0] — [6.1.2]
+
+See GitHub releases for detailed history.
+
+---
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/):
+- **MAJOR** (X.0.0): Breaking API changes, major feature overhauls
+- **MINOR** (0.X.0): New features, helper utilities, backward compatible
+- **PATCH** (0.0.X): Bug fixes, docs, internal improvements
+
+## Migration Guides
+
+- See [OIDC_INTEGRATION_GUIDE.md](./docs/OIDC_INTEGRATION_GUIDE.md) for OpenID Connect setup
+- See [README.md](./README.md) for API reference and examples

package/OIDC_INTEGRATION_GUIDE.md

@@ -17,6 +17,9 @@ Important alignment notes with current implementation:
 - Use a middleware instance created with:
   new keycloackAdapter(app, keyCloackConfig, keyCloackOptions)
 - For generic token endpoint exchange use loginWithCredentials, not login.
+- If loginWithCredentials is used with grant_type=password, enable Direct Access Grants on the client.
+- This is OAuth2 Resource Owner Password Credentials Grant support for that client.
+- loginPKCE (authorization_code + code_verifier) does not require Direct Access Grants.
 
 Quick verification command:
 

package/README.md

@@ -35,6 +35,14 @@ It is based on **'keycloak-connect'** and **'express-session'**.
         - [API - loginWithCredentials](#api---loginwithcredentialscredentials)
         - [API - loginPKCE](#api---loginpkcecredentials)
         - [API - redirectToUserAccountConsole](#api---redirecttouseraccountconsoleres)
+        - [API - hasScope](#api---hasscopescopeinput-requiredscope)
+        - [API - hasScopes](#api---hasscopesscopeinput-requiredscopes-mode)
+        - [API - getTokenClaims](#api---gettokenclaimsreq)
+        - [API - isAuthenticated](#api---isauthenticatedreq)
+        - [API - getScopes](#api---getscopesscopeinputorreq)
+        - [API - hasScopeFromRequest](#api---hasscopefromrequestreq-requiredscope)
+        - [API - hasScopesFromRequest](#api---hasscopesfromrequestreq-requiredscopes-mode)
+        - [API - requireScopes](#api---requirescopesrequiredscopes-mode)
 - [Handling Unauthorized Access (401/403) Gracefully](#handling-unauthorized-access-401403-gracefully)
 - [Testing Documentation](#testing-documentation)
 - [License](#license)
@@ -1039,6 +1047,10 @@ What `loginPKCE(...)` actually does:
 - Calls the token endpoint with grant type `authorization_code` and PKCE verifier.
 - Returns token payload for your own persistence/session strategy.
 
+Client configuration note for PKCE:
+
+- `loginPKCE(...)` uses Authorization Code + PKCE and does **not** require `Direct Access Grants`.
+
 Use `loginWithCredentials(...)` when:
 
 - You need direct token endpoint operations (e.g., refresh token, client credentials, custom grant handling).
@@ -1050,6 +1062,12 @@ What `loginWithCredentials(...)` actually does:
 - Supports multiple grant models by payload (`password`, `client_credentials`, `authorization_code`, `refresh_token`).
 - Returns raw token endpoint response or throws error on failure.
 
+Client configuration note for non-browser password login:
+
+- When `loginWithCredentials(...)` is used with `grant_type=password`, the client must have `Direct Access Grants` enabled in Keycloak.
+- This means the client handles username/password directly and exchanges them with Keycloak token endpoint.
+- In OAuth2 terms, this enables `Resource Owner Password Credentials Grant` support for that client.
+
 Recommended PKCE sequence:
 
 1. Start flow with `generateAuthorizationUrl(...)` and persist `state` + `codeVerifier` server-side.
@@ -1211,6 +1229,12 @@ Generic OAuth2 token endpoint helper supporting multiple grant types.
 - `authorization_code`
 - `refresh_token`
 
+**Client configuration requirement (`password` grant only)**
+
+- If you call `loginWithCredentials(...)` with `grant_type=password`, the Keycloak client must have `Direct Access Grants` enabled.
+- This corresponds to OAuth2 `Resource Owner Password Credentials Grant` for that client.
+- This requirement does not apply to `client_credentials`, `refresh_token`, or `authorization_code` payloads.
+
 **Parameters**
 
 | Name | Type | Required | Description |
@@ -1262,6 +1286,7 @@ Performs authorization-code + PKCE verifier exchange.
 
 - PKCE mitigates intercepted authorization code reuse by binding code to `code_verifier`.
 - This method encapsulates the correct grant payload shape for PKCE callback stage.
+- PKCE callback exchange does not require `Direct Access Grants`.
 
 **Parameters**
 
@@ -1328,6 +1353,216 @@ app.get('/my-account', (req, res) => {
 });
 ```
 
+#### API - hasScope(scopeInput, requiredScope)
+
+**Signature**
+
+```js
+hasScope(scopeInput, requiredScope)
+```
+
+Checks whether one scope is present in a scope string or array.
+
+**What this API is for**
+
+- Use this helper to check scopes without rewriting parsing logic in every route.
+- Works with both middleware token claims and token endpoint responses.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `scopeInput` | `string \| string[]` | Yes | Scope source (`"openid profile email"` or `['openid', 'profile']`). |
+| `requiredScope` | `string` | Yes | Scope to verify. |
+
+**Returns**
+
+- `boolean`: `true` if scope exists, otherwise `false`.
+
+**Example**
+
+```js
+const tokenScope = req?.kauth?.grant?.access_token?.content?.scope;
+const canReadEmail = keycloakInstance.hasScope(tokenScope, 'email');
+```
+
+#### API - hasScopes(scopeInput, requiredScopes, mode)
+
+**Signature**
+
+```js
+hasScopes(scopeInput, requiredScopes, mode = 'all')
+```
+
+Checks multiple scopes with `all` (default) or `any` matching mode.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `scopeInput` | `string \| string[]` | Yes | Scope source (`"openid profile email"` or array). |
+| `requiredScopes` | `string \| string[]` | Yes | One or more scopes to evaluate. |
+| `mode` | `'all' \| 'any'` | No | `all` requires all scopes, `any` requires at least one. |
+
+**Returns**
+
+- `boolean`: scope validation result.
+
+**Example**
+
+```js
+const scopeString = tokenResponse.scope;
+
+const hasAll = keycloakInstance.hasScopes(
+    scopeString,
+    ['openid', 'profile'],
+    'all'
+);
+
+const hasAny = keycloakInstance.hasScopes(
+    scopeString,
+    ['email', 'offline_access'],
+    'any'
+);
+```
+
+#### API - getTokenClaims(req)
+
+**Signature**
+
+```js
+getTokenClaims(req)
+```
+
+Safely returns decoded access token claims from request.
+
+**Returns**
+
+- `Object`: token claims object, or `{}` if token is unavailable.
+
+**Example**
+
+```js
+const claims = keycloakInstance.getTokenClaims(req);
+const username = claims.preferred_username;
+```
+
+#### API - isAuthenticated(req)
+
+**Signature**
+
+```js
+isAuthenticated(req)
+```
+
+Checks whether request contains a Keycloak access token.
+
+**Returns**
+
+- `boolean`.
+
+**Example**
+
+```js
+if (!keycloakInstance.isAuthenticated(req)) {
+    return res.status(401).send('Not authenticated');
+}
+```
+
+#### API - getScopes(scopeInputOrReq)
+
+**Signature**
+
+```js
+getScopes(scopeInputOrReq)
+```
+
+Normalizes scopes to an array from one of:
+
+- scope string
+- scope array
+- Express request (`req.kauth.grant.access_token.content.scope`)
+
+**Returns**
+
+- `string[]`.
+
+**Example**
+
+```js
+const scopes = keycloakInstance.getScopes(req);
+// ['openid', 'profile', 'email']
+```
+
+#### API - hasScopeFromRequest(req, requiredScope)
+
+**Signature**
+
+```js
+hasScopeFromRequest(req, requiredScope)
+```
+
+Convenience wrapper around `hasScope(...)` using request token claims.
+
+**Returns**
+
+- `boolean`.
+
+**Example**
+
+```js
+const canReadEmail = keycloakInstance.hasScopeFromRequest(req, 'email');
+```
+
+#### API - hasScopesFromRequest(req, requiredScopes, mode)
+
+**Signature**
+
+```js
+hasScopesFromRequest(req, requiredScopes, mode = 'all')
+```
+
+Convenience wrapper around `hasScopes(...)` using request token claims.
+
+**Returns**
+
+- `boolean`.
+
+**Example**
+
+```js
+const allowed = keycloakInstance.hasScopesFromRequest(
+    req,
+    ['openid', 'profile'],
+    'all'
+);
+```
+
+#### API - requireScopes(requiredScopes, mode)
+
+**Signature**
+
+```js
+requireScopes(requiredScopes, mode = 'all')
+```
+
+Express middleware that enforces scopes and responds `403` if missing.
+
+**Returns**
+
+- Middleware return.
+
+**Example**
+
+```js
+app.get(
+    '/profile-email',
+    keycloakInstance.protectMiddleware(),
+    keycloakInstance.requireScopes(['email'], 'all'),
+    (req, res) => res.send('Scope check passed')
+);
+```
+
 ---
 ## Handling Unauthorized Access (401/403) Gracefully
 

package/docs/OIDC_INTEGRATION_GUIDE.md

@@ -7,6 +7,14 @@ This guide explains how to integrate the OIDC authentication methods (`generateA
 - **`oidc-methods.js`** - Ready-to-use OIDC methods (no external dependencies)
 - **`test/oidc-methods.test.js`** - Complete test suite (run with `npm test`)
 
+## Client Prerequisites (Non-Browser Flows)
+
+- `loginWithCredentials(credentials)` is a generic token endpoint helper.
+- If you use it with `grant_type=password`, the Keycloak client must have `Direct Access Grants` enabled.
+- This means the client exchanges user username/password directly with Keycloak token endpoint.
+- In OAuth2 specification terms, this enables `Resource Owner Password Credentials Grant` support for that client.
+- `loginPKCE(credentials)` uses `authorization_code` + `code_verifier` and does not require `Direct Access Grants`.
+
 ## Integration Steps
 
 ### Step 1: Run Tests (Verify Methods Work)

package/index.d.ts

@@ -0,0 +1,125 @@
+import { Request, Response, NextFunction } from 'express';
+
+/**
+ * Main Keycloak middleware adapter for Express applications
+ */
+declare module 'keycloak-express-middleware' {
+  
+  /**
+   * Token claims structure (decoded JWT)
+   */
+  interface TokenClaims {
+    sub?: string;
+    aud?: string[];
+    iss?: string;
+    exp?: number;
+    iat?: number;
+    scope?: string;
+    [key: string]: any;
+  }
+
+  /**
+   * Keycloak adapter instance
+   */
+  interface KeycloakAdapter {
+    config?: any;
+    grant?: any;
+  }
+
+  /**
+   * Scope validation modes
+   */
+  type ScopeMode = 'all' | 'any';
+
+  /**
+   * Main Keycloak class constructor options
+   */
+  interface KeycloakOptions {
+    realm?: string;
+    bearer_only?: boolean;
+    ssl_required?: string;
+    resource?: string;
+    credentials?: {
+      secret?: string;
+    };
+    [key: string]: any;
+  }
+
+  /**
+   * Main Keycloak middleware class
+   */
+  class Keycloak {
+    constructor(options?: KeycloakOptions);
+    
+    // Middleware factory methods
+    middleware(): (req: Request, res: Response, next: NextFunction) => void;
+    protect(spec?: string | boolean | ((req: Request, res: Response) => boolean | string)): (req: Request, res: Response, next: NextFunction) => void;
+    enforcer(spec?: string | ((req: Request, res: Response) => boolean)): (req: Request, res: Response, next: NextFunction) => void;
+    
+    // Login/Logout methods
+    login(): (req: Request, res: Response, next: NextFunction) => void;
+    loginMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
+    logout(): (req: Request, res: Response, next: NextFunction) => void;
+    logoutMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
+    redirectToUserAccountConsole(): (req: Request, res: Response, next: NextFunction) => void;
+    
+    // OIDC methods
+    generateAuthorizationUrl(options: {
+      redirect_uri: string;
+      redirectUri?: string;
+      scope?: string;
+      state?: string;
+    }): { authorization_url: string; code_verifier: string; code_challenge: string };
+    
+    loginWithCredentials(credentials: {
+      username?: string;
+      password?: string;
+      clientId?: string;
+      client_id?: string;
+      clientSecret?: string;
+      client_secret?: string;
+    }): Promise<any>;
+    
+    loginPKCE(options: {
+      code: string;
+      redirect_uri: string;
+      redirectUri?: string;
+      code_verifier: string;
+      codeVerifier?: string;
+    }): Promise<any>;
+    
+    // Scope helpers
+    hasScope(scopeInput: string | string[], requiredScope: string): boolean;
+    hasScopes(scopeInput: string | string[], requiredScopes: string[], mode?: ScopeMode): boolean;
+    getTokenClaims(req: Request): TokenClaims;
+    isAuthenticated(req: Request): boolean;
+    getScopes(scopeInputOrReq: string | string[] | Request): string[];
+    hasScopeFromRequest(req: Request, requiredScope: string): boolean;
+    hasScopesFromRequest(req: Request, requiredScopes: string[], mode?: ScopeMode): boolean;
+    requireScopes(requiredScopes: string[], mode?: ScopeMode): (req: Request, res: Response, next: NextFunction) => void;
+  }
+
+  export default Keycloak;
+  
+  /**
+   * Factory function to create Keycloak instance
+   */
+  function keycloakExpress(options?: KeycloakOptions): Keycloak;
+  
+  export { keycloakExpress };
+}
+
+/**
+ * Express Request extension for Keycloak properties
+ */
+declare global {
+  namespace Express {
+    interface Request {
+      kauth?: {
+        grant?: any;
+      };
+      encodedTokenRole?: string;
+      hasPermission?: (permission: string) => boolean;
+    }
+  }
+}

package/index.js

@@ -863,6 +863,12 @@ class keycloakExpressMiddleware {
      * - client_credentials: Client Credentials Grant
      * - authorization_code: Authorization Code Grant (without PKCE)
      * - refresh_token: Refresh Token Grant
+    *
+    * Client prerequisite note:
+    * - When using `grant_type=password`, Keycloak client must have Direct Access Grants enabled.
+    * - This means the client exchanges user username/password directly with Keycloak token endpoint.
+    * - In OAuth2 terms, this is Resource Owner Password Credentials Grant support for that client.
+    * - This prerequisite does not apply to `client_credentials`, `refresh_token`, or `authorization_code` payloads.
      * 
      * The method automatically appends clientId/clientSecret if configured and not overridden.
      * 
@@ -932,6 +938,10 @@ class keycloakExpressMiddleware {
      * 
      * This method is specialized for the callback route after user login.
      * It exchanges the authorization code (from redirect) + code_verifier for tokens.
+        *
+        * Client prerequisite note:
+        * - PKCE uses `authorization_code` + `code_verifier` and does not require Direct Access Grants.
+        * - Direct Access Grants is only required when using `grant_type=password` (ROPC) in loginWithCredentials.
      * 
      * @param {Object} credentials - Token exchange parameters
      * @param {string} credentials.code - Authorization code (from Keycloak redirect) - REQUIRED
@@ -995,6 +1005,159 @@ class keycloakExpressMiddleware {
         res.redirect(redirectUrl);
     }
 
+    /**
+     * Check whether a scope string (or scope array) contains a specific scope.
+     *
+     * Scope input can come from:
+     * - `req.kauth.grant.access_token.content.scope` (middleware/browser flow)
+     * - `tokenResponse.scope` (loginWithCredentials/loginPKCE response)
+     *
+     * @param {string|string[]} scopeInput - Scope string (space-separated) or scope array.
+     * @param {string} requiredScope - Scope to verify.
+     * @returns {boolean} True if required scope is present, false otherwise.
+     */
+    hasScope(scopeInput, requiredScope){
+        if (!requiredScope || typeof requiredScope !== 'string') return false;
+
+        const scopes = Array.isArray(scopeInput)
+            ? scopeInput
+            : String(scopeInput || '').split(' ');
+
+        return scopes
+            .map((s) => String(s || '').trim())
+            .filter(Boolean)
+            .includes(requiredScope);
+    }
+
+    /**
+     * Check whether a scope input contains all (default) or any required scopes.
+     *
+     * @param {string|string[]} scopeInput - Scope string (space-separated) or scope array.
+     * @param {string|string[]} requiredScopes - One scope or list of scopes to verify.
+     * @param {'all'|'any'} [mode='all'] - `all`: every scope required, `any`: at least one required.
+     * @returns {boolean} Scope check result according to selected mode.
+     */
+    hasScopes(scopeInput, requiredScopes, mode = 'all'){
+        const targets = Array.isArray(requiredScopes) ? requiredScopes : [requiredScopes];
+        const normalizedTargets = targets
+            .map((s) => String(s || '').trim())
+            .filter(Boolean);
+
+        if (normalizedTargets.length === 0) return false;
+
+        if (mode === 'any') {
+            return normalizedTargets.some((scope) => this.hasScope(scopeInput, scope));
+        }
+
+        return normalizedTargets.every((scope) => this.hasScope(scopeInput, scope));
+    }
+
+    /**
+     * Safely read decoded access token claims from an Express request.
+     *
+     * @param {Object} req - Express request object.
+     * @returns {Object} Decoded access token claims, or empty object when unavailable.
+     */
+    getTokenClaims(req){
+        return req?.kauth?.grant?.access_token?.content || {};
+    }
+
+    /**
+     * Check whether request contains a Keycloak-authenticated access token.
+     *
+     * @param {Object} req - Express request object.
+     * @returns {boolean} True when access token is present, false otherwise.
+     */
+    isAuthenticated(req){
+        return !!req?.kauth?.grant?.access_token;
+    }
+
+    /**
+     * Normalize scopes into an array.
+     *
+     * Input accepted:
+     * - space-separated scope string
+     * - scope array
+     * - Express request object (reads `req.kauth.grant.access_token.content.scope`)
+     *
+     * @param {string|string[]|Object} scopeInputOrReq - Scope source string/array or Express request.
+     * @returns {string[]} Normalized scope array.
+     */
+    getScopes(scopeInputOrReq){
+        const looksLikeReq = scopeInputOrReq && typeof scopeInputOrReq === 'object' && ('kauth' in scopeInputOrReq || 'headers' in scopeInputOrReq || 'method' in scopeInputOrReq);
+        const rawScope = looksLikeReq
+            ? this.getTokenClaims(scopeInputOrReq).scope
+            : scopeInputOrReq;
+
+        const scopes = Array.isArray(rawScope)
+            ? rawScope
+            : String(rawScope || '').split(' ');
+
+        return scopes
+            .map((s) => String(s || '').trim())
+            .filter(Boolean);
+    }
+
+    /**
+     * Check scope directly from Express request token claims.
+     *
+     * @param {Object} req - Express request.
+     * @param {string} requiredScope - Scope to verify.
+     * @returns {boolean} True when scope is present.
+     */
+    hasScopeFromRequest(req, requiredScope){
+        return this.hasScope(this.getScopes(req), requiredScope);
+    }
+
+    /**
+     * Check multiple scopes directly from Express request token claims.
+     *
+     * @param {Object} req - Express request.
+     * @param {string|string[]} requiredScopes - Required scope(s).
+     * @param {'all'|'any'} [mode='all'] - Matching mode.
+     * @returns {boolean} Scope check result.
+     */
+    hasScopesFromRequest(req, requiredScopes, mode = 'all'){
+        return this.hasScopes(this.getScopes(req), requiredScopes, mode);
+    }
+
+    /**
+     * Express middleware that enforces required scopes.
+     *
+     * - Calls `next()` when scope check passes.
+     * - Returns 403 response when scope check fails.
+     *
+     * @param {string|string[]} requiredScopes - Scope(s) to enforce.
+     * @param {'all'|'any'} [mode='all'] - Matching mode.
+     * @returns {Function} Express middleware.
+     */
+    requireScopes(requiredScopes, mode = 'all'){
+        return (req, res, next) => {
+            if (this.hasScopesFromRequest(req, requiredScopes, mode)) {
+                return next();
+            }
+
+            const payload = {
+                error: 'forbidden',
+                message: 'Missing required scope(s)',
+                requiredScopes: Array.isArray(requiredScopes) ? requiredScopes : [requiredScopes],
+                mode
+            };
+
+            if (typeof res.status === 'function') {
+                res.status(403);
+            }
+
+            if (typeof res.json === 'function') {
+                return res.json(payload);
+            }
+
+            if (typeof res.send === 'function') {
+                return res.send(payload.message);
+            }
+        };
+    }
+
 
 
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "keycloak-express-middleware",
-  "version": "6.1.2",
+  "version": "6.2.0",
   "description": "Adapter API to integrate Node.js (Express) applications with Keycloak. Provides middleware for authentication, authorization, token validation, and route protection via OpenID Connect.",
   "main": "index.js",
+  "typings": "index.d.ts",
   "exports": {
     ".": {
       "require": "./index.js",
@@ -11,24 +12,12 @@
     }
   },
   "scripts": {
-    "test": "NODE_ENV=test node test/helpers/keycloak-setup.js && npm --prefix test install && npm --prefix test test",
+    "test": "npm --prefix test install && npm --prefix test run setup-keycloak && NODE_PATH=./test/node_modules npm --prefix test test",
     "setup-keycloak": "eval \"$(ssh-agent -s)\" && ssh-add ~/.ssh/id_ed25519 && NODE_ENV=test node test/docker-keycloak/setup-keycloak.js"
   },
   "dependencies": {
-    "@keycloak/keycloak-admin-client": "^26.3.2",
-    "async": "^3.2.6",
-    "body-parser": "^2.2.0",
-    "cookie-parser": "^1.4.7",
-    "debug": "^4.4.1",
-    "express": "^5.1.0",
-    "express-session": "^1.18.1",
-    "jwt-simple": "^0.5.6",
-    "keycloak-connect": "^26.1.1",
-    "moment": "^2.30.1",
-    "morgan": "^1.10.0",
-    "responseinterceptor": "^2.0.2",
-    "serve-favicon": "^2.5.0",
-    "underscore": "^1.13.7"
+    "express-session": "^1.19.0",
+    "keycloak-connect": "^26.1.1"
   },
   "keywords": [
     "keycloak",