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 account with admin access
• A verified custom domain 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

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

   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:

   {
     "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.