Use Custom Certificates with Auto Deploy

In vSphere 8.0 and later, you can set up the Auto Deploy server to provision ESXi hosts with custom certificates that are signed by a third-party certificate authority (CA) or your own internal CA. By default, the Auto Deploy server provisions ESXi hosts with certificates that are signed by the VMware Certificate Authority (VMCA).

Prior to vSphere 8.0, your options for managing certificates with Auto Deploy include:

Using vCenter Server and the built-in VMware Certificate Authority (the default).
Making Auto Deploy a subordinate CA of a third-party CA. In this case, the Auto Deploy SSL key signs the certificates.

In vSphere 8.0 and later, you can upload custom certificates to Auto Deploy that are signed by either a third-party CA or your own internal CA. Auto Deploy associates the custom certificate with either the MAC address or BIOS UUID of the ESXi host. Each time an Auto Deploy host starts, Auto Deploy checks for a custom certificate. If Auto Deploy finds a custom certificate, it uses that certificate instead of generating one through the VMCA.

The high-level steps for this task include:

Generating the custom certificate request for either a third-party CA or for your own internal CA.
Obtaining the signed custom certificate (key and certificate) and storing it locally.
If you are using a third-party CA, and if not previously done, ensuring the root certificate of your CA is uploaded to the TRUSTED_ROOTS store on the vCenter Server.
Uploading the custom certificate to Auto Deploy and associating the certificate with either the MAC address or BIOS UUID of an ESXi host.
Booting the ESXi host.

When you assign a custom certificate to an ESXi host, Auto Deploy pushes the certificate to the host on its next boot from Auto Deploy.

Be aware of the following considerations when using custom certificates and Auto Deploy.

You must use the PowerCLI Add-CustomCertificate, Remove-CustomCertificate, and List-CustomCertificate cmdlets to manage custom certificates used with Auto Deploy. The capability to manage custom certificates is not available in the vSphere Client.
To refresh a custom certificate used for Auto Deploy, you must run the Add-CustomCertificate cmdlet again.
Be sure to examine your custom certificate for potential errors. Auto Deploy verifies only that the custom certificate complies with the X.509 certificate standards and that the expiration threshold of the certificate is set to at least 240 days. Auto Deploy does not perform any other certificate validation or checking. To change the certificate threshold, you can run the Set-DeployOption -Key certificate-refresh-threshold cmdlet.
If you later remove a custom certificate from an ESXi host using the Remove-CustomCertificate cmdlet, you must restart the host for the change to take effect.

For more information about custom certificates and Auto Deploy, see the VMware ESXi Installation and Setup documentation.

Prerequisites

Ensure that you have the following:

Request a certificate from your certificate authority. The certificate must meet these requirements.
- Key size: 2048 bits (minimum) to 8192 bits (maximum) (PEM encoded)
- PEM format. VMware supports PKCS8 and PKCS1 (RSA keys). When keys are added to VECS, they are converted to PKCS8.
- x509 version 3
- CRT format
- CA extension set to true
- Key usage of Certificate Signing
- Start time of one day before the current time
Note: vSphere's FIPS certificate only validates RSA key sizes of 2048 and 3072. See Considerations When Using FIPS.
ESXi host MAC address or BIOS UUID. Evaluate which approach makes best sense for your environment. The BIOS UUID is more stable and less subject to change than the MAC address. If you change network adapters in an ESXi host, the MAC address changes. However, the MAC address might be more familiar to work with, and easier to obtain than the BIOS UUID.
At least PowerCLI version 12.6.0. For more information on Auto Deploy PowerCLI cmdlets, see the Auto Deploy PowerCLI Cmdlet Overview topic in the VMware ESXi Installation and Setup documentation.

Ensure that you have the following privileges:

Add custom certificate: Autodeploy.Rule.Create
Get custom certificate information: System.Read

Procedure

Generate the certificate request.
1. Using the requirements listed previously for the certificate request, create a configuration (.cfg) file.
2. To generate a CSR file and a key file, run the openssl req command, passing in the configuration (.cfg) file.
  For example:
```
openssl req -new -config custom_cert.cfg -days 4200 -sha256 -keyout rui.key -out rui.csr
```
  In this command:
  - -new generates a new certificate request.
  - -config custom_cert.cfg specifies your custom .cfg file.
  - -days 4200 specifies 4200 days to certify the certificate for.
  - -sha256 specifies the message digest to sign the request with.
  - -keyout rui.key specifies the file to write the newly created private key to.
  - -out rui.csr specifies the output file to write to.
Either send the certificate request to your third-party CA, or, if you sign your own certificates, run the openssl x509 -req command to generate your custom certificate from your rui.csr file.
For example:
```
openssl x509 -req -in rui.csr -CA "/etc/vmware-rbd/ssl/rbd-ca.crt" -CAkey \
"/etc/vmware-rbd/ssl/rbd-ca.key" -extfile \
openssl.cfg -extensions x509 -CAserial "/etc/vmware-rbd/ssl/rbd-ca.srl" -days \
4200 -sha256 -out signed_rui.crt
```
In this command:
- -in rui.csr specifies the input file.
- -CA "/etc/vmware-rbd/ssl/rbd-ca.crt" specifies the directory to use for server certificate verification.
- -CAkey "/etc/vmware-rbd/ssl/rbd-ca.key" sets the CA private key to sign a certificate with.
- -extfile openssl.cfg specifies an additional, optional configuration file to read certificate extensions from.
- -extensions x509 specifies to use x509 certificate extensions.
- -CAserial "/etc/vmware-rbd/ssl/rbd-ca.srl" uses the serial number in rbd-ca.srl to sign a certificate.
- -days 4200 specifies 4200 days to certify the certificate for.
- -sha256 specifies the message digest to sign the request with.
- -out signed_rui.crt specifies the output file to write to.
(Optional) If you haven't previously uploaded the certificate of your signing certificate authority to the TRUSTED_ROOTS store inside the VMware Endpoint Certificate Store (VECS), perform the following steps on the vCenter Server where the Auto Deploy service runs.
1. Using a tool such as WinSCP, copy the certificate to the vCenter Server.
2. Log in to the vCenter Server using SSH and run the following command.
```
/usr/lib/vmware-vmafd/bin/dir-cli trustedcert publish --cert path_to_ca_certificate
```
Obtain either the ESXi host MAC address or BIOS UUID.
Perform the following steps to add the custom certificate to Auto Deploy.
1. To connect to the vCenter Server, run the Connect-VIServer cmdlet.
```
Connect-VIServer -server VC_ip_address -User administrator_user -Password 'password'
```
2. (Optional) To view existing custom certificates, run the Get-CustomCertificates cmdlet.
  The first time you add custom certificates, you don't see any certificates returned by this cmdlet.
3. To associate the custom certificate with the ESXi host, run the Add-CustomCertificate cmdlet.
```
Add-CustomCertificate -HostID [MAC_Address | BIOS_UUID] -Certificate "path_to_custom_cert" -Key "path_to_custom_cert_key"
```
  You can specify either the MAC address or the BIOS UUID of the host. Auto Deploy uploads the custom certificate to the host.
4. To verify that the certificate was uploaded, run the Get-CustomCertificates cmdlet.
  You see output similar to the following:
```
Name:     CustomHostCert-1
CertificateId:      1
HostId:             02:08:b0:8e:18:a2
ExpirationTime: 1   2/28/2033 10:45:50 AM
TimeCreated:        9/29/2022 7:40:28 AM
LastModified:       9/29/2022 7:40:28 AM
AssociatedHostName: 
```
  The AssociatedHostName is blank for now. After you start the host, the output reflects the name of the ESXi host associated with the custom certificate.
Start the ESXi host.

To verify that the custom certificate is associated with the vCenter Server, run the Get-CustomCertificates cmdlet again.

You see output resembling the following.

Name:     CustomHostCert-1
CertificateId:      1
HostId:             02:08:b0:8e:18:a2
ExpirationTime: 1   2/28/2033 10:45:50 AM
TimeCreated:        9/29/2022 7:40:28 AM
LastModified:       9/29/2022 7:40:28 AM
AssociatedHostName: host1.example.com

Now the AssociatedHostName contains the name of the ESXi host.