To use the Unified Access Gateway REST API to configure certificate settings, or to use the PowerShell scripts, you must convert the certificate into PEM-format files for the certificate chain and the private key, and you must then convert the .pem files to a one-line format that includes embedded newline characters.

When configuring Unified Access Gateway, there are three possible types of certificates you might need to convert.

  • You should always install and configure a TLS/SSL server certificate for the Unified Access Gateway appliance.
  • If you plan to use smart card authentication, you must install and configure the trusted CA issuer certificate for the certificate that will be put on the smart card.
  • If you plan to use smart card authentication, VMware recommends that you install and configure a root certificate for the signing CA for the SAML server certificate that is installed on the Unified Access Gateway appliance.

For all of these types of certificates, you perform the same procedure to convert the certificate into a PEM-format file that contains the certificate chain. For TLS/SSL server certificates and root certificates, you also convert each file to a PEM file that contains the private key. You must then convert each .pem file to a one-line format that can be passed in a JSON string to the Unified Access Gateway REST API.

Prerequisites

  • Verify that you have the certificate file. The file can be in PKCS#12 (.p12 or .pfx) format or in Java JKS or JCEKS format.
  • Familiarize yourself with the openssl command-line tool that you will use to convert the certificate. To see the cipher list format, you can search for "openssl cipher string" in a web browser.
  • If the certificate is in Java JKS or JCEKS format, familiarize yourself with the Java keytool command-line tool to first convert the certificate to .p12 or .pks format before converting to .pem files.

Procedure

  1. If your certificate is in Java JKS or JCEKS format, use keytool to convert the certificate to .p12 or .pks format.
    Important: Use the same source and destination password during this conversion.
  2. If your certificate is in PKCS#12 (.p12 or .pfx) format, or after the certificate is converted to PKCS#12 format, use openssl to convert the certificate to .pem files.
    For example, if the name of the certificate is mycaservercert.pfx, use the following commands to convert the certificate: 
    openssl pkcs12 -in mycaservercert.pfx -nokeys -out mycaservercert.pem
openssl pkcs12 -in mycaservercert.pfx -nodes -nocerts -out mycaservercertkey.pem
openssl rsa -in mycaservercertkey.pem -check -out mycaservercertkeyrsa.pem
  3. Edit mycaservercert.pem and remove any unnecessary certificate entries. It should contain the one SSL server certificate followed by any necessary intermediate CA certificates and root CA certificate.
  4. Use the following UNIX command to convert each .pem file to a value that can be passed in a JSON string to the Unified Access Gateway REST API: 
    awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' cert-name.pem

    In this example, cert-name.pem is the name of the certificate file. The certificate looks similar to this example.

    Figure 1. Certificate File on a Single Line
    Sample certificate file with information on a single line and embedded newline characters
    The new format places all the certificate information on a single line with embedded newline characters. If you have an intermediate certificate, that certificate must also be in one-line format and add to the first certificate so that both certificates are on the same line.

Results

You can now configure certificates for Unified Access Gateway by using these .pem files with the PowerShell scripts attached to the blog post "Using PowerShell to Deploy VMware Unified Access Gateway," available at https://communities.vmware.com/docs/DOC-30835. Alternatively, you can create and use a JSON request to configure the certificate.

What to do next

You can update the default self-signed certificate with a CA-signed certificate. See Update SSL Server Signed Certificates. For smart card certificates, see Configuring Certificate or Smart Card Authentication on the Unified Access Gateway Appliance.