> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/identity-provider/jumpcloud-idp.md).
# JumpCloud IDP
Harmony integrates with JumpCloud as a dedicated Identity Provider (IdP), separate from the existing JumpCloud MDM connection. Once connected using your JumpCloud API key, Harmony automatically imports and keeps your employee directory, application data, and SSO login events in sync - giving you a unified view of identity and access across your organization without manual cross-referencing.
#### What the JumpCloud integration enables
| Capability | Description |
| --------------------------- | ----------------------------------------------------------------------------------------- |
| User Provisioning | Automate user lifecycle management via SCIM or API-based sync |
| SSO Integration | Sync JumpCloud SSO applications with Harmony, including correct display names |
| Group Management | Synchronize user groups and system groups, displayed by human-readable names |
| Multi-Factor Authentication | Coordinate MFA policies and enrollment |
| Directory Sync | Maintain a consistent employee directory, including active/inactive status and last login |
| Password Management | Coordinate password policies and resets |
| SSO Login Events | Ingest and normalize JumpCloud SSO login events for identity and access visibility |
| API Request Pagination | Retrieve large result sets from JumpCloud system groups with automatic pagination |
#### Prerequisites
Before configuring the JumpCloud integration, ensure you have:
* **JumpCloud Administrator Access**: Organization administrator role
* **API Key**: Generated from JumpCloud admin console
* **Harmony Account**: Active Harmony workspace with integration permissions
#### Configuration in JumpCloud
**Step 1: Generate API Key**
1. Log in to JumpCloud admin portal at `https://console.jumpcloud.com`
2. Navigate to the **Admin** icon (gear) > **API Settings**
3. Click **Generate New API Key**
4. Configure:
* **Name**: "Harmony Integration"
* **Permissions**: Select appropriate permissions (User Management, System Management, Directory Insights)
5. Click **Generate API Key**
6. **Copy the API key immediately** (it won't be shown again)
#### Configuration in Harmony
**Step 1: Navigate to Integrations**
1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **JumpCloud (IdP)** under the **Identity Provider** section and click **Connect**
**Step 2: Enter API Credentials**
1. Enter your **JumpCloud API key** that you generated in the previous step
2. Click **Connect**
Once connected, Harmony will automatically begin syncing your employee directory and application data. No additional credentials or setup are required.
#### What Harmony Syncs
**From JumpCloud to Harmony**
* **User Accounts**: All user profiles with attributes
* **User Status**: Active or inactive status for each employee, surfaced directly in Harmony
* **Last Login**: Timestamp of each employee's most recent login, so you can see who is active without checking JumpCloud manually
* **User Groups**: Group memberships and assignments, displayed using human-readable group names
* **SSO Applications**: Connected SAML/OIDC applications, shown with their correct display names rather than internal type labels
* **Application Assignments**: Users assigned to each application, enriched and surfaced in Harmony
* **SSO Login Events**: Authentication events normalized as `USER_AUTHENTICATION_SSO`, fetched from JumpCloud's Directory Insights API with a 90-day lookback and cursor-based pagination for complete data retrieval
#### SCIM Provisioning
In addition to API-based sync, you can connect Harmony to JumpCloud using SCIM for automated user provisioning and deprovisioning. With SCIM enabled, users are automatically added to or removed from Harmony as your JumpCloud directory changes - eliminating manual onboarding and offboarding steps. Access stays continuously in sync with your JumpCloud identity provider.
#### JumpCloud API Request Block and Pagination
When building workflows that retrieve members from JumpCloud system groups, you can now fetch more than 100 results in a single workflow step using the built-in pagination support on the JumpCloud API Request block.
**Enabling pagination**
Set the `paginate` flag to `true` on the JumpCloud API Request block to enable automatic multi-page fetching. When enabled, the block:
* Fetches pages of 100 items at a time behind the scenes
* Merges all pages into a single response
* Requires no manual loop logic in your workflow
**Controlling result limits**
Use the optional `max_results` parameter to cap the total number of results returned. By default, up to 2,000 results are retrieved. Set `max_results` to a lower value if you want to limit the response size for your use case.
#### App Access and Provisioning Workflows
Connecting JumpCloud as an IdP also enables Harmony's access management layer to use your JumpCloud directory as the source of truth for app access requests and agent provisioning workflows. Groups are synced with human-readable names, and applications appear with their correct display names - making it straightforward to build and manage automated provisioning and deprovisioning aligned with your JumpCloud directory.
#### Troubleshooting
Users Not Syncing
**Issue**: New users in JumpCloud don't appear in Harmony
**Solutions**:
* Verify API key has User Management read permissions
* Check user status filter settings (active vs. suspended)
* Ensure users have required attributes (email, username)
* Trigger manual sync from Harmony dashboard
* Review JumpCloud audit logs for API access
SSO Application Access Not Granted
**Issue**: Cannot add users to SSO applications
**Solutions**:
* Confirm API key has SSO Application write permissions
* Verify application exists and is active in JumpCloud
* Check that user account is active (not suspended)
* Ensure application supports API-based user assignment
* Review JumpCloud logs for specific error messages
Group Membership Changes Not Syncing
**Issue**: Group updates don't reflect in Harmony
**Solutions**:
* Verify API key has Group Management permissions
* Check sync frequency settings
* Trigger manual sync to refresh data
* Ensure groups are properly configured in JumpCloud
* Review group sync filters in Harmony settings
Authentication Failures
**Issue**: "Unauthorized" or "Invalid API key" errors
**Solutions**:
* Verify API key copied correctly (no extra spaces)
* Check that API key hasn't been revoked in JumpCloud
* Ensure organization ID is correct
* Confirm API endpoint URL is accurate
* Regenerate API key if necessary
SSO Login Events Not Appearing
**Issue**: JumpCloud SSO login events are missing or incomplete in Harmony
**Solutions**:
* Confirm the API key has Directory Insights read permissions enabled in JumpCloud
* Verify the integration is connected and actively syncing
* Note that the initial fetch includes up to 90 days of historical events - allow time for the first sync to complete
* Check that the relevant users are active and have authenticated via JumpCloud SSO
* Trigger a manual sync if events appear delayed
#### Best Practices
User Management
* **Consistent Naming**: Use standard username formats (firstname.lastname)
* **Complete Profiles**: Ensure all required attributes populated
* **Group Organization**: Use hierarchical groups for clarity
* **Regular Audits**: Review user accounts and access quarterly
* **Deactivation Process**: Promptly suspend departing users
Security and Compliance
* **MFA Enforcement**: Require MFA for all users
* **Password Policies**: Implement strong password requirements
* **Access Reviews**: Conduct regular access certification
* **Least Privilege**: Grant minimum necessary permissions
* **Audit Logging**: Monitor and review authentication logs
Integration Maintenance
* **API Key Rotation**: Rotate API keys annually
* **Permission Reviews**: Audit API permissions quarterly
* **Sync Monitoring**: Track sync success rates and errors
* **Performance Optimization**: Use appropriate sync frequencies
* **Documentation**: Maintain current integration documentation
Automation Strategy
* **Start Simple**: Begin with basic user provisioning
* **Iterate Gradually**: Add complexity as confidence grows
* **Test Thoroughly**: Test automations with test users first
* **Monitor Closely**: Track automation success and failures
* **User Feedback**: Collect feedback on provisioning experience
#### Data & Privacy
Data Handling
* User directory data encrypted in transit (TLS 1.2+)
* Harmony caches user profiles, group memberships, employee status, and last login timestamps
* Sensitive data (passwords, MFA secrets) never accessed
* Data processed according to GDPR and privacy regulations
* Data retention configurable based on requirements
Compliance
* **GDPR**: Full compliance with data protection regulations
* **SOC 2 Type II**: Both JumpCloud and Harmony maintain certification
* **HIPAA**: Available for healthcare organizations
* **Audit Trails**: All user provisioning actions logged
* **Data Residency**: JumpCloud operates from US data centers
Access Control
* API key permissions scoped to minimum required
* Harmony respects JumpCloud's role-based access control
* Integration can be disabled immediately if needed
* All provisioning actions logged with user context
* Multi-approval workflows for sensitive operations
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.harmony.io/integrations/identity-provider/jumpcloud-idp.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.