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

# JumpCloud

> Configure a JumpCloud SAML application for your Auth application.

This guide walks you through connecting a JumpCloud custom SAML application to Prelude Auth. JumpCloud is the Identity Provider (IdP); Prelude Auth is the Service Provider (SP).

## Prerequisites

* A [JumpCloud](https://jumpcloud.com/) account with admin access
* A verified [custom domain](/session/documentation/domain-names) on your Auth application

Because the SP endpoints embed the generated connection ID, the flow is: create the JumpCloud app with placeholder SP values, export JumpCloud's IdP details, create the Prelude connection, then paste the generated SP values back into JumpCloud.

## Configure JumpCloud SAML

<Steps>
  <Step title="Create a custom SAML application in JumpCloud">
    1. Log in to the [JumpCloud Admin Portal](https://console.jumpcloud.com/)
    2. Navigate to **SSO Applications** and click **+ Add New Application**
    3. Choose **Custom Application**, then select **Manage Single Sign-On (SSO)** with **Configure SSO with SAML**
    4. On the **SSO** tab, enter temporary placeholders for now — you will replace them in a later step:
       * **SP Entity ID**: `https://example.com`
       * **ACS URL**: `https://example.com/acs`
    5. Set **SAMLSubject NameID** to `email` and **SAMLSubject NameID Format** to `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
    6. Under **Attributes**, add the user attributes you want in the assertion — typically `email`, `firstName`, and `lastName` (these match Prelude's default attribute mapping)
    7. Click **Save** (and **Continue to Application** if prompted)
  </Step>

  <Step title="Export JumpCloud's IdP details">
    On the application's **SSO** tab, collect the IdP values Prelude needs:

    * **IdP Entity ID** — JumpCloud's issuer, e.g. `https://sso.jumpcloud.com/saml2/${APP_ID}`
    * **IdP URL** (SSO URL) — where Prelude sends SP-initiated requests
    * **IdP Certificate** — click **Export Metadata** / download the certificate (PEM, `-----BEGIN CERTIFICATE-----`)

    You will pass these to Prelude in the next step.
  </Step>

  <Step title="Create the SAML connection in Prelude">
    Create the connection from JumpCloud's IdP details. Start it **disabled** — you will enable it once the SP URLs are wired back into JumpCloud.

    ```bash theme={null}
    curl -X POST https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/jumpcloud \
      -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Acme JumpCloud",
        "enabled": false,
        "idp": {
          "entity_id": "https://sso.jumpcloud.com/saml2/${APP_ID}",
          "sso_url": "https://sso.jumpcloud.com/saml2/${APP_ID}",
          "certificates": ["-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"]
        },
        "behavior": {
          "jit_provisioning": true,
          "allow_email_account_merge": true,
          "email_domain_allowlist": ["acme.com"],
          "enforce_login": false,
          "default_redirect_uri": "https://app.acme.com/callback"
        }
      }'
    ```

    | Field                                | Description                                                                                                                                            |
    | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `name`                               | A human-readable label for the connection.                                                                                                             |
    | `enabled`                            | Set to `false` while you finish IdP setup; flip to `true` at the end.                                                                                  |
    | `idp.entity_id`                      | JumpCloud's IdP Entity ID (issuer).                                                                                                                    |
    | `idp.sso_url`                        | JumpCloud's IdP URL (SSO URL).                                                                                                                         |
    | `idp.certificates`                   | JumpCloud's signing certificate(s), PEM-encoded. Provide exactly one IdP source — the explicit `idp` block, `idp_metadata_url`, or `idp_metadata_xml`. |
    | `behavior.jit_provisioning`          | When `true`, creates a user on first SSO login.                                                                                                        |
    | `behavior.allow_email_account_merge` | When `true`, links to an existing user with the same verified email.                                                                                   |
    | `behavior.email_domain_allowlist`    | Domains this connection covers; required for email-resolved login and `enforce_login`.                                                                 |
    | `behavior.default_redirect_uri`      | Redirect URI for IdP-initiated logins and when `redirect_uri` is omitted.                                                                              |

    The response contains an `sp` block with the values you need next:

    ```json theme={null}
    {
      "connection": {
        "id": "samlc_01jqebhswje1ka1z7ahr9rfsgt",
        "provider_id": "jumpcloud",
        "sp": {
          "entity_id": "https://session.acme.com/v1/session/login/saml/jumpcloud/samlc_01jqebhswje1ka1z7ahr9rfsgt",
          "acs_url": "https://session.acme.com/v1/session/login/saml/jumpcloud/samlc_01jqebhswje1ka1z7ahr9rfsgt/acs",
          "metadata_url": "https://session.acme.com/v1/session/login/saml/jumpcloud/samlc_01jqebhswje1ka1z7ahr9rfsgt/metadata"
        }
      }
    }
    ```
  </Step>

  <Step title="Paste the SP URLs back into JumpCloud">
    Return to the JumpCloud application's **SSO** tab and edit the SAML settings:

    1. Set **ACS URL** to the `sp.acs_url` from the response
    2. Set **SP Entity ID** to the `sp.entity_id` from the response
    3. Click **Save**

    <Note>
      The values must match exactly — no trailing slash, and `https` only.
    </Note>
  </Step>

  <Step title="Assign users and enable the connection">
    1. On the JumpCloud application's **User Groups** tab, assign the groups who should have access.
    2. Enable the Prelude connection:

    ```bash theme={null}
    curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/jumpcloud/samlc_01jqebhswje1ka1z7ahr9rfsgt \
      -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{ "enabled": true }'
    ```
  </Step>
</Steps>

## Rotating the IdP certificate

When JumpCloud rotates its signing certificate, update the connection's IdP block (the Entity ID is immutable — to change it, delete and recreate the connection):

```bash theme={null}
curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/jumpcloud/${CONNECTION_ID} \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "idp": {
      "sso_url": "https://sso.jumpcloud.com/saml2/abc",
      "certificates": ["-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"]
    }
  }'
```

## Delete the connection

```bash theme={null}
curl -X DELETE https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/jumpcloud/${CONNECTION_ID} \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}"
```

Existing `saml:<connection_id>` user identifiers are retained so historical sessions stay auditable.

## What's next?

Now that the JumpCloud connection is configured, integrate the frontend using the [Web Integration](/session/documentation/frontend-sdks/web/saml) guide, or require this domain to use SSO with [Enforce SSO login](/session/documentation/integration-guide/saml/enforce).