Create a certificate template

This page describes the attributes of a certificate template and explains how you can create a certificate template.

Overview of certificate templates

Certificate Authority Service provides reusable and parameterized templates that you can use for common certificate issuance scenarios. A certificate template represents a relatively static and well-defined certificate issuance schema within an organization. The CertificateTemplate resource includes the following.

1. A Common Expression Language (CEL) expression that is evaluated against the requested subject and SANs in all certificate requests that use the template. For more information about using CEL, see Using CEL.
2. An allowlist specifying whether the subject or subject alternative name can be copied from the end-user request to the issued certificate.
3. An optional allowlist specifying which X.509 extensions, if any, can be copied from the end-user request to the issued certificate.
4. An optional set of X.509 extension values that are added to all the issued certificates that use the template.

A certificate template can essentially become a full-fledged vertical certificate issuance framework. For more details, see the full CertificateTemplate message definition.

Predefined values in a certificate template

The predefined values in a certificate template are added to all the certificates that use the certificate template. They allow creating common certificate issuance scenarios, such as mTLS or code signing. The values include the following:

• Key usages: Specifies the base key usage for a certificate according to RFC 5280 section 4.2.1.12.
• Extended key usages: Specifies the extended key usage for a certificate according to RFC 5280 section 4.2.1.3.
• If the certificate is a CA: Specifies if the certificate can issue additional certificates or whether it's an end-entity certificate.
• Max issuer path length: In the case of a CA, it specifies the maximum number of CAs that can be chained up to this CA certificate. If the max issuer path length is set to 0, then the CA can only issue end-entity certificates. If it's set to 1, then the chain beneath this CA certificate can include only one subordinate CA. If a value isn't declared, then the number of subordinate CAs in the chain beneath this CA is unbounded.
• AIA OCSP servers: Refers to the OCSP servers in a certificate's Authority Information Access (AIA) extension, as described in RFC 5280 section 4.2.2.1.
• Additional X.509 extensions: Describes custom X.509 extensions.

The following code sample mentions all the predefined fields in a certificate template:

keyUsage:
  baseKeyUsage:
    digitalSignature: true
    keyEncipherment: true
    contentCommitment: false
    dataEncipherment: false
    keyAgreement: false
    certSign: false
    crlSign: false
    encipherOnly: false
    decipherOnly: false
  extendedKeyUsage:
    serverAuth: true
    clientAuth: false
    codeSigning: false
    emailProtection: false
    timeStamping: false
    ocspSigning: false
caOptions:
  isCa: true
  maxIssuerPathLength: 1
policyIds:
- objectIdPath:
  - 1
  - 2
  - 3
additionalExtensions:
- objectId:
    objectIdPath:
    - 1
    - 2
    - 3
  critical: false
  value: "base64 encoded extension value"

Values not specified in the YAML are either omitted or defaulted to false.

The following extensions are omitted if a value isn't specified:

• keyUsage
• policyIds
• additionalExtensions
• maxIssuerPathLength field in the caOptions extension

The following extensions default to false if a value isn't specified:

• isCa field in the caOptions extension

Create a certificate template

To create a certificate template, use the following gcloud command:

gcloud

gcloud privateca templates create TEMPLATE_ID \
  --copy-subject \
  --copy-sans \
  --identity-cel-expression <expr> \
  --predefined-values-file FILE_PATH \
  --copy-all-requested-extensions \
  --copy-extensions-by-oid <1.2.3.4,5.6.7.8> \
  --copy-known-extensions <ext1,ext2>

Replace the following:

• TEMPLATE_ID: the unique identifier of the certificate template.
• FILE_PATH: the YAML file that describes the X.509 values set by the certificate template.

The --copy-sans flag allows the Subject Alternative Name (SAN) extension from the certificate request to be copied into the signed certificate. You can alternatively specify --no-copy-sans to drop any caller specified SANs from the certificate request.

The --copy-subject flag allows the Subject from the certificate request to be copied into the signed certificate. You can alternatively specify --no-copy-subject to drop any caller specified subjects from the certificate request.

Note: If you want to ensure that a template must be used with identity reflection, specify the --no-copy-subject and --no-copy-sans flags together. For more information about identity reflection, see Identity reflection.

The --identity-cel-expression flag takes a CEL expression that is evaluated against the Subject and Subject Alternative Name of the certificate before it is issued, and returns a boolean signifying whether the request should be allowed. For information about using a Common Expression Language (CEL) expression for a certificate template, see Using CEL for certificate templates.

The --predefined-values-file flag specifies the path to a YAML file describing any predefined X.509 values set by this template. The provided extensions are copied over to any certificate requests that use this template, taking precedence over any allowed extensions in the certificate request. If you update any part of the predefined X.509 values, the update replaces the entire set of the predefined X.509 values.

If the --copy-all-requested-extensions flag is set, all the extensions specified in the certificate request are copied into the signed certificate. Alternatively the --copy-extensions-by-oid flag can be used to copy specific OIDs from the certificate request into the signed certificate and the --copy-known-extensions flag can be used to copy extensions from the certificate request into the signed certificate. Must be one of: base-key-usage, extended-key-usage, ca-options, policy-ids, aia-ocsp-servers.

Note: The tag --copy-all-requested-extensions flag is mutually exclusive from --copy-known-extensions and --copy-extensions-by-oid flags.

Remove the --copy-all-requested-extensions flag to ignore all X.509 extensions in the certificate request, but still keep predefined values defined in this template.

Note: If you delete resources such as CA pools, certificate authorities, and certificate templates, you will not be able to create a new resource of that type with the same name in the same project and location.

Create a certificate template for common scenarios

This section provides gcloud commands for creating a certificate template for common use cases.

DNS server TLS certificates for any domain

To create a certificate template for issuing server TLS certificates that allow any domain, use the following instructions:

1. Create a file with the name leaf_server_tls_values.yaml and add the following end-entity server TLS configuration to it:

   leaf_server_tls_values.yaml

   keyUsage:
     baseKeyUsage:
       digitalSignature: true
       keyEncipherment: true
     extendedKeyUsage:
       serverAuth: true
   caOptions:
     isCa: false
   

2. To only allow certificates with DNS-type SANs, execute following gcloud command:

   gcloud

   gcloud privateca templates create server-tls \
     --predefined-values-file leaf_server_tls_values.yaml \
     --copy-sans --no-copy-subject \
     --identity-cel-expression "subject_alt_names.all(san, san.type == DNS)"
   

   For more information about the gcloud privateca templates create command, see gcloud privateca templates create.

DNS server TLS certificates with only test domains

To create a certificate template for issuing server TLS certificates with DNS SANs limited to test domains, use the following gcloud command:

gcloud

gcloud privateca templates create server-tls \
  --predefined-values-file leaf_server_tls_values.yaml \
  --copy-sans --no-copy-subject \
  --identity-cel-expression "subject_alt_names.all(san, san.type == DNS && san.value.endsWith('.test.example.com'))"

The contents of the leaf_server_tls_values.yaml file must be the same as the previous example.

For more information about using CEL expressions to ensure DNS names start or end with a particular string, see CEL example expressions.

Workload identity certificates

To create a certificate template for issuing mutual TLS (mTLS) certificates, use the following instructions:

1. Create a file with the name leaf_mtls_values.yaml and add the following end-entity mutual TLS configuration to it.

   leaf_mtls_values.yaml

   keyUsage:
     baseKeyUsage:
       digitalSignature: true
       keyEncipherment: true
     extendedKeyUsage:
       serverAuth: true
       clientAuth: true
   caOptions:
     isCa: false
   

2. To only allow certificates with SPIFFE URI SANs, use the following gcloud command:

   gcloud

   gcloud privateca templates create workload-spiffe \
     --predefined-values-file leaf_mtls_values.yaml \
     --copy-sans --no-copy-subject \
     --identity-cel-expression "subject_alt_names.all(san, san.type == URI && san.value.startsWith('spiffe://'))"
   

   For more information about the gcloud privateca templates create command, see gcloud privateca templates create.

For more information about using CEL expressions to ensure DNS names start or end with a particular string, see CEL example expressions.

Grant access to the certificate template

You can use a certificate template if you have the CA Service Certificate Template User (roles/privateca.templateUser) role. We recommend that the authors of a certificate template grant the CA Service Certificate Template User role to the members in the organization who might use that certificate template.

To grant the CA Service Certificate Template User (roles/privateca.templateUser) role to everyone in the example.com domain, use the following gcloud command:

gcloud

gcloud privateca templates add-iam-policy-binding TEMPLATE_ID \
  --member "domain:example.com" \
  --role "roles/privateca.templateUser"

Replace the following:

• TEMPLATE_ID: the unique identifier of the certificate template.

For more information about the gcloud privateca templates add-iam-policy-binding command, see gcloud privateca templates add-iam-policy-binding.

For more information about IAM roles for CA Service, and their associated permissions, see Access control with IAM.

What's next

• Learn about Common Expression Language.
• Learn how to use Common Expression Language.
• Learn about certificate profiles.