Skip to main content

Create certificate profiles with custom extensions

To use custom extensions in your certificates, you first need to create certificate profiles where you define templates for the custom extension data.

You can create profiles with custom extensions for user, device, and server certificates issued from private certificate authorities (CAs) in DigiCert ONE CA Manager.

Create the profile

Follow the usual steps to create the certificate profile, making sure to select one of the base templates and enrollment methods that support custom extensions as explained below:

  1. From the Trust Lifecycle Manager main menu, select Policies > Certificate profiles.

  2. Select the Create profile from template button at top.

  3. Choose one of the following certificate templates as the basis for creating the certificate profile:

    • Generic Device Certificate

    • Generic Private Server Certificate

    • Generic User Certificate

  4. On the initial screens, define basic profile and certificate properties and select your issuing CA, enrollment method, and authentication method (if applicable).

  5. On the Extensions screen, define and verify the Custom extensions for this certificate profile. See Define a custom extension below for more details about this step.

  6. As long as your custom extensions pass the verification check, you can select Next to progress through the remaining profile screens and then select Create to save the new profile.

Define a custom extension

You define custom certificate extensions on the profile Extensions screen, in the Custom extensions section:

  • Add your custom extension templates in JSON format in the left window. We provide an example to help guide you.

  • Select Verify to make sure your JSON is valid:

    • If valid, dynamic custom extension fields get added to the right window so you can finalize the configuration.

    • If not valid, check the validation errors below the window for more information. Fix your JSON and try again.

  • Select Clear if you want to clear out the current JSON and start from scratch.

Consider the following example JSON template for a custom extension:

Example 1. JSON template for a custom certificate extension
{
    "oid": "1.2.3.4",
    "critical": true,
    "template": {
      "type": "SEQUENCE",
      "structure": [
        {
          "type": "PrintableString",
          "value": "${string_value}"
        },
        {
          "type": "BOOLEAN",
          "value": "${boolean_value}"
        },
        {
          "type": "INTEGER",
          "value": 1
        }
      ]
    }
}

This example defines a single custom extension with object identifier (OID) 1.2.3.4 and criticality set to true. The template defines the custom extension as having data type SEQUENCE with a structure consisting of a flat collection of fields of different data types.

Notice

See Data types and example templates for custom extensions for more detailed information about custom extension data types and templates.

Use the following fields to create JSON templates for your own custom extensions:

  • oid: Define the OID for the custom extension as a series of dot-separated integers (nodes). Avoid OIDs starting with 2.5.29 as they are used by standard X.509 certificate extensions.

  • critical: Mark the importance of the custom extension by setting this boolean field to true (critical) or false (not critical).

  • template: Define the data that can be contained in the custom extension:

    • type: The overall data type definition for the custom extension.

    • structure: Used with data types SEQUENCE, SEQUENCE OF, or SET OF to define a data structure that consists of a collection of other data types.

    • value: Used with data types other than SEQUENCE, SEQUENCE OF, or SET OF to provide a placeholder name for the field to be filled in during enrollment (most common) or a fixed value to apply to all certificates issued from the profile. Specify placeholder names for extension fields in the format: ${name}.

      Caution

      Placeholder names can be reused for multiple fields as long as the data type is the same for all. The placeholder name is targeted during enrollment to supply a value for each extension field. All fields with the same placeholder name get the same value.

      The placeholder name can include a mix of alphanumeric characters or underscores. It cannot include dots.

After entering the template, select the Verify button to validate the JSON. Address any validation errors and try again if needed.

Once validated, any dynamic custom extension fields appear in the right window so you can finalize the extension configuration.

Define multiple custom extensions

To define multiple custom extensions, use a JSON array in the Custom extensions section of the certificate profile. For example:

Example 2. JSON template for certificates with two possible custom extensions
[
    {
        "oid": "1.2.8.8",
        "critical": true,
        "template": {
          "type": "INTEGER",
          "value": "${user_id}"
        }
    },
    {
        "oid": "1.2.8.9",
        "critical": false,
        "template": {
          "type": "PrintableString OPTIONAL",
          "value": "${user_work_location}"
        }
    }
]

This example defines two different custom extensions:

  1. A critical extension with OID 1.2.8.8. The extension consists of a simple integer value with placeholder name user_id.

  2. A non-critical extension with OID 1.2.8.9. The extension consists of a simple string value with placeholder name user_work_location. Note the word OPTIONAL after the data type. This marks the field as optional, so a value never has to be supplied during enrollment.

As usual, after defining your custom extensions in the left window, select Verify to validate the JSON and then finalize the extension configuration in the right window.

Notice

See Data types and example templates for custom extensions for more detailed information about custom extension data types and templates.

Finalize the extension configuration

After validating your custom extension templates with the Verify button, any extension fields that require additional configuration are listed in the right window by their placeholder names.

To finalize the configuration of these extension fields, you must indicate how to supply values for them during certificate enrollment or authentication. Fields with fixed values do not require additional configuration.

Use the inputs in the right window to finalize the configuration of the dynamic custom extension fields:

  • Field label in web displays: Add a user-friendly text label to identify the custom extension field in web forms. This input only appears for profiles configured for web-based enrollment methods.

  • Source for the field's value: Select one of the provided options for how the field value will be provided during the certificate enrollment or authentication process. Options here depend on the enrollment or authentication method you have chosen for the certificate profile. Possible options are:

    • Active Directory attribute: Get the value from Active Directory (AD). This is the default selection for profiles configured with the Microsoft Autoenrollment enrollment method. An additional dropdown appears so you can select the specific AD attribute to get the value from.

    • REST request: Supply the value via the Trust Lifecycle Manager REST API by targeting the placeholder name in the JSON request body. See Use the REST API to request certificates with custom extensions for more details.

    • Entered/uploaded by Admin: Administrators will be prompted to supply a value when submitting an enrollment request via the Trust Lifecycle Manager user interface (for example, when enrolling a seat).

    • Entered by User: Users will be prompted to supply a value when confirming an enrollment via the Trust Lifecycle Manager user interface (for example, when using an enrollment code to authenticate and obtain a new certificate).

    • From CSR: The value will be taken from another field in the CSR, as identified by its standard X.509 object identifier (OID). When you select this option, an additional input appears so you can enter the OID for the CSR field to get the value from. For example, enter the OID 2.5.4.6 to assign the country name from the CSR as the value of the custom extension field.

    • EST request: Supply the value in a CSR submitted to DigiCert via the Enrollment over Secure Transport (EST) protocol. When you select this option, you must enter the OID for the CSR field to get the value from, like with the From CSR option.

    • SCEP request: Supply the value in a CSR submitted to DigiCert via the Simple Certificate Enrollment Protocol (SCEP). When you select this option, you must enter the OID for the CSR field to get the value from, like with the From CSR option.

    • SAML assertion: For profiles that use SAML IdP as the authentication method, obtain the value from the SAML provider. The name of the extension field must match what's sent by the SAML provider inside the SAML assertion.

What's next

After creating a certificate profile with custom extensions, you are ready to enroll certificates from that profile using the selected enrollment method.

For information about how to supply values to custom extension fields using the Trust Lifecycle Manager REST API, see Use the REST API to request certificates with custom extensions.

For UI-based enrollment methods, the administrator submitting the request or user confirming it will be presented with any custom extensions they need to supply values for.

In this section: