Creating certificate templates

This topic describes how you can create a certificate template. For an overview of certificate templates, see Certificate templates.

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

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

Granting 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 Permissions and roles.

What's next

• Learn more about certificate templates.
• Learn more about certificate profiles.
• Learn how to use CEL.