Installing

Once you've completed all the preparation steps, you can follow the below instructions to install the gateway and connect to the Keyfactor Gateway Receiver and the Keyfactor Command instance in the managed environment.

Tip:  When you save the Keyfactor Windows 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). Gateway configuration, it creates an enrollment services object in the local 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. matching the name you enter in the gateway configuration wizard for the 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. logical nameClosed The logical name of a CA is the common name given to the CA at the time it is created. For Microsoft CAs, this name can be seen at the top of the Certificate Authority MMC snap-in. It is part of the FQDN\Logical Name string that is used to refer to CAs when using command-line tools and in some Keyfactor Command configuration settings (e.g. ca2.keyexample.com\Corp Issuing CA Two).. If an object already exists with this CA logical name, you may need to delete the existing object before proceeding. The object only needs to be deleted if it does not match the new configuration you are making.

For example, if you're moving the implementation from one server to another, this will change the dNSHostName attribute on the enrollment service object. In this scenario, the enrollment services object will need to be deleted.

If you do not delete the enrollment services object, you may receive an error of AD Registration Failed when trying to save the gateway configuration. If this occurs, you will need to close the configuration wizard, delete the enrollment services object, and start the configuration wizard again.

For more information, see Identify the Installation User.

Note:  A highly available Keyfactor Windows Enrollment Gateway solution can be supported by implementing two or more instances of the Keyfactor Windows Enrollment Gateway, both directed to the same managed instance of Keyfactor Command and configured with the same set of templates. The Keyfactor Windows Enrollment Gateway does not support Microsoft failover clustering.

To begin the Keyfactor Windows Enrollment Gateway installation, execute the CAProxyInstall.msi file from the installation media and install as follows:

  1. On the first installation page, click Next to begin the setup wizard.

    Figure 726: Install Keyfactor Windows Enrollment Gateway

  2. On the End-User License Agreement page, read and accept the license agreement and click Next.

  3. On the Custom Setup page, select the features to install. The available features are:

    • Keyfactor Windows Enrollment Gateway

      The main gateway service that receives and processes enrollment requests and other CA-related functions.

    • Keyfactor Windows Enrollment Sync Service (Optional)

      The optional service that synchronizes Active Directory users and groups from the local forest to the managed environment (see Create or Identify Accounts for Synchronization (Optional)).

      Note:  If token authentication with OAuth will be used to authenticate to Keyfactor Command, account synchronization with the Keyfactor Windows Enrollment Sync Service will be disabled. There will be no need to install this component.

  4. On the Destination Folder page, select the destination folder for the install. The default installation location is:

    C:\Program Files\Keyfactor\Keyfactor Windows Enrollment Gateway
  5. On the next screen, click Install.
  6. On the final installation wizard page, leave the Launch the Configuration Wizard on exit box selected and click Finish. The configuration wizard should open automatically. This can take several seconds.

  7. In the gateway configuration wizard, you can choose to upload a configuration file to populate the fields. You may have a file saved from a previous run of the configuration wizard or you may be provided one by Keyfactor. To upload a file, in the configuration wizard, click File at the top of the wizard and choose Open Config File. Browse to locate the configuration file. Configuration files have an extension of .cmscfg. The file may be protected with a password. If it is, you will need to provide this password to open the file. Continue with the remainder of the steps, reviewing the tabs to assure that the data is complete and correct.

    Figure 727: Upload Existing Configuration File

  8. In the gateway configuration wizard on the Security tab, click the Edit Security button and in the Edit Security popup, grant appropriate permissions to users, groups and service accounts in the local environment:

    • Users who will enroll for certificates from the EJBCA CA via the gateway need Read and Request permissions.

    • If you would like to allow computers in the local forest to enroll for certificates using the Microsoft MMC rather than Keyfactor Command, add the Domain Computers group for each domain, or similarly reference the computer machine accounts, and grant them Request permissions.

      Note:  If you plan to enroll for certificates in the MMC from the gateway server itself, be sure to grant enollment permissions using a group rather than referencing the machine account directly (see the Release Notes for a known issue on this).
    • Users who will approve or deny pending certificates outside of Keyfactor Command (through the gateway) need Read and Issue and Manage Certificate (Manage Certs) permissions.
    • Administrators who will manage the gateway in the future need Manage CA permissions.
    Tip:  Manage CA permissions are granted by default to the local Administrators group (BUILTIN\Administrators) on the server on which the gateway is being installed. This is done because local administrator permissions are needed to complete the initial configuration of the gateway. The user performing the install needs to be a member of this local Administrators group either explicitly or via group membership. You may remove the local Administrators group if desired, but at least one user must continue to have the Manage CA permission going forward. Only users with the Manage CA permission can open the gateway configuration tool to make changes to the configuration in the future.

    When the gateway is first installed, it is registered in Active Directory as a certificate authorityClosed 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.. In order to accomplish this step, the user performing the install needs Write and Create Child Object permissions on the following Active Directory container (where DC=keyexample, DC=com are valid for your Active Directory environment):

    CN=Enrollment Services, CN=Public Key Services, CN=Services, CN=Configuration, DC=keyexample, DC=com

    By default, these permissions are granted to members of the Active Directory Domain Admins and Enterprise Admins groups, and the Active Directory Domain Admins group is by default a member of the local Administrators group on domain-joined machines. If this is not the case in your environment, you will need to grant the user installing the gateway these permissions. If changes are made to permissions or to the user's account (e.g. group membership) in the middle of configuration, the user will need to close the configuration wizard and open it again to pick up the changes. Depending on the type of changes made, the user may need to log out of Windows and back in again.

    Figure 728: Configure Security

  9. In the gateway configuration wizard on the CA Config tab, select a Credential Type of Basic or OAuth depending on the authentication method in use for your Keyfactor Command instance.

    If you selected Basic authentication, enter the Username and Password of the Keyfactor APIClosed 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. service account in the managed forest provided to you by Keyfactor.

    Figure 729: Configure CA Config with Basic Authentication

    If you selected OAuth token authentication, enter the Client ID and Client Secret of the Keyfactor API service account in the managed forest provided to you by Keyfactor. In the Token URL field, enter the URL of the token endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. for the identity provider in the managed forest provided to you by Keyfactor. If provided to you, enter a Scope and Audience in these optional fields. One or more scopes may be specified when requesting a token. The audience indicates the entity the token is intended for.

    Figure 730: Configure CA Config with OAuth Authentication

    Tip:  Passwords and select other sensitive information are encrypted using a self-signed encryption certificate that is generated when the gateway is configured. The certificate—with a CNClosed A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). of CA Gateway Config Encryption—is placed in the local machine store on the server on which you are installing the gateway. If a gateway encryption certificate exists in the local machine store on the server on which you are installing the gateway with sufficient remaining validity (from either an earlier installation of the gateway or an installation of one of the other Keyfactor gateways that generates an encryption certificate) this existing certificate will be used to encrypt the sensitive data and a new certificate will not be generated.

    If the gateway's CA Gateway Config Encryption certificate exists in the gateway machine's personal store but has expired, the gateway will continue to function because the decryption of the encrypted data will still be performed, as long as no changes need to made to the configuration. If a change is required to any of the configuration, a new CA Gateway Config Encryption certificate will be generated automatically when the configuration wizard is re-run, and the new certificate will be used to encrypt any sensitive data.

    In the API URL field, enter the URL of the Keyfactor API service in the managed forest instance of Keyfactor Command, as provided to you by Keyfactor. For example:

    https://exm101keyfactor.keyfactor.com/KeyfactorAPI

    Click the Validate Connection button to confirm that connectivity to the managed instance of Keyfactor Command is functioning successfully with the provided information.

    Important:  The validation must complete successfully before you can move to the TemplateClosed A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. Selection step.

    In the CA Logical Name field, enter a logical name you will use to reference the gateway as a CA in the local environment when doing enrollments via the gateway or making other CA queries. For example, in this certificate request command:

    certreq -submit -config "gtwysrvr2.keyexample.com\Gateway-CA" -attrib "certificateTemplate:EnrollGatewayUser" MyNew.csr MyNew.cer

    The name Gateway-CA is the logical name of the gateway as a CA, registered in your local Active Directory. By default, the gateway server's hostnameClosed The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). followed by “-CA” is suggested for you. You do not need to accept the suggested value, and the value you enter here does not need to match the logical name of the EJBCA CA. The name cannot easily be changed once it has been configured.

    Tip:  The certreq command is case sensitive when referencing things like the CA, so if your CA’s logical name as registered in your local Active Directory is Gateway-CA but you enter a certreq command with gateway-ca, your CA won’t be found.

    Click the Select Logical CA Certificate button and choose the CA certificate you acquired and installed as per Acquire and Install a Chain Certificate. A certificate must be selected from the Intermediate Certification Authorities store.

  10. In the gateway configuration wizard on the Template Selection tab, click Add to add a new local-to-remote mapping row. In the left column of the mapping row, select a template in the dropdown from your local environment (see Create or Identify Templates). In the right column of the mapping row, select a template in the dropdown from your managed instance of Keyfactor Command to map the local template to. Only templates associated with HTTPS CAs are shown. When you create a mapping, enrollment requests made for the template in the local environment are sent on to the final CA via Keyfactor Command by the gateway using the remote template from the mapping.

    Template validation logic checks that the template’s default enrollment pattern has 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. enrollment enabled. If CSR enrollment is not enabled, the template will not be valid for mapping and a validation error message will be displayed when mapping the template. To map the template with this error, go to Keyfactor Command and mark the template’s default enrollment pattern for CSR enrollment and then retry the configuration for that template.

    Example:  A user enrolls for a certificate using the Microsoft certificates MMC and selects the gateway as the CA and the Corp Web Server template. The request is sent to the gateway, where the template for the request is changed to the one from Keyfactor Command—Sample_WebServer—that has been mapped to the Corp Web Server template. The request is then sent on to the managed instance of Keyfactor Command and from there to the EJBCA CA where the certificate is requested and issued.

    Figure 731: Example: Template Mapping

    If you've made updates to the templates configured either in your managed instance of Keyfactor Command or locally, click the Refresh button to query Keyfactor Command and the local Active Directory for the latest template lists.

    To remove a template mapping row, click Remove to the right of the row you wish to remove.

    Check the Include Invalid Templates box to allow all templates from the managed instance of Keyfactor Command to appear in the right column dropdown, including those that are not valid for mapping to the template selected in the left column. This can be helpful in troubleshooting why an expected template from Keyfactor Command is not appearing in the right column. Templates that are not valid for mapping appear with a warning flag. If you select one of these for mapping, you will see a detailed error message indicating why the template is not valid for mapping. If there is more than one reason why the template is not valid for mapping, all discovered reasons will be shown. Errors appear in the Validation Errors and Warnings dropdown and can be seen in a popup if you hover over the warning icon for each template with a warning.

    Example:  You want to map the Gateway Web Server v2 template to the Sample_WebServerv2 template from the managed instance of Keyfactor Command but the Sample_WebServerv2 template does not appear in the right dropdown when you go to create the mapping. You check the Include Invalid Templates box and check the right dropdown again. The Sample_WebServerv2 template now appears but with a warning flag. You select it and then either hover over the warning flag or open the Validation Errors and Warnings at the top to check what the error message is. You discover that the key sizeClosed The key size or key length is the number of bits in a key used by a cryptographic algorithm. configured on the Sample_WebServerv2 template is greater than that of the local template you're trying to map, which isn't supported. The key size of the template in the managed instance of Keyfactor Command must be less than or equal to the key size of the template from the local environment.

    Figure 732: Example: Template Mapping with an Error

    Tip:  If the expected templates from the local environment do not appear on this tab, confirm that you followed the instructions for identifying templates for use with the gateway (see Create or Identify Templates). Make sure that the user running the gateway installation has read permissions on all the templates you want to configure in the gateway.

    If the expected templates from the managed instance of Keyfactor Command do not appear on this tab, confirm that they exist in Keyfactor Command. Click Refresh to fetch the latest templates from Keyfactor Command and the local Active Directory. Confirm that the remote templates are an appropriate match for the local template you are trying to map by using the Include Invalid Templates option.

    Note:  If you've opted to separate the roles for the gateway and sync services onto separate machines, the Template Selection tab will not appear for the sync service. This configuration information is for the gateway service only.

    Figure 733: Configure Template Mapping

  11. Optional: In the gateway configuration wizard on the Account Synchronization tab, enter the Username and Password of the Web Proxy service account in the managed forest provided to you by Keyfactor. In the Web Proxy URL field, enter the URL of the Keyfactor Gateway Receiver service in the managed forest instance of Keyfactor Command, as provided to you by Keyfactor. For example:

    https://exm101keyfactor.keyfactor.com/KeyfactorEnrollGateway

    Click the Validate Connection button to confirm that connectivity to the Keyfactor Gateway Receiver is functioning successfully with the provided username, password and URL.

    If you wish to synchronize Active Directory users and groups from the local forest to the managed forest, enter a value in the Account Sync Interval (minutes) field. If you don't wish to synchronize users and groups, set the sync interval value to zero. The Sync Timeout (seconds) defaults to 100. This value will be appropriate in most environments. If you encounter timeout errors when the synchronization service attempts to send data to the cloud-based receiver, you may need to extend this timeout value.

    If desired, enter a value in the AD Search Base field to limit the user and group synchronization to just a selected portion of your AD tree (a single OU and any OUs under it, for example). The value should be entered in DNClosed A distinguished name (DN) is the name that uniquely identifies an object in a directory. In the context of Keyfactor Command, this directory is generally Active Directory. A DN is made up of attribute=value pairs, separated by commas. Any of the attributes defined in the directory schema can be used to make up a DN. syntax (e.g. ou=Groups,dc=keyexample,dc=com).

    Tip:  Although the AD Search Base option limits the search to groups found within the specified location, all users in these groups, regardless of their location in Active Directory, will be synchronized.

    Enter groups in the local forest containing users that should be synchronized to the managed forest in the Groups To Sync field. You may click Select to browse for groups. Click the Validate button to confirm that groups typed into the field have been entered correctly and exist in the specified AD Search Base, if applicable.

    Synchronization of users and groups from the local forest is optional. Use of the AD Search Base field is optional.

    Important:  The account synchronization function requires installation of the Active Directory module for Windows PowerShell, one of the options within the Remote Server Administration Tools Windows feature (see System Requirements), unless you opt to replace the built-in PowerShell scripts that run on Select and Validate with custom scripts that bypass these tools.
    Note:  The Account Synchronization tab will be grayed out if you installed this option but selected OAuth as your authentication option on the CA Config tab. Account synchronization is not supported when OAuth is used.
    Note:  If you've opted to separate the roles for the gateway and sync services onto separate machines, the Account Synchronization tab will not appear for the gateway service. This configuration information is for the sync service only.

    Figure 734: Configure Account Synchronization

  12. Before completing the configuration wizard, you may choose to save a copy of the configuration as a file for future use. To download the configuration as a file, in the configuration wizard, click File at the top of the wizard and choose Save Config File… . Browse to a location where you want to save the configuration file, enter a file name and click Save. You will be prompted to enter a password to encrypt the data in the file. You may choose to protect the file with a password or not. If you use a password at this time, you will need to provide this password to open the file. Keyfactor strongly recommends using a password to protect production files. If you do not wish to use a password to protect a production file, you may edit the file to remove the sensitive information (the password for the service account entered in the configuration wizard). Once you enter a password or uncheck the encryption box, click OK to save the file.

    Figure 735: Save Configuration File

  13. At the bottom of the dialog, click Save and close the dialog.