The Certificate Provider is responsible for listening to Event Notifications from UEM and forwarding the information to Certificate Authority to generate SMIME cert for a specific user and send that certificate to escrow gateway.

Event Notification Configuration

Customer must subscribe to the following events from UEM by configuring them in Admin Console.

Device Enrollment - this event will be fired when a new device enrolls.

The following example shows how to add event notification for Device Enrollment

Add Evemt Notification where you notification information for when a device is enrolled.

Add Event Notification settings where you enable or disable Device Enrollment notifications.

The following is an example payload for an Enrollment event.

{ "EventId": 148, 
"EventType": "MDM Enrollment Complete", 
"DeviceId": 15, 
"DeviceFriendlyName": "zenny iPod Touch Apple 12.4.5 GGK6", "EnrollmentEmailAddress": "", 
"EnrollmentUserName": "zenny", 
"EventTime": "2020-02-24T16:52:25.9231303Z", 
"EnrollmentStatus": "Enrolled", 
"CompromisedStatus": "", 
"CompromisedTimeStamp": "2020-02-24T16:52:28.9075371Z", "ComplianceStatus": "Compliant", 
"PhoneNumber": "", 
"Udid": "902dca357c02dbc1306ff99ffbf4b9c80218f3a3", 
"SerialNumber": "CCQQ44BMGGK6", 
"MACAddress": "000000000000", 
"DeviceIMEI": "", 
"EnrollmentUserId": 12, 
"AssetNumber": "902dca357c02dbc1306ff99ffbf4b9c80218f3a3", 
"Platform": "Apple", 
"OperatingSystem": "12.4.5", 
"Ownership": "CorporateDedicated", 
"SIMMCC": "", 
"CurrentMCC": "", 
"OrganizationGroupName": "CEG", 
"DeviceUUID": "f90f1abd-b914-4895-9b59-82e8aecf0e66", "EnrollmentUserUUID": "fe13e814-7415-4fce-9f47-de5a55bfe57a"}

Certificate Provider Design

The following are the steps that need to be executed by the customer requesting Certificates to be provisioned through Escrow Gateway by configuring an EG credential profile.

  1. Create a Profile and configure a credential payload with Credential Source as Escrow Gateway and add Signing Certificate or Encryption Certificate or both. You can either publish the profile now or do so after uploading the certificates to EG using the following steps.

    Image showing where to add credentials on the New Apple iOS Profile.

  2. After receiving the Event Notification, the Certificate Provider requests or provisions thes necessary certificates that is to be delivered to the device.
    1. Output: Client Certificate for a given User and/or Device combination.
  3. The Certificate Provider uploads the certificates to the Escrow Gateway. This process can be asynchronous because the entire Escrow Gateway workflow is asynchronous. Escrow Gateway also requires mutual TLS authentication to service requests. Construct a request using cURL.
    1. Input variables for constructing the cURL request:
      1. Escrow Gateway Server URL - EG server that is setup in the customer's environment.
      2. certificate.pfx - A client certificate that is in the approved client certificate list configured at EG used for mTLS authentication with Escrow Gateway.
      3. password - Password for the certificate.pfx file used for mTLS
      4. certificate-payload.json - a required JSON file containing the S/MIME certificates to be uploaded to EG for a User and Device combination
        1. device_uuid - DeviceUUID value from the Event Notification payload
        2. user_uuid - EnrollmentUserUUID value from the Event Notification payload
        3. smime_certificates - JSON containing the following optional fields based on how the Profile is configured in Console in Step 1.
          • signing - An array of base64 encoded Signing certificates as required, generated in Step 2.
          • encryption - An array of base64 encoded Encryption certificates as required, generated in Step 2.
          • archived - An array of expired signing/encryption certificates of a given user and/or device combination.
          Sample cURL to upload certificates to EG
          curl -ik -X POST '<Escrow Gateway Server URL>/v2/certificates' \
          --header 'Content-Type: application/json' \
          --header 'Accept: application/json' \
          --cert <certificate.pfx>:<password> \
          --cert-type p12 \
          --data <Sample certificate-payload.json>

    b. Renew/replace S/MIME certs.

    Customers track the expiration of these certs. Customers are responsible for uploading new certificates for the expiring certs.