PUT Certificate Authority

The PUT /CertificateAuthority method is used to update 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. record in Keyfactor Command. This method returns HTTP 200 OK on a success with details 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. configuration.

Tip:  The following permissions (see Security Overview) are required to use this feature:

PkiManagement: Modify

Warning:  Any previously populated fields that are not submitted with their full existing data using this method will be cleared of their existing data. When using this method, you should first do a GET to retrieve all the values for the record you want to update, enter corrected data into the field(s) you want to update, and then submit all the fields using PUT, including the fields that contain values but which you are not changing.

Table 231: PUT Certificate Authority Input Parameters

Name In Description
Id Body Required. An integer indicating the Keyfactor Command identifier for the certificate authority. The ID is automatically assigned by Keyfactor Command.
LogicalName Body Required. A string indicating the 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). of the certificate authority.
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). Body Required. A string indicating the DNSClosed The Domain Name System is a service that translates names into IP addresses. hostname (for DCOM configurations) or URL (for HTTPS configurations) of the certificate authority (e.g. myca.keyexample.com or https://myca.keyexample.com).
Delegate Body

A Boolean that sets whether management interactions with the certificate authority via Keyfactor Command should be done in the context of the user making the request (true). If set to false, these interactions are done in the context of the service account under which the Keyfactor Command application pool is running unless ExplicitCredentials is true.

Important:  Delegation is only supported with Microsoft CAs and has limitations. Be sure to read more about delegation in Adding or Modifying a CA Record in the Keyfactor Command Reference Guide before setting this option to true.
DelegateEnrollment Body

A Boolean that sets whether 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). to the certificate authority via Keyfactor Command should be done in the context of the user making the request (true). If set to false, enrollment is done in the context of the service account under which the Keyfactor Command application pool is running unless ExplicitCredentials is true.

Important:  Delegation is only supported with Microsoft CAs and has limitations. Be sure to read more about delegation in Adding or Modifying a CA Record in the Keyfactor Command Reference Guide before setting this option to true.
ForestRoot Body A string indicating the 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. root name or DNS domain name for the certificate authority (e.g. keyexample.com).
Note:  This field is retained for legacy purposes and will auto-populate with the value provided in the ConfigurationTenant field.
ConfigurationTenant Body

Required. A string indicating the forest root name or DNS domain name for the certificate authority (e.g. keyexample.com).

For EJBCA CAs, this is a reference ID and 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 for an EJBCA CA if you will also be configuring Microsoft CAs in the same DNS domain.
Remote Body A Boolean that sets whether communications with the certificate authority are done via a Keyfactor Windows OrchestratorClosed The Windows Orchestrator, one of Keyfactor's suite of orchestrators, is used to manage synchronization of certificate authorities in remote forests, run SSL discovery and management tasks, and interact with Windows servers as well as F5 devices, NetScaler devices, Amazon Web Services (AWS) resources, and FTP capable devices, for certificate management. In addition, the AnyAgent capability of the Windows Orchestrator allows it to be extended to create custom certificate store types and management capabilities regardless of source platform or location. configured to manage remote CAs. If set to true, a value must be provided for the Agent. The default is false.
Agent Body A string indicating the GUID of the Keyfactor Windows OrchestratorClosed Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. or Keyfactor Universal OrchestratorClosed The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with Windows servers (a.k.a. IIS certificate stores) and FTP capable devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can run custom jobs to provide certificate management capabilities on a variety of platforms and devices (e.g. F5 devices, NetScaler devices, Amazon Web Services (AWS) resources) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux. configured to manage the certificate authority (see Remote).
Standalone Body A Boolean that sets whether the certificate authority is a standalone CA (true) or not (false). If both Standalone is set to true and AllowedEnrollmentTypes is set to 1 or 3, KeyRetention may be set. The default is false.
MonitorThresholds Body A Boolean that sets whether threshold monitoring is enabled. If set to true, email alerts will be sent when certificate issuance or failures (including denials) since the last threshold alert was sent falls outside the configured limits. If this option is set to true, the following additional fields should also be set:
  • IssuanceMax
  • IssuanceMin
  • FailureMax

The DenialMax field has been deprecated and should always be zero.

Monitoring is not supported for CAs accessed with the Keyfactor Windows Orchestrator or Keyfactor Universal Orchestrator.

The default is false.

See also ThresholdCheck to configure the monitoring frequency.

Note:  For full functionality of threshold monitoring, you must also configure email recipients for threshold alerts. These are configured globally rather than on a CA-by-CA basis. See Certificate Authority Monitoring in the Keyfactor Command Reference Guide for more information.
IssuanceMax Body An integer that sets the maximum number of certificates that can be issued in the period between scheduled threshold monitoring alert emails before an alert is triggered. If more certificates than this are issued in the period, a notification will be included in the threshold monitoring email. This value is unset by default.
IssuanceMin Body An integer that sets the minimum number of certificates that should be issued in the period between scheduled threshold monitoring alert emails before an alert is triggered. If fewer certificates than this are issued in the period, a notification will be included in the threshold monitoring email. This value is unset by default.
FailureMax Body An integer that sets the maximum number of certificate requests that can fail or be denied in the period between scheduled threshold monitoring alert emails before an alert is triggered. If more certificate requests than this fail in the period, a notification will be included in the threshold monitoring email. This value is unset by default.
RFCEnforcement Body

A Boolean that sets whether certificate enrollments made through Keyfactor Command for this CA must include at least one DNS SANClosed 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. (true) or not (false). In the Keyfactor Command Management Portal, this causes the 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). entered in PFXClosed 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. enrollment to automatically be replicated as a SAN, which the user can either change or accept. For 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, if the CSR does not have a SAN that matches the CN, one will automatically be added to the certificate if this is set.

The default is false.

Tip:  The RFCEnforcement option at the CA level is used only for standalone CAs. RFC enforcement for enterprise CAs is configured on a templateClosed A certificate template defines the policies and rules that a CA uses when a request for a certificate is received.-by-template basis (see PUT Templates).
Properties Body Required. Additional properties about the certificate authority. This field is used to store the configuration for the Sync External Certificates option. This option allows 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. The setting is referenced using the following format:
{\"syncExternal\":true} OR {\"syncExternal\":false}
AllowedEnrollmentTypes Body

An integer that sets the type(s) of enrollment that are allowed through Keyfactor Command for the certificate authority. ClosedShow allowed enrollment types.

This value is unset by default.
KeyRetention Body

An integer that sets the type of key retention to enable for the certificate authority, if any. ClosedShow key retention values.

Values of 2 and 3 require setting KeyRetentionDays.

This value is unset by default.

Tip:  The KeyRetention option at the CA level is used only for standalone CAs. Key retention for enterprise CAs is configured on a template-by-template basis (see PUT Templates).

KeyRetention on a CA may only be set to a value other than zero if both Standalone is set to true and AllowedEnrollmentTypes is set to 1 or 3. Some level of 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 must be configured when using PFX enrollment with a standalone CA. See Adding or Modifying a CA Record in the Keyfactor Command Reference Guide for more information.
KeyRetentionDays Body An integer indicating the number of days for which to retain the private keys for certificates issued by this certificate authority before scheduling them for deletion. This value is unset by default.
ExplicitCredentials Body A Boolean that sets whether explicit credentials are enabled for this certificate authority (true) or not (false). Set this to true for CAs that do not support integrated authentication or are not configured for integrated authentication and enter credentials in the ExplicitUser and ExplicitPassword fields. This option is only supported for Microsoft CAs. The default is false.
Tip:  This option is set to true primarily for Microsoft CAs where 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.
SubscriberTerms Body A Boolean that sets whether to add a checkbox on the enrollment pages to force users to agree to a custom set of terms before enrolling (true) or not (false). The default is false.
Tip:  Configure a link to the custom terms using the URL to Subscriber Terms application setting. See Application Settings: Enrollment Tab in the Keyfactor Command Reference Guide for more information.
ExplicitUser Body A string indicating the username, in the format DOMAIN\username, for a service account user in the forest in which the Microsoft CA resides or, for non-domain-joined machines, local machine account credentials on the machine on which the CA is installed when ExplicitCredentials is set to true.
Tip:  This service account user needs appropriate permissions in the Microsoft CA security settings to accomplish the tasks you plan to carry out for this CA through Keyfactor Command. 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 on CAs is controlled with Keyfactor Command security (see Security Roles and Identities in the Keyfactor Command Reference Guide) and the AllowedRequesters option.
Note:  When the ExplicitCredentials option is configured, enrollment and other tasks (e.g. revocation) is 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.
ExplicitPassword Body A string containing the password for the ExplicitUser.
UseAllowedRequesters Body

A Boolean that sets whether the allowed requesters option is enabled (true) or not (false). See also AllowedRequesters. The default is false.

Tip:  This option is supported for all CAs, but it must be used for Microsoft CAs where integrated authentication is not supported and EJBCA CAs. 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.
Tip:  For CAs in a two-way trust you don't usually need to enable UseAllowedRequesters 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 in the Keyfactor Command Reference Guide and see PUT Templates).
AllowedRequesters Body

An array of Keyfactor Command security roles that are allowed to enroll for certificates via Keyfactor Command for this CA. For example:

"AllowedRequesters": [
   "Power Users",
   "Read Only"
]

The 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 is used for EJBCA CAs and Microsoft CAs where 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.

In addition to granting permissions at the CA level, you need to enable the UseAllowedRequesters option to grant permissions on a template-by-template basis (see PUT Templates).

The values set here are only considered if UseAllowedRequesters is set to true.

FullScan Body

The schedule for the full synchronization of this certificate authority. ClosedShow schedule details.

For example:

"FullScan": {
   "Daily": {
      "Time": "2022-05-27T17:30:00Z"
   }
}

Or:

"FullScan": {
   "Weekly": {
      "Days": [
         "Monday",
         "Wednesday",
         "Friday"
      ],
      "Time": "2022-05-27T17:30:00Z"
   }
}
Tip:  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.
IncrementalScan Body

The schedule for the incremental synchronization of this certificate authority. ClosedShow schedule details.
ThresholdCheck Body

The schedule for threshold monitoring checks on this certificate authority (see MonitorThresholds). ClosedShow schedule details.
CAType Body

An integer indicating the type of CA:

  • 0—DCOM
  • 1—HTTPS
AuthCertificatePassword Body

An array indicating the password for the certificate to use to authenticate to the EJBCA CA.

Supported methods to store certificate and associated password information are:

  • Store the credential information in the Keyfactor secrets table.

    A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the Keyfactor Command database.

  • Load the credential information from a PAM provider.

    See Privileged Access Management (PAM) in the Keyfactor Command Reference Guide and PAM Providers for more information.

Value Description
SecretValue

A string containing the password used to security the EJBCA CA client authentication certificate.
Parameters An array indicating the parameters to supply for PAM authentication. These will vary depending on the PAM provider.
Provider

A string indicating the ID of the PAM provider.

Use the GET /PamProviders method (see GET PAM Providers) to retrieve a list of all the PAM providers to determine the ID.

For example, the password stored as a Keyfactor secret will look like:

{
   "SecretValue": "MySuperSecretPassword"
}

The password stored as a CyberArk PAM secret will look like (where the Provider value—1 in this example—is the Id value from GET PAM Providers and the Folder and Object reference the folder name and object name in the CyberArk safe):

{
   "Provider": "1",
   "Parameters":{
      "Folder":"MyFolderName",
      "Object":"MyEJBCAClientAuthPassword"
   }
}

The password stored as a Delinea PAM secret will look like (where the Provider value—1 in this example—is the Id value from GET PAM Providers and the SecretId is the ID if the secret created in the Delinea secret server for this purpose):

{
   "Provider": "1",
   "Parameters":{
      "SecretId":"MyEJBCAPasswordId"
   }
}

Due to its sensitive nature, this value is not returned in responses.
AuthCertificate Body

An array containing information about the client certificate 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.

The syntax is the same as for AuthCertificatePassword.
EnforceUniqueDN Body A Boolean that sets whether the unique 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. requirement is enforced on the CA (true) or not (false).

Checking this will cause Keyfactor Command, upon enrollment, to search the EJBCA CA for end entities with DNs that match the 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.

This setting applies to HTTPS CAs only.
LastScan Body A string indicating the date, in UTC, on which a synchronization was last performed for the CA.

Table 232: PUT Certificate Authority Response Data

Name Description
Id An integer indicating the Keyfactor Command identifier for the certificate authority. The ID is automatically assigned by Keyfactor Command.
LogicalName A string indicating the logical name of the certificate authority.
HostName A string indicating the DNS hostname (for DCOM configurations) or URL (for HTTPS configurations) of the certificate authority (e.g. myca.keyexample.com or https://myca.keyexample.com).
Delegate

A Boolean that sets whether management interactions with the certificate authority via Keyfactor Command should be done in the context of the user making the request (true). If set to false, these interactions are done in the context of the service account under which the Keyfactor Command application pool is running unless ExplicitCredentials is true.

Important:  Delegation is only supported with Microsoft CAs and has limitations. Be sure to read more about delegation in Adding or Modifying a CA Record in the Keyfactor Command Reference Guide before setting this option to true.
DelegateEnrollment

A Boolean that sets whether enrollment to the certificate authority via Keyfactor Command should be done in the context of the user making the request (true). If set to false, enrollment is done in the context of the service account under which the Keyfactor Command application pool is running unless ExplicitCredentials is true.

Important:  Delegation is only supported with Microsoft CAs and has limitations. Be sure to read more about delegation in Adding or Modifying a CA Record in the Keyfactor Command Reference Guide before setting this option to true.
ForestRoot A string indicating the forest root name or DNS domain name for the certificate authority (e.g. keyexample.com).
Note:  This field is retained for legacy purposes and will auto-populate with the value provided in the ConfigurationTenant field.
ConfigurationTenant

A string indicating the forest root name or DNS domain name for the certificate authority (e.g. keyexample.com).

For EJBCA CAs, this is a reference ID and 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 for an EJBCA CA if you will also be configuring Microsoft CAs in the same DNS domain.
Remote A Boolean that sets whether communications with the certificate authority are done via a Keyfactor Windows Orchestrator configured to manage remote CAs. If set to true, a value must be provided for the Agent. The default is false.
Agent A string indicating the GUID of the Keyfactor Windows Orchestrator or Keyfactor Universal Orchestrator configured to manage the certificate authority (see Remote).
Standalone A Boolean that sets whether the certificate authority is a standalone CA (true) or not (false). If both Standalone is set to true and AllowedEnrollmentTypes is set to 1 or 3, KeyRetention may be set. The default is false.
MonitorThresholds A Boolean that sets whether threshold monitoring is enabled. If set to true, email alerts will be sent when certificate issuance or failures (including denials) since the last threshold alert was sent falls outside the configured limits. If this option is set to true, the following additional fields should also be set:
  • IssuanceMax
  • IssuanceMin
  • FailureMax

The DenialMax field has been deprecated and should always be zero.

Monitoring is not supported for CAs accessed with the Keyfactor Windows Orchestrator or Keyfactor Universal Orchestrator.

The default is false.

See also ThresholdCheck to configure the monitoring frequency.

Note:  For full functionality of threshold monitoring, you must also configure email recipients for threshold alerts. These are configured globally rather than on a CA-by-CA basis. See Certificate Authority Monitoring in the Keyfactor Command Reference Guide for more information.
IssuanceMax An integer that sets the maximum number of certificates that can be issued in the period between scheduled threshold monitoring alert emails before an alert is triggered. If more certificates than this are issued in the period, a notification will be included in the threshold monitoring email. This value is unset by default.
IssuanceMin An integer that sets the minimum number of certificates that should be issued in the period between scheduled threshold monitoring alert emails before an alert is triggered. If fewer certificates than this are issued in the period, a notification will be included in the threshold monitoring email. This value is unset by default.
FailureMax An integer that sets the maximum number of certificate requests that can fail or be denied in the period between scheduled threshold monitoring alert emails before an alert is triggered. If more certificate requests than this fail in the period, a notification will be included in the threshold monitoring email. This value is unset by default.
RFCEnforcement

A Boolean that sets whether certificate enrollments made through Keyfactor Command for this CA must include at least one DNS SAN (true) or not (false). In the Keyfactor Command Management Portal, this causes the CN 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.

The default is false.

Tip:  The RFCEnforcement option at the CA level is used only for standalone CAs. RFC enforcement for enterprise CAs is configured on a template-by-template basis (see PUT Templates).
Properties Additional properties about the certificate authority. This field is used to store the configuration for the Sync External Certificates option. This option allows 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. The setting is referenced using the following format:
{\"syncExternal\":true} OR {\"syncExternal\":false}
AllowedEnrollmentTypes

An integer that sets the type(s) of enrollment that are allowed through Keyfactor Command for the certificate authority. ClosedShow allowed enrollment types.

This value is unset by default.
KeyRetention

An integer that sets the type of key retention to enable for the certificate authority, if any. ClosedShow key retention values.

Values of 2 and 3 require setting KeyRetentionDays.

This value is unset by default.

Tip:  The KeyRetention option at the CA level is used only for standalone CAs. Key retention for enterprise CAs is configured on a template-by-template basis (see PUT Templates).

KeyRetention on a CA may only be set to a value other than zero if both Standalone is set to true and AllowedEnrollmentTypes is set to 1 or 3. Some level of private key retention must be configured when using PFX enrollment with a standalone CA. See Adding or Modifying a CA Record in the Keyfactor Command Reference Guide for more information.
KeyRetentionDays An integer indicating the number of days for which to retain the private keys for certificates issued by this certificate authority before scheduling them for deletion. This value is unset by default.
ExplicitCredentials A Boolean that sets whether explicit credentials are enabled for this certificate authority (true) or not (false). Set this to true for CAs that do not support integrated authentication or are not configured for integrated authentication and enter credentials in the ExplicitUser and ExplicitPassword fields. This option is only supported for Microsoft CAs. The default is false.
Tip:  This option is set to true primarily for Microsoft CAs where 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.
SubscriberTerms A Boolean that sets whether to add a checkbox on the enrollment pages to force users to agree to a custom set of terms before enrolling (true) or not (false). The default is false.
Tip:  Configure a link to the custom terms using the URL to Subscriber Terms application setting. See Application Settings: Enrollment Tab in the Keyfactor Command Reference Guide for more information.
ExplicitUser A string indicating the username, in the format DOMAIN\username, for a service account user in the forest in which the Microsoft CA resides or, for non-domain-joined machines, local machine account credentials on the machine on which the CA is installed when ExplicitCredentials is set to true.
Tip:  This service account user needs appropriate permissions in the Microsoft CA security settings to accomplish the tasks you plan to carry out for this CA through Keyfactor Command. 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 on CAs is controlled with Keyfactor Command security (see Security Roles and Identities in the Keyfactor Command Reference Guide) and the AllowedRequesters option.
Note:  When the ExplicitCredentials option is configured, enrollment and other tasks (e.g. revocation) is 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.
ExplicitPassword A string containing the password for the ExplicitUser.
UseAllowedRequesters

A Boolean that sets whether the allowed requesters option is enabled (true) or not (false). See also AllowedRequesters. The default is false.

Tip:  This option is supported for all CAs, but it must be used for Microsoft CAs where integrated authentication is not supported and EJBCA CAs. 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.
Tip:  For CAs in a two-way trust you don't usually need to enable UseAllowedRequesters 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 in the Keyfactor Command Reference Guide and see PUT Templates).
AllowedRequesters

An array of Keyfactor Command security roles that are allowed to enroll for certificates via Keyfactor Command for this CA. For example:

"AllowedRequesters": [
   "Power Users",
   "Read Only"
]

The 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 is used for EJBCA CAs and Microsoft CAs where 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.

In addition to granting permissions at the CA level, you need to enable the UseAllowedRequesters option to grant permissions on a template-by-template basis (see PUT Templates).

The values set here are only considered if UseAllowedRequesters is set to true.

FullScan

The schedule for the full synchronization of this certificate authority. ClosedShow schedule details.

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

The schedule for the incremental synchronization of this certificate authority. ClosedShow schedule details.
ThresholdCheck

The schedule for threshold monitoring checks on this certificate authority (see MonitorThresholds). ClosedShow schedule details.
CAType

An integer indicating the type of CA:

  • 0—DCOM
  • 1—HTTPS
AuthCertificatePassword

An array indicating the password for the certificate to use to authenticate to the EJBCA CA.

Supported methods to store certificate and associated password information are:

  • Store the credential information in the Keyfactor secrets table.

    A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the Keyfactor Command database.

  • Load the credential information from a PAM provider.

    See Privileged Access Management (PAM) in the Keyfactor Command Reference Guide and PAM Providers for more information.

Value Description
SecretValue

A string containing the password used to security the EJBCA CA client authentication certificate.
Parameters An array indicating the parameters to supply for PAM authentication. These will vary depending on the PAM provider.
Provider

A string indicating the ID of the PAM provider.

Use the GET /PamProviders method (see GET PAM Providers) to retrieve a list of all the PAM providers to determine the ID.

Due to its sensitive nature, this value is not returned in responses.
AuthCertificate

An array containing information about the client certificate 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.

ClosedShow authentication certificate values.

EnforceUniqueDN A Boolean that sets whether the unique DN requirement is enforced on the CA (true) or not (false).

Checking this will cause Keyfactor Command, upon enrollment, to search the EJBCA CA for end entities with DNs that match the 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.

This setting applies to HTTPS CAs only.
LastScan A string indicating the date, in UTC, on which a synchronization was last performed for the CA.
Tip:  For code examples, see the Keyfactor API Endpoint Utility. To find the embedded web copy of this utility, click the help icon () at the top of the Keyfactor Command Management Portal page next to the Log Out button.