Skip to main content

​
After this article

You will be able to connect JumpCloud to Lumos to sync users, groups, and applications, manage group membership, and deprovision users, and optionally put Lumos itself behind JumpCloud SAML SSO.

​
Capabilities

​
Required plan and roles

  • JumpCloud plan: no minimum JumpCloud plan is required.
  • JumpCloud role: your JumpCloud user must be an Administrator or Manager.
  • Authentication: an Organization ID plus an API Key (not OAuth). The API key is tied to the admin user who generates it.
  • Permission scoping: this is a read/write integration. Lumos syncs users, groups, and applications, and also manages group membership and deprovisions users. Write access comes with the admin API key, and there is no separate scope selection.

​
Read-only access vs provisioning

Is read-only possible? No. JumpCloud authenticates with a single admin API key that is tied to the connecting Administrator or Manager user, and there is no separate scope selection to narrow it to read-only. What full provisioning requires. The same Organization ID and API Key described above, generated by a JumpCloud Administrator or Manager. Follow the steps below. Watch out for. Because there’s no scope selection, the API key that lets Lumos sync users and groups is the same key that manages group membership and deprovisions users. If the admin who generated the key is removed or the key is revoked, sync fails with “Unauthorized: api key user not found” and you have to regenerate the key with a qualifying user and reconnect.

​
Instructions

Phase 1: Get your Organization ID and API key in JumpCloud
  1. Log in at console.jumpcloud.com/login. If you land on the User Portal, select your initials in the top right and click Launch Admin Portal.
  2. Click Settings at the bottom of the left-hand navigation panel.
  3. Under Organization Profile → General, find and save your Organization ID.
  4. Click your account initials in the top right and select My API Key to retrieve your API key.
Phase 2: Connect in Lumos
  1. Find the JumpCloud card in your Lumos integrations (reconnect an existing card or add a new one).
  2. Enter the Organization ID and API Key values from JumpCloud.
  3. Click Connect JumpCloud.
Optional: Put Lumos behind JumpCloud SAML SSO This restricts who can log in to Lumos via JumpCloud SAML. The ACS URL and SP Entity ID values are not self-service, so request them from Lumos support (Slack or support@lumos.com).
  1. Log into the JumpCloud Admin console and create a custom SAML app (adding a Lumos logo is recommended).
  2. Contact Lumos support to obtain the Single sign on URL (ACS URL) and Audience URI (SP Entity ID).
  3. In the app’s Single Sign-On Configuration, set the ACS URL in the ACS URL field, and enter the SP Entity ID in both the IdP Entity ID and SP Entity ID fields. Save.
  4. Configure attribute mappings (Name → Name Format): id → email, email → email, firstName → firstname, lastName → lastname.
  5. Under the SSO tab, check Sign Assertion and save, then check Declare Redirect endpoint.
  6. Under JumpCloud Metadata on the SSO tab, click Export Metadata and send the XML file to the Lumos team.
  7. Assign users to the JumpCloud Lumos application.
  8. After Lumos support confirms the configuration, verify login from the JumpCloud tile or the Lumos login page.

​
API Endpoints Used

​
Troubleshooting

Can’t connect the integration. Verify the Organization ID and API Key are correct, and that the user who generated the key is at least a Manager in JumpCloud. SSO setup stalls. The ACS URL and SP Entity ID for the SAML app must come from Lumos support. They cannot be derived yourself. Also double-check that the SP Entity ID was entered in both the IdP Entity ID and SP Entity ID fields, a common misconfiguration. Sync fails with “Unauthorized: api key user not found”. The JumpCloud API key was revoked or expired, or the admin that owned it was removed. Regenerate the key with a connecting user that is at least a Manager, and reconnect.