Cirata Symphony Security Reference

This page provides technical reference for Cirata Symphony's security mechanisms, including subject patterns, role definitions, RBAC configuration, and the JWT token hierarchy. For a conceptual overview of the security model, see Understanding the Security Model.

OIDC Configuration Reference

Configuration in symphony.config:

{
  "oidc": {
    "enabled": true,
    "issuer": "https://identity.example.com/realms/myrealm",
    "uiclientid": "symphony-ui",
    "apiclientid": "symphony-api"
  }
}

API Key Capabilities Format

Each API key defines capabilities as NATS subject permissions:

{
  "capabilities": {
    "pub": {
      "allow": [
        "cirata.extensions.myext.>",
        "cirata.services.storage.>",
        "_INBOX.>"
      ]
    },
    "sub": {
      "allow": [
        "cirata.extensions.myext.>",
        "cirata.services.>",
        "_INBOX.>"
      ]
    }
  }
}

Subject Pattern Matching

NATS subjects use . as a separator and support wildcards:

• *—Matches exactly one token (e.g., cirata.extensions.*.info matches cirata.extensions.myext.info)
• >—Matches one or more tokens (e.g., cirata.extensions.> matches cirata.extensions.myext.start and cirata.extensions.myext.config.get)

Examples:

• cirata.services.storage.get—Specific subject
• cirata.services.storage.*—All immediate children (get, put, delete)
• cirata.services.storage.>—All descendants (get, put, delete, list, etc.)
• cirata.>—Everything under cirata namespace

Infrastructure Subjects

Certain subjects are required for NATS operation and are automatically included:

Subject	Purpose
_INBOX.>	Request-reply patterns
$SYS.REQ.USER.INFO	Account information queries
$JS.>	JetStream API operations
$KV.>	Key-value bucket access
$O.>	Object store operations
$SRV.>	Service discovery

RBAC Configuration Reference

RBAC is configured in symphony.config:

{
  "rbac": {
    "groups_claim": "groups",
    "default_role": "viewer",
    "admin_group": "symphony-admins",
    "admin_subject": ""
  }
}

Key	Default	Description
groups_claim	"groups"	OIDC claim containing user's group memberships
default_role	"viewer"	Role assigned to users with no group matches
admin_group	""	LDAP/AD group that grants symphony-admin role
admin_subject	""	Specific user email/subject that grants symphony-admin role
bootstrap	false	Set to true to acknowledge bootstrap mode is intentional

Bootstrap Mode

When neither admin_group nor admin_subject is configured, Symphony operates in bootstrap mode:

• All authenticated users can access the Administration interface
• Any authenticated user can create, edit, and delete roles and assignments
• The Admin menu item is visible to all users

Exiting bootstrap mode: Configure either admin_group or admin_subject in symphony.config and restart Symphony.

Retaining bootstrap mode: Set "bootstrap": true in the rbac configuration to suppress the warning for intentional single-user or development deployments.

Built-in Roles

Role	Pub Allow	Sub Allow	Description
symphony-admin	cirata.> + all infrastructure subjects	cirata.> + all infrastructure subjects	Full administrative access
viewer	—	cirata.services.>, cirata.extensions.>	Read-only access to services

Role Definition Fields

Field	Description
Name	Unique identifier (e.g., data-engineer)
Description	Human-readable purpose
Publish Allow	NATS subjects the role can publish to
Subscribe Allow	NATS subjects the role can subscribe from
Visible Extensions	Which extensions appear in the menu (* for all)
JetStream Limits	Optional resource quotas (memory, disk, streams, consumers)

Custom Role Example

Name: data-engineer
Description: Access to data integration extensions
Publish Allow:
  - cirata.extensions.datamigrator.>
  - cirata.extensions.intelligence.>
  - cirata.services.storage.>
  - _INBOX.>
Subscribe Allow:
  - cirata.extensions.datamigrator.>
  - cirata.extensions.intelligence.>
  - cirata.services.>
  - _INBOX.>
Visible Extensions:
  - datamigrator
  - intelligence

Role Assignment Examples

Group DN	Role
cn=engineers,ou=groups,dc=example,dc=com	data-engineer
cn=analysts,ou=groups,dc=example,dc=com	viewer
cn=admins,ou=groups,dc=example,dc=com	symphony-admin

Role Resolution Process

RBAC and API Key Validation

When RBAC is enabled, API key creation is constrained by the user's role permissions:

1. User requests API key with specific capabilities
2. Symphony retrieves the user's assigned roles
3. Computes effective permissions from roles
4. Validates that requested capabilities are within the role ceiling
5. Rejects the request if capabilities exceed role permissions

NATS Account Hierarchy

Operator (Root CA)
  └── Symphony Account (System)
       ├── Buckets: accounts, tokens, symphony_users, symphony_shares, symphony_roles, symphony_role_assignments
       └── Services: authentication, extension registry, user management

  └── User Account 1
       ├── Imports: symphony_users, symphony_shares, symphony_roles (read-only mirrors)
       ├── Buckets: api_keys, configurations, dashboards, extension_registry_private
       └── User JWTs: API keys with specific capabilities

  └── User Account 2
       └── (same structure)

Extension Visibility Filtering

When RBAC is enabled, extension visibility in the sidebar is filtered based on the user's effective subscribe permissions. An extension is only visible to a user if their subscribe permissions cover cirata.extensions.<prefix>.> for that extension's prefix.

This filtering applies to:

• The extension list (sidebar menu items)
• Aggregated UI features (widgets, routes)
• Individual extension lookups
• Extension service proxy requests (returns 403 instead of a NATS timeout)

Users with cirata.> or cirata.extensions.> in their subscribe permissions can see all extensions. Users with specific patterns like cirata.extensions.catalog.> can only see matching extensions.

This API-level filtering is complementary to NATS-level enforcement—NATS independently blocks unauthorized messages, while the API filter prevents non-functional extensions from appearing in the UI.

Permission Validation Flow

Viewing Your Security Context

Current User Roles

Navigate to Account → Roles in the UI, or query via the CLI or API:

# Using curl
curl -H "Authorization: Bearer <token>" https://your-symphony-instance.com/api/v1/roles

API Key Details

Navigate to Account → API Keys to view your API keys and their capabilities, or query via the CLI or API:

# Using the CLI
cirata account

# Using curl
curl -H "Authorization: Bearer <token>" https://your-symphony-instance.com/api/v1/apikey

Administrator Views

Users with the symphony-admin role can access:

• Administration → Roles—Manage role definitions
• Administration → Assignments—Manage group-to-role mappings
• Administration → Users—View user accounts and their resolved roles

Troubleshooting

Cannot Access Admin Interface

• Check if admin_subject or admin_group is configured
• Verify your user subject matches admin_subject exactly
• Verify your OIDC groups include admin_group
• Check Symphony logs for role resolution errors

API Key Creation Fails with "Exceeds Role Permissions"

• View your effective permissions at /api/v1/roles
• Ensure requested capabilities are subsets of your role permissions
• Contact your administrator to update your role or group assignments

Extension Cannot Publish to Subject

• Check the extension's API key capabilities
• Verify the subject pattern includes the specific subject
• Check NATS logs for permission denied errors
• Ensure infrastructure subjects like _INBOX.> are included

User Has Wrong Roles

• Check role assignments for the user's LDAP/AD groups
• Verify OIDC groups claim contains expected group DNs
• Roles are cached at login—user may need to log out and back in

See Also

• Understanding the Security Model—Conceptual overview
• Role-Based Access Control—Step-by-step RBAC setup
• NATS Security Documentation
• OpenID Connect Specification