Skip to main content

Subject alternative names (SAN)

SAN allows you to define the subject alternative name extensions in the certificate.

You can use the JSON template for each type of SAN entry to specify inclusion rules, define automatic inclusion based on the common name, and determining the data sources—including Certificate Signing Requests (CSR), predefined values, or user input. This configuration offers the flexibility needed to meet specific security standards and manage SAN fields effectively during certificate issuance.

The provided JSON examples details how to configure Subject Alternative Names (SAN) for a certificate template, covering various data types such as DNS names, IP addresses, and email addresses.

JSON structure examples

DNS name, IP address, UPN, email, URI and registered ID

"extensions": {
  "san": {
    "critical": false,
    "dns_name": {
      "include": "yes",
      "auto_include_cn": "no",
      "allowed_source": [
        "csr",
        "fixed_value",
        "user_supplied"
      ]
    },
    "ip_address": {
      "include": "yes",
      "allowed_source": [
        "csr",
        "fixed_value",
        "user_supplied"
      ]
    },
    "user_principal_name": {
      "include": "yes",
      "allowed_source": [
        "csr",
        "fixed_value",
        "user_supplied"
      ]
    },
    "email": {
      "include": "yes",
      "allowed_source": [
        "csr",
        "fixed_value",
        "user_supplied"
      ]
    },
    "uri": {
      "include": "yes",
      "allowed_source": [
        "csr",
        "fixed_value",
        "user_supplied"
      ]
    },
    "registered_id": {
      "include": "yes",
      "allowed_source": [
        "csr",
        "fixed_value",
        "user_supplied"
      ]
    }
  }
}

Other name hardware module name

"extensions": {
  "san": {
    "critical": false,
    "other_name": {
      "required_types": [
        "hardware_module_name"
      ],
      "hardware_module_name": {
        "type": "1.2.240.458.10003.3.12",
        "serial_num": "aabbcc001122"
      },
    }
  }
}

Other name raw types

"extensions": {
  "san": {
    "critical": false,
    "other_name": {
      "required_raw_types": [
        "1.2.3.456.7890.1",
        "1.2.3.456.7890.2"
      ],
      "optional_raw_types": [
        "1.2.3.456.7890.3",
        "1.2.3.456.7890.4"
      ]
    }
  }
}

Parameters

Tabelle 1. Parameters: SAN

Name

Type

Required/optional

Possible values

san

Object

Optional

-

.. critical

Boolean

Optional

Specifies whether the SAN extension is marked as critical. Supported values include:

  • true: Marks the SAN extension as critical

  • false: Does not mark the SAN extension as critical

.. dns_name

Object

Optional

-

.. include

String

Optional

Specifies whether DNS names are included in the SAN extension. Supported values include:

  • yes: Always includes DNS names in the certificate

  • optional: Includes DNS names when values are provided

  • no: Excludes DNS names from the certificate

.. .. auto_include_cn

String

Optional

Specifies whether the Common Name (CN) is automatically added as a DNS name. Supported values include:

  • top: Adds the CN as the first DNS name

  • bottom: Adds the CN as the last DNS name

  • no: Does not add the CN.

.. .. allowed_source

Array of strings

Required

Specifies the allowed sources for DNS name values. Supported values include:

  • csr: Uses values from the certificate signing request (CSR)

  • user_supplied: Allows values to be provided in the enrollment request. Supported only for API, Portal, and Batch enrollment methods

  • fixed_value: Uses values defined in the certificate template when no CSR or request value is provided

.. ip_address

Object

Optional

-

.. .. include

String

Specifies whether IP addresses are included in the SAN extension. Supported values include:

  • yes: Always includes IP addresses in the certificate

  • optional: Includes IP addresses when values are provided

  • no: Excludes IP addresses from the certificate.

.. .. allowed_source

Array of strings

 

Specifies the allowed sources for IP address values. Supported values include:

  • csr

  • user_supplied

  • fixed_value

.. user_principal_name

Object

Optional

-

.. .. include

String

Optional

Specifies whether UPN values are included in the SAN extension. Supported values include:

  • yes

  • optional

  • no

.. .. allowed_source

Array of strings

Required

Specifies the allowed sources for UPN values. Supported values include:

  • csr

  • user_supplied

  • fixed_value

.. email

Object

Optional

-

.. .. include

String

Optional

Specifies whether email addresses are included in the SAN extension. Supported values include:

  • yes

  • optional

  • no

.. .. allowed_source

Array of strings

Required

Specifies the allowed sources for email address values. Supported values include:

  • csr

  • user_supplied

  • fixed_value

.. uri

Object

Optional

-

.. .. include

String

Optional

Specifies whether URI values are included in the SAN extension. Supported values include:

  • yes

  • optional

  • no

.. .. allowed_source

Array of strings

Required

Specifies the allowed sources for URI values. Supported values include:

  • csr

  • user_supplied

  • fixed_value

.. .. allowed_source

Array of strings

Required

Specifies the allowed sources for URI values. Supported values include:

  • csr

  • user_supplied

  • fixed_value

.. .. allowed_source

Array of strings

Required

Specifies the allowed sources for URI values. Supported values include:

  • csr

  • user_supplied

  • fixed_value

.. registered_id

Object

Optional

-

.. .. include

String

Optinal

Specifies whether Registered ID values are included in the SAN extension. Supported values include:

  • yes

  • optional

  • no

.. .. allowed_source

Array of strings

Required

Specifies the allowed sources for Registered ID values. Supported values include:

  • csr

  • user_supplied

  • fixed_value

.. other_name

Object

Optional

-

.. .. required_raw_types

Array of strings

Required (for raw Other Name values)

Specifies the OIDs that must be present in the raw Other Name input

Anmerkung

Use this property only when defining a raw Other Name value

.. .. optional_raw_types

Array of strings

Optional

Specifies the OIDs that must be present in the raw Other Name input

Anmerkung

Use this property only when defining a raw Other Name value

.. .. required_types

Array of strings

Required (for hardware modules)

Specifies the OIDs that must be present in the Other Name value. The list must include hardware_module_name.type

Anmerkung

Use this property only when defining a hardware module name

.. .. hardware_module_name

Object

Optional

-

.. .. .. type

String

Required

Specifies the OID that identifies the hardware module type

.. .. .. serial_num

String

Optional

Specifies the hardware module serial number as a hexadecimal-encoded binary value


In diesem Abschnitt: