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 VariableDescriptionDefault Value
SECURITY_TYPESecurity typeoauth2
SECURITY_OAUTH2_BASE_SERVER_URLBase URL of the Keycloak server (internal)-
SECURITY_OAUTH2_REALMOAuth2 realm name-
SECURITY_OAUTH2_CLIENT_CLIENT_IDClient ID for token introspection-
SECURITY_OAUTH2_CLIENT_CLIENT_SECRETClient secret for token introspection-
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_IDService account client IDflowx-authorization-system-sa
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRETService account client secret-
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URIToken endpoint${SECURITY_OAUTH2_BASE_SERVER_URL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token

​
Redis configuration

Authorization System uses Redis for caching. Configure Redis connection using the standard Redis environment variables. Quick reference:
Environment VariableDescriptionExample ValueStatus
SPRING_DATA_REDIS_HOSTRedis server hostnamelocalhostRecommended
SPRING_DATA_REDIS_PORTRedis server port6379Recommended
SPRING_DATA_REDIS_PASSWORDRedis authentication password-Recommended
REDIS_TTLCache TTL in milliseconds5000000Optional
Both SPRING_DATA_REDIS_* and SPRING_REDIS_* variable prefixes are supported. The SPRING_DATA_REDIS_* prefix is the modern Spring Boot standard and is recommended for new deployments.
For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the Redis Configuration guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

​
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

​
Organization events topic

New in v5.5.0
Environment VariableDescriptionDefault Value
KAFKA_TOPIC_ORGANIZATION_EVENTS_OUTTopic for organization lifecycle eventsai.flowx.organization.events.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
When using the kafka-auth profile, the security protocol will automatically be set to SASL_PLAINTEXT and the SASL mechanism will be set to OAUTHBEARER.

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

​
Keycloak redirect URIs

Available starting with FlowX.AI 5.5.0
On first startup, the authorization-system runs a Liquibase migration that creates (or updates) the default Keycloak realm and configures the flowx-platform-authenticate client. You can control which redirect URIs are set on this client using:
Environment Variables
SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URIS=https://designer.yourcompany.com/*,https://app.yourcompany.com/*
Environment VariableDescriptionDefault Value
SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URISComma-separated list of valid redirect URI patterns for the flowx-platform-authenticate Keycloak client (empty)
For new deployments, if this variable is left empty, the Keycloak client will have no redirect URIs configured and OAuth2 login flows will fail. Set this to match your Designer and app URLs.For existing deployments upgrading to 5.5.0, the migration has already run and will not re-execute. Your current Keycloak redirect URIs remain unchanged.
Examples:
  • https://designer.yourcompany.com/* — Designer access
  • https://app.yourcompany.com/* — Container app access
  • http://localhost* — Local development
You can also configure redirect URIs manually in Keycloak after deployment. This variable only applies during the initial Liquibase migration. See the IAM Configuration guide for manual Keycloak setup.

​
Default realm admin credentials

Available starting with FlowX.AI 5.6.0
During the initial Liquibase migration, the authorization-system creates the default FlowX Keycloak realm along with an admin user. You must set an initial password for this admin user:
Environment VariableDescriptionDefault Value
SPRING_LIQUIBASE_PARAMETERS_DEFAULT_ORG_ADMIN_USERNAMEEmail/username for the default realm admin useradmin@flowx.ai
SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORDInitial password for the default realm admin user. The user will be required to change this password on first login. (empty)
For new deployments, this variable must be set to a non-empty value. If left empty, the Liquibase migration will fail with Cannot create default realm when attempting to create the default admin user, and the authorization-system will not start. The Keycloak realm itself may be created successfully, but the migration will still fail at the user creation step.For existing deployments, this parameter only applies during the initial migration. If the admin user already exists in the realm, it has no effect.

​
Customer-specific variables

Required Customization: These variables must be updated for each deployment environment.
  • SECURITY_OAUTH2_BASE_SERVER_URL — Your Keycloak server URL
  • SECURITY_MASTER_REALM_ADMIN_PASSWORD — Master realm admin password
  • SPRING_DATASOURCE_URL — Your PostgreSQL connection details
  • SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URIS — Designer and app redirect URIs
  • 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
  • SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET
  • SECURITY_MASTER_REALM_ADMIN_PASSWORD

​
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.
Last modified on March 25, 2026