Skip to main content

RBAC & Permissions

Role-Based Access Control (RBAC) in ChainLaunch Pro allows you to manage who can access what resources and perform which actions. This guide covers user roles, permissions, and how to configure access control for your blockchain networks.

Overview​

ChainLaunch Pro includes a comprehensive permission system with:

  • 4 built-in roles (Admin, Operator, Viewer, MCP)
  • 44 granular permissions across all features
  • Custom roles for enterprise organizations
  • Hierarchical access control for multi-tenant scenarios

Built-In Roles​

Admin Role​

Full system access and user management

Admins have unrestricted access to all features including:

  • Create, read, update, delete all resources (networks, nodes, keys)
  • Manage users and roles
  • Configure system settings
  • Access audit logs
  • Manage backup and restore
  • Control monitoring and notifications

Permissions: All 44 permissions granted

Operator Role​

Network and node management without user administration

Operators can:

  • Create and manage networks (Fabric and Besu)
  • Create and manage nodes
  • Execute node operations (start, stop, restart)
  • Manage keys and certificates
  • Deploy chaincodes
  • Create and manage proposals
  • View all resources
  • Cannot manage users or modify system settings

Permissions: All permissions except user and system management

Viewer Role​

Read-only access to all resources

Viewers can:

  • View all networks and nodes
  • View metrics and monitoring data
  • View audit logs (read-only)
  • View keys and certificates (metadata only)
  • Cannot perform any modifications or operations

Permissions: All READ permissions only

MCP Role​

Limited permissions for AI agent operations

The MCP (Model Context Protocol) role is designed for AI agents and automated tools:

  • Execute MCP tools with restrictions
  • Read resources via MCP
  • Access MCP streams
  • Cannot modify core infrastructure

Permissions:

  • MCP_TOOL_EXECUTE
  • MCP_PROMPT_EXECUTE
  • MCP_RESOURCE_READ
  • MCP_STREAM_ACCESS

Permission Categories​

ChainLaunch Pro organizes 44 permissions into the following categories:

Network Permissions​

  • NETWORK_CREATE - Create new blockchain networks
  • NETWORK_READ - View network details
  • NETWORK_UPDATE - Modify network configuration
  • NETWORK_DELETE - Remove networks

Node Permissions​

  • NODE_CREATE - Create new blockchain nodes
  • NODE_READ - View node details
  • NODE_UPDATE - Modify node configuration
  • NODE_DELETE - Remove nodes
  • NODE_EXECUTE - Start, stop, restart nodes

Key Permissions​

  • KEY_CREATE - Generate cryptographic keys
  • KEY_READ - View key metadata
  • KEY_UPDATE - Modify key properties
  • KEY_DELETE - Remove keys
  • KEY_SIGN - Sign data with keys

Provider Permissions​

  • PROVIDER_CREATE - Create key providers
  • PROVIDER_READ - View provider settings
  • PROVIDER_UPDATE - Modify provider configuration
  • PROVIDER_DELETE - Remove providers

Organization Permissions (Fabric)​

  • ORGANIZATION_CREATE - Create new organizations
  • ORGANIZATION_READ - View organization details
  • ORGANIZATION_UPDATE - Modify organization settings
  • ORGANIZATION_DELETE - Remove organizations

Chaincode Permissions (Fabric)​

  • CHAINCODE_CREATE - Package and install chaincode
  • CHAINCODE_READ - View chaincode details
  • CHAINCODE_UPDATE - Approve chaincode for organizations
  • CHAINCODE_DELETE - Remove chaincode
  • CHAINCODE_EXECUTE - Invoke chaincode functions

Proposal Permissions (Fabric)​

  • PROPOSAL_CREATE - Create governance proposals
  • PROPOSAL_READ - View proposal details
  • PROPOSAL_SIGN - Sign proposals
  • PROPOSAL_SUBMIT - Submit proposals to network

User Permissions​

  • USER_CREATE - Invite new users
  • USER_READ - View user information
  • USER_UPDATE - Modify user settings
  • USER_DELETE - Remove users

API Key Permissions​

  • API_KEY_CREATE - Generate API keys
  • API_KEY_READ - View API key information
  • API_KEY_REVOKE - Revoke API keys

System Permissions​

  • SYSTEM_CONFIG - Modify system configuration
  • SYSTEM_BACKUP - Create backups
  • SYSTEM_RESTORE - Restore from backups
  • SYSTEM_MONITOR - Access monitoring and health

Metrics Permissions​

  • METRICS_DEPLOY - Deploy monitoring systems
  • METRICS_MANAGE - Manage metrics collection
  • METRICS_JOB_EDIT - Configure metrics jobs

MCP Permissions​

  • MCP_TOOL_EXECUTE - Execute MCP tools
  • MCP_PROMPT_EXECUTE - Execute MCP prompts
  • MCP_RESOURCE_READ - Read MCP resources
  • MCP_STREAM_ACCESS - Access MCP streams

Creating Custom Roles​

Custom roles allow you to define specific permission sets for your organization.

Via UI​

  1. Navigate to Settings → Roles
  2. Click "Create Role"
  3. Enter role name and description
  4. Select permissions from the available list
  5. Click "Create"

Via API​

curl -X POST http://localhost:8080/api/v1/roles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Network Engineer",
    "description": "Can manage Fabric networks and nodes",
    "permissions": [
      "NETWORK_CREATE",
      "NETWORK_READ",
      "NETWORK_UPDATE",
      "NODE_CREATE",
      "NODE_READ",
      "NODE_UPDATE",
      "NODE_EXECUTE"
    ]
  }'

Managing User Roles​

Assign Role to User​

Via UI:

  1. Go to Settings → Users
  2. Click the user to edit
  3. Select one or more roles
  4. Click Save

Via API:

curl -X POST http://localhost:8080/api/v1/users/{userId}/roles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "roleIds": ["admin-role-id", "custom-role-id"]
  }'

Remove Role from User​

Via UI:

  1. Go to Settings → Users
  2. Click the user to edit
  3. Deselect the role
  4. Click Save

Via API:

curl -X DELETE http://localhost:8080/api/v1/users/{userId}/roles/{roleId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Permission Precedence​

When a user is assigned multiple roles, permissions are additive — if any role grants a permission, the user has it.

Example:

  • User assigned to both "Viewer" and "Operator" roles
  • User can perform all Operator actions + Viewer read-only access
  • Most permissive role wins

API Keys & Permissions​

API keys can be created with a subset of permissions for automated systems and integrations.

Creating an API Key with Limited Permissions​

Via UI:

  1. Go to Settings → API Keys
  2. Click Generate New Key
  3. Enter key name and expiration
  4. Select specific permissions (optional)
  5. Click Generate

Via API:

curl -X POST http://localhost:8080/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "expiresAt": "2025-12-31T23:59:59Z",
    "permissions": [
      "NODE_READ",
      "NETWORK_READ",
      "SYSTEM_MONITOR"
    ]
  }'

Permission Checking Flow​

When you perform an action in ChainLaunch Pro:

  1. Authentication - System verifies your identity (user session, API key, or OIDC token)
  2. Role Resolution - System retrieves all roles assigned to your user
  3. Permission Aggregation - System combines permissions from all roles
  4. Permission Check - System verifies if required permission is in your set
  5. Action Execution - If authorized, action proceeds; otherwise, 403 Forbidden is returned

Audit Log Integration​

All permission-related actions are logged:

  • Role assignments
  • Role modifications
  • Permission changes
  • Permission denials
  • API key generation and revocation

Access audit logs in Settings → Audit Logs to review who has what permissions and when they changed.

Best Practices​

1. Principle of Least Privilege​

Assign only the minimum permissions users need to perform their job.

✅ GOOD: Operator assigned only NETWORK_READ, NODE_READ, NODE_EXECUTE
❌ BAD: Everyone gets Admin role

2. Use Custom Roles​

Create roles matching your organizational structure rather than adding everyone as Admin.

Examples:
- "Network Manager" - Network + Node management
- "Developer" - Chaincode development + testing
- "DevOps" - Infrastructure + monitoring
- "Auditor" - Read-only + audit log access

3. Rotate API Keys Regularly​

Set expiration dates for API keys and rotate them periodically.

✅ GOOD: 90-day expiration with quarterly rotation
❌ BAD: No expiration, never rotated

4. Monitor Permission Changes​

Regularly review audit logs for unexpected permission changes.

# Query permission changes from last 30 days
GET /api/v1/audit-logs?action=permission_changed&days=30

5. Use Different Keys for Different Services​

Don't reuse API keys across multiple services.

✅ GOOD:
  - monitoring-api-key (metrics access only)
  - ci-cd-api-key (deployment access only)

❌ BAD:
  - shared-api-key (used everywhere)

Troubleshooting​

User Can't Access a Resource​

  1. Check role assignment - Verify user has appropriate role
  2. Check permissions - Verify role includes required permission
  3. Check audit logs - Look for permission denial entries
  4. Verify inheritance - Confirm role changes have propagated

API Key Returns 403 Forbidden​

  1. Check key expiration - Verify key hasn't expired
  2. Check key permissions - Verify key has required permission
  3. Check API key revocation - Verify key hasn't been revoked
  4. Check authentication - Verify correct format: Authorization: Bearer YOUR_API_KEY

Permission Changes Not Taking Effect​

  1. Clear browser cache - Permission cache may be stale
  2. Log out and back in - Force session refresh
  3. Check propagation delay - Changes may take up to 1 minute to propagate
  4. Verify role assignment - Confirm changes were saved in database

Migration from Previous Versions​

If upgrading from ChainLaunch Pro without RBAC:

  1. All existing users are assigned to Admin role by default
  2. Review and reassign roles to match your security policy
  3. Create custom roles matching your organizational structure
  4. Gradually transition users to appropriate roles
  5. Audit all permission assignments in Activity Logs

See Also​