Setup Access Control

# Setup Access Control

To configure access control for your channel:

> **Note:** You should have a [channel created](https://docs.catalyst.zoho.com/en/cloud-scale/help/data-streams/implementation/create-channel/) before configuring access control. Access control applies only to subscribers. Publishers are authenticated through the Catalyst SDK or the REST API and do not require access control configuration.

1. Select an access control type during channel creation or from the *Access Control* section.

**User Roles**

Use this when subscribers are authenticated users in Catalyst Authentication with predefined roles.

2. Select **User Roles**.
3. Select one or more roles from the dropdown menu.
  ![Select user roles for channel access control](https://catalyst-docs-development.zohostratus.in/images/help/data-streams/user-roles-selection.webp)

4. Click **Create** or **Update**.

Only users belonging to the selected roles can subscribe to the channel. When a role is removed, subscribers with that role lose access immediately. When a role is granted, users with that role can subscribe immediately.

> **Note:** To create new roles, refer to the [Catalyst Authentication User Roles documentation](https://docs.catalyst.zoho.com/en/cloud-scale/help/authentication/user-management/roles/introduction/).

**Custom Logic**

Use this when you need custom authentication logic beyond role-based access (SSO, session-based connections, anonymous users, or custom criteria).

2. Create an Advanced I/O function that validates the subscriber with your own logic and then generates the token pair. The function you select becomes the channel's access control source: token pairs for this channel must be generated from inside it, using a connection name. A token pair requested from any other function or from the REST API is rejected with "Invalid access control source! Kindly request from the configured one!"

```javascript

const { zcAuth } = require('@zcatalyst/auth');
const { DataStreams } = require('@zcatalyst/datastreams');

// Advanced I/O functions receive Node's raw request and response objects,
// so read the JSON body and write the JSON response yourself.
const readJson = (req) => new Promise((resolve, reject) => {
    let raw = '';
    req.on('data', (chunk) => (raw += chunk));
    req.on('end', () => {
        try { resolve(raw ? JSON.parse(raw) : {}); } catch (e) { reject(e); }
    });
});

const sendJson = (res, status, body) => {
    res.writeHead(status, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(body));
};

module.exports = async (req, res) => {
    try {
        const { channelId, connectionName } = await readJson(req);

// Your custom validation logic
        const isAuthorized = await yourCustomValidationLogic(req, connectionName);
        if (!isAuthorized) {
            return sendJson(res, 403, { approved: false, reason: "Unauthorized" });
        }

// Generate the token pair here, in the configured function
        const app = await zcAuth.init(req);
        const datastreams = new DataStreams(app);
        const token = await datastreams.getTokenPair(channelId, { connectionName });
        sendJson(res, 200, { approved: true, token });
    } catch (error) {
        sendJson(res, 500, { error: error.message });
    }
};

```

Your client calls this function to get a token pair, then uses it to open the WebSocket connection. Catalyst does not call the function on its own.

3. Select **Custom Logic**.
4. Select your Advanced I/O function from the dropdown. If the function doesn't exist, click **Create new Advanced I/O function** to create one first.
  ![Select custom logic function for access control](https://catalyst-docs-development.zohostratus.in/images/help/data-streams/custom-logic-function-selection.webp)

5. Click **Create** or **Update**.

> **Note:** Only Advanced I/O functions are supported. Ensure the function is deployed and available in your project before configuring it.

### Manage Subscriber Connections

After access control is configured, navigate to the *Manage Connections* section in the *Access Control* tab to view all subscribers.

![List of subscriber connections in Manage Connections](https://catalyst-docs-development.zohostratus.in/images/help/data-streams/manage-connections-list.webp)

Each connection displays:

<table class="content-table">
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Connection Name**</td>
<td>Unique identifier for the subscriber connection (generated during token pair creation)</td>
</tr>
<tr>
<td>**User Type**</td>
<td>Type of user (App User or Custom User) based on access control configuration</td>
</tr>
<tr>
<td>**Status**</td>
<td>Current connection state: Active, Inactive, or Blocked</td>
</tr>
</tbody>
</table>

**To block a subscriber:**

1. Locate the subscriber connection.
2. Click the **three-dot menu** icon.
3. Select **Block**.
  ![Block subscriber from three-dot menu](https://catalyst-docs-development.zohostratus.in/images/help/data-streams/manage-connections-block-menu.webp)

Blocking terminates the active connection immediately.

**To delete a subscriber connection:**

1. Locate the subscriber connection.
2. Click the **three-dot menu** icon.
3. Select **Delete**.
4. Confirm deletion in the dialog.

To configure access control for your channel:

Note: You should have a channel created before configuring access control. Access control applies only to subscribers. Publishers are authenticated through the Catalyst SDK or the REST API and do not require access control configuration.

Select an access control type during channel creation or from the Access Control section.

User Roles

Use this when subscribers are authenticated users in Catalyst Authentication with predefined roles.

Select User Roles.
Select one or more roles from the dropdown menu.
Click Create or Update.

Note: To create new roles, refer to the Catalyst Authentication User Roles documentation.

Custom Logic

Use this when you need custom authentication logic beyond role-based access (SSO, session-based connections, anonymous users, or custom criteria).

Create an Advanced I/O function that validates the subscriber with your own logic and then generates the token pair. The function you select becomes the channel’s access control source: token pairs for this channel must be generated from inside it, using a connection name. A token pair requested from any other function or from the REST API is rejected with “Invalid access control source! Kindly request from the configured one!”

copy

         const { zcAuth } = require('@zcatalyst/auth');
const { DataStreams } = require('@zcatalyst/datastreams');

// Advanced I/O functions receive Node's raw request and response objects,
// so read the JSON body and write the JSON response yourself.
const readJson = (req) => new Promise((resolve, reject) => {
    let raw = '';
    req.on('data', (chunk) => (raw += chunk));
    req.on('end', () => {
        try { resolve(raw ? JSON.parse(raw) : {}); } catch (e) { reject(e); }
    });
});

const sendJson = (res, status, body) => {
    res.writeHead(status, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(body));
};

module.exports = async (req, res) => {
    try {
        const { channelId, connectionName } = await readJson(req);

        // Your custom validation logic
        const isAuthorized = await yourCustomValidationLogic(req, connectionName);
        if (!isAuthorized) {
            return sendJson(res, 403, { approved: false, reason: "Unauthorized" });
        }

        // Generate the token pair here, in the configured function
        const app = await zcAuth.init(req);
        const datastreams = new DataStreams(app);
        const token = await datastreams.getTokenPair(channelId, { connectionName });
        sendJson(res, 200, { approved: true, token });
    } catch (error) {
        sendJson(res, 500, { error: error.message });
    }
};
    

Your client calls this function to get a token pair, then uses it to open the WebSocket connection. Catalyst does not call the function on its own.

Select Custom Logic.
Select your Advanced I/O function from the dropdown. If the function doesn’t exist, click Create new Advanced I/O function to create one first.
Click Create or Update.

Note: Only Advanced I/O functions are supported. Ensure the function is deployed and available in your project before configuring it.

Manage Subscriber Connections

After access control is configured, navigate to the Manage Connections section in the Access Control tab to view all subscribers.

Each connection displays:

Field	Description
Connection Name	Unique identifier for the subscriber connection (generated during token pair creation)
User Type	Type of user (App User or Custom User) based on access control configuration
Status	Current connection state: Active, Inactive, or Blocked