Authentication & Permissions

7. Authentication & Permissions

All communication in the system is secured and access-controlled via authenticated WebSocket sessions and per-device role-based permission models.

---

Authentication

Authentication is performed once during the WebSocket upgrade handshake using Zitadel token introspection.

• Each connecting participant (OSS8 or Client) must present a valid access token.
• W3S extracts the authenticated Zitadel ID from the token.
• The Zitadel ID is then bound to the WebSocket session and used for all subsequent message evaluations.

For OSS8 devices, the authenticated Zitadel ID must **match the claimed **DeviceId in every message. Any mismatch results in rejection.

---

Role-Based Permission Model

Permissions are defined per DeviceId and managed through a role assignment system:

• Each device has a dedicated permission file that defines one or more roles (e.g., controller, read-only).
• Each role lists allowed MessageTypeIds for both send and receive directions.
• Users (identified by Zitadel ID) are assigned a role per device. If a user is not assigned a role for a specific device, they have no access to interact with that device at all.

Some MessageTypeIds also support fine-grained field-level constraints. These constraints are:

• Defined per role and per MessageTypeId
• Evaluated after JSON schema validation
• Only applied to message types that explicitly define constrainable fields (e.g., min/max value ranges)

This enables granular control over which users may interact with which devices and what message types they are permitted to exchange.

Permission enforcement occurs after JSON schema validation, using the authenticated session context (UserId) and the message metadata.

---

Permission Evaluation Flow

1. User is authenticated during WebSocket connection and session is linked to their UserId.

2. Message is received and validated against the schema for the declared MessageTypeId.

3. Permission engine evaluates whether the user role (for the given DeviceId) allows the action:

   • Does this user have a role for the device?
   • Is the action direction (send or receive) allowed for this MessageTypeId?
   • If applicable, are field-level constraints (e.g., min/max values) satisfied?

4. If authorized, the message is accepted. Otherwise, it is rejected.

---

Notes

• W3S may use policy engines (e.g., OPA/Rego) internally to evaluate role-based rules.
• Unauthorized messages are rejected silently or with an optional error, depending on system configuration.
• Role and permission mappings are not directly exposed to clients but are centrally managed in W3S.