Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication with Certificates Stored in Active Directory

On your Keyfactor Command server, install the following additional module:

• Client Certificate Mapping Authentication (rather than IIS Client Certificate Mapping Authentication)

If you have more than one Keyfactor Command server with separated roles, this only needs to be installed on the server accepting traffic to the /KeyfactorAgents web application.

The PowerShell command to install the appropriate module is :

Make the following changes in the IIS Management console on the Keyfactor Command server:

1. In the IIS Management console, highlight the server name on the left and open Authentication. Change the status of Active Directory Client Certificate Authentication to Enabled.

   

   Figure 568: Configure Client Certificate Authentication at the Server Level in IIS

2. In the IIS Management console, drill down into sites and into the Default Web Site (or other web site if your Keyfactor Command instance has been installed in an alternate web site). Under the Default Web Site, locate the KeyfactorAgents application and open Authentication for this. Disable all the authentication methods shown here. The Active Directory Client Certificate Authentication method does not appear here.

   

   Figure 569: Disable Authentication Methods at the Application Level in IIS

   Tip:  At the Default Web Site level, the only authentication method that should be enabled is Anonymous. This should not be changed.

3. In the IIS Management console, open SSL Settings for the KeyfactorAgents application. Check the Require SSL box and select either Require or Accept for Client certificates.

   Important:  Only selected Require if your are only using orchestrators that support client certificate authentication and plan to configure all of them for certificate authentication.

   

   Figure 570: Configure SSL Settings in IIS for Client Certificate Authentication

   Tip:  At the Default Web Site level, it is good security practice to check the Require SSL box, but you do not need to accept client certificates at this level and should not require them at this level.

This method of certificate authentication functions by sending a client certificate from the orchestrator to IIS on the Keyfactor Command server, where IIS does a lookup in Active Directory to determine what Active Directory user is associated with that certificate and then turns around and uses that identity to connect to Keyfactor Command. In order for the certificate to the associated with the Active Directory identity, it must be enrolled using a template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. that has the Publish certificate in Active Directory option enabled.

To create the certificate template that will be used for orchestrator client authentication certificates, start by duplicating a template with a Computer subject type. In addition to any standards for your environment, the templates needs:

• The Publish certificate in Active Directory box checked.

  

  Figure 571: Microsoft Certificate Template General for Client Authentication Certificate

• A key usage that includes Digital Signature.

  

  Figure 572: Microsoft Certificate Template Request Handling for Client Authentication Certificate

• An extended key usage (EKU) of Client Authentication.

  

  Figure 573: Microsoft Certificate Template Application Policies for Client Authentication Certificate

• Enroll permissions for either the service account that the orchestrator will run as or the machine account for the orchestrator machine (see ).

  

  Figure 574: Microsoft Certificate Template Security for Client Authentication Certificate

To acquire a certificate for use by the Universal Orchestrator using a Microsoft CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA., first create a template using the appropriate configurations as described above and make it available for enrollment Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). on a CA to which the Universal Orchestrator machine has access. If you plan to enroll for the certificate through Keyfactor Command, you will also need to enable the template for enrollment in Keyfactor Command.

You can enroll for a client authentication certificate for the orchestrator in a variety of ways. The certificate needs to be installed in the local computer personal store on the Windows server on which the orchestrator is installed. Some possible ways to do this are:

• Use Keyfactor Command to enroll for the certificate using the PFX A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. enrollment method and then import the PFX file on the orchestrator server. If you select this method, you will need to login to the Keyfactor Command Management Portal as the orchestrator service account being used on the Keyfactor Command side of the fence (see Create Service Accounts for the Universal Orchestrator) in order to enroll for the certificate in the correct context or use the Keyfactor API A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. to submit a request in a specific user context (see PFX Enrollment in Keyfactor Command Using a PowerShell Script). The orchestrator service account will need enroll permissions on the CA, on the template, and in Keyfactor Command.

• Use IIS or the certificates MMC on the orchestrator server to generate a CSR A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA., use the Keyfactor Command CSR enrollment method to enroll for a certificate using the CSR, and then import the CSR on the orchestrator server, marrying it with the private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure. generated on the server. If you select this method, you will need to login to the Keyfactor Command Management Portal as the orchestrator service account being used on the Keyfactor Command side of the fence (see Create Service Accounts for the Universal Orchestrator) in order to enroll for the certificate in the correct context. The orchestrator service account will need enroll permissions on the CA, on the template, and in Keyfactor Command.

• If there is an existing Universal Orchestrator on the server already running and communicating with Keyfactor Command, use the Keyfactor Command PFX enrollment method and push the certificate out to the certificate store on the orchestrator server using Keyfactor Command. If you select this method, you will need to login to the Keyfactor Command Management Portal as the orchestrator service account being used on the Keyfactor Command side of the fence (see Create Service Accounts for the Universal Orchestrator) in order to enroll for the certificate in the correct context or use the Keyfactor API to submit a request in a specific user context (see PFX Enrollment in Keyfactor Command Using a PowerShell Script). The orchestrator service account will need enroll permissions on the CA, on the template, and in Keyfactor Command.

• Use the Microsoft MMC on the orchestrator server to enroll for a certificate. If you select this method, the orchestrator will connect to Keyfactor Command using the orchestrator machine account rather than an Active Directory user account. The orchestrator machine account will need enroll permissions on the CA and on the template. This method will only work for servers joined to the same Active Directory forest An Active Directory forest (AD forest) is the top most logical container in an Active Directory configuration that contains domains, and objects such as users and computers. in which Keyfactor Command is installed.

PFX Enrollment in Keyfactor Command Using a PowerShell Script

To enroll for a certificate using the PFX enrollment method in Keyfactor Command, you can either do this in the Keyfactor Command Management Portal while logged in as the orchestrator service account or with a PowerShell script. In either case, the orchestrator service account will need PFX enroll permissions in Keyfactor Command. Below is a sample PowerShell script. Once the PFX file has been generated, import it into the local machine store on the orchestrator server.

Tip:  The service account you provide in the PowerShell script is the service account used to provide a connection from the orchestrator to Keyfactor Command. This is not necessarily the same service account that runs the orchestrator service on the orchestrator server. For an orchestrator in a separate forest from Keyfactor Command, this would be a service account in the Keyfactor Command forest, not the orchestrator forest. See Create Service Accounts for the Universal Orchestrator.

#Set variables with the username and password for the orchestrator service account
$orchUsername = 'KEYEXAMPLE\svc_kyforch'
$orchPassword = 'MySecureServiceAccountPassword'
$pair = "$($orchUsername):$($orchPassword)"

# Base-64 encode the service account credentials
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))

$UTCTime = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
$keyfactorServer = 'keyfactor.keyexample.com' # FQDN of the Keyfactor Command server
$caName = 'corpca01.keyexample.com\CorpIssuing01' # CA to use for the enrollment
$templateName = 'KeyfactorOrchestratorAuth' # Template to use for the enrollment
$certSubject = 'Orchestrator Cert Auth' # Using a template that is configured to build from AD will cause this subject to be replaced
$pfxPassword = 'MySecurePFXPassword' # Password for the resulting PFX file
$outputFile = 'C:\stuff\OrchCertAuth.pfx' # Path and file name for the PFX file to be generated

$basicAuthValue = "Basic $encodedCreds"

$headers = @{
"Authorization"=$basicAuthValue
"Accept"="application/json"
"x-keyfactor-requested-with"="APIClient"
"x-certificateformat"="PFX"
}

$body = @{
"Password" = "$pfxPassword"
"Subject" = "$certSubject"
"IncludeChain" = "true"
"CertificateAuthority" = "$caName"
"Timestamp" = "$UTCTime"
"Template" = "$templateName"
}

# Output response as a PFX file
$response = Invoke-WebRequest -Uri "https://$keyfactorServer/KeyfactorAPI/Enrollment/PFX" -Method:Post -Headers $headers -ContentType "application/json" -Body ($body|ConvertTo-Json) -ErrorAction:Stop -TimeoutSec 60
$ResponseContent = $response.Content | ConvertFrom-Json
$bytes = [Convert]::FromBase64String($ResponseContent.CertificateInformation.Pkcs12Blob)
[IO.File]::WriteAllBytes($outputFile, $bytes)

PFX Enrollment and Deployment in Keyfactor Command Using a PowerShell Script

To enroll for a certificate using the PFX enrollment method in Keyfactor Command and deploy it to the orchestrator server using Keyfactor Command, you can either do this in the Keyfactor Command Management Portal while logged in as the orchestrator service account or with a PowerShell script. In either case, the orchestrator service account will need PFX enroll permissions and certificate store management permissions in Keyfactor Command. Below is a sample PowerShell script. This solution is only an option if your orchestrator is already up and running and successfully authenticating to Keyfactor Command using standard authentication (or previously configured certificate authentication).

Tip:  The service account you provide in the PowerShell script is the service account used to provide a connection from the orchestrator to Keyfactor Command. This is not necessarily the same service account that runs the orchestrator service on the orchestrator server. For an orchestrator in a separate forest from Keyfactor Command, this would be a service account in the Keyfactor Command forest, not the orchestrator forest. See Create Service Accounts for the Universal Orchestrator.

#Set variables with the username and password for the orchestrator service account
$orchUsername = 'KEYEXAMPLE\svc_kyforch'
$orchPassword = 'MySecureServiceAccountPassword'
$pair = "$($orchUsername):$($orchPassword)"

# Base-64 encode the service account credentials
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))

$UTCTime = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
$keyfactorServer = 'keyfactor.keyexample.com' # FQDN of the Keyfactor Command server
$storeName = 'websrvr38.keyexample.com' # FQDN of the orchestrator server as defined as a certificate store in Keyfactor Command
$caName = 'corpca01.keyexample.com\CorpIssuing01' # CA to use for the enrollment
$templateName = 'KeyfactorOrchestratorAuth' # Template to use for the enrollment
$certSubject = 'Orchestrator Cert Auth' # Using a template that is configured to build from AD will cause this subject to be replaced

$basicAuthValue = "Basic $encodedCreds"

$enrollHeaders = @{
   "Authorization"=$basicAuthValue
   "Accept"="application/json"
   "x-keyfactor-requested-with"="APIClient
   "x-certificateformat"="Store"
}

$deployHeaders = @{
   "Authorization"=$basicAuthValue
   "Accept"="application/json"
   "x-keyfactor-requested-with"="APIClient"
}

$enrollBody = @{
   "Subject" = "$certSubject"
   "IncludeChain" = "true"
   "CertificateAuthority" = "$caName"
   "Timestamp" = "$UTCTime"
   "Template" = "$templateName"
}

# Enroll for a certificate using the PFX enrollment method and retrieve the certificate ID from the response (as part of the content)
$enrollResponse = Invoke-WebRequest -Uri "https://$keyfactorServer/KeyfactorAPI/Enrollment/PFX" -Method:Post -Headers $enrollHeaders -ContentType "application/json" -Body ($enrollBody|ConvertTo-Json) -ErrorAction:Stop -TimeoutSec 60
$enrollContent = $enrollResponse.Content | ConvertFrom-Json

# Get the store GUID for the certificate store specified by the client machine name in the query string with the storeName variable
$storeInfo = Invoke-WebRequest -Uri "https://$keyfactorServer/KeyfactorAPI/CertificateStores?certificateStoreQuery.queryString=ClientMachine%20-eq%20%22$storeName%22" -Method:Get -Headers $deployHeaders -ContentType "application/json" -ErrorAction:Stop -TimeoutSec 60
$storeContent = $storeInfo.Content | ConvertFrom-Json
$storeGUID = $storeContent.Id

$deployBody = @{
   "StoreIds" = @( "$storeGUID" )
   "StoreTypes" = @(
      @{
         "StoreTypeId" = 6 # Store type 6 is IIS personal
         "Overwrite" = "false"
      }
   )
   "CertificateId" = $enrollContent.CertificateInformation.KeyfactorId
}

# Deploy certificate to certificate store
Invoke-WebRequest -Uri "https://$keyfactorServer/KeyfactorAPI/Enrollment/PFX/Deploy" -Method:Post -Headers $deployHeaders -ContentType "application/json" -Body ($deployBody|ConvertTo-Json) -ErrorAction:Stop -TimeoutSec 60

MMC Enrollment

To enroll for a certificate using the MMC:

1. On the Universal Orchestrator machine, do one of following:
   • Using the GUI:
     1. Open an empty instance of the Microsoft Management Console (MMC).
     2. Choose File->Add/Remove Snap-in….
     3. In the Available snap-ins column, highlight Certificates and click Add.
     4. In the Certificates snap-in popup, choose the radio button for Computer account, click Next, accept the default of Local computer, and click Finish.
     5. Click OK to close the Add or Remove Snap-ins dialog.
   • Using the command line:
     1. Open a command prompt using the "Run as administrator" option.
     2. Within the command prompt type the following to open the certificates MMC:
        certlm.msc

2. Drill down to the Personal folder under Certificates for the Local Computer, right-click, and choose All Tasks->Request New Certificate….
3. Follow the certificate enrollment wizard, selecting the template you created for orchestrator certificate authentication and providing any required information.

Whichever method you decide to use to acquire the client authentication certificate for the orchestrator, you will need to grant the Universal Orchestrator service account—the account that the orchestrator service is running as on the server—permissions to read the private key of that certificate.

To grant private key permissions on the certificate using the MMC:

1. On the Universal Orchestrator machine, do one of following:
   • Using the GUI:
     1. Open an empty instance of the Microsoft Management Console (MMC).
     2. Choose File->Add/Remove Snap-in….
     3. In the Available snap-ins column, highlight Certificates and click Add.
     4. In the Certificates snap-in popup, choose the radio button for Computer account, click Next, accept the default of Local computer, and click Finish.
     5. Click OK to close the Add or Remove Snap-ins dialog.
   • Using the command line:
     1. Open a command prompt using the "Run as administrator" option.
     2. Within the command prompt type the following to open the certificates MMC:
        certlm.msc

2. Drill down to the Personal folder under Certificates for the Local Computer to locate the certificate.
3. Highlight the certificate and choose All Tasks->Manage Private Keys….
4. In the Permissions for private keys dialog, click Add, add the service account under which the Universal Orchestrator is running (created as per Create Service Accounts for the Universal Orchestrator), and grant that service account Read but not Full control permissions. Click OK to save.