启用 JWT 安全性而不是 mTLS

何时以及如何使用 JWT 安全性而不是 mTLS。

API Connect API Connect 子系统之间的大部分网络交互都使用 mTLS ：

管理到门户网站。
管理到分析。
管理到 API 网关。
对兼容 v5 的网关进行管理。
管理到事件网关。 Cloud Pak for Integration 只是
API 分析网关。
V5 兼容分析网关。
事件分析网关。

所有其他子系统间通信都使用 TLS。对于使用 mTLS, 的通信路由，要求所有网络基础设施，如位于 API Connect 子系统之间的负载平衡器，都必须实施 TLS 直通（而不是 TLS 终结）。

使用 JSON Web 令牌 (JWT) 安全性 (而不是 mTLS ) 允许在位于子系统之间的负载均衡器上启用 TLS 终止的网络基础结构中部署 API Connect 。 JWT 在 API Connect 子系统之间提供应用程序层安全性。此功能的典型用例是在网络边界需要对所有网络通信进行有效内容检查时。支持 JWT 安全性的通信流包括:

管理到门户网站。
管理到分析。
管理到 API 网关。
对兼容 v5 的网关进行管理。
API 分析网关。
注: 无法在 V5 兼容网关到分析消息流上使用 JWT 并禁用 mTLS 。

管理子系统在启动与其他子系统的通信时始终发送 JWT ，但缺省情况下，子系统不会验证此 JWT。启用 JWT 安全性后，子系统会通过 REST 调用 JSON 网络密钥集 (JWKS) URL 来验证 JWT。 JWKS URL 位于管理子系统的平台 REST API 上。

要在管理发起的通信中启用 JWT 验证，请更新子系统 CR 以指定 JWKS URL。要禁用 JWT 验证，请更新子系统 CR 并删除 JWKS URL 的值（不设置）。

要在网关到分析通信上启用 JWT 验证，请在 Cloud Manager UI 中注册网关时启用使用 JWT 开关。

注：

对于 OpenShift® 用户 - 本文档中的示例步骤使用命令 Kuberneteskubectl 。在 OpenShift, 使用等效的 oc 命令代替它。
若您使用的是顶级CR，则必须编辑 APIConnectCluster 该CR（即顶级CR），而非直接编辑子系统CR。
若使用顶级CR(APIConnectCluster)，请确保包含部分 spec.gateway 。如果尚未包含，则必须在添加所需属性之前先添加部分 spec.gateway 。

禁用 mTLS 并启用 JSON Web 令牌 (JWT) 安全性

如果禁用 mTLS, ，则必须启用 JWT。无法在禁用 mTLS 和 JWT 的情况下配置 API Connect 。

通过在每个子系统的定制资源 (CR) 中将 mtlsValidateClient 属性设置为 false ，可以在门户网站，网关 (用于管理到网关的通信) 和分析子系统上禁用 mTLS 。

当 mtlsValidateClient 设置为 false 时，子系统不会验证客户机的 TLS 凭证，但会检查是否存在有效的 JWT 配置。例如，要禁用 mTLS 并启用 JWT 以用于管理门户网站通信，请编辑门户网站 CR 并设置:

spec:
  mtlsValidateClient: false
  jwksUrl: <JWKS URL>

其中 <JWKS URL 是管理子系统 CR status.endpoints 部分指定的 jwksUrl 。

以在 Cloud Manager UI 中注册门户网站服务为例， JWT 的工作方式如下所示:

管理子系统与门户网站 Director 管理端点上的门户网站子系统建立 TLS 连接，并将 JWT 发送到门户网站。
在门户网站信任管理子系统之前，它首先验证它接收到的 JWT。 JWT 通过调用 JSON 网络密钥集 (JWKS) URL 进行验证。
管理子系统在其平台 REST API 上从门户网站接收 JWT 验证请求，并响应 JWT 有效。
门户网站接收到 JWT 有效的确认，因此它可以信任管理子系统并继续注册过程。

要对管理启动的通信禁用 JWT 安全性，请从 CR 中除去 jwksUrl 属性，或者将其值留空。如果禁用 JWT ，那么必须通过将 mtlsValidateClient 设置为 true 来启用 mTLS 。

要禁用网关到分析通信的 JWT 安全性，请在 Cloud Manager UI 的 " 拓扑 " 页面中禁用已注册网关的使用 JWT 开关。

配置 JWKS URL

JWKS URL 定义为平台 API 主机名，并附加以下子路径： api/cloud/oauth2/certs 。例如，您可以从管理 CR 的 status.endpoints 部分查看 JWKS URL ：

status:
...
  endpoints:
...
    - name: jwksUrl
      secretName: api-endpoint
      type: API
      uri: https://api.apic.acme.com/api/cloud/oauth2/certs

注: JWT 功能适用于位于子系统之间的负载均衡器所在的环境。如果要使用集群内通信功能部件使用服务而不是路由 (OpenShift) 或入口 (Kubernetes)，那么不能在子系统之间使用负载均衡器，因此不需要禁用 mTLS 和启用 JWT。不过，如果您确实想在群集内通信中使用 JWT 功能，那么可以按照以下步骤获取 JWKS URL ：

描述任何 API Connect pod:
```
kubectl describe pod <apic-pod>
```

在 pod 描述输出中，搜索 APIC_PLATFORM_API_SVC_ENDPOINT:

Containers:
  apim:
    Environment:
      APIC_PLATFORM_API_SVC_ENDPOINT:  https://management-juhu.acme-v1005-020323.svc:2000/api

JWKS URL 是 APIC_PLATFORM_API_SVC_ENDPOINT 的值，后加 /cloud/oauth2/certs 。如果 APIC_PLATFORM_API_SVC_ENDPOINT 在末尾缺少 /api ，请改为添加 api/cloud/oauth2/certs 。 JWKS URL 的路径必须始终为 api/cloud/oauth2/certs 。

JWT 安全性的关键点和限制

更改门户和分析子系统上的 JWKS URL 会导致 pod 重新启动，从而造成短暂的子系统中断。更改 JWKS URL 时，网关 pod 不会重新启动。
在新安装的 Cloud Pak for Integration 和顶层 CR OpenShift 部署中，会自动为门户、网关和分析子系统设置 JWKS URL。
您可以同时启用 mTLS 和 JWT ，但如果启用了 mTLS ，那么分析子系统不会验证 JWT。
v5c 网关不会将 JWT 发送到分析子系统。该流量由 mTLS, 保护，不能禁用。
如果为分析通信网关启用 JWT ，那么分析数据的采集将取决于管理子系统的可用性 (以便可以验证 JWT)。有关此限制的更多信息，请参阅: 网关与分析子系统之间的 JWT 使用情况。
在高分析采集负载下， JWT 启用可能会影响分析子系统的性能。建议先在预期的分析负载下完成性能测试，然后再决定将 JWT 用于网关到分析通信。

网关与分析子系统之间的 JWT 使用情况

由于分析子系统对管理子系统进行 REST 调用以验证其从网关接收的 JWT ，因此在启用 JWT 时，分析采集取决于管理子系统。分析子系统会缓存来自 JWKS URL 的响应，这样就不需要每次从网关接收 API 事件数据时都向管理子系统发出 REST 调用。但是 JWT 验证高速缓存将在 24 小时后到期，并且将对管理子系统进行新的 REST 调用以刷新高速缓存。 JWT 对平台 REST API 的依赖关系意味着管理子系统的中断最终会阻止分析子系统接受新的分析 API 事件记录。