> ## Documentation Index > Fetch the complete documentation index at: https://iii.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Worker RBAC > Configure the iii-worker-manager to enable role-based access control for workers connecting over WebSocket. This guide walks you through enabling RBAC on your iii instance using the **iii-worker-manager**. Workers connect via WebSocket to a dedicated RBAC port, separate from the internal engine bridge. ## 1. Add RBAC Config to the Worker Manager Add an `iii-worker-manager` entry with RBAC config to your engine config file. At minimum you need a port and an `expose_functions` list inside `rbac`: ```yaml title="iii-config.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} workers: # ... your existing workers ... - name: iii-worker-manager config: port: 49135 rbac: expose_functions: - match("api::*") ``` This exposes all functions whose ID starts with `api::` on port 49135 with no authentication. ## 2. Write an Auth Function For production, authenticate workers by registering a function that validates credentials from the WebSocket upgrade request. The function receives an `AuthInput` and must return an `AuthResult`. ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} import type { AuthInput, AuthResult } from 'iii-sdk' import { registerWorker } from 'iii-sdk' const iii = registerWorker('ws://localhost:49134') iii.registerFunction( 'my-project::auth-function', async (input: AuthInput): Promise => { const token = input.headers?.['authorization']?.replace(/^Bearer\s+/i, '') const apiKey = input.query_params?.['api_key']?.[0] if (!token && !apiKey) { throw new Error('Missing credentials') } const user = await validateCredentials(token || apiKey) return { allowed_functions: [], forbidden_functions: user.role === 'readonly' ? ['api::users::delete', 'api::users::update'] : [], allowed_trigger_types: user.role === 'admin' ? ['cron', 'webhook'] : undefined, allow_trigger_type_registration: user.role === 'admin', context: { user_id: user.id, role: user.role, }, } }, ) ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} from iii import AuthInput, AuthResult, register_worker iii = register_worker('ws://localhost:49134') async def auth_function(data: dict) -> dict: auth_input = AuthInput(**data) token = auth_input.headers.get('authorization', '').replace('Bearer ', '', 1) api_key = (auth_input.query_params.get('api_key') or [None])[0] if not token and not api_key: raise Exception('Missing credentials') user = await validate_credentials(token or api_key) return AuthResult( allowed_functions=[], forbidden_functions=['api::users::delete', 'api::users::update'] if user['role'] == 'readonly' else [], allowed_trigger_types=['cron', 'webhook'] if user['role'] == 'admin' else None, allow_trigger_type_registration=user['role'] == 'admin', context={ 'user_id': user['id'], 'role': user['role'], }, ).model_dump() iii.register_function("my-project::auth-function", auth_function) ``` ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} use iii_sdk::{AuthInput, AuthResult, RegisterFunction, register_worker, InitOptions}; use serde_json::json; let iii = register_worker("ws://localhost:49134", InitOptions::default()); iii.register_function(RegisterFunction::new_async( "my-project::auth-function", |auth_input: AuthInput| async move { let token = auth_input.headers.get("authorization") .map(|v| v.trim_start_matches("Bearer ").to_string()); let api_key = auth_input.query_params.get("api_key") .and_then(|v| v.first()) .cloned(); let credential = token.or(api_key) .ok_or_else(|| iii_sdk::IIIError::Handler("Missing credentials".into()))?; let user = validate_credentials(&credential).await?; Ok(AuthResult { allowed_functions: vec![], forbidden_functions: if user.role == "readonly" { vec!["api::users::delete".into(), "api::users::update".into()] } else { vec![] }, allowed_trigger_types: if user.role == "admin" { Some(vec!["cron".into(), "webhook".into()]) } else { None }, allow_trigger_type_registration: user.role == "admin", context: json!({ "user_id": user.id, "role": user.role }), function_registration_prefix: None, }) }, )); ``` ### Function Registration Prefix The auth function can optionally return a `function_registration_prefix` string. When present, the engine automatically prefixes every function ID registered by this worker with `{prefix}::`. Trigger registrations also auto-prefix the `function_id` they reference. When the engine dispatches a function invocation back to the worker, the prefix is stripped so the worker SDK finds the correct local handler. This provides transparent namespace isolation per session without the worker needing to manage prefixes. Update your config to reference the auth function: ```yaml title="iii-config.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} workers: - name: iii-worker-manager config: port: 49135 rbac: auth_function_id: my-project::auth-function expose_functions: - match("api::*") ``` ## 3. Write a Middleware Function (Optional) A middleware sits between the worker and the target function. Use it for validation, rate limiting, audit logging, or enriching the payload with auth context. The function receives a `MiddlewareFunctionInput`. ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} import type { MiddlewareFunctionInput } from 'iii-sdk' iii.registerFunction( 'my-project::middleware-function', async (input: MiddlewareFunctionInput) => { console.log(`[audit] user=${input.context.user_id} invoking ${input.function_id}`) const enrichedPayload = { ...input.payload, _caller_id: input.context.user_id, _caller_role: input.context.role, } return iii.trigger({ function_id: input.function_id, payload: enrichedPayload, }) }, ) ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} from iii import MiddlewareFunctionInput async def middleware_function(data: dict) -> dict: mid = MiddlewareFunctionInput(**data) print(f"[audit] user={mid.context['user_id']} invoking {mid.function_id}") enriched_payload = { **mid.payload, '_caller_id': mid.context['user_id'], '_caller_role': mid.context['role'], } return await iii.trigger_async({ 'function_id': mid.function_id, 'payload': enriched_payload, }) iii.register_function("my-project::middleware-function", middleware_function) ``` ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} use iii_sdk::{MiddlewareFunctionInput, RegisterFunction, TriggerRequest}; use serde_json::json; let iii_clone = iii.clone(); iii.register_function(RegisterFunction::new_async( "my-project::middleware-function", move |input: MiddlewareFunctionInput| { let iii = iii_clone.clone(); async move { let mut enriched = input.payload.as_object().cloned().unwrap_or_default(); enriched.insert("_caller_id".into(), json!(input.context.get("user_id"))); enriched.insert("_caller_role".into(), json!(input.context.get("role"))); iii.trigger(TriggerRequest { function_id: input.function_id, payload: json!(enriched), action: None, timeout_ms: None, }).await } }, )); ``` Add it to your config. Note that `middleware_function_id` sits at the `config` level, not inside `rbac`: ```yaml title="iii-config.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} workers: - name: iii-worker-manager config: port: 49135 middleware_function_id: my-project::middleware-function rbac: auth_function_id: my-project::auth-function expose_functions: - match("api::*") ``` ## 4. Connect a Worker The RBAC port speaks the standard iii engine protocol. Connect using the SDK: ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} import { registerWorker } from 'iii-sdk' const worker = registerWorker('ws://localhost:49135', { headers: { authorization: 'Bearer my-token' }, }) const result = await worker.trigger({ function_id: 'api::users::list', payload: { limit: 10 }, }) console.log(result) ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} from iii import InitOptions, register_worker worker = register_worker( 'ws://localhost:49135', InitOptions(headers={'authorization': 'Bearer my-token'}), ) result = worker.trigger({ 'function_id': 'api::users::list', 'payload': {'limit': 10}, }) print(result) ``` ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} use iii_sdk::{register_worker, InitOptions, TriggerRequest}; use serde_json::json; use std::collections::HashMap; let mut headers = HashMap::new(); headers.insert("authorization".into(), "Bearer my-token".into()); let worker = register_worker("ws://localhost:49135", InitOptions { headers: Some(headers), ..Default::default() }); let result = worker.trigger(TriggerRequest { function_id: "api::users::list".into(), payload: json!({ "limit": 10 }), action: None, timeout_ms: None, }).await.expect("trigger failed"); ``` ## 5. Use Channels Through the RBAC Port Channels work on the RBAC port exactly as they do on the main engine port. The SDK's `createChannel()` works without changes: ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} const worker = registerWorker('ws://localhost:49135', { headers: { authorization: 'Bearer my-token' }, }) const channel = await worker.createChannel() const result = await worker.trigger({ function_id: 'api::files::process', payload: { reader: channel.readerRef }, }) channel.writer.stream.write(Buffer.from('hello')) channel.writer.stream.end() ``` The RBAC port mounts the channel WebSocket endpoint at `/ws/channels/{channel_id}` on the same port, so channel data flows through the secure port without exposing the main engine's channel endpoint. ## 6. RBAC for Trigger Registration Workers connecting through the RBAC port can register trigger types and triggers, subject to access control. ### Auth Result Fields The auth function controls trigger access via two fields in `AuthResult`: * **`allowed_trigger_types`** -- List of trigger type IDs this worker can register triggers for. When omitted, all types are allowed. * **`allow_trigger_type_registration`** -- Whether this worker can register new trigger types. ### Registration Hook Functions For fine-grained control, configure hook functions that are called before each registration: ```yaml title="iii-config.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} workers: - name: iii-worker-manager config: port: 49135 middleware_function_id: my-project::middleware-function rbac: auth_function_id: my-project::auth-function on_trigger_registration_function_id: my-project::on-trigger-reg on_trigger_type_registration_function_id: my-project::on-trigger-type-reg on_function_registration_function_id: my-project::on-function-reg expose_functions: - match("api::*") ``` Each hook receives the registration details and the auth context. Return a result object with the (possibly mapped) fields to allow the registration, or throw an error to deny it. Any fields omitted from the result keep their original values. ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} import type { OnTriggerRegistrationInput, OnTriggerRegistrationResult, OnTriggerTypeRegistrationInput, OnTriggerTypeRegistrationResult, OnFunctionRegistrationInput, OnFunctionRegistrationResult, } from 'iii-sdk' iii.registerFunction( 'my-project::on-trigger-reg', async (input: OnTriggerRegistrationInput): Promise => { const role = input.context.role as string if (!input.function_id.startsWith(`${role}::`)) { throw new Error('Function ID must be prefixed with the role') } return { function_id: `${role}::${input.function_id}` } }, ) iii.registerFunction( 'my-project::on-trigger-type-reg', async (input: OnTriggerTypeRegistrationInput): Promise => { if (input.context.role !== 'admin') { throw new Error('Only admins can register trigger types') } return {} }, ) iii.registerFunction( 'my-project::on-function-reg', async (input: OnFunctionRegistrationInput): Promise => { if (input.function_id.startsWith('internal::')) { throw new Error('Cannot register internal functions') } return { function_id: input.function_id } }, ) ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} from iii import ( OnTriggerRegistrationInput, OnTriggerRegistrationResult, OnTriggerTypeRegistrationInput, OnTriggerTypeRegistrationResult, OnFunctionRegistrationInput, OnFunctionRegistrationResult, ) async def on_trigger_reg(data: dict) -> dict: inp = OnTriggerRegistrationInput(**data) role = inp.context['role'] if not inp.function_id.startswith(f"{role}::"): raise Exception('Function ID must be prefixed with the role') return OnTriggerRegistrationResult( function_id=f"{role}::{inp.function_id}", ).model_dump() async def on_trigger_type_reg(data: dict) -> dict: inp = OnTriggerTypeRegistrationInput(**data) if inp.context['role'] != 'admin': raise Exception('Only admins can register trigger types') return OnTriggerTypeRegistrationResult().model_dump() async def on_function_reg(data: dict) -> dict: inp = OnFunctionRegistrationInput(**data) if inp.function_id.startswith('internal::'): raise Exception('Cannot register internal functions') return OnFunctionRegistrationResult( function_id=inp.function_id, ).model_dump() iii.register_function("my-project::on-trigger-reg", on_trigger_reg) iii.register_function("my-project::on-trigger-type-reg", on_trigger_type_reg) iii.register_function("my-project::on-function-reg", on_function_reg) ``` ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} use iii_sdk::{ OnTriggerRegistrationInput, OnTriggerRegistrationResult, OnTriggerTypeRegistrationInput, OnTriggerTypeRegistrationResult, OnFunctionRegistrationInput, OnFunctionRegistrationResult, RegisterFunction, }; iii.register_function(RegisterFunction::new_async( "my-project::on-trigger-reg", |input: OnTriggerRegistrationInput| async move { let role = input.context.get("role").and_then(|v| v.as_str()).unwrap_or(""); let prefix = format!("{role}::"); if !input.function_id.starts_with(&prefix) { return Err(iii_sdk::IIIError::Handler("Function ID must be prefixed with the role".into())); } Ok(OnTriggerRegistrationResult { function_id: Some(format!("{role}::{}", input.function_id)), ..Default::default() }) }, )); iii.register_function(RegisterFunction::new_async( "my-project::on-trigger-type-reg", |input: OnTriggerTypeRegistrationInput| async move { let role = input.context.get("role").and_then(|v| v.as_str()).unwrap_or(""); if role != "admin" { return Err(iii_sdk::IIIError::Handler("Only admins can register trigger types".into())); } Ok(OnTriggerTypeRegistrationResult::default()) }, )); iii.register_function(RegisterFunction::new_async( "my-project::on-function-reg", |input: OnFunctionRegistrationInput| async move { if input.function_id.starts_with("internal::") { return Err(iii_sdk::IIIError::Handler("Cannot register internal functions".into())); } Ok(OnFunctionRegistrationResult { function_id: Some(input.function_id), ..Default::default() }) }, )); ``` ## Expose Functions by Metadata If your functions register metadata, you can use metadata filters instead of (or in addition to) wildcard patterns: ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} iii.registerFunction('api::users::list', async (input) => { // ... }, { metadata: { public: true, tier: 'free' } }) ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} iii.register_function("api::users::list", list_users, metadata={'public': True, 'tier': 'free'}) ``` ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} let mut msg = RegisterFunctionMessage::with_id("api::users::list".to_string()); msg.metadata = Some(json!({ "public": true, "tier": "free" })); iii.register_function((msg, |input: Value| async move { // ... Ok(json!({})) })); ``` Then filter by metadata in your config: ```yaml title="iii-config.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} rbac: expose_functions: - metadata: public: true - metadata: tier: "free" ``` ## Types Reference All three SDKs export the following types for RBAC functions. ### AuthInput Input passed to the auth function during the WebSocket upgrade. | Field | Type | Description | | -------------- | -------------------------- | ------------------------------------------------------------------------------- | | `headers` | `Record` | HTTP headers from the upgrade request. | | `query_params` | `Record` | Query parameters. Each key maps to an array of values to support repeated keys. | | `ip_address` | `string` | IP address of the connecting client. | ### AuthResult Return value from the auth function. Controls access and passes context to middleware. | Field | Type | Default | Description | | --------------------------------- | ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allowed_functions` | `string[]` | `[]` | Additional function IDs to allow beyond `expose_functions`. | | `forbidden_functions` | `string[]` | `[]` | Function IDs to deny even if they match `expose_functions`. Takes precedence. | | `allowed_trigger_types` | `string[]` or omitted | omitted (permissive) | Trigger type IDs the worker may register triggers for. When omitted, all types are allowed. | | `allow_trigger_type_registration` | `boolean` | `false` | Whether the worker may register new trigger types. | | `allow_function_registration` | `boolean` | `true` | Whether the worker may register new functions. | | `function_registration_prefix` | `string` or omitted | omitted | When set, all function IDs registered by this worker are internally prefixed with `{prefix}::`. Triggers auto-prefix their `function_id` reference. The prefix is stripped when invoking the worker, so the worker SDK never sees it. | | `context` | `Record` | `{}` | Arbitrary context forwarded to the middleware function on every invocation. | ### MiddlewareFunctionInput Input passed to the middleware function on every invocation through the RBAC port. | Field | Type | Description | | ------------- | -------------------------- | -------------------------------------------------------- | | `function_id` | `string` | ID of the function being invoked. | | `payload` | `Record` | Payload sent by the caller. | | `action` | `TriggerAction` or omitted | Routing action (enqueue, void), if any. | | `context` | `Record` | Auth context from `AuthResult.context` for this session. | ### OnTriggerTypeRegistrationInput Input passed to the `on_trigger_type_registration_function_id` hook. Return an `OnTriggerTypeRegistrationResult` or throw to deny. | Field | Type | Description | | ----------------- | ------------------------- | ----------------------------------------------- | | `trigger_type_id` | `string` | ID of the trigger type being registered. | | `description` | `string` | Human-readable description of the trigger type. | | `context` | `Record` | Auth context from `AuthResult.context`. | ### OnTriggerTypeRegistrationResult Result returned from the `on_trigger_type_registration_function_id` hook. Omitted fields keep the original value. | Field | Type | Description | | ----------------- | ------------------- | ----------------------- | | `trigger_type_id` | `string` or omitted | Mapped trigger type ID. | | `description` | `string` or omitted | Mapped description. | ### OnTriggerRegistrationInput Input passed to the `on_trigger_registration_function_id` hook. Return an `OnTriggerRegistrationResult` or throw to deny. | Field | Type | Description | | -------------- | ------------------------- | -------------------------------------------- | | `trigger_id` | `string` | ID of the trigger being registered. | | `trigger_type` | `string` | Trigger type identifier. | | `function_id` | `string` | ID of the function this trigger is bound to. | | `config` | `unknown` | Trigger-specific configuration. | | `context` | `Record` | Auth context from `AuthResult.context`. | ### OnTriggerRegistrationResult Result returned from the `on_trigger_registration_function_id` hook. Omitted fields keep the original value. | Field | Type | Description | | -------------- | -------------------- | ----------------------------- | | `trigger_id` | `string` or omitted | Mapped trigger ID. | | `trigger_type` | `string` or omitted | Mapped trigger type. | | `function_id` | `string` or omitted | Mapped function ID. | | `config` | `unknown` or omitted | Mapped trigger configuration. | ### OnFunctionRegistrationInput Input passed to the `on_function_registration_function_id` hook. Return an `OnFunctionRegistrationResult` or throw to deny. | Field | Type | Description | | ------------- | ------------------------------------ | -------------------------------------------- | | `function_id` | `string` | ID of the function being registered. | | `description` | `string` or omitted | Human-readable description of the function. | | `metadata` | `Record` or omitted | Arbitrary metadata attached to the function. | | `context` | `Record` | Auth context from `AuthResult.context`. | ### OnFunctionRegistrationResult Result returned from the `on_function_registration_function_id` hook. Omitted fields keep the original value. | Field | Type | Description | | ------------- | ------------------------------------ | ------------------- | | `function_id` | `string` or omitted | Mapped function ID. | | `description` | `string` or omitted | Mapped description. | | `metadata` | `Record` or omitted | Mapped metadata. | ## Full Example Config ```yaml title="iii-config.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} workers: - name: iii-worker-manager config: port: 49134 - name: iii-stream config: port: 3112 - name: iii-worker-manager config: host: 0.0.0.0 port: 49135 middleware_function_id: my-project::middleware-function rbac: auth_function_id: my-project::auth-function on_trigger_registration_function_id: my-project::on-trigger-reg on_trigger_type_registration_function_id: my-project::on-trigger-type-reg on_function_registration_function_id: my-project::on-function-reg expose_functions: - match("api::*") - match("*::public") - metadata: public: true ``` Only expose the RBAC port (49135) to external networks. The main engine port (49134) and stream port (3112) should remain internal. Use firewall rules or network policies to enforce this.