POST Enrollment PFX

Documentation Suite v10.3

POST Enrollment PFX

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. method is used to enroll for a certificate by supplying data in the desired fields. This method returns HTTP 200 OK on a success with a message body containing a list of certificate details and any metadata 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 the context of Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. that was associated with the certificate request.

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

CertificateEnrollment: EnrollPFX

Global or container-level schedule permissions for certificate stores are needed to install a certificate generated with this method into a certificate store (see the x-CertificateFormat parameter A parameter or argument is a value that is passed into a function in an application.) using the POST /Enrollment/PFX/Deploy method (see POST Enrollment PFX Deploy) or POST /Enrollment/PFX/Replace method (see POST Enrollment PFX Replace).

Tip: Use the GET /Enrollment/PFX/Context/My method before this method to check which templates and CAs are available for enrollment for the requesting user before submitting the enrollment request.

Note: As of Keyfactor Command version 10, enrollment (PFX and CSR

A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA.), renewal, and revocation requests all flow through Keyfactor Command workflow

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.. This will result in no changes to the enrollment, renewal, and revocation user experience unless customizations have been added in workflow (see Workflow Definitions).

This method has two available versions. Keyfactor recommends using the newer method when possible. For more information about versioning, see Versioning.

Version 2

Version 1

Version 2 of the POST /Enrollment/PFX method redesigns how enrollment flow works to handle require approval functionality in a Keyfactor Command workflow with support for delivery into certificate stores. Users who are planning to use require approval workflow functionality and deliver enrolled certificates into certificate stores must use version 2 of this endpoint An endpoint is a URL that enables the API to gain access to resources on a server..

Note: The PopulateMissingValuesFromAD parameter has been removed from the version 2 endpoint.

Table 332: POST Enrollment PFX v2 Input Parameters

Name

Description

Stores

Body

An object containing a comma delimited set of arrays indicating the certificate stores to which the certificate should be distributed. 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	A string containing 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.

CustomFriendlyName

Body

Required^*. A string that sets a custom friendly name for the certificate.

This field is required if the Require Custom Friendly Name application setting is set to true (the default is false). See Application Settings: Enrollment Tab in the Keyfactor Command Reference Guide for more information.

Password

Body

Required. A string that sets the password used to encrypt the contents of the PFX file. The minimum password length is controlled by the Password Length application setting. The default is 12. See Application Settings: Enrollment Tab in the Keyfactor Command Reference Guide for more information.

Subject

Body

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

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

This field is required if the Common Name Regular Expression application setting is set to the default value of .+. See Application Settings: Enrollment Tab in the Keyfactor Command Reference Guide for more information.

IncludeChain

Body

A Boolean that sets whether to include the certificate chain in the response (true) or not (false). The default is true.

RenewalCertificateId

Body

An integer that sets the ID of the certificate to be renewed when the method is called on a certificate renewal.

The RenewalCertificateId parameter is used in conjunction with InstallIntoExistingCertificateStores parameter to make the determination as to distribution of the certificate to certificate stores. If InstallIntoExistingCertificateStores is true, the certificate will be distributed to certificate stores that the certificate identified in RenewalCertificateId is found in.

CertificateAuthority

Body

Required^*. A string that sets the name of the certificate authority 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. that will be used to enroll against if there is more than one available with the provided template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. name. The certificate authority name can either be provided in hostname\\logical name format or as just the logical name. For example:

corpca01.keyexample.com\\CorpIssuingCA1 OR CorpIssuingCA1

If no certificate authority is provided, one will be chosen at random from the certificate authorities available for enrollment with the provided Template.

This field is optional unless the enrollment is being done against a standalone CA 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., in which case it is required.

Metadata

Body

An array of key/value pairs that set the values for the metadata fields that will be associated with the certificate once it is in Keyfactor Command. The key is the field name and the value is the value for the field. For example:

"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 in the Keyfactor Command Reference Guide for more information.

Timestamp

Body

The current date and time. 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).

Template

Body

Required^*. A string that sets the name of the certificate template that should be used to issue the certificate. The template short name should be used.

This field is required unless the enrollment is being done against a standalone CA.

SANs

Body

An array of key/value pairs that represent the elements for Keyfactor Command to use when generating the subject alternative name The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. (SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common.) for the certificate requested by the CSR. Show SAN key values.

For example:

"SANs": {
   "dns": [
      "dnssan1.keyexample.com",
      "dnssan2.keyexample.com",
      "dnssan3.keyexample.com"
   ],
   "ip4": [
      "192.168.2.73"
   ]
}

InstallIntoExistingCertificateStores

Body

A Boolean that sets whether to deploy the certificate to certificate stores (true) or not (false). The default is true.

AdditionalEnrollmentFields

Body

An array of key/value pairs that provide values for any custom enrollment fields set on the certificate template to supply custom request attributes to the CA during the enrollment process. For example:

"AdditionalEnrollmentFields": { "CustomStringOne": "MyValue", "CustomMultiChoiceOne": "ValueTwo" }

See Certificate Template Operations in the Keyfactor Command Reference Guide for more information.

x-CertificateFormat

Header

Required. The desired output format for the certificate. Available options are PFX, Zip, and Store. If Store is selected, no certificate blob will be returned in the response. The Store option is designed to be used when pushing a newly obtained PFX certificate to a certificate store (see POST Enrollment PFX Deploy).

Table 333: POST Enrollment PFX v2 Response Data

Value

Description

SuccessfulStores

An object containing a comma delimited list of certificate stores, referenced by certificate store GUID, to which the certificate was successfully scheduled for deployment.

CertificateInformation

Information about the certificate that was requested. Show certificate information details.

Value	Description
SerialNumber	A string indicating the serial number of the certificate.
IssuerDN	A string indicating the issuer DN A distinguished name (DN) is the name that uniquely identifies an object in a directory. In the context of Keyfactor Command, this directory is generally Active Directory. A DN is made up of attribute=value pairs, separated by commas. Any of the attributes defined in the directory schema can be used to make up a DN. of the certificate.
Thumbprint	A string indicating the thumbprint of the certificate.
KeyfactorID	An integer indicating the Keyfactor Command reference ID of the issued certificate.
PKCS12Blob	A string containing the base-64-encoded representation of the certificate in Zip or PFX format with the optional certificate chain. The string will need to be base-64 decoded for both Zip and PFX. This can be accomplished in a number of ways. For example, using PowerShell: $b64 = Get-Content 'C:\path\to\source\file' $targetFile = 'C:\path\to\target\file' $bytes = [Convert]::FromBase64String($b64) [IO.File]::WriteAllBytes($targetFile, $bytes) Note: No value is returned for the PKCS12Blob if you select a certificate format of Store in the header. The Store option is designed to be used when pushing a newly obtained PFX certificate to a certificate store (see POST Enrollment PFX Deploy).
Password	An internally used Keyfactor Command field.
WorkflowInstanceId	A string containing the Keyfactor Command reference GUID of the workflow instance. Tip: Both the WorkflowInstanceId and the WorkflowReferenceId refer to the same workflow instance record—one using a GUID and one using a more human readable integer.
WorkflowReferenceId	An integer containing the Keyfactor Command reference ID of the workflow instance. Tip: Both the WorkflowInstanceId and the WorkflowReferenceId refer to the same workflow instance record—one using a GUID and one using a more human readable integer.
KeyfactorRequestId	An integer indicating the Keyfactor Command reference ID of the request.
RequestDisposition	A string indicating the state of the request (e.g. ISSUED).
DispositionMessage	A string providing a message regarding the enrollment (e.g. The private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure. was successfully retained.).
EnrollmentContext	An internally used Keyfactor Command field.

Metadata

An array of the custom metadata values set on the certificate. The values vary depending on customization done in your environment. Show metadata structure details.

See Certificate Metadata in the Keyfactor Command Reference Guide for more information.

Version 1 of the POST /Enrollment/PFX method includes the same capabilities as version 2 except when used in conjunction with Keyfactor Command workflows that require approval with an intended end goal of delivering the resulting certificate into a certificate store. In this specific case, version 2 must be used.

Table 334: POST Enrollment PFX v1 Input Parameters

Name

Description

CustomFriendlyName

Body

Required^*. A string that sets a custom friendly name for the certificate.

Password

Body

PopulateMissingValuesFromAD

Body

A Boolean that sets whether to populate the information in the subject from Active Directory (true) or not (false). The default is false.

Subject

Body

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

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

IncludeChain

Body

A Boolean that sets whether to include the certificate chain in the response (true) or not (false). The default is true.

RenewalCertificateId

Body

An integer that sets the ID of the certificate to be renewed when the method is called on a certificate renewal.

CertificateAuthority

Body

Required^*. A string that sets the name of the certificate authority that will be used to enroll against if there is more than one available with the provided template name. The certificate authority name can either be provided in hostname\\logical name format or as just the logical name. For example:

corpca01.keyexample.com\\CorpIssuingCA1 OR CorpIssuingCA1

If no certificate authority is provided, one will be chosen at random from the certificate authorities available for enrollment with the provided Template.

This field is optional unless the enrollment is being done against a standalone CA, in which case it is required.

Timestamp

Body

The current date and time. 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).

Template

Body

Required^*. A string that sets the name of the certificate template that should be used to issue the certificate. The template short name should be used.

This field is required unless the enrollment is being done against a standalone CA.

Metadata

Body

"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 in the Keyfactor Command Reference Guide for more information.

SANs

Body

An array of key/value pairs that represent the elements for Keyfactor Command to use when generating the subject alternative name (SAN) for the certificate requested by the CSR. Show SAN key values.

Value	Description
rfc822	RFC 822 Name
dns	DNS Name
directory	Directory Name
uri	Uniform Resource Identifier
ip4	IP v4 Address
ip6	IP v6 Address
registeredid	Registered ID (an OID)
ms_ntprincipalname	MS_NTPrincipalName (a string)
ms_ntdsreplication	MS_NTDSReplication (a GUID)

For example:

"SANs": {
   "dns": [
      "dnssan1.keyexample.com",
      "dnssan2.keyexample.com",
      "dnssan3.keyexample.com"
   ],
   "ip4": [
      "192.168.2.73"
   ]
}

AdditionalEnrollmentFields

Body

"AdditionalEnrollmentFields": { "CustomStringOne": "MyValue", "CustomMultiChoiceOne": "ValueTwo" }

See Certificate Template Operations in the Keyfactor Command Reference Guide for more information.

x-CertificateFormat

Header

Table 335: POST Enrollment PFX v1 Response Data

Value

Description

CertificateInformation

Information about the certificate that was requested. Show certificate information details.

Value	Description
SerialNumber	A string indicating the serial number of the certificate.
IssuerDN	A string indicating the issuer DN of the certificate.
Thumbprint	A string indicating the thumbprint of the certificate.
KeyfactorID	An integer indicating the Keyfactor Command reference ID of the issued certificate.
PKCS12Blob	A string containing the base-64-encoded representation of the certificate in Zip or PFX format with the optional certificate chain. The string will need to be base-64 decoded for both Zip and PFX. This can be accomplished in a number of ways. For example, using PowerShell: $b64 = Get-Content 'C:\path\to\source\file' $targetFile = 'C:\path\to\target\file' $bytes = [Convert]::FromBase64String($b64) [IO.File]::WriteAllBytes($targetFile, $bytes) Note: No value is returned for the PKCS12Blob if you select a certificate format of Store in the header. The Store option is designed to be used when pushing a newly obtained PFX certificate to a certificate store (see POST Enrollment PFX Deploy).
Password	An internally used Keyfactor Command field.
WorkflowInstanceId	A string containing the Keyfactor Command reference GUID of the workflow instance. Tip: Both the WorkflowInstanceId and the WorkflowReferenceId refer to the same workflow instance record—one using a GUID and one using a more human readable integer.
WorkflowReferenceId	An integer containing the Keyfactor Command reference ID of the workflow instance. Tip: Both the WorkflowInstanceId and the WorkflowReferenceId refer to the same workflow instance record—one using a GUID and one using a more human readable integer.
KeyfactorRequestId	An integer indicating the Keyfactor Command reference ID of the request.
RequestDisposition	A string indicating the state of the request (e.g. ISSUED).
DispositionMessage	A string providing a message regarding the enrollment (e.g. The private key was successfully retained.).
EnrollmentContext	An internally used Keyfactor Command field.

Metadata

An array of the custom metadata values set on the certificate. The values vary depending on customization done in your environment. Show metadata structure details.

See Certificate Metadata in the Keyfactor Command Reference Guide for more information.

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

Products

Solutions

Resources

Company