Enforce single user sessions with OutSystems and WebSockets

When applications handle sensitive data and critical business processes, managing user sessions is absolutely crucial. Imagine a financial platform or an enterprise system where a user could be logged in from multiple devices simultaneously. This is a recipe for potential security headaches and data inconsistencies.

That's why implementing a single-user session policy is so vital for applications demanding strict access control. It means if a user logs in from a new device or browser, all their other existing sessions are immediately terminated, ensuring security, data integrity, and a seamless user experience.

But how do you achieve this "one user, one session" magic without making your development team tear their hair out? Enter WebSockets, a game-changer for real-time communication, and OutSystems, your rapid application development partner.

Why WebSockets? The real-time advantage

Traditional web applications often rely on HTTP-based authentication, which, while robust, isn't inherently designed for instant, real-time communication. This makes detecting and terminating outdated sessions a bit clunky.

WebSockets, on the other hand, provides a persistent, real-time communication channel directly between your server and connected clients. It’s like a dedicated phone line that stays open, allowing for instant communication. This capability is exactly what we need to detect and terminate outdated sessions instantly, making the single-user session policy far more effective and responsive.

OutSystems and WebSockets: A powerful duo

So, how does OutSystems help you leverage this real-time power? We've got you covered! You can implement a robust single-user session system within your OutSystems applications.

At a high level, the setup involves a WebSocket server (often running on Node.js using socket.io) that exposes a REST API. Your OutSystems application servers can then make POST requests to this API to notify the WebSocket server about login events. Meanwhile, the client (your user's browser) also connects to the same WebSocket server and listens for events.

To make this even easier, OutSystems provides components on the Forge (our public repository of reusable components) that streamline this process:

• WebSockets Refresh Reactive: This component handles the server-side logic to notify the WebSockets server and the client-side logic to listen for events.
• Single User Session Enforcer: This component encapsulates the core logic to manage the single user session and trigger logouts for older sessions.

How it works: A quick peek at the flow

Let's walk through the basic flow to understand how a single-user session is enforced.

First Login

When a user logs into your OutSystems application for the first time:

1. Client-side initialization: The browser-based client logic establishes a connection to the WebSocket server, joining a specific "room" (which can be tied to the user's identifier).
2. Server-side notification: The server-side login action in your OutSystems app triggers a POST request to the WebSocket server with necessary information like the room ID and an authentication key.
3. WebSocket server action: The WebSocket server receives this request. Since this is the first active session for that user in that specific "room," no events are propagated to other listeners because there aren't any yet.

Subsequent Login (New Session)

Now, if that same user logs in from a new browser or device:

1. New client connection: The new client also connects to the WebSocket server, joining the same specific room associated with the user.
2. New server-side notification: Just like before, the server-side login action triggers another POST request to the WebSocket server.
3. The "enforcement" moment: This is where the magic happens! The WebSocket server receives the request and, recognizing that there's already an active listener (the previous session) in that room, it propagates an event to all existing listeners in that room, except the sender (the new session). This event signals the older session(s) to terminate.

The backbone: your WebSocket server configuration

For the WebSocket server (running on Node.js, typically), you'll need to configure it to be reachable by all your OutSystems application servers. A crucial part of this is the config.json file, which defines essential settings such as:

• port: The TCP port where your WebSocket server will listen for connections.
• ipaddr: The IP address of the WebSocket server that your OutSystems servers will connect to.
• authkey: A key used by the WebSocket server to authenticate incoming POST requests, ensuring only authorized sources can send notifications.

For example, a config.json might look something like this:

None
{
  "port": 8080,
  "ipaddr": "10.112.104.13",
  "authkey": "HknYh/u762yhdi<4"
}

The WebSocket server's REST API expects a JSON payload for notifications, typically including the room (e.g., the user's ID for specific session enforcement) and the key (matching your authkey).

What's next? Implementing the solution!

Understanding the "why" and the "what" of single-user sessions with WebSockets and OutSystems is a great start! In this article, we've explored the importance of this policy, how WebSockets provide the real-time foundation, and the high-level flow of how it all ties together.

Now, it's time to roll up our sleeves and get into the practical "how-to" steps to implement this robust security measure. We'll walk through leveraging specific OutSystems Forge components and configuring your environment to ensure only one active session per user.

Essential prerequisite: Your WebSocket server configuration

Before we integrate with OutSystems, let's confirm the setup of your WebSocket server. This server, typically running on Node.js with socket.io, needs to be installed and running on a machine accessible by all your OutSystems application servers.

A key part of this setup is the config.json file, which defines how your WebSocket server operates and communicates. It specifies crucial details:

• port: The TCP port where your WebSocket server will listen for incoming connections.
• ipaddr: The IP address of the WebSocket server that your OutSystems application servers will connect to.
• authkey: A vital security measure! This key is used by the WebSocket server to authenticate all incoming POST requests, ensuring that only authorized sources can send notifications to it.

Here’s an example of what your config.json might look like:

JSON
{
  "port": 8080,
  "ipaddr": "10.112.104.13",
  "authkey": "HknYh/u762yhdi<4"
}

Remember, the WebSocket server's REST API expects a JSON payload for notifications from your OutSystems app, which will include a room identifier (often the user ID for single-user enforcement) and a key that must match your authkey.

Implementing single user session with OutSystems Forge components

The OutSystems Forge provides two fantastic components that streamline this entire process: Websocket Refresh Reactive and Single User Session Enforcer.

Step 1: Install the components

Your first task is to install both components into your OutSystems environment:

1. Install WebSockets Refresh Reactive: This component handles both the server-side logic (to notify the WebSocket server about login events) and the client-side logic (to listen for events from the WebSocket server).
2. Install Single User Session Enforcer: This component encapsulates the core logic to manage the single user session, effectively forcing a logout on older, outdated sessions.

Step 2: Add the AutoLogout block to your layouts

Once the components are installed, you need to integrate the provided UI block into your application.

1. Navigate to your application module that contains the common layouts used across your app(s) (e.g., myapp_th for a theme module).
2. Consume the AutoLogout block from the ForceLogout_Pat module (which is part of the Single User Session Enforcer component
   
3. Add the AutoLogout block to all necessary Layout blocks within your application. This ensures that the client-side session management logic is present on every screen your users access.
   
4. Set up the handler for the SessionExpired event: In the AutoLogout block’s properties, map the SessionExpired event to a client action. The recommended client action is AutoLogoutSessionExpired.
   
5. Call DoLogout within AutoLogoutSessionExpired: Inside the AutoLogoutSessionExpired client action, make sure to call the DoLogout server action. This action will effectively terminate the user's session when the SessionExpired event is triggered by the WebSocket server. You can also add additional logic here, like displaying a notification pop-up to the user, as demonstrated in the demo app.
   
   
   
   
   

Step 3: Set site properties

Configuration is key! You need to set specific Site Properties in Service Center for both installed modules.

1. For WebSocketsRefreshReactive_pat module: Go to Service Center, navigate to the WebSocketsRefreshReactive_Pat module, and then to its "Site Properties" tab. Here, you will set the appropriate values for connection details, typically including the WebSocket server's IP address and port, and the authentication key from your config.json.
2. For ForceLogout_Pat module: Similarly, go to the ForceLogout_Pat module in Service Center. Set the proper value for the ParameterName site property. This parameter typically dictates which user identifier is used to create the "room" on the WebSocket server (for example, UserId, Username).

Step 4: Test the solution!

Now for the moment of truth! Testing is crucial to validate that your single-user session enforcement is working as expected.

1. First login and validation: Log in to your application from one browser. Open your browser's developer tools (usually F12). You should be able to validate that you are receiving "heartbeats" from the WebSocket server, indicating a live, persistent connection. You should also ensure you don't see any connection errors.
2. Second login and enforcement: Without logging out of the first session, open a new browser or incognito window and log in to the same application with the same user credentials.
3. Observe termination: Go back to your original browser session. You should observe that this session is immediately terminated or logged out. The AutoLogout block will have received the notification from the WebSocket server and triggered the logout flow.

This confirms that your system effectively enforces a single active session per user, boosting your application's security and data integrity!

What's next? Continuous improvement!

You've now successfully implemented a robust single-user session enforcement system in your OutSystems application using WebSockets. This capability is invaluable for applications requiring stringent security and controlled access, ensuring that sensitive data remains protected and user experiences are streamlined.

Keep an eye on the OutSystems Forge for updates to these components and explore other ways to enhance your application's security and real-time capabilities. Happy coding!