keycloak-express-middleware 2.0.3 → 3.0.0

package/README.md

@@ -1,13 +1,11 @@
-# 🔐 Keycloak Adapter API for Node.js (Express)
-
+# 🔐 Keycloak Express middleware for Node.js (Express)
 An adapter API to seamlessly integrate **Node.js Express** applications with **Keycloak** for authentication and authorization using **OpenID Connect (OIDC)**.
+This middleware provides route protection, token validation, user role management. Ideal for securing RESTful services, microservices, Express-based backends, and express or javascript frontends.
+it is based on **'keycloak-connect'**, and **'express-session'**
 
-This middleware provides route protection, token validation, user role management, and easy access to Keycloak-secured APIs. Ideal for securing RESTful services, microservices, and Express-based backends.
-it is based on 'keycloak-connect', 'express-session' and '@keycloak/keycloak-admin-client'
----
 
+---
 ## 📦 Features
-
 - 🔑 OIDC-based authentication with Keycloak
 - 🧾 Access token validation (JWT)
 - 🔐 Route protection via role-based access control
@@ -15,28 +13,19 @@ it is based on 'keycloak-connect', 'express-session' and '@keycloak/keycloak-adm
 - ⚙️ Configurable Keycloak client and realm settings
 - 👤 User info extraction from token
 - 🌍 CORS support and integration with frontend apps (SPA or mobile)
-
 ---
-
 ## 🚀 Installation
-
 ```bash
 npm install keycloak-express-middleware
 ```
-
 Or, if using Yarn:
-
 ```bash
 yarn add keycloak-express-middleware
 ```
-
 ---
-
 ## 🛠️ Get Keycloak Configuration
-
 Copy or Download from keycloak admin page your client configuration `keycloak.json` by visiting 
 the Keycloak Admin Console → clients (left sidebar) → choose your client → Installation → Format Option → Keycloak OIDC JSON → Download
-
 ```json
 {
   "realm": "your-realm",
@@ -49,14 +38,11 @@ the Keycloak Admin Console → clients (left sidebar) → choose your client →
   "confidential-port": 0
 }
 ```
-
 ---
-
 ## 📄 Usage Example
-
 ```js
 const express = require('express');
-const keycloackAdapter = require('keycloak-adapter-api');
+const keycloackAdapter = require('keycloak-express-middleware');
 
 const app = express();
 
@@ -79,12 +65,13 @@ await keycloackAdapter.configure(app,{
     });
 
 
-// Public route
+// -------------- Public route  -----------------------
 app.get('/', (req, res) => {
   res.send('Public route: no authentication required');
 });
 
-/* Protected routes (any authenticated user)   */
+
+/* ############## Protected routes (any authenticated user) ###########  */
 
 // Example of login with keycloackAdapter.login function
 // After login redirect to "/home" 
@@ -183,8 +170,12 @@ app.get('/encodeToken', keycloackAdapter.encodeTokenRole(), (req, res) => {
 
 });
 
-// This section provides examples of how to protect resources based on permissions
-// rather than roles.
+
+// #####################################################################################
+// #   This section provides examples of how to protect resources based on permissions #
+// #   rather than roles.                                                              #                                
+// #####################################################################################
+
 
 // Example of protection with keycloackAdapter.enforcerMiddleware middleware
 // whith a static control string
@@ -255,15 +246,11 @@ app.listen(PORT, () => {
   console.log(`Server running at http://localhost:${PORT}`);
 });
 ```
-
 ---
-
 ## 🧩 Configuration
-
 In your Express application:
-
 ```js
-import keycloakAdapter from 'keycloak-adapter-api';
+import keycloakAdapter from 'keycloak-express-middleware';
 
 // Configure and Initialize Keycloak adapter
 keycloackAdapter.configure(app,{
@@ -282,94 +269,55 @@ keycloackAdapter.configure(app,{
         }
     })
 ```
-
 keycloackAdapter.configure is a configuration function for the Keycloak 
-adapter in an Express application.  
-It must be called at app startup, before defining any protected routes.
+adapter in an Express application. It must be called at app startup, before defining any protected routes.
 It is an async function and returns a promise
 
-Parameters:
-- app: Express application instance (e.g., const app = express();)
--   keyCloakConfig: JSON object containing the Keycloak client configuration.
-     This can be obtained from the Keycloak admin console:
-     Clients → [client name] → Installation → "Keycloak OIDC JSON" → Download
-      Example:
+**` -- @parameters -- `**
+- **app**: `[required]` Express application instance (e.g., const app = express();)
+- **keyCloakConfig:** `[required]`JSON object containing the Keycloak client configuration.  This can be obtained from the Keycloak admin console: Clients → [client name] → Installation → "Keycloak OIDC JSON" → Download
+  Example:   
+  ```js       
     {
-    "realm": "realm-name",
-    "auth-server-url": "https://keycloak.example.com/",
-    "ssl-required": "external",
-    "resource": "client-name",
-    "credentials": { "secret": "secret-code" },
-    "confidential-port": 0
+        "realm": "realm-name",
+        "auth-server-url": "https://keycloak.example.com/",
+        "ssl-required": "external",
+        "resource": "client-name",
+        "credentials": { "secret": "secret-code" },
+        "confidential-port": 0
     }
-- keyCloakOptions: advanced configuration options for the adapter.
-  Main supported options:
-    - session: Express session configuration (as in express-session)
-    - scope: authentication scopes (e.g., 'openid profile email offline_access')
-      Note: to use offline_access, the client must have the option enabled and
-      the user must have the offline_access role.
-    - idpHint: to suggest an identity provider to Keycloak during login
-    - cookies: to enable cookie handling
-    - realmUrl: to override the realm URL
-- adminClientCredentials: [Optional] Advanced configuration for setting up the realm-admin user or client,
-  which will be used as the administrator to manage Keycloak via API.
-  This is required in order to use the administrative functions exposed by this library.
-  If this parameter is not provided, it will not be possible to use the administrative functions of Keycloak
-  exposed by this adapter. In fact, exports.kcAdminClient will be null, so any attempt to call
-  keycloakAdapter.kcAdminClient will result in a runtime error due to access on an undefined object
-  Main supported options:
-    - realmName: [Optional] A String that specifies the realm to authenticate against, if different from the "keyCloakConfig.realm" parameter.
-      If you intend to use Keycloak administrator credentials, this should be set to 'master'.
-    - scope: [Optional] A string that specifies The OAuth2 scope requested during authentication (optional).
-      Typically, not required for administrative clients. example:openid profile
-    - requestOptions: [Optional] JSON parameters to configure HTTP requests (such as custom headers, timeouts, etc.).
-      It is compatible with the Fetch API standard. Fetch request options
-      https://developer.mozilla.org/en-US/docs/Web/API/fetch#options
-    - username: [Optional] string username. Required when using the password grant type.
-    - password: [Optional] string password. Required when using the password grant type.
-    - grantType: The OAuth2 grant type used for authentication.
-      Possible values: 'password', 'client_credentials', 'refresh_token', etc.
-    - clientId: string containing the client ID configured in Keycloak. Required for all grant types.
-    - clientSecret: [Optional] string containing the client secret of the client. Required for client_credentials or confidential clients.
-    - totp: string for Time-based One-Time Password (TOTP) for multifactor authentication (MFA), if enabled for the user.
-    - offlineToken: [Optional] boolean value. If true, requests an offline token (used for long-lived refresh tokens). Default is false.
-    - refreshToken: [Optional] string containing a valid refresh token to request a new access token when using the refresh_token grant type.
+  ```
+- **keyCloakOptions**: `[required]` advanced configuration options for the adapter. Main supported options:
+  - **session:** Express session configuration (as in express-session)
+  - **scope:** authentication scopes (e.g., 'openid profile email offline_access') **Note:** to use offline_access, the client must have the option enabled and the user must have the offline_access role.
+  - **idpHint:** to suggest an identity provider to Keycloak during login
+  - **cookies:** to enable cookie handling
+  - **realmUrl:** to override the realm URL
 ---
-
 ## 🔧 Available Middlewares
-
 ### `underKeycloakProtection(callback) - deprecated - ` 
-@deprecated. Use the `configure` Method with `await keycloakAdapter.configure(...)`,
-then define your resources as you normally would in Express:
+**@deprecated Method**. Use the `configure` Method with await keycloakAdapter.configure(...)`, then define your resources as you normally would in Express:
 ```js
     await keycloakAdapter.configure(config_Parameters);
     
-    // all your routes
+    // Define all your routes here
 
     app.get('/my-route', handler);
 ```
-
-Alternatively, if you prefer to define your resources inside a container after configuration,
-you can use the `then` syntax:
+Alternatively, if you prefer to define your resources inside a container after configuration, you can use the `then` syntax:
 ```js
     keycloakAdapter.configure(configParameters).then(() => {
-        // Define all your routes here
+        // Define all your routes to protect here
         app.get('/my-route', handler);
     });
 ```
+This Method is deprecated and will be removed in future versions. It must be called **after** Keycloak has been configured with `configure()`.
+The routes declared inside the provided callback will be protected and will have access to authentication/authorization features managed by Keycloak.
 
-This Method is deprecated and will be removed in future versions.
-
-Method to define Express routes that must be protected by Keycloak.
-
-This method must be called **after** Keycloak has been configured with `configure()`.
-The routes declared inside the provided callback will be protected and will have access
-to authentication/authorization features managed by Keycloak.
-
-📌 Public (unprotected) routes should be declared **before** calling this method.
+📌 Public (unprotected) routes should be declared **before** calling this method. 
 
-@param {Function} callback - A function that defines all routes to be protected.
-It must contain exclusively routes requiring authentication.
+**` -- @parameters -- `** 
+- **{Function} callback:** `[required]` A function that defines all routes to be protected. It must contain exclusively routes requiring authentication.
 
 ✅ Usage example:
 ```js
@@ -396,30 +344,25 @@ keycloakAdapter.underKeycloakProtection(() => {
     });
 });
 ```
-
+---
 ### `protectMiddleware([conditions])`
-Middleware to protect Express routes based on authentication and, optionally,
-authorization via Keycloak roles.
+Middleware to protect Express routes based on authentication and, optionally, authorization via Keycloak roles. 
+Allows restricting access to a resource only to authenticated users or to those possessing specific roles in the realm or in a Keycloak client.
 
-Allows restricting access to a resource only to authenticated users or
-to those possessing specific roles in the realm or in a Keycloak client.
-
-@param {string|function} [conditions]
-- If a string, specifies one or more required roles, using the syntax:
+**` -- @parameters -- `**
+- **conditions**: `[optional]` An array of strings each specifying one or more required roles; or a function executing custom code performing an access role verification 
+  - As array of strings: specifies one or more required roles, using the syntax: 
     - 'role'              → client role in the configured client (e.g., 'admin')
     - 'clientid:role'     → client role of a specific client (e.g., 'myclient:editor')
     - 'realm:role'        → realm role (e.g., 'realm:superuser')
-  - If a function, receives (token, req) and must return true or false synchronously.
-    This function enables custom authorization logic.
-    - The `token` object passed to the authorization function exposes methods such as:
-      - token.hasRole('admin')               // client role in configured client
-      - token.hasRole('realm:superuser')     // realm role
-      - token.hasRole('my-client:editor')    // client role of a specific client
-      - token.hasResourceRole('editor', 'my-client-id') // equivalent to hasRole('my-client:editor')
-
+  - As a function: receives (token, req) and must return true or false synchronously. This function enables custom authorization logic. The `token` object passed to the authorization function exposes methods such as:
+    - token.hasRole('admin')               // client role in configured client
+    - token.hasRole('realm:superuser')     // realm role
+    - token.hasRole('my-client:editor')    // client role of a specific client
+    - token.hasResourceRole('editor', 'my-client-id') // equivalent to hasRole('my-client:editor')
     The authorization function must be synchronous and return true (allow access) or false (deny access).
 
-@returns {Function} Express middleware to protect the route.
+**` -- @returns -- `**  It return a function as an Express middleware to protect the route.
 
 ✅ Usage example:
 ```js
@@ -452,13 +395,10 @@ app.get('/custom', keycloakAdapter.protectMiddleware((token, req) => {
 }), (req, res) => {
     res.send('Access granted by custom authorization function.');
 });
-
 ```
-
-
+---
 ### `customProtectMiddleware(fn)`
 Middleware similar to `protectMiddleware` but with dynamic role checking via a function.
-
 Unlike `protectMiddleware`, which accepts a string expressing the role or a control function
 that works on the token, this middleware accepts a function that receives the Express
 request and response objects `req` and `res` and must return a string representing the role control string.
@@ -466,15 +406,12 @@ request and response objects `req` and `res` and must return a string representi
 This is useful for parametric resources where the role control string must be dynamically generated based on the request,
 for example, based on URL parameters or query strings.
 
-Note: this function **does not** access or parse the token, nor performs any checks other than the role,
-so it cannot be used for complex logic depending on request properties other than the role
-(e.g., client IP, custom headers, etc.).
+**Note:** this function **does not** access or parse the token, nor performs any checks other than the role,
+so it cannot be used for complex logic depending on request properties other than the role (e.g., client IP, custom headers, etc.).
 The function's sole task is to generate the role control string.
 
---- Parameters ---
-
-@param {function} customFunction - function that receives (req, res) and returns a string
-with the role control string to pass to Keycloak.
+**` -- @parameters -- `**
+- **fn:** `[required]` Custom function that receives (req, res) and returns a string with the role control string to pass to Keycloak.
 
 ✅ Usage example:
 ```js
@@ -486,11 +423,10 @@ app.get('/custom/:id', keycloakAdapter.customProtectMiddleware((req) => {
     res.send(`Access granted to users with role 'clientRole${req.params.id}'`);
 });
 ```
-
-
+---
 ### `enforcerMiddleware(conditions, options)`
-`enforcerMiddleware` is a middleware to enable permission checks
-based on resources and policies defined in Keycloak Authorization Services (UMA 2.0-based).
+`enforcerMiddleware` is a middleware to enable permission checks based on resources and policies
+defined in Keycloak Authorization Services (UMA 2.0-based).
 
 Unlike `protectMiddleware` and similar, which only verify authentication or roles,
 `enforcerMiddleware` allows checking if the user has permission to access
@@ -499,20 +435,18 @@ a specific protected resource through flexible and dynamic policies.
 Useful in contexts where resources are registered in Keycloak (such as documents, instances, dynamic entities) and
 protected by flexible policies.
 
---- Parameters ---
-
-@param {string|function} conditions
-- string containing the name of the resource or permission to check
-- custom check function with signature:
-  function(token, req, callback)
-    - token: decoded Keycloak token
-    - req: Express request
-    - callback(boolean): invoke with true if authorized, false otherwise
-
-@param {object} [options] (optional)
-- response_mode: 'permissions' (default) or 'token'
-- claims: object with claim info for dynamic policies (e.g. owner id matching)
-- resource_server_id: resource client id (default: current client)
+**` -- @parameters -- `**
+- **conditions:** a check control string or function
+  - ***As a string:*** contain the name of the resource or permission to check
+  - ***as a function:*** custom check function with signature:
+    ***`function(token, req, callback)`***
+      - token: decoded Keycloak token
+      - req: Express request
+      - callback(boolean): invoke with true if authorized, false otherwise 
+- **options:**: parameter provided as a JSON object that accepts the following filter:
+  - response_mode: 'permissions' (default) or 'token'
+  - claims: object with claim info for dynamic policies (e.g. owner id matching)
+  - resource_server_id: resource client id (default: current client)
 
 --- How it works ---
 - If conditions is a function, it is used for custom checks with callback.
@@ -562,7 +496,7 @@ app.get('/onlyAdminrouteByfunction', keycloakAdapter.enforcerMiddleware(function
     res.send('You are an authorized admin or viewer (custom check)');
 });
 ```
-
+---
 ### `customEnforcerMiddleware(fn, options)`
 `customEnforcerMiddleware` is a middleware for permission checks based on resources and policies
 defined in Keycloak Authorization Services (UMA 2.0), using dynamic permission strings.
@@ -571,23 +505,20 @@ This middleware is similar to `enforcerMiddleware`, but takes a function
 `customFunction(req, res)` as a parameter, which must dynamically return
 the permission/resource string to be checked.
 
---- Parameters ---
-
-@param {function} customFunction
-Function that receives `req` and `res` and returns the control string for Keycloak.
-Example:
-```js
-function customFunction(req, res) {
-    // Your function logic
-    return req.params.permission;
-}
-```
+**` -- @parameters -- `**
+- **fn:**`[required]` custom function that receives `req` and `res` and returns the control string for Keycloak.
+    As example:
+    ```js
+    function customFunction(req, res) {
+        // Your function logic
+        return req.params.permission;
+    }
+    ```
 
-@param {object} [options] (optional)
-Additional options passed to `keycloak.enforcer()`, including:
-    - response_mode: 'permissions' (default) or 'token'
-    - claims: object with claim info for dynamic policies (e.g., owner ID)
-    - resource_server_id: string representing the resource client ID (default: current client)
+- **options:** `[optional]` Additional options passed to `keycloak.enforcer()`, including:
+  - **response_mode:** 'permissions' (default) or 'token'
+  - **claims:** object with claim info for dynamic policies (e.g., owner ID)
+  - **resource_server_id:** string representing the resource client ID (default: current client)
 
 --- response_mode options ---
 1) 'permissions' (default)
@@ -619,11 +550,12 @@ const tmpFunctionEnforce = function(req, res) {
 };
 
 app.get('/onlyAdminrouteByfunction/:permission', keycloakAdapter.customEnforcerMiddleware(tmpFunctionEnforce), (req, res) => {
+    console.log("token permissions:", req.permissions);    
     res.send('You are an authorized user with dynamic permission: ' + req.params.permission);
 });
 
 ```
-
+---
 ### `encodeTokenRole()`
 `encodeTokenRole` is a middleware that decodes the Keycloak token and adds it
 to the Express request as `req.encodedTokenRole`.
@@ -656,7 +588,7 @@ app.get('/encodeToken', keycloakAdapter.encodeTokenRole(), (req, res) => {
 });
 
 ```
-
+---
 ### `encodeTokenPermission()`
 `encodeTokenPermission` ia s Middleware whose sole purpose is to decode the access token present in the request
 and add to the `req` object a property called `encodedTokenPermission` containing the token's permissions.
@@ -672,12 +604,8 @@ It is particularly useful when:
 
 --- Additions to `req` ---
 
-After applying the middleware, `req` contains:
-- @property {Object} req.encodedTokenPermission
-An object exposing the method:
-    - hasPermission(permission: string, callback: function(boolean))
-      Checks whether the token contains the specified permission.
-      The callback receives `true` if the permission is present, `false` otherwise.
+After applying the middleware, `req` contains the property **`encodedTokenPermission`** as an object exposing the method:
+- hasPermission(permission: string, callback: function(boolean)) :Checks whether the token contains the specified permission. The callback receives `true` if the permission is present, `false` otherwise.
 
 ✅ Usage example:
 ```js
@@ -694,7 +622,7 @@ app.get('/encodeTokenPermission',
     });
 
 ```
-
+---
 ### `loginMiddleware(redirectTo)`
 `loginMiddleware` is a Middleware used to **force user authentication** via Keycloak.
 
@@ -709,9 +637,8 @@ It is particularly useful when you want to:
 2. If authentication fails or is denied, the user is redirected according to Keycloak's configured settings.
 3. If authentication is successful, the user is redirected to 'redirectTo' (usually `/home`, `/dashboard`, etc.).
 
---- Parameters ---
-
-@param {string} redirectTo - URL to redirect the user to after login.
+**` -- @parameters -- `**
+- **redirectTo**: `[required]` URL to redirect the user to after login.
 
 --- Warning ---
 
@@ -727,8 +654,7 @@ app.get('/loginMiddleware', keycloakAdapter.loginMiddleware("/home"), (req, res)
 });
 
 ```
-
-
+---
 ### `logoutMiddleware(redirectTo)`
 `logoutMiddleware` Middleware is used to **force user logout**, removing the local session
 and redirecting the user to Keycloak's logout endpoint according to its configuration.
@@ -744,9 +670,8 @@ It is useful when:
 3. **Destroys the local Express session** (e.g., cookies, user data).
 4. Redirects the user to the Keycloak logout URL, which in turn redirects to the provided URL.
 
---- Parameters ---
-
-@param {string} redirectTo - URL to which the user will be redirected after complete logout.
+**` -- @parameters -- `**
+- **redirectTo**: `[required]` URL to which the user will be redirected after complete logout.
 
 ✅ Usage example:
 ```js
@@ -757,7 +682,6 @@ app.get('/logoutMiddleware', keycloakAdapter.logoutMiddleware("http://localhost:
     });
 
 ```
-
 --- Note ---
 - The middleware **never executes the route callback**, as it fully handles the response.
 - The `redirectTo` parameter must match a **valid redirect URI** configured in Keycloak for the client.
@@ -768,7 +692,6 @@ app.get('/logoutMiddleware', keycloakAdapter.logoutMiddleware("http://localhost:
 
 
 ## 🔧 Available Functions
-
 ### `login(req, res, redirectTo)`
 `login` Function not a middleware, but a **classic synchronous function** that forces user authentication
 via Keycloak and, if the user is not authenticated, redirects them to the login page.
@@ -779,11 +702,10 @@ After successful login, the user is redirected to the URL specified in the `redi
 - `login` instead is a function **that can be manually called inside the route handler**,
   offering **greater control** over when and how login is enforced.
 
---- Parameters ---
-
-- @param {Object} req - Express `Request` object
-- @param {Object} res - Express `Response` object
-- @param {string} redirectTo - URL to redirect the user to after successful login
+**` -- @parameters -- `**
+- **req:** `[required]` Express `Request` object
+- **res:** `[required]` Express `Response` object
+- **redirectTo:** `[required]` URL to redirect the user to after successful login
 
 --- Behavior ---
 1. Attempts to protect the request using `keycloak.protect()`.
@@ -808,7 +730,7 @@ app.get('/login', (req, res) => {
 
 --- Requirements ---
 - `Valid Redirect URIs` must include the URL passed to `redirectTo`.
-
+---
 ### `logout(req, res, redirectTo)`
 `logout` Function is not a middleware, but a **classic synchronous function** that forces the user to logout
 via Keycloak. In addition to terminating the current session (if any), it generates the Keycloak
@@ -819,10 +741,11 @@ logout URL and redirects the user's browser to that address.
 - `logout` instead is a function **to be called inside the route**, useful for handling logout
   **conditionally** or within more complex logic.
 
---- Parameters ---
-- @param {Object} req - Express `Request` object
-- @param {Object} res - Express `Response` object
-- @param {string} redirectTo - URL to redirect the user after logout
+**` -- @parameters -- `**
+- **req:** `[required]` Express `Request` object
+- **res:** `[required]` Express `Response` object
+- **redirectTo:** `[required]` URL to redirect the user to after successful logout
+
 
 --- Behavior ---
 1. Retrieves the `id_token` from the current user's Keycloak token (if present).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keycloak-express-middleware",
-  "version": "2.0.3",
+  "version": "3.0.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",
   "scripts": {