Acquire a Certificate for Client Certificate Authentication (Optional)

The Keyfactor Universal OrchestratorClosed The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with servers and devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can provide certificate management capabilities on a variety of platforms and devices (e.g. Amazon Web Services (AWS) resources, Citrix\NetScaler devices, F5 devices, IIS stores, JKS keystores, PEM stores, and PKCS#12 stores) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux servers or Linux containers. supports client certificate authentication to allow you to authenticate via client certificates from individual orchestratorClosed Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. machines either directly or via a centralized proxy, such as a network load balancer, which would in turn authenticate to the Keyfactor Command server using either a username and password or client ID and secret that was stored securely on the proxy or another client certificate. The proxy approach allows orchestrator credentials to be assigned and managed outside the Active Directory forestClosed 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. The web proxy's job is to confirm the validity of the certificate and to provide Active Directory or an identity provider other than Active Directory credentials known to Keyfactor Command (if configured in this manner). Typically the proxy would be configured to accept all certificates issued from a given PKIClosed A public key infrastructure (PKI) is a set of roles, policies, and procedures needed to create, manage, distribute, use, store and revoke digital certificates and manage public-key encryption. implementation—even a PKI that is unknown to the Keyfactor Command Active Directory forest—thus delegating orchestrator access control to that PKI. For more information, see:

Important:  The Universal Orchestrator supports automated client certificate renewal using an extension point interface on the orchestrator that can be implemented by the end-user. The custom extension will generate a CSRClosed 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. with private keyClosed 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. and submit the CSR to Keyfactor Command for enrollmentClosed 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).. Keyfactor Command will return the certificate to the orchestrator, which will pair it with its private key and use that certificate for authentication. See Register a Client Certificate Renewal Extension for more information.
Note:  Client certificate authentication is not supported when using the Universal Orchestrator installed in a Linux container (see Install the Universal Orchestrator in a Linux Container).

There are several situations in which using certificate authentication for the Universal Orchestrator may be helpful, including:

  • Scale—To allow orchestrator numbers to scale (e.g. the IoT case) where it isn't practical to have a unique Active Directory account for each orchestrator.
  • Untrusted Environments—To support environments (e.g. a “hostile” network) where policy doesn't allow the password for an Active Directory account to be stored on the orchestrator.

On Windows servers, the certificate may be referenced either as a PKCS12 file stored in the file system or may be placed either in the local machine's personal store (My), or, if you opt to run the Universal Orchestrator service as a domain service account rather than the default of Network Service, in the personal store of the Universal Orchestrator service account user. If you opt to place the certificate in the local machine store, you need to grant the service account under which the Universal Orchestrator service will run (including Network Service if you will use this option) read permissions to the private key of the certificate (see Grant the Service Account Certificate Private Key Permissions). If you opt to place the certificate in the personal store of the Universal Orchestrator service account user, it also needs to be placed in the personal store of the user running the installation for the duration of the installation to allow it to be read during initial configuration. It may be removed from the installing user's store after installation is complete.

On Linux servers, the certificate is referenced as a PKCS12 file stored in the file system.

Important:  Keyfactor highly recommends that you use strong passwords for any accounts or certificates related to Keyfactor Command and associated products, especially when these have elevated or administrative access. A strong password has at least 12 characters (more is better) and multiple character classes (lowercase letters, uppercase letters, numeral, and symbols). Ideally, each password would be randomly generated. Avoid password re-use.
Create a Template for Client Certificate Authentication

The certificate that the Universal Orchestrator uses for authentication needs:

Enroll for a Client Authentication Certificate

To acquire a certificate for use by the Universal Orchestrator using a Microsoft CAClosed 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 templateClosed A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. using the appropriate configurations as described above and make it available for enrollment on the CA from which you will request the certificate. If you plan to enroll for the certificate through Keyfactor Command, you will also need to enable the template for enrollment in Keyfactor Command. The account requesting the certificate will need enroll permissions on the CA, on the template, and, if applicable, in Keyfactor Command.

You can enroll for a client authentication certificate for the orchestrator in a variety of ways. For an orchestrator on Windows, the certificate can either be installed in the local computer personal store on the Windows server on which the orchestrator is installed or provided as a PKCS#12Closed 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. file. For an orchestrator on Linux, the certificate must be provided as a PKCS#12 file. Some possible ways to do this are:

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.

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. For a Windows server, 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.
Copy 
#Set variables with the username and password for the orchestrator service account
$apiUsername = 'KEYEXAMPLE\APIUser'
$apiPassword = 'MySecureAPIAccountPassword'
$pair = "$($apiUsername):$($apiPassword)"

# 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 = 'CN=orchname.keyexample.com' # 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)

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.
Copy 
#Set variables with the username and password for the orchestrator service account
$apiUsername = 'KEYEXAMPLE\APIUser'
$apiPassword = 'MySecureAPIAccountPassword'
$pair = "$($apiUsername):$($apiPassword)"

# 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 = 'CN=orchname.keyexample.com' # 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
Grant the Service Account Certificate Private Key Permissions

Whichever method you decide to use to acquire the client authentication certificate for a Windows orchestratorClosed The Windows Orchestrator, one of Keyfactor's suite of orchestrators, is used to manage synchronization of certificate authorities in remote forests, run SSL discovery and management tasks, and interact with Windows servers as well as F5 devices, NetScaler devices, Amazon Web Services (AWS) resources, and FTP capable devices, for certificate management. In addition, the AnyAgent capability of the Windows Orchestrator allows it to be extended to create custom certificate store types and management capabilities regardless of source platform or location., if you’ve installed the certificate in the local machine store on the server, 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.

Tip:  If the service account is a member of the local administrators group, this step may not be necessary, since the local administrators group is typically granted these permissions automatically.

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.
Tip:  If you receive an error similar to the following when attempting to install your orchestrator:
The request was aborted: Could not create SSL/TLS secure channel.