Set up Microsoft AD CS for Issuing and Importing Certificates¶

This guide provides step-by-step instructions for configuring a direct integration between VSatellite and Microsoft Active Directory Certificate Services (AD CS). By connecting directly from VSatellite, you no longer need a separate VSatellite Worker to establish or manage this integration.

After completing these steps, you'll be able to import existing certificates and issue new certificates through your AD CS service.

Prerequisites¶

Before you begin, ensure the following baseline requirements are met:

• Linux server to run VSatellite: See Pre-requisites for installing VSatellites for a list of system and network requirements.

• VSatellite 2.0.31 or later: Required for the Authentication method setting. On earlier versions the setting is not available, and VSatellite behaves as it does in Automatic mode.

• AD CS service network access: The VSatellite machine must have direct network access to the Microsoft AD CS service on the following ports:

• TCP 135

• TCP 49152–65535

• AD CS permissions: The account used for authentication must have Read, Issue and Manage Certificates, and Request Certificates permissions on the Microsoft AD CS server.

• Completed AD CS configuration: Your AD CS service must meet specific configuration requirements.

• Microsoft AD CS server information:

• IP or hostname of your Microsoft AD CS server
• Username and password used to authenticate to Microsoft AD CS
• Microsoft AD CS Issuing Certificate Common Name

Note: Additional network access and connectivity requirements apply only if you want VSatellite to authenticate using Kerberos. These requirements are described in the sections below.

How Authentication Works (Kerberos and NTLM)¶

VSatellite authenticates to Microsoft AD CS using the Authentication method you select when configuring the connection. Kerberos provides mutual authentication and stronger encryption than NTLM and is the recommended method. Three options are available:

• Automatic (default): VSatellite attempts to authenticate using Kerberos when the environment supports it, and automatically falls back to NTLM otherwise.

Kerberos is used automatically when all required conditions are met, such as:

• Using a fully qualified domain name (FQDN) for the AD CS server
• Supplying domain-qualified credentials
• Having network connectivity to the Active Directory Domain Controller

If a Kerberos attempt fails quickly—an SPN that cannot be resolved, rejected credentials, or a Kerberos Key Distribution Center (KDC) that actively refuses the request—VSatellite automatically falls back to NTLM authentication. No additional configuration is required to enable or manage this fallback behavior.

Note: Fallback does not cover a Kerberos attempt that hangs. If the KDC is unreachable because port 88 traffic is silently dropped, or the realm does not resolve in DNS, the operation times out and fails rather than falling back.

• NTLM: VSatellite authenticates using NTLM only. Kerberos is not attempted, and no Kerberos-specific configuration is required.

• Kerberos: VSatellite authenticates using Kerberos only, with the Service Principal Name (SPN), Key Distribution Center (KDC), and Domain that you provide. Automatic SPN discovery is not performed, and VSatellite does not fall back to NTLM if the connection fails. Choose this method when you want to control the exact SPN and KDC used, when LDAP-based SPN discovery is not available in your environment, or when the server's SPN uses a prefix other than HOST/ or RPCSS/—which automatic discovery ignores.

If you are satisfied using NTLM authentication, select NTLM. You can also leave Automatic selected in an environment that does not meet the Kerberos conditions. In either case, no Kerberos-specific configuration or validation steps are required.

How Do I Get Started?¶

To configure the integration, enter the AD CS connection details directly in the VSatellite interface as described in Step 1 below.

If you want to use Kerberos authentication (recommended for stronger security), complete the optional Kerberos configuration section before proceeding to Step 1.

Optional: Configure Kerberos Authentication¶

Complete the following requirements and verification steps only if you want to use Kerberos authentication in Automatic mode, where VSatellite discovers the SPN through LDAP. If you select the explicit Kerberos authentication method instead, you supply the SPN, KDC, and Domain directly in Step 1. VSatellite does not use LDAP-based SPN discovery in that mode, so only KDC reachability on port 88 is required, along with a domain-qualified username and a VSatellite host clock within five minutes of the KDC's.

These requirements apply to Automatic mode. If you skip this section and the Kerberos conditions are not met, VSatellite uses NTLM authentication.

Kerberos Network and Connectivity Requirements¶

• Domain Controller network access: The VSatellite machine must be able to reach the Active Directory Domain Controller using the following ports:
• TCP 636: LDAPS for SPN discovery (attempted first)
• TCP 389: LDAP for SPN discovery (fallback)

• TCP/UDP 88: Kerberos KDC for ticket issuance

• Credential and address requirements:

• The AD CS server address must be specified as an FQDN, not an IP address.
• The username must include a domain qualifier, either:
  • UPN format: user@DOMAIN.COM
  • Down-level format: DOMAIN\user
• LDAP connectivity must be available from the VSatellite machine to the Domain Controller.

Verify LDAP Connectivity (Recommended)¶

Before configuring credentials in VSatellite, you can verify that LDAP connectivity from the VSatellite machine is working as expected. These checks help confirm that Kerberos authentication can succeed.

If you skip this step or the tests fail, VSatellite will use NTLM authentication instead.

1. Run a Port Reachability Check¶

From the VSatellite machine, verify that required ports are reachable (no credentials required):

• Test LDAPS: nc -zv <DOMAIN_CONTROLLER> 636 -w 5
• Test LDAP: nc -zv <DOMAIN_CONTROLLER> 389 -w 5

2. Run a Full LDAP Query Test (Optional)¶

Run an LDAP query that replicates the SPN discovery performed by VSatellite. You can use either LDAPS or LDAP.

LDAPS (port 636):

ldapsearch -H ldaps://${DOMAIN}:636 \
  -x \
  -D "${USERNAME}" \
  -w "${PASSWORD}" \
  -b "DC=${DOMAIN_PART1},DC=${DOMAIN_PART2}" \
  "(&(objectClass=computer)((cn=${SHORT_NAME})(dNSHostName=${FQDN})))" \
  servicePrincipalName

Replace the variables with values from your environment, for example:

• ${DOMAIN} = example.com
• ${USERNAME} = user@example.com
• ${SHORT_NAME} = AD CS server short hostname (uppercase)
• ${FQDN} = full AD CS server hostname

Step 1: Configure the AD CS Connection in VSatellite¶

Once prerequisites are met, configure the integration in the VSatellite interface.

1. Sign in to Certificate Manager - SaaS.

2. Click Integrations > Certificate Authorities.

3. Click New > Microsoft AD CS.

4. Enter a Name for the Certificate Authority.

Tip: This is the name that will be used throughout Certificate Manager - SaaS for this CA.

1. Enter the server address: In the AD CS administrative address field, enter the FQDN of your Microsoft AD CS server.

Note: In Automatic mode, using an IP address instead of an FQDN forces NTLM authentication because Kerberos SPN discovery requires a hostname.

1. Enter the CA common name: In the Common Name (CN) of the CA's certificate field, enter the Common Name of the Microsoft AD CS issuing (root) certificate.

2. Provide credentials: Enter your Username and Password.

3. The username must include a domain qualifier, in either UPN format (user@DOMAIN.COM) or down-level format (DOMAIN\user). In Automatic mode, a username without a qualifier causes VSatellite to use NTLM. With the Kerberos method, the connection fails.

4. Passwords must not exceed 128 characters.

5. Select the authentication method: In the Authentication method drop-down, select how VSatellite authenticates to AD CS (requires VSatellite 2.0.31 or later):

6. Automatic (default): VSatellite attempts Kerberos when conditions are met and falls back to NTLM otherwise. No additional fields are required.

7. NTLM: VSatellite uses NTLM only. No additional fields are required.
8. Kerberos: VSatellite uses Kerberos only. When you select this option, the following additional fields appear and are all required:
   • Service Principal Name (SPN): The SPN of the AD CS server (for example, HOST/adcs.example.com). Any SPN prefix is accepted in this mode.
   • Key Distribution Center (KDC): The address or hostname of the Kerberos KDC (for example, dc.example.com). A hostname must be resolvable from the VSatellite machine.
   • Domain: The Active Directory DNS domain name (for example, example.com). Case is not significant—VSatellite uppercases this value to form the Kerberos realm, so example.com and EXAMPLE.COM are equivalent.

Note: In Kerberos mode, VSatellite does not perform automatic SPN discovery and does not fall back to NTLM. Ensure that the SPN, KDC, and Domain values are correct, that the Username includes a domain qualifier, that the VSatellite machine can reach the KDC on port 88, and that its clock is within five minutes of the KDC's.

Each of these three values must be 255 characters or fewer. None of them may contain control characters or the characters [, ], {, }, or =. A value that fails validation returns an error naming the field and the problem—for example, kerberosConfig.kdc contains invalid characters. The SPN, KDC, and Domain are checked in that order, and only the first problem is reported.

Finding Your SPN, KDC, and Domain Values¶

If you selected the Kerberos authentication method, use the commands below to look up the required values.

Note: These are Windows commands, run in PowerShell on the AD CS server—unlike the nc and ldapsearch checks above, which run on the VSatellite Linux host.

Both commands query Active Directory, so any other domain-joined Windows machine also works, provided it has Remote Server Administration Tools (RSAT) installed; setspn takes the AD CS server name as an argument. Replace the placeholders with your own values.

Service Principal Name (SPN)¶

From PowerShell on the AD CS server, list the SPNs registered to the server's machine account:

setspn -L <ADCS_SERVER_NAME>

From the output, pick an entry that uses the server's FQDN—for example, HOST/adcs.example.com. HOST/ and RPCSS/ are the prefixes VSatellite tries in Automatic mode; with the Kerberos method you can enter any SPN registered to the server.

If LDAP is reachable from the VSatellite host, the LDAP query test earlier in this topic returns the same servicePrincipalName values without switching machines.

Key Distribution Center (KDC)¶

From PowerShell on the AD CS server, find the domain controller that acts as a KDC for your domain:

nltest /dsgetdc:<DOMAIN> /kdc

Use the returned domain controller hostname as the KDC value.

Note: nltest locates a domain controller from the machine where you run it, which may not be the one closest to the VSatellite host. Confirm the returned host is reachable from the VSatellite machine on port 88.

Domain¶

Your Active Directory DNS domain name—for example, example.com. From PowerShell on the AD CS server, $env:USERDNSDOMAIN returns it. Enter it in either case.

Step 2: Test Credentials¶

To verify the configuration, click Test credentials in the VSatellite interface. This test confirms connectivity and authentication with the AD CS server, using both certificate-request and certificate-administration access—so an account missing the Issue and Manage Certificates permission fails here.

The test uses the Authentication method you selected:

• In Automatic mode, a Kerberos failure that returns promptly falls back to NTLM and the test can still succeed. A Kerberos attempt that hangs—typically an unreachable KDC—causes the test to fail instead.
• In NTLM or Kerberos mode, VSatellite uses only the selected protocol. No fallback occurs, so the test fails if that protocol cannot authenticate.

Once the test succeeds, click Next.

Troubleshooting Authentication Errors¶

Step 3: Select AD CS issuance templates to map to Certificate Manager - SaaS¶

Now that the connection is made, we can set up certificate issuance through Certificate Manager - SaaS. This step is required only if you want to issue new TLS server authentication certificates through Certificate Manager - SaaS. If you just want to import existing certificates, see the import existing certificates steps below.

1. Click in the Issuance templates field. After clicking in the field, Certificate Manager - SaaS queries your AD CS and returns a list of issuance templates from your AD CS server.

2. Select the AD CS issuance templates that you want to map to Certificate Manager - SaaS.

3. Click Add.

   Certificate Manager - SaaS tests all the templates you selected. Templates with a Passed result are available to map to request policies in Certificate Manager - SaaS. Those with a Failed result are not.

   Why did some templates fail?

   After adding templates, Certificate Manager - SaaS issues test certificates using each of the AD CS issuance templates. Certificate Manager - SaaS supports issuance through templates that:

   • Have Server Authentication set in the Application Policies setting of the Extensions tab on the issuance template
   • Allow issuing certificates using RSA keys
   • Supply the Subject Name in the request (can't issue certificates with SN build from the AD)

   Issuance templates that are incapable of issuing such certificates fail the Certificate Manager - SaaS issuance test. This is expected. Some of the predefined (default) Issuance templates that will fail are:

   • DirectoryEmailReplication
   • DomainController
   • DomainControllerAuthentication
   • KerberosAuthentication

   Only the certificates that pass the test will be available when mapping AD CS templates to Certificate Manager - SaaS templates.

   However, issuance tests use a static 2048-bit CSR, and are expected to fail for AD CS templates that require larger key sizes. You will still be able to save the CA account settings, and issue certificates with ADCS templates with larger key sizes.

4. Click Next.

On the Statistics tab of your Microsoft AD CS certificate authority, you see a summary of your certificates. Click on any number to open a pre-filtered Certificate Inventory page to see those certificates.

What's Next?¶

Now that your AD CS templates are mapped to Certificate Manager - SaaS, you can create a request policy and associate your AD CS templates with Certificate Manager - SaaS request policies.

Select Microsoft from the New Request Policy screen. The AD CS templates that passed validation will show up in the Product Option drop-down.

Step 4: Import existing certificates from AD CS¶

This step is required only if you want to import existing certificates from AD CS.

1. Click in the Import templates box. After clicking in the box, Certificate Manager - SaaS queries your AD CS and returns a list of templates from your AD CS server.

2. Select the AD CS templates that you want to import certificates from. Only certificates issued by the templates you select will be imported.

3. Click Add.

4. If you want to schedule the import to occur on a regular basis, click the AD CS Import slider, and then set the import interval. This option is available only if one or more AD CS templates were added in the previous steps.

5. Under Import options, select whether you want to import revoked or expired certificates.

6. Click Done.

Certificate Manager - SaaS imports the certificates.

On the Statistics tab of your Microsoft AD CS certificate authority, you see a summary of your certificates. Click on any number to open a pre-filtered Certificate Inventory page to see those certificates.

Need help? See the Certificate Manager - SaaS Troubleshooting guide for solutions to common issues, including VSatellite and Microsoft AD CS configuration problems.