TLS Update Process - bcgov/PIMS GitHub Wiki

Description

The pims.gov.bc.ca uses Transport Layer Security to secure the connection in the user's browser. This is a requirement for the https protocol and a necessity for using this custom URL for the application.

The TLS certificate expires yearly and must be renewed with its provider then updated in the configuration for the relevant OpenShift route.

You can use your browser to view the current status of the TLS certificate. This process depends on your browser, but it often starts by clicking on the lock icon in your browser's address bar. Among other properties, you can view the issue and expiry dates.

image

Steps

1. Expiry Notification

This process will begin about a month from the certificate's expiry date. The CITZ IMB Technical Services team will be notified by CITZ Identity Management Solutions. Once it's confirmed that a renewed certificate is required, they will forward the newly generated certificate files to the PIMS team contact.

These files should include:

  • pims.gov.bc.ca.txt
  • pims.gov.bc.ca.key (may have to specifically request that this is generated)
  • TLSChain.txt
  • TLSRoot.txt (not used)
  • TrustedRoot.txt (not used)

2. Backup/Download Original Configuration

The Route in OpenShift that allows for external access to the react-app service is titled pims-app. If you need to inspect it with the UI, log in to OpenShift in your browser, enter the production namespace, use Administrator view, and find it under Networking > Routes in the side menu.

Log in to the OpenShift CLI. You can find this command with your temporary token after logging in to the OpenShift portal and clicking your email at the top right, followed by Copy login command.

Once logged in and in the correct namespace, run the following command to download a copy of the current route configuration.

oc get route pims-app -o yaml > pims-app.yaml

Please consider making a copy of this configuration. This way, we have the previous configuration if something goes wrong with the following steps.

cp pims-app.yaml pims-app.yaml.bak

3. Updating the Configuration File

In the pims-app.yaml file you downloaded, you should see three fields under the tls heading.

Take the contents of your new certificate files and replace these values in the pims-app.yaml file according to this table:

File Field
pims.gov.bc.ca.txt certificate
pims.gov.bc.ca.key key
TLSChain.txt caCertificate

You can start each field with the |- syntax to indicate that you're entering a multi-line value.

For example:

certificate: |-
  -----BEGIN CERTIFICATE-----
  [ ... ]
  -----END CERTIFICATE-----

4. Apply New Configuration

Once the new certificate has been copied and pasted into the .yaml file, save it, then do a dry run using the following command:

oc apply -f pims-app.yaml --dry-run=client

If the dry run was successful, you should see the following with no errors:

route.route.openshift.io/pims-app configured (dry run)

As long as there are no errors, apply the new .yaml which will update the route in OpenShift:

oc apply -f pims-app.yaml

If the process was successful, you will see an output similar to below:

route.route.openshift.io/pims-app configured

5. Validate Success

Please check the live site after making this update.

If there was an issue with the certificate, you may receive a warning when visiting pims.gov.bc.ca, or you may be blocked entirely.

You should be able to inspect the certificate the same way as mentioned in the Description section, and it should contain the new expiry dates.

The previous certificate should still be valid assuming this process is completed in advance. Use the backup you created in step #2 to restore functionality until the issue can be resolved.