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.
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
.
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:
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
To only allow certificates with
DNS
-type SANs, execute followinggcloud
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:
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
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.