1  ---
  2  title: Role-Based Access Control (RBAC)
  3  sidebar_position: 10
  4  ---
  5  
  6  :::warning Security Notice
  7  **Agent Mesh Enterprise now uses secure-by-default authorization.** If you do not configure an authorization service, the system will **deny all access** by default. You must explicitly configure RBAC or another authorization type to grant access to users.
  8  :::
  9  
 10  This guide walks you through configuring Role-Based Access Control (RBAC) for Agent Mesh Enterprise. You will learn how to control access to Agent Mesh Enterprise features and resources based on user roles and permissions. This guide covers RBAC configuration for both Docker and Helm deployments.
 11  
 12  
 13  ## Overview
 14  
 15  Before you configure RBAC, you need to understand how the system works. Agent Mesh Enterprise uses a three-tier authorization model that separates identity, roles, and permissions.
 16  
 17  ### RBAC Concepts
 18  
 19  RBAC in Agent Mesh Enterprise uses three connected concepts:
 20  
 21  **Users** represent identities in your system. Each user has a unique identifier, typically an email address. When a user attempts to access a feature or resource, Agent Mesh Enterprise checks their assigned roles to determine what they can do.
 22  
 23  **Roles** are collections of permissions that you assign to users. Instead of granting permissions directly to individual users, you create roles that represent job functions or responsibilities. For example, you might create a "data_analyst" role for users who need to work with data tools and artifacts. This approach simplifies administration because you can modify a role's permissions once and affect all users assigned to that role.
 24  
 25  **Scopes** are the actual permissions that grant access to specific features or resources. Each scope follows a pattern that identifies what it controls. For example, the scope `tool:data:read` grants permission to read data tools, while `tool:artifact:create` allows creating artifacts. Scopes use wildcards to grant broader permissions. For example, the scope `tool:data:*` grants all permissions for data tools.
 26  
 27  ### How Authorization Works
 28  
 29  When a user attempts an action in Agent Mesh Enterprise, the system follows this authorization flow:
 30  
 31  1. The system identifies the user based on their authentication credentials
 32  2. It retrieves all roles assigned to that user
 33  3. For each role, it collects all associated scopes (permissions)
 34  4. It checks if any of the user's scopes match the permission required for the requested action
 35  5. If a matching scope exists, the system allows the action; otherwise, it denies access
 36  
 37  This model implements the principle of least privilege: users receive only the permissions they need to perform their job functions.
 38  
 39  
 40  ### Authorization Types
 41  
 42  Agent Mesh Enterprise supports multiple authorization types, each suited for different use cases:
 43  
 44  **`deny_all` (Default)** - The secure default that denies all access. This type is automatically used when:
 45  - No `authorization_service` configuration block is present
 46  - The `authorization_service` block is empty
 47  - The `type` field is explicitly set to `deny_all`
 48  
 49  When this type is active, all user requests are denied and logged with WARNING messages. This ensures maximum security by default.
 50  
 51  **`default_rbac`** - Role-Based Access Control using configuration files. This type is the recommended type for production deployments where you need fine-grained control over user permissions. It requires both role definitions and user assignments files.
 52  
 53  **`custom`** - Custom authorization service implementation. Use this when you need to integrate with external authorization systems or implement custom authorization logic.
 54  
 55  **`none`** - Disables authorization entirely, granting wildcard `*` scope to all users. This type must be explicitly configured and should **only be used in development environments**. The system logs prominent security warnings when this type is active.
 56  
 57  :::danger Development Only
 58  The `type: none` authorization configuration grants full access to all users and should **never** be used in production environments. It is intended only for local development and testing.
 59  :::
 60  
 61  ## Planning Your RBAC Configuration
 62  
 63  Before you create configuration files, you should plan your RBAC structure. This planning phase helps you design a system that meets your organization's needs while remaining maintainable.
 64  
 65  ### Identifying User Types
 66  
 67  Start by identifying the different types of users in your organization. Consider their job functions and what they need to accomplish with Agent Mesh Enterprise. Common user types include:
 68  
 69  Administrators need full access to all features and resources. They manage the system, configure settings, and troubleshoot issues. You typically assign these users a role with wildcard permissions.
 70  
 71  Operators perform day-to-day tasks such as running tools, creating artifacts, and monitoring system activity. They need broad access to operational features but not administrative capabilities.
 72  
 73  Analysts work with data and reports. They need access to data tools, artifact creation, and monitoring capabilities, but they do not need access to system configuration or advanced tools.
 74  
 75  Viewers need read-only access to monitor system activity and view artifacts. They cannot create, modify, or delete resources.
 76  
 77  ### Designing Roles
 78  
 79  Once you identify user types, design roles that match their needs. Each role should represent a specific job function and include only the scopes necessary for that function.
 80  
 81  Consider creating a role hierarchy where some roles inherit permissions from others. For example, an "operator" role might inherit all permissions from a "viewer" role and add additional capabilities. This approach reduces duplication and makes your configuration easier to maintain.
 82  
 83  ### Mapping Scopes to Features
 84  
 85  Understanding available scopes helps you design effective roles. Agent Mesh Enterprise uses a hierarchical scope naming convention. This section describes the different types of scopes and how they control access to specific features.
 86  
 87  #### Tool Scopes
 88  
 89  Tool scopes control access to tools and follow the pattern `tool:<category>:<action>`. The `<category>` identifies the type of tool, and the `<action>` specifies what operation is permitted (e.g., `read`, `execute`, `create`, `delete`).
 90  
 91  Common tool scopes include:
 92  - `tool:basic:read` - Permission to read/view basic tools
 93  - `tool:basic:*` - All permissions for basic tools
 94  - `tool:data:*` - All permissions for data-related tools
 95  - `tool:advanced:read` - Permission to read advanced tools
 96  
 97  #### Custom Tool Scopes with `required_scopes`
 98  
 99  When you create a custom tool in Agent Mesh Enterprise, you can specify a `required_scopes` field in the tool's configuration that defines what permissions a user needs to access that tool. The field accepts a list of scope strings. This allows you to create fine-grained access controls for specific tools.
100  
101  For example, if you create a custom database query tool in your agent configuration, you would set `required_scopes` in the tool's component definition:
102  
103  ```yaml
104  # In your agent flow configuration (e.g., flows_config.yaml)
105  components:
106    - component_name: query_customer_database
107      component_module: my_custom_tools
108      component_config:
109        tool_name: "customer_database_query"
110        description: "Query the customer database for analysis"
111        required_scopes:
112          - "tool:database:query"  # RBAC scope required to use this tool
113        database_connection:
114          host: "db.example.com"
115          port: 5432
116  ```
117  
118  Then, in your role configuration, you would grant access to users who need this tool:
119  
120  ```yaml
121  # In role-to-scope-definitions.yaml
122  roles:
123    data_analyst:
124      description: "Analyst with database access"
125      scopes:
126        - "tool:database:query"  # Grants access to the customer_database_query tool
127        - "tool:artifact:list"
128        - "tool:artifact:create"
129  ```
130  
131  Only users with the `data_analyst` role (or any role containing the `tool:database:query` scope) can access the `customer_database_query` tool. Users without this scope receive an authorization error when attempting to use the tool.
132  
133  You can use wildcards in role scopes to grant broader access:
134  
135  ```yaml
136  roles:
137    database_admin:
138      description: "Database administrator with full database tool access"
139      scopes:
140        - "tool:database:*"  # Grants access to all tools with required_scopes starting with "tool:database:"
141  ```
142  
143  This role would have access to any tool with `required_scopes` containing `tool:database:query`, `tool:database:admin`, `tool:database:backup`, etc.
144  
145  #### Agent Scopes
146  
147  Agent scopes control access to specific agents and follow the pattern `agent:<agent_name>:delegate`. These scopes allow you to control which users can interact with which agents in your Agent Mesh Enterprise deployment.
148  
149  #### How Agent Scopes Work
150  
151  Unlike tools (which use an explicit `required_scopes` field), agent scopes are **automatically derived from the agent's `agent_name` configuration field**. When you define an agent, the system automatically enforces the scope `agent:<agent_name>:delegate` for access control.
152  
153  For example, if you configure an agent like this:
154  
155  ```yaml
156  # In your agent configuration file (e.g., customer_support_agent.yaml)
157  apps:
158    - name: customer_support_app
159      app_config:
160        agent_name: "customer_support_agent"  # This determines the required scope
161        display_name: "Customer Support"
162        instruction: |
163          You are a customer support agent...
164        # ... other agent configuration ...
165  ```
166  
167  The system automatically requires users to have the scope `agent:customer_support_agent:delegate` to interact with this agent. You don't need to explicitly configure this scope on the agent itself—it's derived from the `agent_name` field.
168  
169  When a user attempts to send a message to an agent or invoke an agent's capabilities, the system checks whether the user has the appropriate agent scope. The `<agent_name>` in the scope must match the name of the agent being accessed.
170  
171  #### Example: Controlling Access to Specific Agents
172  
173  Suppose you have three agents in your system:
174  - `customer_support_agent` - Handles customer inquiries
175  - `data_analysis_agent` - Performs data analytics
176  - `admin_agent` - Performs administrative tasks
177  
178  You can create roles that grant access to specific agents:
179  
180  ```yaml
181  # In role-to-scope-definitions.yaml
182  roles:
183    customer_support_rep:
184      description: "Customer support representative"
185      scopes:
186        - "agent:customer_support_agent:delegate"  # Can only access customer support agent
187        - "tool:artifact:load"
188  
189    data_analyst:
190      description: "Data analyst"
191      scopes:
192        - "agent:data_analysis_agent:delegate"  # Can only access data analysis agent
193        - "tool:data:*"
194        - "tool:artifact:load"
195        - "tool:artifact:create"
196  
197    system_admin:
198      description: "System administrator"
199      scopes:
200        - "agent:*:delegate"  # Can access all agents (wildcard)
201        - "*"  # Full access to all features
202  ```
203  
204  With this configuration:
205  - A user with the `customer_support_rep` role can only interact with `customer_support_agent`
206  - A user with the `data_analyst` role can only interact with `data_analysis_agent`
207  - A user with the `system_admin` role can interact with any agent
208  
209  #### Using Wildcards for Agent Access
210  
211  You can use wildcards to grant access to multiple agents:
212  
213  ```yaml
214  roles:
215    agent_operator:
216      description: "Can access all non-admin agents"
217      scopes:
218        - "agent:customer_*:delegate"  # Access to all agents starting with "customer_"
219        - "agent:data_*:delegate"      # Access to all agents starting with "data_"
220        - "tool:artifact:load"
221  ```
222  
223  This role would grant access to agents like `customer_support_agent`, `customer_feedback_agent`, `data_analysis_agent`, `data_processing_agent`, etc., but not `admin_agent`.
224  
225  #### Artifact Scopes
226  
227  Artifact scopes control access to files and data created by agents during task execution. Artifact tools use the standard tool scope pattern `tool:artifact:<action>`:
228  
229  - `tool:artifact:list` - Permission to list available artifacts
230  - `tool:artifact:load` - Permission to view and download artifacts
231  - `tool:artifact:create` - Permission to create new artifacts
232  - `tool:artifact:append` - Permission to append data to existing artifacts
233  - `tool:artifact:delete` - Permission to delete artifacts
234  - `tool:artifact:*` - All artifact permissions
235  
236  Example role configuration:
237  ```yaml
238  roles:
239    data_analyst:
240      description: "Data analyst with artifact access"
241      scopes:
242        - "tool:artifact:load"
243        - "tool:artifact:create"
244        - "tool:data:*"
245  ```
246  
247  #### Monitoring Scopes
248  
249  Monitoring scopes control access to system monitoring features and follow the pattern `monitor/namespace/<namespace>:a2a_messages:subscribe`. These scopes allow users to observe message traffic in specific namespaces.
250  
251  Examples:
252  - `monitor/namespace/production:a2a_messages:subscribe` - Monitor the "production" namespace
253  - `monitor/namespace/*:a2a_messages:subscribe` - Monitor all namespaces (wildcard)
254  
255  #### The Wildcard Scope
256  
257  The wildcard scope `*` grants all permissions and should only be used for administrator roles. This scope provides unrestricted access to all features, tools, agents, and resources in the system.
258  
259  ## Setting Up RBAC in Docker
260  
261  Now that you understand RBAC concepts and have planned your configuration, you can set up RBAC in your Docker environment. This process involves creating configuration files, setting up the Docker container, and verifying that everything works correctly.
262  
263  ### Prerequisites
264  
265  Before you begin, ensure you have:
266  
267  - Docker installed and running on your system
268  - The Agent Mesh Enterprise Docker image (`solace-agent-mesh-enterprise`)
269  - A text editor for creating configuration files
270  - Basic familiarity with YAML file format
271  
272  ### Creating the Configuration Directory Structure
273  
274  You need to create a directory structure on your host system to store RBAC configuration files. The Docker container will mount this directory to access your configurations.
275  
276  Create the directory structure as follows (note that `sam-enterprise` is just an example directory name - you can use any name you prefer):
277  
278  ```bash
279  mkdir -p sam-enterprise/config/auth
280  ```
281  
282  This command creates a `sam-enterprise` directory with a nested `config/auth` subdirectory. The `auth` subdirectory will contain your RBAC configuration files.
283  
284  ### Defining Roles and Permissions
285  
286  Create a file named `role-to-scope-definitions.yaml` in the `sam-enterprise/config/auth` directory. 
287  This file defines all roles in your system and the scopes (permissions) associated with each role.
288  
289  Here is an example configuration that defines three roles:
290  
291  ```yaml
292  # role-to-scope-definitions.yaml
293  roles:
294    enterprise_admin:
295      description: "Full access for enterprise administrators"
296      scopes:
297        - "*"  # Wildcard grants all permissions
298      
299    data_analyst:
300      description: "Data analysis and visualization specialist"
301      scopes:
302        - "tool:data:*"  # All data tools
303        - "tool:artifact:load"
304        - "tool:artifact:create"
305        - "monitor/namespace/*:a2a_messages:subscribe"  # Can monitor any namespace
306  
307    standard_user:
308      description: "Standard user with basic access"
309      scopes:
310        - "tool:artifact:load"
311        - "tool:basic:read"
312        - "tool:basic:search"
313  ```
314  
315  This configuration creates three distinct roles:
316  
317  The `enterprise_admin` role receives the wildcard scope `*`, which grants all permissions in the system. You should assign this role only to trusted administrators who need complete control over Agent Mesh Enterprise.
318  
319  The `data_analyst` role receives permissions tailored for data analysis work. The scope `tool:data:*` grants all permissions for data-related tools (read, write, execute). The `tool:artifact:load` and `tool:artifact:create` scopes allow analysts to view existing artifacts and create new ones. The monitoring scope `monitor/namespace/*:a2a_messages:subscribe` enables analysts to observe message traffic across all namespaces, which helps them understand data flows.
320  
321  The `standard_user` role provides minimal permissions for basic operations. Users with this role can read artifacts and perform basic tool operations but cannot create new artifacts or access advanced features.
322  
323  ### Assigning Users to Roles
324  
325  Create a file named `user-to-role-assignments.yaml` in the `sam-enterprise/config/auth` directory. This file maps user identities to roles.
326  
327  Here is an example configuration:
328  
329  ```yaml
330  # user-to-role-assignments.yaml
331  users:
332    admin@example.com:
333      roles: ["enterprise_admin"]
334      description: "Enterprise Administrator Account"
335      
336    data.analyst@example.com:
337      roles: ["data_analyst"]
338      description: "Senior Data Analyst"
339      
340    user1@example.com:
341      roles: ["standard_user"]
342      description: "Standard Enterprise User"
343  ```
344  
345  Each entry in this file maps a user identity (typically an email address) to one or more roles. Email identities are normalized to lowercase before matching, so `User@Example.com` and `user@example.com` are treated as the same identity. Non-email identifiers (such as `sub` or `oid` values) are case-sensitive and must match exactly what your authentication system provides.
346  
347  You can assign multiple roles to a single user by listing them in the `roles` array. When a user has multiple roles, they receive the combined permissions from all assigned roles. For example, if you assign both `data_analyst` and `standard_user` roles to a user, they receive all scopes from both roles.
348  
349  The `description` field is optional but recommended. It helps you document the purpose of each user account, which is valuable when reviewing or auditing your RBAC configuration.
350  
351  ### Creating the Enterprise Configuration
352  
353  Create a file named `enterprise_config.yaml` in the `sam-enterprise/config` directory (not in the `auth` subdirectory). This file tells Agent Mesh Enterprise where to find your RBAC configuration files and how to use them.
354  
355  :::info
356  The `enterprise_config.yaml` file controls authorization for both the WebUI Gateway and the Platform Service. Both services read from the same configuration through a shared `MiddlewareRegistry`, so RBAC rules you define here apply uniformly to all API endpoints. For details on how this works, see [Authentication and Authorization](platform-service-auth.md).
357  :::
358  
359  :::tip Optional Configuration
360  The `authorization_service` configuration block is **optional**. If omitted, the system defaults to `deny_all` (secure by default) and logs a WARNING message. You must explicitly configure authorization to grant access to users.
361  :::
362  
363  ```yaml
364  # enterprise_config.yaml
365  authorization_service:
366    type: "default_rbac"
367    role_to_scope_definitions_path: "config/auth/role-to-scope-definitions.yaml"
368    user_to_role_assignments_path: "config/auth/user-to-role-assignments.yaml"
369  
370  namespace: "enterprise_prod"
371  ```
372  
373  The `authorization_service` section configures the RBAC system. The `type` field specifies `default_rbac`, which tells Agent Mesh Enterprise to use the file-based RBAC system. The two path fields point to your RBAC configuration files—these paths are relative to the container's working directory, not your host system.
374  
375  **Important:** When using `type: default_rbac`, `role_to_scope_definitions_path` is **required**. The system fails to start if these files are missing or invalid.
376  
377  The `namespace` field configures the Agent Mesh Enterprise instance. The namespace isolates this instance from others.
378  
379  #### Alternative: Development Mode (Permissive)
380  
381  For local development and testing only, you can disable authorization:
382  
383  ```yaml
384  # enterprise_config.yaml - DEVELOPMENT ONLY
385  authorization_service:
386    type: "none"  # Grants full access to all users
387  
388  namespace: "enterprise_dev"
389  ```
390  
391  :::danger Security Warning
392  Using `type: none` disables all authorization checks and grants wildcard `*` scope to every user. This configuration should **never** be used in production environments. The system logs prominent security warnings when this type is active.
393  :::
394  
395  #### Default Behavior (No Configuration)
396  
397  If you omit the `authorization_service` block entirely, the system uses secure defaults:
398  
399  ```yaml
400  # enterprise_config.yaml - Secure by default
401  # No authorization_service block = deny_all
402  
403  namespace: "enterprise_prod"
404  ```
405  
406  When no authorization configuration is present, the system:
407  1. Logs a WARNING message about missing configuration
408  2. Defaults to `deny_all` authorization type
409  3. Denies all user requests with WARNING logs
410  4. Requires explicit RBAC configuration to grant access
411  
412  ### Running the Docker Container
413  
414  Now you can start the Docker container with your RBAC configuration. 
415  Navigate to your `sam-enterprise` directory and run:
416  
417  ```bash
418  cd sam-enterprise
419  
420  docker run -d \
421    --name sam-enterprise \
422    -p 8001:8000 \
423    -v "$(pwd):/app" \
424    -e SAM_AUTHORIZATION_CONFIG="/app/config/enterprise_config.yaml" \
425    -e NAMESPACE=enterprise_prod \
426    -e ... list here all other necessary env vars ...
427    solace-agent-mesh-enterprise:<tagname>
428  ```
429  
430  ### Verifying Your Configuration
431  
432  After starting the container, you should verify that RBAC is working correctly. Follow these steps:
433  
434  1. Open your web browser and navigate to `http://localhost:8001`
435  2. Log in using one of the user identities defined in your `user-to-role-assignments.yaml` file
436  3. Attempt to access features that the user should have permission to use
437  4. Attempt to access features that the user should not have permission to use
438  
439  If RBAC is configured correctly, the user can access permitted features and receives authorization errors when attempting to access restricted features.
440  
441  You can also check the container logs to verify that Agent Mesh Enterprise loaded your configuration files:
442  
443  ```bash
444  docker logs sam-enterprise
445  ```
446  
447  Look for log messages that indicate successful configuration loading. You should see messages similar to:
448  
449  ```
450  INFO:solace_ai_connector:[ConfigurableRbacAuthSvc] Successfully loaded role-to-scope definitions from: /app/config/auth/role-to-scope-definitions.yaml
451  DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'enterprise_admin' loaded with 1 direct scopes, 1 resolved scopes.
452  DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'data_analyst' loaded with 4 direct scopes, 4 resolved scopes.
453  DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'standard_user' loaded with 3 direct scopes, 3 resolved scopes.
454  ```
455  
456  These messages confirm that Agent Mesh Enterprise found and parsed your configuration files correctly.
457  
458  ## Setting Up RBAC with Helm
459  
460  For production deployments, Solace recommends using Helm to deploy Agent Mesh Enterprise on Kubernetes. The RBAC concepts (roles, scopes, and user assignments) are identical to Docker deployments, but the configuration is managed through Kubernetes ConfigMaps.
461  
462  For complete instructions on configuring RBAC in Helm deployments, including ConfigMap setup, role definitions, and user assignments, please refer to the [Solace Agent Mesh Helm Quickstart Guide - RBAC section](https://solaceproducts.github.io/solace-agent-mesh-helm-quickstart/docs/#role-based-access-control-rbac).
463  
464  ## Understanding Configuration Files
465  
466  Now that you have a working RBAC configuration, you should understand the full structure and capabilities of each configuration file. This knowledge helps you customize the configuration to meet your specific needs.
467  
468  ### Role-to-Scope Definitions Structure
469  
470  The `role-to-scope-definitions.yaml` file supports several features beyond the basic examples shown earlier. Here is the complete structure:
471  
472  ```yaml
473  roles:
474    role_name:
475      description: "Role description"
476      scopes:
477        - "scope1"
478        - "scope2"
479      inherits:  # Optional - inherit scopes from other roles
480        - "parent_role1"
481        - "parent_role2"
482  ```
483  
484  The `inherits` field allows you to create role hierarchies. When a role inherits from another role, it receives all scopes from the parent role in addition to its own scopes. This feature reduces duplication and makes your configuration easier to maintain.
485  
486  For example, you might create a base "viewer" role with read-only permissions, then create an "operator" role that inherits from "viewer" and adds write permissions:
487  
488  ```yaml
489  roles:
490    viewer:
491      description: "Read-only access"
492      scopes:
493        - "tool:basic:read"
494        - "tool:artifact:load"
495  
496    operator:
497      description: "Operational access"
498      inherits:
499        - "viewer"
500      scopes:
501        - "tool:basic:*"
502        - "tool:artifact:create"
503  ```
504  
505  In this example, the "operator" role receives all scopes from "viewer" (`tool:basic:read` and `tool:artifact:load`) plus its own scopes (`tool:basic:*` and `tool:artifact:create`). Note that `tool:basic:*` includes `tool:basic:read`, so there is some overlap. Agent Mesh Enterprise handles this correctly by deduplicating scopes.
506  
507  ### User-to-Role Assignments Structure
508  
509  The `user-to-role-assignments.yaml` file supports both global user identities and gateway-specific identities. Here is the complete structure:
510  
511  ```yaml
512  users:
513    user_identity:
514      roles: ["role1", "role2"]
515      description: "User description"
516  
517  # Optional: Gateway-specific user identities
518  gateway_specific_identities:
519    gateway_id:user_identity:
520      roles: ["role1", "role2"]
521      description: "User with specific roles on this gateway"
522  ```
523  
524  The `users` section defines global user identities that apply across all gateways. Most configurations only need this section.
525  
526  The `gateway_specific_identities` section allows you to assign different roles to the same user identity on different gateways. This feature is useful in multi-gateway deployments where you want to grant different permissions based on which gateway a user accesses. The key format is `gateway_id:user_identity`, where `gateway_id` matches the gateway ID in your configuration. The default gateway ID is `_default_enterprise_gateway`.
527  
528  ### Enterprise Configuration Structure
529  
530  The enterprise configuration file supports multiple authorization service types. Here is the complete structure for the file-based RBAC system:
531  
532  ```yaml
533  authorization_service:
534    type: "default_rbac"
535    role_to_scope_definitions_path: "path/to/role-to-scope-definitions.yaml"
536    user_to_role_assignments_path: "path/to/user-to-role-assignments.yaml"
537  ```
538  
539  ## Advanced Configuration Options
540  
541  After you have a basic RBAC configuration working, you might want to explore advanced options that provide additional flexibility and integration capabilities.
542  
543  ### Production-Ready Role Configuration
544  
545  A production environment typically needs more sophisticated role definitions than the basic examples. Here is a comprehensive configuration that demonstrates best practices:
546  
547  ```yaml
548  # role-to-scope-definitions.yaml
549  roles:
550    admin:
551      description: "Administrator with full access"
552      scopes:
553        - "*"
554    
555    operator:
556      description: "System operator"
557      scopes:
558        - "tool:basic:*"
559        - "tool:advanced:read"
560        - "tool:artifact:load"
561        - "tool:artifact:create"
562        - "monitor/namespace/*:a2a_messages:subscribe"
563  
564    viewer:
565      description: "Read-only access"
566      scopes:
567        - "tool:basic:read"
568        - "tool:artifact:load"
569        - "monitor/namespace/*:a2a_messages:subscribe"
570  ```
571  
572  ```yaml
573  # user-to-role-assignments.yaml
574  users:
575    admin@company.com:
576      roles: ["admin"]
577      description: "System Administrator"
578    
579    operator@company.com:
580      roles: ["operator"]
581      description: "System Operator"
582    
583    viewer@company.com:
584      roles: ["viewer"]
585      description: "Read-only User"
586  ```
587  
588  This configuration creates a clear hierarchy of access levels. The admin role has unrestricted access, the operator role can perform most operational tasks, and the viewer role provides read-only access for monitoring and auditing purposes.
589  
590  ### Integrating with Microsoft Graph
591  
592  For enterprise environments that use Microsoft Entra ID (formerly Azure AD) for user management, you can integrate Agent Mesh Enterprise with Microsoft Graph. This integration allows you to manage user role assignments through Microsoft Graph instead of maintaining a separate YAML file.
593  
594  To configure Microsoft Graph integration, modify your `enterprise_config.yaml`:
595  
596  ```yaml
597  # enterprise_config.yaml
598  authorization_service:
599    type: "default_rbac"
600    role_to_scope_definitions_path: "config/auth/role-to-scope-definitions.yaml"
601    user_to_role_provider: "ms_graph"
602    
603    ms_graph_config:
604      ms_graph_tenant_id: ${MS_GRAPH_TENANT_ID}
605      ms_graph_client_id: ${MS_GRAPH_CLIENT_ID}
606      ms_graph_client_secret: ${MS_GRAPH_CLIENT_SECRET}
607  ```
608  
609  This configuration tells Agent Mesh Enterprise to retrieve user role assignments from Microsoft Graph instead of reading them from a YAML file. The `${...}` syntax indicates that these values come from environment variables, which keeps sensitive credentials out of your configuration files.
610  
611  When you use Microsoft Graph integration, you still define roles in the `role-to-scope-definitions.yaml` file, but you manage user-to-role assignments through Microsoft Graph groups or attributes.
612  
613  Run the Docker container with the Microsoft Graph credentials:
614  
615  ```bash
616  docker run -d \
617    --name sam-enterprise \
618    -p 8000:8001 \
619    -v "$(pwd):/app" \
620    -e MS_GRAPH_TENANT_ID=your-tenant-id \
621    -e MS_GRAPH_CLIENT_ID=your-client-id \
622    -e MS_GRAPH_CLIENT_SECRET=your-client-secret \
623    -e NAMESPACE=enterprise_prod \
624    solace-agent-mesh-enterprise:<tag>
625  ```
626  
627  The Microsoft Graph integration requires that you configure an application registration in Microsoft Entra ID with appropriate permissions to read user and group information. The tenant ID identifies your Microsoft Entra ID tenant, the client ID identifies your application registration, and the client secret authenticates your application.
628  
629  ## Best Practices
630  
631  Following best practices helps you create a secure, maintainable RBAC configuration that scales with your organization's needs.
632  
633  ### Security Recommendations
634  
635  You should implement these security practices to protect your Agent Mesh Enterprise deployment:
636  
637  Apply the principle of least privilege by assigning users only the minimum permissions necessary for their tasks. Start with restrictive permissions and add more as needed, rather than starting with broad permissions and removing them later. This approach reduces the risk of unauthorized access.
638  
639  Conduct regular audits of your role assignments and permissions. Review who has access to what features and verify that access levels remain appropriate as job responsibilities change. Remove access for users who no longer need it.
640  
641  Protect your RBAC configuration files with appropriate file permissions on your host system. These files control access to your entire Agent Mesh Enterprise deployment, so you should restrict read and write access to authorized administrators only.
642  
643  Store sensitive information like Microsoft Graph credentials as environment variables rather than hardcoding them in configuration files. Environment variables provide better security because they do not appear in version control systems or configuration backups.
644  
645  Never use development configurations in production environments. Development configurations often include test accounts with elevated permissions or relaxed security settings that are inappropriate for production use.
646  
647  ### Role Design Principles
648  
649  Well-designed roles make your RBAC configuration easier to understand and maintain:
650  
651  Create roles that align with job functions in your organization. Each role should represent a specific type of work that users perform. This alignment makes it easier to determine which role to assign to new users.
652  
653  Use role inheritance to build a logical hierarchy. If one role needs all the permissions of another role plus additional permissions, use inheritance rather than duplicating scopes. This approach reduces configuration size and makes updates easier.
654  
655  Use clear, descriptive names for roles that indicate their purpose. Names like "data_analyst" or "system_operator" are more meaningful than generic names like "role1" or "user_type_a".
656  
657  Document the purpose and scope of each role in the description field. This documentation helps other administrators understand your RBAC configuration and makes it easier to maintain over time.
658  
659  Minimize wildcard usage in scope definitions. While wildcards like `*` or `tool:*:*` are convenient, they grant broad permissions that might include features you did not intend to allow. Use specific scopes whenever possible, and reserve wildcards for administrator roles.
660  
661  ### Docker-Specific Recommendations
662  
663  When you run Agent Mesh Enterprise in Docker, follow these recommendations:
664  
665  Use Docker volumes for persistent configuration storage. The volume mount approach shown in this guide ensures that your configuration persists even if you remove and recreate the container.
666  
667  Create separate configuration files for different environments (development, staging, production). This separation prevents accidental use of inappropriate configurations and makes it easier to maintain environment-specific settings.
668  
669  Implement health checks to verify that RBAC is functioning correctly. You can add a health check to your Docker run command that periodically tests whether the container is responding correctly.
670  
671  Regularly backup your RBAC configuration files. Store backups in a secure location separate from your Docker host. If you lose your configuration files, you lose control over who can access your Agent Mesh Enterprise deployment.
672  
673  Follow Docker security best practices such as running containers as non-root users and using read-only filesystems where possible. These practices reduce the impact of potential security vulnerabilities.
674  
675  ## Troubleshooting
676  
677  When you encounter issues with your RBAC configuration, systematic troubleshooting helps you identify and resolve problems quickly.
678  
679  ### Authorization Denied for Valid User
680  
681  If a user cannot access features they should have permission to use, you might see authorization denied messages in the logs or user interface.
682  
683  To resolve this issue, first verify that the user identity matches what appears in your `user-to-role-assignments.yaml` file. Email identities are normalized to lowercase before matching, so `User@Example.com` and `user@example.com` are treated as the same identity. However, non-email identifiers (such as `sub` or `oid` values) are case-sensitive and must match exactly.
684  
685  Next, check that the role assigned to the user has the necessary scopes. Review the `role-to-scope-definitions.yaml` file and verify that the role includes scopes for the features the user is trying to access.
686  
687  Ensure that your configuration files are correctly mounted in the Docker container. You can verify the mount by running:
688  
689  ```bash
690  docker exec -it sam-enterprise ls -la /app/config/auth
691  ```
692  
693  This command lists the files in the mounted directory. You should see your `role-to-scope-definitions.yaml` and `user-to-role-assignments.yaml` files.
694  
695  Check the container logs for authorization service errors:
696  
697  ```bash
698  docker logs sam-enterprise
699  ```
700  
701  Look for messages with the `[ConfigurableRbacAuthSvc]` prefix. These messages indicate whether Agent Mesh Enterprise successfully loaded your configuration files and how it resolved roles and scopes. You should see messages like:
702  
703  ```
704  INFO:solace_ai_connector:[ConfigurableRbacAuthSvc] Successfully loaded role-to-scope definitions from: /app/config/auth/role-to-scope-definitions.yaml
705  DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'enterprise_admin' loaded with 1 direct scopes, 1 resolved scopes.
706  DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'data_analyst' loaded with 4 direct scopes, 4 resolved scopes.
707  DEBUG:solace_ai_connector:[ConfigurableRbacAuthSvc] Role 'standard_user' loaded with 1 direct scopes, 1 resolved scopes.
708  ```
709  
710  ### Configuration Files Not Found
711  
712  If you see error messages about missing configuration files or the system uses default authorization behavior, the container cannot find your configuration files.
713  
714  Check that the volume mount in your Docker run command is correct. The mount should map your host directory to `/app` in the container. Verify that you are using the correct path on your host system.
715  
716  Ensure that file permissions allow the container user to read the files. On Linux systems, you might need to adjust file permissions:
717  
718  ```bash
719  chmod 644 sam-enterprise/config/auth/*.yaml
720  ```
721  
722  Check for typos in file names or paths. The file names are case-sensitive, and even small typos prevent Agent Mesh Enterprise from finding your configuration files.
723  
724  ### Microsoft Graph Integration Not Working
725  
726  If users cannot authenticate when you use Microsoft Graph integration, or you see error messages related to Microsoft Graph in the logs, several issues might be causing the problem.
727  
728  Verify that your Microsoft Graph credentials are correct. Double-check the tenant ID, client ID, and client secret against your Microsoft Entra ID application registration.
729  
730  Check that environment variables are properly set in your Docker run command. You can verify environment variables inside the container:
731  
732  ```bash
733  docker exec -it sam-enterprise env | grep MS_GRAPH
734  ```
735  
736  Ensure that your Microsoft Graph application has the necessary permissions. The application needs permissions to read user and group information from Microsoft Entra ID.
737  
738  Check network connectivity from the container to Microsoft Graph endpoints. The container must be able to reach `graph.microsoft.com` over HTTPS. Firewall rules or network policies might block this connectivity.
739  
740  ### Debugging Authorization Issues
741  
742  When you need to investigate authorization problems in detail, follow these debugging steps:
743  
744  Enable debug logging by adding a log level setting to your `enterprise_config.yaml`:
745  
746  ```yaml
747  # Add to your enterprise_config.yaml
748  log_level: "DEBUG"
749  ```
750  
751  Debug logging provides detailed information about authorization decisions, including which scopes the system checked and why it allowed or denied access.
752  
753  Check the container logs for detailed information:
754  
755  ```bash
756  docker logs sam-enterprise
757  ```
758  
759  Look for log messages with the `[EnterpriseConfigResolverImpl]` or `[ConfigurableRbacAuthSvc]` prefixes. These messages show how Agent Mesh Enterprise loaded and processed your configuration.
760  
761  Temporarily assign the user to an administrator role to verify whether the issue is permission-related. If the user can access features when assigned to an admin role, the problem is with the scopes assigned to their original role.
762  
763  Inspect the mounted configuration files inside the container to verify that they contain the expected content:
764  
765  ```bash
766  docker exec -it sam-enterprise cat /app/config/auth/role-to-scope-definitions.yaml
767  docker exec -it sam-enterprise cat /app/config/auth/user-to-role-assignments.yaml
768  ```
769  
770  This verification ensures that the files inside the container match your host files and that the volume mount is working correctly.
771  
772  ### Getting Help
773  
774  If you continue to experience issues after following these troubleshooting steps, you can get additional help:
775  
776  Check the Agent Mesh Enterprise documentation for updates or additional information about RBAC configuration.
777  
778  Review the container logs for specific error messages. Error messages often include details about what went wrong and how to fix it.
779  
780  Contact Solace support with details of your configuration and the issues you are experiencing. Include relevant log excerpts and describe the steps you have already taken to troubleshoot the problem.
781  
782  ## Conclusion
783  
784  Setting up Role-Based Access Control in your Agent Mesh Enterprise Docker installation provides enhanced security and granular access control. This guide has walked you through understanding RBAC concepts, planning your configuration, creating configuration files, and troubleshooting common issues.
785  
786  You now have the knowledge to configure RBAC to meet your organization's specific requirements while maintaining a secure and manageable environment. Remember to regularly review and update your RBAC configuration as your organization's needs evolve, and always follow security best practices when managing access control.