Upgrading from 7.6.X to 8.0.0

Upgrading the XML Configuration

Description Applicability Change Method
Restructuring of the WebAuthn authenticator settings Deployments using the WebAuthn authenticator Automatic using XSLT, or manual
Changing the default for haapi/use-legacy-dpop Deployments with clients having the HAAPI capability Automatic using XSLT, or manual

As with previous releases, the XML configuration can be converted using a provided XSLT and its associated auto-upgrade.sh script. To run the XSLT on a configuration data set, run the auto-upgrade.sh script:

Listing 94 Upgrading from 7.6.X to 8.0.0 using the provided XSLT and auto-upgrade.sh
$ $INSTALL_DIR/misc/upgrade/7.6-to-8.0/auto-upgrade.sh $IDSVR_HOME/etc/init/some-config.xml

Authorization custom token procedures update

When custom authorization token procedures are used, they must be updated to return the iss parameter to comply with RFC 9207 OAuth 2.0 Authorization Server Issuer Identification.

Update all procedures with authorize-authorization-code, authorize-implicit or authorize-hybrid type, to add the issuer provided in the procedure context into the responseData as highlighted in the example below:

function result(context) {
  var responseData = {
      code: issuedAuthorizationCode,
      state: context.providedState,
      iss: context.issuer,
  return responseData;

DynamoDB schema changes

This release brings user accounts listing by user name or email on DynamoDB through the accounts GraphQL query as well as through the Devops Dashboard. To use this feature, a data migration and a schema update of the accounts table on DynamoDB are needed as described below, otherwise they are optional.

To upgrade the DynamoDB accounts table, the following steps must be carried out:

  1. Upgrade Curity Identity Server to version 8.0.0 or above following the General Upgrade Procedure.
  2. Migrate the data in DynamoDB accounts table.
  3. Create the global secondary indexes on the DynamoDB accounts table.
  4. Restart Curity Identity Server cluster nodes.

Migrate the data in DynamoDB accounts table

To list accounts using GraphQL with paginated results and starts with search, two new attributes are needed on every account item:

  • userNameInitial: the first three letters of the userName attribute,
  • emailInitial: the first three letters of the email attribute.


It is important to migrate the data after Curity Identity Server version 8.0.0 is running on all nodes to ensure any new account is created with the extra columns, which can happen concurrently with the migration process.


It is important to migrate the data before creating the global secondary indexes to consume less read and write capacity units in DynamoDB.


Before migrating the data, the following information is needed:

  • the AWS region name where the Curity DynamoDB database is hosted,
  • the DynamoDB datasource configuration in the Curity Identity Server, namely :
    • the table prefix, if any,
    • the AWS ARN role used when requesting temporary credentials, if any.
  • the maximum read and write capacity units, using the AWS Management Console for Amazon DynamoDB or the AWS CLI, if the DynamoDB curity-accounts table is using provisioned capacity,
  • an account allowed to read and write to the curity-accounts table in DynamoDB which can be defined as:
    • an access key identifier and secret,
    • or, a configuration profile defined in the local ~/.aws/credentials file,
    • or, use Amazon EC2 Instance Metadata Service,
    • or, use Web identity token credentials with the AWS STS (can be used with IAM Role for Service Accounts in EKS),
    • or, use a default credential provider that automatically looks for available credentials.

Data migration

A command line data migration tool is provided in the $IDSVR_INSTALL/misc/upgrade/7.6-to-8.0 directory.


The migration procedure will scan the whole curity-accounts table and update every item, thus consuming the read and write capacity required for reading all items and writing approximately one quarter of all items. It is advised to migrate the data during low activity periods. Moreover, if your curity-accounts table is configured with provisioned capacity, you must specify the --max-read-capacity and --max-write-capacity parameters to share resources between the migration tool and your production load:

  • When these parameters are set, the migration tool will automatically throttle the API call rate to avoid consuming all the provisioned capacity.
  • When these parameters are not set, the migration tool runs with unlimited capacity, and Denial of Service might happen for your production users or other applications.

The --max-read-capacity and --max-write-capacity parameters can also be set to reduce the call rate:

  • when the curity-accounts table is using on-demand capacity thus avoiding to create a traffic peak,
  • to avoid reaching the request limit applicable to the AWS account owning the DynamoDB database.

In a console, after cd to the $IDSVR_INSTALL/misc/upgrade/7.6-to-8.0 directory, run one of the following commands according to your case.

  • With credentials in user’s environment and table name prefix.

    • Credentials to connect to the DynamoDB are configured in the user’s environment,
    • AWS region: eu-west-1
    • Table name prefix: iam- (as a consequence the full table name will be iam-curity-accounts)
    ./upgrade-dynamodb.sh --aws-region eu-west-1 --use-default-credentials --table-name-prefix "iam-"
  • With credentials defined in a profile

    • Credentials to connect to the DynamoDB are configured in a production profile defined in ~/.aws/credentials file,
    • AWS region: eu-west-1
    ./upgrade-dynamodb.sh --aws-region eu-west-1 --aws-profile production
  • With credentials defined in a profile and assuming a role

    • Credentials to connect to the DynamoDB are configured in a production profile defined in ~/.aws/credentials file,
    • Assuming curity-dynamodb role
    • AWS region: eu-west-1
    ./upgrade-dynamodb.sh --aws-region eu-west-1 --aws-profile production --aws-role-arn curity-dynamodb
  • With provisioned capacity for curity-accounts table

    • Credentials to connect to the DynamoDB are configured in the user’s environment,
    • AWS region: eu-west-1
    • Provisioned read capacity units: 100
    • Provisioned write capacity units: 50
    • Target capacity for migration tool: 50%
    ./upgrade-dynamodb.sh --aws-region eu-west-1 --use-default-credentials --max-read-capacity 50 --max-write-capacity 25
  • Help about all the parameters available to run the data migration tool:

    ./upgrade-dynamodb.sh --help

Data migration result

After each run, the data migration tool displays a report and the migration result. When the Data migration completed successfully. message is displayed, data are migrated and global secondary indexes can be created. Otherwise, details about the encountered problems are displayed in the console.

The migration performed by this tool is idempotent and will not modify data if it was already migrated or created using version 8.0 or higher. It can be safely run several times, especially after a failure or an incomplete migration.

To get more details about the failures, the tool can be run with the following options:

LOG4J2_UPGRADE_LEVEL=debug ./upgrade-dynamodb.sh --aws-region eu-west-1 --use-default-credentials

Create the global secondary indexes on the DynamoDB accounts table


It is important to migrate the data before creating the global secondary indexes to consume less read and write capacity units in DynamoDB.

To allow listing user accounts through GraphQL, 2 global secondary indexes (GSI) must be added to the schema of the accounts table:

  • userNameInitial-userName-index: with userNameInitial attribute as partition key and userName attribute as sort key,
  • emailInitial-email-index: with emailInitial attribute as partition key and email attribute as sort key.

To facilitate updating the accounts table’s schema, JSON configuration files are provided with this release, in the $IDSVR_INSTALL/misc/upgrade/7.6-to-8.0 directory. A file is provided for each index to be created:

  • for userNameInitial-userName-index: curity-accounts-userNameInitial-userName-index.json,
  • for emailInitial-email-index: curity-accounts-emailInitial-email-index.json.


Each file also includes ProvisionedThroughput fields defining the index provisioned capacity. The values present in these fields are illustrative, and must be adapted to the operational requirements of each deployment environment.

These files can be used with the aws dynamodb update-table command and passed as arguments to --cli-input-json option, to create each of the indexes:

aws dynamodb update-table [...] --cli-input-json file://${D}/curity-accounts-userNameInitial-userName-index.json
aws dynamodb update-table [...] --cli-input-json file://${D}/curity-accounts-emailInitial-email-index.json

Restart Curity Identity Server cluster nodes

Once the data are migrated and the global secondary indexes created, restart each Curity Identity Server node so that the DynamoDB datasource enables the account listing feature.

WebAuthn authenticator

The WebAuthn authenticator was updated to improve support for passkeys. As a consequence, there were changes to the configuration model - which can be upgraded using the general instructions in the start of this guide - and some templates were modified.

The authenticator was also updated to support HAAPI. Refer to the section on HAAPI responses further down on this guide.

Updated templates

  • core/authenticator/webauthn/js/register.vm
  • core/authenticator/webauthn/register/get.vm

In order to use the new configuration options, any custom versions of these templates must be updated. If the new options are not used, existing templates are compatible with this server version. Even so, it is recommended to update the templates.

HAAPI capability and use of legacy DPOP

The use-legacy-dpop configuration setting, located inside the haapi capability, was changed to be false by default (previously it was true by default). Any configuration containing a client that needs to use the old legacy DPOP behavior will need to be changed to explicitly set this property to true, if it is relying on the default value. This can be achieved by using the general instructions in the start of this guide. See Hypermedia Authentication API for more information about the use-legacy-dpop configuration setting.

Microsoft SQL Server JDBC driver

This release upgrades the SQL Server JDBC driver shipped with Curity from version 6.4 to version 11.2. In between those versions, the certificate validation behavior when encryption is used was changed. If TLS encryption is used, the connection string in Curity may need to be updated so that the server certificate is trusted. This will depend on the type of certificates being used and how trust anchors are configured on the servers running Curity. For more details refer to the vendor’s documentation.

Changes to HAAPI responses

Representation improvements

Multiple small changes were done to the representations returned by Curity, aiming for consistency and better usability. These include:

  • Correction of messages and action titles.
  • Replacing actions with links and vice versa, when they better represent the available options.
  • Removing message classes (namely info) when an admonition is not intended. Note that messages may have an empty classList.

The aforementioned improvements did not require any changes to the HAAPI response schema.

New client operations for WebAuthn

Two new client-operation actions have been added for the WebAuthn authenticator - webauthn-registration and webauthn-authentication. Any clients using the WebAuthn authenticator with HAAPI should be updated before upgrading Curity. Both new client-operation contain a fallback mechanism to use an external browser flow in the form of error actions.

Password-based PBES2 JWE algorithms

In previous versions of Curity, it was possible to configure PBES2 algorithms for Request Object JWT encryption and for ID token encryption in the OpenID Connect authenticator, even though usage of those algorithms wasn’t actually supported in runtime. This release removes the options to configure those algorithms.

Windows Connector Failover Update

Recent versions of IIS handles configuration slightly different which breaks the Windows Connector failover capability. This version updates the aspx-file used to redirect to the failover authenticator. Older versions of the Windows Connector will work with 8.0, but upgrading will make the connector incompatible with versions prior to 8.0. To apply the upgrade, replace the 401.2.aspx file in IIS with the file bundled with the release. No configuration update needed.