POST Enrollment CSR

The POST /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)./CSRClosed 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. method is used to enroll for a certificate using a certificate signing requestClosed 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. (CSR). This method returns HTTP 200 OK on a success with a message body containing a list of certificate details and any 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 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: EnrollCSR

Tip:  Use the GET /Enrollment/CSR/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 (PFXClosed 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. and CSR), renewal, and revocation requests all flow through Keyfactor Command 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.. This will result in no changes to the enrollment, renewal, and revocation user experience unless customizations have been added in workflow (see Workflow Definitions).

Table 329: POST Enrollment CSR Input Parameters

Name In Description
CSR Body

Required. The base-64 encoded CSR that will be passed in for enrollment.
PrivateKey Body

A string containing the base-64 encoded private key that corresponds to the CSR to be saved with the enrollment. This is done to support private key retention in Keyfactor Command for requests made through CSR enrollment. The key should be provided in unencrypted PKCS#8 format. The private key option is only supported for enrollments done using templates configured in Keyfactor Command for private key retention.
Timestamp Body

Required. 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.

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.

IncludeChain Body

A Boolean that sets whether to include the certificate chain in the response (true) or not (false). The default is false.
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.
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. ClosedShow SAN key values.

For example:

"SANs": {
   "dns": [
      "dnssan1.keyexample.com",
      "dnssan2.keyexample.com",
      "dnssan3.keyexample.com"
   ],
   "ip4": [
      "192.168.2.73"
   ]
}
Note:  Entering SANs with this option may either append or overwrite the SANs in the CSR request depending on how the issuing CA is configured. Please be sure to check that the certificate has the correct SANs after issuance. Any SAN added automatically as a result of the RFC 2818 compliance settings (see GET Templates) will still be added alongside anything you add here. Review the SAN Attribute Policy Handler for the Keyfactor CA Policy Module (see Installing the Keyfactor CA Policy Module Handlers in the Keyfactor Command Server Installation Guide) for more information.
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": "ValueOne", "CustomMultiChoiceTwo": "ValueTwo" }

See Certificate Template Operations of the Keyfactor Command Reference Guide for more information.
x-CertificateFormat Header

Required. The desired output format for the certificate. Available options are DER and PEM.

Table 330: POST Enrollment CSR Response Data

Value Description
CertificateInformation

Information about the certificate that was requested. ClosedShow CSR details.
Metadata

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

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.