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 Roles and Claims) are required to use this feature:

/certificate_authorities/modify/

Important:  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 319: PUT Certificate Authority Input Parameters

Name In Description
Agent Body A string indicating the GUID of the Keyfactor Universal Orchestrator configured to manage the certificate authority (see Remote).
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 0 by default.

This option is supported only for standalone CAs.
AllowedRequesters Body

An array of strings indicating Keyfactor Command security roles that are allowed to enroll for certificates via Keyfactor Command for this CA.

For example:

Copy 
"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 option is supported only for standalone CAs.

The values set here are only considered if UseAllowedRequesters is set to true.
AllowOneClickRenewals Body A Boolean that sets whether the CA will allow (true) One-Click Renewal on certificates in this CA or not (false).

To use One-Click Renewal for certificates, the Allow One-Click Renewals option must be enabled in both the certificate templates and CAs to which you want One-Click Renewal to apply (see Certificate Template Operations, HTTPS CAs - Advanced Tab or DCOM CAs - Advanced Tab ). For more information about one-click renewals, see Renew.

Audience Body For HTTPS CAs, this is a string specifying the audience to include in token requests to the identity provider when OAuth authentication is selected.
AuthCertificate Body

An object containing information about the client certificate used to provide authentication to the HTTPS CA. This certificate is used to authenticate to the CA for synchronization, enrollment and management of certificates.

The certificate and associated password information are stored 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.

For example:

Copy 
{
   "SecretValue": "MIACAQMwgAYJKoZIhvcNAQcBoIAkgASCA+[truncated for display]gQUwRndGMbmlkmwIOuC0MbOY1EyDpACAwGQAAAA"
}

The SecretValue is a string containing the base-64-encoded representation of the certificate with private key (in PKCS#12 format) that will be used to authenticate to the HTTPS CA.

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

An object indicating the password for the certificate (see AuthCertificate) to use to authenticate to the HTTPS CA.

The certificate and associated password information are stored 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.

For example:

Copy 
{
   "SecretValue": "MySuperSecretPassword"
}

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

An integer indicating the type of CA:

  • 0—DCOM
  • 1—HTTPS
CertificateCleanupEnabled Body

A Boolean indicating whether the certificate cleanup job is enabled for the CA (true) or not (false). The default is true.

The certificate cleanup task periodically removes expired certificates from the database. Once removed, these certificates will not be re-imported during a standard CA synchronization unless certificate cleanup is later disabled. CA synchronization tasks use the certificate cleanup settings to determine whether a certificate is eligible for cleanup and exclude such certificates from import.

Certificate cleanup settings can be configured at three levels:

  • Certificate Template Record: If configured, overrides the system-wide settings when processing certificate cleanup tasks for certificates associated with this template. These cleanup tasks are processed first.

  • Certificate Authority (CA) Record: If configured, overrides the system-wide settings when processing certificate cleanup tasks for certificates associated with this CA but not associated with any template. These cleanup tasks are processed second.

  • System-Wide: Applies to all certificate authorities and templates in the system. These values are used when processing certificate cleanup tasks for certificates associated with neither a CA nor a template and when no overrides are set at the CA or template level. These cleanup tasks are processed last.

    Note:  For manually imported certificates without an associated template (e.g., from a standalone CA), system-wide cleanup settings will be applied even if the CA exists in Keyfactor Command. This occurs because Keyfactor Command cannot reliably associate such certificates with the correct CA.
Important:  If a certificate with a stored private key is deleted and later restored, the stored private key will not be restored.
Note:  The system-wide settings for certificate cleanup are configured in application settings (see Application Settings: Console Tab).
ClientId Body For HTTPS CAs, this is a string specifying the client ID used to authenticate to the CA when OAuth authentication is selected.
ClientSecret Body

For HTTPS CAs, this is an object indicating the secret for the client used to authenticate to the HTTPS CA when OAuth authentication is selected.

Supported methods to store secret information are:

  • Store the secret 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 secret from a Keyfactor Command local or supported third-party PAM solution.

    See Privileged Access Management (PAM) and PAM Providers for more information.

ClosedShow authentication certificate password values and examples.

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

Copy 
 {
   "SecretValue": "MySuperSecretPassword"
}

The password stored as a local Keyfactor Command PAM secret will look like (where the Provider value—1 in this example—is the Id value from GET PAM Providers and the SecretName is the name defined for the secret):

Copy 
{
   "Provider": "1",
   "Parameters":{
      "SecretName":"Keycloak5443-EJBCA4"
   }
}

The password stored as a CyberArk PAM secret will look like (where the Provider value—2 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):

Copy 
{
   "Provider": "2",
   "Parameters":{
      "Folder":"MyFolderName",
      "Object":"MyEJBCAOAuthSecret"
   }
}

The password stored as a Delinea PAM secret will look like (where the Provider value—3 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):

Copy 
{
   "Provider": "3",
   "Parameters":{
      "SecretId":"MyEJBCAOAuthSecretId"
   }
}

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

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

For HTTPS CAs, this is a reference ID and does not need to be the DNS domain name. The short hostname of the HTTPS 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.
ConnectorPool Body

A string indicating the name of the connector pool to use when using the CA Connector Client to connect to the CA.

Use the GET /CertificateAuthority/CAConnectors method (see GET Certificate Authority CA Connectors) to retrieve a list of all the defined CA connector pools.
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 Management Portal and Keyfactor API application pools are 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 DCOM CA before setting this option to true.
DelegateEnrollment Body

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 Management Portal and Keyfactor API application pools are 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 DCOM CA before setting this option to true.
DeleteWithArchiveKey Body A Boolean that sets whether certificates with a private key stored in the system are eligible for removal by the certificate cleanup task.
EnforceUniqueDN Body A Boolean that sets whether the unique DN requirement is enforced on the CA (true) or not (false).

Enabling 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.
ExplicitCredentials Body A Boolean that sets whether explicit credentials are enabled for this certificate authority (true) or not (false). 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.
ExplicitPassword Body

An object indicating the password information to use for authentication along with the ExplicitUser if ExplicitCredentials is true.

Supported methods to store secret information are:

  • Store the secret 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 secret from a Keyfactor Command local or supported third-party PAM solution.

    See Privileged Access Management (PAM) and PAM Providers for more information.

ClosedShow password values and examples.

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

Copy 
 {
   "SecretValue": "MySuperSecretPassword"
}

The password stored as a local Keyfactor Command PAM secret will look like (where the Provider value—1 in this example—is the Id value from GET PAM Providers and the SecretName is the name defined for the secret):

Copy 
{
   "Provider": "1",
   "Parameters":{
      "SecretName":"Keycloak5443-User5"
   }
}

The password stored as a CyberArk PAM secret will look like (where the Provider value—2 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):

Copy 
{
   "Provider": "2",
   "Parameters":{
      "Folder":"MyFolderName",
      "Object":"MyUserFivePassword"
   }
}

The password stored as a Delinea PAM secret will look like (where the Provider value—3 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):

Copy 
{
   "Provider": "3",
   "Parameters":{
      "SecretId":"MyUser5PasswordId"
   }
}

Due to its sensitive nature, this value is not returned in responses.
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 Claims) 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.
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.
ForceSave Query A Boolean indicating whether to save the certificate authority record to the database even if the CA test fails (true) or not (false).
ForestRoot Body

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.
FullScan Body

An object indicating the schedule for the full synchronization of this certificate authority.

Prior to Command v11, it was possible to create a Keyfactor schedule via the API that was impossible to display via the Management Portal schedule picker. For example, an interval that is not on the interval dropdown (e.g., every 107 minutes). Now, the API will also not allow interval values to be saved that cannot be represented in the Management Portal. Previously saved schedules that don't meet these restrictions can still be parsed and used, but not edited and re-saved, as a result errors may be encountered on re-saving invalid schedules that were created via the API.

ClosedShow schedule details.

For example:

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

Or:

Copy 
"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.
HostName Body Required. 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).
Id Body Required. An integer indicating the Keyfactor Command identifier for the certificate authority. The ID is automatically assigned by Keyfactor Command.
IncrementalScan Body

An object indicating the schedule for the incremental synchronization of this certificate authority.

Prior to Command v11, it was possible to create a Keyfactor schedule via the API that was impossible to display via the Management Portal schedule picker. For example, an interval that is not on the interval dropdown (e.g., every 107 minutes). Now, the API will also not allow interval values to be saved that cannot be represented in the Management Portal. Previously saved schedules that don't meet these restrictions can still be parsed and used, but not edited and re-saved, as a result errors may be encountered on re-saving invalid schedules that were created via the API.

ClosedShow schedule details.
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.
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 key retention must be configured when using PFX enrollment with a standalone CA. See Adding or Modifying a DCOM CA 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.
LastScan Body A string indicating the date, in UTC, on which a synchronization was last performed for the CA.
LogicalName Body Required. A string indicating the logical name of the certificate authority.
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 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 Alert Recipients Tab for more information.
New EndEntity OnRenew And Reissue Body

A Boolean that sets whether a renewal and reissue requests against an EJBCA CA will create a new end entity for the new certificate (true) or attempt to associate the new certificate with the existing end entity (false). The default is false.

This value must be set to true for CA records created for the Keyfactor AnyCA Gateway REST to allow renewal and reissue enrollments to succeed.
Properties Body A string indicating 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}
Remote Body A Boolean that sets whether communications with the certificate authority are done via a Keyfactor Universal Orchestrator configured to manage remote CAs. If set to true, a value must be provided for the Agent. The default is false.
RFCEnforcement Body

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 at the enrollment pattern level (see POST Enrollment Patterns).
Scope Body For HTTPS CAs, this is a string indicating any scopes that should be included in token requests to the identity provider when OAuth authentication is selected. If multiple scopes are desired, they should be separated by spaces.
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.
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.

Note:  The subscriber terms setting does not apply to enrollments done through the Keyfactor API.
Tip:  Configure a link to the custom terms using the URL to Subscriber Terms application setting. See Application Settings: Enrollment Tab for more information.
ThresholdCheck Body

An object indicating the schedule for threshold monitoring checks on this certificate authority (see MonitorThresholds). ClosedShow schedule details.
TimeAfterExpiration Body The amount of time after certificate expiration to wait until the certificate is eligible for removal by the certificate cleanup task.
TimeAfterExpirationUnits Body The time unit to apply to the certificate expiration time (TimeAfterExpiration). Options are days, weeks, or months.
TokenURL Body For HTTPS CAs, this is a string indicating the bearer token URL. This is the URL of the token endpoint for your identity provider instance.
UseAllowedRequesters Body

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

This option is supported only for standalone CAs.
UseCAConnector Body A Boolean that sets whether communications with the certificate authority are done via a CA Connector Client. If set to true, a value must be provided for the ConnectorPool. The default is false.
UseForEnrollment Body A Boolean that sets whether the CA is available for enrollment within Keyfactor Command (true) or not (false). The default is false.

Table 320: PUT Certificate Authority Response Data

Name Description
Agent A string indicating the GUID of the Keyfactor Universal Orchestrator configured to manage the certificate authority (see Remote).
AgentName A string indicating the reference name of the Keyfactor Universal Orchestrator configured to manage the certificate authority (see Remote).
AgentUserName A string indicating the name of the service account user the Keyfactor Universal Orchestrator uses to connect to Keyfactor Command (see Remote).
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 0 by default.

This option is supported only for standalone CAs.
AllowedRequesters

An array of strings indicating Keyfactor Command security roles that are allowed to enroll for certificates via Keyfactor Command for this CA.

For example:

Copy 
"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 option is supported only for standalone CAs.

The values set here are only considered if UseAllowedRequesters is set to true.
AllowOneClickRenewals A Boolean that sets whether the CA will allow (true) One-Click Renewal on certificates in this CA or not (false).

To use One-Click Renewal for certificates, the Allow One-Click Renewals option must be enabled in both the certificate templates and CAs to which you want One-Click Renewal to apply (see Certificate Template Operations, HTTPS CAs - Advanced Tab or DCOM CAs - Advanced Tab ). For more information about one-click renewals, see Renew.

Audience For HTTPS CAs, this is a string specifying the audience to include in token requests to the identity provider when OAuth authentication is selected.
AuthCertificate

An object containing information about the client certificate used to provide authentication to the HTTPS CA. This certificate is used to authenticate to the CA for synchronization, enrollment and management of certificates.

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

ClosedShow authentication certificate values.

AuthCertificatePassword

An object indicating the password for the certificate (see AuthCertificate) to use to authenticate to the HTTPS CA.

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

An integer indicating the type of CA:

  • 0—DCOM
  • 1—HTTPS
CertificateCleanupEnabled

A Boolean indicating whether the certificate cleanup job is enabled for the CA (true) or not (false). The default is true.

The certificate cleanup task periodically removes expired certificates from the database. Once removed, these certificates will not be re-imported during a standard CA synchronization unless certificate cleanup is later disabled. CA synchronization tasks use the certificate cleanup settings to determine whether a certificate is eligible for cleanup and exclude such certificates from import.

Certificate cleanup settings can be configured at three levels:

  • Certificate Template Record: If configured, overrides the system-wide settings when processing certificate cleanup tasks for certificates associated with this template. These cleanup tasks are processed first.

  • Certificate Authority (CA) Record: If configured, overrides the system-wide settings when processing certificate cleanup tasks for certificates associated with this CA but not associated with any template. These cleanup tasks are processed second.

  • System-Wide: Applies to all certificate authorities and templates in the system. These values are used when processing certificate cleanup tasks for certificates associated with neither a CA nor a template and when no overrides are set at the CA or template level. These cleanup tasks are processed last.

    Note:  For manually imported certificates without an associated template (e.g., from a standalone CA), system-wide cleanup settings will be applied even if the CA exists in Keyfactor Command. This occurs because Keyfactor Command cannot reliably associate such certificates with the correct CA.
Important:  If a certificate with a stored private key is deleted and later restored, the stored private key will not be restored.
Note:  The system-wide settings for certificate cleanup are configured in application settings (see Application Settings: Console Tab).
ClientId For HTTPS CAs, this is a string specifying the client ID used to authenticate to the CA when OAuth authentication is selected.
ClientSecret

For HTTPS CAs, this is an object indicating the secret for the client used to authenticate to the HTTPS CA when OAuth authentication is selected.

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

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

For HTTPS CAs, this is a reference ID and does not need to be the DNS domain name. The short hostname of the HTTPS 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.
ConnectorPool

A string indicating the name of the connector pool to use when using the CA Connector Client to connect to the CA.
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 Management Portal and Keyfactor API application pools are 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 DCOM CA 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 Management Portal and Keyfactor API application pools are 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 DCOM CA before setting this option to true.
DeleteWithArchiveKey A Boolean that sets whether certificates with a private key stored in the system are eligible for removal by the certificate cleanup task.
DenialMax This is considered deprecated and may be removed in a future release.
EnforceUniqueDN A Boolean that sets whether the unique DN requirement is enforced on the CA (true) or not (false).

Enabling 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.
ExplicitCredentials A Boolean that sets whether explicit credentials are enabled for this certificate authority (true) or not (false). 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.
ExplicitPassword

An object indicating the password information to use for authentication along with the ExplicitUser if ExplicitCredentials is true.

Due to its sensitive nature, this value is not returned in responses.
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 Claims) 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.
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.
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.
FullScan

An object indicating the schedule for the full synchronization of this certificate authority.

Prior to Command v11, it was possible to create a Keyfactor schedule via the API that was impossible to display via the Management Portal schedule picker. For example, an interval that is not on the interval dropdown (e.g., every 107 minutes). Now, the API will also not allow interval values to be saved that cannot be represented in the Management Portal. Previously saved schedules that don't meet these restrictions can still be parsed and used, but not edited and re-saved, as a result errors may be encountered on re-saving invalid schedules that were created via the API.

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.
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).
Id Required. An integer indicating the Keyfactor Command identifier for the certificate authority. The ID is automatically assigned by Keyfactor Command.
IncrementalScan

An object indicating the schedule for the incremental synchronization of this certificate authority.

Prior to Command v11, it was possible to create a Keyfactor schedule via the API that was impossible to display via the Management Portal schedule picker. For example, an interval that is not on the interval dropdown (e.g., every 107 minutes). Now, the API will also not allow interval values to be saved that cannot be represented in the Management Portal. Previously saved schedules that don't meet these restrictions can still be parsed and used, but not edited and re-saved, as a result errors may be encountered on re-saving invalid schedules that were created via the API.

ClosedShow schedule details.
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.
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 DCOM CA 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.
LastScan A string indicating the date, in UTC, on which a synchronization was last performed for the CA.
LogicalName A string indicating the logical name of the certificate authority.
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 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 Alert Recipients Tab for more information.
New EndEntity OnRenew And Reissue

A Boolean that sets whether a renewal and reissue requests against an EJBCA CA will create a new end entity for the new certificate (true) or attempt to associate the new certificate with the existing end entity (false). The default is false.

This value must be set to true for CA records created for the Keyfactor AnyCA Gateway REST to allow renewal and reissue enrollments to succeed.
Properties A string indicating 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}
Remote A Boolean that sets whether communications with the certificate authority are done via a Keyfactor Universal Orchestrator configured to manage remote CAs. If set to true, a value must be provided for the Agent. The default is false.
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 at the enrollment pattern level (see POST Enrollment Patterns).
Scope For HTTPS CAs, this is a string indicating any scopes that should be included in token requests to the identity provider when OAuth authentication is selected. If multiple scopes are desired, they should be separated by spaces.
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.
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.

Note:  The subscriber terms setting does not apply to enrollments done through the Keyfactor API.
Tip:  Configure a link to the custom terms using the URL to Subscriber Terms application setting. See Application Settings: Enrollment Tab for more information.
ThresholdCheck

An object indicating the schedule for threshold monitoring checks on this certificate authority (see MonitorThresholds). ClosedShow schedule details.
TimeAfterExpiration The amount of time after certificate expiration to wait until the certificate is eligible for removal by the certificate cleanup task.
TimeAfterExpirationUnits The time unit to apply to the certificate expiration time (TimeAfterExpiration). Options are days, weeks, or months.
TokenURL For HTTPS CAs, this is a string indicating the bearer token URL. This is the URL of the token endpoint for your identity provider instance.
UseAllowedRequesters

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

This option is supported only for standalone CAs.
UseCAConnector A Boolean that sets whether communications with the certificate authority are done via a CA Connector Client. If set to true, a value must be provided for the ConnectorPool. The default is false.
UseForEnrollment A Boolean that sets whether the CA is available for enrollment within Keyfactor Command (true) or not (false). The default is false.
Tip:  See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. endpoints can be called and results returned. It is intended to be used primarily for validation, testing and workflowClosed A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. development. It also serves secondarily as documentation for the API. The link to the Keyfactor API Reference and Utility is in the dropdown from the help icon () at the top of the Management Portal page next to the Log Out button.