WebSocket Authentication Basics

# CHAPTER 11

WebSocket Authentication Basics #

1. Introduction #

2. Learning Objectives #

• Explain why standard HTTP cookie authentication can be tricky with WebSockets.

• Authenticate a WebSocket connection via the initial handshake URI.

• Authenticate a connection via a first-message JSON token.

• Securely reject unauthenticated connections.

3. Beginner-Friendly Explanation #

• HTTP Authentication: Every time you want a drink, you have to show the bartender your ID.

• WebSocket Authentication: You show your ID to the bouncer at the front door (the Handshake). Once you are inside the club, you don't need to show your ID to anyone anymore. The server trusts you for the duration of the connection.

4. Real-World Examples #

• Stock Trading App: The app connects to the WebSocket server. The server verifies the user's JWT (JSON Web Token). Only then does the server start streaming live portfolio data to that specific user.

5. Authentication Strategies #

Strategy 1: Query Parameters (The URI method) Pass the token in the URL itself: ws://server.com?token=abc123xyz

Strategy 2: The Ticket/First-Message Method Connect normally, but the server puts you in a "waiting room". You must immediately send a JSON message containing your token. If the token is valid, the server lets you in. If not, the server closes the connection.

6. Strategy 1: Query Parameters Example #

7. JavaScript Examples (Query Param) #

// Retrieve your auth token from local storage (or wherever you keep it)
const authToken = localStorage.getItem('user_token');

// Append it to the WebSocket URL
const socketUrl = `wss://api.example.com/chat?token=${authToken}`;

const socket = new WebSocket(socketUrl);

socket.onopen = function() {
    console.log("Connected and authenticated!");
};

*Note: The server backend reads the $_GET['token'] during the HTTP Upgrade phase and rejects the handshake if the token is invalid.*

8. Strategy 2: First-Message Example #

const socket = new WebSocket("wss://api.example.com/chat");

socket.onopen = function() {
    // Do NOT allow the user to see the UI yet.
    // Immediately send the authentication payload.
    const authPayload = {
        action: 'authenticate',
        token: localStorage.getItem('user_token')
    };
    
    socket.send(JSON.stringify(authPayload));
};

socket.onmessage = function(event) {
    const data = JSON.parse(event.data);
    
    if (data.status === 'authenticated') {
        console.log("Server accepted our token!");
        // NOW show the chat UI
    } else if (data.status === 'unauthorized') {
        console.error("Auth failed.");
        socket.close();
    }
};

9. PHP Backend Concept #

<?php
// PHP Server Pseudocode
public function onMessage(ConnectionInterface $conn, $msg) {
    $data = json_decode($msg);
    
    // Check if they are authenticated yet
    if (!isset($conn->isAuthenticated) || $conn->isAuthenticated === false) {
        
        if ($data->action === &#039;authenticate' && validateToken($data->token)) {
            $conn->isAuthenticated = true;
            $conn->send(json_encode([&#039;status' => 'authenticated']));
        } else {
            // Bad token, kick them out
            $conn->close(); 
        }
        return; // Stop processing further
    }
    
    // Normal chat logic goes here...
}

10. Best Practices #

• Use Short-Lived Tokens: If you use the Query Parameter method, don't use the user's permanent session token. Generate a temporary "WebSocket Ticket" via an HTTP API that expires in 60 seconds, and pass *that* in the WebSocket URL.

• Enforce WSS: Never send authentication tokens over unencrypted ws://. Always use wss:// to protect tokens from man-in-the-middle attacks.

11. Common Mistakes #

• Relying on HTTP Cookies: While WebSockets *do* send browser cookies during the handshake, relying on them is tricky if your WebSocket server is hosted on a different subdomain (e.g., ws.example.com) than your main website, due to strict browser CORS and SameSite cookie policies.

12. Mini Exercises #

1. 1. Look at the URL structure in Strategy 1. If someone looked over your shoulder and copied that URL, could they connect to your chat? *(Answer: Yes, which is why temporary tickets are preferred over permanent tokens).*

13. Coding Challenges #

14. MCQs with Answers #

15. Interview Questions #

• Q: Explain the "Ticket" or "First-Message" approach to WebSocket authentication.

• Q: Why might using standard browser cookies be difficult for authenticating a WebSocket connection on a separate domain?

16. FAQs #

17. Summary #

18. Next Chapter Recommendation #