Skip to main content
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_SPICEDB_HOST=spicedb
FLOWX_SPICEDB_PORT=50051
FLOWX_SPICEDB_TOKEN=<spicedb-token>  # Use Kubernetes Secret
The SpiceDB token must match the preshared_key value from the SpiceDB Kubernetes secret. This same value is used as:
  • preshared_key in the SpiceDB Kubernetes secret
  • SPICEDB_GRPC_PRESHARED_KEY for SpiceDB configuration
  • FLOWX_SPICEDB_TOKEN for FlowX services
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
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_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

​
Kafka configuration

​
Connection settings

Environment VariableDescriptionDefault Value
SPRING_KAFKA_BOOTSTRAPSERVERSKafka broker addresseslocalhost:9092
SPRING_KAFKA_SECURITY_PROTOCOLSecurity protocol for KafkaPLAINTEXT
KAFKA_MESSAGE_MAX_BYTESMaximum message size52428800 (50 MB)
KAFKA_AUTHEXCEPTIONRETRYINTERVALRetry interval for auth exceptions (seconds)10

​
Topic naming configuration

Environment VariableDescriptionDefault Value
KAFKA_TOPIC_NAMING_PACKAGEPackage prefix for topic namesai.flowx.
KAFKA_TOPIC_NAMING_ENVIRONMENTEnvironment segment for topic names
KAFKA_TOPIC_NAMING_VERSIONVersion suffix for topic names.v1
KAFKA_TOPIC_NAMING_SEPARATORPrimary separator for topic names.
KAFKA_TOPIC_NAMING_SEPARATOR2Secondary separator for topic names-

​
Audit topic

Environment VariableDescriptionDefault Value
KAFKA_TOPIC_AUDIT_OUTTopic for sending audit logsai.flowx.core.trigger.save.audit.v1

​
OAuth authentication (when using SASL_PLAINTEXT)

Environment VariableDescriptionDefault Value
KAFKA_OAUTH_CLIENT_IDOAuth client IDkafka
KAFKA_OAUTH_CLIENT_SECRETOAuth client secretkafka-secret
KAFKA_OAUTH_TOKEN_ENDPOINT_URIOAuth token endpointkafka.auth.localhost

​
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: [email protected]) 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
If you’ve deployed with an incorrect subject_id, use this SQL script to fix it:
-- Replace the incorrect subject_id with the correct one from Keycloak
UPDATE public.cas_user
SET subject_id = 'PASTE_CORRECT_SUBJECT_ID_FROM_KEYCLOAK_HERE'
WHERE id = '00000000-0000-0000-0000-100000000001';
The first organization administrator always has the ID 00000000-0000-0000-0000-100000000001 in the authorization-system database.

​
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_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.

​
Ingress configuration

The Authorization System uses the standard FlowX.AI ingress pattern. For complete setup instructions including the full ingress template, CORS configuration, and troubleshooting, see the Ingress Configuration Guide. Service-specific values for Authorization System:
  • Ingress name: authorization-system-admin
  • Service path: /auth/api(/|$)(.*)(/|$)(.*)
  • Service name: authorization-system
  • Rewrite target: /api/$2
  • Fx-Workspace-Id: Required

Complete Ingress Configuration

View the centralized ingress guide for the complete configuration template, annotations reference, and best practices.