Replacing custom certificates

Use the APICUP installer certs commands to replace existing certificates.

About this task

  • Customization of public certificates and public user-facing certificates is recommended. Customization of internal certificates is strongly discouraged.
  • To view a list of public, public user-facing, and internal certificates, see Certificate management: Read This First. For details on each certificate, see Certificate reference.

The APICUP installer can be used to update certificates for each subsystem after installation.

Requirements for custom certificates:
  • Extended Key Usage (EKU), either serverAuth or clientAuth depending upon the type of certificate. Certificates of type Server must have an Extended Key Usage with serverAuth purpose. Certificates of type Client must have an Extended Key Usage with clientAuth purpose.
  • Subject Alternative Name (SAN) for the required hosts
  • Any custom common certificates that are being used must be set prior to setting any custom certificates for a subsystem.

See Certificate Reference to view the list of common certificates and to determine whether an EKU is needed for a certificate and which type of EKU (serverAuth or clientAuth).

Certificates and identical endpoints:

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.


  1. Generate the custom certificate with the appropriate EKU and SAN. You will need to obtain the private key, public certificate, and CA certificates in non-password-protected PEM format for the custom certificate. Following is an example for how to generate a certificate (platform-api-example) with an EKU serverAuth and SAN using openssl:
    openssl x509 -req -days 360 -in platform-api-example.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -out platform-api-cert -sha256  
    -extfile <(cat /etc/ssl/openssl.cnf <(printf "\n[SAN]\\nextendedKeyUsage=serverAuth")) 
    -extensions SAN
    Following is an example for how to generate a certificate (portal-client) with an EKU clientAuth and SAN using openssl:
    openssl x509 -req -days 360 -in portal-client-example.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -out portal-client-cert  
    -sha256 -extfile <(cat /etc/ssl/openssl.cnf <(printf "\n[SAN]\nkeyUsage=critical, digitalSignature,keyEncipherment\nextendedKeyUsage = clientAuth\nbasicConstraints=critical, 
    CA:FALSE\nsubjectKeyIdentifier=hash\n")) -extensions SAN
  2. Once the certificate has been created, set the certificate by entering the following command:


    You can find definitions for commands at the following location: Command reference

    If the certificate is signed by an intermediate CA, the CA_File argument must point to a file that concatenates the intermediate CA, followed by the root CA, in that order.

    If the certificate was generated with an EKU serverAuth, it must be assigned to a server certificate. If the certificate was generated with an EKU clientAuth, it must be assigned to a client certificate.

  3. Install the subsystem with the new certificate using apicup subsys install SUBSYS. Any missing certificates will be generated. The installation will not proceed if there are any validation issues with the certificates.
  4. Repeat for other subsystems requiring new certificates.