3.1.1 was published on 20.11.2019


can be read from:


Unity requires Java VM to be installed (JRE). Minimum supported version is 8. Unity is also tested on Java 11, which become supported since release 3.0 and becomes a default platform from release 3.2.


There are two distribution formats:

  • tar.gz bundle which can be unpacked and this way installed in a single directory,
  • rpm which can be installed system-wide in the Linux standard locations.

The rpm is build and tested on Centos 7, noarch. It should work flawlessly also on SL7 and recent Fedora distributions. We may build packages for other distributions in future, however the tar.gz format should be fully portable and is our primary distribution form.

We found couple of issues related to the initial versions of migration (especially the in place DB-based migration) from Unity 2 to 3. Those issues were fixed in version 3.1.1. This post provides more details if you are affected.



Unity 3.1.X provides is mostly a bugfix release on top of huge 3.0.0 release, however it provides also two new, important features.

Selective database dump/restore

So far Unity allowed to export an (almost) complete database contents to JSON and subsequently import it. This worked fine before 3.0 release, as after importing the data into running server, it was softly re-initialized. During the re-initialization, by default, Unity was setting up all file-configured settings: endpoints, authenticators, realms and more. In effect any of those settings imported from the JSON dump were overwritten immediately after import, leaving only directory schema and members. This situation was typically a good one, as endpoints & friends were anyway managed in configuration files, which could be copied separately when needed.

With changes introduced in Unity 3, this mechanism stopped to be practical: Unity by default is not overwriting DB-stored configuration from config files anymore, because of complete system control in Admin Console.

In Unity 3.1.0 this problem was addressed by introducing new capabilities in JSON dump export. It is possible to export only a directory alone, or directory together with basic system settings (including services, authenticators, …). What’s more it is possible to transfer only system basic setup without directory, or even only directory schema (groups tree, attribute types, classes) without members.


Multi-group bulk query

A new operation was added to the Admin REST API. It allows for retrieving – with a single query – members with attributes from multiple groups. Groups can be enumerated, or all groups under a given parent can be fetched.

Querying multiple groups was possible before by requesting all groups of interest one by one with separate queries. While the old approach was working, the new one is superior in case of speed. In our tests, using MySQL backend installed locally, and setup with 5000 queried groups, 50.000 memberships in those groups and 150.000 dynamic attributes in total the time difference between serial queries on Unity 3.0 and a single call to new API in 3.1 was around 1000 times in favor of the new API. On smaller data sets this will be for sure smaller, but for large deployments this API endpoint can become a critical element.


New features:
  • UY-950 Embed included translation profile in admin console
Bugs fixed:
  • UY-947 NPE on IdPs view after DB migration from 2.8
  • UY-948 Dump creation hangs in 3.1.0
  • UY-949 During upgrade to 3.0.0 or 3.1.0 custom translation profile of OAuth authenticator is lost
New features:
  • UY-916 Selective DB dump creation and loading
  • UY-929 Bulk query over REST API of multiple groups
Bugs fixed:
  • UY-922 memory control of SCrypt hashing
  • UY-923 Support Linkedin oauth v2 API with multiple user profile endpoints
  • UY-936 Update default OAuth integrations
  • UY-938 Only direct attributes used in few internal APIs
  • UY-939 OAuth AS should return error when openid scope requested and oidc not enabled
  • UY-940 HTTPS server hangs after some time
  • UY-941 No way to add initial group attribute statement in console
  • UY-943 Can not save in Console Admin/Upman service with configured authentication screen logo
  • UY-945 Missing checkboxes in entities list in directory browser
  • UY-946 Subsequent multi-entity removal broken


Here you can download previous versions from the series and read their documentation:

nothing so far on 3.1.x branch