The Configure Command
The configure command of the Keyfactor ACME configuration tool (KeyfactorACMEConfig.exe) is used to set up the Keyfactor ACME Server on Windows during initial provisioning and to apply configuration changes afterward.
After installing the Keyfactor ACME software, configure it as follows:
- Open a command prompt using the Run as administrator option.
-
Change to the Configuration directory under the directory in which you installed Keyfactor ACME. By default, this is:
C:\Program Files\Keyfactor\ACME\Configuration -
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.Tip: To use Basic authentication between Keyfactor ACME and Keyfactor Command, do not specify any of the command authentication parameters (e.g. --commandclientid). The configuration tool will evaluate Keyfactor Command to determine the supported authentication methods, and if Basic authentication is supported, the tool will prompt for a username and password. Windows authentication must be disabled on the Keyfactor API
An API is 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. virtual directory to allow Keyfactor ACME to connect and function with Basic authentication. This is not the default Keyfactor Command configuration.Examples:
-
Pre-populate the configuration values using SQL authentication and OAuth to authenticate to Keyfactor Command:
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" -
Prompts from command line, with or without database name specified. For example, with the database specified, using SQL authentication, and using Basic authentication to Keyfactor Command:
Copy.\KeyfactorACMEConfig.exe configure --database ACME
SQL Server Name:
sqlsrvr05.keyexample.com
Please choose between (S)ql and (I)ntegrated Authentication.
s
SQL Server Username:
john_smith
Please enter the user password to connect to SQL.***********
*******************************************
* Database Configuration. *
*******************************************
Database 'ACME' does not exist. Creating.
Database 'ACME' 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
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
Testing connection to https://command.keyexample.com/KeyfactorAPI/status/endpoints
Basic authentication detected on Command server.
Username to use for basic authentication to the Keyfactor API. (DOMAIN\username or username@domain.example):
keyexample\svc_acme
Password:
***********
Saving Basic Auth configurations to database
Test connection succeeded.
SUCCESS - Command Enrollment API Configuration complete.
************************************
* Configuring IIS. *
************************************
Application Pool to run the web app:
ACMEPool
SUCCESS - IIS is configured.
Host name of ACME server:
websrvr93.keyexample.comIn 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 |
|---|---|---|---|
|
--acmeauthority
|
The issuer/authority endpoint URL for the identity provider that is used to authenticate entities connecting to the Keyfactor ACME server. The information referenced by this parameter is required and will be prompted for if not supplied. |
||
|
--acmejwksurl
|
The JWKS (JSON Web Key Set) URL for the identity provider that is used to authenticate entities connecting to the Keyfactor ACME server. The information referenced by this parameter is required and will be prompted for if not supplied. |
||
|
--acmenameclaimtype
|
A type of user claim for the identity provider containing a friendly name for the user. This is used to authenticate entities connecting to the Keyfactor ACME server. The information referenced by this parameter is required and will be prompted for if not supplied. Tip: Claims to grant permissions and map templates are configured using the Claims API endpoints (see Keyfactor ACME API)
|
For Keycloak, 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). |
|
|
--acmeroleclaimtype
|
The value used to reference the type of group claim for the identity provider. This is used to authenticate entities connecting to the Keyfactor ACME server. The information referenced by this parameter is required and will be prompted for if not supplied. |
For Keycloak, this should be: groups
|
|
|
--acmeuniqueclaimtype
|
A type of user claim for the identity provider containing a unique name for the user. This is used to authenticate entities connecting to the Keyfactor ACME server. The information referenced by this parameter is required and will be prompted for if not supplied. |
For Keycloak, this should be: sub
In Keycloak, 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:
The information referenced by this parameter is required and will be prompted for if not supplied. |
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.
|
|
--commandaudience
|
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. |
|
|
--commandauthority
|
The issuer/authority endpoint URL for the identity provider used to authenticate from Keyfactor ACME to Keyfactor Command if OAuth authentication is used for Keyfactor Command. The information referenced by this parameter is required if OAuth is used and will be prompted for if not supplied. |
Important: The OAuth identity provider used to authenticate to Keyfactor Command must be defined as an identity provider in Keyfactor Command.
|
|
|
--commandclientid
|
The ID of the client application created in the identity provider to authenticate from Keyfactor ACME to Keyfactor Command if OAuth authentication is used for Keyfactor Command. The information referenced by this parameter is required if OAuth is used and will be prompted for if not supplied. |
||
|
--commandclientsecret
|
The secret of the client application created in the identity provider to authenticate from Keyfactor ACME to Keyfactor Command if OAuth authentication is used for Keyfactor Command. The information referenced by this parameter is required if OAuth is used and will be prompted for if not supplied. |
||
|
--commandscope
|
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. |
|
|
--commandtokenurl
|
The token endpoint URL for the identity provider used to authenticate from Keyfactor ACME to Keyfactor Command if OAuth authentication is used for Keyfactor Command. The information referenced by this parameter is required if OAuth is used 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:
Optional Hardware Security Module (HSM):
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.
|
|
--forcedatabaseupgrade
|
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 on Windows 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. |
|
--useintegratedauthentication
|
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 |
--virtualdirectory
|
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
- 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.
- Prompts from command line with Windows authentication to SQL and OAuth to Keyfactor Command:
.\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.
Was this page helpful? Provide Feedback