创建证书模板

本页面介绍了证书模板的属性，并说明了如何创建证书模板。

证书模板概览

Certificate Authority Service 提供可重复使用且参数化的模板，可用于常见的证书颁发场景。证书模板代表组织内一个相对静态且定义明确的证书颁发架构。CertificateTemplate 资源包含以下内容。

1. 一个通用表达式语言 (CEL) 表达式，针对使用该模板的所有证书请求中的请求主题和 SAN 进行求值。如需详细了解如何使用 CEL，请参阅使用 CEL。
2. 一个许可名单，用于指定是否可以将主题或主题备用名称从最终用户请求复制到已颁发的证书。
3. 可选的许可名单，用于指定可从最终用户请求中将哪些 X.509 扩展程序（如果有）复制到已颁发的证书。
4. 一组可选的 X.509 扩展值，添加到使用该模板的所有已颁发证书。

证书模板本质上可以成为成熟的垂直证书颁发框架。如需了解详情，请参阅完整的 CertificateTemplate 消息定义。

证书模板中的预定义值

证书模板中的预定义值会添加到使用该证书模板的所有证书中。它们允许创建常见的证书颁发场景，例如 mTLS 或代码签名。这些值包括：

• 密钥用途：根据 RFC 5280 第 4.2.1.12 节的规定，指定证书的基本密钥用途。
• 扩展密钥用途：根据 RFC 5280 第 4.2.1.3 节指定证书的扩展密钥用途。
• 如果证书是 CA：指定相应证书是否可以颁发其他证书，或者它是否为最终实体证书。
• 颁发者路径长度上限：以 CA 为例，它指定可以链接到此 CA 证书的 CA 数量上限。如果颁发者路径长度上限设置为 0，则 CA 只能颁发最终实体证书。如果设为 1，则此 CA 证书下的链只能包含一个从属 CA。如果未声明值，则此 CA 下的链中的从属 CA 的数量是无界限的。
• AIA OCSP 服务器：指证书授权信息访问 (AIA) 扩展程序中的 OCSP 服务器，如 RFC 5280 第 4.2.2.1 节中所述。
• 其他 X.509 扩展项：描述自定义 X.509 扩展项。

以下代码示例提及了证书模板中的所有预定义字段：

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"

YAML 中未指定的值会被省略或默认为 false。

如果未指定值，系统会省略以下扩展名：

• keyUsage
• policyIds
• additionalExtensions
• caOptions 扩展中的 maxIssuerPathLength 字段

如果未指定值，以下扩展程序默认为 false：

• caOptions 扩展中的 isCa 字段

创建证书模板

如需创建证书模板，请使用以下 gcloud 命令：

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>

替换以下内容：

• TEMPLATE_ID：证书模板的唯一标识符。
• FILE_PATH：YAML 文件，用于描述由证书模板设置的 X.509 值。

--copy-sans 标记允许将证书请求中的主题备用名称 (SAN) 扩展复制到已签署的证书。或者，您也可以指定 --no-copy-sans 以从证书请求中删除任何调用方指定的 SAN。

--copy-subject 标志允许将证书请求中的主题复制到已签署的证书。或者，您也可以指定 --no-copy-subject 以从证书请求中删除任何调用方指定主题。

注意 ：如果要确保模板必须与身份反射一起使用，请同时指定 --no-copy-subject 和 --no-copy-sans 标志。如需详细了解身份反射，请参阅身份反射。

--identity-cel-expression 标记接受一个 CEL 表达式，该表达式在证书颁发之前针对证书的主题和主题备用名称进行求值，并返回表示是否应允许该请求的布尔值。如需了解如何对证书模板使用通用表达式语言 (CEL) 表达式，请参阅为证书模板使用 CEL。

--predefined-values-file 标志指定 YAML 文件的路径，该文件描述了此模板设置的任何预定义 X.509 值。所提供的扩展会复制到使用此模板的所有证书请求中，其优先级高于证书请求中任何允许的扩展。如果您更新预定义 X.509 值的任何部分，此更新将替换整组预定义的 X.509 值。

如果设置了 --copy-all-requested-extensions 标志，则证书请求中指定的所有扩展都会复制到已签名的证书。或者，可以使用 --copy-extensions-by-oid 标志将证书请求中的特定 OID 复制到已签署的证书，也可以使用 --copy-known-extensions 标志将证书请求的扩展复制到已签署的证书。必须为以下项之一：base-key-usage、extended-key-usage、ca-options、policy-ids、aia-ocsp-servers。

注意 ：标记 --copy-all-requested-extensions 标记与 --copy-known-extensions 和 --copy-extensions-by-oid 标记是互斥的。

移除 --copy-all-requested-extensions 标志以忽略证书请求中的所有 X.509 扩展，但仍保留此模板中定义的预定义值。

注意 ：如果您删除 CA 池、证书授权机构和证书模板等资源，将无法在同一项目和位置创建该类型、同名的新资源。

为常见场景创建证书模板

本部分提供了用于常见用例创建证书模板的 gcloud 命令。

任何网域的 DNS 服务器 TLS 证书

如需创建证书模板，以便颁发允许任何网域的服务器 TLS 证书，请按照以下说明操作：

1. 创建一个名为 leaf_server_tls_values.yaml 的文件，并在其中添加以下最终实体服务器 TLS 配置：

   leaf_server_tls_values.yaml

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

2. 如需仅允许具有 DNS 类型的 SAN 的证书，请执行以下 gcloud 命令：

   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)"
   

   如需详细了解 gcloud privateca templates create 命令，请参阅 gcloud privateca template create。

仅包含测试网域的 DNS 服务器 TLS 证书

如需创建证书模板，以便颁发服务器 TLS 证书并将 DNS SAN 限定为测试网域，请使用以下 gcloud 命令：

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'))"

leaf_server_tls_values.yaml 文件的内容必须与上一示例相同。

如需详细了解如何使用 CEL 表达式来确保 DNS 名称以特定字符串开头或结尾，请参阅 CEL 示例表达式。

工作负载身份证书

如需创建用于颁发双向 TLS (mTLS) 证书的证书模板，请按照以下说明操作：

1. 创建一个名为 leaf_mtls_values.yaml 的文件，并向其添加以下最终实体双向 TLS 配置。

   leaf_mtls_values.yaml

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

2. 如需仅允许使用 SPIFFE URI SAN 的证书，请使用以下 gcloud 命令：

   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://'))"
   

   如需详细了解 gcloud privateca templates create 命令，请参阅 gcloud privateca template create。

如需详细了解如何使用 CEL 表达式来确保 DNS 名称以特定字符串开头或结尾，请参阅 CEL 示例表达式。

授予对证书模板的访问权限

如果您拥有 CA Service Certificate Template User (roles/privateca.templateUser) 角色，则可以使用证书模板。我们建议证书模板的作者向组织中可能会使用该证书模板的成员授予 CA Service Certificate Template User 角色。

如需将 CA Service Certificate Template User (roles/privateca.templateUser) 角色授予 example.com 网域中的所有人，请使用以下 gcloud 命令：

gcloud

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

替换以下内容：

• TEMPLATE_ID：证书模板的唯一标识符。

如需详细了解 gcloud privateca templates add-iam-policy-binding 命令，请参阅 gcloud privateca template add-iam-policy-binding。

如需详细了解 CA Service 的 IAM 角色及其关联权限，请参阅使用 IAM 进行访问权限控制。

后续步骤

• 了解通用表达式语言。
• 了解如何使用通用表达式语言。
• 了解证书配置文件。