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

/certificates/enrollment/csr/

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:  All 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., ODKG and CSR), renewal, and revocation requests flow through Keyfactor Command 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. (see Workflow Definitions).

Table 456: POST Enrollment CSR Input Parameters

Name In Description
Additional Enrollment Fields Body An object that provide values for any custom enrollment fields set on the enrollment pattern to supply custom request attributes to the CA during the enrollment process. For example:
"AdditionalEnrollmentFields": { "CustomStringOne": "ValueOne", "CustomMultiChoiceTwo": "ValueTwo" }

See Adding or Modifying an Enrollment Pattern for more information.
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 or EnrollmentPatternId.

Note:   The list of CAs from which a CA is selected if a template or enrollment pattern is not supplied depends on the enrollment pattern's Restrict CAs setting (see Basic Information Tab) and the configuration tenant of the template associated with the enrollment pattern:

  • Restrict CAs Enabled: The CAs listed in the enrollment pattern’s Certificate Authorities list, limited to those in the same configuration tenant as the associated template.

  • Restrict CAs Disabled: All enterprise CAs defined in Keyfactor Command that share the same configuration tenant as the associated template.

In either case, the template associated with the enrollment pattern must also be available for enrollment on the CA and must have certificate request permissions granted to the appropriate user (see HTTPS CAs - Advanced Tab or DCOM CAs - Advanced Tab) in order for the CA to be included in the list.

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

CSR Body

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

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

One of either the Template or the EnrollmentPatternId is required unless the enrollment is being done against a standalone CA. If both the Template 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.

forceEnroll Query A Boolean that sets whether to allow a CSR generated within Keyfactor Command to be used for the CSR enrollment request (true) or not (false). The default is false.
Include Subject Header Body

A Boolean that sets whether to include the subject header in the response (true) or not (false). The default is true if not included in the request. Only applicable when PEM format is selected. When set to false, the first line in the PEM file that contains the certificates subject information is removed. When set to true, the first line in the PEM file that contains the certificates subject information is included.

Works with Include Chain option where it will remove the subject header, when set to false, for each of the certificates returned in the chain. It also works with Include Private Key option enabled.

 
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 object 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:

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.
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 enrollment pattern 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 enrollment pattern or system-wide settings Certificate Owner Role policy has been configured as Required.
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.
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"
   ]
}
Note:  SANs submitted outside the CSR may be ignored, appended to SANs in the CSR, or overwrite the SANs in the CSR request depending on the type and configuration of the issuing CA. 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 will still be added alongside anything you add here. For a Microsoft CA, review the SAN Attribute Policy Handler for the Keyfactor CA Policy Module (see Installing the Keyfactor CA Policy Module Handlers) for more information.
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. See also EnrollmentPatternId.

One of either the Template or the EnrollmentPatternId is required unless the enrollment is being done against a standalone CA. If both the Template 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.

Important:  The template must be configured with at least one enrollment pattern in order to be used for enrollment (see POST Enrollment Patterns).
Note:  This parameter is considered deprecated and may be removed in a future release.
Timestamp Body

Required. The current date and time (which will be automatically populated in the Keyfactor API Reference and Utility). 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).
x-CertificateFormat Header

Required. A string indicating the desired output format for the certificate. Available options are DER and PEM.

Table 457: POST Enrollment CSR Response Data

Value Description
CertificateInformation

An object containing 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 for more information.
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 workflow 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.