# JumpCloud SSO (SAML)

Configure JumpCloud as a SAML 2.0 identity provider for Brizz

Set up JumpCloud as your SAML 2.0 identity provider so your team can sign in to Brizz with their JumpCloud credentials. Supports both SP-initiated login (from the Brizz login page) and IdP-initiated login (from the JumpCloud User Portal).

## Prerequisites

- A JumpCloud admin account
- A Brizz **Organization Admin** role
- **SSO enabled** for your Brizz organization (contact Brizz support if the SSO settings page shows "SSO is not enabled")
- Your organization's email domain(s) registered on your tenant (required for SP-initiated discovery by email)

## Step 1: Create the SAML application in JumpCloud

1. In the JumpCloud Admin Console, go to **User Authentication > SSO Applications**.
2. Click **+ Add New Application**, search for **Custom SAML App**, then **Next**.
3. Set a **Display Label** (e.g. "Brizz") and click **Next**.

## Step 2: Configure SP settings

You'll need the **SP Entity ID** and **ACS URL** from Brizz. Both are shown on the SSO settings page in Brizz (**Settings > SSO**). For your tenant they are:

- **SP Entity ID**: `https://platform.brizz.dev/api/v1/saml/your-tenant`
- **ACS URL**: `https://platform.brizz.dev/api/v1/saml/your-tenant/acs`

In the JumpCloud SAML app, on the **SSO** tab:

| Field | Value |
| --- | --- |
| **SP Entity ID** | Paste from Brizz |
| **ACS URL** | Paste from Brizz |
| **SAMLSubject NameID** | `email` |
| **SAMLSubject NameID Format** | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` |
| **Signature Algorithm** | `RSA-SHA256` |
| **Sign Assertion** | Checked |
| **Default RelayState** | *(leave blank)* |
| **Login URL** *(for IdP-initiated)* | `https://sso.jumpcloud.com/saml2/<your-app-name>` |

> Setting the **Login URL** is what makes the app tile appear (and work) in users' JumpCloud User Portal — required for IdP-initiated login.

## Step 3: Configure user attributes

Under **Attributes**, add the following — these match Brizz's default attribute mappings:

| Service Provider Attribute Name | JumpCloud Attribute Name |
| --- | --- |
| `email` | `email` |
| `firstName` | `firstname` |
| `lastName` | `lastname` |
| `displayName` | `displayname` |

Click **Activate** to save the application. JumpCloud will prompt you to download the **IdP metadata XML** or copy the **IdP Metadata URL** — keep this handy for the next step.

## Step 4: Assign users

On the **User Groups** tab of the SAML app, assign the groups (or individual users on the **Users** tab) that should be able to sign in to Brizz. Users must be assigned before they can authenticate.

## Step 5: Connect JumpCloud in Brizz

1. In Brizz, go to **Settings > SSO**.
2. Paste the **IdP Metadata URL** from JumpCloud and click **Save**. Brizz will fetch the IdP Entity ID, SSO URL, and signing certificate automatically.
3. Toggle **Enable SAML** on.
4. Click **Test Connection** to verify the certificate and metadata are valid.

If you don't have a metadata URL, you can configure manually instead — paste the **IdP Entity ID**, **IdP SSO URL**, and the signing **certificate** (PEM format) from JumpCloud.

## Step 6: Sign in

### SP-initiated (from Brizz)

1. Go to the Brizz login page.
2. Click **Sign in with SSO** and enter your work email.
3. Brizz discovers your tenant by email domain and redirects to JumpCloud to authenticate.

### IdP-initiated (from JumpCloud)

1. Open the JumpCloud **User Portal**.
2. Click the **Brizz** application tile.
3. JumpCloud posts the assertion to Brizz and you land in the dashboard.

## Just-in-Time provisioning

By default, **JIT provisioning** is enabled — users assigned to the SAML app in JumpCloud are automatically created in Brizz on first login, with the default role configured on the SSO settings page. To require pre-existing users, disable **Allow JIT** in the SSO settings.

## Troubleshooting

| Symptom | Likely cause |
| --- | --- |
| `sso_disabled` on the login page after redirect | SSO feature flag is off for your organization — contact Brizz support |
| `saml_error` after IdP redirect | SP Entity ID, ACS URL, or signing certificate mismatch — re-check Steps 2 and 5, and use **Refresh Metadata** in Brizz |
| Tile missing in JumpCloud User Portal | **Login URL** not set on the JumpCloud SAML app (Step 2) |
| User redirected but never reaches dashboard | `Platform.URL` misconfigured, or `/auth/callback` not handling the token hash |
| "Email attribute not found" | The `email` attribute isn't being sent — re-check Step 3 mappings |
| SP-initiated SSO can't find your tenant by email | Your organization's email domain isn't registered on the tenant |

When debugging, the Brizz backend logs (`backend.log`) emit a detailed `ACS: SAML assertion validation failed` entry with the underlying `InvalidResponseError` — this almost always pinpoints the mismatch (issuer, audience, or signature).

## Certificate rotation

JumpCloud signing certificates have an expiry date. Brizz tracks it and surfaces a warning on the SSO settings page as the expiry approaches. When JumpCloud rotates the certificate, click **Refresh Metadata** in Brizz to pick up the new certificate — no downtime required.

## See also

- [API keys](/docs/admin/api-keys.md) — programmatic access; SSO covers humans, API keys cover services.
- [Troubleshooting](/docs/help/troubleshooting.md) — broader auth/ingestion issues.