POST Enrollment Patterns

The POST /EnrollmentPatterns method is used to create a new 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). pattern. This method returns HTTP 200 OK on a success with details about the new enrollment pattern.

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

/enrollment_pattern/modify/

Table 482: POST EnrollmentPatterns Input Parameters

Name In Description
Name Body A string indicating the Keyfactor Command reference name of the enrollment pattern.
Description Body A string indicating the Keyfactor Command description of the enrollment pattern.
Template Body

An integer indicating the template associated with the enrollment pattern.

Use the GET /Templates method (see GET Templates) to retrieve a list of all the templates to determine the template ID.

Template Default Body

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

An array of strings 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. For example:

Copy
 "AssociatedRoles": [
    "Administrators",
    "Power Users"
  ]
Certificate Authorities Body

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

Use the GET /CertificateAuthority method (see GET Certificate Authority) to retrieve a list of all the certificate authorities to determine the ID.

Allowed Enrollment Types Body

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. ClosedShow allowed enrollment type details.

Regexes Body

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. ClosedShow regular expression details.

For example:

Copy
"Regexes": [
   {
      "SubjectPart": "O",
      "Regex": "^(?:Key Example Company|Key Example\, Inc\.)$",
      "Error": "Organization must be Key Example, Inc or Key Example Company.",
      "CaseSensitive": true
   }
]
Metadata Fields Body

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.

ClosedShow metadata field details.

For example:

Copy
"MetadataFields": [
   {
      "MetadataId": 4,
      "DefaultValue": "reggie.wallace@keyexample.com",
      "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.",
      "CaseSensitive": false
   },
   {
      "MetadataId": 13,
      "DefaultValue": "E-Business",
      "Validation": "",
      "Enrollment": 0,
      "Message": "",
      "Options": "Accounting,E-Business,Executive,HR,IT,Marketing,R&D,Sales",
      "CaseSensitive": false
   }
]
RestrictCAs Body 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 Body

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. ClosedShow enrollment pattern policy details.

For example:

Copy
"Policies": {
   "AllowKeyReuse": false,
   "AllowWildcards": true,
   "RFCEnforcement": true,
   "CertificateOwnerRole": 0,
   "DefaultCertificateOwnerRoleId": 3,
   "DefaultCertificateOwnerRoleName": "Power Users",
   "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
   }
}
Defaults Body

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. ClosedShow enrollment pattern default details.

For example:

Copy
"Defaults": [
   {
      "SubjectPart": "L",
      "Value": "Denver"
   },
   {
      "SubjectPart": "ST",
      "Value": "Colorado"
   }
]
Enrollment Fields Body

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.

ClosedShow enrollment field details.

For example:

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

Table 483: POST Enrollment Patterns Response Body

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. ClosedShow template details.

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. ClosedShow 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). ClosedShow CA details.

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. ClosedShow allowed enrollment type details.

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. ClosedShow regular expression details.

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.

ClosedShow metadata field details.

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. ClosedShow enrollment pattern policy details.

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. ClosedShow enrollment pattern default details.

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.

ClosedShow enrollment field details.

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