Authorization

“Authorization in computing is not just about keeping people out. It’s about letting the right people in with precision and discernment.”

Authorization

Overview

To secure your WebSocket server and channels from unauthorized access, you must:

1. Prevent unauthorized users from connecting to the WebSocket server.
2. Prevent unauthorized users from joining channels.

Conveyor uses token-based authorization. You configure a main token on server startup, then issue temporary tokens for client-side connections. The main token never needs to be exposed in your frontend code, helping keep it secure.

1. Setting the Main Token

Specify your main token when initializing the ConveyorServer:

1<?php
2
3include __DIR__ . '/vendor/autoload.php';
4
5use Conveyor\Constants;
6use Conveyor\ConveyorServer;
7
8(new ConveyorServer())
9    ->conveyorOptions([
10        Constants::WEBSOCKET_SERVER_TOKEN => 'my-secure-conveyor-token',
11    ])
12    ->port(8181)
13    ->start();

Clients must include this token in their WebSocket URL (e.g., ws://127.0.0.1:8181/?token=my-secure-conveyor-token), unless you generate a temporary token.

2. Generating a Temporary Token

Instead of exposing the main token in the frontend, request a temporary token from the server. If you're using the Conveyor Laravel Driver, simply call:

1use Kanata\LaravelBroadcaster\Conveyor;
2
3// Token for a basic connection (no channel interaction):
4$tempToken = Conveyor::getToken();
5
6// Token for channel authorization (required for channel operations):
7$tempToken = Conveyor::getToken('my-channel-name');

If you want to do it manually, here is an example:

1curl -X POST \ "http://127.0.0.1:8181/conveyor/auth?token=main-token-here" \ -H "Content-Type: application/json" \ -d '{"channel":"my-channel"}'

Or without channel:

1curl -X POST \ "http://127.0.0.1:8181/conveyor/auth?token=main-token-here" \ -H "Content-Type: application/json" \ -d '{}'

The expected response has this body format:

1{
2    "auth": "your-temp-token"
3}

You can then pass this temporary token to your frontend, where it can be used in the connection URL. Once used, the temporary token is invalidated.

3. Connecting from the Frontend

a) Using a Standard WebSocket

1const ws = new WebSocket('ws://127.0.0.1:8181/?token=my-temporary-conveyor-token');
2
3ws.onopen = () => {
4  // Connect to the channel
5  ws.send(JSON.stringify({
6    action: 'channel-connect',
7    channel: 'my-channel',
8  }));
9
10  // Broadcast a message to "my-channel"
11  ws.send(JSON.stringify({
12    action: 'broadcast-action',
13    data: 'My broadcast message.',
14  }));
15};

b) Using the Conveyor Client

1const connect = () => {
2  const conveyor = new window.Conveyor({
3    protocol: 'ws',
4    uri: '127.0.0.1',
5    port: 8181,
6    channel: 'my-channel',
7    token: 'my-temporary-conveyor-token',
8    onMessage: (msg) => {
9      console.log('Received:', msg);
10    },
11    onReady: () => {
12      console.log('Connected');
13    },
14  });
15};
16
17document.addEventListener("DOMContentLoaded", connect);

Summary

1. Set a main token on the server.
2. Obtain a temporary token from the server (if using the Laravel Driver, call Conveyor::getToken()).
3. Use the temporary token to connect from your frontend, ensuring the main token is never directly exposed.

This token-based approach helps secure both server connections and channel access, preventing unauthorized usage.