Role-Based Access Control

Role-based access control (RBAC) restricts administrative actions to authorized users. Permissions are organized into roles that can be assigned to users or service accounts. This ensures that only authorized personnel can modify policies, approve releases, or access sensitive data.

Prerequisites

API credentials with RBAC management permissions
Understanding of your organization’s access control requirements
List of users or service accounts that need access

Understanding RBAC

RBAC in Big Picture operates at three scopes:

Global — System-wide permissions (e.g., tenant management, global policies)
Tenant — Permissions scoped to a specific tenant
Product — Permissions scoped to a specific product

Permissions are additive: users with tenant-level permissions can perform actions on that tenant’s resources, but not on other tenants’ resources.

Step 1: Review Available Permissions

Query available permissions to understand what actions can be controlled:

curl "${BP_BASE_URL}/v1/permissions" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response includes:

Permission identifiers
Descriptions
Required scopes (global, tenant, product)

Common permissions include:

releases:create — Create releases
releases:approve — Approve releases
policies:manage — Manage update policies
entitlements:manage — Manage license entitlements
tenants:manage — Manage tenants (global only)
audit:read — Read audit logs
reports:generate — Generate compliance reports

Step 2: Create a Role

Create a role that groups related permissions:

curl -X POST "${BP_BASE_URL}/v1/roles" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "release-manager",
    "description": "Can create and approve releases",
    "permissions": [
      "releases:create",
      "releases:approve",
      "releases:read"
    ]
  }'

Response:

{
  "role_id": "role_abc123",
  "name": "release-manager",
  "description": "Can create and approve releases",
  "permissions": [
    "releases:create",
    "releases:approve",
    "releases:read"
  ],
  "created_at": "2024-01-15T10:30:00Z"
}

Step 3: Assign Role to User

Assign a role to a user at the appropriate scope:

Tenant-scoped assignment:

curl -X POST "${BP_BASE_URL}/v1/tenants/tenant_abc123/roles" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user@example.com",
    "role_id": "role_abc123"
  }'

Product-scoped assignment:

curl -X POST "${BP_BASE_URL}/v1/products/prod_xyz789/roles" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user@example.com",
    "role_id": "role_abc123"
  }'

Global assignment:

curl -X POST "${BP_BASE_URL}/v1/roles/role_abc123/assignments" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "admin@example.com"
  }'

Step 4: Verify Access

Test that the user has the expected permissions:

# As the assigned user, attempt to create a release
curl -X POST "${BP_BASE_URL}/v1/releases" \
  -H "Authorization: Bearer $USER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xyz789",
    "version": "1.2.3",
    "channel": "stable"
  }'

If permissions are correctly configured, the request succeeds. If not, a 403 Forbidden response is returned.

Common Role Patterns

Release Manager

Manages releases but cannot modify policies:

{
  "name": "release-manager",
  "permissions": [
    "releases:create",
    "releases:approve",
    "releases:read",
    "releases:update",
    "artifacts:upload",
    "artifacts:verify"
  ]
}

Policy Administrator

Manages update policies but cannot create releases:

{
  "name": "policy-admin",
  "permissions": [
    "policies:manage",
    "policies:read",
    "blocklists:manage"
  ]
}

Compliance Auditor

Read-only access for audits and reporting:

{
  "name": "compliance-auditor",
  "permissions": [
    "audit:read",
    "reports:generate",
    "releases:read",
    "entitlements:read",
    "policies:read"
  ]
}

License Administrator

Manages license entitlements:

{
  "name": "license-admin",
  "permissions": [
    "entitlements:manage",
    "entitlements:read",
    "licenses:import",
    "licenses:revoke"
  ]
}

Managing Role Assignments

List User’s Roles

Query all roles assigned to a user:

curl "${BP_BASE_URL}/v1/users/user@example.com/roles" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "user_id": "user@example.com",
  "roles": [
    {
      "role_id": "role_abc123",
      "name": "release-manager",
      "scope": "tenant",
      "scope_id": "tenant_abc123"
    }
  ]
}

Remove Role Assignment

Remove a role assignment:

curl -X DELETE "${BP_BASE_URL}/v1/tenants/tenant_abc123/roles/role_abc123/users/user@example.com" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Update Role Permissions

Modify a role’s permissions:

curl -X PUT "${BP_BASE_URL}/v1/roles/role_abc123" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      "releases:create",
      "releases:approve",
      "releases:read",
      "releases:update",
      "releases:delete"
    ]
  }'

Service Account Access

Service accounts can be assigned roles for automated operations:

curl -X POST "${BP_BASE_URL}/v1/service-accounts" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-cd-pipeline",
    "description": "CI/CD pipeline service account"
  }'

Assign a role to the service account:

curl -X POST "${BP_BASE_URL}/v1/tenants/tenant_abc123/roles" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_account_id": "svc_abc123",
    "role_id": "role_abc123"
  }'

Permission Precedence

When a user has multiple role assignments, permissions are combined:

Global roles grant system-wide permissions
Tenant roles grant tenant-scoped permissions
Product roles grant product-scoped permissions

Permissions are additive: if a user has releases:create at the tenant level and releases:approve at the product level, they can create releases for any product in that tenant and approve releases for the specific product.

Best Practices

Principle of least privilege: Assign only the permissions necessary for a user’s responsibilities.

Regular audits: Periodically review role assignments to ensure they remain appropriate.

Service accounts: Use service accounts for automated operations rather than user accounts.

Documentation: Document why specific roles are assigned and what they enable.

Separation of duties: Separate release creation from approval to prevent unauthorized releases.

Approval Workflows — Configure release approval requirements
Audit Readiness — Review audit logs for access patterns
Permissions Reference — Complete list of available permissions