# 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.

  ```bash
  # 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](/flxbl/sfp-server/setting-up/saml-authentication/identity-providers/entra-id.md)
* [Okta](/flxbl/sfp-server/setting-up/saml-authentication/identity-providers/okta.md)

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:

```bash
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

```bash
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:

```bash
curl -X POST "https://<your-domain>/sfp/api/users" \
  -H "Authorization: Bearer $SFP_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "firstName": "John",
    "lastName": "Doe",
    "team": "<team-slug>",
    "role": "member"
  }'
```

Or via the CLI:

```bash
sfp server user add \
  --firstname John \
  --lastname Doe \
  --target-email john.doe@company.com \
  --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

```bash
sfp set server-url https://<your-domain> --global
sfp set server-email user@company.com --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:

```bash
sfp auth refresh --email user@company.com
```

### 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](/flxbl/sfp-server/setting-up/saml-authentication/troubleshooting.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp-server/setting-up/saml-authentication/cloud-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.