GET Certificate Authority

The GET /CertificateAuthority operation retrieves a list of certificate authorities defined in Keyfactor Command. Query parameters support filtering using defined criteria, control over pagination by specifying the page number and return limit, and customization of sorting based on specified fields and order. On success, the operation returns HTTP 200 OK with  details for all the defined certificate authorities.

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

/certificate_authorities/read/

Table 336: GET Certificate Authority Input Parameters

Name In Description
QueryString Query

A string containing a query to limit the results (for example, field1 -eq value1 AND field2 -gt value2). The default is to return all records. For querying guidelines, refer to: Using Search in the Management Portal. The query fields supported for this operation are:

  • Agent
  • ConfigurationTenant
  • ForestRoot
  • HostName
  • Id
  • LogicalName
PageReturned Query An integer that specifies how many multiples of the returnLimit to skip and offset by before returning results, to enable paging. The default is 1.
ReturnLimit Query An integer that specifies how many results to return per page. The default is 50. Very large values can result in long processing time.
SortField Query

A string containing the property by which the results should be sorted. Fields available for sorting through the API include:

  • Agent

  • ConfigurationTenant

  • ForestRoot

  • HostName

  • Id

  • LogicalName

Available sort fields are affected by the query provided in QueryString. The default sort field is Id.
SortAscending Query An integer that sets the sort order on the returned results. A value of 0 sorts results in ascending order while a value of 1 sorts results in descending order. The default is ascending.

Table 337: GET 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 types 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 One-Click Renewal on certificates in this CA (True or False).

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

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 False). The default is True.

Important:  If a certificate with a stored private key is deleted and later restored, the stored private key will not be restored.

The certificate cleanup task runs daily at 1:00 UTC and removes expired certificates from the database. Once removed, these certificates are not re-imported during a standard CA synchronization unless certificate cleanup is later turned off. CA synchronization tasks use the certificate cleanup settings to determine whether a certificate is eligible for cleanup and whether to exclude such certificates from import.

For more information, see Certificate Cleanup.

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 that do not have an associated template (for example, certificates issued by a standalone CA), system-wide cleanup settings are applied, even if the issuing CA is defined in Keyfactor Command.

    Because these certificates are imported without reliable issuer-to-CA mapping information, Keyfactor Command cannot consistently associate them with a specific configured CA. As a result, CA-level cleanup settings are not evaluated for those certificates.

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 (for example, keyexample.com).

For HTTPS CAs, this is a reference ID and does not need to be the DNS domain name. The short host name 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 Add or Modify 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 Add or Modify 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 False).

Turning on Enforce Unique DN 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 turn on this option in Keyfactor Command, it must also be turned on for 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 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 (for example, 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 (for example, 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.

Schedules created through the Keyfactor API using interval values that cannot be represented in the Management Portal (for example, every 107 minutes) are not supported. These schedules cannot be displayed in the Management Portal schedule picker.

Existing schedules that use unsupported intervals (created in versions of Keyfactor Command before this was enforced) can still be parsed and used, but cannot be edited and re-saved. Attempting to re-save these schedules may result in errors.

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 host name (for DCOM configurations) or URL (for HTTPS configurations) of the certificate authority (for example, 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.

Schedules created through the Keyfactor API using interval values that cannot be represented in the Management Portal (for example, every 107 minutes) are not supported. These schedules cannot be displayed in the Management Portal schedule picker.

Existing schedules that use unsupported intervals (created in versions of Keyfactor Command before this was enforced) can still be parsed and used, but cannot be edited and re-saved. Attempting to re-save these schedules may result in errors.

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 Add or Modify 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 containing an escaped JSON object of additional certificate authority properties. This field stores configuration for options such as Sync External Certificates, which allows foreign certificates imported into a Microsoft CA to be synchronized to Keyfactor Command along with certificates issued by the CA.

For example:

{\"syncExternal\":true}
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 indicates whether RFC 2818 compliance enforcement is turned on (True or False). When this option is set to True, certificate enrollments made through Keyfactor Command for this CA must include at least one DNS SAN.

In the Keyfactor Command Management Portal, this causes the following behavior:

  • PFX Enrollment: The CN entered in PFX enrollment is automatically replicated as a DNS SAN, which the user does not see and cannot change.

  • CSR Enrollment: If the CSR does not have a SAN that matches the CN, one will automatically be added to the certificate. The user enrolling does not see this and cannot change it.

  • CSR Generation: The CN entered will be automatically replicated as a DNS SAN and set to read only.

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 False). If Standalone is 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 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 Enrollment > General > 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 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 False). The default is False.
Tip:  See 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. Reference and Utility, which allows you to call API operations and view results. It is primarily intended 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, and also serves as an interactive supplement to this API documentation. You can access it from the help menu () in the Management Portal.