Configuring Keyfactor ACME for Load Balancing

To ensure Keyfactor ACME functions correctly when using a load balancer, apply the following configuration on each Keyfactor ACME server.

Considerations for load balancing:

Use the Keyfactor ACME Configure command (see The Configure Command) to configure load balancing by pre-populating the configuration values as described in Table 13: Configuration Command Parameters for Load Balancing.

Copy 
.\KeyfactorACMEConfig.exe configure `
  --acmeauthority "https://appsrvr186.keyexample.com:4443/realms/Keyfactor" `
  --acmejwksurl "https://appsrvr186.keyexample.com:4443/realms/Keyfactor/protocol/openid-connect/certs" `
  --acmenameclaimtype "preferred_username" `
  --acmeroleclaimtype "groups" `
  --acmeuniqueclaimtype "sub" `
  --apppool "ACMEPool" `
  --commandauthority "https://appsrvr187.keyexample.com:5443/realms/Keyfactor" `
  --commandclientid "ACME1" `
  --commandclientsecret "88pTwKlPDpAwAo6Y5mEFHmwnlre0RG5f" `
  --commandtokenurl "https://appsrvr187.keyexample.com:5443/realms/Keyfactor/protocol/openid-connect/token" `
  --database "ACME93" `
  --hostname "acme.keyexample.com" `
  --password "MySuperSecretSQLUserPassword" `
  --server "sqlsrvr05.keyexample.com" `
  --url "https://command.keyexample.com/KeyfactorAPI" `
  --username "john_smith" `
  --website "default web site"

Table 13: Configuration Command Parameters for Load Balancing

Short Name Long Name Description Notes
  --acme authority

The issuer/authority endpoint URL for the identity provider used for entities authenticating to the Keyfactor ACME server.

The information referenced by this parameter is required and will be prompted for if not supplied.

  
  --acme jwks url

The JWKS (JSON Web Key Set) URL for the identity provider used for entities authenticating to the Keyfactor ACME server.

The information referenced by this parameter is required and will be prompted for if not supplied.

  
  --acme name claim type

A type of user claim for the identity provider containing a friendly name for the user. This is used for entities authenticating to the Keyfactor ACME server.

The information referenced by this parameter is required and will be prompted for if not supplied.

For Keyfactor Identity Provider, this should be:

preferred_username

For Okta, this might be preferred_names (e.g. john.smith@keyexample.com) or just name (e.g. John Smith). For Auth0 this might be name (e.g. johnsmith@keyexample.com).
  --acme role claim type

The value used to reference the type of group claim for the identity provider. This is used for entities authenticating to the Keyfactor ACME server.

The information referenced by this parameter is required and will be prompted for if not supplied.

For Keyfactor Identity Provider, this should be:

groups
  --acme unique claim type

A type of user claim for the identity provider containing a unique name for the user. This is used for entities authenticating to the Keyfactor ACME server.

The information referenced by this parameter is required and will be prompted for if not supplied.

For Keyfactor Identity Provider, this should be:

sub

In Keyfactor Identity Provider, this is a GUID uniquely identifying the user. The sub (subject) user claim type is also commonly used by other OAuth providers.
-a --apppool

The IIS application pool under which the Keyfactor ACME server should run. The application pool must exist before the command is run. The parameter is case sensitive.

The application pool user needs, at a minimum:

  • SQL DBO permissions on the ACME database to run the application.

  • The SQL server roles dbcreator and securityadmin to create a database.

The information referenced by this parameter is required and will be prompted for if not supplied.
Important:  If the Keyfactor API virtual directory on the Keyfactor Command server is configured for Windows Authentication, the user under which this application pool runs must have CSR Enroll permissions for Certificate Enrollment and Read permissions for Certificates in Keyfactor Command Security Roles and Claims (see Preparing).
Tip:  This may be the Application Pool defined in the Keyfactor Command Configuration Wizard on the API tab (see the Install the Main Keyfactor Command Components on the Keyfactor Command Server(s): API Tab in the Keyfactor Command Server Installation Guide), if Keyfactor ACME is installed on the same server as Keyfactor Command. This can be found in IIS Manager > Application Pools.
  --command audience

An audience value to be included in token requests delivered to the identity provider when making a token request where Keyfactor ACME is acting as the OAuth client authenticating to Keyfactor Command.

The OAuth mechanism in use in your Keyfactor ACME environment may or may not require this.
  --command authority

The issuer/authority endpoint URL for the identity provider used to authenticate from Keyfactor ACME to Keyfactor Command.

The information referenced by this parameter is required and will be prompted for if not supplied.
Important:  The identity provider used to authenticate to Keyfactor Command must be defined as an identity provider in Keyfactor Command.
  --command client id

The ID of the client application created in the identity provider to authenticate from Keyfactor ACME to Keyfactor Command.

The information referenced by this parameter is required and will be prompted for if not supplied.

  
  --command client secret

The secret of the client application created in the identity provider to authenticate from Keyfactor ACME to Keyfactor Command.

The information referenced by this parameter is required and will be prompted for if not supplied.

  
  --command scope

One or more scopes that should be included in token requests delivered to the identity provider when making a token request where Keyfactor ACME is acting as the OAuth client authenticating to Keyfactor Command. Multiple scopes should be separated by spaces.

The OAuth mechanism in use in your Keyfactor ACME environment may or may not require this.
  --command token url

The token endpoint URL for the identity provider used to authenticate from Keyfactor ACME to Keyfactor Command.

The information referenced by this parameter is required and will be prompted for if not supplied.

  
-d --database

The name of the Keyfactor ACME database.

The default is Keyfactor.ACME.

Enter unique database names for each Keyfactor ACME server.

Tip:  If a database already exists, the configuration tool will use the existing one. If not, one will be created during configuration. If there is an existing database with the same name that you do not want to use, rename it, or delete it in SQL prior to running the configure command.

If you are using Azure SQL no database will be created, so the database must exist prior to running this command, or the command will fail.
-e --encryption The thumbprint for the local machine certificate used for application-level encryption.

By default, sensitive data—such as EAB HMAC keys—is securely stored in the Keyfactor ACME database using SQL encryption. However, an additional layer of security can be added with application-level encryption.

Application-Level Encryption Certificate Requirements:

  • The certificate must be installed in the Personal Certificate store of the Local Computer on each Keyfactor ACME server.

  • The certificate must have a key usage of one of:

    • Key Encipherment

    • Data Encipherment (Microsoft certificate templates allow this only as a suboption of key encipherment.)

  • You may use:

    • The certificate issued to the Keyfactor ACME website and bound to it in IIS, provided that it supports the appropriate key usage

    • A separate certificate for this purpose.

Optional Hardware Security Module (HSM):

  • An HSM may be used to store the private key for the certificate.

  • The Windows CSP driver for the HSM must be installed on the Keyfactor ACME server.

  • Be aware that transactions accessing the encrypted data (e.g. certificate enrollment) will require HSM access, which may slow down processes if the HSM is slow.

Important:  If multiple Keyfactor ACME servers are used in a load balanced configuration, each server must be configured with the same certificate for application-level encryption.
  --force database upgrade Forces the upgrade of an older version of the Keyfactor ACME database to the same version as the installed product.

Example:

KeyfactorACMEConfig.exe configure --force database upgrade
  --help Display the command help screens.  
-h --hostname

The fully qualified domain name (FQDN) of the machine running the Keyfactor ACME application. This is used to construct a URL for returning responses to the client.

The information referenced by this parameter is required and will be prompted for if not supplied.

For load balancing configuration, replace the backend hostnames with a single load balanced hostname to be provided to the ACME client in responses.

Tip:  This may be the Host Name defined in the Keyfactor Command Configuration Wizard on the API tab (see the Install the Main Keyfactor Command Components on the Keyfactor Command Server(s): API Tab in the Keyfactor Command Server Installation Guide), if Keyfactor ACME is installed on the same server as Keyfactor Command.
-o --password

The password for the SQL account, if using SQL authentication.

The information referenced by this parameter is required and will be prompted for if not supplied if SQL authentication is used.

 If you supply the username parameter with the configure command, you will be prompted for the password, or you can supply both when issuing the command.

-s

 --server

The name for the SQL server to use for the Keyfactor ACME database.

The information referenced by this parameter is required and will be prompted for if not supplied.

 The fully qualified domain name (FQDN )of the SQL server. This will be the same for all Keyfactor ACME servers.
-u --url

The full URL to the Keyfactor API.

The information referenced by this parameter is required and will be prompted for if not supplied.

Specify your specific URL.
  --use integrated authentication Forces the use of integrated authentication when connecting to SQL. This cannot be used with the --username parameter. If neither --username nor --useintegratedauthentication is specified, the user will be prompted for SQL authentication or integrated authentication.
-n --username

The username of the account used to access SQL, if using SQL authentication.

The information referenced by this parameter is required and will be prompted for if not supplied if SQL authentication is used.

 If you do not supply the username or integrated authentication options, you will be prompted.
  --version List the version of the command.  
-p --virtual directory

The URL virtual directory for the Keyfactor ACME. This is the URL to which certificate requests will be directed on the Keyfactor ACME server.

The default is ACME.

Specify the value.

If this directory already exists, it will be deleted and recreated with the correct permissions.
-w --website

The web site under which the Keyfactor ACME virtual directory will be installed.

The default is default web site.

The syntax expected is the value surrounded by quotes if the value contains spaces (e.g. default web site).

Tip:  This may be the web site defined in the Keyfactor Command Configuration Wizard on the API tab (see the Install the Main Keyfactor Command Components on the Keyfactor Command Server(s): API Tab in the Keyfactor Command Server Installation Guide), if Keyfactor ACME is installed on the same server as Keyfactor Command.