Documentation Suite v24.4

Submit Search

POST Enrollment PFX Deploy

The POST /Enrollment 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)./PFX A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers./Deploy method is used to put a certificate into a certificate store. It is intended to be used immediately after using the POST /Enrollment/PFX method to enroll for a PFX using the Store value for the x-certificateformat header (see POST Enrollment PFX) or the POST /Enrollment/Renew method to renew a certificate already in a certificate store. This method returns HTTP 200 OK on a success with a message body containing the failed and succeeded stores.

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

/certificate_stores/schedule/

/certificates/enrollment/pfx/

/certificate_stores/schedule/#/ (where # is a reference to a specific certificate store container ID)

/certificates/enrollment/pfx/

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.

Tip: The POST /Enrollment/PFX/Deploy method must be used within 5 minutes of acquiring a certificate with the POST /Enrollment/PFX or POST /Enrollment/Renew method as the same user who executed the certificate request. After 5 minutes, the temporary staging data needed in order to deploy the certificate is automatically cleared and is no longer available for deployment.

Table 433: POST Enrollment PFX Deploy Input Parameters

Name Type Description

Stores

Body

Required^*. An array of objects indicating the certificate stores to which the certificate should be deployed with additional properties as needed based on the store type and whether an existing certificate is being overwritten with the new certificate. Show store details.

Name	Description
StoreId	A string indicating the GUID of the certificate store(s) to which the certificate should be deployed. Use the GET /CertificateStores method (see GET Certificate Stores) with a query of “Approved -eq true” to retrieve a list of all your approved certificate stores to determine the GUID(s) of the store(s).
Alias	A string indicating the alias of the certificate upon entry into the store. The format of and requirement for this varies depending on the certificate store type and whether the Overwrite flag is selected. See PFX Enrollment in the Keyfactor Command Reference Guide for more information.
Overwrite	A Boolean that sets whether a certificate in the store with the Alias provided should be overwritten with the new certificate (true) or not (false). The default is false. Use the GET /Certificates/Locations/{id} method (see GET Certificates Locations ID) to retrieve a list of the locations an existing certificate is in to determine the alias used for the certificate in the certificate store.
Properties	An object containing the unique parameters defined for the certificate store type that need to be populated for the certificate. 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 the certificate in the certificate store. For example, for NetScaler, the key name that is optionally used to associate the 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: Copy `"Properties": { "NetscalerVserver":"MyVirtualServerName" }` Note: The only built-in certificate store type that makes use of properties that can be set on a certificate-by-certificate basis in the store is NetScaler. You may have custom certificate store types that make use of this functionality.

This replaces the StoresIDs and StoreTypes parameters as of Keyfactor Command version 9.4.

Password Body Required^*. A string with a password used to secure the certificate in the certificate store. This field is required for store types that require an entry password, such as PEM stores.

CertificateId

Body

Required^*. The integer for the certificate that needs to be deployed. This is returned in the response to the POST /Enrollment/PFX or POST /Enrollment/Renew request as the KeyfactorId.

Note: For enrollments that do not require manager approval (where the certificate is issued immediately), the CertificateId is required. The RequestId may be provided but is not required in this case. For enrollments that do require manager approval (where the certificate is not issued immediately), only the KeyfactorRequestId will be returned on the enrollment and the RequestId is required for deployment.

RequestId

Body

Required^*. The integer of the request ID for the certificate that needs to be deployed. This is returned in the response to the POST /Enrollment/PFX or POST /Enrollment/Renew request as the KeyfactorRequestId.

See the note under CertificateId regarding when this field is required and when it is not.

JobTime Body A string containing the date and time when the certificate should be deployed. The date and time should be given using the ISO 8601 UTC time format YYYY-MM-DDTHH:mm:ss.000Z (e.g. 2023-11-19T16:23:01Z). Dates in the past will cause a management job to be created to run immediately. Dates in the future will result in a management job set to run in the future. The default is to create a management job that runs immediately.

StoreIds

Body

An array of strings containing the certificate store GUIDs for the stores to which the certificate should be added.

The StoreIds parameter is obsolete as of Keyfactor Command version 9.4 and has been replaced by the Stores parameter. It is still supported for backward compatibility, but no longer required.

StoreTypes

Body

An array of objects indicating the store types used with additional properties as needed based on the store type and whether an existing certificate is being overwritten with the new certificate.

The StoreTypes parameter is obsolete as of Keyfactor Command version 9.4 and has been replaced by the Stores parameter. It is still supported for backward compatibility, but is no longer required.

Show store type details.

Name

Description

StoreTypeId

An integer indicating the type of certificate store the certificate is being deployed to. Show store type ID details.

Value	Description
0	Java Keystore
2	PEM File
3	F5 SSL Profiles
4	IIS Roots
5	NetScaler
6	IIS Personal
7	F5 Web Server
8	IIS Revoked
9	F5 Web Server REST
10	F5 SSL Profiles REST
11	F5 CA Bundles REST
100	Amazon Web Services
101	File Transfer Protocol
1xx	User-defined certificate stores will be given a type ID over 101.

Alias A string indicating the alias of the certificate upon entry into the store. The format of and requirement for this varies depending on the certificate store type and whether the Overwrite flag is selected. See PFX Enrollment in the Keyfactor Command Reference Guide for more information.

Overwrite

A Boolean that sets whether a certificate in the store with the Alias provided should be overwritten with the new certificate (true) or not (false). The default is false.

Use the GET /Certificates/Locations/{id} method (see GET Certificates Locations ID) to retrieve a list of the locations an existing certificate is in to determine the alias used for the certificate in the certificate store.

Properties

An array of objects with the unique parameters defined for the certificate store type that need to be populated for the certificate. 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 the certificate in the certificate store. For example, for NetScaler, the key name that is optionally used to associate the 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:

Copy

"Properties": [
   {
      "NetscalerVserver":"MyVirtualServerName"
   }
]

Note: The only built-in certificate store type that makes use of properties that can be set on a certificate-by-certificate basis in the store is NetScaler. You may have custom certificate store types that make use of this functionality.

Table 434: POST Enrollment PFX Deploy Response Data

Name	Description
SuccessfulStores	An array of strings containing the GUIDs for the certificates stores for which management jobs to deploy the certificate were successfully created. Note: Successful creation of a management job to deploy a certificate to a certificate store does not necessarily mean that a certificate will successfully be deployed to the store. A management job may fail for any number of reasons (e.g. permissions on the store). Use the GET /Certificates/{id} method with includeLocations=true to confirm that the certificate has successfully been deployed to the target store(s). The locations won't appear in the certificate record until after a certificate store inventory has been completed for each store.
FailedStores	An array of strings containing the GUIDs for the certificates stores for which management jobs to deploy the certificate could not be created.

Name

Description

SuccessfulStores

An array of strings containing the GUIDs for the certificates stores for which management jobs to deploy the certificate were successfully created.

Note: Successful creation of a management job to deploy a certificate to a certificate store does not necessarily mean that a certificate will successfully be deployed to the store. A management job may fail for any number of reasons (e.g. permissions on the store). Use the GET /Certificates/{id} method with includeLocations=true to confirm that the certificate has successfully been deployed to the target store(s). The locations won't appear in the certificate record until after a certificate store inventory has been completed for each store.

FailedStores

An array of strings containing the GUIDs for the certificates stores for which management jobs to deploy the certificate could not be created.

Tip: See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor API

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 workflow

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.

Version v24.4

On this page: