The Certificate reference provides a description of all the certificates
required in API Connect.
Before you begin
APICUP sets default certificates for each subsystem during
installation. The default certificates are self-signed so may not provide a level of trust suitable
for external communication. Custom certificates can be set and managed following the steps described
in Setting custom certificates. The Certificates reference topic lists all certificates that are set by the apicup
certs commands. The default certificates can be used for the majority of these
certificates. The certificates that are marked as public and user-facing are
recommended to be explicitly set as custom certificates because they are presented to an end user
through a browser or Command Line Interface (CLI).
The certificates that are described
as TLS certificate used by ingress are also considered public
in the sense that they interact with a client that sits outside of an API Connect cluster.
The remaining certificates are considered internal because they interact
with internal components.
Certificates that are listed as
auto-generated cannot be set using the apicup certs set command.
For example, the common certificate ingress-ca is auto-generated and used as an
intermediate CA for all default ingress certificates. If you set an ingress certificate as a custom
certificate, you will need to configure an intermediate CA if desired.
Important:
When setting custom certificates, additional steps must be taken to provide an Extended Key Usage
(EKU) serverAuth and ClientAuth and a Subject Alternative Name (SAN) for the required hosts. These
certificates are generated automatically by the apicup certs command when using the
default certificates.
- For custom certificates of type server, an additional extended key usage
client authentication (EKU serverAuth) certificate is required.
- For custom certificates of type client, an additional extended key usage
server authentication (EKU clientAuth) certificate is required.
Procedure
- Common certificates - The following certificates are common to all
subsystems in a deployment. Subsystems require the common certificates to allow them to register
with the management subsystem. The common certificates are identical across subsystems. When
installing any one subsystem, the common certificates will be set for that subsystem and for all the
other subsystems. Custom common certificates must be set prior to setting any custom subsystem
certificates.
Common certificates cannot be changed between subsystem installs. For example, you cannot set a
common certificate for the management subsystem, install the management subsystem, then change a
common certificate for the analytics subsystem, then install the analytics subsystem. This scenario
will result in a failed installation because the common certificates are not identical.
Table 1. Common certificates
Certificate name (value used in apicup certs) |
Type |
Usage |
Requirements |
Description |
| root-ca |
CA |
internal |
|
CA certificate which forms the root of the certificate chain |
| ingress-ca |
CA |
internal |
signed by: root-ca |
Auto-generated intermediate certificate used to generate certificates for subsystem ingress
endpoints if not provided by user. The ingress-ca intermediate certificate cannot be set
explicitly, it is always only generated. TLS certificates for the ingresses are not required to use
ingress-ca as an intermediate certificate, but if a given ingress TLS certificate is left to be
auto-generated then it will be signed by this ingress-ca.
|
| mgmt-db-ca |
CA |
internal |
signed by: root-ca |
Intermediate CA certificate used to sign certificates used by Cassandra. |
| portal-client |
Client |
internal |
Must be signed by the same authority as the one used for the matching ingress TLS
certificate portal-admin-ingress. |
Client certificate used by management subsystem to authenticate with the Portal admin
endpoint. Requires EKU clientAuth. |
| analytics-client-client |
Client |
internal |
Must be signed by the same authority as the one used for the matching ingress TLS
certificate analytics-client-ingress . |
Client certificate used by management subsystem to authenticate with analytics client
endpoint. Requires EKU clientAuth. |
| analytics-ingestion-client |
Client |
internal |
Must be signed by the same authority as the one used for the matching ingress TLS
certificate analytics-ingestion-ingress . |
Client certificate used by gateway subsystem to authenticate with analytics ingestion
endpoint. Requires EKU clientAuth. |
- Management certificates
These certificates apply to a single Management subsystem.
The Management subsystem has four endpoints: api-manager-ui, cloud-admin-ui,
platform-api, and consumer-api. Distinct TLS certificates can be set
for each endpoint. However, if any two endpoints identical, only one TLS certificate will be
effective. The order of precedence is: api-manager-ui, cloud-admin-ui, platform-api,
consumer-api.
Following are examples for how precedence is determined for TLS certificates for endpoints:
- If all four endpoints are distinct, then all four TLS certificates will be effective for their
respective endpoints.
- If all four endpoints are identical, then only the api-manager-ui TLS certificate will be
effective for all endpoints, as it is first in the precedence order.
- If the api-manager-ui, cloud-admin-ui, and platform-api endpoints are the same, and consumer-api
is a different endpoint, then the api-manager-ui TLS certificate will be effective for the
api-manager-ui/cloud-admin-ui/platform-api endpoints, while the consumer-api TLS certificate will be
effective for the consumer-api endpoint
The encryption-secret certificate is unique in that it is a secure random number. It is used to
provide field level encryption in management (Cassandra) database. To set the encryption secret for
the management database, use the following command: apicup certs set SUBSYS CERT_NAME
[KEY_FILE] For example: apicup certs set mgmt1 encryption-secret
/path/to/keyfile. See Setting
the encryption-secret for the management database
Table 2. Management certificates
| Certificate name |
Type |
Usage |
Requirements |
Description |
| encryption-secret |
secure random bytes |
|
length: 128 bytes |
Encryption secret used to do field level encryption in management (Cassandra)
database |
| platform-api |
Server |
public and user-facing |
The host names for which the certificate is valid must include the platform-api endpoint. A
wildcard certificate can be used as the first element in a host name, for example, if the endpoint
is: store.acme.com, the certificate can be one that is valid for host names
matching *.acme.com. |
TLS certificate used by ingress. Requires EKU serverAuth. Public and user-facing. |
| consumer-api |
Server |
public and user-facing |
The host names for which the certificate is valid must include the consumer-api endpoint. A
wildcard certificate can be used as the first element in a host name, for example, if the endpoint
is: store.acme.com, the certificate can be one that is valid for host names
matching *.acme.com. |
TLS certificate used by ingress. Requires EKU serverAuth. Public and user-facing. |
| api-manager-ui |
Server |
public and user-facing |
The host names for which the certificate is valid must include the api-manager-ui endpoint. A
wildcard certificate can be used as the first element in a host name, for example, if the endpoint
is: store.acme.com, the certificate can be one that is valid for host names
matching *.acme.com. |
TLS certificate used by ingress. Requires EKU serverAuth. Public and user-facing. |
| cloud-admin-ui |
Server |
public and user-facing |
The host names for which the certificate is valid must include the cloud-admin-ui endpoint. A
wildcard certificate can be used as the first element in a host name, for example, if the endpoint
is: store.acme.com, the certificate can be one that is valid for host names
matching *.acme.com. |
TLS certificate used by ingress. Requires EKU serverAuth. Public and user-facing. |
| mgmt-ca |
CA |
internal |
signed by: root-ca |
Intermediate CA used to sign management subsystem certificates |
| service-server |
Server |
internal |
signed by: mgmt-ca Required hosts:
- *.<namespace>
- *.<namespace>.svc
- *.<namespace>.svc.cluster.local
|
Server certificates used by management services. Requires EKU serverAuth. |
| service-client |
Client |
internal |
signed by: mgmt-ca |
Client certificate used by management services. Requires EKU clientAuth. |
| db-server |
Server |
internal |
signed by: mgmt-db-ca
Required hosts:
- *.<namespace>
- *.<namespace>.svc
- *.<namespace>.svc.cluster.local
|
Server certificate used by management (Cassandra) database to communicate with other nodes.
Requires EKU serverAuth. |
| db-client |
Client |
internal |
signed by: mgmt-db-ca |
Client certificate used by management services. Requires EKU clientAuth. |
| service-plugin |
Client |
internal |
signed by: mgmt-ca |
Client certificate used by plugin services to talk to management subsystem. Requires EKU
clientAuth. |
| migration-client |
Client |
|
signed by: mgmt-ca |
This certificate is deprecated and no longer used, and can be ignored. |
- Portal certificates
These certificates apply to a single portal subsystem.
Table 3. Portal certificates
| Certificate name |
Type |
Usage |
Requirements |
Description |
| portal-admin-ingress |
Server |
internal |
host must match admin endpoint |
TLS certificate used by ingress. The portal-client common certificate must
be set prior to setting the portal-admin-ingress certificate. Requires EKU
serverAuth.The portal-admin-ingress TLS certificate does not have any specific
requirement on the authority signing it. If the certificate is auto-generated, it is signed by the
ingress-ca.
|
| portal-www-ingress |
Server |
public and user-facing |
host must match www endpoint |
TLS certificate used by ingress. Requires EKU serverAuth. |
| portal-ca |
CA |
internal |
signed by: root-ca |
Intermediate CA used to sign portal subsystem certificates |
| portal-db-ca |
CA |
internal |
signed by: portal-ca |
Intermediate CA certificate used to sign certificates used by portal DB |
| service-server |
Server |
internal |
signed by: portal-ca
Required hosts:
- *.<namespace>
- *.<namespace>.svc
- *.<namespace>.svc.cluster.local
|
Server certificates used by portal services. Requires EKU serverAuth. |
| service-client |
Client |
internal |
signed by: portal-ca |
Client certificate used by portal services. Requires EKU clientAuth. |
| apim-client |
Client |
internal |
signed by: portal-ca |
Client certificate used by portal services to talk to management subsystem. Requires EKU
clientAuth. |
- Analytics certificates
These certificates apply to a single analytics subsystem.
Table 4. Analytics certificates
| Certificate name |
Type |
Usage |
Requirements |
Description |
| analytics-client-ingress |
Server |
internal |
Required hosts:
- client ingress endpoint
- *.<namespace>
- *.<namespace>.svc
- *.<namespace>.svc.cluster.local
|
TLS certificate used by ingress. The analytics-client-client common
certificate must be set prior to setting the analytics-client-ingress certificate.
Requires EKU serverAuth.The analytics-client-ingress TLS certificate does not
have any specific requirement on the authority signing it. If the certificate is auto-generated, it
is signed by the ingress-ca.
|
| analytics-ingestion-ingress |
Server |
internal |
Required hosts:
- ingestion ingress endpoint
- *.<namespace>
- *.<namespace>.svc
- *.<namespace>.svc.cluster.local
|
TLS certificate used by ingress. The analytics-ingestion-client common
certificate must be set prior to setting the analytics-ingestion-ingress
certificate. Requires EKU serverAuth.The analytics-ingestion-ingress TLS
certificate does not have any specific requirement on the authority signing it. If the certificate
is auto-generated, it is signed by the ingress-ca.
|
| analytics-ca |
CA |
internal |
signed by: root-ca |
Intermediate CA used to sign analytics subsystem certificates |
| service-server |
Server |
internal |
signed by: analytics-ca
Required hosts:
- *.<namespace>
- *.<namespace>.svc
- *.<namespace>.svc.cluster.local
|
Server certificates used by analytics services. Requires EKU serverAuth. |
| service-client |
Client |
internal |
signed by: analytics-ca |
Client certificate used by analytics services; requires EKU clientAuth. |
- Gateway certificates
These certificates apply to a single gateway subsystem.
Table 5. Gateway certificates
| Certificate name |
Type |
Usage |
Requirements |
Description |
| api-gateway-ingress |
Server |
public and user-facing |
host must match api-gateway endpoint |
TLS certificate used by ingress. Requires EKU serverAuth. (deprecated, see
Note.) |
| apic-gw-service-ingress |
Server |
public |
host must match apic-gw-service endpoint |
TLS certificate used by ingress. Requires EKU serverAuth. |
| gw-ca |
CA |
internal |
signed by: root-ca |
Intermediate CA used to sign gateway subsystem certificates |
| gateway-peering |
Server |
internal |
signed by: gw-ca |
Server certificates used by gateway services. Requires EKU serverAuth. |
Note: The
api-gateway-ingress certificate is a legacy certificate
which has been deprecated. It is no longer used to terminate TLS at the api-gateway endpoint. You
configure a TLS profile for the termination of the api-gateway endpoint using the Cloud Manager
API Invocation Endpoint and SNI settings when registering the gateway. The
profiles used during configuration can be updated as needed. See
Registering a gateway service