Documentation Suite v25.1.1

Submit Search

GET Enrollment CSR Context My

The GET /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)./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./Context/My method is used to check the templates and CAs available for CSR enrollment for the current user. This method has no input parameters other than the standard headers (see Endpoint Common Features). It returns HTTP 200 OK on a success with the list of templates that are available for enrollment via Keyfactor Command and the CAs those templates may be enrolled from along with template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. and 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. configuration details. Results are returned based on the enrollment permissions of the user making the request—both Keyfactor Command permissions and template and CA level permissions on the originating CA. Templates or standalone CAs are included in the results only if the user has appropriate permissions in both locations and the template and CA are configured for CSR enrollment in Keyfactor Command.

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

/certificates/enrollment/csr/

Table 450: GET Enrollment CSR Context My Response Data

Name Description

Templates

An array of objects containing the templates available for enrollment by the user. Show template details.

Name Description

Id An integer indicating the Keyfactor Command reference ID of the certificate template.

Name A string containing the common name (short name) of the template. This name typically does not contain spaces. For a template created using a Microsoft management tool, this will be the Microsoft template name.

Display Name A string containing the common name (short name) of the template. This name typically does not contain spaces. For a template created using a Microsoft management tool, this will be the Microsoft template name.

Requires Approval A Boolean indicating whether the template has been configured with the Microsoft CA certificate manager approval option enabled (true) or not (false).

RFC Enforcement A Boolean indicating whether certificate enrollments made through Keyfactor Command for this template must include at least one DNS SAN (true) or not (false). In the Keyfactor Command Management Portal, this causes the CN entered in PFX enrollment to automatically be replicated as a SAN, which the user can either change or accept. For CSR enrollment, if the CSR does not have a SAN that matches the CN, one will automatically be added to the certificate if this is set. By default, this is set to false at a system-wide level and may be overridden on a template-by-template basis.

CAs

An array of objects indicating the certificate authorities that allow enrollment for the template and the requesting user. The template must be available for enrollment on the CA, the template and CA must be configured for enrollment in Keyfactor Command, and the requesting user must have enrollment permissions. Show CA details.

Name	Description
Name	A string indicating the full name of the CA, made up of the DNS hostname of the certificate authority (e.g. corpca01.keyexample.com) and the logical name (e.g. CorpIssuingCA1) for a full name similar to corpca01.keyexample.com\\CorpIssuingCA1.
RFC Enforcement	A Boolean that sets whether certificate enrollments made through Keyfactor Command for this CA must include at least one DNS SAN (true) or not (false). In the Keyfactor Command Management Portal, this causes the CN entered in PFX enrollment to automatically be replicated as a SAN, which the user can either change or accept. For CSR enrollment, if the CSR does not have a SAN that matches the CN, one will automatically be added to the certificate if this is set. This setting at the CA level applies only to standalone CAs. For CAs that use templates, this setting is controlled at the template level and is ignored at the CA level.
Subscriber Terms	A Boolean that sets whether to add a checkbox on the enrollment pages to force users to agree to a custom set of terms before enrolling (true) or not (false). Tip: Configure a link to the custom terms using the URL to Subscriber Terms application setting. See Application Settings: Enrollment Tab for more information.

Enrollment Fields

An array of objects containing custom enrollment fields. These are configured on a per-template basis to allow you to submit custom fields with CSR enrollments and PFX enrollments to supply custom request attributes to the CA during the enrollment process. This functionality offers such benefits as:

Preventing users from requesting invalid certificates, based on your specific certificate requirements per template.
Providing additional information to the CA with the CSR.

Once created on the template, these values are shown in Keyfactor Command on the PFX and CSR enrollment pages in the Additional Enrollment Fields section. The fields are mandatory during enrollment. The data will appear on the CA / Issued Certificates attribute tab for certificates enrolled with a template configured with Keyfactor Command enrollment fields.

Note: These are not metadata fields, so they are not stored in the Keyfactor Command database, but simply passed through to the CA. The CA in turn could, via a gateway or policy module, use this data to perform required actions.

Show enrollment field details.

Name

Description

An integer indicating the ID of the custom enrollment field.

Name

A string indicating the name of the custom enrollment field. This name will appear on the enrollment pages.

DataType

An integer indicating the parameter type. The options are:

Value	Description
1	String: A free-form data entry field.
2	Multiple Choice: Provides a list of acceptable values for the field. The multiple choice values are provided in the Options parameter.

Options

For multiple choice values, an array of strings containing the value choices.

For example:

Copy

"EnrollmentFields": [
   {
      "Id": 3,
      "Name": "MyCustomField",
      "Options": ["Green","Red","Yellow","Blue"],
      "DataType": 2
   }
]

Metadata Fields

An array of objects containing template-level metadata field settings. Template-level metadata field configurations can override global metadata field configurations in these possible ways:

Configuration on the metadata field of required, optional or hidden.
The default value for the metadata field.
A regular expression defined for the field (string fields only) against which entered data will be validated along with its associated message.
For fields of data type multiple choice, the list of values that appear in multiple choice dropdowns.

Metadata field settings defined on a template apply to enrollments made with that template only. Template-level metadata field settings, if defined, take precedence over global-level metadata field settings.

Show metadata field details.

Name Description

Id An integer indicating the Keyfactor Command reference ID of the template-specific metadata setting.

Default Value A string containing the default value defined for the metadata field for the specific template.

Metadata Id An integer indicating the global metadata field associated with the template-specific settings.

Validation

A string containing the template-specific regular expression against which data entered in a string field will be validated. When a user enters information in a metadata field that does not match the specified regular expression, he or she will see the warning message specified in the Message field. For example:

Copy

^[a-zA-Z0-9'_\.\-]*@(keyexample\.org|keyexample\.com)$

This regular expression specifies that the data entered in the field must consist of some number of characters prior to the “@” made up only of lowercase letters, uppercase letters, numbers, apostrophes, underscores, periods, and/or hyphens followed by exactly either “@keyexample.org” or “keyexample.com”.

This field is only supported for metadata fields with data type string.

Enrollment

An integer that indicates how metadata fields should be handled on the PFX and CSR Enrollment pages. Possible values are:

Value	Description
0	Optional Users have the option to either enter a value or not enter a value in the field.
1	Required Users are required to enter data in the field when populating metadata fields on the PFX and CSR Enrollment pages. The field is not required on the certificate details or Add Certificate page.
2	Hidden The field is hidden and does not appear on the PFX and CSR Enrollment pages. This field still appears on the certificate details and the Add Certificate page.

Message A string containing a message to present when a user enters information in a metadata field that does not match the template-specific regular expression (Validation field).

For example:

Copy

"MetadataFields": [
   {
      "Id": 4,
      "DefaultValue": "reggie.wallace@keyexample.com",
      "MetadataId": 4,
      "Validation": "^[a-zA-Z0-9'_\\.\\-]*@(keyexample\\.org|keyexample\\.com)$",
      "Enrollment": 1,
      "Message": "Your email address must be of the form user@keyexample.com or fname.lname@keyexample.com."
   },
   {
      "Id": 13,
      "DefaultValue": "E-Business",
      "MetadataId": 5,
      "Validation": "",
      "Enrollment": 0,
      "Message": "",
      "Options": "Accounting,E-Business,Executive,HR,IT,Marketing,R&D,Sales"
   }
]

Regexes

An array of objects containing the global template regular expression settings. These apply to all enrollments that are not otherwise overridden by individual template settings, including those that do not use a template (e.g. from a standalone CA). Show regular expression details.

Name Description

Template Id An integer indicating the Keyfactor Command reference ID of the certificate template the regular expression is associated with.

Subject Part A string indicating the portion of the subject the regular expression applies to (e.g. CN).

RegEx

A string specifying the regular expression against which data entered in the indicated subject part field (e.g. CN) in the enrollment pages of the Keyfactor Command Management Portal or using an API enrollment method will be validated.

Use the GET /Templates/SubjectParts method (see GET Templates Subject Parts) to retrieve a list of all the supported subject parts.

Show regular expression examples.

Subject Part	Example
CN (Common Name)	This regular expression specifies that the data entered in the field must consist of 1 to 63 characters in the first portion of the field made up only of lowercase letters, uppercase letters, numbers, periods, and/or hyphens (but not at the beginning or end of sections or duplicated) followed by exactly .keyexample.com: Copy `^(?!-)(?!.--)[A-Za-z0-9-]{1,63}(?<!-)(\.[A-Za-z0-9-]{1,63})\.keyexample\.com$` The default value for the Common Name regular expression is: Copy `.+` This requires entry of at least one character in the Common Name field in the enrollment pages.
O (Organization)	This regular expression requires that the organization name entered in the field be one of “Key Example Inc”, “Key Example” or “Key Example Inc.”: Copy `^(?:Key Example Inc\|Key Example\|Key Example, Inc\.)$` The period in the final company name (Key Example, Inc.) needs to be escaped in the regular expression with a slash ("\") but the comma does not.
OU (Organization Unit)	This regular expression requires that the organizational unit entered in the field be one of these four departments: Copy `^(?:IT\|HR\|Accounting\|E-Commerce)$`
L (City/ Locality)	This regular expression requires that the city entered in the field be one of these five cities: Copy `^(?:Boston\|Chicago\|New York\|London\|Dallas)$`
ST (State/ Province)	This regular expression requires that the state entered in the field be one of these eight states: Copy `^(?:Massachusetts\|Illinois\|New York\|Ontario\|Texas)$`
C (Country)	This regular expression requires that the country entered in the field be either US or CA: Copy `^(?:US\|CA)$`
E (Email)	This regular expression specifies that the data entered in the field must consist of some number of characters prior to the “@” made up only of lowercase letters, uppercase letters, numbers, periods, underscores, percent signs, apostrophes, plus signs, and/or hyphens followed by exactly “@keyexample.com”: Copy `^[A-Za-z0-9._%'+-]+@keyexample\.com$`
DNS (Subject Alternative Name: DNS Name)	This regular expression specifies that the data entered in the field must consist of 1 to 63 characters in the first portion of the field made up only of lowercase letters, uppercase letters, numbers, periods, and/or hyphens (but not at the beginning or end of sections or duplicated) followed by exactly either “.keyexample1.com” or “.keyexample2.com”: Copy `^(?!-)(?!.--)[A-Za-z0-9-]{1,63}(?<!-)(\.[A-Za-z0-9-]{1,63})\.(keyexample\.com\|keyexample2\.com)$`
IPv4 (Subject Alternative Name: IPv4 Address)	This regular expression specifies that the data entered in the field must be exactly “130.101.” followed by a value between 0 and 255, followed by “.”, followed a value between 0 and 255: Copy `^130\.101\.(?:[0-9]\|[1-9][0-9]\|1[0-9]{2}\|2[0-4][0-9]\|25[0-5])\.(?:[0-9]\|[1-9][0-9]\|1[0-9]{2}\|2[0-4][0-9]\|25[0-5])$` This regular expression specifies only that the IPv4 address is made up of 4 sets of values between 0 and 255 separated by periods: Copy `^(?:[0-9]{1,2}\|1[0-9]{2}\|2[0-4][0-9]\|25[0-5])\.(?:[0-9]{1,2}\|1[0-9]{2}\|2[0-4][0-9]\|25[0-5])\.(?:[0-9]{1,2}\|1[0-9]{2}\|2[0-4][0-9]\|25[0-5])\.(?:[0-9]{1,2}\|1[0-9]{2}\|2[0-4][0-9]\|25[0-5])$`
IPv6 (Subject Alternative Name: IPv6 Address)	This regular expression specifies that the data entered in the field must be made up of up to eight sets of between one and four numbers and/or uppercase letters separated by colons: Copy `^([A-F0-9]{1,4}:){1,7}([A-F0-9]{1,4})?(\:\:([A-F0-9]{1,4}:){0,6}[A-F0-9]{1,4})?$` This regular expression optionally matches a shorthand “::” that can replace one or more groups of zero segments, allowing the address to use shorthand notation.
MAIL (Subject Alternative Name: Email)	This regular expression specifies that the data entered in the field must consist of some number of characters prior to the “@” made up only of lowercase letters, uppercase letters, numbers, periods, underscores, percent signs, apostrophes, plus signs, and/or hyphens followed by exactly “@keyexample.com”: Copy `^[A-Za-z0-9._%'+-]+@keyexample\.com$`
UPN (Subject Alternative Name: User Principal Name)	This regular expression specifies that the data entered in the field must consist of between 1 and 64 characters prior to the “@” made up only of lowercase letters, uppercase letters, numbers, apostrophes, underscores, spaces, and/or hyphens followed by exactly “@keyexample.com”: Copy `^[A-Za-z0-9'_ -]{1,64}@keyexample\.com$`

Error

A string specifying the error message displayed to the user when the subject part referenced in the CSR or entered for a PFX enrollment does not match the given regular expression.

Note: The error message already includes a leading string with the subject part (e.g. “Common Name:” or “Invalid CN provided:” depending on the interface used). Your custom message follows this.

Extended Key Usages

Currently not in use.

Enrollment Template Policy

An object containing the individual template-level template policy settings. Template policies defined on a template apply to enrollments made with that template only. Template-level policies, if defined, take precedence over system-wide template policies. For more information about system-wide template policies, see GET Templates Settings. Show template policy details.

Value

Description

Key Info

An object containing the supported key types for the template along with the bit lengths and/or curves for the key types as appropriate.

Name	Description
ECDSA	An object containing two arrays: bit_lengths: An array of integers indicating the key sizes supported for enrollment through Keyfactor Command. curves: An array of strings indicating the elliptic curve algorithms that are supported for enrollment through Keyfactor Command. ECC curves may be specified using the well-known OIDs for ECC algorithms or by friendly name. Well-known OIDs include: 1.2.840.10045.3.1.7 = P-256/ prime256v1/ secp256r1 1.3.132.0.34 = P-384/secp384r1 1.3.132.0.35 = P-521/secp521r1 When specifying by friendly name, do not include a slash (use “P-256”, not “P-256/prime256v1/secp256r1”).
RSA	An object containing two arrays: bit_lengths: An array of integers indicating the key sizes supported for enrollment through Keyfactor Command. curves: There are no curves for this type of key.
Ed448	An object containing two arrays: bit_lengths: An array of integers indicating the key sizes supported for enrollment through Keyfactor Command. curves: There are no curves for this type of key.
Ed25519	An object containing two arrays: bit_lengths: An array of integers indicating the key sizes supported for enrollment through Keyfactor Command. curves: There are no curves for this type of key.

Allow Key Reuse

A Boolean that indicates whether private key reuse is allowed (true) or not (false). This option applies to certificate renewals. By default, this is set to true at a system-wide level.

Allow Wildcards

A Boolean that indicates whether wildcards are allowed (true) or not (false). By default, this is set to true at a system-wide level.

RFC Enforcement

A Boolean that indicates whether RFC 2818 compliance enforcement is enabled (true) or not (false). When this option is set to true, certificate enrollments made through Keyfactor Command for this template must include at least one DNS SAN. In the Keyfactor Command Management Portal, this causes the CN entered in PFX enrollment to automatically be replicated as a SAN, which the user can either change or accept. For CSR enrollment, if the CSR does not have a SAN that matches the CN, one will automatically be added to the certificate if this is set. By default, this is set to false at a system-wide level.

For example:

Copy

"TemplatePolicy": {
   "AllowKeyReuse": false,
   "AllowWildcards": true,
   "RFCEnforcement": true,
   "KeyInfo": {
      "ECDSA": {
         "bit_lengths": [
            256,
            384,
            521
         ],
         "curves": [
            "1.2.840.10045.3.1.7",
            "1.3.132.0.34",
            "1.3.132.0.35"
         ]
      },
      "RSA": null,
      "Ed448": null,
      "Ed25519": null
   }
}

Key Size A string indicating the minimum supported key size of the template.

Curve A string indicating the OID of the elliptical curve algorithm configured for the template, for ECC templates.

Standalone CAs

An array of objects containing enrollment information for standalone certificate authorities available for enrollment for the current user. Show standalone CA details.

Name	Description
Name	The full name of the CA, made up of the DNS hostname of the certificate authority (e.g. myca.keyexample.com) and the logical name (e.g. CorpStandaloneCA1) for a full name similar to myca.keyexample.com\\CorpStandaloneCA1.
RFC Enforcement	A Boolean that sets whether certificate enrollments made through Keyfactor Command for this CA must include at least one DNS SAN (true) or not (false). In the Keyfactor Command Management Portal, this causes the CN entered in PFX enrollment to automatically be replicated as a SAN, which the user can either change or accept. For CSR enrollment, if the CSR does not have a SAN that matches the CN, one will automatically be added to the certificate if this is set. This setting at the CA level applies only to standalone CAs. For CAs that use templates, this setting is controlled at the template level and is ignored at the CA level.
Subscriber Terms	A Boolean that sets whether to add a checkbox on the enrollment pages to force users to agree to a custom set of terms before enrolling (true) or not (false). Tip: Configure a link to the custom terms using the URL to Subscriber Terms application setting. See Application Settings: Enrollment Tab for more information.

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.

Was this page helpful? Provide Feedback

Version v25.1.1

On this page: