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

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": "bmalinowski@vmware.com", 
"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 new 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 steps below.

  2. After receiving the Event Notification, the Certificate Provider should first request or provision the necessary certificate(s) that is to be delivered to the device.

    1. Output: Client Certificate for a given User and/or Device combination.

  3. The Certificate Provider should then upload the certificate(s) 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. Here we will 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 SMIME certificates to be uploaded to EG for a given 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 SMIME certs.

    The expiration of these certs are tracked by the customers. So they are responsible for uploading new certificates for the expiring certs.