关于 Apigee 根 CA 证书和轮替

本页面适用于 Apigee，但不适用于 Apigee Hybrid。

查看 Apigee Edge 文档。

本页介绍了用于保护与 Apigee 运行时之间的 TLS 连接的 Apigee 根证书授权机构 (CA) 证书，并说明了轮换流程。本文档还列出了受轮换影响的访问模式，以及您应采取的准备应用步骤。

根 CA 证书简介

每个 Apigee 组织都有一个由 Google 管理的根 CA 证书，该证书会颁发 Apigee 运行时入站网关用于 TLS 终结的服务器证书。当客户端打开与 Apigee 实例的 HTTPS 连接时，服务器会提供链接到此根 CA 的证书。验证服务器证书的客户端必须信任根 CA，无论是隐式（当流量流经终止 TLS 的客户管理的负载均衡器时）还是显式（当客户端直接连接到 Apigee 运行时时）。

根 CA 证书在 organizations.get API 响应的 caCertificates[] 字段中公开。该字段是一个数组，因为在轮替期间，系统会同时返回当前根 CA 证书和即将到来的根 CA 证书，以便客户端在割接之前信任这两个证书。

为什么要轮换根 CA 证书

Apigee 根 CA 证书的有效期较长，但有限（通常为 10 年）。在证书过期之前轮替证书，以便：

  • 在 Apigee 运行时使用的安全证书永不过期。
  • Apigee 组件之间的内部通信渠道继续正常运行，不会中断。

轮换是一项常规的计划内操作。Apigee 会按照 Google Cloud 控制的时间表运行该作业。您不会启动轮换，并且轮换本身不会更改 Apigee 运行时端点或 Apigee API 表面。

轮替阶段和时间表

Apigee 会分四个阶段轮换根 CA 证书。每个阶段都是循序渐进的：它会先在您组织中的一个区域应用，然后逐步扩展到其他区域，因此需要一段时间才能完成。下表介绍了每个阶段对客户的影响以及每个阶段的典型开始时间（相对于当前根 CA 的到期日期）。

阶段 典型时间安排 caCertificates[] 中包含的内容 具体变化
1. 新证书已发布 在当前证书失效前大约 1 年 当前和新（两者） Apigee 会生成新的根 CA 证书，并将其添加到每个 Apigee 自有组件的信任库中。新证书也会显示在 organizations.get 响应中，以便您提取并暂存该证书。Apigee 运行时会继续提供由当前根 CA 签名的服务器证书，因此现有客户端暂时不受影响。Apigee 会在开始此阶段时向客户发送通知。
2. 叶证书割接 当前证书到期前大约 60 天 当前和新（两者） Apigee 运行时开始提供由新根 CA 签名的新服务器（叶）证书。仅信任当前根 CA 的客户端在所在区域完成此阶段后，将无法通过 TLS 验证。信任这两个证书（或仅信任新证书）的客户端会继续正常运行。当此阶段开始时，Apigee 会向客户发送通知。
3. 旧证书已撤销 在当前证书到期前大约 30 天 仅限新商品 Apigee 会从内部信任库中移除旧的根 CA，并停止从 organizations.get 返回该根 CA。 仍仅信任旧根 CA 的客户端无法连接。 Apigee 会在开始此阶段时向客户发送通知。
4. 轮替完成 在原失效日期 仅限新商品 Apigee 会永久删除旧根 CA，轮替完成。新根 CA 现在是唯一的根 CA，并且新的大约 10 年周期开始。当此阶段完成时，Apigee 会向客户发送通知。

轮替会影响哪些人

轮替是否需要您采取行动取决于客户端访问 Apigee 运行时的方式：

访问模式 需要采取行动？ 原因
通过 Google Cloud 外部应用负载均衡器实现外部路由 (MIG) 否 外部负载均衡器使用您管理的证书终止 TLS。客户端信任您的证书，而不是 Apigee 根 CA。轮换对这些客户端没有任何影响。
内部路由 (VPC)、TLS 选项 1（内部 HTTPS 应用负载均衡器） 否 您的内部负载均衡器使用您管理的证书终止 TLS。客户端信任您的证书，而不是 Apigee 根 CA。轮换对这些客户端没有任何影响。
内部路由 (VPC)，TLS 选项 2（内部默认完全限定域名） 是 客户端直接连接到 Apigee 管理的内部负载均衡器，并验证 Apigee 颁发的服务器证书。每个客户端都必须在轮替割接之前信任新的根 CA。
直接通过 TCP 连接到运行时实例入口 IP（例如，通过内部 TCP 负载均衡器） 是 客户端验证 Apigee 颁发的服务器证书。 每个客户端都必须在轮替割接之前信任新的根 CA。
非 TLS 选项（curl -k 标志，或跳过证书验证的任何客户端） 否 客户端不验证服务器证书，因此轮替没有实际效果。在测试环境之外，不建议使用此选项。

如何为轮替做好准备

如果您使用的访问模式需要采取行动，请在轮换通知中收到的轮换割接日期之前，按照以下步骤操作。

第 1 步：发现 Apigee 运行时实例

列出组织中的 Apigee 运行时实例。每个实例都有一个专用入站 IP，即直连客户端到达的主机。

# Ensure $AUTH and $PROJECT_ID are set in your environment
curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances \
  | jq -r '.instances[] | "\(.name)\t\(.host)"'

如果您的客户端连接到这些 IP 以外的主机（例如，内部负载均衡器前面的自有 DNS 名称），请改用该主机。

第 2 步：获取当前和即将推出的根 CA 证书

从 organizations.get 读取 caCertificates[] 字段。在轮换期间，此数组包含当前根 CA 和新根 CA，每个根 CA 都采用 base64 编码：

curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID \
  | jq -r '.caCertificates[]' \
  | awk '/-----BEGIN/{i++}{print > ("ca_" i ".b64")}'

将每个条目解码为 PEM 格式，并检查有效期以确定新证书：

for f in ca_*.b64; do
  base64 -d "$f" > "${f%.b64}.crt"
  echo "==> ${f%.b64}.crt"
  openssl x509 -in "${f%.b64}.crt" -noout -subject -issuer -dates
done

notAfter 日期较晚的证书是新的根 CA。

第 3 步：将新根 CA 添加到信任库

将新的根 CA 证书添加到当前信任 Apigee 根 CA 的每个客户端信任库。在割接完成之前，请保留当前根 CA，以便连接在割接窗口期间继续正常运行。割接后，您可以从信任库中移除旧的根 CA。

具体步骤取决于客户端。常见情况包括：

  • 将证书添加到操作系统级信任库（例如，在基于 Debian 的系统上运行 /etc/ssl/certs/，然后运行 update-ca-certificates）。
  • 将证书添加到应用管理的信任库（例如，Java cacerts 密钥库、Nginx ssl_trusted_certificate 软件包或 Envoy validation_context 信任软件包）。
  • 将证书添加到已装载到工作负载 Pod 中的 Kubernetes Secret 或 ConfigMap。

第 4 步：验证连接是否能正常使用新的根 CA

暂存新根 CA 后，请验证在仅信任新证书的情况下，对 Apigee 运行时的 HTTPS 请求是否成功：

# Ensure $ENV_GROUP_HOSTNAME and $INTERNAL_LOAD_BALANCER_IP are set
curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert NEW_CA_FILE \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

如果此命令成功执行，则表示您的客户端已准备好进行割接。如果失败，则表示客户端尚不信任新的根 CA，请重新访问第 3 步。

示例：内部路由 (VPC)，TLS 选项 2

此示例演示了内部路由 (VPC)（TLS 选项 2）中记录的访问模式的轮替步骤，其中客户端直接连接到 Apigee 内部负载均衡器并验证 Apigee 自签名证书。这是最常受旋转影响的访问模式。

在割接之前：

  1. 获取 Apigee 内部负载均衡器的 IP： 
    export INTERNAL_LOAD_BALANCER_IP=$(curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances -s \
  | jq -r '.instances[0].host')
  2. 将当前根 CA 和新根 CA 分别提取到单独的文件中，并确定新根 CA： 
    curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID \
  | jq -r '.caCertificates[]' \
  | awk '/-----BEGIN/{i++}{print > ("ca_" i ".b64")}'

for f in ca_*.b64; do
  base64 -d "$f" > "${f%.b64}.crt"
done

# Identify the new root CA (latest notAfter):
openssl x509 -in ca_1.crt -noout -dates
openssl x509 -in ca_2.crt -noout -dates
  3. 构建一个包含当前根 CA 和新根 CA 的组合信任库，并将其用于测试请求： 
    cat ca_1.crt ca_2.crt > cacert-combined.crt

curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert cacert-combined.crt \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

    如果此请求成功，请将 cacert-combined.crt 部署为客户端信任库。合并后的信任库今天会继续验证当前证书，并在割接后验证新证书。

割接后（通常在割接日期后的几天内），通过验证仅信任新证书时连接是否仍然成功，来确认轮替：

curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert NEW_CA_FILE \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

如果此请求成功，您可以放心地从信任库中移除旧的根 CA。

通知

在每个轮换阶段开始时，Apigee 会向 Google Cloud 项目的项目所有者和组织所有者发送通知。每封通知都包含阶段名称、阶段将应用于您组织的日期，以及指向此页面的链接。

通知 建议客户采取的操作
1. 发布新证书
（在过期前约 1 年）		 从 caCertificates[] 中获取新的根 CA，并将其添加到当前信任 Apigee 根 CA 的每个客户端信任库中。请参阅如何为轮替做好准备。
2. 叶证书割接
（在失效前约 60 天）		 在将此阶段应用于您的区域之前，请确认您的所有客户端都信任新的根 CA。在此阶段之后，仅信任旧根 CA 的客户端将无法连接。
3. 旧证书被撤消
（在失效前约 30 天）		 将此阶段应用于所有区域后，您可以放心地从客户端信任库中移除旧根 CA。
4. 轮替完成
（在原始到期日期）		 无需执行任何操作。旧根 CA 已被永久删除，新根 CA 是您组织的唯一根 CA。

如果您未收到轮换通知，并且您使用的访问模式属于哪些用户会受到轮换影响中列出的模式，请与 Apigee 支持团队联系，确认您组织的通知接收者。

后续步骤