keycloak-express-middleware 4.5.1 → 6.0.1

package/README.md

@@ -379,6 +379,113 @@ app.listen(PORT, () => {
 });
 ```
 ---
+
+## Handling Unauthorized Access (401/403) Gracefully
+
+When a user tries to access a protected resource without the proper roles, the `keycloak-express-middleware` may respond with a plain `401` or `403` message containing `access_denied`.  
+While technically correct, this behavior results in a **blank browser page** showing only that message.
+To improve user experience, you can easily intercept these responses and display a custom HTML page or redirect users 
+elsewhere using the [`responseinterceptor`](https://www.npmjs.com/package/responseinterceptor) middleware.
+This allows developers to present a more user-friendly "Access Denied" page or redirect unauthorized users to 
+a login or error page.
+
+> 🛈 Note: In a secure application, users should normally not reach protected routes without authentication.  
+> However, for simplicity or flexibility during development, this interception approach can be convenient.
+
+### Example 1 — Custom Access Denied Page
+
+```js
+import responseinterceptor from 'responseinterceptor';
+import keycloakMiddleware from 'keycloak-express-middleware';
+
+
+function tmpInterceptor(req, respond) {
+    // Handling Unauthorized Access (401/403) Gracefully
+  respond(200, '<h1>Access Denied</h1><p>You are not authorized to view this page.</p>');
+}
+
+// if protectMiddleware('role') return a 403 with keycloak blank page then 
+// interceptByStatusCode Handle Unauthorized Access (401/403) Gracefully
+app.get(
+  '/test403',
+  responseinterceptor.interceptByStatusCode(403, tmpInterceptor),
+  keycloakMiddleware.protectMiddleware('role'),
+  (req, res) => {
+    res.render('welcome');
+  }
+);
+```
+
+### Example 2 — Redirect to a Dedicated Page (Dynamic Redirect)
+
+```js
+function tmpInterceptorDinamic(req, respond) {
+  //your log 
+  switch (req.path) {
+      case '/':
+          respond('/access-denied');        
+          break
+      case '/help':
+          respond('/access-denied-help');
+          break
+      default:
+          respond('/access-denied-default');
+  }
+}
+
+app.get('/access-denied', (req, res) => {
+  res.render('access-denied');
+});
+
+app.get('/access-denied', (req, res) => {
+    res.render('access-denied-help');
+});
+
+app.get('/access-denied', (req, res) => {
+    res.render('access-denied-default');
+});
+
+// if protectMiddleware('role') return a 403 with keycloak blank page then 
+// interceptByStatusCode Handle Unauthorized Access (401/403) Gracefully
+// by user redirection with tmpInterceptorDinamic logic
+app.get(
+  '/test403redirectDynamic',
+  responseinterceptor.interceptByStatusCodeRedirectTo(403, tmpInterceptorDinamic),
+  keycloakMiddleware.protectMiddleware('none'),
+  (req, res) => {
+      res.render('welcome');
+  }
+);
+```
+
+### Example 3 — Static Redirect to a Route
+
+```js
+// if protectMiddleware('role') return a 403 with keycloak blank page then 
+// interceptByStatusCode Handle Unauthorized Access (401/403) Gracefully
+// by user redirection
+app.get(
+  '/test403redirectStatic',
+  responseinterceptor.interceptByStatusCodeRedirectTo(403, '/access-denied'),
+  keycloakMiddleware.protectMiddleware('none'),
+  (req, res) => {
+      res.render('welcome');
+  }
+);
+```
+
+### Summary
+
+| Scenario | Middleware Used | Action |
+|-----------|------------------|---------|
+| Replace response content | `interceptByStatusCode()` | Renders a custom message or template |
+| Redirect dynamically | `interceptByStatusCodeRedirectTo()` + callback | Redirects to a route computed in code |
+| Redirect statically | `interceptByStatusCodeRedirectTo()` + string | Redirects to a predefined route |
+
+
+---
+
+
 ## 🧩 Configuration
 In your Express application:
 ```js
@@ -918,15 +1025,13 @@ app.get('/logout', (req, res) => {
 
 ---
 
-### `redirectToUserAccountConsole(req, res)`
+### `redirectToUserAccountConsole(res)`
 `redirectToUserAccountConsole` Function is not a middleware, but a **classic synchronous function** that redirect
 the users to keycloak Admin console where they can view and manage their personal profile and account settings.
 
-
 **` -- @parameters -- `**
-- **req:** `[required]` Express `Request` object
 - **res:** `[required]` Express `Response` object
-- **redirectTo:** `[required]` URL to redirect the user to after successful logout
+
 
 
 --- Design suggestions ---
@@ -937,28 +1042,27 @@ This way, the app page remains open, and the user can easily return to it after
 Example:
 Suppose that https://auth.example.com/user/account is the endpoint used by the redirectToUserAccountConsole function
 here’s a possible example:
+✅ Usage example:
 ```html
-<a href="https://auth.example.com/user/account" target="_blank">
+<a href="https://auth.example.com/user/account/console" target="_blank">
   Manage my profile
 </a>
 ```
 
-
-The user opens the account console in a new tab, uses it, and then manually returns to your app.
-✅ Simple, no special configuration required.
-
-
-✅ Usage example:
 ```js
 
-app.get('/logout', (req, res) => {
+app.get('/user/account/console', (req, res) => {
     // Any custom logic before logout
-    // ...
-    keycloakAdapter.logout(req, res, "http://localhost:3001/home");
+    keycloakAdapter.redirectToUserAccountConsole(res);
 });
 
 ```
 
+The user opens the account console in a new tab, uses it, and then manually returns to your app.
+✅ Simple, no special configuration required.
+
+---
+
 --- Requirements ---
 - The user must be authenticated with Keycloak and have a valid token in `req.kauth.grant`.
 - The URL specified in `redirectTo` must be present in the `Valid Redirect URIs` in the Keycloak client.

package/index.js

@@ -1274,7 +1274,7 @@ class keycloakExpressMiddleware {
     }
 
 
-    redirectToUserAccountConsole(req,res){
+    redirectToUserAccountConsole(res){
         let redirectUrL=`${this.authServerUrl}/realms/${this.realmName}/account/`
         res.redirect(redirectUrL);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keycloak-express-middleware",
-  "version": "4.5.1",
+  "version": "6.0.1",
   "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": {