创建证书模板

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

证书模板概览

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:描述证书模板设置的 X.509 值的 YAML 文件。

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

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

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

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

如果设置了 --copy-all-requested-extensions 标志,则证书请求中指定的所有扩展都会复制到已签名的证书中。此外,--copy-extensions-by-oid 标记可用于将证书请求中的特定 OID 复制到已签署的证书中,--copy-known-extensions 标记可用于将证书请求的扩展复制到已签署证书中。必须是以下各项之一:base-key-usageextended-key-usageca-optionspolicy-idsaia-ocsp-servers

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

针对常见场景创建证书模板

本部分提供了用于针对常见用例创建证书模板的 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 templates create

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

创建用于通过 DNS 颁发服务器 TLS 证书的证书模板 仅限测试网域的 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 示例表达式

Workload Identity 证书

要创建用于颁发双向 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 templates create

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

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

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

如需向 example.com 网域中的所有用户授予 CA Service Certificate Template User (roles/privateca.templateUser) 角色,请使用以下 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 templates add-iam-policy-binding

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

后续步骤