Customizing your user-facing certificates

How to set the user-facing endpoints of API Connect to use your own TLS server certificates.

Before you begin

Identify the user-facing certificates that you want to customize: User-facing certificates.

Ensure that you have certificate, key, and CA PEM files for each certificate you want to customize. The PEM files must not be password-protected.

For example, to customize the certificate that secures the Cloud Manager UI, you must have the following PEM files: cloud-admin-ui-cert.pem, cloud-admin-ui-key.pem, cloud-admin-ui-ca.pem

User-facing certificates must meet the following requirements:

Specify Extended Key Usage (EKU) of serverAuth.
Include the Subject Alternative Name (SAN) of the endpoint that they secure.
If the certificate is signed by an intermediate CA, then the ca.pem file must contain the full chain to root CA.

About this task

You update the user-facing certificates with the apicup command.

You can set custom user-facing certificates during installation, or you can update them after installation, replacing the default certificates that are generated.

Note: API Connect verifies certificates when you set them, but does not continuously monitor them for expiry. You are responsible for monitoring and updating your custom certificates before they expire.

Procedure

If you are updating a user-facing certificate after installation, you must first clear the default certificate that was created:
```
apicup certs set <subsystem name> <certificate name> --clear
```
For example, to clear the certificate that secures the Cloud Manager UI:
```
apicup certs set mgmt cloud-admin-ui --clear
```

Set the user-facing certificate with the apicup certs set command, supplying the PEM files for your new certificate:

apicup certs set <subsystem name> <certificate name> <cert file> <key_file> <ca file>

For example:

apicup certs set mgmt cloud-admin-ui cert.pem key.pem ca.pem

If you are updating the certificate after installation, then apply the update with apicup subsys install
```
apicup subsys install <subsystem name>
```

You can verify that the certificate is updated with apicup certs list --endpoints:

apicup certs list <subsystem name> --endpoints

Example output:

Common certificates
===================

Name                        Summary                                                          Validation errors
----                        -------                                                          -----------------
...                                                
                                                                                             
Subsystem def-management certificates
=====================================

Name                            Summary                                                          Validation errors
----                            -------                                                          -----------------
...                 
cloud-admin-ui                  CN: cloud-admin-ui                                               
                                SubjectKeyId: 9E:8B:FA:7E:92:70:EC:86:2F:C3:3A:20:E8:13:EA:F4    
                                AuthorityKeyId: E4:AB:09:FF:A9:7D:D3:70:DD:AD:69:C4:A4:34:8D:96  
...

Note: Along with the user-facing certificates, the apicup certs list (without --endpoints flag) command outputs details of other internal API Connect certificates and secrets that you should not update.

If you see validation errors in apicup certs list --endpoints output, check Certificate validation reference.

If you want to revert to using automatically generated user-facing certificates, then you can clear and regenerate the certificates by following these steps:

Clear the certificate:
```
apicup certs set <subsystem name> <certificate name> --clear
```
Repeat for all certificates that you want to clear.
Generate new certificates for all the cleared certificates:
```
apicup certs generate <subsystem name>
```
If you are updating the certificate after installation, then apply the update with apicup subsys install:
```
apicup subsys install <subsystem name>
```