ws Token Authentication and Verification

Introduction

Sometimes we need token authentication/verification before WebSocket connection is established. If verification fails, ws connection will not be established. The flow ends at HTTP stage, which effectively reduces malicious long connections.

Framework supports this kind of extension. You can implement it in external-server side.

Usage Scenarios

WebSocket Token is commonly used for identity authentication and authorized access to WebSocket connections. When client attempts to establish a WebSocket connection, server can require a valid token as credential.

WebSocket Token can provide:

• Authentication: by validating token, server determines client identity and whether to allow connection.
• Authorization: token can authorize access to specific resources/operations; server can restrict permissions based on token level.
• Security: token-based authentication/authorization improves WebSocket connection security. Only clients with valid tokens can connect, and only authorized clients can execute corresponding operations.

In short, WebSocket Token is a mechanism for authentication and authorization over WebSocket connections, providing security and permission control.

Example Source Code

see https://github.com/iohao/ionet-examples

path : ionet-cookbook-code

• MyWebSocketVerifyHandler
• WsVerifyApplication
• WsClient

Custom WebSocketVerifyHandler

Now define custom verifier MyWebSocketVerifyHandler by extending WebSocketVerifyHandler and overriding verify.

• code 5: get key:value parameters from params.
• code 11~18: create request and send to logic server.
• code 23: return true means verification passed; return false and framework closes current connection.

public final class MyWebSocketVerifyHandler extends WebSocketVerifyHandler {
    @Override
    protected boolean verify(SocketUserSession userSession, Map<String, String> params) {
        // ws://127.0.0.1:10100/websocket?token=abc&name=aaaa
        String token = params.get("token");
        boolean verifyResult = "abc".equals(token);
        log.info("verify name: {}", params.get("name"));

        if (verifyResult) {
            // Send a login message
            var cmdInfo = HallCmd.of(HallCmd.loginVerify);
            byte[] data = DataCodecManager.getDataCodec().encode(token);

            var message = userSession.ofMessage(cmdInfo);
            message.setData(data);

            // send message to logicServer
            this.convenientCommunication.request(message);
        }

        // Return true means verification passed, return false means the framework will close the connection.
        return verifyResult;
    }
}

tip

userSession: current connection's UserSession.

params: when connection is ws://127.0.0.1:10100/websocket?token=abc&name=aaaa, parameters after ? are stored in map params as k-v, for example:

• token=abc
• name=aaaa

How to Use

Create external server and override WebSocketMicroBootstrapFlow.createVerifyHandler.

• code 6: set custom verifier class.

ExternalServer createExternalServer() {
    var builder = ExternalMapper.builder(ExternalGlobalConfig.externalPort);

    // WebSocketVerifyHandler
    var microBootstrapFlow = new WebSocketMicroBootstrapFlow();
    microBootstrapFlow.verifyHandler = new MyWebSocketVerifyHandler();
    builder.setMicroBootstrapFlow(microBootstrapFlow);

    return builder.build();
}

Test in Simulated Client

• code 7: set WebsocketVerify parameter to test in simulated client.

public final class WsClient {
    static void main() {
        String websocketVerify = "?token=abc&name=aaaa";

        new ClientRunOne()
                ...
                .setWebsocketVerify(websocketVerify)
                .startup();
    }

    ...
}