Control Plane Setup

This guide assumes you have already completed the Enterprise Edition installation.

After installing Formance Enterprise Edition, you need to configure the control plane components: Dex (OIDC provider), Membership (management API), and Console (web interface).

Components Overview

Component	Description	Default URL
Dex	OIDC/OAuth2 provider for authentication	`dex.<your-domain>`
Membership	Management API for organizations, users, and stacks	`membership.<your-domain>`
Console	Web interface for managing your Formance stack	`console.<your-domain>`

Dex Configuration

Dex is deployed as the default OIDC provider. You can configure it to:

Create local users for testing
Connect to external identity providers (SAML, LDAP, OAuth2)
Integrate with your existing SSO infrastructure

Default Configuration

The default Dex configuration creates a simple setup for testing with a static admin user. For production, configure your own identity provider.

Connecting to External Identity Providers

Dex configuration is set through cloudprem.membership.dex.configOverrides, which merges with the default Dex configuration generated by the Membership chart.

Configure SAML Provider

# values.yaml
cloudprem:
  membership:
    dex:
      configOverrides:
        connectors:
          - type: saml
            id: saml
            name: SAML
            config:
              ssoURL: https://your-idp.example.com/sso
              ca: /path/to/ca.pem
              redirectURI: https://dex.your-domain.com/callback
              usernameAttr: name
              emailAttr: email

Configure LDAP Provider

# values.yaml
cloudprem:
  membership:
    dex:
      configOverrides:
        connectors:
          - type: ldap
            id: ldap
            name: LDAP
            config:
              host: ldap.example.com:636
              insecureNoSSL: false
              bindDN: cn=admin,dc=example,dc=com
              bindPW: admin-password
              userSearch:
                baseDN: ou=users,dc=example,dc=com
                filter: "(objectClass=person)"
                username: uid
                idAttr: uid
                emailAttr: mail
                nameAttr: cn

Configure OAuth2 Provider (Okta, Auth0, etc.)

# values.yaml
cloudprem:
  membership:
    dex:
      configOverrides:
        connectors:
          - type: oidc
            id: okta
            name: Okta
            config:
              issuer: https://your-org.okta.com
              clientID: your-client-id
              clientSecret: your-client-secret
              redirectURI: https://dex.your-domain.com/callback
              scopes:
                - openid
                - profile
                - email

Using Your Own OIDC Provider

If you already have an OIDC provider (e.g., Keycloak), you can bypass Dex entirely:

# values.yaml
global:
  platform:
    membership:
      relyingParty:
        scheme: "https"
        host: "keycloak.example.com"
        path: "/realms/master"

cloudprem:
  membership:
    dex:
      enabled: false
    config:
      oidc:
        clientId: "membership"
        clientSecret: "your-client-secret"
        scopes:
          - openid
          - email
          - federated:id

The global.platform.membership.relyingParty defines the OIDC issuer URL. Use the path field when your provider uses a sub-path (e.g., Keycloak realms).

Membership Configuration

You can customize authentication behavior and stack defaults:

cloudprem:
  membership:
    config:
      oidc:
        clientId: "membership"
        clientSecret: "changeMe"
        scopes:
          - openid
          - email
          - federated:id
      auth:
        loginWithSSO: false  # Enable email-based SSO selector
        tokenValidity:
          accessToken: "5m"
          refreshToken: "72h"
      stack:
        minimalStackModules:
          - Auth
          - Ledger
          - Gateway
        additionalModules:
          - Payments
          - Stargate
      fctl: true  # Enable fctl CLI support

Service Ports

Service	Port	Protocol
Membership	8080	HTTP
Membership	8082	gRPC
Dex	5556	HTTP
Portal	3000	HTTP
Console V3	3000	HTTP

Initial Setup with Membership CLI

The Membership CLI provides commands to configure your self-hosted deployment. You run these commands directly inside the Membership container.

Accessing the Membership CLI

Connect to the Membership container:

kubectl exec -it -n formance-system deployment/membership -- sh

Quick Setup (Recommended)

Use the configuration init command for an all-in-one setup:

membership configuration init \
  --region-name "default" \
  --region-base-url "https://formance.your-domain.com" \
  --production \
  --org-name "My Company" \
  --admin-email "admin@your-company.com" \
  --stack-name "production"

This command creates:

A region for your deployment
An organization
An admin user
A stack ready to use

Check Database Connection

Before running any configuration, verify the database connection:

membership configuration check

This displays the connection status and migration state.

Manual Setup

If you prefer to configure each component separately:

Create a Region

membership configuration region create \
  --name "default" \
  --base-url "https://formance.your-domain.com" \
  --production

List existing regions:

membership configuration region list

Create an Organization

membership configuration org create \
  --name "My Company"

List organizations:

membership configuration org list

Create a User

membership configuration user create \
  --email "admin@your-company.com" \
  --org "My Company" \
  --role ADMIN

Available roles:

ADMIN - Full access
GUEST - Read-only access

List users:

membership configuration user list --org "My Company"

Create a Stack

membership configuration stack create \
  --name "production" \
  --org "My Company" \
  --region "default"

List stacks:

membership configuration stack list

JSON Output

All commands support the --json flag for scripting:

membership configuration region list --json
membership configuration org list --json
membership configuration stack list --json

Available Commands Reference

membership configuration
├── check              # Verify database connection and status
├── init               # All-in-one setup command
├── region
│   ├── create         # Create a new region
│   ├── list           # List all regions
│   └── delete         # Delete a region
├── org
│   ├── create         # Create an organization
│   └── list           # List organizations
├── stack
│   ├── create         # Create a stack
│   ├── list           # List stacks
│   └── delete         # Delete a stack
└── user
    ├── create         # Create a user
    └── list           # List users

Configure Organization with fctl

After the initial setup, you can use fctl for additional configuration.

fctl login --membership-uri https://membership.<your-domain>/api

fctl cloud organizations update <ORGANIZATION_ID> \
  --domain=your-company.com \
  --default-organization-role=GUEST \
  --default-stack-role=GUEST

Wizard Bootstrap (Alternative to CLI)

Instead of using the Membership CLI, you can auto-create users, organizations, regions, and stacks on first install using the wizard in your values file:

cloudprem:
  membership:
    dex:
      configOverrides:
        staticPasswords:
          - email: "admin@example.com"
            hash: "$2a$10$..."  # bcrypt hash of password
            username: "admin"
            userID: "unique-uuid"
            role: ADMIN
    config:
      wizard:
        setup: |
          users:
            - id: "unique-uuid"
              email: "admin@example.com"
              role: "ADMIN"
          organizations:
            - id: "my-org"
              ownerId: "unique-uuid"
              name: "My Organization"
          regions:
            - id: "region-1"
              name: "production"
              organizationId: "my-org"
              baseUrl: "https://formance.example.com"
          stacks:
            - id: "main"
              name: "main"
              organizationId: "my-org"
              regionId: "region-1"
              version: "v3.1"

The wizard job runs once on first install and creates all the configured resources. This is the approach used by the ee-demo.yaml profile.

Accessing the Console

After setup, access the Console at:

https://console.<your-domain>

Verifying the Setup

Check Component Health

# Check all pods are running
kubectl get pods -n formance-system

# Check services
kubectl get svc -n formance-system

# Check ingresses
kubectl get ingress -n formance-system

Test Authentication

# Test Dex
curl -I https://dex.<your-domain>/.well-known/openid-configuration

# Test Membership API
curl -I https://membership.<your-domain>/api/_info

# Test Console
curl -I https://console.<your-domain>

Troubleshooting

Cannot access Console

Verify ingress is configured:

kubectl get ingress -n formance-system

Check TLS certificate:

kubectl describe certificate -n formance-system

Check Console logs:

kubectl logs -n formance-system -l app=console

Authentication fails

Check Dex configuration:

kubectl get secret -n formance-system membership-dex-config -o jsonpath='{.data.config\.yaml}' | base64 -d

Verify Dex is accessible:

curl https://dex.<your-domain>/.well-known/openid-configuration

Check Dex logs:

kubectl logs -n formance-system -l app.kubernetes.io/name=dex

Membership CLI errors

Check database connection from inside the container:

kubectl exec -it -n formance-system deployment/membership -- membership configuration check

Check Membership logs:

kubectl logs -n formance-system -l app=membership

Verify PostgreSQL is running:

kubectl get pods -n formance-system -l app.kubernetes.io/name=postgresql

Deployment

Components Overview

Dex Configuration

Default Configuration

Connecting to External Identity Providers

Using Your Own OIDC Provider

Membership Configuration

Service Ports

Initial Setup with Membership CLI

Accessing the Membership CLI

Quick Setup (Recommended)

Check Database Connection

Manual Setup

Create a Region

Create an Organization

Create a User

Create a Stack

JSON Output

Available Commands Reference

Configure Organization with fctl

Wizard Bootstrap (Alternative to CLI)

Accessing the Console

Verifying the Setup

Check Component Health

Test Authentication

Troubleshooting

Next Steps

Infrastructure Services

Deploy a Stack

Deployment

​Components Overview

​Dex Configuration

​Default Configuration

​Connecting to External Identity Providers

​Using Your Own OIDC Provider

​Membership Configuration

​Service Ports

​Initial Setup with Membership CLI

​Accessing the Membership CLI

​Quick Setup (Recommended)

​Check Database Connection

​Manual Setup

​Create a Region

​Create an Organization

​Create a User

​Create a Stack

​JSON Output

​Available Commands Reference

​Configure Organization with fctl

​Login to Your Cluster

​Configure Auto-Login for Your Domain

​Wizard Bootstrap (Alternative to CLI)

​Accessing the Console

​Verifying the Setup

​Check Component Health

​Test Authentication

​Troubleshooting

​Next Steps

Infrastructure Services

Deploy a Stack

Components Overview

Dex Configuration

Default Configuration

Connecting to External Identity Providers

Using Your Own OIDC Provider

Membership Configuration

Service Ports

Initial Setup with Membership CLI

Accessing the Membership CLI

Quick Setup (Recommended)

Check Database Connection

Manual Setup

Create a Region

Create an Organization

Create a User

Create a Stack

JSON Output

Available Commands Reference

Configure Organization with fctl

Login to Your Cluster

Configure Auto-Login for Your Domain

Wizard Bootstrap (Alternative to CLI)

Accessing the Console

Verifying the Setup

Check Component Health

Test Authentication

Troubleshooting

Next Steps