Certificate Authority Tab - HTTPS CAs

If you have EJBCA CAs, you will need to manually configure 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. records for them.

 

When adding or editing your CAs, the connection can be tested prior to saving.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Certificate Authorities > Read
Certificate Authorities > Modify

Important:  In order for CAs to successfully synchronize to the Keyfactor Command database and perform other functions (e.g. 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).), the service account under which Keyfactor Command is making the request to the CA must be granted appropriate permission to the CA database as per Grant the Keyfactor Command Users and Service Account(s) Permissions on the 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 HTTPS as the CA communication protocol in the Select CA Communication Protocol dropdown.

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

    Details Section

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

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

      Toggling this to enable it will cause Keyfactor Command, upon enrollment, to search the EJBCA CA for end entities with DNs that match the 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. 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 243: Enforce Unique DN Setting on the EJBCA CA

      The value of the Keyfactor CommandEnforce 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.

      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.
    Scan Section
    Tip:  If you plan to use the certificate owner functionality, you may wish to configure a default certificate owner on one or more certificate templates or at the system-wide settings policy level (see Configuring System-Wide Settings and Policies Tab) before doing any CA synchronizations to assure that certificate owner information is associated with certificates synchronized into Keyfactor Command. Certificates already in Keyfactor Command are not updated on subsequent synchronizations.

    In the Scan section, choose when to schedule Closedfull 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.

      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 244: 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 245: EJBCA Certificate Profile Backdated Revocation

    Figure 246: Certificate Authority Basic Tab for an EJBCA CA

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

    Details Section

    In the Details section, click the Use CA Connector toggle to enable this functionality and choose the appropriate CA Connector Client in the dropdown.

    The CA Connector Pool dropdown shows the CA connector pools defined on the CA Connectors tab (see CA Connectors Tab) of the type matching the CA being configured .

    Note:  The CA Connector Pool dropdown is only active if the Use CA Connector toggle is enabled.

    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 Installing the CA Connector Client. In addition, the CA Connector 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. must be installed on a Keyfactor Command server and the Task Queue Connection (see Task Queue Connection) and CA Connector (see CA Connectors Tab) information must be fully configured in Keyfactor Command.

    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.
    Note:  In order to perform enrollment through Keyfactor Command, the account making the request to the CA must be granted appropriate enroll permissions on the CA itself. Which account this is depends on the delegation and authentication configuration (see Authentication Method Tab):

    Enrollment is not supported using NTLM authentication.

    Tip:  To fully configure enrollment for the CA, you will also need to configure templates for enrollment (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 HTTPS CAs - Advanced Tab or ). For more information about one-click renewals, see Renew.

    • The Key Retention policy set at the CA level is only used for enrollments and certificate imports where no template is associated with the request. For enrollments with a certificate template, set key retention at the template level (see Certificate Template Operations).

      Note:  If private keyClosed 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 Closedretention 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.

    • Restrict Allowed Requesters is required for HTTPS CAs, thus the toggle is disabled. 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. 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.

      Figure 247: Certificate Authority Advanced Tab for HTTPS CA - Add Allowed Requester

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

      • Implementations using OAuth as an identity provider.

      • EJBCA CAs.

      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 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 collectionClosed 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). level.

    Figure 248: Certificate Authority Advanced Tab for HTTPS CA

    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. Default is 50.
    • 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. Default is 50.
    • 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, however, you must enter a number here to save the CA.

    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.

    Figure 249: Certificate Authority Monitoring Tab for HTTPS CA

    On the Authentication Methods tab, you configure how authentication to the CA from Keyfactor Command for management tasks and enrollment occurs.

    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 the Basic tab) 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#12Closed 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 250: 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 endpointClosed 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 ClosedLoad from Keyfactor Secrets or ClosedLoad From PAM Provider.

      • 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 251: 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 tenantClosed A grouping of CAs. The Microsoft concept of forests is not used in EJBCA so to accommodate the new EJBCA functionality, and to avoid confusion, the term forest needed to be renamed. The new name is configuration tenant. For EJBCA, there would be one configuration tenant per EJBCA server install. For Microsoft, there would be one per forest. Note that configuration tenants cannot be mixed, so Microsoft and EJBCA cannot exist on the same configuration tenant. dropdown on the Import Templates dialog (see Certificate Templates).
  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.
Tip:   Once a CA record has been created for your CA, go to certificate templates (see Certificate Templates) and import templates for the CA.

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

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Certificate Authorities > Read
Certificate Authorities > Modify

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.

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 an HTTPS CA). 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 252: Save Certificate Authority

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Certificate Authorities > Read
Certificate Authorities > Modify

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.