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, 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:
|
-
|
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. |
|
-
|
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. |
|
-
|
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. |
|
-
|
User clicks the URL to generate the certificate. |
|
-
|
User or partner requests the Ivanti admin to create a user. |
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. |