Cloud Setup

End-to-end walkthrough for wiring SAML SSO into a flxbl-managed cloud deployment.

---

How cloud SSO works

Cloud deployments use a two-level architecture:

1. Global auth (auth.flxbl.io) — managed by flxbl; handles the actual SAML round-trip with your IdP.

2. Your tenant — stores the provider ID locally so the CLI, web UI, and desktop app can auto-detect SSO settings.

You configure the IdP once with auth.flxbl.io URLs, flxbl registers it in global auth, and you store the resulting provider ID on your tenant.

---

Prerequisites

• A running cloud-hosted sfp tenant.

• Admin access to your SAML identity provider.

• An owner-level JWT for the sfp API. The admin user created by sfp server init has the owner role, which is what /sfp/api/sso/providers requires. Application tokens (UUID-format, created via sfp server application-token create) are explicitly rejected on this endpoint — only the user JWT works.

  # Sign in once; the token is stored in your OS keyring under service
  # `sfp-pro`, account `supabase-token-<your-email>`.
  sfp server auth login --admin \
    --email admin@<tenant>.local \
    --sfp-server-url https://<your-domain>
  
  # Extract it into a shell variable for the curl calls below.
  export SFP_JWT=$(sfp server auth display --email admin@<tenant>.local --jwt)

  Headless / WSL / SSH session? The keyring backend needs an active D-Bus session and a running gnome-keyring-daemon (or equivalent). If sfp server auth display --jwt errors with no secret service provider or dbus session found, prefix with dbus-launch or run from a graphical session.

---

Step 1 — Configure your IdP

Create the SAML application in your IdP using the cloud URLs:

Field	Value
Entity ID	https://auth.flxbl.io/auth/v1/sso/saml/metadata
ACS URL	https://auth.flxbl.io/auth/v1/sso/saml/acs

These URLs always point at auth.flxbl.io — the global auth instance — regardless of your tenant domain.

Pick the matching IdP guide and use the cloud URLs in place of the self-hosted ones:

• Microsoft Entra ID

• Okta

When you finish, you should have a federation metadata URL.

---

Step 2 — Request global registration

flxbl needs to register the IdP at the global auth level. Open a support request with:

• The federation metadata URL from Step 1.

• The email domain(s) you want to enable SSO for (e.g. company.com).

flxbl will register the IdP and reply with a provider UUID.

---

Step 3 — Store the provider ID on your tenant

Once you have the UUID, register it locally so your tenant can auto-detect SSO configuration:

curl -X POST "https://<your-domain>/sfp/api/sso/providers" \
  -H "Authorization: Bearer $SFP_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "metadataUrl": "<idp-metadata-url>",
    "domains": ["company.com"],
    "providerId": "<global-provider-uuid>"
  }'

The providerId field tells the server the registration was already done at the global level — it just stores the ID locally for auto-detection.

Verify

curl "https://<your-domain>/sfp/api/config"
# -> sso.domain and sso.providerId are populated

---

Step 4 — Provision users

Self-registration is disabled by default, so users must be created before they can sign in:

curl -X POST "https://<your-domain>/sfp/api/users" \
  -H "Authorization: Bearer $SFP_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "team": "<team-slug>",
    "role": "member"
  }'

Or via the CLI:

sfp server user add \
  --firstname John \
  --lastname Doe \
  --target-email [email protected] \
  --team <team-slug> \
  --role member \
  --email admin@<tenant>.local \
  --sfp-server-url https://<your-domain>

The endpoint is idempotent — re-running it for an existing user just adds team membership and links the SSO identity if needed.

---

Step 5 — Sign in

CLI

sfp set server-url https://<your-domain> --global
sfp set server-email [email protected] --global
sfp auth login --provider saml

The CLI fetches the SSO domain and provider ID from /sfp/api/config, opens your browser, and completes the SAML round-trip via auth.flxbl.io. Tokens are refreshed automatically; force a refresh with:

sfp auth refresh --email [email protected]

Web UI

Open https://<your-domain> in a browser. The login screen pre-fills the SSO domain. Click Continue to redirect to your IdP via auth.flxbl.io.

Desktop app

Open the desktop app and sign in with SAML. The IdP redirect is captured through the app's custom protocol handler.

---

Something not working?

See Troubleshooting.