Configuring the Credential Escrow Gateway creates a trust and secure communication channel between client and host. Learn more about configuring Workspace ONE UEM Credential Escrow Gateway.

While following the steps to configure Credential Escrow Gateway, there are several general considerations to keep in mind.

  • The CEG API requires mutual TLS authentication (mTLS).

  • The CEG API server must present to the client a proper server-side certificate for

  • TLS handshake.

  • API requests to Credential Escrow Gateway must present a client certificate whose thumbprint is allowed by CEG.

Note: To generate certificate trust between Credential Escrow Gateway and ACC, the certificate needs to be generated via OpenSSL. Certificate generated by windows PowerShell for trust between Credential Escrow Gateway and Certificate Authority works fine.

Configure CEG server's TLS certificate

Credential Escrow Gateway needs a server certificate for API calls over HTTPS. The CA of this certificate needs to be trusted by ACC in order to establish TLS communication between ACC and CEG. The following are steps to installing the TLS certificate on CEG.

  1. Convert the TLS certificate to a pfx/p12 file with a password

  2. Upload the TLS certificate to the following folder inside Credential Escrow Gateway.

    You can upload using scp with the root user's credential.

    /opt/vmware/docker/ceg/compose-config/tls-certificate.pfx

  3. Log into Credential Escrow Gateway using SSH or VM Console.

  4. Use an editor such as vim to edit the file:

    /opt/vmware/docker/ceg/docker-compose.yml

  5. Modify the following lines so that the new file name and the certificate's password match the pfx/p12 file you just uploaded. The file path should not be changed.

    1. ASPNETCORE_Kestrel__Certificates__Default__Password=airwatch-

    2. ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx

    Note:

    The above two-line group appears twice in the yml file. You must change it in both places.

  6. Save the changes and reboot Credential Escrow Gateway VA

  7. To test the TLS certificate

    1. Login to ACC Windows desktop

    2. Use a web browser to open the URL: https://{CEG hostname}/v1/hc

      Note:

      A properly installed certificate will prevent the browser from warning about an invalid certificate. The result should show a host hash id.

Configure client certificate for mTLS

Because the API requests issued by Workspace ONE UEM to Credential Escrow Gateway (CEG) are proxied by ACC, ACC needs to have the client certificate used for mTLS. Workspace ONE UEM specifies which certificate to use, and the specified certificate must also be allowed by Credential Escrow Gateway.

  1. Choose or install a client certificate on ACC

    1. Log onto ACC's Windows desktop.

    2. Launch Manage Computer Certificates by typing in the text after clicking the Windows key.

    3. In the Personal Certificate store, you can select or install a certificate to be used for mTLS client authentication.

    4. The requirements for this certificate include:

      1. Must have a private key

      2. The key usages are appropriate for client authentication

      3. It must be a root certificate because EG cannot obtain the revocation list for a non-root certificate.

        Note:

        Since Credential Escrow Gateway validates the certificate only by its thumbprint, self-signed certificates do work.

        With this certificate in place, write down its thumbprint. Keep in mind that copying the thumbprint from this dialog can contain the NUL '\0' character at the beginning or end, causing problems if you paste it elsewhere.

Configure WS1 UEM to use the selected client certificate

This configuration is done with UEM API's.

  1. Use the following API to get the Organization Group's UUID. This UUID is required to make the configuration change.

    curl -i -X GET \-H 'Content-Type: application/json'\-H 'aw-tenant-code: {API access key provisioned from Settings->System->Advanced->API} \-H 'Authorization: Basic {base64 encoding of admin-username:password}'\'https://{WS1 UEM hostname}/api/v1/system/groups/{the OG's integer id}'

    The Organization Group's integer id is displayed in the web browser's address bar when you view the Organization Group's details in UEM Console from Groups & Settings > Organizations Groups > Details.

  2. The response has a UUID field:

    "Uuid":"6eea71da-d8ef-4e51-b407-d22a0e41336a"

    Copy the UUID value and use it in the following configuration query:

    curl -i -X GET \-H 'Content-Type: application/json'\-H 'aw-tenant-code: {API access key provisioned from Settings->System->Advanced->API}'\-H 'Authorization: Basic {base64 encoding of admin-username:password}'\'https://{WS1 UEM hostname}/api/v1/system/groups/{OG UUID}/escrow-gateway-settings'
  3. To make the configuration change:

    curl -i -X PUT \-H 'Content-Type: application/json'\-H 'aw-tenant-code: {API access key provisioned from Settings->System->Advanced->API}'\-H 'Authorization: Basic {base64 encoding of admin-username:password}'\--data-raw '{"gateway_url":"https://{CEG hostname}", "client_cert_thumbprint":"{the client certificate's thumbprint"}' \'https://{WS1 UEM hostname}/api/v1/system/groups/{OG UUID}/escrow-gateway-settings'

Allow the client certificate in Credential Escrow Gateway

  1. Log into Credential Escrow Gateway VA using SSH or VM console

  2. Use an editor such as vim to edit the file:

    /opt/vmware/docker/ceg/compose-config/authorized-client-certs.env

    Here is an example of adding an allowed certificate thumbprint:

    AuthorizedClientCertThumbprints__0=0D63640B84A97544DE1C3E7EB7F4E9EABE9152D7

  3. Save the changes and reboot Credential Escrow Gateway VA

Test client certificate

  1. To test client certificate configuration:

    1. Log onto ACC Windows Desktop

    2. Export the client certificate to a pfx file

    3. From a bash terminal (e.g., Git Windows' bash terminal), run this command:

      curl -iv 'https://{CEG hostname}/v1/hc'\--cert path-to-exported-client-certificate-file-in-p12-format:cert-password \--cert-type p12

      The result should be success (200 OK) and should contain Credential Escrow Gateway's host name in hash format.

Logs for Credential Escrow Gateway

  1. Application logs are in /var/log/vmware/docker/ceg/

Configuring logging level, Encryption, and Certificate retention period

All configurations for Escrow Gateway can be updated through the .env files located in /opt/vmware/docker/ceg/compose-config directory. The following are the file names and the configurations available through them.

File Name

Configuration Name

Description

Allowed Values

Default

Logging.settins.env

Serilog__MinimumLevel__Default

Change the application logging level.

Verbose

Debug

Information

Warning

Error

Fatal

Information

redis.encryption.settings.env

EncryptionConfiguration__EnableEncryption

If true, encrypts SMIME certificates before storing them into Redis. By default, this is disabled.

NOTE: Needs to be set at application start or data corruption occurs.

base64 string representation of an encryption key

Empty. Please uncomment the line and add the desired value.

redis.encryption.settings.env

EncryptionConfiguration__EncryptionKey

If EncryptionConfiguration__EnableEncryption property is set to true, provide a base64 encoded key to use for encryption.

NOTE: Needs to be set at application start or data corruption occurs.

true

false

true

redis.retention.settings.env

smimeCertificateRetention__UseCertificateExpiryAsRetention

If true, Certificate expiration date is used as retention period. If false, the value set at redisKeyRetention__DefaultKeyExpiryTimeInDays is used.

true

false

true

redis.retention.settings.env

redisKeyRetention__DefaultKeyExpiryTimeInDays

The default retention period used for smime_certificates if smimeCertificateRetention__UseCertificateExpiryAsRetention is set to false.

±5.0 × 10−324

to

±1.7 × 10308

3

redis.retention.settings.env

smimeCertificateRetention__DeleteCertificateAfterConsumption

If true, overrides the above-mentioned retention period settings and deletes certificates as soon as it is used to complete a profile request.

true

false

false

For any of the above changes to take effect, the following steps need to be executed after updating the configurations.
Docker stack rm ceg
Docker stack deploy -c/opt/vmware/docker/ceg/docker-compose.yml ceg