Getting Started

24 min

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, Certificate-based authentication workflows,and Example Ivanti Neurons for MDM certificate-based authentication cURL command.

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.

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

Certificate-based authentication

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 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 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 for how to set up certificate-based authentication, and Certificate-based authentication security 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 and Example Ivanti Neurons for MDM certificate-based authentication cURL command 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:

	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 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 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 for how to assign the CPS role to users.

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:

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.