Skip to main content

Workspace ONE UEM

Visualize Omnissa Workspace ONE UEM (formerly VMware AirWatch) admins, users, organization groups, profiles, and devices, map Workspace ONE UEM users to employees, and monitor changes through queries and alerts.

Installation​

Omnissa Workspace ONE UEM was formerly known as VMware AirWatch. Instances configured before the rename keep working without changes.

To install this integration, you will need to configure settings both within Workspace ONE UEM and on JupiterOne. Before enabling in JupiterOne, ensure that you have completed the setup within your Workspace ONE UEM console.

Configuration in Workspace ONE UEM​

Log into the Workspace ONE UEM console and create an Administrator user account for the integration to authenticate with the REST API:

  1. Select Accounts > Administrators > Admins (List View in console versions 2402 and earlier).

  2. Select Add > Add Admin. On the Basic tab, set User Type to Basic and fill in the required details. The integration authenticates with this username and password.

    note

    We recommend setting values that represent JupiterOne as a system user account. Ensure that you set Title on the Details tab to system so that JupiterOne understands this is a user for automation (so it does not attempt to map to a Person entity).

  3. Assign the necessary read-only permissions to the administrator account. The REST API key does not carry permissions of its own; requests use the permissions of this administrator's role. The integration requires read access to:

    • Devices (/mdm/devices/search, /mdm/devices/security)
    • Administrators (/system/admins/search)
    • Organization Groups (/system/groups/search, /system/groups/{id}/children)
    • Profiles (/mdm/profiles/search, /mdm/profiles/{uuid}/devices)

    Roles are managed under Accounts > Administrators > Roles. To create a dedicated role, select Add Role and grant only these Read Only permissions (Omnissa documentation):

    • REST > Devices: REST API Devices Read
    • REST > Groups: REST API Groups Read
    • REST > Admins: REST API Admins Read
    • REST > Profiles: REST API Profiles Read

    Assign the role to the administrator at the organization group whose devices you want to ingest. The integration only sees devices, groups and profiles at and below that organization group. The integration doesn't call the Smart Groups, User Groups, Users or Apps APIs, so the role doesn't need those permissions.

    A missing permission makes the corresponding step fail with a 403. The one exception is device security details. If that call is denied, devices are still ingested but their passcode and encryption properties stay empty.

  4. Navigate to Groups & Settings > All Settings > System > Advanced > API > REST API (Omnissa documentation):

    • On the General tab, select Enable API Access.
    • Select Add, enter a Service name (for example JupiterOne), set Account Type to Admin, and copy the generated API Key.
    • On the Authentication tab, make sure Basic is enabled.
    • On the Usage tab, check the Daily Quota (50,000 calls per day by default). The quota is shared by every API consumer of the tenant, not only JupiterOne. See Skip Device Security Details and Max API Requests Per Job below for large tenants.

Configuration in JupiterOne​

To install the Workspace ONE UEM integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Workspace ONE UEM. Click New Instance to begin configuring the integration.

Creating a Workspace ONE UEM instance requires the following:

  • The Account Name used to identify the Workspace ONE UEM account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • The Hostname (for example cn1234.awmdm.com), Admin Username, and Admin Password of your Workspace ONE UEM environment.

  • Rest API Key (or Tenant Code) used to authenticate with Workspace ONE UEM.

  • Optionally, Skip Device Security Details. By default the integration makes one Workspace ONE API call per device to collect passcode and encryption properties. On large tenants this is most of the integration's API usage, which counts against the Workspace ONE daily API quota (50,000 calls per day by default). Enabling this option skips that call, and those device properties are no longer ingested.

  • Optionally, Max API Requests Per Job. A hard cap on the API requests a single job sends, retries included. Before each request the integration checks the count, so a job never goes over the cap. When the cap is reached, the job stops with a failed step that names the limit, and data the job could not refresh is kept from the previous run rather than deleted. The cap applies to each job separately, so a manual run and a scheduled run on the same day can each use up to the cap. Defaults to Unlimited. Use it as a safety net, not as the main way to cut usage: Skip Device Security Details removes about one request per device, which is nearly all of a run's requests. A cap below what a full run needs stops at about the same point every run, so devices past that point are never refreshed.

  • Optionally, Ingest Enrolled Devices Only. Skips devices whose Workspace ONE EnrollmentStatus shows they are no longer enrolled or are being wiped: Unenrolled, UnenrolledByFeedbackService, EnterpriseWipePending, DeviceWipePending, WipeInitiated, Retired, DeviceNotFound and Blacklisted. Their security request is skipped too. Devices with any other status, including Enrolled and UserEnrolled, are kept. The device search API has no enrollment filter, so all device pages are still read and the filter runs in JupiterOne. Enabling this option removes previously ingested non-enrolled devices, and device users linked only to them, on the next run.

  • Optionally, Device Last Seen Within. Only ingest devices whose LastSeen falls within the selected number of days. Excluded devices also skip their security request. Narrowing this window removes devices outside it, and device users linked only to them, on the next run.

  • Optionally, the page sizes: Device Page Size (default 500), Profile Page Size (default 50, the Workspace ONE maximum) and Profile Device Page Size (default 500). 500 is also the largest size offered, since the API documents no maximum above its default. Page size has little effect on the total, because a run's API usage is mostly the per-device security calls and the per-profile assignment calls.

Click Create once all values are provided to finalize the integration.

API usage​

Every request is read-only, and requests are made one at a time. The calls are:

  • GET /API/mdm/devices/search (v2), 500 devices per page (Device Page Size)
  • GET /API/mdm/devices/security (v1), one call per device with a serial number. Not made when Skip Device Security Details is enabled.
  • GET /API/system/admins/search (v2)
  • GET /API/system/groups/search (v2), plus GET /API/system/groups/{id}/children (v1) once per organization group
  • POST /API/mdm/profiles/search (v3), a search that doesn't change anything, 50 profiles per page (Profile Page Size)
  • GET /API/mdm/profiles/{uuid}/devices (v1), one call per 500 devices assigned to each profile, at least one per profile (Profile Device Page Size)

When Skip Device Security Details is enabled, most of a run's calls are device pages and profile assignments. For example, 40,000 devices take 80 device pages, and each profile takes one call per 500 devices it is assigned to, so a run is usually a few hundred to a few thousand calls. When it is disabled, add roughly one call per device. For example, a tenant with 40,000 devices uses about 40,000 calls per run, so one run per day fits the default quota of 50,000 calls per day, but a second run on the same day doesn't. If Workspace ONE UEM rate-limits a request, the integration stops collecting security details for the rest of that run and ingests everything else.

Failed requests are retried only for server errors (5xx), rate limiting (429, honoring Retry-After) and network errors. Other client errors (4xx) are never retried. Each request gets up to 3 attempts, with waits of 30 and 60 seconds in between, and each attempt times out after 180 seconds. A timed-out attempt starts a new set of attempts, up to 3 more times, so one request can be sent at most 12 times. Every attempt counts against the daily quota and against Max API Requests Per Job. The integration stops requesting device security details for the rest of the run after a 429, after 3 security requests in a row that get no response (timeouts, network errors or 503, which is how a throttled Workspace ONE server behaves), or after 10 failures in a row of any kind. The affected devices are then ingested without their security properties.

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.