Enable JWT security instead of mTLS

When and how to use JWT security instead of mTLS.

Most of the network interactions between API Connect subsystems use mTLS. The communication flows in API Connect that are secured with mTLS are as follows:

Management to portal. mTLS set by default.
Management to analytics. mTLS set by default.
Management to API gateway. TLS set by default, mTLS can be enabled following Enabling mTLS on management to gateway communication.
Management to v5 compatible gateway. TLS set by default, mTLS can be enabled following Enabling mTLS on management to gateway communication.
Management to Event gateway. mTLS set by default. Cloud Pak for Integration only.
API gateway to analytics. mTLS set by default.
V5 compatible gateway to analytics. mTLS is set and cannot be disabled.
Event gateway to analytics. mTLS set and cannot be disabled. Cloud Pak for Integration only.

All other inter-subsystem communication uses TLS. For the communication routes that use mTLS, it is a requirement that all network infrastructure such as load-balancers that are located between API Connect subsystems implement TLS passthrough (and not TLS termination).

Use of JSON Web Token (JWT) security instead of mTLS allows for the deployment of API Connect in network infrastructures where TLS termination is enabled on load-balancers that are located between subsystems. JWT provides application layer security between API Connect subsystems. The typical use-case for this feature is when payload inspection of all network communications is required at network boundaries. The communication flows that support JWT security are:

Management to portal.
Management to analytics.
Management to API gateway.
Management to v5 compatible gateway.

The management subsystem always sends a JWT when it initiates communication with the other subsystems, but by default the subsystems do not verify this JWT. When JWT security is enabled, the subsystems verify the JWT by making a REST call to the JSON Web Key Set (JWKS) URL. The JWKS URL is hosted on the management subsystem's platform REST API.

To enable JWT verification, you update the subsystem CRs to specify the JWKS URL. To disable JWT verification, you update the subsystem CRs and delete the value of the JWKS URL (leave it unset).

Note: For OpenShift users: The example steps in this topic use the Kubernetes kubectl command. On OpenShift, use the equivalent oc command in its place. If you are using a top-level CR you must edit the API Connect cluster CR (the top-level CR), instead of directly in the subsystem CRs. If the subsystem section is not included in the top-level CR, copy and paste the section from the subsystem CR to the top-level CR.

Disabling mTLS and enabling JSON Web Token (JWT) security

If you disable mTLS, you must enable JWT. It is not possible to configure API Connect with both mTLS and JWT disabled.

You disable mTLS on the portal, gateway, and analytics subsystems by setting the mtlsValidateClient property to false in the Custom Resources (CRs) of each subsystem.

Note: By default, mtlsValidateClient is set to false on the gateway subsystem.

When mtlsValidateClient is set to false, the subsystem does not verify the client's TLS credentials, but it does check for a valid JWT configuration. For example, to disable mTLS and enable JWT for management to portal communication, edit the portal CR and set:

spec:
  mtlsValidateClient: false
  jwksUrl: <JWKS URL>

where <JWKS URL> is the jwksUrl specified in the management subsystem CR status.endpoints section.

Using registration of the portal service in the Cloud Manager UI as an example, JWT works as follows:

Management subsystem establishes a TLS connection to the portal subsystem on the portal director admin endpoint, and sends a JWT to the portal.
Before the portal trusts the management subsystem, it first verifies the JWT it received. The JWT is verified by a call to a JSON Web Key Set (JWKS) URL.
The management subsystem receives the JWT verification request from the portal on its platform REST API, and responds that the JWT is valid.
The portal receives confirmation that the JWT is valid, and so it can trust the management subsystem and continue the registration process.

To disable JWT security, either remove the jwksUrl property from the CR , or leave its value empty. If you disable JWT, you must enable mTLS by setting mtlsValidateClient to true.

Configuring the JWKS URL

The JWKS URL is defined as the platform API hostname with the following subpath appended: api/cloud/oauth2/certs. You can see what the JWKS URL is from the status.endpoints section of the management CR, for example:

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

Note: The JWT feature is intended for environments where the are load-balancers located between subsystems. If you are using the in-cluster communications feature Use services instead of routes (OpenShift) or ingresses (Kubernetes), then you cannot have load-balancers between subsystems, and so disabling mTLS and enabling JWT is not necessary. However, if you do want to use the JWT feature with in-cluster communications then the JWKS URL can be obtained following these steps:

Describe any API Connect pod:
```
kubectl describe pod <apic-pod>
```

In the pod describe output, search for APIC_PLATFORM_API_SVC_ENDPOINT:

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

The JWKS URL is the value of APIC_PLATFORM_API_SVC_ENDPOINT with /cloud/oauth2/certs appended to it. If the APIC_PLATFORM_API_SVC_ENDPOINT is missing the /api at the end, add api/cloud/oauth2/certs instead. The path of the JWKS URL must always be api/cloud/oauth2/certs.

Key points and limitations of JWT security

For API Connect deployments upgraded from a pre-v10.0.5.3 release, the behavior of each subsystem remains the same as it was before upgrade.
Changing the JWKS URL on portal, and analytics subsystems causes pods to restart, and so a short subsystem outage. The gateway pod does not restart when the JWKS URL is changed.
You can have both mTLS and JWT enabled.