Authors: Aiden Gallagher (aidengal@uk.ibm.com), Cameron McWilliam (Cameron.McWilliam@ibm.com) and David Finn (david_finn@uk.ibm.com)
Introduction
This article details how certificates are configured within API Connect and covers version 10.0.5.x on OpenShift 4.12. This is intended for API Connect administrators, operations teams and security teams with a focus on API Connect with lots of focus on certificate management including the creation and renewal of certificates.
IBM API Connect Overview
Figure 1 - API Connect Components
IBM API Connect is an API management platform that enables the publishing, discovery, subscription and securing of APIs. It is made up of four sub-systems:
- Management: The management system is the “brains” of API Connect, where all management of APIs, users, certificates, topology objects, analytics, discoverability, and subscriptions take place from both a topology administrator and an API provider organisation perspective.
- Gateway: The gateway cluster is made up of one or more instances of IBM DataPower and is the runtime environment of all APIs deployed in API Connect. This provides a secure way of exposing APIs. All API traffic passes through only this system.
- Analytics: The analytics system provides analytical data on a variety of information about the APIs and the applications calling it. It allows for the offloading of analytical data to other services such as ElasticSearch, Splunk, etc.,
- Portal: The portal system provides developers with the ability to view and subscribe to available Products and APIs. It provides developers with a self-service experience for consuming APIs, including community forums, application generation, and credential management e.g., client id and client secret.
API Connect on OpenShift
OpenShift Operators provide ease of installation and an automated management when deploying IBM software products. The API Connect operator has multiple custom resources that allow the installation of the components and additional tooling in a straightforward manner. A custom resource is effectively a Kubernetes object that tells the platform what to deploy and what that deployment looks like e.g., CPU, Memory, ConfigMaps, Storage etc.
In API Connect, users have the option of a top-level APIConnectCluster custom resource which configures the four sub-systems. Alternatively, each of the components has their own custom resource allowing independent deployments and management of the components. The most typical use of independent custom resource is for additional gateway clusters for traffic isolation between business or technical domains.
There is an additional decision point for OpenShift around whether to deploy with Cloud Pak for Integration (CP4I) or directly with OpenShift. API Connect deployed with CP4I requires Foundational Services to be deployed, and is important for the certificate discussion because it means that certain routes for API Connect are redirected via the Platform UI.
API Communication
Figure 2 - API Communication
The four components within API Connect communicate with each other, each component’s pods communicate with each other, and external services connect into the gateway.
External users access the gateway, management, and portal endpoints. Each of these communications require certificates but each has its own characteristics.
We can split types of communication in API Connect into these three broad categories: Inter-component communication, cross-component communication, and external communication. Table 1 - Types of communication describes each type and an example.
|
Communication Type
|
Description
|
Examples
|
|
Inter-component Communication
|
Each of the components is made up of multiple pods (or peers) that interact with each other in order to complete internal processes
|
The REST endpoint called by users persisting configuration changes to the database e.g., new consumer application details
|
|
Cross-component Communication
|
Each of the components need to talk to at least one other components, mainly the management cluster.
All sub-systems within API Connect communicate with the management system. This initial communication takes the form of the registration process of the gateway, analytics, and portal services into the management service.
|
Management cluster pushing configuration to the gateway e.g., API and Product definitions
|
|
External communication
|
External users and services connecting into the systems use endpoints that are publicly accessible (or through a DNS / Load balancer)
|
An external user invoking the gateway endpoint to call APIs, discover APIs in the Portal, and an operations team user viewing analytics data in the manager
|
Table 1 - Types of communication
Managing Certificates
There are three primary methods for providing certificates to be used by API Connect in an OpenShift Platform:
- Self-signed by API Connect
- Trusted certificates uploaded as secrets into OpenShift
- Certificates generated by a certificate-manager within OpenShift
Figure 3 - Certificate Ownership
Self-signed
Certificates are a vital aspect of planning and eventually implementing an API Connect deployment. Out of the box, API Connect generates its own self-signed certificates with the aid of cert-manager. API Connect requires cert-manager operands and won’t install without it. Most organisations will deem self-signed certificates as unsafe and, in many cases, will obstruct communication with external partner systems which will not trust the certificate when performing TLS handshakes.
Trusted certificates uploaded as secrets into OpenShift
Instead of self-signed certificates, administrators can deploy CA-signed certificates for each component which are then used to present themselves to other systems. This method does not require the uploading of the CA signer certificate but does mean more certificates to manage in OpenShift by the admins.
It is recommended to use self-signed certificate for inter-component and cross-component communication generated by the API Connect issuers, but all external certificates should be signed by a trusted CA. Within OpenShift, certificates are stored as TLS secrets in the correct namespaces which are referenced in the relevant custom resources.
Certificates generated by a certificate-manager within OpenShift
Alternatively, we can create a signer, by uploading a secret containing a CA certificate and key which is used by IBM Cert Manager as part of its Issuer object. The issuer object allows users and services (such as the API Connect Custom Resource) to generate certificate objects that are automatically signed by the trusted CA meaning administrators must only manage the CA secret and not the individual secrets.
Certificates in API Connect
Figure 4 - Certificate Usage in API Connect shows the certificate pattern used in a typical API Connect deployment with the communication type and the assumed issuer as per the key.
Figure 4 - Certificate Usage in API Connect
The green certificates signify any routes or certificates that are presented when the endpoint is accessed externally. All four routes to the management system have trusted external-facing certificates as users access the management system user interfaces for a variety of API management or administration tasks.
Additionally, the portal-web has a trusted external-facing certificate as any portal websites created will be accessed by consumers and administrators.
Blue certificates are automatically generated by a self-signed CA certificate that API Connect creates on deployment. These are issued by the apic-ingress-issuer and are used for cross-component communication.
The red certificates represent inter-component communication and are issued from component specific CA certificates generated at deployment time and are self-signed because all the communication stays internally to the component between their pods.
An API Connect TLS server profile is assigned to each gateway service, all calls to APIs on API Connect come through the gateway, and the TLS server profile acts as the server in this client server relationship. These certificates are not managed within the custom resource but are deployed through management REST APIs and manual configuration in the UI.
TLS client profiles are used within API assemblies in the ‘invoke’ policies which enable certificates to be presented to downstream services. Both keystore and truststores are required for mutual TLS authentication. These certificates are not managed within the custom resource but are deployed through management REST APIs and manual configuration in the UI.
Considerations
There are a few additional considerations when managing API Connect certificates:
- OpenShift administration access is required to push root CA certificates into relevant secrets
- Should certificate management be automatic using auto-renew on cert-manager or more controlled by the team performing the certificate updates
- How will CA issuer certificates be renewed and how does that impact API Connect, the systems that call it and the systems called by API Connect
- In some deployments, you need to ensure the OpenShift / Cloud platform can trust the CA being generated for API Connect. For example, on managed OpenShift clusters such as ARO and ROSA, these need to trust the integration CA certificate
- How will you monitor when certificates are due to expire, or can you simply put a regular process in place to renew certificates e.g., every time there is a fix pack applied or API deployed?
References