POST Enrollment PFX Deploy

Documentation Suite v10.3

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 Overview) are required to use this feature:

CertificateStoreManagement: Schedule

CertificateEnrollment: EnrollPFX

Permissions for certificate stores can be set at either the global or certificate store container level. See Container Permissions in the Keyfactor Command Reference Guide 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 338: POST Enrollment PFX Deploy Input Parameters

Name

Type

Description

Stores

Body

Required^*. An array 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	An array of GUIDs indicating 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	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 key/value pairs for 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 A parameter or argument is a value that is passed into a function in an application. 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: "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

A PEM format certificate file is a base64-encoded certificate. Since it's presented in ASCII, you can open it in any text editor. PEM certificates always begin and end with entries like ---- BEGIN CERTIFICATE---- and ----END CERTIFICATE----. PEM certificates can contain a single certificate or a full certifiate chain and may contain a private key. Usually, extensions of .cer and .crt are certificate files with no private key, .key is a separate private key file, and .pem is both a certificate and private key. 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

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. 2021-05-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 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 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

The type of certificate store the certificate is being deployed to. Show store type ID details.

Alias

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 key/value pairs for 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:

"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 339: POST Enrollment PFX Deploy Response Data

Name	Description
SuccessfulStores	An array of 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 GUIDs for the certificates stores for which management jobs to deploy the certificate could not be created.

Name

Description

SuccessfulStores

An array of 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 GUIDs for the certificates stores for which management jobs to deploy the certificate could not be created.

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.

POST Enrollment PFX Deploy

Products

Solutions

Resources

Company