Event Notification Service and Common Platform Services API Guide

Common Platform Services API Guide

Ivanti Neurons for MDM 100 and Ivanti EPMM 12.1.0.0

April 2024

Privacy and Legal

Page 2 of 108

Contents

Revision history 5

Introduction 8

Resolved issues 8

Limitations 8

Getting Started 11

Prerequisites 11

Certificate-based authentication workflows 12

Assigning the CPS role to a user 15

Enabling messaging 19

Validating Event Notification Service and CPS API functionality 22

Using the Event Notification Service 23

Overview 23

Endpoint information 24

Getting event subscription metadata 25

Messages 26

Sample client snippet for message subscriber 27

API characteristics 31

Endpoint information 31

Aggregate API rate limits per cluster 33

Batch ID recommendation 33

Pulling data 33

Common items 34

Enums 35

Object models 36

Handling Paged Responses 45

Inventory APIs 46

Get application inventory 46

Get certificate inventory (iOS only) 48

Get profile inventory (iOS only) 50

Device APIs 53

Get device attributes metadata 53

Get devices by MDM or deviceGuid identifiers 54

Get devices by mac addresses 57

Search devices by status 58

Search devices by device group identifier 59

Get device location details 61

Count devices by status 62

Count devices by device group identifier 63

Update device attributes by device UEM identifiers 64

Manage device settings - iOS only 65

Get device settings - iOS only 69

Force checkin 73

Page 3 of 108

Check-in for Threat Response Matrix update 73

Device Group APIs 77

Get all Device Groups 77

Get device groups associated with device list 78

Search device groups by device group name 81

Get device group by device group identifier 82

Example device groups API scenario 83

Message APIs 86

Send email to device owners 86

Send push notification to devices 87

User APIs 89

Get user attributes metadata 89

Search users by GUID 91

Search users by user id 93

Count users by user id 96

Update user attributes 97

App Catalog APIs 98

Get application inventory 98

Metadata APIs 102

Get current minor version of the API 102

Get device registration URI 103

Get device app metadata 103

Get device certificate metadata 104

Enabling Windows 10 app inventory reporting on Ivanti EPMM 106

Documentation resources 107

Ivanti EPMM documentation 107

Page 4 of 108

Revision history

Date Description

April 30, 2024 Updated for Ivanti EPMM 12.1.0.0.

March 11, 2024 Updated for Ivanti EPMM 12.0.0.0.

November 16,

2023

Updated for Ivanti EPMM 11.12.0.0.

August 21, 2023 Updated for Ivanti EPMM 11.11.0.0.

April 26, 2023 Added a sample request and deepened the

documentation for the call,

"Get device registration URI"

on page103

November 7, 2022 Re-branded "Cloud" as "Ivanti Neurons for MDM," and

"Core" as "Ivanti EPMM."

November 2, 2022 Added

note

that the CPS APIs only support usage in the

default device space.

July 5, 2022 Changed instances of

MDM_IDENTIFIERS

MDM_

IDENTIFIER

for occurrences in descriptions and examples

of the

identifierType

parameter.

December 10, 2021 Added

"Sign out " on page44

event.

July 7, 2021

Content changes for rebranding and distribution:

Product documentation has been rebranded to align with

Ivanti standards and is now available on the Ivanti Product

Documentation page.

January 22, 2021 Added the following iOS fields to the

application

object

model:

adHocCodeSigned

appStoreVendable

betaApp

deviceBasedVPP

externalVersionIdentifier

Page 5 of 108

updateAvailable

installing

validated

shortVersion

bundleVersion

See "Get application inventory" on page46 for an example

response with these new fields.

October 28, 2020 Added the

managed

field to the return of

"Get application

inventory" on page46

August 31, 2020 The following calls are now supported in Ivanti EPMM

10.8.0.0, and were already supported in Ivanti Neurons for

MDM:

l "Get device groups associated with device list" on

page78

l "Search users by GUID" on page91

August 3, 2020 Clarified that the direction is inbound for the port (8883)

on which the

messaging service

listens.

July 21, 2020 Added the call,

"Get device groups associated with device

list" on page78

June 11, 2020

Add documentation for the call,

"Search users by

GUID" on page91

Updated documentation for the call

"Get devices by

MDM or deviceGuid identifiers" on page54

describe that the call can also take the deviceGUID

as a search identifier.

April 2, 2020

Updated

"Device" on page38

object model to

include deviceGuid.

Updated

"Example Device Event messages" on

page26

to include deviceGuid.

July 31, 2019

Clarified

MQTT

and

API

endpoints.

Updated Authentication methods supported for

Ivanti EPMM and Ivanti Neurons for MDM to include

basic auth and certificate-based authentication.

Page 6 of 108

Revision history

July 17, 2019

Added ldapStandardAttributes parameter to the

"Search users by user id" on page93

call.

Added LDAP standard attributes information to the

"Get user attributes metadata" on page89

call.

Changed identifier_type parameter to identifierType

for the

"Get profile inventory (iOS only)" on page50

and

"Check-in for Threat Response Matrix update"

on page73

, and

"Get application inventory" on

page46

calls.

June 3, 2019

Updated the API

"Endpoint information" on page31

to reflect the new format for certificate-based

authenticated calls.

Updated the messaging

"Endpoint information" on

page24

Updated the

"Resolved issues" on page8

and

"Limitations" on page8

sections for the Ivanti

Neurons for MDM 62 and Ivanti EPMM 10.3.0.0

version of the guide.

April 24, 2019 Added identifier_type parameter to the

"Get profile

inventory (iOS only)" on page50

and

"Check-in for Threat

Response Matrix update" on page73

, and

"Get application

inventory" on page46

calls.

April 22, 2019 Added documentation for these calls:

l "Get device app metadata" on page103

l "Get device certificate metadata" on page104

April 10, 2019 Added documentation for the

"Check-in for Threat

Response Matrix update" on page73

call.

January 2, 2018

Added documentation for these new calls:

- "Manage device settings - iOS only" on page65

- "Get device settings - iOS only" on page69

- "Get device location details " on page61

The device.report_initialized event is now supported

on Ivanti EPMM for iOS and Android devices.

Previously, it was only supported on Ivanti Neurons

for MDM. See

"Device event" on page40

Page 7 of 108

Revision history

Introduction

The Event Notification Service and Common Platform Services (CPS) API provide automated clients with a

messaging push and an RPC pull interface for integration with third-party solutions, namely:

• Event Notification Service: an MQTT endpoint for notifications of activities within Ivanti Neurons

for MDM and Ivanti EPMM. See "Using the Event Notification Service" on page23.

• CPS API: an RPC (HTTP/JSON) API to retrieve detailed information of interest to integrators. The

API is an RPC API using JSON over HTTP. See the API-related chapters, starting with "API

characteristics" on page31.

The Event Notification Service and CPS API comprise an integration platform between Ivanti's integration

partners and the Ivanti customer base. Before this integration platform, integration partners had to write

and maintain two separate integrations between Ivanti EPMM and Ivanti Neurons for MDM, and

constantly poll the API for device state changes, increasing processing complexity and computational

load.

The Event Notification Service notifies integration partners of events within a few seconds of event

occurrence, and the CPS API provides standard responses across Ivanti EPMM and Ivanti Neurons for

MDM, serving as the ideal integration platform between integration partners and the Ivanti EPMM and

Ivanti Neurons for MDM customer base.

Resolved issues

This release includes the following resolved issues:

• AW-32833: Previously, the GET /msa/v1/cps/appcatalog/apps API returned multiple versions of

the same app, whereas the App Catalog user interface showed only the latest of the two

uploaded versions in the app catalog listing. This issue has been fixed.

• AW-32746: The WINDOWS parameter of the GET /msa/v1/cps/appcatalog/apps API now returns

expected results.

Limitations

This release includes the following limitation:

Page 8 of 108

• AW-23186: The GET /msa/v1/cps/user API call yields differing result formats on Ivanti Neurons for

MDM and Ivanti EPMM for the following items:

Item Ivanti Neurons for MDM Ivanti EPMM

LDAP

cust

attri

bute

keys

Lower case

objectguid

userprincipalname

See the highlighted example in Ivanti

Neurons for MDM response below.

Camel Case

objectGUID

userPrincipalName

See the highlighted

example in

Ivanti

EPMM response

below.

objec

tguid

field

Hexadecimal:

\3f\\21\\d9\\5b\\1c\\ab\\cf\\49\

\81\\11\\7a\\fa\\b7\\d2\\ab\\6a

See the highlighted example in Ivanti

Neurons for MDM response below.

Unencoded string:

9a34fe08e8041c47

991c5a387efff6bb

See the highlighted

example in

Ivanti

EPMM response

below.

Ivanti Neurons for MDM response

Page 9 of 108

Introduction

{

"searchResults": [

{

"enabled": true,

"createdAt": 1520419288985,

"accountSource": "LDAP",

"displayName": "cloud user",

"emailAddress": "cloud.user@exchce.com",

"firstName": "cloud",

"lastName": "user",

"userId": "cloud.user12@exchce.com",

"userUuid": "a27c1b0e-96f6-4acc-af79-b3af881db1cd",

"ldapCustomAttributes": {

"objectguid":

"\\3f\\21\\d9\\5b\\1c\\ab\\cf\\49\\81\\11\\7a\\fa\\b7\\d2\\ab\\6a",

"userprincipalname": "cloud.user12@exchce.com"

}

"results": 1,

"offset": 0,

"limit": 50

}

Ivanti EPMM response

{

"searchResults": [

{

"enabled": true,

"createdAt": 1520553600000,

"accountSource": "LDAP",

"displayName": "testuser6771",

"emailAddress": "testuser6771@auto8.mobileiron.com",

"firstName": "testuser6771",

"userId": "testuser6771",

"userUuid": "bff6bf12-72ff-4524-97a0-064cc137f955",

"ldapCustomAttributes": {

"objectGUID": "9a34fe08e8041c47991c5a387efff6bb",

"userPrincipalName": "testuser6771@auto8.mobileiron.com"

}

"results": 1,

"offset": 0,

"limit": 50

}

Page 10 of 108

Introduction

Getting Started

Prerequisites

These sections describe the prerequisites for using the Event Notification Service and Common Platform

Services API.

Common prerequisites

You need to have a working Ivanti EPMM or Ivanti Neurons for MDM environment with registered

devices. See the Ivanti Neurons for MDM Administrator Guide and the Ivanti EPMM documentation set

for information about configuring your environment to work with this integration platform.

Event Notification Service prerequisites

• Event notification requires Certificate based Authentication for each connection using client

(identity) certificates issued by DigiCert, Inc. See "Authentication" below, "Certificate-based

authentication workflows" on the next page,and "Example Ivanti Neurons for MDM certificate-

based authentication cURL command" on page32.

• Integrators can only subscribe to events if admin user associated with the certificate has been

granted the CPS role. See "Assigning the CPS role to a user" on page15.

CPS API prerequisites

Authentication

Ivanti supports the following authentication methods for CPS on Ivanti EPMM and Ivanti Neurons for

MDM over an encrypted link between client and server using Transport Layer Security (TLS) v1.2:

• "Basic authentication" on the next page

Page 11 of 108

• "Certificate-based authentication" below

Basic authentication

The credentials you use for basic authentication must correspond to a user with the required CPS role. See

"Assigning the CPS role to a user" on page15 for how to assign the CPS role to users.

Certificate-based authentication

The Common Platform Services API requires authentication for each API call, and supports certificate-

based authentication using client (identity) certificates issued by DigiCert, Inc. When using certificate-

based authentication, you must include the identity certificate in every API call and when establishing a

connection to MQTT. See "Example Ivanti Neurons for MDM certificate-based authentication cURL

command" on page32 for how to include the certificate. Ivanti Neurons for MDM or Ivanti EPMM

compares the username and email address (RFC 822) in the certificate SAN field against the registered

username and email address. If these do not match, the system refuses the MQTT connection and API calls.

See "Certificate-based authentication workflows" below for how to set up certificate-based authentication,

and "Certificate-based authentication security" on page15 for a discussion of how Ivanti enforces

certificate security.

The system does not renew certificates. Please keep track of your certificate expiration date and

renew the certificate before expiration.

See "Certificate-based authentication workflows" below and "Example Ivanti Neurons for MDM certificate-

based authentication cURL command" on page32 for more details.

Certificate-based authentication workflows

Thus section describes the following workflows:

• Obtaining a certificate

• Using certificates in messaging

• Using certificate for API calls

Workflow: Obtaining a certificate

Follow this workflow to set up certificate-based authentication:

Page 12 of 108

Getting Started

1. Request Certificate

- User or partner requests a premium certificate from the DigiCert CA,

https://www.digicert.com/secure/order.

- The certificate issuer should be "DigiCert SHA2 Assured ID CA"

- Signature Hash must be SHA2.

- Common Name must be the Ivanti Neurons for MDM or Ivanti EPMM email of a user with the CPS

role. See "Assigning the CPS role to a user" on page15 for how to assign the CPS role to users.

- Recipient Email must be a working email address of a username that is also registered with same

email id in Ivanti Neurons for MDM or Ivanti EPMM.

2. Send Mail

- DigiCert sends an email to the Recipient Email containing an URL at which to generate the

certificate for the Common Name, in this case, the Ivanti Neurons for MDM or Ivanti EPMM email id

associated with the CPS role.

3. Get Certificate

- DigiCert sends a certificate in P12 format.

- Ensure that certificate is created with the "RFC 822 Name" header.

- The "RFC 822 Name" should be the email id of the user who will have the required CPS role. See

"Assigning the CPS role to a user" on page15 for how to assign the CPS role to users.

4. Acknowledge

- User clicks the URL to generate the certificate.

5. Request a new user

- User or partner requests the Ivanti admin to create a user.

6. Create user

- The Ivanti admin creates a single user for the given email id. The email id must be the same as to

which the certificate refers. See "Adding a User" in the Ivanti Neurons for MDM Administrator

Guide and "Managing Users" in the Getting Started with Ivanti EPMM guide for information about

creating users.

7. Enable CPS role

- The Ivanti admin enables the CPS role for the email id. See "Assigning the CPS role to a user" on

page15 for how to assign the CPS role to users.

Page 13 of 108

Getting Started

Workflow: Using certificates in messaging

Follow this workflow to use certificates in messaging:

Workflow: Using certificates for API calls

Follow this workflow to use certificates for API calls:

Page 14 of 108

Getting Started

Certificate-based authentication security

CPS supports Certificate-based Mutual Authentication. Mutual Authentication requires that both the

server and client present a certificate to prove their identity. This allows CPS to prevent unauthorized

clients without valid certificates from connecting to CPS APIs and event notification service.

Certificate Validation

To be considered a valid certificate, a certificate must:

1. Chain to a Certificate Authority (CA) trusted by Ivanti Neurons for MDM and Ivanti EPMM. Currently,

this is DigiCert only.

2. Be otherwise valid, for example, marked as usable for client authentication, and not expired.

3. After validating a certificate as valid, Ivanti extracts the email identity of a certificate using the

SubjectAltName RFC822Name value. Ivanti enforces that only one RFC822Name value may exist in a

given certificate, and rejects a certificate if there are multiple values.

X509v3 Subject Alternative Name format: email: <name>@<domain>.com

4. After extracting the email identity from the certificate, Ivanti performs a lookup for the user and

ensures user has the CPS role for the Ivanti Neurons for MDM or Ivanti EPMM tenant.

Security of Certificate Procurement Process

The security of this system depends upon preventing unauthorized users from obtaining certificates that

are valid for authorized users. To that end, DigiCert has the following processes and protections in place:

1. When a certificate for an email address is requested, an email is sent to that email address requesting

confirmation of the certificate request. Note: it is not required that the requester has access to the

email address. This allows admins to request (and pay for) certificates on behalf of users.

2. The certificate is only generated when the email recipient clicks the confirmation link. Prior to this, the

certificate requester is prevented from seeing the certificate.

3. The certificate and private key are sent to the email address to which the certificate belongs. If the

certificate is requested by person A who does not have access to mailbox B, then A will not be able to

obtain the private key.

4. The certificate (public) is visible to the certificate requester on Digicert's website, but the private key is

not. Certificate-based Mutual Authentication works by proving that each side has possession of their

respective private key. Thus, by providing the private key only to the intended recipient and not the

requester, the system prevents attackers from gaining unauthorized access to the APIs.

Assigning the CPS role to a user

The process differs between Ivanti Neurons for MDM and Ivanti EPMM.

Page 15 of 108

Getting Started

Assigning the CPS role to a Ivanti Neurons for MDM user

To assign the CPS role to a user:

1. Log in to Ivanti Neurons for MDM and then click Users.

2. Select Users.

3. Select a user.

4. Select Append Roles.

Page 16 of 108

Getting Started

5. Select the Common Platform Services (CPS) role.

6. Click Next.

7. Click Done.

Assigning the CPS role to a Ivanti EPMM user

To assign the CPS role to a user:

1. Log in to Ivanti EPMM and then click Admin.

Page 17 of 108

Getting Started

2. Select a user.

3. Select Edit Roles.

4. Assign the admin user to the global space.

The user will be unable to access Common Platform Services functionality if assigned to a device

space other than global.

5. Select the Common Platform Services (CPS) role.

6. Click Save.

Page 18 of 108

Getting Started

Enabling messaging

The process for enabling messaging differs between Ivanti Neurons for MDM and Ivanti EPMM. See the

following sections for details.

Ivanti recommends to allow HTTPS traffic on port 8443 from the corporate network, limited to Ivanti

applications only. This service is intended for EPMM server management and must have strictly controlled

access.

Enabling messaging on Ivanti Neurons for MDM

You can enable messaging using the Ivanti Neurons for MDM admin portal.

To enable messaging:

1. Login to Ivanti Neurons for MDM, and then select Admin.

2. Select Common Platform Services Notifications.

3. Toggle the CPS notifications switch to enable or disable the service.

Enabling messaging on Ivanti EPMM

You run the Ivanti EPMM CLI program to enable messaging. This procedure invokes a message broker,

enables the Event Notification Service event notification feature, restarts the Ivanti server, and restarts

Apache Tomcat (on Ivanti EPMM) to reload configurations.

Considerations:

Page 19 of 108

Getting Started

• The Messaging server listens to subscribing client requests over port 8883, and this port must be

open inbound for the service to function.

• If Ivanti EPMM is running in a High Availability configuration, please enable messaging on both

primary and secondary nodes.

To enable or disable messaging, run the Ivanti EPMM CLI program as shown below:

host:~ host$ ssh miadmin@hostname

miadmin@hostname's password:

Last login: Thu May 4 13:43:48 2017 from 10.101.10.191

************************************************************

* Ivanti EPMM CLI *

* *

************************************************************

Welcome miadmin it is Thu May 4 13:49:39 UTC 2017

CORE(9.4.0.0-2388)@hostname> enable

Password:

CORE(9.4.0.0-2388)@hostname#configure terminal

Enter configuration commands, one per line.

CORE(9.4.0.0-2388)@hostname/config#activemq

Warning:Maintenance mode command.

Portal service will be stopped during this operation. Proceed? (y/n)y

Updating chkconfig...

Page 20 of 108

Getting Started

Updating portal...

Starting ActiveMQ...

INFO: Loading '/mobileiron.com/programs/org.apache.activemq/bin/env'

INFO: Using java '/mobileiron.com/programs/com.mobileiron.platform.jre8/bin/java'

INFO: Starting - inspect logfiles specified in logging.properties and log4j.properties

to get details

INFO: pidfile created : '/mobileiron.com/programs/org.apache.activemq/data/activemq.pid'

(pid '22954')

Capturing tomcat metrics: [ OK ]

Stopping tomcat: [ OK ]

Starting tomcat: Using TOMCAT_ALLOCATION_MB=2048

Using JAVA_OPTS=-Xms128m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=512m -

XX:+OptimizeStringConcat -server -Dvsp.branding=mobileiron -Dmi.hostname=hostname -

Dfile.encoding=utf-8 -Djavax.net.ssl.keyStore=/usr/java/default/jre/lib/security/cacerts

-Djava.security.auth.login.config=/mi/files/ldap/gsseg_jaas.conf -

Djava.security.krb5.conf=/mi/files/ldap/krb5.conf -Dspring.auth.method=form -

Dsun.net.inetaddr.ttl=60 -Dmi.tcp.port.system.manager.portal=8443 -

Djsse.enableSNIExtension=false -Dmi.version=9.4.0.0-2388 -Xms1024m -Xmx2048m -XX:-

HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/mi/files -verbose:gc -XX:+PrintGCDateStamps

-XX:+PrintGCTimeStamps -XX:+PrintGCDetails -Xloggc:/mi/tomcat/logs/gc.log -

XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:MaxNewSize=480M -XX:NewRatio=7 -

XX:TargetSurvivorRatio=90 -XX:CMSInitiatingOccupancyFraction=60

[ OK ]

Successfully enabled activemq

CORE(9.4.0.0-2388)@hostname/config#no activemq

Warning:Maintenance mode command.

Portal service will be stopped during this operation. Proceed? (y/n)y

Updating chkconfig...

Updating portal...

Page 21 of 108

Getting Started

Stopping ActiveMQ...

INFO: Loading '/mobileiron.com/programs/org.apache.activemq/bin/env'

INFO: Using java '/mobileiron.com/programs/com.mobileiron.platform.jre8/bin/java'

ERROR: No or outdated process id in

'/mobileiron.com/programs/org.apache.activemq/data/activemq.pid'

INFO: Removing /mobileiron.com/programs/org.apache.activemq/data/activemq.pid