TLS profiles overview

Create TLS profiles to manage the TLS communication between subsystems, external systems, and your API invocation endpoint.

Mutual TLS is used to secure communication between API Connect subsystems, and TLS is used for communication with external systems such as email servers.

If you do not want to use mTLS for inter-subsystem communication, you can use JWT instead:

Use JWT instead of mTLS on Kubernetes and OpenShift.

Some of the API Connect TLS configuration is managed in the Cloud Manager UI, and is covered by this topic. The rest of the API Connect TLS configuration, which includes the management REST API endpoints and portal site certificates, are managed at the infrastructure level. For more information, see:

Kubernetes and OpenShift: API Connect certificates

The API Connect TLS configuration that is managed in the Cloud Manager UI covers the following areas:

Client certificates for inter-subsystem communication: Communication from your management subsystem to your portal, analytics, and gateway services.
API invocation endpoint. The certificates that callers of your published APIs see.
TLS profiles that you create for use in API definitions.
Communication with third-party systems.

When you install API Connect, default TLS profiles are created. If all of your API Connect subsystems are in the same environment (same Kubernetes or OpenShift namespace and project directory), then you can use these default TLS profiles to register your portal, gateway, and analytics services with your management subsystem.

Note: If you do not want to use the default TLS profiles, it is recommended to create new TLS profiles to use instead. Do not edit the default TLS profiles.

Two types of TLS profile can be configured in the Cloud Manager UI:

Client profiles are used to define the client certificate and ciphers that are used for making client connections to other systems.
Server profiles are used to define the server certificate and ciphers that are used for securing server endpoints. The only server profile that is created automatically (during installation) is the Default TLS server profile, which is used to secure the API invocation endpoint.

The components of a TLS Profile are:

TLS version indicates the version of the Transport Layer Security Protocol that is used by the profile. Options are TLS versions 1.0, 1.1, 1.2, and 1.3.
Support for mutual authentication and renegotiation for server profiles.
Support for weak server connections and Server Name Indication for client profiles.
Supported cipher suites.
Keystores, which contain the TLS keys that are used for initiating client connections.
Truststores, which contain the public keys to validate your analytics, portal, and gateway subsystems, and for trusted third-party services that you integrate with.

Important: If you create your own TLS profiles, API Connect verifies certificates when you upload them, but does not continuously monitor them for expiry. You are responsible for monitoring and updating your certificates before they expire.

TLS profiles created during installation

The following table shows the TLS profiles that API Connect creates during installation. You can use these profiles when you register your portal, gateway, and analytics services if your deployment is:

On OpenShift or Kubernetes, and all subsystems are installed in the same environment and namespace.

Table 1. TLS profiles
TLS profile name	Description
Default TLS server profile	For testing and demonstration purposes, you can specify this profile as the TLS server profile when you register your gateway service. For production deployments, best practice is to create your own TLS server profiles and not use the `Default TLS server profile`.
Default TLS client profile	You can use this profile as a client profile for communication between the management subsystem and any other system. This profile is set to trust everything (`insecure server connections` is set to `true`), and has no keystore or truststore. Use this profile only for testing and demonstrations.
Analytics ingestion TLS client profile	Default client profile for use when the management or gateway subsystem communicates with the analytics service: From the management subsystem to the analytics subsystem, when you register the analytics service and when querying for analytics data. From the gateway to the analytics subsystem, when the gateway sends API event data to the analytics subsystem. Select this profile when you register the analytics service. Note: If you want to use a different client certificate for your analytics service, do not edit this client profile, create a new profile instead.
Portal Director TLS client profile	Default client profile when the management subsystem communicates with the developer portal subsystem. Select this profile when you register the portal service. Note: If you want to use a different client certificate for your portal service, do not edit this client profile, create a new profile instead.
Gateway management client TLS client profile	Default client profile when the management subsystem communicates with the gateway subsystem. Select this profile when you register the gateway service. Note: If you want to use a different client certificate for your gateway service, do not edit this client profile, create a new profile instead.

Keystores created during installation

The following table shows the keystores that API Connect creates during installation:

Table 2. Keystores
Keystore name	Description
Analytics ingestion	Used by the `Analytics ingestion TLS client profile`, this keystore contains the client certificate that is used for connecting to the analytics subsystem's ingestion endpoint. This certificate is used by the management subsystem when it initiates communication with the analytics subsystem, and by the gateway when it sends API event data to the analytics subsystem. Kubernetes and OpenShift installations: The default client certificate in this keystore is set from the Kubernetes certificate analytics-ingestion-client. Do not edit this keystore. If you want to use a different client certificate for analytics ingestion, then create a new client profile and keystore for it.
Portal director	Used by the `Portal Director TLS client profile`, this keystore contains the client certificate that is used when the management subsystem initiates communication with the portal subsystem. Kubernetes and OpenShift installations: The default client certificate in this keystore is set from the Kubernetes certificate portal-admin-client.
Gateway mgmt	Used in the `Gateway management client TLS client profile`, this keystore contains the client certificate that is used when the management subsystem initiates communication with the gateway. Kubernetes and OpenShift installations: The default client certificate in this keystore is set from the Kubernetes certificate gateway-client-client or gw-dr-client.
Default TLS server keystore	Used in the `Default TLS server profile`, this keystore contains the server certificate that secures the API invocation endpoint on your gateway. Note: It is recommended to use the `Default TLS server profile` only for testing and demonstrations. Best practice is to create a new keystore and server profile for your API invocation certificate.
Default keystore for id_token signing key	Used for signing ID tokens that API Connect generates. You must update the certificate in this keystore manually before it expires. Upload a replacement certificate in the Cloud Manager UI.
Default keystore for self signed token signing key	Used for signing self-signed tokens that API Connect generates. You must update the certificate in this keystore manually before it expires. Upload a replacement certificate in the Cloud Manager UI.
Default keystore for temporary token signing key	Used for signing temporary tokens that API Connect generates. You must update the certificate in this keystore manually before it expires. Upload a replacement certificate in the Cloud Manager UI.
Default keystore for access_token signing key	Used for signing access tokens that API Connect generates. You must update the certificate in this keystore manually before it expires. Upload a replacement certificate in the Cloud Manager UI.

Truststores created during installation

The following table shows the truststores that API Connect creates during installation:

Table 3. Truststores
Truststore name	Description
Analytics ingestion	Used by the `Analytics ingestion TLS client profile`, this truststore contains the `root-ca` and `ingress-ca`, with which the management subsystem validates the certificate that the analytics subsystem presents.
Portal director	Used by the `Portal Director TLS client profile`, this truststore contains the `root-ca` and `ingress-ca`, with which the management subsystem validates the certificate that the portal subsystem presents.
Gateway management client truststore	Used by the `Gateway management client TLS client profile`, this truststore contains the `ingress-ca` on Kubernetes and OpenShift, with which the management subsystem validates the certificate that the gateway subsystem presents.