---
title: "Configure ABAC"
slug: "configure-abac"
tags: ["Defense"]
updated: 2026-08-31T15:51:29Z
published: 2026-08-31T15:51:29Z
canonical: "docs.rocket.chat/configure-abac"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure ABAC

![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/Defense.svg)

[Attribute-Based Access Control (ABAC)](/v1/docs/attribute-based-access-control-abac) enables fine-grained authorization by evaluating user attributes, directory data, and room properties when determining access.

This guide walks through configuring ABAC in your Rocket.Chat workspace, from enabling the feature to selecting a Policy Decision Point (PDP), syncing LDAP attributes, and optionally connecting an external Virtru PDP.

## Prerequisites

Ensure the following requirements are met before configuring ABAC:

1. **License:** [Defense](/v1/docs/our-plans#defense-plan) subscription.
2. **Directory service:** [LDAP](/v1/docs/ldap) must be configured and reachable.
3. **Supported rooms:** ABAC applies only to **private channels and private teams.**
4. **Permissions:** Administrators require the **Manage ABAC configuration** permission to access the ABAC admin section. Each ABAC admin tab is gated by an additional per-tab permission:

| Permission | Grants access to |
| --- | --- |
| Manage ABAC settings | The [**Settings**](/v1/docs/configure-abac#core-settings) tab |
| Manage ABAC room attributes | The [**Room Attributes**](/v1/docs/manage-abac-rooms-and-attributes#manage-room-attributes) tab |
| Manage ABAC rooms | The [**Rooms**](/v1/docs/manage-abac-rooms-and-attributes#manage-abac-rooms) tab |
| View ABAC audit log | The [**Logs**](/v1/docs/manage-abac-rooms-and-attributes#abac-logs-and-audit-trail) tab |

To assign these permissions, navigate to **Manage → Workspace → Permissions** and edit the relevant role.

---

## Access ABAC settings

To open the ABAC configuration page, navigate to **Manage → Workspace → Attribute-Based Access Control → Settings**. This is the recommended entry point, as it groups all ABAC controls (Settings, Room Attributes, Rooms, and Logs) in one place.

> [!WARNING]
> The same settings are also available from **Manage → Workspace → Settings → General → ABAC**. Both locations point to the same underlying settings and have the same effect.

The **Settings** tab groups all workspace-level ABAC controls into three areas:

- [**Core settings**](/v1/docs/configure-abac#core-settings): Enable ABAC, select a Policy Decision Point, configure display and caching behavior.
- [**Classification banners:**](/v1/docs/configure-abac#classification-banners) Display classification markings above the room header in ABAC-managed rooms.
- [**Sync ABAC Attributes**](/v1/docs/configure-abac#sync-abac-attributes): Control how user attributes are synchronized from LDAP.
- [**Virtru PDP Configuration**](/v1/docs/configure-abac#configure-virtru-pdp): Connect an external Virtru Policy Decision Point (optional).

---

## Core settings

Configure the following settings to control the foundational behavior of ABAC in your workspace:

| **Setting** | Description |
| --- | --- |
| **Enable ABAC** | Turn on the **Enable Attribute Based Access Control (ABAC)** toggle to activate attribute-based authorization across the workspace. Once enabled: - ABAC policies are enforced in all supported rooms. - User attributes are synchronized through LDAP. - The Room Attributes, Rooms, and Logs tabs become active. |
| **Policy Decision Point (PDP)** | A Policy Decision Point is the engine that evaluates access requests using user and room attributes. Select one of the following options: - **Local (default)**: Access decisions are evaluated inside Rocket.Chat using LDAP-synchronized attributes. No external system is required. - **Virtru**: Access decisions are delegated to an external Virtru PDP for centralized attribute management. Requires additional configuration. Selecting **Virtru** enables the [**Virtru PDP Configuration** section](/v1/docs/configure-abac#configure-virtru-pdp) further down the page. |
| **Attribute store** | Select where assignable room attributes come from. This setting appears **only** when the Policy Decision Point is set to Virtru. Switching the attribute store permanently clears all existing room attribute assignments. See the [Attribute store](/v1/docs/configure-abac#attribute-store) section for more details. |
| **Show ABAC attributes in rooms** | Enable this option to display each room's assigned ABAC attributes in its contextual bar. This allows room admins to verify enforcement rules without leaving the room view. |
| **ABAC Cache Decision Time** | Set how long access decisions are cached before re-evaluation. The default is **300** seconds. Higher values reduce load on the PDP but delay the effect of attribute changes. Set to **0** to disable caching entirely (every access request is re-evaluated). |

---

## Classification banners

Classification banners display a colored strip above the room header in ABAC-managed rooms, showing classification markings (such as classification level, need-to-know compartments, and releasability) to every member of the room. Banners are computed from the room's ABAC attributes and a JSON configuration, and update live when either changes, no reload or restart required.

| Settings | Description |
| --- | --- |
| **Enable classification banners** | Show a classification banner in rooms managed by ABAC. |
| **Classification banners configuration (JSON)** | A JSON document describing which room attributes appear in the banner, their labels and colors. |

Each attribute entry's `source` is the key of a room ABAC attribute (created on the Room Attributes tab); when a room carries values for it, the banner renders the mapped labels. One attribute drives the banner color, ranked most restrictive first. Three banner styles are supported: `classic`, `segmented`, and `edge`.

Use the [classification banner builder](https://rocketchat.github.io/abac-banner-builder/) to compose and validate the configuration with a live preview, load the complete example configuration, and view the full schema reference. JSON syntax is validated on save; the builder validates the full configuration contract.

> [!WARNING]
> The configuration is a public setting synced to every logged-in client, any logged-in user can read the full configuration, including all attribute keys and label mappings. Do not include information in it that workspace members shouldn't see.

---

## Sync ABAC Attributes

This section controls how Rocket.Chat pulls user attributes from your LDAP directory and maps them to ABAC attributes used in access decisions. Expand the **Sync ABAC Attributes section** on the Settings tab to configure the options below.

| **Setting** | Description |
| --- | --- |
| **ABAC Attributes Background Sync** | Enable this toggle to run a dedicated background process that continuously synchronizes user ABAC attributes from LDAP. This ensures LDAP updates are reflected in ABAC access decisions with minimal delay. |
| **ABAC Attributes Background Sync Interval** | Defines how frequently the background sync runs, using a cron expression. For example: - `0 0 * * *`: once per day at midnight - `*/15 * * * *`: every 15 minutes Adjust based on how often attributes change in your LDAP directory. |
| **ABAC Attribute Mapping** | Defines which LDAP attributes are synchronized as ABAC attributes. Enter a JSON object where: - **Key**: LDAP attribute name - **Value**: ABAC attribute name stored in Rocket.Chat Example: ```json { "departmentNumber": "department", "employeeType": "accessLevel", "destinationIndicator": "country" } ``` This configuration maps: - `departmentNumber` → `department` - `employeeType` → `accessLevel` - `destinationIndicator` → `country` |

After saving the mapping, click the **Sync Now** button in the top-right corner of the ABAC settings page to immediately synchronize ABAC attributes from LDAP, without waiting for the next scheduled background sync. Use this when:

- You have just updated the ABAC Attribute Mapping and want changes applied right away.
- A user's LDAP attributes have changed and you want the update reflected immediately.
- You are troubleshooting attribute sync issues.

> [!WARNING]
> Notes about Sync Now button
> 
> - **Sync Now** is only available when both LDAP and ABAC are enabled.
> - This button synchronizes ABAC attributes only. It is separate from the standard LDAP Sync Now action, which does not trigger an ABAC sync.

---

## Attribute store

The **Attribute store** setting appears on the ABAC Settings tab when the Policy Decision Point (PDP) is set to Virtru. It controls where assignable room attributes come from.

Switching the attribute store from **Local** to **Virtru** has immediate effects on your workspace:

- Existing ABAC attribute assignments are permanently cleared from all rooms. This cannot be undone.
- Rooms remain private. No users are removed from any room until attributes are assigned again.
- Access decisions are evaluated on Virtru. Users can only see and edit rooms they have access to according to Virtru policies.
- Attributes are managed externally and limited to those the acting admin possesses. The **Room Attributes** tab is hidden.
- An audit event is recorded for the store switch.

> [!WARNING]
> Changing the **Policy Decision Point (PDP)** setting is gated by a confirmation step, since it changes how room access is evaluated across the workspace. When you save the change, a **"Confirm settings change"** modal warns that users may be unexpectedly removed from rooms, and that switching back to **local** also resets the **Attribute store** to **local** to ensure compatibility. Click **Save changes** to apply, or **Cancel** to keep the current value.

---

## Configure Virtru PDP

Use the **Virtru PDP Configuration** section to connect Rocket.Chat to an external Virtru Policy Decision Point. This centralizes attribute management and delegates access decisions to the Virtru platform.

The Virtru PDP evaluates user attributes against room access policies and returns an allow or deny decision.

### Additional prerequisites

In addition to the general ABAC prerequisites, Virtru integration requires:

- A Virtru PDP instance configured and reachable from your Rocket.Chat server.
- A Virtru OIDC endpoint with valid client credentials.
- Network connectivity between Rocket.Chat and both the Virtru PDP and OIDC endpoint.

### Connection settings

Enter your Virtru connection credentials exactly as provided by your Virtru administrator.

| Setting | Description | Required |
| --- | --- | --- |
| **Base URL** | Virtru PDP base URL. | Yes |
| **Client ID** | OIDC client identifier. | Yes |
| **Client Secret** | OIDC client secret. | Yes |
| **OIDC Endpoint** | Base OIDC realm URL used for client credentials authentication. Example: `https://keycloak.example.com/auth/realms/opentdf`. | Yes |

### Attribute mapping

| Setting | Description | Default |
| --- | --- | --- |
| **Default Entity Key** | The entity identifier sent to the External Rights Server (ERS). Options: `emailAddress`, `oidcIdentifier`. | `emailAddress` |
| **Attribute Namespace** | Namespace used to build attribute FQNs. For example, `opentdf.io` produces `https://opentdf.io/attr/{key}/value/{value}`. | `example.com` |

Select the entity key that matches your Virtru configuration and update the attribute namespace to match your environment.

### Synchronization

| Setting | Description | Default |
| --- | --- | --- |
| **Membership Sync Interval** | Cron expression for re-evaluating ABAC room memberships against the Virtru PDP. Non-compliant users are evicted on each run. | `*/5 * * * *` (every 5 minutes) |

Adjust based on how frequently attributes change in your environment.

### Test the connection

After entering your Virtru settings:

1. Click **Test connection** at the bottom of the Virtru PDP Configuration section.
2. Rocket.Chat attempts to authenticate with Virtru and reach the health endpoint, then displays the result as a toast notification in the top-right corner.
3. The toast is not persistent, once it disappears, you'll need to click **Test connection** again to re-check the status. For deeper troubleshooting, check your Rocket.Chat server logs, which record the action and the full error details for any failed connection attempt.

### Health status

The ABAC PDP Health (toast notification) shows one of the following messages:

| Status | Meaning |
| --- | --- |
| **All systems operational** | Connected and healthy. |
| **No PDP configured** | ABAC is enabled but no PDP has been selected. |
| **Unable to connect to the Identity Provider (IdP)** | Cannot generate a token. Verify OIDC credentials and endpoint. |
| **Unable to reach the Virtru platform health endpoint** | Network connectivity issue, or Base URL is missing or incorrect. |
| **Unable to perform an authenticated request** | OIDC client lacks admin rights. Verify client permissions. |
| **PDP health check failed due to an unexpected error** | Review server logs for details. |

### Access control behaviour

Once the Virtru PDP is configured and healthy:

- Access decisions are made by the Virtru PDP instead of local policies.
- User attributes are synced from Virtru at the configured interval.
- Room access is evaluated against Virtru policies.
- Decisions are cached according to the **ABAC Cache Decision Time** setting.

---

## Disable ABAC

To disable, turn off the **Enable Attribute Based Access Control (ABAC)** toggle on the Settings tab.

Disabling ABAC suspends attribute-based enforcement across the workspace. Before disabling, be aware of the following:

- Automatic and manual user management is blocked in existing ABAC rooms.
- Rooms must be removed from ABAC management before reverting to default access controls.
- All attribute-based enforcement is paused until ABAC is re-enabled.
- Re-enabling ABAC triggers a new LDAP synchronization.

---

## Force a sync on revocations

When a user’s LDAP attributes change due to termination, role downgrade, or clearance removal, immediately trigger a manual ABAC sync:

```bash
POST /api/v1/abac/users/sync
```

This endpoint refreshes ABAC attributes for the specified users. Although ABAC enforcement runs in near real time, invoking this endpoint reduces the residual access window after revocation.

**Requirements:**

- Defense license with ABAC enabled
- `abac-management` permission

**Request body:**

Provide a JSON payload containing one or more user identifiers:

```json
{
  "usernames": ["alice", "bob"],
  "ids": ["userId123"],
  "emails": ["user@example.com"],
  "ldapIds": ["ldap-uid-456"]
}
```

You may specify any combination of identifiers. At least one field is required.

**Behaviour:**

- Scalar values are automatically converted to arrays.
- Non-string values are stringified.
- Only mapped LDAP attributes are synchronized.
- Only the specified users are refreshed.