Use the Command Line to Manage Smart Card Authentication

You can use the sso-config utility to manage smart card authentication from the command line. The utility supports all smart card configuration tasks.

You can find the sso-config script at the following location:

/opt/vmware/bin/sso-config.sh

Configuration of supported authentication types and revocation settings is stored in VMware Directory Service and replicated across all vCenter Server instances in a vCenter Single Sign-On domain.

If user name and password authentication are disabled, and if problems occur with smart card authentication, users cannot log in. In that case, a root or administrator user can turn on user name and password authentication from the vCenter Server command line. The following command enables user name and password authentication.

sso-config.sh -set_authn_policy -pwdAuthn true -t tenant_name

If you use the default tenant, use vsphere.local as the tenant name.

If you use OCSP for revocation check, you can rely on the default OCSP specified in the smart card certificate AIA extension. You can also override the default and configure one or more alternative OCSP responders. For example, you can set up OCSP responders that are local to the vCenter Single Sign-On site to process the revocation check request.

Note: If your certificate does not have OCSP defined, enable CRL (certificate revocation list) instead.

Prerequisites

Verify that an enterprise Public Key Infrastructure (PKI) is set up in your environment, and that certificates meet the following requirements:
- A User Principal Name (UPN) must correspond to an Active Directory account in the Subject Alternative Name (SAN) extension.
- The certificate must specify Client Authentication in the Application Policy or Extended Key Usage field or the browser does not show the certificate.
Add an Active Directory identity source to vCenter Single Sign-On.
Assign the vCenter Server Administrator role to one or more users in the Active Directory identity source. Those users can then perform management tasks because they can authenticate and they have vCenter Server administrator privileges.
Ensure that you have set up the reverse proxy and restarted the physical or virtual machine.

Procedure

Obtain the certificates and copy them to a folder that the sso-config utility can see.
1. Log in to the appliance console, either directly or by using SSH.
2. Enable the appliance shell, as follows.
```
shell
chsh -s "/bin/bash" root
```
3. Use WinSCP or a similar utility to copy the certificates to the /usr/lib/vmware-sso/vmware-sts/conf on the vCenter Server.
4. Optionally disable the shell, as follows.
```
chsh -s "/bin/appliancesh" root
```

To enable smart cart authentication, run the following command.

sso-config.sh -set_authn_policy -certAuthn true -cacerts first_trusted_cert.cer,second_trusted_cert.cer  -t tenant

For example:

sso-config.sh -set_authn_policy -certAuthn true -cacerts MySmartCA1.cer,MySmartCA2.cer  -t vsphere.local

Separate multiple certificates with commas, but do not put spaces after the comma.

To disable all other authentication methods, run the following commands.

sso-config.sh -set_authn_policy -pwdAuthn false -t vsphere.local
sso-config.sh -set_authn_policy -winAuthn false -t vsphere.local
sso-config.sh -set_authn_policy -securIDAuthn false -t vsphere.local

(Optional) To set a certificate policies allowlist, run the following command.
```
sso-config.sh -set_authn_policy -certPolicies policies
```
To specify multiple policies, separate them with a comma, for example:
```
sso-config.sh -set_authn_policy -certPolicies 2.16.840.1.101.2.1.11.9,2.16.840.1.101.2.1.11.19
```
This allowlist specifies object IDs of policies that are allowed in the certificate's certificate policy extension. An X509 certificate can have a Certificate Policy extension.

(Optional) Turn on and configure revocation checking using OCSP.

Turn on revocation checking using OCSP.

sso-config.sh  -set_authn_policy -t tenantName  -useOcsp true

If the OCSP responder link is not provided by the AIA extension of the certificates, provide the overriding OCSP responder URL and OCSP authority certificate.

The alternative OCSP is configured for each vCenter Single Sign-On site. You can specify more than one alternative OCSP responder for your vCenter Single Sign-On site to allow for failover.

sso-config.sh -t tenant -add_alt_ocsp  [-siteID yourPSCClusterID] -ocspUrl http://ocsp.xyz.com/ -ocspSigningCert yourOcspSigningCA.cer

Note: The configuration is applied to the current vCenter Single Sign-On site by default. Specify the siteID parameter only if you configure alternative OCSP for other vCenter Single Sign-On sites.

Consider the following example.

 .sso-config.sh -t vsphere.local -add_alt_ocsp -ocspUrl http://failover.ocsp.nsn0.rcvs.nit.disa.mil/ -ocspSigningCert ./DOD_JITC_EMAIL_CA-29__0x01A5__DOD_JITC_ROOT_CA_2.cer
 Adding alternative OCSP responder for tenant :vsphere.local
 OCSP responder is added successfully!
 [
 site::   78564172-2508-4b3a-b903-23de29a2c342
     [
     OCSP url::   http://ocsp.nsn0.rcvs.nit.disa.mil/
     OCSP signing CA cert:   binary value]
     ]
     [
     OCSP url::   http://failover.ocsp.nsn0.rcvs.nit.disa.mil/
     OCSP signing CA cert:   binary value]
     ]
 ]

To display the current alternative OCSP responder settings, run this command.
```
sso-config.sh -t tenantName -get_alt_ocsp]
```

To remove the current alternative OCSP responder settings, run this command.

sso-config.sh -t tenantName -delete_alt_ocsp [-allSite] [-siteID pscSiteID_for_the_configuration]

(Optional) To list configuration information, run the following command.
```
sso-config.sh -get_authn_policy -t tenantName
```