Configuring and managing custom TLS certificates

Custom TLS certificates allow you to secure dataplane and engine services by using certificates stored in Azure Key Vault instead of the default platform-generated certificates.

Overview

The certificate must be stored in PEM format in an Azure Key Vault that belongs to the same Azure subscription as the dataplane.

During both initial dataplane deployment and post-deployment certificate updates, the Azure Key Vault Resource ID and Secret Name are used to securely retrieve the certificate.

An ARM template deployment is required to grant the dataplane the necessary Azure permissions to access the certificate from the Key Vault.

Certificate requirements

If you provide a server certificate (CA = FALSE), it must be signed by a Root or Intermediate Certificate Authority (CA = TRUE).

If your server certificate is signed by a Certificate Authority (CA), the full certificate chain must be available.

Provide:

  • The Server Certificate (CA = FALSE)
  • The Root CA certificate (CA = TRUE)
  • Optional intermediate certificates

Provide the complete certificate chain so NGINX can serve the certificate correctly. The certificates are typically combined into a single file:

cat server.crt intermediate.crt rootCA.crt > fullchain.crt

Private root CAs

If your Root CA is private (for example, an internal corporate CA), it is not trusted automatically by browsers.

As a result:

  • End-user systems must have the Root CA installed.
  • The Root CA must be distributed through enterprise device management.

Example

Your organization creates:

  • Root CA: Corporate-Internal-Root
  • Server certificate: console.customer-domain.com

The certificate is valid and correctly signed. However, if the Root CA is not installed on user systems, users see:


Your connection is not private
ERR_CERT_AUTHORITY_INVALID
Figure 1. Certificate trust validation flow

Browser trust considerations

To avoid browser trust errors:

  • Install the Root CA into the operating system trust store.
  • Use a publicly trusted CA such as DigiCert or Let's Encrypt.

macOS (Chrome and Edge)

Chrome and Edge use the operating system trust store.

  1. Open Keychain Access.
  2. Select the System keychain.
  3. Click File > Import Items.
  4. Import the Root CA certificate.
  5. Open the certificate.
  6. Expand Trust.
  7. Set When using this certificate to Always Trust.
  8. Save the changes and restart the browser.

Windows (Chrome and Edge)

Chrome and Edge use the Windows certificate store.

  1. Press Win+R.
  2. Run:
    certlm.msc
  3. Navigate to Trusted Root Certification Authorities > Certificates.
  4. Import the Root CA certificate.
  5. Restart the browser.

Firefox

Firefox might not use the operating system trust store.

  1. Open Firefox.
  2. Go to Settings > Privacy & Security.
  3. Under Certificates, click View Certificates.
  4. Select Authorities.
  5. Click Import.
  6. Select the Root CA certificate.
  7. Enable Trust this CA to identify websites.
  8. Restart Firefox.

Common Name (CN) and Subject Alternative Name (SAN) requirements

The server certificate must include the correct DNS name in the Subject Alternative Name (SAN) field.

The Common Name (CN) must also match the fully qualified domain name (FQDN) of the console.

Although SAN is used for validation, the CN should match for compatibility and best practices.

For example, if users access:

https://console.customer-domain.com

The certificate must contain:

DNS:console.customer-domain.com

in the SAN field and:

CN=console.customer-domain.com

in the Subject field.

Verify the certificate subject:

openssl x509 -in tls.crt -noout -subject

If the CN or SAN value does not match the hostname, browsers display a certificate name mismatch error.

Create an Azure Key Vault and import a TLS certificate

Before configuring a custom TLS certificate for the dataplane, create an Azure Key Vault and import the TLS certificate (PFX or PEM) that will be referenced during dataplane setup.

Prerequisites

  • An Azure subscription with permissions to create Azure Key Vaults.
  • A valid TLS certificate.
  • If using a CA-signed certificate, include the complete certificate chain (server certificate, intermediate certificates, and root CA).
  • The certificate contains the correct Common Name (CN) and Subject Alternative Name (SAN) matching the console FQDN.

Create an Azure Key Vault

  1. Sign in to the Azure portal.
  2. Search for Key Vaults.
    Figure 2. Key Vaults page
  3. Click Create.
    Figure 3. Create Key Vault
  4. Enter the required information.
  5. Open the Access configuration tab.
    Figure 4. Access configuration
  6. Under Permission model, select Azure role-based access control (recommended).
  7. Review the configuration.
  8. Click Create.
    Figure 5. Review and create
Note: IBM recommends using Azure RBAC instead of the legacy Vault access policy model because Azure RBAC is required for custom TLS certificate integration.

Import the TLS certificate

  1. Open the Key Vault.
  2. Select Certificates.
  3. Click Generate/Import.
    Figure 6. Certificate import dialog
  4. Specify:
    • Method of Certificate Creation = Import
    • Certificate Name
    • Upload Certificate File
    • Password (if applicable)
    • Figure 7. Create a certificate
  5. Click Create.

Verify the certificate

Verify that the certificate appears with:

  • Status: Enabled
  • Thumbprint
  • Expiration Date

Azure Key Vault stores both the certificate metadata and private key securely.

Figure 8. Verify the certificate

Configure a custom TLS certificate during dataplane setup

Prerequisites

Ensure that:

  • The TLS certificate is uploaded to Azure Key Vault.
  • The certificate is stored in PEM format.
  • The Key Vault belongs to the same Azure subscription as the dataplane.
  • You have:
    • Azure Key Vault Resource ID
    • Secret Name

Step1: Enable the custom certificate

  1. Navigate to the Setup Dataplane page.
  2. Go to the Azure cloud configuration section.
  3. Enable Use custom TLS certificate.
Figure 9. Enable a custom TLS certificate

Step 2: Provide Key Vault details

Enter:

  • Key Vault Resource ID
  • Secret Name

When both values are validated, the Deploy button becomes available.

Step 3: Deploy the ARM template

Click Deploy.

The ARM template creates:

  • Managed identities
  • Custom roles
  • Role assignments

These permissions allow the dataplane deployment process to retrieve the certificate from Azure Key Vault.

Step 4: Complete dataplane setup

  1. Return to the dataplane setup workflow.
  2. Continue the setup process.
  3. Initiate dataplane creation.

Result:

During dataplane provisioning, the certificate is retrieved from Azure Key Vault and configured for the deployed services.

The dataplane is deployed using the customer-provided certificate instead of the default platform-generated certificate.

Update a custom TLS certificate after dataplane deployment

To replace an existing certificate, upload a new certificate to Azure Key Vault and update the certificate configuration through the BYOC console.

Prerequisites

To replace an existing certificate, upload a new certificate to Azure Key Vault and update the certificate configuration through the BYOC console.

Ensure that:

  • The new certificate is uploaded to Azure Key Vault.
  • The certificate is stored in PEM format.
  • The Key Vault belongs to the same Azure subscription as the dataplane.
  • You have:
    • Azure Key Vault Resource ID
    • Secret Name

Step 1: Open the Certificate Management Page

From the BYOC home page, click Update Certificate under Manage Certificate.

Figure 10. Accessing the certificate management workflow

Step 2: Provide Azure Key Vault details

Enter:

  • Key Vault Resource ID
  • Secret Name

Click Add Certificate.

Figure 11. Providing Key Vault Resource ID and Secret Name

Step 3: Deploy the required roles

After the certificate details are added, a New Roles Available notification is displayed.

Click View Details.

Figure 12. New roles available in Db2 as a Service BYOC

Step 4: Deploy the updated ARM template

  1. Click Download Template.
  2. Click Deploy.
  3. Complete ARM deployment in Azure.

The role updates grant permission to retrieve the certificate from Azure Key Vault.

Figure 13. Deploy updated ARM template in Db2 as a Service BYOC

step 5; Trigger certificate update

After the ARM template deployment completes successfully, an SRE initiates the certificate update operation by invoking the certificate update API endpoint.

The update process:

  • Retrieves the certificate from Azure Key Vault.
  • Updates dataplane certificates.
  • Propagates the certificate to dataplane and engine services.

Result:

The existing TLS certificate is replaced with the new certificate stored in Azure Key Vault without redeploying the dataplane.