The Centralized Authorization System (CAS), implemented as the authorization-system microservice, is introduced in FlowX 5.0 to manage workspace permissions, user access control, and ACL (Access Control List) rules for the multi-tenant architecture.

​
Overview

The CAS microservice provides centralized authorization services for the FlowX platform, managing workspaces, users, groups, roles, and permissions. It works alongside SpiceDB to deliver fine-grained access control and supports the new multi-tenant Workspaces feature.
Important: Only the authorization-system microservice should have direct write access to the CAS PostgreSQL database. Other services communicate through the CAS client library and REST APIs.

​
Prerequisites

Before installing CAS, ensure the following components are available:

​
Infrastructure requirements

  • PostgreSQL
  • Kafka
  • Keycloak

​
Dependencies

CAS requires the following FlowX components to be operational:
  • Existing FlowX infrastructure (Engine, Admin, Designer)
  • Keycloak or compatible OAuth2 identity provider
  • PostgreSQL database for FlowX (can be same or separate instance)

​
SpiceDB installation

SpiceDB is required for ACL (Access Control List) management and must be installed before CAS.

​
CAS microservice installation

​
Service communication architecture

The CAS system follows a strict communication pattern to ensure data integrity and security:
Database Access Control: Only the authorization-system microservice has direct access to the CAS PostgreSQL database. All other services communicate exclusively through REST APIs via the CAS client library.
Communication Methods:
  • authorization-system: Direct database access (exclusive write access)
  • data-sync: Temporary database write access during migrations only (exception for migrating existing projects)
  • Other FlowX services: REST API communication only via CAS client library
  • SpiceDB: All services communicate with SpiceDB via gRPC through CAS client library

​
Database architecture

  • CAS PostgreSQL Database: Used exclusively by authorization-system for authorization data
  • Migration Exception: data-sync service requires temporary write access to migrate existing projects from app-manager database to CAS database
  • No Direct Database Access: Other services do not connect directly to the CAS database - all communication is through REST APIs
  • SpiceDB Integration: Uses PostgreSQL as backend storage, accessed via gRPC through CAS client library

​
Authorization-system environment variables

The authorization-system microservice requires the following configuration:
  • SPRING_APPLICATION_NAME
  • SPRING_LIQUIBASE_CHANGE_LOG
  • SPRING_LIQUIBASE_PARAMETERS_SPICE_DB_HOST
  • SPRING_LIQUIBASE_PARAMETERS_SPICE_DB_PORT
  • SPRING_LIQUIBASE_PARAMETERS_SPICE_DB_TOKEN
  • SPRING_LIQUIBASE_PARAMETERS_CREATE_DEFAULT_WORKSPACE
  • SPRING_LIQUIBASE_PARAMETERS_DEFAULT_ORG_ADMIN_USER_SUBJECT_ID
  • SPRING_LIQUIBASE_PARAMETERS_DEFAULT_ORG_ADMIN_USERNAME
Environment Variables
SPRING_APPLICATION_NAME=authorization-system
SPRING_LIQUIBASE_CHANGE_LOG=classpath:config/liquibase/master.xml
SPRING_LIQUIBASE_PARAMETERS_SPICE_DB_HOST=localhost
SPRING_LIQUIBASE_PARAMETERS_SPICE_DB_PORT=50051
SPRING_LIQUIBASE_PARAMETERS_SPICE_DB_TOKEN=flowx_test_token
SPRING_LIQUIBASE_PARAMETERS_CREATE_DEFAULT_WORKSPACE=true
SPRING_LIQUIBASE_PARAMETERS_DEFAULT_ORG_ADMIN_USER_SUBJECT_ID=
SPRING_LIQUIBASE_PARAMETERS_DEFAULT_ORG_ADMIN_USERNAME=admin@flowx.ai
SPRING_LIQUIBASE_PARAMETERS_OPENID_REALM_NAME=flowx
SPRING_LIQUIBASE_PARAMETERS_OPENID_BASE_SERVER_URL=http://localhost:8080/auth
SPRING_LIQUIBASE_PARAMETERS_OPENID_ADMIN_CLIENT_ID=flowx-admin-client
SPRING_LIQUIBASE_PARAMETERS_OPENID_ADMIN_CLIENT_SECRET=flowx-admin-client-secret
SPRING_LIQUIBASE_PARAMETERS_DEFAULT_TEST_USERNAMES=

​
Database configuration

Important: The authorization-system requires its own dedicated PostgreSQL database. This database should only be accessed directly by the authorization-system microservice.
Database Configuration Parameters:
  • SPRING_DATASOURCE_URL
  • SPRING_DATASOURCE_USERNAME
  • SPRING_DATASOURCE_PASSWORD
  • SPRING_DATASOURCE_DRIVER_CLASS_NAME
Environment Variables
spring.datasource.url=jdbc:postgresql://localhost:5432/flowx_cas
spring.datasource.username=flowx_cas
spring.datasource.password=flowx_cas
spring.datasource.driver-class-name=org.postgresql.Driver

​
Migration parameters

Custom configurations are only required during migration from previous FlowX versions.
  • create-default-workspace: true: Required for upgrades to migrate existing projects to default workspace
  • default-org-admin-username: admin@flowx.ai: Bootstrap first organization admin from Keycloak
  • default-org-admin-user-subject-id: Leave empty - fallback method if username approach fails
  • default-test-usernames: Optional - for creating test users during development

​
SpiceDB integration parameters

SpiceDB parameters are automatically retrieved from CAS client library configuration - no manual setup required.
  • spice-db-host: Inherited from ${flowx.lib.cas-client.spicedb.host}
  • spice-db-port: Inherited from ${flowx.lib.cas-client.spicedb.port}
  • spice-db-token: Inherited from ${flowx.lib.cas-client.spicedb.token}

​
Keycloak integration parameters

Keycloak parameters inherit from existing FlowX OAuth2 configuration - no additional setup required.
  • openid-realm-name: Inherited from existing FlowX security configuration
  • openid-base-server-url: Inherited from existing FlowX security configuration
  • openid-admin-client-id: Inherited from existing FlowX security configuration
  • openid-admin-client-secret: Inherited from existing FlowX security configuration

​
Organization admin bootstrap

The authorization-system uses a fallback mechanism to create the first organization administrator when no admin users exist.
1

Primary Method (Recommended)

Set SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME (default: admin@flowx.ai)Process:
  1. System searches for this username in Keycloak
  2. Copies the user’s sub_id (subject ID) to CAS database
  3. Grants organization admin privileges automatically
2

Fallback Method

Set SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID with a specific Keycloak subject IDProcess:
  1. Creates user directly in authorization-system database
  2. Assigns organization admin roles
  3. Used when username method fails or is set to null
3

Error Handling

If incorrect subject_id is provided:
  • Login will fail
  • No org-admin privileges granted
  • Manual database correction required

​
FlowX services configuration

​
CAS client library integration

All FlowX microservices integrate with the authorization-system through the CAS client library, which handles communication with both CAS REST APIs and SpiceDB gRPC APIs.
CAS Client Library Configuration: Each FlowX service requires a {microservice}-cas.yml configuration file that defines connectivity to both authorization-system and SpiceDB through the CAS client library.

​
CAS client configuration structure

Each microservice needs the following configuration file ({microservice}-cas.yml):
Environment Variables
FLOWX_LIB_CAS_CLIENT_SPICEDB_HOST=localhost
FLOWX_LIB_CAS_CLIENT_SPICEDB_PORT=50051
FLOWX_LIB_CAS_CLIENT_SPICEDB_TOKEN=flowx_test_token
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_BASE_URL=http://localhost:8100
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_RESPONSE_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_CONNECTION_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_MAX_IN_MEMORY_SIZE=5242880
Configuration Parameters:
  • spicedb.host: SpiceDB service hostname
  • spicedb.port: SpiceDB gRPC port (typically 50051)
  • spicedb.token: Authentication token for SpiceDB access
  • authorization-system.base-url: authorization-system service REST endpoint
  • web-client.response-timeout: HTTP response timeout in seconds
  • web-client.connection-timeout: HTTP connection timeout in seconds
  • web-client.max-in-memory-size: Maximum memory buffer size for HTTP responses

​
Admin service configuration

The admin service requires the CAS client configuration file for integration with authorization-system and SpiceDB. 
FLOWX_LIB_CAS_CLIENT_SPICEDB_HOST=localhost
FLOWX_LIB_CAS_CLIENT_SPICEDB_PORT=50051
FLOWX_LIB_CAS_CLIENT_SPICEDB_TOKEN=flowx_test_token
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_BASE_URL=http://localhost:8100
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_RESPONSE_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_CONNECTION_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_MAX_IN_MEMORY_SIZE=5242880

​
Engine service configuration

The engine service requires the CAS client configuration file for integration with authorization-system and SpiceDB. 
FLOWX_LIB_CAS_CLIENT_SPICEDB_HOST=localhost
FLOWX_LIB_CAS_CLIENT_SPICEDB_PORT=50051
FLOWX_LIB_CAS_CLIENT_SPICEDB_TOKEN=flowx_test_token
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_BASE_URL=http://authorization-system:80
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_RESPONSE_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_CONNECTION_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_MAX_IN_MEMORY_SIZE=5242880

​
Application manager service configuration

The application manager service requires the CAS client configuration file for integration with authorization-system and SpiceDB. 

FLOWX_LIB_CAS_CLIENT_SPICEDB_HOST=localhost
FLOWX_LIB_CAS_CLIENT_SPICEDB_PORT=50051
FLOWX_LIB_CAS_CLIENT_SPICEDB_TOKEN=flowx_test_token
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_BASE_URL=http://authorization-system:80
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_RESPONSE_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_CONNECTION_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_MAX_IN_MEMORY_SIZE=5242880

​
CMS core service configuration

The CMS core service requires the CAS client configuration file for integration with authorization-system and SpiceDB. 

FLOWX_LIB_CAS_CLIENT_SPICEDB_HOST=localhost
FLOWX_LIB_CAS_CLIENT_SPICEDB_PORT=50051
FLOWX_LIB_CAS_CLIENT_SPICEDB_TOKEN=flowx_test_token
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_BASE_URL=http://authorization-system:80
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_RESPONSE_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_CONNECTION_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_MAX_IN_MEMORY_SIZE=5242880

​
Authorization-system CAS client library

The authorization-system also needs to be configured to use the CAS client library: 

FLOWX_LIB_CAS_CLIENT_SPICEDB_HOST=spicedb-headless
FLOWX_LIB_CAS_CLIENT_SPICEDB_PORT=50051
FLOWX_LIB_CAS_CLIENT_SPICEDB_TOKEN=herepassword
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_BASE_URL=http://authorization-system:80
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_RESPONSE_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_CONNECTION_TIMEOUT=5
FLOWX_LIB_CAS_CLIENT_AUTHORIZATION_SYSTEM_WEB_CLIENT_MAX_IN_MEMORY_SIZE=5242880

​
Default roles and permissions

FlowX 5.0 includes a comprehensive set of predefined roles that provide different levels of access across the platform. Understanding these roles is crucial for proper workspace setup and user management.

​
Role hierarchy

Organization Admin (org_admin)
  • Has full administrative access to manage users, workspaces, groups, roles, and system settings across the organization
  • Cannot be edited, duplicated, or deleted
  • Can only be assigned in the Organization admin space
  • Hidden from workspace role lists

​
Default groups

Each workspace automatically includes an “Everyone in workspace” group that simplifies permission management.
Auto-Generated Group: all_users_[workspace_name]
  • Created automatically when provisioning a workspace
  • Not displayed in the Groups list interface
  • Cannot be edited, deleted, or duplicated by users
  • Users are automatically added/removed when their workspace access changes
  • Pre-selected when creating projects/libraries for easy access management

​
Permission matrix overview

The permission system is structured around different entity types:

​
Role management rules

Predefined Roles

  • Cannot be deleted or fundamentally altered
  • Permission structures are fixed for consistency
  • Can be duplicated to create custom variations
  • Ensure consistent access patterns across workspaces

Custom Roles

  • Out of scope for FlowX 5.0 initial release
  • Will be available in future versions
  • Will support both workspace and project-level customization
  • Will allow full permission customization
1

Deploy authorization-system Infrastructure

Deploy SpiceDB and authorization-system microservice with migration configuration:
# Key migration environment variables
SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true
SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME=admin@flowx.ai
2

Automatic Default Workspace Creation

The authorization-system will automatically:
  • Create default organization and workspace
  • Import the admin user from Keycloak
  • Assign organization admin privileges
  • Set up default roles and groups
3

data-sync Migration Process

The data-sync service will:
  • Read existing projects from app-manager PostgreSQL database
  • Migrate projects to the CAS database
  • Assign all existing resources to the default workspace
  • Preserve all existing functionality
Note: data-sync is the only service (besides authorization-system) with write access to CAS database during migration.
4

Update Service Configurations

Update all FlowX microservices with CAS integration configuration and restart services.
5

Validate Migration

Verify successful migration by checking:
  • Organization and workspace creation
  • Admin user import and role assignment
  • Project migration to default workspace
  • Service connectivity to CAS and SpiceDB

​
Troubleshooting