Certificate Management

Learn about certificates in Oracle Communications Unified Assurance and how to manage them.

Unified Assurance leverages SSL certificates for security, trust, and authentication in parts of the product. It includes a root CA bundle and a certificate generation tool in order to secure connections between internal components. You can optionally use a prepackaged CSR if you want to use an externally signed web certificate.

Certificates and corresponding keys are located in the following directory:

$A1BASEDIR/etc/ssl

About Unified Assurance Generated Certificates

Unified Assurance generated certificates use a trust chain that starts with the Unified Assurance Global CA. New installations and rotated systems use the UnifiedAssuranceCA.crt and UnifiedAssuranceCA.key files for the Global CA. Upgraded systems that have not yet rotated certificates may still include the legacy Assure1CA.crt Global CA certificate.

The Unified Assurance Site CA signs internal Host, User, Vision, and Unified Assurance generated Web certificates. The BundleCA.crt, BundleCA.p12, and BundleCA.jks files contain the Unified Assurance certificate chain that internal components use to trust each other.

During certificate rotation, Unified Assurance creates cross-signed Global CA and Site CA certificates so that components using the previous certificates and components using the new certificates can continue to trust each other during the rollout.

Note:

You run most of the commands in this document as the root user. Before running the commands, set environment variables by running the following command:

source <UA_home>/.bashrc

where <UA_home> is the directory where you installed Unified Assurance, typically /opt/assure1.

About Certificate Expiry

Applications that rely on certificates, such as Docker and SVN, may stop functioning when certificates expire.

Host and User certificates expire after five years, and you must regenerate them when they expire. Because each server has its own Host certificate, certificates may expire at different times, depending on when the server was initially installed. If you want consistent expiration dates, you can regenerate all Host certificates on the same day, even those that have not yet expired, one server at a time.

Web certificates issued as of March 15, 2026 expire every 6.5 months (199 days). Thirteen month certificates issued before that date will continue to work on all major browsers up until their expiry date.

When Unified Assurance generated certificates are close to expiry, rotate the certificates from the primary presentation server. Certificate rotation regenerates the Unified Assurance generated certificate chain and distributes updated certificate files to the other Unified Assurance servers. See Rotating Unified Assurance Generated Certificates for more details.

Checking for Expired Certificates

You can view expired certificates and certificates that expire soon in the Servers UI.

In the All Servers list, the Server Name column includes warning icons for servers with certificates that have expired or expire within the warning period. The default warning period is 60 days. To change the warning period, update the CertExpiryWarning global property in the Global Properties UI. To view the certificate names and expiration dates, place the pointer over the warning icon.

To view a server's certificates and expiration dates, select a server from the list. You can also add the Cert Expiry column to the All Servers list. This column shows expiration dates for certificate files in the $A1BASEDIR/etc/ssl directory on each server. You can filter and sort the column.

To view all certificate expiration dates on a server, run the following command:

for cert in "$A1BASEDIR"/etc/ssl/*.crt; do
    echo "$cert"
    openssl x509 -in "$cert" -noout -dates
done

Rotating Unified Assurance Generated Certificates

Certificate rotation replaces the Unified Assurance generated certificate chain. Rotation creates a new Unified Assurance Global CA, creates a cross-signed Global CA, creates a cross-signed Site CA, creates a new Site CA, regenerates dependent Unified Assurance generated certificates, updates BundleCA.crt, BundleCA.p12, and BundleCA.jks, updates trust stores, and requests the other Unified Assurance servers to update their local certificate files.

Run certificate rotation when the certificate expiry information in the Servers UI shows that Unified Assurance generated certificates are expired or approaching expiry, or when your organization's certificate policy requires a new certificate chain.

You must run certificate rotation from the primary presentation server as the root user or with sudo privileges. If you run the command on another server, the command stops with an error.

Before rotating certificates:

Plan a maintenance window for service restarts after the rotation command completes.
Confirm that the other Unified Assurance servers are online when possible. If a server does not receive the rotation broadcast, you can update that server later by running CreateSSLCertificate --UpdateLocalCerts.
If the environment includes OpenSearch, confirm that the OpenSearch cluster is healthy. If the OpenSearch cluster does not become green or yellow during rotation, the OpenSearch JWT signing key certificate update is skipped.

WARNING:

Do not run certificate rotation if your environment has more than one node in the OpenSearch cluster. The CreateSSLCertificate --RotateCertificates command can trigger OpenSearch certificate updates on multiple servers during the same rotation. Because this process does not perform a coordinated rolling restart of OpenSearch nodes, it can break quorum in a multi-node OpenSearch cluster.

Note:

Certificate rotation does not regenerate externally signed Web certificates. If you use an externally signed Web certificate, plan to manually generate and install a new externally signed Web certificate when the old one is due to expire. See Importing the Unified Assurance Global CA Certificate in Unified Assurance User's Guide for more information.

To rotate Unified Assurance generated certificates:

On the primary presentation server, set environment variables by running the following command:
```
source <UA_home>/.bashrc
```
where <UA_home> is the directory where you installed Unified Assurance, typically /opt/assure1.
Run certificate rotation:
```
$A1BASEDIR/bin/CreateSSLCertificate --RotateCertificates
```
The command performs the following actions on the primary presentation server:
- Backs up the existing Global CA and Site CA files.
- Creates UnifiedAssuranceCA.crt and UnifiedAssuranceCA.key.
- Creates cross-signed Global CA and Site CA certificates for the transition.
- Creates a new SiteCA.crt and SiteCA.key.
- Regenerates User, Vision, Host, and, if internally signed, Web certificates.
- Updates BundleCA.crt, BundleCA.p12, and BundleCA.jks.
- Preserves external CA certificates that were already included in BundleCA.crt.
- Copies updated certificate files to OpenSearch and Podman certificate directories when those directories exist.
- Restarts assure1-db and assure1-web on the primary presentation server, broadcasts the certificate update request to the other Unified Assurance servers, waits while remote updates begin, and then restarts assure1-bus and assure1-broker on the primary presentation server.
Review the command output.

If the command completed successfully, the output includes the following message:
```
Certificate rotation complete.
```
If the environment includes OpenSearch and the OpenSearch certificate update completes successfully, the output includes messages that the OpenSearch cluster is healthy and that the JWT signing key certificate was updated and applied.

Updating Certificates on an Unresponsive Server

If the rotation command output lists an unresponsive server, run the following command on that server after it is online:

$A1BASEDIR/bin/CreateSSLCertificate --UpdateLocalCerts

The --UpdateLocalCerts command reads shared certificate files from the primary presentation server, updates the local certificate files, regenerates the local Host certificate, and copies updated certificate files to OpenSearch and Podman certificate locations when those directories exist. If the server includes a running microservice cluster or OpenSearch deployment, --UpdateLocalCerts also updates the microservice cluster certificate resources or OpenSearch JWT signing key certificate.

Rebroadcasting Certificate Updates After Rotation

If certificate rotation completes successfully, but validation shows that multiple servers are missing the updated certificates, rebroadcast the certificate update request from the primary presentation server.

On the primary presentation server, set the Web FQDN:
```
export $WEBFQDN=<web_host>
```
where <web_host> is the FQDN of the load balancer or shared FQDN for the presentation server that users visit to access Unified Assurance.

Run the following command as the assure1 user:

$A1BASEDIR/bin/BrokerControl --batch CALL UpdateCerts $WEBFQDN 1

Verify that each server has the updated certificates.
Restart the relevant system services and Unified Assurance services as described in Restarting Services.

Completing a Skipped OpenSearch Certificate Update

If the OpenSearch cluster is red or unavailable during certificate rotation, the OpenSearch JWT signing key certificate update is skipped. Restore OpenSearch cluster health, and then run the following command:

$A1BASEDIR/bin/historical/AnalyticsWizard --Update-Certs

The command restarts the local analytics database service, waits for the OpenSearch cluster health to become green or yellow, updates the OpenSearch JWT signing key certificate, and applies the updated OpenSearch security configuration.

Restarting Services

Note:

Verify that each server has the updated certificates before you restart services.

To restart services:

Run the following commands to restart the relevant system services on each server where they are installed:

systemctl restart assure1-db
systemctl restart assure1-bus
systemctl restart assure1-broker
systemctl restart assure1-web

Restart Unified Assurance services as the assure1 user on each server so that running services use the updated certificates:
```
$A1BASEDIR/bin/BrokerControl --batch stopall
$A1BASEDIR/bin/BrokerControl --batch startall
```

Restarting Microservice Workloads

If the environment includes a microservice cluster, you must restart all microservices in the cluster so that pods load the updated certificate secrets.

Restart Pulsar first. See Restarting Pulsar Workloads in Unified Assurance Implementation Guide for the Pulsar restart procedure.

You do not need to restart the services running in the submariner-operator namespace.

To restart all other microservices:

Run the following restart command as the assure1 user for each deployment:
```
a1k -n <namespace> rollout restart deployment/<deployment-name>
```
To check the status of the rollout, run the following command as the assure1 user:
```
a1k -n <namespace> rollout status deployment/<deployment-name>
```

In these commands:

<namespace> is the namespace that contains the microservice.
<deployment-name> is the name of the deployment to restart.

If the affected workload is not a deployment, replace deployment with the appropriate workload type, such as statefulset or daemonset.

If the environment uses Kafka Bridge with TLS or mTLS, update the Kafka Bridge certificate secret with the latest certificate files before you restart Kafka Bridge. For information about Kafka Bridge certificate secrets, see Certificate Secret in Unified Assurance Implementation Guide.

After you update the certificate secret, restart Kafka Bridge:

a1k -n <namespace> rollout restart deployment/<kafka-bridge-deployment-name>
a1k -n <namespace> rollout status deployment/<kafka-bridge-deployment-name>

Note:

After rotation, provide the latest BundleCA.crt to any external clients that send HTTPS requests to microservices. Requests that use an older BundleCA.crt may fail TLS validation.
RKE2 certificates are not related to the Unified Assurance generated certificates. See Rotating RKE2 Certificates to rotate these certificates.

Verifying Certificate Rotation

In the Servers UI, verify that the certificate expiration dates reflect the newly generated certificates.

Certificate rotation automatically updates Podman certificate locations when those directories exist. If OpenSearch is running, certificate rotation copies the updated certificate files to the OpenSearch certificate directory, restarts the local analytics database service, waits for OpenSearch cluster health to become green or yellow, and then updates and applies the OpenSearch JWT signing key certificate. You do not need to manually copy the updated BundleCA.crt to OpenSearch or Podman certificate directories as part of certificate rotation.

First Rotation After Upgrade

If you are upgrading from an environment that uses the legacy Assure1CA.crt Global CA, the first certificate rotation moves the environment to the UnifiedAssuranceCA.crt Global CA.

During this first rotation, Unified Assurance copies the previous Global CA to UnifiedAssuranceCA-old.crt and writes that previous Global CA to BundleCA.crt as part of the transition chain. This transition chain helps preserve trust while servers and services load the newly generated certificates.

Oracle recommends planning another maintenance window and running certificate rotation a second time to remove the legacy Assure1CA.crt Global CA from the certificate chain. This will allow your system to stay up to date with dual-signed certificate chains.

Renewing Unified Assurance Generated Web Certificates and Host Certificates

Use this procedure when you need to renew a specific Host certificate or Unified Assurance generated Web certificate. To regenerate the full Unified Assurance certificate chain, use Rotating Unified Assurance Generated Certificates.

To renew certificates:

On each server, set environment variables and regenerate the Host certificate by running the following commands:
```
export $HOSTFQDN=<host>
$A1BASEDIR/bin/CreateSSLCertificate --Type Host --CN $HOSTFQDN --Force
```
where:
- <UA_home> is the directory where you installed Unified Assurance, typically /opt/assure1.
- <host> is the appropriate server FQDN, for example hostname.example.com.
If your Web certificate is not signed by an external third-party, on presentation servers, regenerate the Web certificate by running one of the following sets of commands:
- For non-redundant environments:
```
export $WEBFQDN=<web_host>
$A1BASEDIR/bin/CreateSSLCertificate --Type Web --CN $WEBFQDN --Force
```
- For redundant environments:
```
export $WEBFQDN=<web_host>
export $HOSTFQDN1=<primary_host>
export $HOSTFQDN2=<secondary_host>
$A1BASEDIR/bin/CreateSSLCertificate --Type Web --CN $WEBFQDN --AltCN $HOSTFQDN1 --AltCN $HOSTFQDN2 --Force
```
where:
- <UA_home> is the directory where you installed Unified Assurance, typically /opt/assure1.
- <web_host> is the FQDN of the load balancer or shared FQDN for the presentation server that users visit to access Unified Assurance. For example, presentation.example.com.
- <primary_host> is the host FQDN of the primary presentation server. For example, hostname1.example.com.
- <secondary_host> is the host FQDN of the secondary presentation server. For example, hostname2.example.com.
If you do not know the values for <primary_host> or <secondary_host>, you can find them in the Servers UI, or by running the following commands on the primary presentation server:
```
a1mysql
select ServerHostFQDN, WebFQDN, ServerID, PrimaryServerID from Servers where IsPresentation=1;
select ServerHostFQDN, WebFQDN, ServerID, PrimaryServerID from Servers where PrimaryServerID in (select ServerID from Servers where IsPresentation=1);
```
If you regenerated the Web certificate, restart the web server by running the following command:
```
service assure1-web restart
```
On each server, reload the Broker to update the new certificate expirations by running the following command as the assure1 user:
```
$A1BASEDIR/bin/BrokerControl --batch reload
```

Rotating RKE2 Certificates

By default, RKE2 certificates expire after 12 months. To rotate certificates that have expired or will expire in 90 days or fewer, restart the RKE2 Server service using the Services UI.

Using an Externally Signed Web Certificate

By default, Web certificates are automatically signed by the Unified Assurance Global CA. This CA is not known to major web browsers and will display a warning to users. Without the CA being trusted, users must either allow an exception to the certificate or import the Unified Assurance Global CA. Most organizations will instead prefer users have a seamless experience by signing the Web certificate with a trusted vendor known by default to all major web browsers.

Certificate rotation does not regenerate an externally signed Web certificate. When rotation detects that Web.crt is signed by an external CA, it skips Web certificate generation and prints a warning that you must manually generate and install a new Web certificate signed by the external CA. Certificate rotation preserves external CA certificates that are already included in BundleCA.crt and adds them to the regenerated BundleCA.crt file.

To set up an externally-signed Web certificate:

Gather the certificate request from the primary presentation server:
```
$A1BASEDIR/etc/ssl/Web.csr
```
Send the certificate request to the external authority for signing.
Copy the signed certificate sent back by the external authority to $A1BASEDIR/etc/ssl/Web.crt, overwriting the existing file.
(Optional) If the certificate request and key were not generated from Unified Assurance (for example, using a wildcard certificate for your domain), you will need to update the associated key. Copy the key file sent back by the external authority to $A1BASEDIR/etc/ssl/Web.key, overwriting the existing file.
Identify the intermediate chain file and add the contents to both the signed certificate file and the bundle CA certificates file:
```
cat intermediate.pem >> $A1BASEDIR/etc/ssl/Web.crt
cat intermediate.pem >> $A1BASEDIR/etc/ssl/BundleCA.crt
```
Copy the updated BundleCA.crt to every existing Unified Assurance server. New Unified Assurance servers will automatically get the new BundleCA.crt when they join.
Update the Podman trusted CA file on every existing server with the Presentation.Internal or any Cluster roles. New Unified Assurance servers will automatically use the correct CA file during installation.
```
cp $A1BASEDIR/etc/ssl/BundleCA.crt /etc/containers/certs.d/*/ca.crt
```
Note:

The command may fail if there is more than one directory in /etc/containers/certs.d. To resolve this, replace the ca.crt in the directory of the hostname used by the Podman system.
On all OpenSearch servers (those with the Database.Historical role), update the BundleCA.crt for OpenSearch:
```
cp $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/vendor/opensearch/config/certs/BundleCA.crt
```
Restart Telegraf, OpenSearch, and OpenSearch Dashboards.
Restart Apache to start using the new certificate:
```
systemctl restart assure1-web
```
Verify that the new certificate works.
Disable the login banner that prompts users to install the Unified Assurance global certificate:
1. In the UI, from the main navigation menu, select Configuration, and then Global Properties.
2. Select CertificateAuthorityWarning.
3. In the form, change Property Value to 0, then click Submit.

Troubleshooting Existing Certificates

The BundleCA.crt contains details of the full Unified Assurance trust chain and optionally, the chain from your external certificate authority. To ensure correct functionality:

Check that BundleCA.crt matches the following files:

diff $A1BASEDIR/etc/ssl/BundleCA.crt /etc/containers/certs.d/*/ca.crt
diff $A1BASEDIR/etc/ssl/User-assure1.crt /etc/containers/certs.d/*/client.cert
diff $A1BASEDIR/etc/ssl/Host.crt $A1BASEDIR/vendor/opensearch/config/certs/Host.crt
diff $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/vendor/opensearch/config/certs/BundleCA.crt
diff $A1BASEDIR/etc/ssl/User-assure1.crt $A1BASEDIR/vendor/opensearch/config/certs/User-assure1.crt

Check that BundleCA.crt can validate all certificates in the $A1BASEDIR/etc/ssl directory:

openssl verify -verbose -show_chain -CAfile $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/etc/ssl/User-assure1.crt 
openssl verify -verbose -show_chain -CAfile $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/etc/ssl/User-api.crt 
openssl verify -verbose -show_chain -CAfile $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/etc/ssl/User-kibana.crt 
openssl verify -verbose -show_chain -CAfile $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/etc/ssl/User-repl.crt 
openssl verify -verbose -show_chain -CAfile $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/etc/ssl/User-root.crt 
openssl verify -verbose -show_chain -CAfile $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/etc/ssl/Web.crt 
openssl verify -verbose -show_chain -CAfile $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/etc/ssl/Host.crt 
openssl verify -verbose -show_chain -CAfile $A1BASEDIR/etc/ssl/BundleCA.crt /etc/docker/certs.d/*/client.cert 
openssl verify -verbose -show_chain -CAfile $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/vendor/opensearch/config/certs/Host.crt 
openssl verify -verbose -show_chain -CAfile $A1BASEDIR/etc/ssl/BundleCA.crt $A1BASEDIR/vendor/opensearch/config/certs/User-assure1.crt

Title and Copyright Information

Security Guide

G49436-03