> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Authorization system setup
> Configure these environment variables for the authorization-system microservice deployment.
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.
```bash Environment Variables theme={"system"}
SPRING_DATASOURCE_URL=jdbc:postgresql://postgresql:5432/authorization_system
SPRING_DATASOURCE_USERNAME=flowx
SPRING_DATASOURCE_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.
```bash Environment Variables theme={"system"}
FLOWX_SPICEDB_HOST=spicedb
FLOWX_SPICEDB_PORT=50051
FLOWX_SPICEDB_TOKEN= # Use Kubernetes Secret
```
The SpiceDB token must match the `preshared_key` value from the [SpiceDB Kubernetes secret](./spicedb#step-3-create-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` |
| `FLOWX_LIB_CASCLIENT_CACHE_WORKSPACEVALIDATION_LOCALTTLSECONDS` | Local cache TTL (seconds) for workspace-validation results in the CAS client library. Shared by every service that embeds the CAS client. | `3600` |
## OAuth2/Keycloak configuration
| Environment Variable | Description | Default Value |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server (internal) | - |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-authorization-system-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Token endpoint, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |
**Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.
***
## 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](/5.1/setup-guides/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
```bash Environment Variables theme={"system"}
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:
```sql theme={"system"}
-- 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:
```bash Environment Variables theme={"system"}
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](./access-management/configuring-an-iam-solution) 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](./organization-manager-setup#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_BASESERVERURL` — 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
* PostgreSQL with `authorization_system` database
* SpiceDB with authentication configured
* Redis for caching
* 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](./ingress-configuration).