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 locations:

Windows	C:\Program Files\VMware\VCenter server\VMware Identity Services\sso-config.bat
Linux	/opt/vmware/bin/sso-config.sh

Configuration of supported authentication types and revocation settings is stored in VMware Directory Service and replicated across all Platform Services Controller 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 Platform Services Controller command line. The following command enables user name and password authentication.

OS	Command
Windows	sso-config.bat -set_authn_policy -pwdAuthn true -t <tenant_name> If you use the default tenant, use vsphere.local as the tenant name.
Linux	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 your environment uses Platform Services Controller version 6.5 or later, and that you use vCenter Server version 6.0 or later. Platform Services Controller version 6.0 Update 2 supports smart card authentication, but the setup procedure is different.
• 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 Enhanced Key Usage field or the browser does not show the certificate.

• Verify that the Platform Services Controller certificate is trusted by the end user's workstation. Otherwise, the browser does not attempt authentication.
• 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.
  Note: The administrator of the vCenter Single Sign-On domain, [email protected] by default, cannot perform smart card authentication.
• Set up the reverse proxy and restart the physical or virtual machine.

Procedure

1. Obtain the certificates and copy them to a folder that the sso-config utility can see.

   Option	Description
   Windows	Log in to the Platform Services Controller Windows installation and use WinSCP or a similar utility to copy the files.
   Appliance	Log in to the appliance console, either directly or by using SSH. Enable the appliance shell, as follows. shell chsh -s "/bin/bash" root Use WinSCP or a similar utility to copy the certificates to the /usr/lib/vmware-sso/vmware-sts/conf on the Platform Services Controller. Optionally disable the appliance shell, as follows. chsh -s "/bin/appliancesh" root

2. To enable smart cart authentication for VMware Directory Service (vmdir), run the following command.

   sso-config.[bat|sh] -set_authn_policy -certAuthn true -cacerts first_trusted_cert.cer,second_trusted_cert.cer  -t tenant
   

   For example:

   sso-config.[bat|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.
3. To disable all other authentication methods, run the following commands.

   sso-config.[bat|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

4. (Optional) To set a certificate policies allowlist, run the following command.

   sso-config.[bat|sh] -set_authn_policy -certPolicies policies

   To specify multiple policies, separate them with a comma, for example:

   sso-config.bat -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.
5. (Optional) Turn on and configure revocation checking using OCSP.
   1. Turn on revocation checking using OCSP.

      sso-config.[bat|sh]  -set_authn_policy -t tenantName  -useOcsp true

   2. 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.[bat|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.[bat|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]
           ]
       ]

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

      sso-config.[bat|sh] -t tenantName -get_alt_ocsp]
      

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

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

6. (Optional) To list configuration information, run the following command.

   sso-config.[bat|sh] -get_authn_policy -t tenantName