Upgrade instructions 6.x


Basic Authentication for REST APIs changes:

  • The user defined by environment variable IDP_API_REST_USERNAME with password defined by IDP_API_REST_PASSWORD is now mandatory. This user by default will have all APIs roles assigned
  • Other API users and their password are no longer mandatory i.e. users defined by following environment variables:


    are now optional

  • If you decide to define any of the optional users it is required that all API usernames are unique

Introduced Sign in with Apple

Since Sign in with Apple have some prerequisites:

  • it needs to be initiated by clicking a specific icon that is provided by Apple
  • the first phase of the flow is triggered by a javascript code (also provided by Apple)

we have added a new ModelMap property appleLoginEnabled to the login_form Thymeleaf fragment that is part of the wayf_box.

The appleLoginEnabled is a boolean value that indicates whether Sign in with Apple is configured and available within the Onegini IDP.

If you are interested in adding support for this Identity Provider type you can consider using this property to either show or hide controls based on the current state of the application.


Default connection pool size

Default connection pool size have been decreased from 60 to 30. This should be enough to handle most of the cases. If there is a really high traffic expected, this can be configured by IDP_DATABASE_MAX_POOL_SIZE.


IDP_DATABASE_TRANSACTION_ISOLATION values need to be updated according to table below:

Previous value New value


We strongly recommended to not set the IDP_DATABASE_VALIDATION_QUERY property when the database driver supports JDBC4. It is meant for "legacy" drivers only that do not support the JDBC4 Connection.isValid() API.


In case migration with version is present in the schema_version table and is not it is necessary to set IDP_DATABASE_MIGRATIONS_OUTOFORDER to true on extension before next CIM core startup. After migration with version is applied successfully IDP_DATABASE_MIGRATIONS_OUTOFORDER is no longer required to be set.


Deprecation of tokens validate endpoint in credentials api

Tokens validate endpoint has been deprecated and will be removed in next major version. Since this version please use tokens process endpoint.

Changed a way in which showIdps variable is calculated

Since this version showIdps modelmap variable which is available in templates personal/fragments/login/login_form.html and personal/fragments/login/wayf_box.html has value true only if identity providers except Username and password, LDAP and iDIN are defined. Before this change it's value was always true.


Saml email attribute name modification

We have changed urn in the email saml attribute to valid one (urn:oid:1.2.840.113549.1.9.1). The old value (1.2.840.113549.1.9.1) is now deprecated and will be deleted in another major release. Until then if attribute is not mapped, we will return both uid values.

Error response unification

In order to unify ErrorResponses across all products, we have fixed existing ErrorResponse to contain error details in List instead of Map. New version is placed in SDK: com.onegini.sdk.model.error.ErrorResponse. So previous result:

  "error_code" : "3012",
  "error_message" : "One or more actions have failed",
  "details" : {
    "failed_actions" : ["LOGIN"]


will now look like:

  "error_code" : "3012",
  "error_message" : "One or more actions have failed",
  "details" : [{
      "failed_actions" : ["LOGIN"]

Error responses associated with Account Link contained error code as integer. Now it's unified and strings are applied everywhere.

Action Token API Endpoint.

Current year solving

We introduced new code [current.year] that can be used inside message.properties. This one is resolved automatically and represents current year. It needs to be updated in all extensions separately (especially in the copyright messages).


Password encoding compatibility fallback

The IDP_PASSWORD_ENCODING_COMPATIBILITY_FALLBACK_ENABLED property has been added. IdP changed encoding of data sent via html forms so the reason for enabling it is to rewrite hash of password for existing users who has non-ascii characters in their password.

If property is undefined it is set to true for existing CIM installations and false for new installations.


The following configuration properties have been removed :


Since this version the Onegini IDP generates and manages keys which are used for signing and encryption in OpenID Connect related flows. Please refer to managing JWKs chapter for more details.


Right to be forgotten

To maintain compatibility with GDPR (right to be forgotten) please run personal data cleanup. It needs to be executed once and is available in admin panel Configuration -> Data clean up -> Clean-up personal data in action log.

This operation is available after completing snapshots synchronisation operation.

Automatic email verification

Automatic email verification has been turned off in all automatic sign up flows. If an email saml attribute is mapped and email verification during sign up with external idp is not required, select "Verified by default" checkbox in external IdP configuration.


Action token changes

Action token configuration is moved from Identity Providers tab to Features tab. Each action token action now has its own expiration time, and thus there is no global option to set expiration time on token itself. Such change required action token api changes - there is no possibility to set the token expiration time using API calls. All expiration times are now configured on the admin panel, next to each token action configuration.

LinkedIn API update

LinkedIn API has been updated to version 2 which means that applications created before January 14, 2019 may not work. Because of that please update LinkedIn application configuration if needed.

Quote from LinkedIn page:

All developer applications created on the LinkedIn Developer Portal after January 14, 2019 have access to the LinkedIn v2 API by default. 
Alternatively, if your developer application has made a successful LinkedIn v1 API request from September 1, 2018 to December 17, 2018, your developer 
application has immediate access to the v2 API.

Google Authentication API update

Database driver migration

  • MySQL database driver is not supported anymore. MariaDB driver should be used instead and proper variable should be set to:
    • IDP_DATABASE_DRIVER=org.mariadb.jdbc.Driver


Property changes

  • Key store file location have been made configurable with IDP_KEYSTORE_FILE environment variable (it defaults to the previous path: /opt/data/keystore/keystore.jks)
  • IDP_HTTPS_TRUST_STORE property have been renamed to IDP_HTTPS_TRUST_STORE_FILE

Automated external identity coupling

  • Automated external identity coupling enabled flag is always disabled after upgrade. In case this features were turned on and you would like to keep old behavior please enable it in Admin panel in Configuration -> Feature management -> Processes section.

Mobile authentication callback url changes:

  • Step-up and mobile login callback url were merged into one and moved to the Token Server system tab in admin panel. (it is removed from Step-up configuration and Identity providers).


  • Search API is now deprecated and additionally available from /api/v1/persons/search-profile, the new api version is /api/v2/persons/search

Bug fixes

  • Added missing prefix to partitioning feature property descriptor


Mobile Authentication configuration changes:

The Onegini Token Server related configuration properties has been moved to a new section in the Onegini IDP admin console.

Copy the values from following variables

  • IDP_MOBILE_AUTH_API_URL to the corresponding fields in the form under the System -> Token Server tab.

Copy the values from the following variables:

  • IDP_MOBILE_LOGIN_ALLOWED_ATTEMPTS to the corresponding fields in Mobile login form under the Configuration -> Identity Providers tab.

Added configurable mobile login callback property has been moved to appropriate section in admin console.

Copy the values from following variables:

  • IDP_MOBILE_AUTH_CALLBACK-URL to corresponding fields in Mobile login form under Smart security -> Step-up authentication configuration tab.

The following configuration property has been removed:


Removed LDAP configuration for Mobile Login, now only person identifier is used when communicating with Token Server. Please update configuration for those users who are coupled with token server via configured LDAP attribute.

Axon Snapshot synchronization

This procedure must be performed. It is necessary only for existing installations. No work for new installations is needed.

The procedure may take from couple of minutes to several hours depending on the size of the DomainEventEntry table. These are the required steps:

  1. Consider creating a backup or snapshot of the database before attempting this procedure
  2. Deploy newest idp-core.
  3. Run snapshot synchronization:
    • Open admin panel,
    • "Configuration" tab,
    • "Event clean up" tab,
    • Press the "Run snapshot synchronization" button.
  4. Wait for synchronization job to finish. Refresh the page until you see information that snapshot synchronization has been completed. You can track the progress on the same page. There will be information how many events were processed and the speed of processing expressed in events per second.
  5. Stop idp-core.
  6. Run synchronization verification query manually on DB. The query verifies that there are no events left without corresponding snapshot. Queries are listed below. Only proceed if the query returns no results.
  7. If synchronization verification query returned 0 rows then delete all records from the DomainEventEntry table manually.
  8. Start idp-core again.
  9. Enable regular clean-up via cron job is enabled (The same tab in admin panel as for the snapshot synchronization).

If synchronization verification query returned any row this is an indication that the synchronisation process may have failed in some part. In such case please:

  • Do not proceed with the procedure.
  • Start idp-core again and continue using the application normally.
  • Make sure the regular clean-up feature in "Event clean up" tab in Admin Panel is disabled.
  • Contact Onegini Support.

Verification queries:

SELECT dee.aggregateIdentifier,
       max(dee.sequenceNumber) AS dee_sequenceNumber,
       max(see.sequenceNumber) AS see_sequenceNumber
FROM DomainEventEntry dee
LEFT JOIN SnapshotEventEntry see ON dee.aggregateIdentifier=see.aggregateIdentifier
AND dee.type=see.type
AND dee.sequenceNumber=see.sequenceNumber
GROUP BY dee.aggregateIdentifier,
HAVING dee_sequenceNumber>see_sequenceNumber
OR see_sequenceNumber IS NULL
LIMIT 100;
FROM (SELECT dee.aggregateIdentifier,
           max(dee.sequenceNumber) AS dee_sequenceNumber,
           max(see.sequenceNumber) AS see_sequenceNumber
    FROM DomainEventEntry dee
    LEFT JOIN SnapshotEventEntry see ON dee.aggregateIdentifier=see.aggregateIdentifier
    AND dee.type=see.type
    AND dee.sequenceNumber=see.sequenceNumber
    GROUP BY dee.aggregateIdentifier,
    HAVING max(dee.sequenceNumber) > max(see.sequenceNumber)
    OR max(see.sequenceNumber) IS NULL) o
WHERE rownum < 100;
MSSQL (SQL Server)
SELECT dee.aggregateIdentifier,
       max(dee.sequenceNumber) AS dee_sequenceNumber,
       max(see.sequenceNumber) AS see_sequenceNumber
FROM DomainEventEntry dee
LEFT JOIN SnapshotEventEntry see ON dee.aggregateIdentifier=see.aggregateIdentifier
AND dee.type=see.type
AND dee.sequenceNumber=see.sequenceNumber
GROUP BY dee.aggregateIdentifier,
HAVING max(dee.sequenceNumber)>max(see.sequenceNumber)
OR max(see.sequenceNumber) IS NULL

Mobile login and mobile step-up authentication behaviour change

From this version of the Onegini IDP the Mobile Login and mobile step-up authentication functionality will no longer work if you are not using the Person ID as the user identifier in the Onegini Token Server.