POST Certificate Stores Reenrollment

The POST /CertificateStores/Reenrollment method is used to schedule an existing certificate store for reenrollment and for ODKG requests.

Important:  The endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. has been updated to include optional fields for SANs, metadataClosed Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates., owner role, and additional enrollmentClosed Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). fields. To fully support this functionality, Keyfactor Universal OrchestratorClosed The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with servers and devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can provide certificate management capabilities on a variety of platforms and devices (e.g. Amazon Web Services (AWS) resources, Citrix\NetScaler devices, F5 devices, IIS stores, JKS keystores, PEM stores, and PKCS#12 stores) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux servers or Linux containers. be updated to version 25.1 or later.

This endpoint returns 204 with no content upon success. Use the GET /OrchestratorJobs/JobHistory method to check on the progress of the job after submission (see GET Orchestrator Jobs Job History).

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:
/certificates/enrollment/csr/
/certificate_stores/modify/
OR
/certificates/enrollment/csr/
/certificate_stores/modify/#/ (where # is a reference to a specific certificate store container ID)

Permissions for certificate stores can be set at either the global or certificate store container level. See Container Permissions for more information about global vs container permissions.

In addition, either the user scheduling the ODKG job or the user configured to provide authentication to 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. (see HTTPS CAs - Authentication Method Tab or DCOM CAs - Authentication Method Tab) must have enrollment permissions configured on the CA and enrollment pattern.

Table 400: POST Certificates Stores Reenrollment Input Parameters

Name In Description
KeystoreId Body

Required. The GUID of the certificate store to schedule for reenrollment.

Use the GET /CertificateStores method (see GET Certificate Stores) to retrieve a list of your certificate stores to determine the GUID of the store.
SubjectName Body

Required. A string containing the reenrollment subject name using X.500 format. For example:

"SubjectName": "CN=websrvr14.keyexample.com,OU=IT,O=\"Key Example, Inc.\",L=Independence,ST=OH,C=US"
AgentGuid Body

Required. The GUID of the orchestrator that is registered with the certificate store.

Use the GET /CertificateStores method (see GET Certificate Stores) to retrieve a list of your certificate stores to determine the GUID of the orchestrator associated with the store.
Alias Body

Required. The alias of the certificate in the certificate store.
JobProperties Body An object indicating the unique parameters defined for the certificate store type. The key is the name of the specific parameter from the certificate store type definition as returned in the JobProperties on the store type using the GET CertificateStoreTypes method and the value is the value that should be set for that parameter on a certificate in the certificate store. For example, for NetScaler, the key name that is optionally used to associate a certificate with a virtual server is NetscalerVserver and is returned by GET CertificateStoreTypes like so:
"JobProperties": [ "NetscalerVserver" ]

It can be seen in the Keyfactor Command Management Portal when editing the certificate store type in the field for Management Job Custom Fields.

The setting is referenced using the following format:

"JobProperties": [ {"NetscalerVserver":"MyVirtualServerName"} ]
Note:  The only built-in certificate store type that makes use of job properties that can be set on a certificate-by-certificate basis in the store is NetScaler, which does not support reenrollment. You may have custom certificate store types that make use of this functionality.
CertificateAuthority Body A string indicating the certificate authority to which to direct the enrollment request. If this parameter is not provided, the value set in the Certificate Authority For Submitted CSRs application setting will be used (see Application Settings: Agents Tab).
CertificateTemplate Body

A string indicating the certificate template to use for the enrollment request.

Note:  This parameter is considered deprecated and may be removed in a future release.
Enrollment Pattern Id Body

An integer indicating the enrollment pattern to use for the enrollment request. If this value is not provided, the default enrollment pattern defined for the template provided in the request (see the CertificateTemplate parameter) will be used.

If neither the CertificateTemplate nor the EnrollmentPatternId is provided, the value set in the Template For Submitted CSRs application setting will be used (see Application Settings: Agents Tab. If both the CertificateTemplate and EnrollmentPatternId are provided, the settings from the enrollment pattern take precedence. If both are specified, the enrollment will fail if the Template does not match the one defined by the specified enrollment pattern.

SANs Body

An object that contains the elements for Keyfactor Command to use when generating the subject alternative name (SAN) for the certificate requested by the CSR, each of which is supplied as an array of strings. ClosedShow SAN key values.

For example:

Copy 
"SANs": {
   "dns": [
      "dnssan1.keyexample.com",
      "dnssan2.keyexample.com",
      "dnssan3.keyexample.com"
   ],
   "ip": [
      "192.168.2.73"
   ]
}
Additional Enrollment Fields Body An object that provide values for any custom enrollment fields set on the enrollment pattern for the certificate template to supply custom request attributes to the CA during the enrollment process. The additionalPropx is the used-defined field name and the string is the value for the field. For example:
Copy
"AdditionalEnrollmentFields": {
   "CustomStringOne": "MyValue",
   "CustomMultiChoiceOne": "ValueTwo"
}

See Enrollment Pattern Operations for more information.
Metadata Body

An object that set the values for the metadata fields that will be associated with the certificate once it is in Keyfactor Command. The additionalPropx is the field name and the string is the value for the field. For example:

Copy 
"Metadata": {
   "AppOwnerFirstName": "William",  // This is a String field.
   "AppOwnerLastName": "Smith",
   "AppOwnerEmailAddress": "william.smith@keyexample.com",
   "BusinessCritical": "true",      // This is a Boolean field.
   "BusinessUnit": "E-Business",    // This is a Multiple Choice field with a pre-defined value.
   "Notes": "Here are some notes.", // This is a BigText field.
   "SiteCode": 3,                   // This is an integer field.
   "TicketResolutionDate": "2021-07-23"   // This is a Date field in yyyy-mm-dd format.
}

See Certificate Metadata for more information.

Note:  Required metatdata fields will not be validated. An error will not be thrown if no value is entered in a required metadata field.
Owner Role Id Body

An integer indicating the Keyfactor Command reference ID of the security role assigned as the certificate owner.

Note:  To assign a certificate owner, one of OwnerRoleId or OwnerRoleName is required, not both. A certificate owner is required if the certificate template or system-wide settings Certificate Owner Role policy has been configured as Required.
Owner Role Name Body

A string containing the name of the security role assigned as the certificate owner. This name must match the existing name of the security role.

Note:  To assign a certificate owner, one of OwnerRoleId or OwnerRoleName is required, not both. A certificate owner is required if the certificate template or system-wide settings Certificate Owner Role policy has been configured as Required.
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.