POST Certificate Authority Test

The POST /CertificateAuthority/Test method is used to validate that a connection can be made to the certificate authorityClosed A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. with the provided information. This method returns HTTP 200 OK on a success with details for the success or failure of 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. validation.

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

/certificate_authorities/read/

Table 276: POST Certificate Authority Test Input Parameters

Name In Description
id Body Required. An integer indicating the CA id in the Keyfactor database.
CAType Body

An integer indicating the type of CA:

  • 0—DCOM

    Use this option for Microsoft CAs and CA gateways.

  • 1—HTTPS

    Use this option for EJBCA CAs.

The default is 0.
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.
ExplicitPassword Body

A string containing either null, or the password for the ExplicitUser, including: SecretValue, parameters, and provider if applicable.

Copy 
 xml:space="preserve">"ExplicitePassword": {
"secretValue": "string",
"parameters": {
  "additionalProp1": "string",
  "additionalProp2": "string",
  "additionalProp3": "string"
},
"provider": 0
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.
AuthCertificate Body

Required*. An object indicating the PKCS#12 client certificate to use to authenticate to the CA using the following format. This certificate is used to authenticate to the CA database for synchronization, enrollment and management of certificates. The certificate is provided in the following format:

Copy 
"AuthCertificate": {
"secretValue": "string",
"parameters": {
   "IssuedDN": "CN=superadmincert",
   "IssuerDN": "CN=CorpIssuingCA1, DC=keyexample, DC=com",
   "Thumbprint": "913D80B33517DD6F42428664883DA43BB64D0EEE",
   "ExpirationDate": "2025-07-17T18:24:23Z"
     },
"provider": 0                                

This parameter is required for EJBCA CAs.
AuthCertificatePassword Body

Required*. An object containing password for the client certificate used to provide authentication to the CA.

Copy 
"authCertificatePassword": {
"secretValue": "string",
"parameters": {
  "additionalProp1": "string",
  "additionalProp2": "string",
  "additionalProp3": "string"
},
"provider": 0

This parameter is required for EJBCA CAs.
LogicalName Body Required. A string indicating the logical name of the certificate authority.
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).
ConfigurationTenant Body

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

This parameter is required for Microsoft CAs.
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.

Table 277: POST Certificate Authority Test Response Data

Name Description
Success A Boolean that indicates whether the CA could successfully be reached (True) or not (False).
Message A string indicating a message about the validation test of the certificate authority.
Tip:  See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor APIClosed 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 the context of Keyfactor Command, it refers to the workflow builder, which allows you automate event-driven tasks when a certificate is requested or revoked. 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.