Customizing user-facing certificates

Edit online

Replace the default user-facing TLS certificate that cert-manager generates with a custom TLS certificate for a DataPower Interact Gateway deployment.

Before you begin

Make sure that you meet the following requirements.

Create or obtain TLS certificates that contain the host names that are required for your IDIG deployment.
Requirements for creating custom certificate secret.
- Create a Kubernetes TLS secret of type kubernetes.io/tls that contains the tls.crt, tls.key, and ca.crt fields.
- Include all required Subject Alternative Names (SANs) for the exposed IDIG hostnames in the certificate. For example, include idig.domain, ai.domain if Analytics is enabled, and devportal.domain if Developer Portal is enabled.

About this task

DataPower Interact Gateway uses TLS certificates to secure communication between platform components and external clients. By default, cert-manager generates and manages certificates for all user-facing endpoints.

You can replace the default user-facing certificate with a custom certificate. The user-facing certificate is the server certificate that is presented to users when they access the IDIG endpoints.

DataPower Interact Gateway supports customization of the following user-facing endpoints.

Table 1. User-facing endpoints
Endpoint	Default hostname
IDIG	`idig.domain`
Analytics ingestion	`ai.domain`
Developer Portal	`devportal.domain`

idig.domain is set in the IDIG cluster CR. For details, see Deploying IDIG cluster. When you provide a custom certificate, the IDIG operator configures the platform to use the certificate that you specify.

Note: It is recommended that you customize only the user-facing ingress certificate. Internal service certificates and intra-subsystem certificates are managed by the platform operators and must not be modified.

For details about the TLS certificates you can customize and the certificates that are managed automatically by the IDIG platform, see DataPower Interact Gateway TLS certificates.

Procedure

Create a Kubernetes TLS secret that contains the certificate and private key of your custom certificate.

kubectl create secret tls idig-custom-cert \
  --cert=/path/to/your/certificate.crt \
  --key=/path/to/your/private.key \
  -n namespace

Add the CA certificate to the secret.

kubectl patch secret idig-custom-cert -n namespace \
  --type='json' \
  -p='[{"op":"add","path":"/data/ca.crt","value":"base64-encoded-ca.crt"}]'

Reference the secret in the IDIG cluster CR.
Open the IDIG cluster CR (release_files/samples/deployment profile yaml file) and configure the customIngressCertificate property.

The customIngressCertificate value must match the name of the Kubernetes TLS secret that you created.
```
apiVersion: datapowerinteractgateway.ibm.com/v1beta1
kind: DatapowerInteractGatewayCluster
metadata:
  name: idig
  namespace: namespace
spec:
  domain: example.com
  customIngressCertificate: idig-custom-cert
```
Apply the updated CR.
```
kubectl apply -f idig-cluster.yaml
```
The IDIG operator validates the referenced secret and updates the IDIG platform to use the specified certificate.

Generating a self-signed certificate and Kubernetes secret

The following example shows how to generate a self-signed certificate with the required SANs and create the Kubernetes secret:

# Generate self-signed certificate with all required SANs
openssl req -x509 -newkey rsa:4096 \
  -keyout /tmp/idig.key \
  -out /tmp/idig.crt \
  -days 365 -nodes \
  -subj "/CN=idig.example.com" \
  -addext "subjectAltName=DNS:idig.example.com,DNS:ai.example.com"

# Create Kubernetes secret
kubectl create secret tls idig-custom-cert \
  --cert=/tmp/idig.crt \
  --key=/tmp/idig.key \
  -n namespace

# Add CA certificate
kubectl patch secret idig-custom-cert -n namespace \
  --type='json' \
  -p='[{"op":"add","path":"/data/ca.crt","value":"base64-encoded-idig.crt"}]'

Update the host names to match your deployment.

What to do next

If Analytics is enabled and you use custom client certificates for Analytics ingestion, see Customizing Analytics mTLS client authentication.

If you encounter any problem while customizing the user facing certificates, see Troubleshooting certificate customization.