> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML Single Sign-On

> Let your team sign in to CloudCruise with your identity provider over SAML 2.0

CloudCruise supports **SAML 2.0 Single Sign-On (SSO)**, so your team signs in to the dashboard with your own identity provider (IdP) instead of a CloudCruise password. You can also **require** SSO for everyone on your email domain, centralizing access in your IdP and turning off password sign-in.

<Note>
  SAML SSO is part of the **Enterprise plan** and is configured per **organization** by an organization **owner**. If you don't see the Authentication settings, [contact CloudCruise](mailto:founders@cloudcruise.com) to enable it.
</Note>

## How it works

SSO is set up in two steps, both from [Organization Settings → Authentication](https://app.cloudcruise.com/organizations/authentication):

1. **Verify your domain** — prove you own the email domain your team uses (e.g. `acme.com`) by adding a DNS TXT record.
2. **Attach a SAML configuration** — paste your IdP's metadata (Entity ID, SSO URL, signing certificate) onto the verified domain.

Once configured, anyone with an email on that domain can authenticate with SSO. Access to an organization or workspace is still controlled by CloudCruise membership and invites. Optionally, turn on **Require SSO** to block password sign-in and sign-up for the domain entirely.

Any SAML 2.0–compliant identity provider works, including:

* **Okta**
* **Microsoft Entra ID** (Azure AD)
* **Google Workspace**
* **OneLogin**
* **Ping Identity**
* **JumpCloud**
* …and any other SAML 2.0 IdP

## Before you start

You'll be moving values back and forth between your IdP and CloudCruise. From CloudCruise, your IdP needs these **Service Provider (SP)** details:

| Setting in your IdP                                                            | Value                                                                    |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| **ACS URL** (a.k.a. Reply URL, Single sign-on URL, Assertion Consumer Service) | `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/acs`          |
| **SP Entity ID** (a.k.a. Audience URI, Identifier)                             | `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/metadata`     |
| **SP Metadata URL** (if your IdP supports importing it)                        | `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/metadata`     |
| **Name ID format**                                                             | Email address (`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`) |

<Note>
  These Service Provider URLs are the same for every CloudCruise customer — they're CloudCruise's hosted SAML endpoint. Point your IdP's ACS and Audience at them, and send the user's **email address as the SAML Name ID**.
</Note>

From your IdP, CloudCruise needs three values (covered in [Step 2](#step-2-add-your-saml-configuration)):

* **IdP Entity ID** — your IdP's SAML issuer / metadata identifier.
* **IdP SSO URL** — the IdP login endpoint (must be **HTTPS**).
* **IdP signing certificate** — the IdP's x509 public certificate, in PEM format.

***

## Step 1: Verify your domain

<Steps>
  <Step title="Open Authentication settings">
    Go to your organization's [**Settings → Authentication**](https://app.cloudcruise.com/organizations/authentication) page. (This link resolves to your active organization automatically.)
  </Step>

  <Step title="Add your email domain">
    Under **Verified domains**, enter the domain your team signs in with (for example `acme.com`) and click **Add domain**. A verification dialog opens automatically.
  </Step>

  <Step title="Publish the DNS TXT record">
    Add the following record at your DNS provider (the dialog shows the exact values with copy buttons):

    | Field           | Value                                    |
    | --------------- | ---------------------------------------- |
    | **Type**        | `TXT`                                    |
    | **Name / Host** | `_cloudcruise-sso-verification.acme.com` |
    | **Value**       | `cc-sso-verify=<your-unique-token>`      |

    The token is generated per domain — copy it from the dialog rather than from this page.
  </Step>

  <Step title="Verify">
    Click **Start verification**. CloudCruise checks DNS every 15 seconds for up to 15 minutes (you can also click **Check now**). Once the record is found, the domain flips to **Verified**.
  </Step>
</Steps>

<Note>
  DNS changes can take anywhere from a minute to a few hours to propagate. If verification keeps failing, the dialog tells you exactly what it found at the hostname — e.g. a stale `cc-sso-verify=` record or no record at all.
</Note>

<Warning>
  A domain can only be **verified by one organization**. Multiple organizations can have a *pending* claim on the same domain, but only the first to verify it via DNS takes ownership.
</Warning>

***

## Step 2: Add your SAML configuration

First create a SAML application in your IdP using the [Service Provider details above](#before-you-start), then bring the IdP's values back into CloudCruise.

<Steps>
  <Step title="Create the SAML app in your IdP">
    In your identity provider, create a new SAML 2.0 application and set:

    * **ACS URL** → `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/acs`
    * **Audience / SP Entity ID** → `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/metadata`
    * **Name ID** → the user's **email address**, format `emailAddress`

    Assign the app to the users or groups who should be allowed to authenticate with CloudCruise. They still need CloudCruise organization and workspace membership to access your team's workspaces.
  </Step>

  <Step title="Copy your IdP's metadata values">
    From the IdP's SAML metadata (or app settings), collect:

    * **IdP Entity ID** (e.g. `https://idp.acme.com/metadata`)
    * **IdP SSO URL** — the HTTPS sign-on endpoint (e.g. `https://idp.acme.com/sso`)
    * **Signing certificate** in PEM form, including the `-----BEGIN CERTIFICATE-----` / `-----END CERTIFICATE-----` lines
  </Step>

  <Step title="Create the configuration in CloudCruise">
    Back on the **Authentication** page, under **SAML configuration**:

    1. Choose the **verified domain** from Step 1.
    2. Paste the **IdP Entity ID**, **IdP SSO URL**, and **IdP Certificate (PEM)**.
    3. Click **Create configuration**.

    CloudCruise validates the values and registers the provider with its hosted SAML endpoint.
  </Step>

  <Step title="Test the login">
    Open the [login page](https://app.cloudcruise.com/login), choose **Sign in with SSO**, and enter a work email on the configured domain. You should be redirected to your IdP and, after authenticating, returned to CloudCruise signed in.
  </Step>
</Steps>

<Warning>
  The **IdP SSO URL must use HTTPS**, and the certificate must be a valid PEM-encoded x509 certificate (starting with `-----BEGIN CERTIFICATE-----`). The dashboard rejects values that don't meet these requirements.
</Warning>

***

## Requiring SSO (enforcement)

Each SAML configuration has a **Require SSO** toggle:

| State             | Behavior                                                                                                                          |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Off** (default) | Users on the domain can sign in **either** with SSO **or** with an email/password.                                                |
| **On**            | Password sign-in and new password sign-ups are **blocked** for the domain. Anyone attempting password login is redirected to SSO. |

Enforcement is applied both in the CloudCruise sign-in flow and deep in the auth layer, so it can't be bypassed by going straight to the password form.

<Note>
  Turn enforcement **on only after** you've confirmed SSO login works end-to-end. If your IdP configuration has a mistake and password sign-in is already disabled, you can lock yourself out. Leave it off while testing, then flip it on.
</Note>

***

## User provisioning

CloudCruise uses **just-in-time provisioning**. When a user signs in through SSO for the first time, an account is created automatically from the email address in the SAML assertion — there's no separate import step. The email comes from the SAML **Name ID** (`emailAddress` format), which is why your IdP must send it there.

Just-in-time provisioning creates the CloudCruise user account and profile only. It does **not** automatically add the user to your organization or to every workspace.

To give a user access, invite them to your organization from CloudCruise. When they accept the invite, they're added as an organization **Member** and as a **Member** of the organization's existing workspaces. New workspaces can also be created with existing organization members added automatically, or workspace access can be managed separately.

<Note>
  For most providers the default mapping (Name ID → email) is all you need. If your IdP can only send email as a custom attribute claim, [contact support](mailto:founders@cloudcruise.com) — a custom attribute mapping can be applied to your configuration.
</Note>

***

## Identity provider quick reference

The exact labels differ per provider, but the mapping is always the same.

<Tabs>
  <Tab title="Okta">
    1. **Applications → Create App Integration → SAML 2.0**.
    2. **Single sign-on URL** → `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/acs`
    3. **Audience URI (SP Entity ID)** → `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/metadata`
    4. **Name ID format** → `EmailAddress`; **Application username** → Email.
    5. Finish, then open **Sign On → View SAML setup instructions** to grab:
       * **Identity Provider Issuer** → IdP Entity ID
       * **Identity Provider Single Sign-On URL** → IdP SSO URL
       * **X.509 Certificate** → paste as the PEM certificate
  </Tab>

  <Tab title="Microsoft Entra ID">
    1. **Enterprise applications → New application → Create your own** (non-gallery), then **Single sign-on → SAML**.
    2. **Identifier (Entity ID)** → `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/metadata`
    3. **Reply URL (ACS URL)** → `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/acs`
    4. Ensure the **Unique User Identifier (Name ID)** claim is the user's `user.mail` in email format.
    5. From the SAML configuration panel, copy:
       * **Microsoft Entra Identifier** → IdP Entity ID
       * **Login URL** → IdP SSO URL
       * Download the **Certificate (Base64)** → paste as the PEM certificate
  </Tab>

  <Tab title="Google Workspace">
    1. **Admin console → Apps → Web and mobile apps → Add custom SAML app**.
    2. Copy Google's **SSO URL**, **Entity ID**, and **Certificate** (these are your IdP values).
    3. **ACS URL** → `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/acs`
    4. **Entity ID** → `https://hrcczpkvvknatvtuwksw.supabase.co/auth/v1/sso/saml/metadata`
    5. **Name ID format** → `EMAIL`; **Name ID** → Basic Information > Primary email.
  </Tab>
</Tabs>

***

## Managing and removing configurations

From the [**Authentication**](https://app.cloudcruise.com/organizations/authentication) page you can:

* **Toggle Require SSO** on or off at any time.
* **Delete a SAML configuration** — users on that domain can no longer sign in via SSO (delete this before removing the domain).
* **Delete a verified domain** — only allowed once its SAML configuration has been removed.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Domain verification never succeeds">
    Confirm the TXT record is on the exact host `_cloudcruise-sso-verification.<your-domain>` and the value matches `cc-sso-verify=<token>` from the dialog. The verification dialog reports what it actually found — a stale token, a non-CloudCruise record, or nothing yet. Allow time for DNS propagation and use **Check now** to retry.
  </Accordion>

  <Accordion title="“SSO is not configured for this domain”">
    The email's domain has no SAML configuration, or you entered a domain that isn't verified. Make sure the domain is **Verified** and has a SAML configuration attached, and that the user's email domain exactly matches.
  </Accordion>

  <Accordion title="Login redirects to the IdP but fails to come back">
    Double-check the **ACS URL** and **SP Entity ID** in your IdP exactly match the values above, and that the IdP sends the user's **email as the Name ID** in `emailAddress` format. A mismatched audience or missing email is the most common cause.
  </Accordion>

  <Accordion title="Certificate or SSO URL rejected on save">
    The **IdP SSO URL** must be HTTPS, and the **certificate** must be a PEM block beginning with `-----BEGIN CERTIFICATE-----`. Copy the full certificate including the header and footer lines.
  </Accordion>

  <Accordion title="Locked out after enabling Require SSO">
    If SSO is misconfigured and enforcement is on, password sign-in is blocked. [Contact support](mailto:founders@cloudcruise.com) to temporarily disable enforcement so you can fix the IdP settings.
  </Accordion>
</AccordionGroup>

## Security notes

* CloudCruise validates each SAML assertion against the **signing certificate** you provide — rotate it in your IdP and update the configuration if it changes.
* Enforcement blocks the password path **server-side**, not just in the UI, so it cannot be bypassed.
* SSO is scoped to your **organization** for configuration and enforcement. Workspace access is still determined by CloudCruise workspace membership.
* All configuration changes (created, updated, enforcement toggled, deleted) are recorded in an audit log.