Managing the vCenter Server Security Token Service

The vCenter Server Security Token Service (STS) is a Web service that issues, validates, and renews security tokens.

As a token issuer, the Security Token Service (STS) uses a private key to sign the tokens and publishes the public certificates for services to verify the token signature. vCenter Server manages the STS signing certificates and stores them in the VMware Directory Service (vmdir). Tokens can have a significant lifetime, and historically might have been signed by any one of multiple keys.

Users present their primary credentials to the STS interface to acquire tokens. The primary credential depends on the type of user.

Table 1. STS Users and Credentials
Type of User	Primary Credentials
Solution user	Valid certificate.
Other users	User name and password available in a vCenter Single Sign-On identity source.

STS authenticates the user based on the primary credentials, and constructs a SAML token that contains user attributes.

By default, the VMware Certificate Authority (VMCA) generates the STS signing certificate. You can refresh the STS signing certificate with a new VMCA certificate. You can also import and replace the default STS signing certificate with a custom or third-party generated STS signing certificate. Do not replace the STS signing certificate unless the security policy of your company requires replacing all certificates.

You can use the vSphere Client to:

Refresh STS certificates
Import and replace custom and third-party generated STS certificates
View STS certificate details, such as the expiration date

You can also use the command line to replace custom and third-party generated STS certificates.

STS Certificate Duration and Expiration

A fresh installation of vSphere 7.0 Update 1 and later creates an STS signing certificate with a duration of 10 years. When an STS signing certificate is close to expiring, an alarm warns you starting at 90 days once per week, and then daily when seven days away.

Note: In certain circumstances, replacing your STS signing certificates can change the duration of the certificates. When performing certificate replacement, pay attention to the issuing and expiration dates.

STS Certificate Auto-Renewal

In vSphere 8.0 and later, vCenter Single Sign-On automatically renews a VMCA-generated STS signing certificate. The auto-renewal occurs before the STS signing certificate expires and before triggering the 90-day expiration alarm. If the auto-renewal fails, vCenter Single Sign-On creates an error message in the log file. If necessary, you can refresh the STS signing certificate manually.

Note: vCenter Single Sign-On does not perform auto-renewal of custom generated or third-party STS signing certificates.

Refreshing and Importing and Replacing STS Certificates

In vSphere 8.0 and later, refreshing or importing and replacing the STS signing certificates does not require a vCenter Server restart and so avoids any downtime. Also, in a linked configuration, refreshing or importing and replacing the STS signing certificates on a single vCenter Server updates the STS certificates on all the linked vCenter Server systems.

Note: In certain circumstances, a refresh or import and replace of STS signing certificates can require you to manually restart the vCenter Server systems.

Refresh a vCenter Server STS Certificate Using the vSphere Client

You can refresh your vCenter Server STS signing certificates using the vSphere Client. The VMware Certificate Authority (VMCA) issues a new certificate and replaces the current certificate.

When you refresh STS signing certificates, the VMware Certificate Authority (VMCA) issues a new certificate and replaces the current certificate in the VMware Directory Service (vmdir). STS starts using the new certificate to issue new tokens. In an Enhanced Linked Mode configuration, vmdir uploads the new certificate from the issuing vCenter Server system to all linked vCenter Server systems. When you refresh STS signing certificates, you do not need to restart the vCenter Server system, nor any other vCenter Server system that is part of an Enhanced Linked Mode configuration.

If you are using a custom generated or third-party STS signing certificate, the refresh overwrites that certificate with a VMCA-issued certificate. To update custom generated or third-party STS signing certificates, use the import and replace option. See Import and Replace a vCenter Server STS Certificate Using the vSphere Client.

The VMCA-issued STS signing certificate is valid for 10 years and is not an external-facing certificate. Do not replace this certificate unless the security policy of your company requires it.

Prerequisites

For certificate management, you must supply the password of the administrator of the local domain (administrator@vsphere.local by default). If you are renewing certificates, you must also supply the vCenter Single Sign-On credentials for a user with administrator privileges on the vCenter Server system.

Procedure

Log in with the vSphere Client to the vCenter Server.
Specify the user name and password for administrator@vsphere.local or another member of the vCenter Single Sign-On Administrators group.
If you specified a different domain during installation, log in as administrator@ mydomain.
Navigate to the Certificate Management UI.
1. From the Home menu, select Administration.
2. Under Certificates, click Certificate Management.
If the system prompts you, enter the credentials of your vCenter Server.
Under the STS Signing tab, select the desired certificate and click Refresh with vCenter Certificate.
If you are using a custom generated or third-party STS signing certificate, the refresh action overwrites that certificate with a VMCA-generated certificate.
Note: If you were using third-party certificates for compliance reasons, the refresh might cause your vCenter Server systems to go out of compliance. Also, if you are using a custom generated or third-party STS signing certificate, the Security Token Service no longer uses that custom or third-party certificate for token signing.
Click Refresh.
The VMCA refreshes the STS signing certificate on this vCenter Server system and on any linked vCenter Server systems.
(Optional) If the Force Refresh button appears, vCenter Single Sign-On has detected a problem. Before clicking Force Refresh, consider the following potential results.
- If all the impacted vCenter Server systems are not running at least vSphere 7.0 Update 3, they do not support the certificate refresh.
- Selecting Force Refresh requires that you restart all vCenter Server systems and can render those systems inoperable until you do so.
1. If you are unsure of the impact, click Cancel and research your environment.
2. If you are sure of the impact, click Force Refresh to proceed with the refresh then manually restart your vCenter Server systems.

Import and Replace a vCenter Server STS Certificate Using the vSphere Client

You can import and replace the vCenter Server STS certificate with a custom generated or third-party certificate using the vSphere Client.

To import and replace the default STS signing certificate, you must first generate a new certificate. When you import and replace STS signing certificates, the VMware Directory Service (vmdir) uploads the new certificate from the issuing vCenter Server system to all linked vCenter Server systems.

The STS certificate is not an external-facing certificate. Do not replace this certificate unless the security policy of your company requires it.

Prerequisites

For certificate management, you must supply the password of the administrator of the local domain (administrator@vsphere.local by default). You also must supply the vCenter Single Sign-On credentials for a user with administrator privileges on the vCenter Server system.

Procedure

Log in with the vSphere Client to the vCenter Server.
Specify the user name and password for administrator@vsphere.local or another member of the vCenter Single Sign-On Administrators group.
If you specified a different domain during installation, log in as administrator@ mydomain.
Navigate to the Certificate Management UI.
1. From the Home menu, select Administration.
2. Under Certificates, click Certificate Management.
If the system prompts you, enter the credentials of your vCenter Server.
Under the STS Signing tab, select the desired certificate and click Import and Replace Certificate.
Select the PEM file.
The PEM file includes the signing certificate chain and the private key.
Click Replace.
The STS signing certificate is replaced on this vCenter Server system and on any linked vCenter Server systems. Unless otherwise indicated, you do not need to restart the vCenter Server systems.

Replace a vCenter Server STS Certificate Using the Command Line

You can replace the vCenter Server STS certificate with a custom generated or third-party certificate using the CLI.

To use a company required certificate or to refresh a certificate that is near expiration, you can replace the existing STS signing certificate. To replace the default STS signing certificate, you must first generate a new certificate.

The STS certificate is not an external-facing certificate. Do not replace this certificate unless the security policy of your company requires it.

Caution: You must use the procedures described here. Do not replace the certificate directly in the file system.

Prerequisites

Enable SSH login to vCenter Server. See Manage vCenter Server Using the vCenter Server Shell.

Procedure

Create a certificate.

Create a top-level directory to hold the new certificate and verify the location of the directory.
```
mkdir newsts
cd newsts
pwd 
#resulting output: /root/newsts
```

Copy the certool.cfg file into the new directory.

cp /usr/lib/vmware-vmca/share/config/certool.cfg /root/newsts

Using a command-line editor such as Vim, open your copy of the certool.cfg file and edit it to use the local vCenter Server IP address and hostname. The country is required and has to be two characters, as shown in the following example.

#
# Template file for a CSR request
#

# Country is needed and has to be 2 characters
Country = US
Name = STS
Organization = ExampleInc
OrgUnit = ExampleInc Dev
State = Indiana
Locality = Indianapolis
IPAddress = 10.0.1.32
Email = chen@exampleinc.com
Hostname = homecenter.exampleinc.local

Generate the key.

/usr/lib/vmware-vmca/bin/certool --server localhost --genkey --privkey=/root/newsts/sts.key --pubkey=/root/newsts/sts.pub

Generate the certificate.

/usr/lib/vmware-vmca/bin/certool --gencert --cert=/root/newsts/newsts.cer --privkey=/root/newsts/sts.key --config=/root/newsts/certool.cfg

Create a PEM file with the certificate chain and private key.

cat newsts.cer /var/lib/vmware/vmca/root.cer sts.key > newsts.pem

Update the STS signing certificate, for example:
```
/opt/vmware/bin/sso-config.sh -set_signing_cert -t vsphere.local /root/newsts/newsts.pem
```
The VMCA refreshes the STS signing certificate on this vCenter Server system and on any linked vCenter Server systems.

View the Active vCenter Server STS Signing Certificate Chain Using the vSphere Client

You can use the vSphere Client to view the active vCenter Server STS signing certificate chain and the certificate information, such as the valid until date.

Procedure

Log in with the vSphere Client to the vCenter Server.
Enter the user name and password for a user that has at least Read privileges.
Navigate to the Certificate Management UI.
1. From the Home menu, select Administration.
2. Under Certificates, click Certificate Management.
If the system prompts you, enter the credentials of your vCenter Server.
Under the STS Signing tab, select a certificate, then expand the certificate.
Certificate and issue information is displayed, including:
- Valid until date
- A green check for a valid certificate, and an orange check warning of an expired certificate

Determine the Expiration Date of an LDAPS SSL Certificate Using the Command Line

When using Active Directory over LDAPS, you can upload an SSL certificate for the LDAP traffic. SSL certificates expire after a predefined lifespan. You can use the sso-config.sh command to view the certificate's expiration date so that you know to replace or renew the certificate before it expires.

vCenter Server alerts you when an active LDAP SSL certificate is close to its expiration date.

You see certificate expiration information only if you use Active Directory over LDAP or an OpenLDAP identity source and specify an ldaps:// URL for the server.

Prerequisites

Enable SSH login to vCenter Server. See Manage vCenter Server Using the vCenter Server Shell.

Procedure

Log in as root to the vCenter Server.
Run the following command.
```
/opt/vmware/bin/sso-config.sh -get_identity_sources
```
Ignore the SLF4J messages.
To determine the expiration date, view the SSL certificate's details and verify the NotAfter field.