Upgrade Best Practices

Curity releases upgrades and new versions of the Curity Identity Server on a regular basis. As much as possible, all upgrades are backwards compatible, though major releases may introduce occasional breaking changes. This tutorial lists the steps you should follow to ensure a resilient upgrade process for the Curity Identity Server.

Upgrades of the Curity Identity Server typically require two main operations, to upgrade the product itself and to upgrade the data storage schema. In some cases, these tasks are performed by different people, like a DevOps team and a database administrator (DBA).

The Upgrade Data Sources explains ways to manage database schema updates and keep the current schema aligned with the product. This tutorial explains more about upgrading the product and its plugins, then provides a checklist of upgrade steps.

Use Parameterized Configuration

When you first onboard to the Curity Identity Server, do some work to take the pain out of upgrades. Use the Configuration System to create parameterized configuration and avoid duplication of security settings across stages of the deployment pipeline. The Configure Deployed Environments tutorial explains the techniques. The following example Dockerfile deploys shared configuration.

FROM curity.azurecr.io/curity/idsvr:11.0.0
COPY --chown=10001:10000 config/*.xml /opt/idsvr/etc/init/

Use a Custom Machine Image

If you run the Curity Identity Server on containers or virtual machines, deploy parameterized configuration to a custom image. Then, use that image for all stages of your deployment pipeline. The machine image can contain assets such as the following.

• Configuration XML files
• Themes and branding customizations
• JavaScript procedures with custom logic
• Plugins with deeper customizations

Once you have a versioned machine image, most upgrades only require you to change the base image version for one or more stages of your deployment pipeline.

Practice Local Upgrades

Since the Curity Identity Server is a cloud native product, you can practice deployment on a standalone computer. You can easily rehearse the following types of upgrades and downgrades.

• Redeploy the 10.6 version
• Upgrade from 10.6 to 10.7
• Upgrade from 10.7 to 11.0
• Downgrade from 11.0 to 10.7

A local setup can work well to ensure that the core upgrade works as expected.

• Run a local deployment using a technology like Docker Compose.
• Use OAuth Tools to test some end-to-end flows.

In some cases, deployed environments for the Curity Identity Server may be considerably more complex, with many external dependencies. You might therefore use simplified configuration for local deployments. Still, a local deployment can play a useful role to identify potential upgrade issues as early as possible in the deployment pipeline.

Upgrade Frequently

Aim to frequently upgrade the version of the Curity Identity Server, such as one upgrade per quarter. Doing so keeps your applications up to date with the latest security features. Frequent upgrades help to ensure a reliabile technical process and alleviate any potential people concerns.

Always Follow Upgrade Instructions

The System and Operation Guide explains the main upgrade technical steps. Always follow the upgrade instructions, whether performing a minor or major upgrade. For most upgrades, the process requires little or no changes other than deploying a new machine image.

Separate Plugin Upgrades from System Upgrades

When you develop Custom Plugins to extend the Curity Identity Server, use the Server-Provided Dependencies that match the latest product version. During development, avoid deployments to test environments solely to test plugins. Instead, test plugins on a local computer with the following steps, so that you get fast feedback:

• Run a local deployment, such as that in the GitHub repository for the Custom Username Password Authenticator.
• Use OAuth Tools to test some end-to-end flows that use the plugins.

For major upgrades, server dependency versions, or the Java runtime, may change to a newer version. This does not necessarily mean you have to create new versions of plugins in advance of every major upgrade. Plugins built with an older version of Java, or using an old version of a server dependency, typically work with a newer version of the Curity Identity Server without changes. In some cases however, the upgrade instructions may indicate that an old library or Java version is no longer supported for security reasons. In this case, you need to upgrade custom plugins as well.

Follow an Upgrade Checklist

Although most upgrades are straightforward, the process can consist of multiple steps. If you are on a very old version of the Curity Identity Server you should carefully read upgrade instructions to understand all steps to upgrade to the latest product version. The following sections describe the main upgrade steps that Curity recommends.

Produce a New Machine Image

First, produce a new image for the Curity Identity Server and use it for both the admin and runtime nodes. For major upgrades, you may decide to update plugins in advance of the upgrade. In some cases you may have slightly different machine images for particular environments. As a first upgrade step, produce any new machine images.

Test the New Image

Use different image version tags for different stages of the pipeline. For example, if you upgrade from 10.7 to 11.0 you can initially run 11.0 only in test systems, while keeping production on version 10.7. Later, once tests pass, change the production machine image.

Upgrade Data Sources

When required, make schema upgrades to data sources before updating workloads of the Curity Identity Server. The Upgrade Data Sources tutorial explains how ways to automate schema upgrades. Database schemas are backwards compatible with recent versions of the Curity Identity Server. However, if you are on a very old version, consult the upgrade instructions to understand the sequence of schema changes.

Ensure Zero Downtime

Next, upgrade the admin and runtime nodes. The system and operation guide explains how you must renew cluster keys on every upgrade. If you use Kubernetes, the Helm Chart automates the creation of new cluster keys. For other environments, use automation like the genclust tool from the Running in Cluster Mode tutorial. The following example commands create an environment-specific cluster XML file to deploy to the $IDSVR_HOME/etc/init folder.

#!/bin/bash

docker run -d -p 6749:6749 -e PASSWORD=Password1 --name curity curity.azurecr.io/curity/idsvr:latest
trap 'docker rm -f curity 1>/dev/null 2>&1' EXIT
docker exec -i curity bash -c "genclust -c idsvr-admin.company.local" > cluster.xml

Use the hosting platform's capabilities to only replace old runtime nodes when a new runtime node reports that it is ready to receive requests. See the Health and Auto Healihg tutorial for more about statuses and readiness. For a short time, old and new runtime nodes run side by side. Both old and new instances can process OAuth requests from applications.

Ensure a Rollback Capability

For best reliability, plan for a worst case scenario after an upgrade. Ensure that you can switch back to the old machine image and perform a downgrade. If you upgraded data source schemas, leave them on the new version so that there is no data loss, then downgrade the admin and runtime nodes.

Perform Post-Upgrade Data Updates

You may want to change identity data after some upgrades, such as to execute SCIM Updates on User Accounts or to use GraphQL to Create OAuth Database Clients. Such a step typically runs after the actual upgrade. Develop a client that can run against all stages of the pipeline, so that you avoid manual steps and ensure reliability.

Summary

An authorization server manages many security settings so that applications can externalize this responsibility. In the Curity Identity Server, use the configuration system to manage settings with minimal duplication. Other than security configuration, upgrading the Curity Identity Server should work in a similar way to upgrading your APIs.

Join our Newsletter

Get the latest on identity management, API Security and authentication straight to your inbox.

Email

Subscribe

I agree to Curity's Privacy Policy

Start Free Trial

Try the Curity Identity Server for Free. Get up and running in 10 minutes.

Start Free Trial