The authorization-system microservice provides centralized authorization services for the FlowX.AI platform, managing workspaces, users, groups, roles, and permissions. It works alongside SpiceDB to deliver fine-grained access control and supports the Workspaces feature.

Database configuration

The authorization-system must use a dedicated PostgreSQL database. Do not share with other FlowX.AI services.
Environment Variables
SPRING_DATASOURCE_URL=jdbc:postgresql://postgresql:5432/authorization_system
SPRING_DATASOURCE_USERNAME=flowx
SPRING_DATASOURCE_PASSWORD=<password>  # Use Kubernetes Secret
Requirements:
  • Database user needs full access to authorization_system database
  • PostgreSQL must be available before service startup

CAS client library configuration

The authorization-system uses the CAS client library to communicate with SpiceDB for ACL operations.
Environment Variables
FLOWX_LIB_CASCLIENT_SPICEDB_HOST=spicedb
FLOWX_LIB_CASCLIENT_SPICEDB_PORT=50051
FLOWX_LIB_CASCLIENT_SPICEDB_TOKEN=<spicedb-token>  # Use Kubernetes Secret
The SpiceDB token is the SPICEDB_GRPC_PRESHARED_KEY value from your SpiceDB configuration.
Configuration Parameters:
  • SpiceDB Host: Service hostname (typically spicedb)
  • SpiceDB Port: gRPC port (standard: 50051)
  • SpiceDB Token: Authentication token for SpiceDB access

OAuth2/Keycloak configuration

Environment Variables
SECURITY_OAUTH2_BASE_SERVER_URL=https://auth.yourcompany.com/auth
SECURITY_OAUTH2_REALM=flowx
SECURITY_OAUTH2_CLIENT_CLIENT_ID=flowx-platform-authorize
SECURITY_OAUTH2_CLIENT_CLIENT_SECRET=<oauth-secret>  # Use Kubernetes Secret
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET=<service-account-secret>  # Use Kubernetes Secret

OAuth2 Client

Must be configured in Keycloak with appropriate scopes for platform access

Service Account

Requires admin privileges in Keycloak for user management operations

Redis configuration

Environment Variables
SPRING_REDIS_HOST=redis-master
SPRING_REDIS_PASSWORD=<redis-password>  # Use Kubernetes Secret

Management

Environment Variables
MANAGEMENT_SERVER_PORT=8081

Organization admin bootstrap

The authorization-system uses a fallback mechanism to create the first organization administrator when no admin users exist.
Set SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME (default: admin@flowx.ai) Process:
  • System searches for this username in Keycloak
  • Copies the user’s sub_id (subject ID) to authorization-system database
  • Grants organization admin privileges automatically

Fallback method

Set SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID with a specific Keycloak subject ID Process:
  • Creates user directly in authorization-system database
  • Assigns organization admin roles
  • Used when username method fails or is set to null

Error handling

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

Customer-specific variables

Required Customization: These variables must be updated for each deployment environment.
  • SECURITY_OAUTH2_BASE_SERVER_URL - Your Keycloak server URL
  • SECURITY_OAUTH2_REALM - Your Keycloak realm name
  • SECURITY_OAUTH2_CLIENT_CLIENT_ID - Your OAuth2 client identifier
  • SPRING_DATASOURCE_URL - Your PostgreSQL connection details
  • Service hostnames - Update to match your Kubernetes service names

Secrets management

Security: Always use Kubernetes Secrets for sensitive configuration values.
Required Kubernetes Secrets:
  • SPRING_DATASOURCE_PASSWORD
  • FLOWX_LIB_CASCLIENT_SPICEDB_TOKEN
  • SPRING_REDIS_PASSWORD
  • SECURITY_OAUTH2_CLIENT_CLIENT_SECRET
  • SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET

Deployment prerequisites

Infrastructure

  • PostgreSQL with authorization_system database
  • SpiceDB with authentication configured
  • Redis for caching

Identity & Access

  • Keycloak with configured realm
  • OAuth2 clients created
  • Admin user exists in Keycloak

Architecture notes

Database Access Control: Only authorization-system has direct write access to the CAS PostgreSQL database. Other services communicate via REST APIs only.
SpiceDB Integration: Uses PostgreSQL as backend storage and communicates via gRPC through the CAS client library.