Upgrading from 6.3.X to 6.4.0¶

There are no changes to the database schema, SDK, or the configuration model in this version. As a result, it should be possible to upgrade without explicit action. Some changes were made that can be important to know about when upgrading, however. These are described below.

Default Java Options Changed¶

The default options passed to the Java Virtual Machine (JVM) that the Curity Identity Server runs in were changed. The flag -XX:+UseStringDeduplication was added to deduplicate redundant strings. This should take affect on first start if the default G1 garbage collector hasn’t been changed. Refer to JVM Configuration for more details on how to control the JVM options.

Java Upgraded to Version 11¶

The JVM that the Curity Identity Server runs in was upgraded from version 8 to version 11. In some specific cases, custom plugins may need to be updated to account for changes in behavior.

Nashorn¶

The Nashorn script engine used for procedures has changed compilation strategy. The new optimistic typing strategy may increase the time to stable state both in number of classes loaded as well as in time to stability. In return the stable state should result in faster execution. In most cases this should not affect deployments, but if a large number of request hit newly deployed nodes and the response times suffer initially, then it is possible to disable the optimistic typing by providing the following JAVA_OPTS when starting the server.

export JAVA_OPTS="-Dnashorn.args=-ot=false"

JAX-WS, JAXB and JAF¶

In Java 11, multiple modules containing Java EE and CORBA technologies were removed, namely the ones related to JAX-WS, JAXB and JAF. The Curity Identity Server now bundles reference implementations of JAX-WS and JAXB, ensuring that any types in the following packages (and their subpackages) are available in plugins’ classpaths without any change:

javax.activation
javax.jws
javax.xml.bind
javax.xml.soap
javax.xml.ws

JAX-WS allows developers to control request capabilities by setting well-known properties in the request context via the javax.xml.ws.BindingProvider class. The names of those properties are different when using the JAX-WS reference implementation, so plugins that use them need to be updated. The following table lists the old and new names of some commonly used properties.

Old property name	New property name
`com.sun.xml.internal.ws.transport.https.client.SSLSocketFactory`	`com.sun.xml.ws.transport.https.client.SSLSocketFactory`
`com.sun.xml.internal.ws.connect.timeout`	`com.sun.xml.ws.connect.timeout`
`com.sun.xml.internal.ws.request.timeout`	`com.sun.xml.ws.request.timeout`

Serialization¶

Changes between major versions of the Java compiler and/or runtime may change the structure of the compiled class files (e.g. JEP 181). If a class doesn’t explicitly declare a serialVersionUID and it is compiled again, this may result in a different serialVersionUID being calculated at runtime, which ultimately can cause deserialization of existing data to fail.

As also stated in the Java documentation, it is strongly recommended that serializable types defined by plugins explicitly declare serialVersionUID values to prevent possible deserialization failures if they are recompiled.

Garbage Collection Log¶

Garbage Collection logging is now based in the JVM unified logging framework (Xlog). If the GC_LOG_OPTS environment variable is used when starting the Curity Identity Server, its value must be updated to use Xlog configuration options. Refer to the java command documentation for more information.

Procedure maps may return `undefined` instead of `null`¶

The Java upgrade changed the behaviour of how non-existing keys from a map are returned due to a bug fix. Versions prior to 6.4 would return a null object when a map was queried with a non-existing key; however, 6.4 and forward will return an undefined object. This means that checks like this will give a different behavior from before.

Listing 99 Strict checking for null¶

 if(attributes.role === null) {
     // Missing role attribute, add default value
 }

Before 6.4, the if-statement would be true if there is no role in attributes, but in 6.4 it will be false since attributes.role will instead return undefined.

Since undefined is falsy, expressions like this will still behave the same.

Listing 100 Check if not set¶

 if(!attributes.role) {
     // Missing role attribute, add default value
 }

SDK¶

The Curity Identity Server exposes certain third-party Java packages to plug-ins via the class path. One of these is Hibernate Validators. Due to security issues, this was upgraded from 5.4.3 to 6.2.0-CR1. This should not affect plug-ins, except perhaps the changed group ID of the module or if plug-in developers have bundled the old version with the deployment of their plugin. In the later case, version 5.X of the Hibernate Validator JAR file should be removed when upgrading. It used to be org.hibernate and was changed to org.hibernate.validator. For more details, refer to the Hibernate Validators migration guide. Upgrading to this new version of Hibernate Validators also required the Java Bean Validation API to be changed from version 1.1 to 2.0. Refer to the Bean Validator website for information about what is new in this new version.

Changes to the HAAPI Web SDK¶

The fetch-like function returned by createHaapiFetch requires asynchronous initialization, which is implicitly managed by the SDK. Nevertheless, the fetch-like function now includes an init method that can be used for explicit initialization, allowing consumers to know that the function is ready to use. The following examples illustrate both cases, also relying on newly added error types.

Listing 101 Implicit initialization¶

const haapiFetch = createHaapiFetch(...);
...
try {
    const res = await haapiFetch(...);
} catch (e) {
    if (e instanceof InitializationError) {
        // initialization error
        // can also use e.name === 'InitializationError'
    }
}

Listing 102 Explicit initialization¶

try {
    const haapiFetch = await createHaapiFetch(...).init();
} catch (e) {
    // initialization error
}

The fetch-like function is meant to be created once and used throughout the page/application. To that end, createHaapiFetch now ensures that there’s at most one active fetch-like function. A previously created fetch-like function becomes unusable after a new one is created.

For details, refer to the HAAPI Web SDK documentation and changelog.

DPoP Proof Token Clock Skew¶

A new configuration setting was added to define the allowed clock skew when validating DPoP tokens.

The se.curity.dpop.maxskew system property is no longer considered. Usages of this property should be replaced by the new configuration option.

DN Certificate Validation¶

DN certificate validation has been updated to follow RFC 2253 instead of the deprecated RFC 1779. This means that attribute values in a DN that have the same value but different string types will not be considered equivalent.