Certificate Authority Operations

The fields on the certificate authorities tab grid include:

Adding or Modifying a CA Record

Whether your CA has been imported or added manually, you'll need to update it to configure synchronization and other optional settings. When adding or editing your CAs, the connection can be tested prior to saving.

CAs that need to be added manually include:

• An EJBCA CA
• A Microsoft CA accessed via the CA Connector Client. This is often used with a managed instance of Keyfactor Command.
• A EJBCA CA accessed via the CA Connector Client. This is often used with a managed instance of Keyfactor Command.

If your Microsoft CA or Keyfactor CA gateway is domain-joined in the forest in which Keyfactor Command is installed or a forest in a two-way trust with this forest and has been registered in Active Directory, you can opt to add a record for it manually, but it is generally easier to use the import option (see Importing Trusted Forest CAs).

To create a CA record manually or modify an existing one:

1. In the Management Portal, browse to Locations > Certificate Authorities.
2. On the Certificate Authorities page, select the Certificate Authorities tab, and click Add to add a new CA, or select a row and click Edit from either the top or right-click menu to modify an existing one.

3. At the top of the dialog, choose an appropriate CA communication protocol in the Select CA Communication Protocol dropdown. The options are:

   • DCOM—Select this option for Microsoft CAs, CA Connector Clients or type DCOM/Microsoft, CAs accessed via a Keyfactor Universal Orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores., and Keyfactor CA gateways.

   • HTTPS—Select this option for EJBCA CAs, CA Connector Clients or type HTTPS/EJBCA, and AnyCAGateway REST.

   This field cannot be modified on an edit.

4. The remainder of the Certificate Authority dialog shows five tabs. Only the first four are used for EJBCA CAs. Complete the Certificate Authority dialog with the appropriate data using the following instructions:

   The Basic Tab

   Details Section

   • Populate the Logical Name, Host Name and Configuration Tenant fields with the appropriate information for the CA.

     The Logical Name and Configuration Tenant fields cannot be modified on an edit.

     Tip:  Previous versions of Keyfactor Command referred to the Configuration Tenant as the Template Forest.

   • For CAs of type HTTPS, you may enable either Enforce Unique DN or Create new End Entity when renewing or reissuing certificates. These options are mutually exclusive and you may not enable both; they CANNOT both be selected since they're telling the CA to do opposite things. If you enable one, the other will be disabled and grayed out. They are disabled by default.

     Enforce Unique DN

     Toggling this to enable it will cause Keyfactor Command, upon enrollment, to search the EJBCA CA for end entities with DNs that match the DN 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. in the certificate request. If a matching DN is found, the process will update the existing end entity in EJBCA with the new certificate request information rather than creating a new end entity. If you enable this option in Keyfactor Command, it must also be enabled on the matching EJBCA CA. A mismatch in these settings can result in enrollment failures.

     

     Figure 233: Enforce Unique DN Setting on the EJBCA CA

     The value of the Keyfactor Command Enforce Unique DN setting is verified for each certificate request:

     • If unset, enrollment proceeds as usual.

     • If set, EJBCA is searched for an end entity associated with the DN and CA in the certificate request and:

       • If none is found, the enrollment proceeds as usual.
       • If one or more is found, the end entity in EJBCA is updated with the information from the certificate request, so that the new certificate request is tied to the same end entity as the existing certificate (or the first one found, if multiple are found). A new password is generated and the enrollment proceeds as usual.

     Note:  Enforce Unique DN must be set to disabled if OAuth is selected as the Auth Method on the Authentication Method tab.
     Create new End Entity when renewing or reissuing certificates

     Enabling this will force the EJBCA CA to create a new end entity for any renewed or reissued certificate. This option must be enabled for CAs configured to authenticate with OAuth (see Authentication Method Tab) or CAs managed through the AnyCAGateway REST.

     Note:  Create new End Entity when renewing or reissuing certificates must be set to enabled if OAuth is selected as the Auth Method on the Authentication Method tab.
     Note:  The Enforce Unique DN and Create new End Entity when renewing or reissuing certificates options appear only for HTTPS certificate authorities.

   The following are some tips on how to configure various types of CAs:

   EJBCA CA

   • Select CA Communication Protocol—HTTPS

   • Logical Name—The logical name of the EJBCA CA. For example: CorpCA1

     Note:  EJBCA CA logical names are case sensitive (e.g. CorpCA1 is not the same as CORPCA1).

   • Host URL—The URL pointing to the EJBCA CA. For example: https://ejbca01.keyother3.com. If the URL provided does not have a virtual directory (/ejbca or otherwise) the /ejbca will be provided, otherwise it will use what is supplied in the URL.

   • Configuration Tenant—A reference ID for the EJBCA CA server. For EJBCA CAs, this does not need to be the DNS The Domain Name System is a service that translates names into IP addresses. domain name. The short hostname 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). of the EJBCA CA server makes a good reference ID.

     Important:  EJBCA and Microsoft CAs cannot be configured with the same Configuration Tenant, so do not set this to the DNS domain name if you will also be configuring Microsoft CAs in the same DNS domain.

   Domain-Joined Enterprise or Standalone Microsoft CA in the Forest in which Keyfactor Command is Installed or in a Two-Way Trust with this Forest

   • Select CA Communication Protocol—DCOM
   • Logical Name—The logical name of the CA in the local forest. For example: CorpIssuingCA1
   • Host Name—The fully qualified domain name of the server on which the CA in the local forest is installed. For example: corpca01.keyexample.com
   • Configuration Tenant—The DNS domain name for the Active Directory forest in which the CA resides. For example: keyexample.com

   Note:  CAs of this type can generally be imported automatically using the Import option—or are imported automatically on install—unless they have not been added to Active Directory.

   Domain-Joined Enterprise or Standalone Microsoft CA in a Forest with a One-Way Trust (either direction) with the Forest in which Keyfactor Command is Installed

   • Select CA Communication Protocol—DCOM
   • Logical Name—The logical name of the CA in the remote forest. For example: Corp2IssuingCA1
   • Host Name—The fully qualified domain name of the server on which the CA in the remote forest is installed. For example: corp2ca01.keyother.com
   • Configuration Tenant—The DNS domain name for the Active Directory forest in which the CA resides. For example: keyother.com

   Domain-Joined Enterprise or Standalone Microsoft CA in a Forest that has No Trust with the Forest in which Keyfactor Command is Installed

   • Select CA Communication Protocol—DCOM
   • Logical Name—The logical name of the CA in the remote forest. For example: Corp3IssuingCA1
   • Host Name—The fully qualified domain name of the server on which the CA in the remote forest is installed. For example: corp3ca01.keyother2.com
   • Configuration Tenant—The DNS domain name for the Active Directory forest in which the CA resides. For example: keyother2.com

   Non-Domain-Joined Standalone Microsoft CA

   • Select CA Communication Protocol—DCOM
   • Logical Name—The logical name of the standalone CA. For example: CorpSARootCA1
   • Host Name—The fully qualified domain name of the server on which the standalone CA is installed. For example: saroot01.keyexample.com
   • Configuration Tenant—The DNS domain name for the standalone CA. For example: keyexample.com

   Remote EJBCA CA Accessed via a CA Connector Client

   • Select CA Communication Protocol—HTTPS
   • Logical Name—The logical name of the CA in the remote forest to which the CA Connector Client will be connecting for synchronization. For example: CorpIssuingCA2
   • Host URL—The URL pointing to the CA in the remote forest to which the CA Connector Client will be connecting for synchronization. For example: https://ejbca01.keyother3.com. If the URL provided does not have a virtual directory (/ejbca or otherwise) the /ejbca will be provided, otherwise it will use what is supplied in the URL.
   • Configuration Tenant—A reference ID for the EJBCA CA server. For EJBCA CAs, this does not need to be the DNS domain name. The short hostname of the EJBCA CA server makes a good reference ID.

   Important:  EJBCA and Microsoft CAs cannot be configured with the same Configuration Tenant, so do not set this to the DNS domain name if you will also be configuring Microsoft CAs in the same DNS domain.

   Note:  You must install and configure the CA Connector Client on a machine in the same environment where the CA resides and configure a CA Connector for it in the Management Portal before creating the CA record.

   Remote Microsoft CA Accessed via a CA Connector Client

   • Select CA Communication Protocol—DCOM
   • Logical Name—The logical name of the CA in the remote forest to which the CA Connector Client will be connecting for synchronization. For example: CorpIssuingCA3
   • Host Name—The fully qualified domain name of the CA in the remote forest to which the CA Connector Client will be connecting for synchronization. For example: corpca03.keyother4.com
   • Configuration Tenant—The DNS domain name for the Active Directory forest in which the CA Connector Client is operating and in which the CA resides. Or for non-domain-joined standalone CAs, the DNS domain name. For example: keyother4.com

   Note:  You must install and configure the CA Connector Client on a machine in the same environment where the CA resides and configure a CA Connector for it in the Management Portal before creating the CA record.

   Remote Microsoft CA Accessed via a Keyfactor Universal Orchestrator

   • Select CA Communication Protocol—DCOM
   • Logical Name—The logical name of the CA in the remote forest to which the orchestrator will be connecting for synchronization. For example: Corp4IssuingCA1
   • Host Name—The fully qualified domain name of the CA in the remote forest to which the orchestrator will be connecting for synchronization. For example: corp4ca01.keyother4.com
   • Configuration Tenant—The DNS domain name for the Active Directory forest in which the orchestrator is operating and in which the CA resides. For example: keyother4.com

   Note:  You must install and configure the Keyfactor Universal Orchestrator on a machine in the same forest where the CA resides, configure it with CA Support and approve the orchestrator in the Management Portal before creating the CA record.

   Keyfactor CA Gateway

   • Select CA Communication Protocol—DCOM
   • Logical Name—The logical name of the CA gateway in the local forest. For example: EntrustGateway
   • Host Name—The fully qualified domain name of the server on which the CA gateway in the local forest is installed. For example: entgtw1.keyexample.com
   • Configuration Tenant—The DNS domain name for the Active Directory forest in which the CA resides. For example: keyexample.com

   AnyCAGateway REST

   • Select CA Communication Protocol—HTTPS

   • Logical Name—The logical name, exactly as entered in AnyCA Gateway portal. The logical name is unique for each CA.

     Note:  Logical names are case sensitive (e.g. CorpCA1 is not the same as CORPCA1).
   • Host URL—The fully qualified domain name of the server on which the gateway is installed and the port number defined in -ServerPort. For example: https://CAGateway24.keyexample.com:8443. The Host URL is unique for each CA.
   • Configuration Tenant—A reference ID for the gateway CA. This can be any name you choose, but it should not conflict with other non-related CAs.

   Important:  HTTPS and DCOM CAs cannot be configured with the same Configuration Tenant, so do not set this to the DNS domain name if you will also be configuring DCOM CAs in the same DNS domain.

   Scan Section

   In the Scan section, choose when to schedule full and incremental scans. You can choose to run each scan Weekly, Daily or on an Interval:

   • If you select Weekly, you can select one or more days of the week on which to run the scan and a time when the scan should begin.
   • If you select Daily, you can set the time of day when the scan should begin.
   • If you select Interval, you can select a scan frequency of anywhere from every 1 minute to every 12 hours.

   • Select Off in the dropdown to disable a scan job.

     There are two types of synchronization schedules available for CAs—Full and Incremental. You do not necessarily need to configure both types. A full scan reads all the certificates and certificate requests in the CA database and synchronizes them to Keyfactor Command regardless of their current state in Keyfactor Command. An incremental scan reads the certificates and certificate requests in the CA database that have been generated since the last full or incremental scan and synchronizes them to Keyfactor Command. A common configuration would be a full scan once or twice a week to provide a clean image of the CA database with a frequent incremental scan to provide timely updates to Keyfactor Command. For a large CA database, a full scan can take a long time to complete. Since an incremental scan only synchronizes updates that have occurred to the CA database since the last synchronization was run, this process is generally quick (other than for the initial synchronization when Keyfactor Command is first installed). The frequency of the incremental scans would depend on the volume of certificate requests coming into the CA.

     Note:  For EJBCA CAs, if the certificate profile has a Validity Offset configured to a value greater than the value configured in the CA Sync Backward Offset Minutes application setting (15 minutes by default), certificates requested outside of Keyfactor Command will not be picked up on incremental scans. These certificates will only appear in Keyfactor Command on a full synchronization. The CA Sync Backward Offset Minutes application setting should be set to the same number of minutes as the Validity Offset value, if Validity Offset is configured.

     

     Figure 234: EJBCA Certificate Profile Validity Offset Greater than 15 Minutes

     Note:  For EJBCA CAs, if the certificate profile has Allow Backdated Revocation configured and a revocation is completed outside of Keyfactor Command with a backdate of greater than 10 minutes, the revocation will not be picked up on incremental scans. These revocations will only appear in Keyfactor Command on a full synchronization.

     

     Figure 235: EJBCA Certificate Profile Backdated Revocation

   For Microsoft CAs, if desired click the Sync External Certificates toggle to allow foreign certificates that have been imported into a Microsoft CA to be synchronized to Keyfactor Command along with the certificates issued by the Microsoft CA. This option does not appear for HTTPS CAs.

   

   Figure 236: Certificate Authority Basic Tab for a Microsoft CA

   

   Figure 237: Certificate Authority Basic Tab for an EJBCA CA

   Advanced Tab

   On the Advanced tab, configure enrollment settings and advanced connectivity and authorization configurations.

   Details Section

   In the Details section, if you've opted to use either the Keyfactor Universal Orchestrator or the CA Connector Client to communicate with a remote CA, click the Use Orchestrator or Use CA Connector toggle to enable this functionality and choose the appropriate orchestrator or CA Connector Client in the appropriate dropdown.

   Important:  The Use CA Connector toggle is only active if both Delegate Management Operations and Delegate Enrollment are toggled to disabled.

   Note:  The Use Orchestrator and Use CA Connector dropdowns are only active if the respective Use Orchestrator or Use CA Connector toggle is enabled. If you enable one of these options, the matching dropdown will populate with any orchestrators approved in Keyfactor Command with the CA capability or any CA connectors defined on the CA Connectors tab (see CA Connectors Tab).

   For the orchestrator option, the Keyfactor Universal Orchestrator must be installed on a machine in the forest where the remote CA resides, installed and configured as per Universal Orchestrator. In addition, in the Management Portal, the Keyfactor Universal Orchestrator must be configured as per Orchestrator Management.

   For the CA Connector Client option, the CA Connector Client must be installed on a machine in the environment where the remote CA resides, installed and configured as per the instructions in the CA Connector Client Installation and Configuration Guide. In addition, the CA Connector API 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. must be installed on a Keyfactor Command server and the Task Queue Connection (see Task Queue Connection Tab) and CA Connector (see CA Connectors Tab) information must be fully configured in Keyfactor Command.

   Delegation Section

   The Delegate Management Operations and Delegate Enrollment toggles are used for CAs that support Windows integrated authentication to allow interactions with the CAs via Keyfactor Command to be done in the context of the user authenticated to Keyfactor Command using Kerberos authentication. These options also apply to users who authenticate to Keyfactor Command using Basic authentication, since Keyfactor Command performs pseudo delegation for these users. These options are not supported for users who authenticate using NTLM or Token authentication.

   Important:  The Delegate options are only supported when using Active Directory as an identity provider.

   Integrated authentication is generally supported for Microsoft CAs, Keyfactor CA gateways, or Keyfactor CA management gateways on servers joined to the local Active Directory forest in which Keyfactor Command is installed and any Active Directory forests in a two-way trust with this forest. If delegation is enabled, when a user authenticates with Kerberos or Basic authentication to Keyfactor Command, the Keyfactor Command server can delegate the user's credentials to the CA to provide end-to-end authentication without unpacking the credentials at the Keyfactor Command layer.

   The types of interactions affected by these settings include:

   • Approval of pending certificate requests (Delegate Management Operations)
   • Denial of pending certificate requests (Delegate Management Operations)
   • Revocation of certificates (Delegate Management Operations)
   • Certificate key recovery (Delegate Management Operations)
   • Certificate enrollment (Delegate Enrollment)

   Note:  Use of explicit credentials is mutually exclusive of delegation.

   Note:  If a workflow A workflow is a series of steps necessary to complete a process. In the context of Keyfactor Command, it refers to the workflow builder, which allows you automate event-driven tasks when a certificate is requested or revoked. (see Workflow Definitions) is configured with a step that will result in a suspended state (e.g. pausing to wait for approvals) and the CA for the request is configured for delegation, the enrollment or revocation request made via the workflow will fail with an error indicating that the failure occurred because CA delegation is enabled. Workflows are not supported with CA delegation in the case where a suspended state may occur because it's possible that the initiating user's context may not be available all the way to the conclusion of the workflow.

   When using workflow with steps that will result in a suspended state, do not use CA delegation. Instead, use the Keyfactor Command access control model provided by the Restrict Allowed Requesters option for enrollment (see Enrollment Section) and the Revoke permission for certificates at both the global and collection The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports). levels (see Certificate Collection Permissions).

   If you choose to enable delegation, be aware that each user performing one of these delegable operations through the Management Portal must have the appropriate permissions to accomplish this task configured in the CA security settings.

   Important:  Granting users permissions in the CA security settings for certificate revocation, certificate key recovery, or certificate request approval and denial—e.g. the Issue and Manage Certificates permission—in order to support delegation of these operations through the Management Portal also grants these permissions to the users when operating outside the Keyfactor Command Management Portal.

   The Delegate Management Operations and Delegate Enrollment options are not used for EJBCA CAs.

   Tip:  Keyfactor recommends the following configuration for most DCOM CAs to support access control within Keyfactor Command:

   • Use Explicit Credentials: Enabled or disabled as required by the environment (see Authentication Method Tab)
   • Delegate Management Operations: Disabled
   • Delegate Enrollment: Disabled
   • Restrict Allowed Requesters: Set to the Keyfactor security roles allowed to perform certificate enrollment for this CA. If you're using workflow (see Workflow Definitions), the users who hold these roles are the ones who are able to initiate workflows. This is entirely separate from the roles configured within workflows, which control the users who are able to approve workflows.

   Enrollment Section

   Important:  Depending on the configurations you make in this section, some toggles will be grayed out and unavailable for change with a default of enabled or disabled. For example, if you enable the Use CA Connector option, the Delegate toggles will automatically be disabled and grayed out. If Delegate Enrollment is disabled, the Restrict Allowed Requesters option will automatically be enabled and grayed out.

   Tip:  To fully configure enrollment for the CA, you will also need to configure access on the Authentication Methods tab (see Authentication Method Tab) for Microsoft CAs requiring access via explicit credentials and EJBCA CAs and configure templates (see Certificate Template Operations).

   • In the Enrollment section, click the Enable PFX Enrollment and/or Enable CSR Enrollment toggles to enable enrollment for the CA through Keyfactor Command.

   • If desired, click the Require Subscriber Terms toggle to add a checkbox on the enrollment pages to force users to agree to a custom set of terms before enrolling. Configure a link to the custom terms using the URL to Subscriber Terms application setting (see Application Settings: Enrollment Tab).

     Note:  The Require Subscriber Terms setting does not apply to enrollments done through the Keyfactor API.

   • If you wish to use One-Click Renewal for certificates, the Allow One-Click Renewals option must be enabled in both the templates and CAs to which you want One-Click Renewal to apply (see Certificate Template Operations and Adding or Modifying a CA Record). For more information about one-click renewals, see Renew.

   • Key Retention may be enabled at the CA level to support standalone Microsoft CAs and other CAs that complete enrollments without a certificate template. For enrollments with a certificate template, set key retention at the template level (see Details Tab).

     Note:  If private key 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. retention is set at both the CA level and the template level, the configuration from the template is used.

     To configure key retention at the CA level, click the Key Retention toggle to enable it and then select a retention type. Enter the number of days, weeks, months, or years to keep the encrypted private key stored in the Keyfactor Command database based on the type selected, then select the desired time frame (Day(s), Week(s), Month(s), or Year(s)). You will not have the option to choose a retention timeframe if you choose Indefinite.

     Configuring private key retention allows the private keys for certificates enrolled through Keyfactor Command to be stored, encrypted, in the Keyfactor Command database for a user-definable period of time.

     The private key retention configuration options are:

     • Blank

       The private key will not be retained if the box is unchecked, or the blank option is selected.

     • Indefinite

       The private key will be retained until it is explicitly deleted.

     • After Expiration

       The private key will be retained until the specified number of days, weeks, months or years after the certificate expires, at which point it will be scheduled for deletion.

     • From Issuance

       The private key will be retained until the specified number of days, weeks, months or years after the date on which the certificate was issued, at which point it will be scheduled for deletion.

     Note:  When the retention period is stored in the database, weeks are converted to 7 days, months are converted to 30 days, and years are converted to 365 days.
     Tip:  Setting the retention period to 0 will cause the private keys to be purged by the private key clean up job when it next runs, after the certificate expires or after the certificate is issued.
     Note:  Key Retention must be enabled at the CA level if the Standalone option is enabled and PFX Enrollment is enabled for the CA.

   • The Restrict Allowed Requesters option is used to select Keyfactor Command security roles that a user must belong to in order to successfully enroll for certificates in Keyfactor Command via this CA. This option must be used to provide enrollment access if the Delegate Enrollment option is disabled. When this option is enabled, use the Add, Edit, and Delete options on the Allowed Requester Security Roles table to manage the security roles that should be granted enrollment access. You must include at least one role in the Allowed Requester Security Roles table for enrollment to work.

     This option is supported for all CAs, but it must be used for:

     • Implementations using OAuth as an identity provider.

     • Microsoft CAs where Windows integrated authentication is not supported.

       Integrated authentication is generally supported for Microsoft CAs, Keyfactor CA gateways, or Keyfactor CA management gateways on servers joined to the local Active Directory forest in which Keyfactor Command is installed and any Active Directory forests in a two-way trust with this forest. Since Keyfactor Command cannot make use of the access control model of the CA itself to determine which users can enroll for certificates at either a template or CA level without using integrated authentication, this setting replaces that functionality. This setting is similar to setting request certificates for the selected security roles at the CA level on a Microsoft CA.

     • EJBCA CAs.

     The Restrict Allowed Requesters toggle must be enabled—and the Allowed Requester Security Roles populated—if the Use Explicit Credentials toggle is enabled for a Microsoft CA that isn't accessed using integrated authentication.

     In addition to granting permissions at the CA level using this option, you need enable the Restrict Allowed Requesters option to grant permissions on a template-by-template basis (see Certificate Templates).

     Tip:  For Microsoft CAs in a two-way trust environment you don't necessarily need to enable Restrict Allowed Requesters on the CA, though this may be required in some circumstances depending on the security configuration in the environment. However, templates for a two-way trust environment always require configuration of this option at a template level to support enrollment (see Certificate Template Operations).

   Note:  Access control for other types of interactions with the CA (e.g. revocation) is managed with standard security roles (e.g. the certificate revoke permission) at both the global and certificate collection level.

   

   Figure 238: Certificate Authority Advanced Tab for Microsoft CA Access Using a CA Connector Client

   Monitoring Tab

   On the Monitoring Tab, click the Enable Monitoring toggle to enable email alerting when certificate issuance or failures (including denials) since the last threshold alert was sent falls outside the configured limits. In the Threshold Check Schedule dropdown, select a delivery schedule for the alerts. You can choose to schedule the alerts either for daily delivery at a specified time or at intervals of anywhere from every 1 minute to every 12 hours. Daily is the most common configuration. Set the thresholds for:

   • Issuance Greater Than—You will receive an alert if more certificates are issued by this CA in the time period between executions of the alert than the number you set here. The value set here must be greater than, or equal to, the value set for Issuance Less Than.
   • Issuance Less Than—You will receive an alert if the number of certificates issued by this CA in the time period between executions of the alert is less than the number you set here. The minimum allowed value for Issuance Less Than is 0.
   • Failures Greater Than—You will receive an alert if more certificate requests fail or are denied by this CA in the time period between executions of the alert than the number you set here. Zero is a valid setting (meaning you will receive an alert for a single failure).
     Note:  EJBCA CAs do not return failure counts using the API, so failures cannot be reported with threshold monitoring for EJBCA CAs.

   In addition to configuring the thresholds for each CA, you must also configure the email recipients on the Alert Recipients tab (see Alert Recipients Tab) of the Certificate Authorities page. Monitoring is not supported for CAs accessed with the Keyfactor Universal Orchestrator.

   

   Figure 239: Certificate Authority Advanced Tab for Microsoft CA

   Authentication Method Tab

   On the Authentication Methods tab, you configure how authentication to the CA from Keyfactor Command for management tasks and enrollment occurs. The options on this tab will vary depending on the type of CA you selected under Select CA Communication Protocol.

   Use Explicit Credentials (DCOM—Microsoft CAs)

   For a CA of type DCOM, toggle Use Explicit Credentials to enable this option. The Use Explicit Credentials option allows you to configure specific credentials that will be used to make requests to the CA for management tasks and enrollment. This is generally used for Microsoft CAs where Windows integrated authentication is not supported. Integrated authentication is generally supported for Microsoft CAs, Keyfactor CA gateways, or Keyfactor CA management gateways on servers joined to the local Active Directory forest in which Keyfactor Command is installed and any Active Directory forests in a two-way trust with this forest. CAs configured using the CA Connector Client default to using the account under with the CA Connector Client service is running unless you enable this option.

   If you enable Use Explicit Credentials, enter a User in the format DOMAIN\username for a service account user in the forest in which the CA resides or, for non-domain-joined machines, a local machine account on the machine on which the CA is installed. Click the Set Explicit Password button and in the Set Explicit Password dialog, choose from No Value, Load from Keyfactor Secrets or Load From PAM Provider.

   A Keyfactor secret is a user-defined password or other information that is encrypted and stored securely in the Keyfactor Command database. Although Keyfactor recommends using Privileged Access Management (see Privileged Access Management (PAM)) as a more secure solution to secure information, Keyfactor Secret is an option for customers that do not already have a relationship with a PAM provider such as CyberArk or Delinea.

   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.

   Select the Load From Keyfactor Secrets radio button as the Secret Source if you want Keyfactor Command to encrypt and store the password in the Keyfactor Command database. Enter and confirm a password.

   Select the Load from PAM Provider radio button as the Secret Source if you want to store the password in a supported third-party PAM solution (see Privileged Access Management (PAM)). The remaining fields on the dialog will vary depending on the PAM provider. For example:

   CyberArk

   Select your CyberArk provider in the Providers dropdown if your PAM provider is CyberArk (see Adding or Modifying a PAM Provider). The remaining fields in the dialog will then be:

   • Safe—The name of the safe the credential resides in.
   • Object—The name of the username or password object in the safe.
   • Folder—The path and name of the folder that stores the object (e.g. Root or Root\MyDir).

   Delinea

   Select your Delinea provider in the Providers dropdown if your PAM provider is Delinea (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

   • Secret Server Secret ID—The numeric ID of the secret to retrieve from Secret Server.
   • Secret Field Name—The name of the field to use when retrieving a secret form Secret Server.

   Hashicorp

   Select your Hashicorp Vault provider in the Providers dropdown if your PAM provider is Hashicorp Vault (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

   • KV Secret Key—The key of the secret to retrieve from the Hashicorp Vault.
   • KV Secret Name—The name of the secret to retrieve from the Hashicorp Vault.

   This service account user needs appropriate permissions in the CA security settings to accomplish the tasks you plan to carry out for this CA through the Management Portal. For example:

   • Certificate enrollment
   • Certificate revocation
   • Certificate key recovery
   • Certificate request approval and denial

   These tasks will be carried out on the CA in the context of the credentials you provide here. Access control for these tasks is controlled with Keyfactor Command security (see Security Roles and Claims) and the Restrict Allowed Requesters option, (see ).

   Note:  When this option is configured, enrollment and other tasks (e.g. revocation) are done in the context of the user configured here, not the user making the request in Keyfactor Command. This overrides the existing AD security policy used by Keyfactor Command.

   Note:  Once you have established explicit credentials to a forest for a CA, the forest will be included in the forest dropdown on the Import Templates dialog (see Certificate Templates).

   Tip:  The Use Explicit Credentials option is not needed if you are accessing your CA using a Keyfactor Universal Orchestrator. Enrollment is not supported when accessing a CA using an orchestrator, so the Restrict Allowed Requesters option is not relevant for this type of CA configuration.

   The Use Explicit Credentials option is not used for EJBCA CAs.

   

   Figure 240: Certificate Authority Authentication Methods Tab for a DCOM CA

   Authentication Certificate or Token (HTTPS—EJBCA CAs)

   You may choose to authenticate Keyfactor Command to your EJBCA using either a client certificate or an OAuth token. To configure authentication for your HTTPS CAs:

   1. In the Auth Method dropdown, select either Client Certificate or OAuth. The remaining fields will vary depending on the selection you make here.

      Note:  Enforce Unique DN must be set to disabled and Create new End Entity when renewing or reissuing certificates must be set to enabled (see Details Section) if OAuth is selected as the Auth Method.

   2. If you selected Client Certificate, click the Select Authentication Certificate button to upload a client certificate in PKCS#12 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. format used to provide authentication to the EJBCA CA. This certificate is used to authenticate to the EJBCA database for synchronization, enrollment and management of certificates.

      

      Figure 241: Certificate Authority Authentication Methods Tab for an HTTPS-EJBCA CA Using Client Certificate Authentication

   3. If you selected OAuth, enter the following information:

      • Client Id

        The client you created in your OAuth identity provider to authenticate to your EJBCA instance. If you’re using Keyfactor Identity Provider, see Service Accounts for help creating a client account.

      • Token URL

        Set this to the URL of the token endpoint An endpoint is a URL that enables the API to gain access to resources on a server. for your OAuth identity provider. For example:

        https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token

      • Client Secret

        The secret of the client you created in your OAuth identity provider to authenticate to your EJBCA instance. Click the Set/Update Client Secret button and in the Client Secret dialog, choose from Load from Keyfactor Secrets or Load From PAM Provider.

        A Keyfactor secret is a user-defined password or other information that is encrypted and stored securely in the Keyfactor Command database. Although Keyfactor recommends using Privileged Access Management (see Privileged Access Management (PAM)) as a more secure solution to secure information, Keyfactor Secret is an option for customers that do not already have a relationship with a PAM provider such as CyberArk or Delinea.

        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.

        Select the Load From Keyfactor Secrets radio button as the Secret Source if you want Keyfactor Command to encrypt and store the password in the Keyfactor Command database. Enter and confirm a password.

        Select the Load from PAM Provider radio button as the Secret Source if you want to store the password in a supported third-party PAM solution (see Privileged Access Management (PAM)). The remaining fields on the dialog will vary depending on the PAM provider. For example:

        CyberArk

        Select your CyberArk provider in the Providers dropdown if your PAM provider is CyberArk (see Adding or Modifying a PAM Provider). The remaining fields in the dialog will then be:

        • Safe—The name of the safe the credential resides in.
        • Object—The name of the username or password object in the safe.
        • Folder—The path and name of the folder that stores the object (e.g. Root or Root\MyDir).
        Delinea

        Select your Delinea provider in the Providers dropdown if your PAM provider is Delinea (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

        • Secret Server Secret ID—The numeric ID of the secret to retrieve from Secret Server.
        • Secret Field Name—The name of the field to use when retrieving a secret form Secret Server.
        Hashicorp

        Select your Hashicorp Vault provider in the Providers dropdown if your PAM provider is Hashicorp Vault (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

        • KV Secret Key—The key of the secret to retrieve from the Hashicorp Vault.
        • KV Secret Name—The name of the secret to retrieve from the Hashicorp Vault.

      • Scope

        One or more scopes that should be included in token requests delivered to your OAuth identity provider. This is not required when using Keyfactor Identity Provider.

      • Audience

        Specify an audience value to be included in token requests delivered to your OAuth identity provider. This is not required when using Keyfactor Identity Provider.

      

      Figure 242: Certificate Authority Authentication Methods Tab for an HTTPS CA Using OAuth Authentication

   Note:  Once you have established a connection to the EJBCA CA, it will be included in the configuration tenant dropdown on the Import Templates dialog (see Certificate Templates).
   Standalone Tab (Microsoft CAs)

   To configure a standalone Microsoft CA, click the Standalone toggle to enable it.

   Click the Enforce RFC 2818 Compliance toggle to enable it to require that certificate enrollments made through the Keyfactor Command Management Portal for this CA include at least one DNS SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common.. This causes the CN 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). entered in PFX enrollment to automatically be replicated as a SAN, which the user can either change or accept. For CSR enrollment, if the CSR does not have a SAN that matches the CN, one will automatically be added to the certificate if this is set.

   

   Figure 243: Certificate Authority Standalone Tab

   Note:  This tab will be grayed out for CAs of type HTTPS.
5. Click Test and Save to add or update the CA, or click Test Connection to test the CA prior to saving (see Testing a CA Connection) for more information, including options for a failed CA test.

Testing a CA Connection

CA connections can be tested using the action buttons on the Certificate Authority dialog, Test Connection and Save and Test.

Certificate Authorities will be tested before they are saved to the database. If the CA can't be verified, an error message with an explanation of the issue will be displayed and added to the Audit Log and you will be given the option to save the configuration anyway.

• For EJBCA, the test checks that the CA name provided is valid for the given EJBCA instance. It validates the hostname, the EJBCA version (7.8.1 or greater), connectivity to the required REST and SOAP APIs enabled in the EJBCA instance (see Certificate Authorities), and the authentication certificate.

• For Microsoft, the test checks the forest, logical name, CA host, and explicit credentials by using a certutil ping.

• Remote CAs managed by an orchestrator will not have the connection tested before saving the CA. The Test Connection button will be active, but you will receive a message that the connection cannot be tested if you click it. The Save and Test button will skip the test when saving. Remote CAs managed by a CA Connector Client are tested.

To test a CA record:

1. In the Management Portal, browse to Locations > Certificate Authorities.
2. On the Certificate Authorities page, select the Certificate Authorities tab, and click Add to add a new CA, or select a row and click Edit from either the top or right-click menu to modify an existing one.

3. Follow the instructions for adding or modifying a CA (see Adding or Modifying a CA Record). Once you have entered the details you want to test, click Test Connection or Save and Test.

   1. Upon a successful test, you will receive a success notification at the bottom of the page and will be returned to the certificates authority grid.

   2. Upon a test failure, you will receive a pop-up message and an entry will also be added to the audit log. Click OK to save the CA despite the error, or click CANCEL to return to the dialog to correct any issues.

      

      Figure 244: Save Certificate Authority

Importing Trusted Forest CAs

Microsoft CA and Keyfactor CA gateway records from the Active Directory forest in which Keyfactor Command is installed and any Active Directory forests in a two-way trust with this forest may be imported using the Import option provided they are registered in Active Directory.

To import CA records:

1. In the Management Portal, browse to Locations > Certificate Authorities.
2. On the Certificate Authorities page, select the Certificate Authorities tab and click the Import action button to import local or two-way trusted forest CAs and Keyfactor CA gateways.

3. In the Import Certificate Authorities dialog, select the forest from which you want to import in the dropdown and click Import.

   

   Figure 245: Import Certificate Authorities

   Your certificate authorities and CA gateways will be retrieved from Active Directory in the selected forest and will populate the CA grid. Import once for each forest containing Microsoft CAs that you want to synchronize or use for enrollment.

   Once the records are imported, use the Edit option (see Adding or Modifying a CA Record) to configure synchronization and other optional settings for the CA.

   Tip:  This step does not typically need to be completed for the forest in which Keyfactor Command is installed because those records are imported during the installation process for domain-joined servers unless you have added a new CA or CA gateway following Keyfactor Command installation.
   Note:  Keyfactor CA gateways are not supported in any configuration other than in the same forest in which Keyfactor Command is installed.
   Note:  The import option only works for Microsoft CAs or Keyfactor CA gateways that have been registered in Active Directory. Non-domain-joined servers will not have any options available in this dropdown.

Deleting a CA Record

To delete a CA record:

1. In the Management Portal, browse to Locations > Certificate Authorities.
2. On the Certificate Authorities page, select the Certificate Authorities tab, select a row, and click Delete from either the top or right-click menu.
3. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

A CA cannot be deleted if:

• It has scanning tasks enabled.
• It has certificates associated with it in the Keyfactor Command database.
• It is the last CA for its Configuration Tenant and there are certificate templates (see Certificate Templates) for that Configuration Tenant in Keyfactor Command.

The two types of monitoring that Keyfactor Command offers for certificate authorities are configured on the Alert Recipients tab of the Certificate Authorities page at Locations > Certificate Authorities. Monitoring is not supported for CAs accessed with the Keyfactor Universal Orchestrator.

Certificate Authority Health Monitoring

Enable certificate authority health monitoring to receive email alerts when one or more of your CAs is not responding. Only CAs configured for synchronization will be monitored for health. To enable health monitoring, configure one or more recipients to receive the email messages and configure a health check schedule. You can choose to schedule the health checks either for daily at a specified time or at intervals of anywhere from every one minute to every 12 hours.

Certificate Authority Threshold Alerts

Enable threshold alerting to receive email alerts when a CA issues more or fewer certificates or experiences more failures or denials than configured for monitoring on the CA. Setting threshold monitoring is a two-step process:

1. Configure monitoring on the advanced tab (see Advanced Tab) for each CA.
2. Set the email recipients for the alerts on the alert recipients tab of the certificate authorities page.

CA connectors allow organizations to make connections to Keyfactor Command from certificate authorities that are remote from their instance of Keyfactor Command. Remote can mean just in an untrusted forest or can mean on an entirely different network. It is often used by organizations with managed instances of Keyfactor Command to connect to their on-premises CAs. The CA Connectors tab is used to manage connector record instances of the CA Connector Client software installed in the remote environment.

Before adding a connector record on this tab, be sure that the information on the Task Queue Connection tab has been populated. This is typically populated during installation, but must be complete before proceeding.

To create a new CA connector record or modify an existing one:

1. In the Management Portal, browse to Locations > Certificate Authorities.
2. On the Certificate Authorities page, select the CA Connectors tab, and click Add to add a new CA connector, or select a row and click Edit from either the top or right-click menu to modify an existing one.
3. In the Add/Edit New CA Connector dialog, enter a Name for the connector. This name must match the name that the CA Connector Client server will use to connect to Keyfactor Command. If you use the -Name (Windows) or --name (Linux) parameter A parameter or argument is a value that is passed into a function in an application. when installing the CA Connector Client, you can specify this value. If you do not specify this value, the CA Connector Client uses the results from a hostname lookup for the server's name. The Name field cannot be modified on an edit.
4. Enter a CA Connector Pool Name. Pools are used to group multiple remote CA connectors together to perform tasks on the same CA or set of CAs. A pool may only contain remote CA connectors of one type—DCOM or HTTPS.
5. In the CA Type dropdown, select the correct type for your connector. DCOM is used for Microsoft CAs. HTTPS is used for EJBCA CAs.

6. Select a Claim Type in the dropdown. Supported options are:

   • OAuth Subject—An open authorization 2.0 user claim.
   • OAuth Object Id—An open authorization 2.0 claim of a type not covered by client, role or subject.
   • OAuth Role—An open authorization 2.0 group claim.
   • OAuth Client Id—An open authorization 2.0 client application claim.
7. In the Claim Value field, enter the OAuth claim value that the CA Connector Client will use to authenticate to Keyfactor Command based on the Claim Type you selected.

8. Select the OAuth Provider from the dropdown that will provide your claim. This list is populated with your configured identity providers.

   Tip:  If you're using Keyfactor Identity Provider and you are using a Subject (sub) claim, you can find the value to enter in this field as follows:

   1. In the Keyfactor Identity Provider Administration Console, browse to Clients under the correct Realm (e.g. Keyfactor) to locate the client you created for use with the CA Connector Client.

   2. Open the client for editing, and on the Service accounts roles tab look for an informational message that says:

      To manage detail and group mappings, click on the username

      Followed by a link related to your client name. For example, if your client name is MyCAConnector, the link would be service-account-MyCAConnector. Click the link. This will open a user page.

   3. The GUID in the ID field of the user details for the service-account-YourClientName is the sub claim. This is the value you would enter as the Claim Value field.

9. Click to toggle the Enabled option to off, if desired. The default is on.

   

   Figure 247: Add New CA Connector

To delete a CA connector record:

1. In the Management Portal, browse to Locations > Certificate Authorities.
2. On the Certificate Authorities page, select the CA Connectors tab, select a row, and click Delete from either the top or right-click menu.
3. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

A CA connector cannot be deleted if it is the last one in its pool and the pool is configured for use by at least one CA.

On the Task Queue Connection tab, you enter information to provide Keyfactor Command with the necessary information to acquire a token for and then communicate with your instance of RabbitMQ. This information is generally configured during your initial Keyfactor Command configuration, but it may be configured or modified here.

To configure or modify the task queue connection information:

1. In the Login Type dropdown, select either Basic (username and password) or OAuth. The remaining fields will vary depending on the selection you make here.

2. In the Task Queue URL, enter the amqp or amqps URL to the RabbitMQ instance. For example:

   amqps://appsrvr12.keyexample.com

   Keyfactor strongly recommends that if you choose the Basic option, you connect to RabbitMQ over a secure channel (amqps).

3. If you selected Basic, enter a Username and Password valid for authentication to the RabbitMQ instance.

4. If you selected OAuth, enter the following information:

   • Client Id

     The client you created in your OAuth identity provider to authenticate to your RabbitMQ instance. If you’re using Keyfactor Identity Provider, see Service Accounts for help creating a client account.

   • Token URL

     Set this to the URL of the token endpoint for your OAuth identity provider. For example:

     https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token

   • Client Secret

     The secret of the client you created in your OAuth identity provider to authenticate to your RabbitMQ instance. Click the Set/Update Client Secret button and in the Client Secret dialog, choose from Load from Keyfactor Secrets or Load From PAM Provider.

     A Keyfactor secret is a user-defined password or other information that is encrypted and stored securely in the Keyfactor Command database. Although Keyfactor recommends using Privileged Access Management (see Privileged Access Management (PAM)) as a more secure solution to secure information, Keyfactor Secret is an option for customers that do not already have a relationship with a PAM provider such as CyberArk or Delinea.

     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.

     Select the Load From Keyfactor Secrets radio button as the Secret Source if you want Keyfactor Command to encrypt and store the password in the Keyfactor Command database. Enter and confirm a password.

     Select the Load from PAM Provider radio button as the Secret Source if you want to store the password in a supported third-party PAM solution (see Privileged Access Management (PAM)). The remaining fields on the dialog will vary depending on the PAM provider. For example:

     CyberArk

     Select your CyberArk provider in the Providers dropdown if your PAM provider is CyberArk (see Adding or Modifying a PAM Provider). The remaining fields in the dialog will then be:

     • Safe—The name of the safe the credential resides in.
     • Object—The name of the username or password object in the safe.
     • Folder—The path and name of the folder that stores the object (e.g. Root or Root\MyDir).
     Delinea

     Select your Delinea provider in the Providers dropdown if your PAM provider is Delinea (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

     • Secret Server Secret ID—The numeric ID of the secret to retrieve from Secret Server.
     • Secret Field Name—The name of the field to use when retrieving a secret form Secret Server.
     Hashicorp

     Select your Hashicorp Vault provider in the Providers dropdown if your PAM provider is Hashicorp Vault (see Adding or Modifying a PAM Provider). The remaining field in the dialog will then be:

     • KV Secret Key—The key of the secret to retrieve from the Hashicorp Vault.
     • KV Secret Name—The name of the secret to retrieve from the Hashicorp Vault.

   • Scope

     One or more scopes that should be included in token requests delivered to your OAuth identity provider. This is not required when using Keyfactor Identity Provider.

   • Audience

     Specify an audience value to be included in token requests delivered to your OAuth identity provider. This is not required when using Keyfactor Identity Provider.

     

     Figure 249: CA Basic Task Queue Connection

     

     Figure 250: CA OAuthTask Queue Connection

5. Click Save to save any changes. Click Test to validate that the entered information can be used to make a connection to RabbitMQ.