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.
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) |
Usage |
Requirements |
Description |
| root-ca |
CA |
|
CA certificate which forms the root of the certificate chain |
| ingress-ca |
CA |
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 remains to be
auto-generated then it will be signed by this ingress-ca.
|
| portal-client |
Client |
Must be signed by the same authority as the one used for the matching ingress TLS
certificate portal-admin-ingress. For a two data center deployment, both data
centers must have an identical subject name. For example, both data centers subject name could be
CN=portal-admin-client, or they could both be CN=ptl-adm-client,
O=cert-manager, but they must be identical. |
Client certificate used by management subsystem to authenticate with the Portal admin
endpoint. Requires EKU clientAuth. |
| analytics-client-client |
Client |
This is a legacy certificate, it is not used from v10.0.5 onwards |
|
| analytics-ingestion-client |
Client |
Must be signed by the same authority as the one used for the matching ingress TLS
certificate analytics-ingestion-ingress . For a two data center deployment,
both data centers must have an identical subject name. For example, both data centers subject name
could be CN=a7s-ingestion-client, or they could both be
CN=a7s-ingestion-client, O=cert-manager, but they must be identical. |
Client certificate used by management subsystem to authenticate with analytics client
endpoint. Requires EKU clientAuth. Also used by gateway subsystem to authenticate with analytics
ingestion endpoint. |
- Management certificates
These certificates apply to a single Management subsystem.
The Management subsystem has four public 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 are identical, only one TLS
certificate will be effective. When 2 or more endpoints are set to the same host, the secrets
associated with the endpoints should be the same or contain the same certificate files.
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 |
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 |
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 |
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 |
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 |
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. |
| hub-endpoint |
Server |
|
Automated Testing Behavior UI and API endpoint |
| turnstile-endpoint |
Server |
|
Automated Testing Behavior UI and API endpoint |
- Portal certificates
These certificates apply to a single portal subsystem.
Table 3. Portal certificates
| Certificate name |
Usage |
Requirements |
Description |
| portal-admin-ingress |
Server |
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 |
host must match www endpoint |
TLS certificate used by ingress. Requires EKU serverAuth. Public and user-facing. |
- Analytics certificates
These certificates apply to a single analytics subsystem.
Table 4. Analytics certificates
| Certificate name |
Usage |
Requirements |
Description |
| analytics-ingestion-ingress |
Server |
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.
|
- OVA/Appliance certificates
These certificates apply only to an appliance in a VMware environment. The
k8s-ca and appliance-client certificates are auto-generated and
cannot be set as custom certificates. These are used to set up the Kubernetes cluster in an
OVA/Appliance.
Table 5. OVA/Appliance certificates
| Certificate name |
Usage |
Requirements |
Description |
| k8s-ca |
CA |
|
Auto-generated CA certificate that forms the root of the certificate chain for the
Appliance/Kubernetes cluster components |
| appliance-client |
Client |
signed by: k8s-ca |
Auto-generated client certificate used to communicate with the Appliance API server. Requires
EKU clientAuth. |