Documentation Suite v25.1.2

Submit Search

GET Enrollment Patterns

The GET /EnrollmentPatterns method is used to retrieve one or more 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). patterns from Keyfactor Command. Query parameters enable filtering using defined criteria, control over pagination by specifying the page number and return limit, and customization of sorting based on specified fields and order. This method returns HTTP 200 OK on a success with details about the specified enrollment patterns.

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

/enrollment_pattern/read/

Table 449: GET Enrollment Patterns Input Parameters

Name	In	Description
QueryString	Query	A string containing a query to limit the results (e.g. field1 -eq value1 AND field2 -gt value2). The default is to return all records. Fields available for querying through the API for the most part match those that appear in the Keyfactor Command Management Portal search dropdowns for the same feature. For querying guidelines, refer to: Using the Enrollment Pattern Search Feature. The query fields supported for this endpoint are: AllowedEnrollmentType (1-PFX Enrollment, 2-CSR Enrollment, 3-CSR Generation, 0-None) AssociatedRoleName CALogicalName ConfigurationTenant RestrictCA (True, False) TemplateDefault (True, False) TemplateDisplayName TemplateFriendlyName TemplateId TemplateShortName
PageReturned	Query	An integer that specifies how many multiples of the returnLimit to skip and offset by before returning results, to enable paging. The default is 1.
ReturnLimit	Query	An integer that specifies how many results to return per page. The default is 50. Very large values can result in long processing time.
SortField	Query	A string containing the property by which the results should be sorted. Fields available for sorting through the API for the most part match those that appear as sortable columns in the Keyfactor Command Management Portal. The default sort field is Name.
SortAscending	Query	An integer that sets the sort order on the returned results. A value of 0 sorts results in ascending order while a value of 1 sorts results in descending order. The default is ascending.

Table 450: GET Enrollment Patterns Response Data

Name Description

Id An integer indicating the ID of the enrollment pattern in Keyfactor Command.

Name A string indicating the Keyfactor Command reference name of the enrollment pattern.

Description A string indicating the Keyfactor Command description of the enrollment pattern.

Template

An object containing information for the template associated with the enrollment pattern. Show template details.

Name	Description
Id	An integer indicating the ID of the template in Keyfactor Command.
Template Name	A string containing the name of the template. For a template created using a Microsoft management tool, this will be the Microsoft template display name. For a template generated for an EJBCA CA, this will be built using a naming scheme of <end entity profile name> (<certificate profile name>). This field is populated based on information retrieved from the CA and is not configurable.
Common 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. For a template generated for an EJBCA CA, this will be built using a naming scheme of <end entity profile name>_<certificate profile name>. This field is populated based on information retrieved from the CA and is not configurable.
Configuration Tenant	A string indicating the configuration tenant of the template.
Requires Approval	A Boolean indicating whether the template has been configured with the Microsoft CA certificate manager approval option enabled (true) or not (false).
Friendly Name	A string indicating the Keyfactor Command friendly name of the template. Template friendly names, if configured, appear in the dropdowns for PFX enrollment, CSR enrollment, and CSR generation in place of the template names. This can be useful in environments where the template names are long or not very human readable.

Template Default

A Boolean indicating whether this enrollment pattern is the default pattern for the associated template (true) or not (false). A certificate template can have only one default enrollment pattern, which is required for the template to be used for enrollment. If no other enrollment pattern for the template exists or is marked as default, this option will automatically be enabled when a new pattern is created.

UseAD Permissions A Boolean indicating whether Active Directory permissions should be used for certificate enrollment authorization (true) or whether Keyfactor Command security roles should be used (false). If set to false, at least one value must be provided for AssociatedRoles.

Associated Roles

An array of objects indicating the security roles associated with the enrollment pattern. Only users holding ones of these roles will be able to use the enrollment pattern if UseADPermissions is false. Show role details.

Certificate Authorities

An array of objects indicating the certificate authorities to which the enrollment pattern is restricted, if applicable (see the RestrictCAs parameter). Show CA details.

Name	Description
Id	An integer indicating the ID of the certificate authority in Keyfactor Command.
Logical Name	A string indicating the logical name of the certificate authority.
HostName	A string indicating the DNS hostname (for DCOM configurations) or URL (for HTTPS configurations) of the certificate authority (e.g. myca.keyexample.com or https://myca.keyexample.com).
Configuration Tenant	A string indicating the forest root name or DNS domain name for the certificate authority (e.g. keyexample.com).

Allowed Enrollment Types

An integer indicating the type of enrollment allowed for the enrollment pattern. Setting these options causes the enrollment pattern to appear in dropdowns in the corresponding section of the Management Portal. In the case of CSR Enrollment and PFX Enrollment, the enrollment patterns only appear in dropdowns on the enrollment pages if they are available for enrollment from a CA also configured for enrollment within Keyfactor Command. See HTTPS CAs - Enrollment Section or DCOM CAs - Enrollment Section for more information. Show allowed enrollment type details.

Value	Description
0	None
1	PFX Enrollment
2	CSR Enrollment
3	CSR Enrollment & PFX Enrollment
4	CSR Generation
5	CSR Generation & PFX Enrollment
6	CSR Generation & CSR Enrollment
7	CSR Enrollment, PFX Enrollment & CSR Generation

Regexes

An array of objects containing regular expressions specific to an individual enrollment pattern, used to validate the subject data. Regular expressions defined on an enrollment pattern apply to enrollments made with that enrollment pattern only. Regular expressions defined for enrollment patterns take precedence over system-wide regular expressions. Show regular expression details.

Name Description

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.

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.

Case Sensitive A Boolean that sets the validation for the field to be case-sensitive (true) or not (false). If the subject part does not match the expected case, the value specified by the Error parameter will display. If the CaseSensitive option is disabled, even if the regular expression contains requirements to enforce case, the case requirement will not be enforced.

Metadata Fields

An array of objects containing metadata field settings specific to an individual enrollment pattern. These 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 an enrollment pattern apply to enrollments made with that enrollment pattern only and take precedence over global-level metadata field settings.

Show metadata field details.

Name Description

Metadata Id

An integer indicating the Keyfactor Command reference ID of the global metadata field associated with the settings specific to the enrollment pattern.

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

Validation

A string containing the regular expression for the enrollment pattern 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 regular expression for the enrollment pattern (Validation field).

Case Sensitive A Boolean for string metadata fields with Validation defined, that sets the validation for the field to be case-sensitive (true) or not (false). If the user's entry for the metadata field does not match the expected case, the value specified by the Message parameter will display.

RestrictCAs A Boolean indicating whether the enrollment pattern should be restricted to use with a specified list of certificate authorities (true) or not (false). If set to true, at least one CA must be configured using the CertificateAuthorities parameter.

Policies

An object containing the individual policy settings for the enrollment pattern. Policies defined on an enrollment pattern apply to enrollments made with that enrollment pattern only and take precedence over system-wide policies. For more information about system-wide enrollment pattern policies, see GET Enrollment Patterns Settings. Show enrollment pattern policy details.

Name

Description

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 enrollment pattern must include at least one DNS SAN. In the Keyfactor CommandManagement Portal, this causes the following behavior:

PFX Enrollment: The CN entered in PFX enrollment is automatically replicated as a DNS SAN, which the user does not see and cannot change.
CSR Enrollment: For CSR enrollment, if the CSR does not have a SAN that matches the CN, one will automatically be added to the certificate. The user enrolling does not see this and cannot change it.
CSR Generation: The CN entered in CSR generation will be automatically replicated as a DNS SAN and set to read only.

By default, this is set to false at a system-wide level.

Certificate Owner Role

An integer indicating the certificate owner role setting. The supported values are:

0 - Optional
1 - Required
2 - Hidden

Required is enforced for PFX and CSR enrollment in both the Management Portal and Keyfactor API. Hidden applies to PFX and CSR enrollment in the Management Portal.

Default Certificate Owner Role Id

An integer indicating the Keyfactor Command reference ID of the security role assigned as the default certificate owner for certificates enrolled or imported via synchronization or scanning with this enrollment pattern.

Default Certificate Owner Role Name

A string indicating the name of the security role assigned as the default certificate owner for certificates enrolled or imported via synchronization or scanning with this enrollment pattern.

KeyInfo

An object containing the supported key types for the enrollment pattern along with the bit lengths and/or curves for the key types as appropriate. Show key info details.

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

Defaults

An array of objects containing default subject settings specific to an individual enrollment pattern. Default subjects defined on an enrollment pattern apply to enrollments made with that enrollment pattern only and take precedence over system-wide default subject settings. For more information about system-wide defaults, see GET Enrollment Patterns Settings. Show enrollment pattern default details.

Value	Description
SubjectPart	A string indicating the portion of the subject the default applies to (e.g. L for City/Locality).
Value	A string containing the value to assign as the default for that subject part (e.g. Chicago).

Enrollment Fields

An object containing custom enrollment fields. These are configured for each enrollment pattern to allow you to submit custom fields with CSR enrollments and PFX enrollments, supplying custom request attributes to the CA during the enrollment process. This functionality offers benefits such as:

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

Once created for the enrollment pattern, 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 an enrollment pattern 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

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.

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

On this page: