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

# SAML with JumpCloud

> Configure SAML 2.0 single sign-on between TrueFoundry and JumpCloud using a Custom SAML Application.

This guide walks you through setting up SAML 2.0 single sign-on between TrueFoundry and JumpCloud. JumpCloud doesn't ship a TrueFoundry connector in its SSO catalog, so you'll create a **Custom Application**. Once finished, members of your JumpCloud directory can sign in to TrueFoundry through a **Login with JumpCloud** button.

## Prerequisites

* A TrueFoundry tenant with **Admin** access to **Settings → Security & Access → SSO**.
* A JumpCloud admin account with permission to create **SSO Applications** and assign **User Groups**.

<Tip>
  Keep the JumpCloud admin console and TrueFoundry SSO settings open in side-by-side tabs — you'll copy a handful of URLs and a certificate between them.
</Tip>

## Configuration overview

<Steps>
  <Step title="Create the SSO configuration in TrueFoundry">
    Save a SAML SSO configuration in TrueFoundry to surface the **ACS URL**, **SP Entity ID**, and **Relay URL**.
  </Step>

  <Step title="Create a Custom SAML Application in JumpCloud">
    Add a new SSO Application with the **Custom Application** template and choose **Configure SSO with SAML**.
  </Step>

  <Step title="Configure the SAML connection on both sides">
    Paste TrueFoundry's values into JumpCloud, switch signing mode, then paste JumpCloud's IDP URL and certificate back into TrueFoundry.
  </Step>

  <Step title="Assign user groups and test">
    Assign one or more JumpCloud user groups to the application and sign in to verify.
  </Step>
</Steps>

## Step 1 — Create the SSO configuration in TrueFoundry

<Steps>
  <Step title="Open SSO settings">
    Go to **Settings → Security & Access → SSO**.

    Click the **+** icon labeled **Add New SSO Config**.

    <Frame caption="SSO page in TrueFoundry — click the + icon to add a new SSO configuration">
      <img src="https://mintcdn.com/truefoundry/OlEFjoHwZJ0edSjd/images/sso/entra/saml-truefoundry-add-sso-config.png?fit=max&auto=format&n=OlEFjoHwZJ0edSjd&q=85&s=f768205b84d9f33ce04a8b8576ab0070" alt="TrueFoundry SSO settings page with the Add New SSO Config plus button highlighted" width="1024" height="263" data-path="images/sso/entra/saml-truefoundry-add-sso-config.png" />
    </Frame>
  </Step>

  <Step title="Fill in the basic fields">
    * **Enabled**: turn this on.
    * **Name**: a lowercase alphanumeric label — for example, `jumpcloudsaml`.
    * **SSO Provider**: choose **Custom**.
    * **Authentication Configuration**: select **SAML v2**.

    Leave **Identity Provider Endpoint** and **X.509 Certificate** blank for now — you'll fill them in once JumpCloud surfaces those values.
  </Step>

  <Step title="Save to reveal the Single sign-on URL, Audience URI (SP Entity ID), and Relay URL">
    Click **Save**. TrueFoundry displays the values you need for JumpCloud on the SSO configuration card:

    | JumpCloud field             | Value from TrueFoundry          |
    | --------------------------- | ------------------------------- |
    | **ACS URL**                 | **Single Sign On URL**          |
    | **SP Entity ID**            | **Audience URI (SP Entity ID)** |
    | **Relay State** *(if used)* | **Relay URL**                   |

    <Frame caption="TrueFoundry SSO configuration card showing the SAML values to copy into JumpCloud">
      <img src="https://mintcdn.com/truefoundry/OlEFjoHwZJ0edSjd/images/sso/entra/saml-truefoundry-sp-metadata.png?fit=max&auto=format&n=OlEFjoHwZJ0edSjd&q=85&s=e061fae840c0fa4e8af3c4efe9961a2b" alt="TrueFoundry SSO configuration card displaying Audience URI, Single Sign On URL, Metadata URL, and Relay URL for SAML setup" width="1024" height="391" data-path="images/sso/entra/saml-truefoundry-sp-metadata.png" />
    </Frame>
  </Step>
</Steps>

## Step 2 — Create a Custom SAML Application in JumpCloud

<Steps>
  <Step title="Open SSO Applications">
    Sign in to the [JumpCloud admin console](https://console.jumpcloud.com/) and click **SSO Applications** in the left navigation.

    Click **Add New Application** in the top-left corner. (If your tenant has no SSO applications yet, click **Get Started** instead.)
  </Step>

  <Step title="Pick the Custom Application tile">
    On the **Create New Application Integration** page, scroll to the **Custom Application** card and click **Select**, then click **Next**.
  </Step>

  <Step title="Choose Configure SSO with SAML">
    On the **Select Options** screen, check **Manage Single Sign-On (SSO)**. The radio buttons will expand — pick **Configure SSO with SAML**, then click **Next**.
  </Step>

  <Step title="Set a Display Label">
    On the **Enter General Info** step, set the **Display Label** to something users will recognise on their JumpCloud portal — for example, `TrueFoundry`.

    Click **Save Application**, then click **Configure Application** on the confirmation screen to open the SAML configuration.
  </Step>
</Steps>

## Step 3 — Enter TrueFoundry's details into JumpCloud

Switch back to the JumpCloud SAML configuration screen for your Custom Application and open the **SSO** tab.

<Steps>
  <Step title="Set the entity IDs and ACS URL">
    Fill in the following fields:

    | JumpCloud field   | Value                                                                                                                                                       |
    | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **IdP Entity ID** | A descriptive identifier you choose — for example, `jumpcloud-truefoundry`. JumpCloud doesn't generate this; it just needs to be unique within your tenant. |
    | **SP Entity ID**  | TrueFoundry **Audience URI (SP Entity ID)**                                                                                                                 |
    | **ACS URL**       | TrueFoundry **Single Sign On URL**                                                                                                                          |
  </Step>

  <Step title="Switch Sign to Assertion and Response">
    Scroll down to the **Sign** option and change the radio button from the default to **Assertion and Response**.

    <Warning>
      This step is critical. JumpCloud's default signing mode signs only the assertion, which TrueFoundry rejects with a signature validation error. You **must** select **Assertion and Response**.
    </Warning>
  </Step>

  <Step title="Enable Declare Redirect Endpoint">
    Tick the **Declare Redirect Endpoint** checkbox. Without this, JumpCloud won't advertise a redirect (HTTP-Redirect) binding in its metadata, and TrueFoundry's login button will fail to start the SAML handshake.
  </Step>

  <Step title="Map SAML attributes">
    In the **Attributes** section, add the following user attributes. JumpCloud uses lowercase user property names on the right-hand side.

    | Service Provider Attribute Name | JumpCloud Attribute Name |
    | ------------------------------- | ------------------------ |
    | `email`                         | `email`                  |
    | `sub`                           | `id`                     |
    | `firstName`                     | `firstname`              |
    | `lastName`                      | `lastname`               |
  </Step>
</Steps>

## Step 4 — Assign user groups in JumpCloud

JumpCloud only lets users sign in to applications that are bound to a user group containing them.

<Steps>
  <Step title="Open the User Groups tab">
    Inside the same SAML application, click the **User Groups** tab at the top.
  </Step>

  <Step title="Pick the groups that should have access">
    Tick one or more user groups to grant them access to TrueFoundry.

    <Tip>
      If you don't have a suitable group yet, exit the application, click **User Groups** in the left navigation, click the **+** icon, name the group, add **Users**, then come back to this step.
    </Tip>
  </Step>

  <Step title="Activate the application">
    Click **Activate** (or **Save** if the app is already active) in the bottom-right corner. JumpCloud confirms with a green toast.
  </Step>
</Steps>

## Step 5 — Copy JumpCloud's details back to TrueFoundry

With the application activated, JumpCloud exposes the IdP signing certificate and login URL on the **SSO** tab.

<Steps>
  <Step title="Download the IDP certificate">
    On the left side of the SSO panel, click **IDP Certificate Valid → Download Certificate**. JumpCloud downloads a file named `certificate.pem`.

    Open the file in a text editor and copy the entire contents — including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.
  </Step>

  <Step title="Copy the IDP URL">
    Scroll down to the field labelled **IDP URL** and copy its value. This is JumpCloud's HTTP-Redirect SSO endpoint.
  </Step>

  <Step title="Paste into TrueFoundry">
    Return to **Settings → Security & Access → SSO** in TrueFoundry and edit the SSO configuration you created in Step 1. Set:

    * **Identity Provider Endpoint** → the **IDP URL** from JumpCloud.
    * **X.509 Certificate** → the certificate text you copied from `certificate.pem`.

    Click **Save**.
  </Step>

  <Step title="(Optional) Customise the login button">
    Expand **Show advanced fields** in the TrueFoundry SSO form to override:

    * **Button Text** — for example, `Login with JumpCloud`.
    * **Button Image URL** — a publicly reachable URL pointing at a JumpCloud icon.
    * **Email Claim** / **Unique ID Claim** — only needed if you mapped custom attribute names in JumpCloud.
  </Step>
</Steps>

## Step 6 — Test single sign-on

1. Open a private/incognito window and go to your TrueFoundry login page.
2. Click **Login with JumpCloud** (or whichever button label you set under **Show advanced fields → Button Text**).
3. Authenticate with a JumpCloud user that belongs to one of the assigned user groups.

If the sign-in succeeds, you'll land in the TrueFoundry dashboard. The user is created automatically if [JIT provisioning](/docs/platform/user-management#user-provisioning) is on; otherwise they must already exist in TrueFoundry, be invited, or be synced via SCIM.

## Optional next steps

* **Automate user lifecycle with SCIM** — see [SCIM with JumpCloud](/docs/platform/sso/jumpcloud/scim) to push users and groups from JumpCloud into TrueFoundry automatically.

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Invalid Signature' or 'Could not validate SAML response'">
    The most common cause is forgetting to switch JumpCloud's **Sign** option from the default to **Assertion and Response**. Re-open the SAML application's **SSO** tab, change the radio button, and click **Save**.

    If the error persists, re-download `certificate.pem` from JumpCloud and paste the full PEM (including the BEGIN/END lines) into TrueFoundry's **X.509 Certificate** field.
  </Accordion>

  <Accordion title="The login button does nothing or returns an SSO error before reaching JumpCloud">
    Make sure **Declare Redirect Endpoint** is checked on the JumpCloud SSO tab. Without it, JumpCloud doesn't publish an HTTP-Redirect binding, and TrueFoundry can't start the SAML AuthnRequest.
  </Accordion>

  <Accordion title="'You are not authorized to access this application'">
    The JumpCloud user isn't a member of any user group bound to the SAML application. Go back to **Step 4** and make sure the user belongs to one of the assigned **User Groups**.
  </Accordion>

  <Accordion title="The login succeeds but the user gets 'no matching user found' inside TrueFoundry">
    Check the provisioning mode under **Settings → Security & Access → Provisioning**:

    * **Invite-only** — the user must be invited from **Access → Users** first.
    * **JIT** — the user is created on first login automatically.
    * **SCIM** — the user must be synced from JumpCloud first. See [SCIM with JumpCloud](/docs/platform/sso/jumpcloud/scim).
  </Accordion>

  <Accordion title="Users sign in but email or unique ID is empty">
    Confirm the SAML attribute mapping in JumpCloud includes `email` → `email` and `sub` → `id` as described in **Step 3**. If you renamed the attributes, expand **Show advanced fields** in TrueFoundry and set **Email Claim** and **Unique ID Claim** to match.
  </Accordion>
</AccordionGroup>