Metadata Field Operations

To create a new metadata field or edit an existing one:

1. In the Management Portal, browse to the System Settings Icon > Certificate Metadata.

2. On the Certificate Metadata page, click Add to create a new metadata field, or, to edit an existing one, double-click the row in the metadata grid, right-click the row and choose Edit from the right-click menu, or highlight the row in the grid and click Edit at the top of the grid.

   

   Figure 367: Certificate Metadata

3. In the Metadata Edit dialog, enter a Name for your metadata field. This name appears in interfaces where you can use metadata, such as certificate details dialogs, alert dialogs, certificate imports and certificate requests. Once this field has a value associated with it for at least one certificate, you cannot change this name. The metadata name field cannot contain spaces; dashes and underscores are supported.

   Important:   Be sure to review the list of existing queryable certificate fields on the Certificate Search Page before adding a new metadata field, so you do not add a field of the same name or alias as an existing field. Doing so would cause a search or alert on that field to fail. For example, do not create a metadata field called NetBIOSRequester or its alias RequesterName, as this would match is an existing certificate field, and having a metadata field with this name would create issues.

   

   Figure 368: Create or Edit Certificate Metadata Field

4. Enter a Description for the metadata field. The description appears in a tool tip when users hover over the field name in places where metadata may be edited such as 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. 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)., PFX 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. enrollment, and the certificate details metadata tab.

5. The Enrollment Options provide three possible settings for the metadata field:

   • Select the Optional radio button to allow users the option to either enter a value or not enter a value in the field when populating metadata fields.
   • Select the Required radio button to force users to enter a value in the field when populating metadata fields. Required fields will be marked with *Required next to the field label on the Certificate Details dialog for a certificate and on the certificate enrollment pages.
   • To hide the field on the enrollment pages (see Enrollment), select the Hidden radio button. Selecting the Hidden option does not hide the field in the certificate details (see Metadata Tab) or on the Add Certificate page (see Add Certificate).

6. Enter a short hint in the Hint field to provide the user with a clue as to what type of data should be entered in the field. The hint appears in parentheses following the field name in places where metadata may be edited such as CSR enrollment, PFX enrollment, and the certificate details metadata tab.

7. Select the Data Type for the field in the dropdown. The available field types are String (alphanumeric), Integer (whole numbers), Date, Multiple Choice, Big Text, Email and Boolean (True/False). String fields support additional indexing, and so may be preferable for large databases where possible. The data type cannot be edited once the metadata field is saved.

   The remaining fields on the dialog—plus the Hint—will vary depending on the data type selected. Table 75: Certificate Metadata Data Type Dialog Options shows the fields that appear based on the data type selected.

   Table 75: Certificate Metadata Data Type Dialog Options

   Data Type	Character Limit	Hint	Default Value	RegEx Message	RegEx Validation	Options
   String	400 alphanumeric with indexing
   Integer	32-bit (about 10 characters)
   Date	N/A
   Boolean	N/A
   Multiple Choice	4,000
   Big Text	4,000
   Email	100 (for all entries)

   Table 76: Certificate Metadata Data Type Table Legend

   Symbol	Option Available?
   	Yes
   	No
   	Metadata table only

8. To set a default value with which to pre-populate the metadata field for new certificate requests made using the Management Portal enrollment pages, enter the desired value in the Default Value box, or, for Boolean fields, select the desired radio button. The default value option appears for string, integer, Boolean and multiple choice fields.

9. For string fields, you can choose to enter a regular expression against which entered data will be validated in the RegEx Validation field. 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 RegEx Message field. The example regular expression shown in Figure 368: Create or Edit Certificate Metadata Field is:

   ^(\([0-9]{3}\) |[0-9]{3}-)[0-9]{3}-[0-9]{4}$

   This regular expression specifies that the data entered in the field must consist of an opening parenthesis, three integers, a closing parenthesis, a space, three integers, a dash, and four integers—one popular format for a US phone number. For more examples of regular expressions, see Regular Expressions.

10. For multiple choice fields, enter the series of values that should appear in the field dropdown as a comma delimited list in the Options field.

    For example:

    Accounting,HR,IT,Marketing,Sales
    Note:  The multiple choice options are displayed in the order entered in the comma delimited list. When a user selects a multiple choice value in a metadata field while editing a certificate, the value is saved to the database as the string (e.g. Marketing). Subsequently editing the series of values for the metadata field or rearranging them will not affect existing certificates configured with values for this field.
11. Click Save to save your metadata field.

You may change the display order for metadata fields. This affects how the fields display on the certificate details, certificate template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. details when configuring the metadata tab, and on enrollment pages.

To change the display order of a metadata field:

1. Browse to System Settings Icon > Certificate Metadata.
2. Right-click a grid row and choose Move from the right-click menu, or highlight the row in the grid and click Move at the top of the grid.

3. In the Display Order dialog enter the desired display order number and click Save. The value entered must fall without the current display order range. For example, if the current range is 0-12, enter 12 to move a field to the end of the list, not 13. The metadata field will move to the entered display order row and the metadata fields from the rows above and below will be re-ordered.

   

   Figure 369: Metadata Display Order

Metadata fields cannot be deleted if they are associated with any certificate values.

To delete a metadata field:

1. Browse to System Settings Icon > Certificate Metadata.
2. Right-click a grid row and choose Delete from the right-click menu, or highlight the row in the grid and click Delete at the top of the grid.