The Configure Command

The configure command of the Keyfactor ACME configuration tool (KeyfactorACMEConfig.exe) is used to set up the Keyfactor ACME Server during initial provisioning and to apply configuration changes afterward.

Tip:  Run the Keyfactor ACME commands at the command line or in a regular PowerShell window, NOT using the PowerShell ISE (as it does not have support for the “Console” class).

After installing the Keyfactor ACME software, configure it as follows:

  1. Open a command prompt using the Run as administrator option.

  2. Change to the Configuration directory under the directory in which you installed Keyfactor ACME. By default, this is:

    C:\Program Files\Keyfactor\ACME\Configuration

  3. Execute a command similar to the following examples, using appropriate values for your environment (see Table 5: Configure Command Parameters).

    Important:  If you receive an error from the configuration tool, you can fix the issue and re-run the command. It will continue to use any configuration that was successful from the prior run. Alternatively, you can delete the Keyfactor ACME database before re-running the tool to start from scratch.

    Examples:

    1. Pre-populate the configuration values using SQL authentication:

      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 "ACME" `
        --commandclientsecret "88pTwKlPDpAwAo6Y5mEFHmwnlre0RG5f" `
        --commandtokenurl "https://appsrvr187.keyexample.com:5443/realms/Keyfactor/protocol/openid-connect/token" `
        --database "ACME93" `
        --hostname "websrvr93.keyexample.com" `
        --password "MySuperSecretSQLUserPassword" `
        --server "sqlsrvr05.keyexample.com" `
        --url "https://command.keyexample.com/KeyfactorAPI" `
        --username "john_smith" `
        --website "default web site"

    2. Prompts from command line, with or without database name specified:

      Copy 
      KeyfactorACMEConfig.exe configure
      Copy 
      KeyfactorACMEConfig.exe configure --database ACME201

      In this case, you have the option to pass in a specific value for individual parameters and still be prompted for the other parameters or allow the tool to prompt for all parameters.

Table 5: Configure Command Parameters

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.

If you run it as per option A (pre-populate the configuration values), the database will be created as named in the --database parameter (e.g. ACME).

If you run the tool as per option B (with prompts from the configure tool), the database will be created as Keyfactor.ACME. There is no prompt for a database name, in this case. You could however pass in the --database parameter in the command line to name the database other than the default.

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.

See Configuring Keyfactor ACME for Load Balancing for configuring load balancing.

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.
-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.

If you run the tool as per option B (with prompts from configure tool), the default value is https://localhost/KeyfactorAPI. However, you can specify your specific URL by entering a value when prompted.
  --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.

If you run the tool as per option A (pre-populate the configuration values), you may specify the value.

If you run the tool as per option B (with prompts from configure tool), the value will be set as ACME unless you pass in the --virtualdirectory parameter.

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.

If you run the tool as per option A (pre-populate the configuration values), the syntax expected is the value surrounded by quotes if the value contains spaces (e.g. default web site).

If you run the tool as per option B (with prompts from configure tool), the value will be set as default web site unless you pass in the --website parameter.

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.
Expected Results
  1. Pre-populate the configuration values with SQL authentication: 
    .\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 "ACME" `
>>   --commandclientsecret "88pTwKlPDpAwAo6Y5mEFHmwnlre0RG5f" `
>>   --commandtokenurl "https://appsrvr187.keyexample.com:5443/realms/ Keyfactor/protocol/openid-connect/token" `
>>   --database "ACME93" `
>>   --hostname "websrvr93.keyexample.com" `
>>   --password "MySuperSecretSQLUserPassword" `
>>   --server "sqlsrvr05.keyexample.com" `
>>   --url "https://command.keyexample.com/KeyfactorAPI" `
>>   --username "john_smith" `
>>   --website "default web site"
*******************************************
*         Database Configuration.         *
*******************************************
Database 'ACME93' does not exist. Creating.
Database 'ACME93' created successfully.
Upgrading ACME database
SUCCESS - Database configuration is complete.
****************************************************************************************
*         Configuration setup for authentication with ACME Key Management API.         *
****************************************************************************************
Saving ACME OAuth connection information to database
SUCCESS - ACME OAuth Configuration complete.
***************************************************************************************
*         Configuration setup for authenticating with Command Enrollment API.         *
***************************************************************************************
Testing connection to https://command.keyexample.com/KeyfactorAPI/status/endpoints
OAuth authentication detected on Command server.
Saving Command OAuth configurations to database
Test connection succeeded.
SUCCESS - Command Enrollment API Configuration complete.
************************************
*         Configuring IIS.         *
************************************
SUCCESS - IIS is configured.
  2. Prompts from command line with Windows authentication to SQL:
    .\KeyfactorACMEConfig.exe configure --database ACME93
*******************************************
*         Database Configuration.         *
*******************************************
SQL Server Name:
sqlsrvr05.keyexample.com <- Enter the name of the SQL server to store the Keyfactor ACME database
Please choose between (S)ql and (I)ntegrated Authentication.
I <- Select an authentication type for the connection to SQL
Database 'ACME93' does not exist. Creating. <- Using the database name passed in with the --database parameter
Database 'ACME93' created successfully.
Upgrading ACME database
SUCCESS - Database configuration is complete.

****************************************************************************************
*         Configuration setup for authentication with ACME Key Management API.         *
****************************************************************************************
OAuth Name Claim Type:
preferred_username <- In this section, enter the OAuth connection information for authentications to Keyfactor ACME
OAuth Role Claim Type:
groups
OAuth Unique Claim Type:
sub
OAuth Authority:
https://appsrvr186.keyexample.com:4443/realms/Keyfactor
OAuth JSON Web Key Url:
https://appsrvr186.keyexample.com:4443/realms/Keyfactor/protocol/openid-connect/certs
Saving ACME OAuth connection information to database
SUCCESS - ACME OAuth Configuration complete.

***************************************************************************************
*         Configuration setup for authenticating with Command Enrollment API.         *
***************************************************************************************
Url of Command Enrollment API: (Default:https://localhost/KeyfactorAPI)
https://command.keyexample.com/KeyfactorAPI <- Enter the URL for the Keyfactor Command server
Testing connection to https://command.keyexample.com/KeyfactorAPI/status/endpoints
OAuth authentication detected on Command server.
OAuth Client Id:
ACME <- Enter the OAuth credentials to authenticate to Keyfactor Command
OAuth Client Secret:
******************************** <- Enter the OAuth credentials to authenticate to Keyfactor Command
OAuth Token Url:
https://appsrvr187.keyexample.com:5443/realms/Keyfactor/protocol/openid-connect/token <- Enter the token URL to request a token to authenticate to Keyfactor Command
Saving Command OAuth configurations to database
Test connection succeeded.
SUCCESS - Command Enrollment API Configuration complete.

************************************
*         Configuring IIS.         *
************************************
Application Pool to run the web app:
ACMEPool <- Enter the name of the pre-created IIS application pool the Keyfactor ACME server will use
SUCCESS - IIS is configured.
Host name of ACME server:
websrvr93.keyexample.com <- Enter the FQDN of the Keyfactor ACME server

*********************************************************
*         Configuring App Pool SQL Permissions.         *
*********************************************************
SUCCESS - Finished granting the app pool user access to the database.
Tip:  The Keyfactor ACME server will only use the last database successfully configured through the command line tool from a given server.