GET Certificate Authority ID

The POST /CertificateAuthority method is used to retrieve details for a specified 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.. This method returns HTTP 200 OK on a success with the details for the certificate authority.

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

PkiManagement: Read

Table 225: GET Certificate Authority {id} Input Parameters

Name In Description
id Path Required. An integer that specifies the Keyfactor Command ID of the certificate authority record to retrieve.

Table 226: GET Certificate Authority {id} 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.