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.
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
kubectlcommand. On OpenShift, use the equivalent
occommand 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
mtlsValidateClientproperty to false in the Custom Resources (CRs) of each subsystem.
Note: By default,When
mtlsValidateClientis set to false on the gateway subsystem.
mtlsValidateClientis 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:
where <JWKS URL> is the
spec: mtlsValidateClient: false jwksUrl: <JWKS URL>
jwksUrlspecified in the management subsystem CR
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
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.endpointssection 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
kubectl describe pod <apic-pod>
- In the pod describe output, search for
Containers: apim: Environment: APIC_PLATFORM_API_SVC_ENDPOINT: https://management-juhu.acme-v1005-020323.svc:2000/api
- The JWKS URL is the value of
/cloud/oauth2/certsappended to it. If the APIC_PLATFORM_API_SVC_ENDPOINT is missing the
/apiat the end, add
api/cloud/oauth2/certsinstead. The path of the JWKS URL must always be
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.