Skip to main content

Access Control

The Access Control service provides centralized authentication and authorization for the VirtueAI platform. It manages identities, roles, and access control policies across all Virtue applications.

This guide targets DevOps and Infrastructure teams responsible for deploying and configuring the service.

The service is being rolled out in phases and currently supports basic authentication and authorization. It does support multi-tenancy if large organizations require strict isolation between divisions or groups.

Architecture​

The service implements a Role-Based Access Control (RBAC) model with strict multi-tenant isolation.

ComponentDescription
APIFastAPI service
DatabasePostgreSQL
AuthenticationJWT tokens (access + refresh)

Core Concepts:

  • Multi-Tenancy: Data is logically isolated by Tenant. Users belong to one or more tenants.
  • Scope:
    • System Scope: Managed by the system tenant. Handles global resources (tenants, system admins). System admins can administer any tenant.
    • Tenant Scope: Users and roles within a specific tenant. Access is controlled by role assignments.
  • Tokens: JWT tokens are tenant-scoped. A token is valid only for the tenant it was issued for.

Deployment​

Docker Compose​

# Set required environment variables
export SECRET_KEY=$(openssl rand -hex 32)
export BOOTSTRAP_ADMIN_USERNAME=admin@yourcompany.com
export BOOTSTRAP_ADMIN_PASSWORD=your-secure-password

# Start services
docker-compose up -d

Environment Variables​

VariableRequiredDefaultDescription
SECRET_KEYYes-JWT signing key (use openssl rand -hex 32)
BOOTSTRAP_ADMIN_USERNAMEYes*-Initial system admin email, required only once
BOOTSTRAP_ADMIN_PASSWORDYes*-Initial system admin password, required only once
DATABASE_URLNo(docker-compose default)PostgreSQL connection string
ACCESS_TOKEN_EXPIRE_MINUTESNo60 (1 hour)JWT access token expiry
REFRESH_TOKEN_EXPIRE_DAYSNo1Refresh token expiry

Bootstrap​

On the first startup, the service automatically bootstraps the administrative environment.

Initialization Process​

When the container starts:

  1. Creates the System Tenant (system).
  2. Creates the System Admin user using the provided credentials in BOOTSTRAP_ADMIN_USERNAME and BOOTSTRAP_ADMIN_PASSWORD.
  3. Assigns the system_admin role to this user.

Note: BOOTSTRAP_ADMIN_USERNAME and BOOTSTRAP_ADMIN_PASSWORD are only required on first startup. Once the system admin exists, the service starts without it.

Default Roles​

The system comes with two primary roles designed for different levels of administration and usage.

RoleScopeDescription
System AdminSystem TenantPlatform Owner. Can create tenants, manage users, and oversee the entire deployment.
VirtueRed UserSpecific TenantStandard User. Can create and run scans, view results, and manage their own resources within VirtueRed.

Setup Guide​

This section outlines the process of setting up a new customer environment (Tenant) and onboarding users.

1. Log in as System Admin​

Access the Access Control Dashboard and log in using the bootstrapped system credentials.

2. Create a Tenant​

A Tenant represents a customer organization or any other kind of isolated logical grouping.

  1. Navigate to Tenants > Create Tenant.
  2. Enter the Tenant Name (e.g., acme-corp) and Description.
  3. Confirm creation.

3. Add Users​

Users must be created within a specific tenant. They can be added to more tenants if needed later.

  1. Switch context to the newly created tenant.
  2. Navigate to Users > Add User.
  3. Provide the user's email and initial password.

4. Assign Roles​

By default, a new user has no permissions. You must assign a role to grant access.

  1. Select the newly created user.
  2. Go to the Roles tab.
  3. Assign the VirtueRed User role.

The user can now log in to the VirtueRed application using their credentials.

Multi-Tenant Setup (Optional)​

To support multiple customers or isolated teams, repeat the Create Tenant process.

Each tenant is completely isolated:

  • Users in Tenant A cannot see or access resources in Tenant B.
  • System Admins can view and manage all tenants.

API Documentation​

Interactive API documentation is available at http://localhost:8010/swagger.

Support​

For assistance, contact support@virtueai.com