Enterprise Single Sign-On
for AI Requests

If your organisation uses Active Directory Federation Services (ADFS) or has a SAML enterprise app in Entra ID, your app can POST the base64-encoded SAML assertion directly to Smartflow. Smartflow fetches the IdP signing certificate from the federation metadata XML, verifies the RSA-SHA256 signature, checks NotOnOrAfter expiry, and extracts the NameID, email, groups, and department from well-known SAML attribute URNs.

Configure via CLI

# ADFS federation metadata URL
curl -X POST https://<your-domain>/api/auth/sso/config \
  -H "Authorization: Bearer <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "saml_idp_metadata_url": "https://adfs.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml",
    "saml_sp_entity_id":    "https://smartflow.contoso.com"
  }'

Exchange a SAML assertion

# Get a SAML assertion from ADFS (your SAML SP logic does this)
# Then pass it to Smartflow in the X-SAML-Assertion header:
curl -X POST https://<your-domain>/api/auth/sso/signin \
  -H "X-SAML-Assertion: <base64-encoded-saml-assertion>"

Domain-joined Windows machines already hold a Kerberos Ticket Granting Ticket (TGT) from AD logon. When a Kerberos-aware client application calls Smartflow, it presents a SPNEGO token in Authorization: Negotiate <token>. Smartflow decodes the ASN.1 GSSAPI wrapper, extracts the client principal (e.g. jsmith@CONTOSO.COM), strips the realm, and returns a Smartflow JWT. An optional LDAP enrichment step can add group memberships and department.

Configure via config.yaml (server-side)

sso:
  kerberos:
    enabled:            true
    service_principal:  "HTTP/smartflow.contoso.com@CONTOSO.COM"
    keytab_path:        "/etc/smartflow/smartflow.keytab"
  admin_groups:
    - "Domain Admins"
    - "Smartflow-Admins"

Client call (browser or app with SSPI/GSSAPI)

# Windows PowerShell — browser does this automatically on intranet
$token = [System.Convert]::ToBase64String(
    (New-Object System.Net.Http.HttpClient).DefaultRequestHeaders.GetValues("Authorization")
)
curl -X POST https://smartflow.contoso.com/api/auth/sso/signin `
  -H "Authorization: Negotiate $token"

If your infrastructure already has an SSO-aware reverse proxy sitting in front of Smartflow (e.g. Nginx with auth_request, an F5 APM, Zscaler App Connector, or AWS ALB with OIDC), configure Smartflow to trust identity headers injected by that proxy. No tokens are validated by Smartflow — it trusts the upstream proxy completely, but only from IPs in your trusted CIDR list.

Configure via config.yaml (or environment variable)

sso:
  trusted_proxy_cidrs:
    - "10.0.0.0/8"        # internal corporate network
    - "172.16.0.0/12"     # private range
    - "192.168.0.0/16"    # private range

Your upstream proxy injects these headers

# Nginx example — after auth_request validates the session cookie:
proxy_set_header  x-smartflow-user-id         $authenticated_user;
proxy_set_header  x-smartflow-user-email      $user_email;
proxy_set_header  x-smartflow-user-groups     $user_groups;     # comma-separated
proxy_set_header  x-smartflow-user-department  $department;

Supported header names (checked in priority order)

# User identity (any of these)
x-smartflow-user-id  |  x-remote-user  |  x-forwarded-user  |  x-authenticated-user  |  x-username

# Supplementary attributes
x-smartflow-user-email       # or x-user-email
x-smartflow-user-groups      # comma-separated CNs — or x-user-groups
x-smartflow-user-department  # or x-user-department
x-user-name                  # or x-display-name

After any SSO validation path succeeds, Smartflow inspects the user's group list against the configured admin_groups patterns. Members of an admin group receive roles ["admin","user"]; everyone else gets ["user"]. Patterns support * wildcards.

Configure admin groups via the Dashboard UI

In SSO Configuration → Auto-provisioned Teams defaults section → enter the group names in the Admin Groups field (one per line, wildcards supported).

Configure via CLI

# Override default admin groups [Smartflow-Admins, IT-Admins, Domain Admins]
curl -X POST https://<your-domain>/api/auth/sso/config \
  -H "Authorization: Bearer <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id":    "contoso.onmicrosoft.com",
    "client_id":    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "admin_groups": ["IT-Admins", "AI-Platform-Admins", "*-SuperAdmin"]
  }'

Default admin groups (if not overridden):

"Smartflow-Admins"  |  "IT-Admins"  |  "Domain Admins"

Your company has 200 developers on Entra ID. You want all Cursor or VS Code Copilot traffic routed through Smartflow, with each developer's AI usage tracked and their team's budget enforced — without issuing 200 API keys.

Setup

You have an internal web application that calls an LLM API. The app sits behind an Nginx reverse proxy that already validates SAML sessions and injects x-remote-user. You want AI calls attributed to real users without changing the app at all.

Nginx config snippet

# Nginx already handles auth_request — add these lines to your location block
location /v1/ {
    auth_request     /auth-validate;
    auth_request_set $authed_user $upstream_http_x_auth_user;

    proxy_pass       http://smartflow:7775;
    proxy_set_header x-remote-user   $authed_user;
    proxy_set_header x-user-groups   $authed_groups;   # set by your auth module
}

# Smartflow trusts this Nginx IP — config.yaml:
sso:
  trusted_proxy_cidrs: ["10.1.0.0/16"]   # IP of Nginx

No changes to the app. Nginx injects the headers → Smartflow reads them → every AI call is logged under the real user's name with their team's policy applied.

A Python microservice runs as a service principal in Entra ID. It uses the client-credentials flow to get an access token, then exchanges it for a Smartflow JWT once per hour and reuses it for all LLM calls during that period.

## Python example — service principal OIDC token exchange
import msal, openai, time

# 1. Acquire Entra ID token via client credentials
app = msal.ConfidentialClientApplication(
    client_id="<app-client-id>",
    client_credential="<app-secret>",
    authority="https://login.microsoftonline.com/<tenant-id>"
)
result = app.acquire_token_for_client(scopes=["api://<app-client-id>/.default"])
entra_token = result["access_token"]

# 2. Exchange for Smartflow JWT
import requests
resp = requests.post(
    "https://<your-domain>/api/auth/sso/signin",
    headers={"Authorization": f"Bearer {entra_token}"}
)
sf_token = resp.json()["token"]
expires_at = time.time() + resp.json()["expires_in"] - 60  # 1 min buffer

# 3. Use for all OpenAI-compatible calls through Smartflow
client = openai.OpenAI(
    api_key=sf_token,
    base_url="https://<your-domain>/v1"
)
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarise this contract..."}]
)

Check current SSO config

curl https://<your-domain>/api/auth/sso/config \
  -H "Authorization: Bearer <admin-key>"

# Returns: { "success": true, "config": { "tenant_id": "...", "client_id": "..." } }
# If not configured: { "success": false, "error": "Not configured" }

Generate an SSO login URL (test the config is wired correctly)

curl https://<your-domain>/api/auth/sso/login
# Returns: { "auth_url": "https://login.microsoftonline.com/..." }
# Paste the auth_url in a browser — should redirect to Microsoft login

Test token exchange manually

# Decode any Smartflow JWT to inspect claims (no secret needed for base64):
echo "eyJhbGci..." | cut -d. -f2 | base64 -d 2>/dev/null | python3 -m json.tool

# Should show: sub, username, email, groups, roles, auth_method, exp

Common issues