Authorization system setup

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

Runtime authorization backend

Selects which backend the CAS client library uses for runtime authorization checks. With CUSTOM (the default), authorization requests are served by the authorization-system service over REST. With SPICEDB, checks are delegated directly to SpiceDB. The value is defined once in the shared CAS client library and inherited by every service; override it only if instructed by FlowX.

Environment Variable	Description	Default Value
`FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION`	Runtime authorization backend. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB.	`CUSTOM`

OAuth2/Keycloak configuration

Environment Variable	Description	Default Value
`SECURITY_TYPE`	Security type	`oauth2`
`SECURITY_OAUTH2_BASE_SERVER_URL`	Base URL of the Keycloak server (internal)	-
`SECURITY_OAUTH2_REALM`	OAuth2 realm name	-
`SECURITY_OAUTH2_CLIENT_CLIENT_ID`	Client ID for token introspection	-
`SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`	Client secret for token introspection	-
`SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID`	Service account client ID	`flowx-authorization-system-sa`
`SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET`	Service account client secret	-
`SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI`	Token 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 Variable	Description	Example Value	Status
`SPRING_DATA_REDIS_HOST`	Redis server hostname	`localhost`	Recommended
`SPRING_DATA_REDIS_PORT`	Redis server port	`6379`	Recommended
`SPRING_DATA_REDIS_PASSWORD`	Redis authentication password	-	Recommended
`REDIS_TTL`	Cache TTL in milliseconds	`5000000`	Optional

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 Variable	Description	Default Value
`SPRING_KAFKA_BOOTSTRAPSERVERS`	Kafka broker addresses	`localhost:9092`
`SPRING_KAFKA_SECURITY_PROTOCOL`	Security protocol for Kafka	`PLAINTEXT`
`KAFKA_MESSAGE_MAX_BYTES`	Maximum message size	`52428800` (50 MB)
`KAFKA_AUTHEXCEPTIONRETRYINTERVAL`	Retry interval for auth exceptions (seconds)	`10`

Topic naming configuration

Environment Variable	Description	Default Value
`KAFKA_TOPIC_NAMING_PACKAGE`	Package prefix for topic names	`ai.flowx.`
`KAFKA_TOPIC_NAMING_ENVIRONMENT`	Environment segment for topic names
`KAFKA_TOPIC_NAMING_VERSION`	Version suffix for topic names	`.v1`
`KAFKA_TOPIC_NAMING_SEPARATOR`	Primary separator for topic names	`.`
`KAFKA_TOPIC_NAMING_SEPARATOR2`	Secondary separator for topic names	`-`

Audit topic

Environment Variable	Description	Default Value
`KAFKA_TOPIC_AUDIT_OUT`	Topic for sending audit logs	`ai.flowx.core.trigger.save.audit.v1`

Organization events topic

Environment Variable	Description	Default Value
`KAFKA_TOPIC_ORGANIZATION_EVENTS_OUT`	Topic for organization lifecycle events	`ai.flowx.organization.events.v1`

OAuth authentication (when using SASL_PLAINTEXT)

Environment Variable	Description	Default Value
`KAFKA_OAUTH_CLIENT_ID`	OAuth client ID	`kafka`
`KAFKA_OAUTH_CLIENT_SECRET`	OAuth client secret	`kafka-secret`
`KAFKA_OAUTH_TOKEN_ENDPOINT_URI`	OAuth token endpoint	`kafka.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.

Service account realm secrets

These variables configure the client secrets for service accounts in the dedicated service accounts realm. Liquibase uses these secrets when provisioning the SA realm during deployment. By default, secrets are left empty and auto-generated. Set explicit values only if you need to reference specific service account credentials in custom integrations.

Environment Variable	Description	Default Value
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_ORGANIZATION_MANAGER_SA`	Client secret for the organization-manager service account	Auto-generated
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_ADMIN_SA`	Client secret for the admin service account	Auto-generated
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_AUTHORIZATION_SYSTEM_SA`	Client secret for the authorization-system service account	Auto-generated
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_INTEGRATION_DESIGNER_SA`	Client secret for the integration-designer service account	Auto-generated
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_PROCESS_ENGINE_SA`	Client secret for the process-engine service account	Auto-generated
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_RUNTIME_MANAGER_SA`	Client secret for the runtime-manager service account	Auto-generated
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_SCHEDULER_CORE_SA`	Client secret for the scheduler-core service account	Auto-generated
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_TASK_MANAGEMENT_PLUGIN_SA`	Client secret for the task-management-plugin service account	Auto-generated
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_LICENSE_SA`	Client secret for the license service account	Auto-generated
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_EMAIL_GATEWAY_SA`	Client secret for the email-gateway service account	Auto-generated
`FLOWX_SA_REALM_SECRETS_SERVICE_ACCOUNTS_FLOWX_WEBHOOK_GATEWAY_SA`	Client secret for the webhook-gateway service account	Auto-generated

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.

Primary method (recommended)

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

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 Variable	Description	Default Value
`SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URIS`	Comma-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

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 Variable	Description	Default Value
`SPRING_LIQUIBASE_PARAMETERS_DEFAULT_ORG_ADMIN_USERNAME`	Email/username for the default realm admin user	`admin@flowx.ai`
`SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD`	Initial password for the default realm admin user. The user will be required to change this password on first login.	(empty)
`SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD_IS_TEMPORARY`	Whether the initial password is temporary. When `true`, the admin user is required to change the password on first login.	`true`

Self-hosted deployments: leave these variables empty. The bootstrap admin password is supplied through the first-time setup screen in Designer the first time the platform starts. See Self-hosted initialization for the registration flow.

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 and CORS

The Authorization System is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

Service route

Host group	External path	Backend receives	Example client URL
admin	`/auth`	`/`	`https://admin.{host}/auth/api/...`

The path is set through services.authorization-system.ingress.admin.path (or services.authorization-system.gateway.admin.paths) in the chart values. The /auth prefix is also used by Keycloak (configured separately via global.flowx.idp.keycloak.contextPath); the chart wires both behind the same prefix.

CORS configuration

Environment Variable	Description	Default Value
`APPLICATION_CORS_ALLOW_ORIGIN`	Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Authorization System.	`-`

Allowed methods, allowed headers (including Authorization, Content-Type, Fx-Workspace-Id), and credential handling are baked into the service’s application.yaml with safe defaults. Override these only if you have a non-standard requirement. For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the ingress configuration guide.

Documentation Index

​Database configuration

​CAS client library configuration

​Runtime authorization backend

​OAuth2/Keycloak configuration

​Redis configuration

​Kafka configuration

​Connection settings

​Topic naming configuration

​Audit topic

​Organization events topic

​OAuth authentication (when using SASL_PLAINTEXT)

​Service account realm secrets

​Management

​Organization admin bootstrap

​Primary method (recommended)

​Fallback method

​Error handling

​Keycloak redirect URIs

​Default realm admin credentials

​Customer-specific variables

​Secrets management

​Deployment prerequisites

Infrastructure

Identity & Access

​Architecture notes

​Ingress and CORS

​Service route

​CORS configuration

Database configuration

CAS client library configuration

Runtime authorization backend

OAuth2/Keycloak configuration

Redis configuration

Kafka configuration

Connection settings

Topic naming configuration

Audit topic

Organization events topic

OAuth authentication (when using SASL_PLAINTEXT)

Service account realm secrets

Management

Organization admin bootstrap

Primary method (recommended)

Fallback method

Error handling

Keycloak redirect URIs

Default realm admin credentials

Customer-specific variables

Secrets management

Deployment prerequisites

Architecture notes

Ingress and CORS

Service route

CORS configuration