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.

Configuration certificates used in Credential Escrow Gateway (CEG):

  • Client Certs: These certificates are authorized certs that client can use toinvoke CEG APIs

  • Thumbprints of client certs are pinned on CEG.

  • CEG uses the list of pinned certificate thumbprints to authorize API access.

  • SSL cert: This certificate is used for binding https (443) port. The API application runs on port 443.

  • SSL certificate will be presented to client when it accesses CEG APIs over https.

  • CEG virtual appliance is shipped with self-signed SSL cert for localhost.

The Credential Escrow Gateway exposes a set of configuration APIs (on port 5002), which will allow a VA admin to query and override existing configuration certificates. The next steps will need to be performed from a terminal logged into the VA since the 5002 port is blocked by the Virtual Appliance's firewall for incoming requests. Please keep the localhost:5002 as seen in the examples below.

  1. Health check: This allows you to query health check of the configuration API endpoint.

    curl -k -L -X GET 'https://localhost:5002/v1/hc'

  2. Get configuration: This allows you to query existing certificate configuration for the CEG API endpoint.

    curl -k -L -X GET 'https://localhost:5002/v1/configuration'

  3. Put configuration: This allows you to override existing certificate configuration for the CEG API endpoint.

    curl -k -L -X PUT 'https://localhost:5002/v1/configuration' \ -H 'Content-Type: application/json' \ --data-raw '{ "client_certificate_thumbprints": [ "{client certificate thumbprints} -> This should match up with the client cert you installed on your ACC" ], "server_certificate": { "pkcs12": "{base64-encoded cert string of your tls cert}", "password": "{certificate password1}" } }'

  4. Afterwards you need to run the following script to restart docker services for the configuration changes to take effect

    docker stack rm ceg

    docker stack deploy -c /opt/vmware/docker/ceg/docker-compose.yml ceg

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

Services requiring docker-compose.yml change

Description

Allowed Values

Default

logging.settings.env

Serilog__MinimumLevel__Default

api-0

api-1

skeleton-profile-consumer

completed-profile-consumer

Change the application logging level.

Verbose

Debug

Information

Warning

Error

Fatal

Information

redis.encryption.settings.env

EncryptionConfiguration__EnableEncryption

api-0

api-1

skeleton-profile-consumer

completed-profile-consumer

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

NOTE: Needs to be set at application start. Will lead to data corruption otherwise.

True

False

False

redis.encryption.settings.env

EncryptionConfiguration__EncryptionKey

api-0

api-1

skeleton-profile-consumer

completed-profile-consumer

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

NOTE: This property should be set only once at application start along with the EncryptionConfiguration__EnableEncryption property. Changes in this value in future will lead to errors/data corruption.

tbase64 string representation of an encryption key

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

redis.retention.settings.env

NOTE: If this setting is changed, it will only be applied for future uploads. All existing data will use the retention setting from when you actually uploaded the data.

smimeCertificateRetention__UseCertificateExpiryAsRetention

api-0

api-1

skeleton-profile-consumer

completed-profile-consumer

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

api-0

api-1

skeleton-profile-consumer

completed-profile-consumer

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

api-0

api-1

skeleton-profile-consumer

completed-profile-consumer

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