Upgrade Best Practices
On this page
Curity releases upgrades and new versions of the Curity Identity Server on a regular basis (see also the release schedule). 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.
Invest in Deployment
Prepare a machine image (usually Docker-based or a virtual machine) with resources that are the same for all environments of the deployment pipline. Each deployment contains at least some of the following assets to configure the behavior of the Curity Identity Server.
- Configuration XML files
- Themes and branding customizations
- JavaScript procedures with custom logic
- Plugins with deeper customizations
At every stage of the deployment pipeline, apply environment-specific configuration settings together with the machine image to deploy the Curity Identity Server. The Configuration System takes most of the pain out of production upgrades, since it prevents duplication of security settings to improve reliability.
At runtime, your continuous delivery system can inject environment-specific values to complete the deployment of admin and runtime nodes. The Configure Deployed Environments tutorial explains the techniques. The following image illustrates a Docker-based pipeline deployment that combines the machine image (binary) with environment-specific configurations.
Run Local Upgrades
When designing deployments, make sure you include a local environment for development on standalone computers. Since the Curity Identity Server is a cloud native product, you can easily rehearse upgrades and downgrades, such as the following examples.
- Redeploy the 9.5 version
- Upgrade from 9.5 to 9.7
- Upgrade from 9.7 to 10.1
- Downgrade from 10.1 to 9.7
The following type of local setup can work well to ensure that the upgrade basic steps work 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 also iron out any technical issues to ensure reliable deployments.
Always Follow Upgrade Instructions
The System Admin 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 Campaign
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 may need to run multiple campaigns to upgrade the system to the latest product version. The following sections describe the high level steps that we recommend for an upgrade process.
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 9.7 to 10.1 you can initially run 10.1 only in test systems, while keeping production on version 9.7. Later, once tests pass, change the production machine image.
Upgrade the Database
For major upgrades, there may be changes to the database schema to add new tables or columns. Upgrade the database first. 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 release notes to understand the sequence of database upgrades.
Ensure Zero Downtime
Next, upgrade the admin and runtime nodes. The system admin 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/bashdocker run -d -p 6749:6749 -e PASSWORD=Password1 --name curity curity.azurecr.io/curity/idsvr:latesttrap 'docker rm -f curity 1>/dev/null 2>&1' EXITdocker 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 the database, leave it on the new version so that there is no data loss, then downgrade the admin and runtime nodes.
Perform Post-Upgrade Data Updates
In some cases you may want to change identity data after an upgrade, such as with SCIM Updates to User Accounts or GraphQL to Create OAuth Clients that use database storage. Although this is not part of the upgrade itself, 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.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free Trial
