Skip to main content
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

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

1

Create a custom SAML application in JumpCloud

  1. Log in to the JumpCloud Admin Portal
  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)
2

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

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.
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"
    }
  }'
FieldDescription
nameA human-readable label for the connection.
enabledSet to false while you finish IdP setup; flip to true at the end.
idp.entity_idJumpCloud’s IdP Entity ID (issuer).
idp.sso_urlJumpCloud’s IdP URL (SSO URL).
idp.certificatesJumpCloud’s signing certificate(s), PEM-encoded. Provide exactly one IdP source — the explicit idp block, idp_metadata_url, or idp_metadata_xml.
behavior.jit_provisioningWhen true, creates a user on first SSO login.
behavior.allow_email_account_mergeWhen true, links to an existing user with the same verified email.
behavior.email_domain_allowlistDomains this connection covers; required for email-resolved login and enforce_login.
behavior.default_redirect_uriRedirect URI for IdP-initiated logins and when redirect_uri is omitted.
The response contains an sp block with the values you need next:
{
  "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"
    }
  }
}
4

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
The values must match exactly — no trailing slash, and https only.
5

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:
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 }'

​
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): 
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

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 guide, or require this domain to use SSO with Enforce SSO login.