Reference Guide

Step-by-step reference implementations for common enterprise scenarios. These are provided as working examples — you are not required to use Keycloak or any specific technology. FlowSquad works with any SAML 2.0, LDAP, or OAuth2 provider.

1. Overview

2. Keycloak — SAML 2.0 Configuration

This walkthrough uses Keycloak 23.x / 24.x. The same FlowSquad SP endpoints apply to any SAML 2.0–compliant IdP — only the IdP-side UI steps differ.

Step 1 — Create the SAML client in Keycloak

1. Log in to Keycloak Admin Console → select your realm → Clients → Create client
2. Set Client type: SAML  (not OpenID Connect)
3. Set Client ID to the FlowSquad public URL ending in /saml/metadata:

   https://flowsquad.yourcompany.com/saml/metadata

   This value is also shown in FlowSquad → Setup Wizard → Step 4 → SAML → Entity ID / Client ID box.
4. Set Name: FlowSquad Enterprise → click Save

Step 2 — Configure client settings in Keycloak

In the Settings tab of the new client (replace the hostname with yours):

Root URL:                    https://flowsquad.yourcompany.com
Home URL:                    https://flowsquad.yourcompany.com
Valid redirect URIs:         https://flowsquad.yourcompany.com/saml/callback
Master SAML Processing URL:  https://flowsquad.yourcompany.com/saml/callback
IDP-Initiated SSO URL name:  flowsquad

Under SAML Capabilities:

Name ID format:           email
Sign documents:           ON
Sign assertions:          ON
Signature algorithm:      RSA_SHA256
SAML signature key name:  KEY_ID
Canonicalization method:  EXCLUSIVE
Force POST binding:       OFF   (leave OFF — FlowSquad uses Redirect binding by default)
Encrypt assertions:       OFF   (optional)

Click Save.

Logout Service POST Binding URL:     https://flowsquad.yourcompany.com/saml/logout
Logout Service Redirect Binding URL: https://flowsquad.yourcompany.com/saml/logout

Step 3 — Add attribute mappers

FlowSquad expects attributes named email, firstName, and lastName with SAML Attribute NameFormat: Basic. These must be added to the dedicated client scope, not directly to the client.

Create these four mappers (one at a time). For each: fill in Name, Property, SAML Attribute Name, set SAML Attribute NameFormat to Basic, click Save.

Step 4 — Configure FlowSquad

1. Open Setup Wizard → Step 4: Authentication → SAML 2.0 SSO (click the section header to expand)
2. Fill in the three required fields:

3. Click Test Connection — this checks the SP Entity ID format, validates the certificate, and confirms the IdP URL is reachable from the server. Review any warnings before proceeding.
4. Click Save Configuration.

Step 5 (Optional) — Enable SAML Request Signing

Request signing adds a cryptographic signature to every SAML AuthnRequest so Keycloak can verify it originated from FlowSquad. Required by some security policies.

1. In FlowSquad SAML section, click Generate SP Certificate & Key → then Download SP Certificate → save saml_sp_cert.pem
2. In Keycloak: Clients → FlowSquad Enterprise → Keys tab → Import Certificate → Archive Format: Certificate PEM → upload the file
3. Back in FlowSquad, enable Enable SAML Request Signing → click Save Configuration

Step 6 — Verify end-to-end login

1. Complete the remaining Setup Wizard steps and open the FlowSquad login page
2. Click Login with SAML → you are redirected to Keycloak
3. Authenticate with a test user → you are redirected back and logged in to FlowSquad
4. In Admin Panel → Users confirm the user’s Auth Source shows SAML

Optional — Group-based role assignment

Add a Group List mapper to the dedicated client scope (same location as Step 3):

Mapper type:               Group list
Name:                      groups
Group attribute name:      groups
SAML Attribute NameFormat: Basic
Single Group Attribute:    OFF
Full group path:           OFF

The attribute name groups matches FlowSquad’s default Groups attribute name field. Create groups in Keycloak (e.g. FlowSquad-Admins) and assign users to them.

Troubleshooting

3. Keycloak — OAuth2 / OIDC Configuration

Use this when you want users to log in to FlowSquad via "Login with Keycloak" using OpenID Connect (OAuth2). Unlike SAML, OIDC uses redirect-based token flows and is simpler to configure.

Step 1: Create an OIDC Client in Keycloak

1. Keycloak Admin → select your realm → Clients → Create client
2. Fill in:

Client type:  OpenID Connect
Client ID:    flowsquad-oauth2
Name:         FlowSquad OAuth2

3. Click Next → on the Capability config page:
   • Client authentication: ON (this makes it a Confidential client, enabling a Client Secret)
   • Authentication flow: Standard flow (Authorization Code)
4. Click Next → on the Login settings page:
   • Valid redirect URIs: https://flowsquad.yourcompany.com/oauth2/keycloak/callback
   • Web origins: https://flowsquad.yourcompany.com
5. Click Save

Step 2: Retrieve the Client Secret

1. In the client you just created, open the Credentials tab
2. Copy the Client Secret value

Step 3: Configure FlowSquad

1. Open Setup Wizard → Step 4: Authentication → OAuth2 → Keycloak
2. Fill in:

Keycloak Server URL:  https://keycloak.yourcompany.com
Realm:                master   (or your custom realm name)
Client ID:            flowsquad-oauth2
Client Secret:        (paste from Credentials tab)

3. Click Test Connection to confirm Keycloak responds, then click Save

Step 4: Verify Login

1. Navigate to the FlowSquad login page → a "Login with Keycloak" button appears
2. Click it → you are redirected to the Keycloak login page → authenticate → you are redirected back and logged in
3. In Admin Panel → Users, the user’s Auth Source shows OAuth2 / Keycloak

4. Keycloak — LDAP User Federation

Keycloak can federate users from Active Directory or OpenLDAP into its realm. Once configured, FlowSquad connects to Keycloak as its LDAP provider — meaning all directory lookups go through Keycloak rather than directly to your AD/LDAP server.

Step 1: Add LDAP Federation to Keycloak

1. Keycloak Admin → select your realm → User Federation → Add provider → LDAP
2. Fill in the connection settings:

Vendor:               Active Directory  (or Other for OpenLDAP)
Connection URL:       ldap://ad.yourcompany.com:389
                      (use ldaps://ad.yourcompany.com:636 for encrypted)
Bind DN:              CN=svc-keycloak,OU=ServiceAccounts,DC=yourcompany,DC=com
Bind Credential:      (service account password)
Users DN:             OU=Users,DC=yourcompany,DC=com
UUID LDAP attribute:  objectGUID   (Active Directory) or entryUUID (OpenLDAP)
User object classes:  person, organizationalPerson, user

3. Click Test connection and Test authentication to validate
4. Click Save → click Sync all users to import directory users into the Keycloak realm

Step 2: Configure Attribute Mappers in Keycloak

Ensure the LDAP provider maps the correct attributes. In the LDAP federation settings → Mappers tab, verify that at minimum the following are mapped:

username   →  sAMAccountName (AD) or uid (OpenLDAP)
email      →  mail
firstName  →  givenName
lastName   →  sn

Step 3: Connect FlowSquad to Keycloak LDAP

Once Keycloak is federating your AD/LDAP users, FlowSquad can authenticate against Keycloak using either of two approaches:

• SAML or OAuth2 (recommended) — users authenticate at Keycloak (which validates against AD/LDAP internally) and are redirected back to FlowSquad. Follow the Keycloak SAML or OAuth2 steps above.
• Direct LDAP to Keycloak’s LDAP interface — point FlowSquad’s LDAP configuration at Keycloak’s built-in LDAP server (ldap://keycloak.yourcompany.com:10389 by default if enabled). This approach is less common and requires enabling the LDAP feature in Keycloak.

For most deployments, configuring Keycloak SAML or OIDC (sections above) and enabling LDAP federation inside Keycloak is the cleanest architecture.

5. nginx Reverse Proxy with HTTPS

Use this configuration to run FlowSquad on port 5000 (the default) behind nginx on port 443, with nginx handling TLS termination. This is the recommended pattern for Linux and Docker deployments.

Prerequisites

• nginx 1.18+ installed on the server or in a container alongside FlowSquad
• A TLS certificate and private key (Let’s Encrypt / Certbot, or a corporate CA-issued certificate)
• DNS pointing your FlowSquad domain to the nginx server’s public IP
• Ports 80 and 443 open in the firewall

Obtaining a Certificate with Certbot (Let’s Encrypt)

# Install Certbot
sudo apt install certbot python3-certbot-nginx   # Ubuntu/Debian
sudo dnf install certbot python3-certbot-nginx   # RHEL/Rocky

# Issue certificate (replace with your domain)
sudo certbot --nginx -d flowsquad.yourcompany.com

# Certbot writes the certificate to:
#   /etc/letsencrypt/live/flowsquad.yourcompany.com/fullchain.pem
#   /etc/letsencrypt/live/flowsquad.yourcompany.com/privkey.pem

nginx Configuration

Create /etc/nginx/sites-available/flowsquad (Ubuntu/Debian) or /etc/nginx/conf.d/flowsquad.conf (RHEL/Rocky):

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name flowsquad.yourcompany.com;
    return 301 https://$host$request_uri;
}

# HTTPS termination and proxy to FlowSquad
server {
    listen 443 ssl http2;
    server_name flowsquad.yourcompany.com;

    # TLS certificate (Let's Encrypt / Certbot)
    ssl_certificate     /etc/letsencrypt/live/flowsquad.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/flowsquad.yourcompany.com/privkey.pem;

    # Modern TLS settings (TLS 1.2 + 1.3 only)
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 1d;

    # Security headers
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
    add_header X-Frame-Options           SAMEORIGIN always;
    add_header X-Content-Type-Options    nosniff always;

    # Proxy to FlowSquad (adjust port if different)
    location / {
        proxy_pass         http://127.0.0.1:5000;
        proxy_http_version 1.1;

        # CRITICAL: do NOT let nginx rewrite Location headers from FlowSquad.
        # Without this line, nginx rewrites 302 responses that point to an
        # external Identity Provider (Keycloak, Okta, Azure AD, etc.) during
        # SAML SSO and OAuth2 login, replacing the IdP hostname with the
        # FlowSquad hostname.  The browser then follows the rewritten redirect
        # back to FlowSquad instead of the IdP and receives a 404.
        proxy_redirect     off;

        # Required for SSE / streaming AI responses
        proxy_buffering    off;
        proxy_cache        off;

        # WebSocket support (used by FlowSquad real-time features)
        proxy_set_header   Upgrade    $http_upgrade;
        proxy_set_header   Connection "upgrade";

        # Pass real client IP to FlowSquad
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;

        # Timeouts for long-running AI generation requests
        proxy_connect_timeout  60s;
        proxy_send_timeout     300s;
        proxy_read_timeout     300s;
    }
}

Enable and Reload nginx

# Ubuntu/Debian -- create symlink and reload
sudo ln -s /etc/nginx/sites-available/flowsquad /etc/nginx/sites-enabled/
sudo nginx -t               # test config syntax
sudo systemctl reload nginx

# RHEL/Rocky -- just test and reload (conf.d is auto-loaded)
sudo nginx -t
sudo systemctl reload nginx

Verifying the Configuration

# Confirm HTTPS redirects correctly
curl -I http://flowsquad.yourcompany.com          # Should return 301 to HTTPS
curl -I https://flowsquad.yourcompany.com         # Should return 200

# Check TLS grade at https://www.ssllabs.com/ssltest/

6. IIS Reverse Proxy with HTTPS (Windows Server)

Use IIS Application Request Routing (ARR) and URL Rewrite to proxy requests from HTTPS (port 443) to FlowSquad running on port 5000. This is the standard approach for Windows Server environments.

Prerequisites

• Windows Server 2016 / 2019 / 2022 with IIS installed
• IIS Application Request Routing (ARR) 3.0 installed
• IIS URL Rewrite 2.1 installed
• A TLS certificate bound to the IIS site (corporate CA, self-signed, or win-acme / WACS for Let’s Encrypt)
• FlowSquad running on http://localhost:5000

Step 1: Enable ARR Proxy

1. Open IIS Manager → click on the server node (top-level)
2. Double-click Application Request Routing Cache
3. In the right-hand Actions pane, click Server Proxy Settings
4. Check Enable proxy → click Apply

Step 2: Create a New IIS Website for FlowSquad

1. In IIS Manager → Sites → Add Website
2. Fill in:
   • Site name: FlowSquad
   • Physical path: any local folder (e.g. C:\inetpub\flowsquad) — IIS needs a physical path even for a pure proxy site
   • Binding type: https, Port: 443, Host name: flowsquad.yourcompany.com
   • SSL certificate: select your certificate from the dropdown
3. Click OK

Step 3: Add URL Rewrite Rules

1. Select the FlowSquad site in IIS Manager
2. Double-click URL Rewrite
3. Click Add Rule(s) → Reverse Proxy
4. Enter the backend server URL: localhost:5000 → click OK

Alternatively, create the rule manually by editing web.config in the site root:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <!-- WebSocket upgrade (FlowSquad real-time features) -->
        <rule name="FlowSquad-WebSocket" stopProcessing="true">
          <match url="(.*)" />
          <conditions>
            <add input="{HTTP_UPGRADE}" pattern="websocket" />
          </conditions>
          <serverVariables>
            <set name="HTTP_X_FORWARDED_PROTO" value="https" />
            <set name="HTTP_X_FORWARDED_HOST"  value="{HTTP_HOST}" />
          </serverVariables>
          <action type="Rewrite" url="http://localhost:5000/{R:1}" />
        </rule>
        <!-- All other requests -->
        <rule name="FlowSquad-Proxy" stopProcessing="true">
          <match url="(.*)" />
          <serverVariables>
            <set name="HTTP_X_FORWARDED_PROTO" value="https" />
            <set name="HTTP_X_FORWARDED_HOST"  value="{HTTP_HOST}" />
          </serverVariables>
          <action type="Rewrite" url="http://localhost:5000/{R:1}" />
        </rule>
      </rules>
      <outboundRules>
        <!--
          SAML / OAuth2 IdP redirect passthrough.
          Any Location header pointing to an external https:// host is an IdP
          redirect (SAML AuthnRequest or OAuth2 authorization endpoint).
          stopProcessing="true" prevents subsequent rules and ARR's built-in
          host rewriter from touching it.
        -->
        <rule name="FlowSquad-PreserveIdPLocation"
              preCondition="ResponseIsRedirect"
              stopProcessing="true">
          <match serverVariable="RESPONSE_Location"
                 pattern="^https://(?!localhost)" />
          <action type="None" />
        </rule>
        <!--
          Safety net: rewrite any Location that still carries the raw backend
          address (http://localhost:5000/...) to the public HTTPS URL.
          Uses {HTTP_HOST} so this config works for any hostname without edits.
        -->
        <rule name="FlowSquad-RewriteLocalhostLocation"
              preCondition="ResponseIsRedirect">
          <match serverVariable="RESPONSE_Location"
                 pattern="^http://localhost:5000/(.*)" />
          <action type="Rewrite"
                  value="https://{HTTP_HOST}/{R:1}" />
        </rule>
        <preConditions>
          <preCondition name="ResponseIsRedirect">
            <add input="{RESPONSE_STATUS}" pattern="3[0-9][0-9]" />
          </preCondition>
        </preConditions>
      </outboundRules>
    </rewrite>
    <security>
      <requestFiltering>
        <requestLimits maxAllowedContentLength="104857600" />
      </requestFiltering>
    </security>
  </system.webServer>
</configuration>

Step 4: HTTP to HTTPS Redirect (Optional but Recommended)

1. In IIS Manager → Sites → Add Website → create a second site:
   • Site name: FlowSquad-HTTP-Redirect
   • Binding type: http, Port: 80, Host name: flowsquad.yourcompany.com
2. Select that site → URL Rewrite → Add Rule → Blank rule:
   • Name: Redirect HTTP to HTTPS
   • Match URL: .*
   • Action type: Redirect
   • Redirect URL: https://flowsquad.yourcompany.com/{R:0}
   • Redirect type: Permanent (301)

Step 5: Add Security Response Headers

1. Select the FlowSquad HTTPS site → double-click HTTP Response Headers
2. Add the following headers:

Strict-Transport-Security:  max-age=63072000; includeSubDomains
X-Frame-Options:            SAMEORIGIN
X-Content-Type-Options:     nosniff

Verifying the Configuration

# In Windows PowerShell -- check HTTPS responds correctly
Invoke-WebRequest -Uri "https://flowsquad.yourcompany.com" -UseBasicParsing

# Check that HTTP redirects to HTTPS
Invoke-WebRequest -Uri "http://flowsquad.yourcompany.com" -MaximumRedirection 0 -ErrorAction SilentlyContinue | Select-Object StatusCode, Headers

Binding an SSL Certificate Issued by a Corporate CA

1. Import the certificate and its full chain into the Local Computer → Personal certificate store: certlm.msc → Personal → Certificates → right-click → All Tasks → Import
2. In IIS Manager → select the FlowSquad HTTPS site → Bindings → Edit → select the imported certificate from the SSL certificate dropdown