Certificate Authority Service provides predefined certificate templates to help streamline and secure the certificate issuance process. By offering pre-configured sets of X.509 parameters for common use cases, these ready-made templates simplify certificate management, reduce the risk of human error, and enforce security best practices. Each template is designed for a specific use case to make sure that certificates are issued with the correct parameters for their intended purpose, while also respecting any limitations set by the issuing certificate authority (CA).
This document is for audiences within the application operator group, such as application developers or data scientists, who manage certificate lifecycles within their project. For more information, see Audiences for GDC air-gapped documentation.
Apply a certificate template
To apply a template, specify the template's name in the certificateTemplate
field of your CertificateRequest resource. CA Service applies the parameters
from the chosen template to the issued certificate.
For detailed guidance on how to structure the CertificateRequest resource and
include the certificateTemplate field, see
Request a certificate.
Certificate template types
The following predefined certificate templates are available. Each template is designed for a specific use case and pre-configures the X.509 parameters that the template enforces.
In the template descriptions below, any parameters not explicitly set by the
template are taken from the CertificateRequest resource, whether provided in a
Certificate Signing Request (CSR) or fields you define.
Default
Template name: default
This template is automatically used if you don't specify a certificate template
in your CertificateRequest resource. The issued certificate inherits Key
usage and Extended key usage settings from the issuing CA's profile, and sets
Basic constraints to CA:FALSE, preventing the certificate from being used to
sign other certificates.
| X509 parameter | Value |
|---|---|
| RawSubject | [User defined SubjectOverride or Passthrough from CSR] |
| Basic constraints | CA:FALSE |
| Subject alternative name | [Passthrough from CSR] |
| Key usage | [Key usage set in CA] |
| Extended key usage | [Extended key usage set in CA] |
Client TLS certificates
Template name: endEntityClientAuthCertificate
This template issues end-entity certificates for client-side TLS authentication.
The issued certificate sets Extended key usage to TLS web client
authentication, and Basic constraints to CA:FALSE, preventing the
certificate from being used to sign other certificates.
| X509 parameter | Value |
|---|---|
| RawSubject | [User defined SubjectOverride or Passthrough from CSR] |
| Basic constraints | CA:FALSE |
| Subject alternative name | [Passthrough from CSR] |
| Key usage | Critical, digital signature, key encipherment |
| Extended key usage | TLS web client authentication |
Server TLS certificates
Template name: endEntityServerAuthCertificate
This template issues end-entity certificates for server-side TLS authentication,
which is ideal for use with web servers. The issued certificate sets Extended
key usage to TLS web server authentication, and Basic constraints to
CA:FALSE, preventing the certificate from being used to sign other
certificates.
| X509 parameter | Value |
|---|---|
| RawSubject | [User defined SubjectOverride or Passthrough from CSR] |
| Basic constraints | CA:FALSE |
| Subject alternative name | [Passthrough from CSR] |
| Key usage | Critical, digital signature, key encipherment |
| Extended key usage | TLS web server authentication |
Subordinate CA certificates (PathLen 0)
Template name: blankSubCACertificate_PathLen0_CSRPassthrough
This template issues subordinate CA certificates with a path length constraint of 0, which allows the certificate to sign end-entity certificates but not other CA certificates.
| X509 parameter | Value |
|---|---|
| RawSubject | [User defined SubjectOverride or Passthrough from CSR] |
| Basic constraints | CA:TRUE, pathlen: 0 |
| Subject alternative name | [Passthrough from CSR] |
| Key usage | [Key usage set in CSR] |
| Extended key usage | [Extended key usage set in CSR] |
Subordinate CA certificates (PathLen 1)
Template name: blankSubCACertificate_PathLen1_CSRPassthrough
This template issues subordinate CA certificates with a path length constraint of 1, which allows the certificate to sign end-entity certificates as well as other subordinate CA certificates that have a path length of 0.
| X509 parameter | Value |
|---|---|
| RawSubject | [User defined SubjectOverride or Passthrough from CSR] |
| Basic constraints | CA:TRUE, pathlen: 1 |
| Subject alternative name | [Passthrough from CSR] |
| Key usage | [Key usage set in CSR] |
| Extended key usage | [Extended key usage set in CSR] |
Conflict detection
Each CA has a profile that defines the types of certificates it's allowed to
issue. For example, a CA might be restricted to only issuing client
authentication certificates. The CA's profile is configured within the
certificateProfile section of the CertificateAuthority resource when
the CA is created, as detailed in
Create a root certificate authority
and
Create a subordinate certificate authority.
When you request a certificate using a predefined template, CA Service validates
the template's parameters against the issuing CA's configuration. To be valid,
the X.509 parameters defined in the chosen template must be a subset of those
permitted by the issuing CA according to its certificateProfile. A conflict
occurs if the template requests attributes or permissions that the CA isn't
authorized to grant. For example, a template can't request an
Extended key usage (EKU) of serverAuth if the issuing CA is only authorized
to grant clientAuth.
If CA Service detects such a conflict, the CertificateRequest fails. You can
inspect the status of the CertificateRequest resource to understand the reason
for the failure.
Example
In the following scenario, a CA named client-certs-ca is configured to issue
certificates only for client authentication. Its certificateProfile specifies
that the only allowed Extended key usage is TLS web client authentication.
You submit the following CertificateRequest to issue a certificate for a
server, using the endEntityServerAuthCertificate template:
apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
name: server-cert-req
namespace: my-project
spec:
certificateAuthorityRef:
name: client-certs-ca
namespace: my-project
csr: "..."
certificateTemplate: endEntityServerAuthCertificate
signedCertificateSecret: server-cert-secret
This request fails due to the following:
- The
endEntityServerAuthCertificatetemplate requires the EKUTLS web server authentication. - The issuing CA,
client-certs-ca, has acertificateProfilethat only permits the EKUTLS web client authentication.
Since the EKU required by the template isn't included in the list of EKUs allowed by the CA's profile, the template's requirements aren't a subset of the CA's permitted parameters. The request is therefore rejected.