Upgrade instructions 6.x


Added backward compatibility for PERSON_NAME_MANDATORY feature

Added backward compatibility for PERSON_NAME_MANDATORY feature, which was divided into two separate features in version 6.19.0: PERSON_FIRST_NAME_MANDATORY and PERSON_LAST_NAME_MANDATORY. Now PERSON_NAME_MANDATORY will return true if at least one of PERSON_FIRST_NAME_MANDATORY or PERSON_LAST_NAME_MANDATORY feature is turned on.


First name and last name attributes requirement

Changes were introduces to separate attributes configuration for the first and the last name during person creation. Now it is possible to check separately if person first name and/or last name is mandatory in the Admin Panel. Templates adjustments are needed if PERSON_NAME_MANDATORY feature was used. Now there are two separate features: PERSON_FIRST_NAME_MANDATORY and PERSON_LAST_NAME_MANDATORY.

For instance if sign-up form template checks whether to show name section. Instead of using: <th:block th:if="${@applicationPropertyService.isFeatureEnabled(T(com.onegini.web.access.Features).PERSON_FIRST_NAME_MANDATORY)>...</th:block>

it is advised to use for instance:

        || @applicationPropertyService.isFeatureEnabled(T(com.onegini.web.access.Features).PERSON_LAST_NAME_MANDATORY)}">

or even:

<th:block th:if="${@applicationPropertyService.isFeatureEnabled(T(com.onegini.web.access.Features).PERSON_FIRST_NAME_MANDATORY)">

<th:block th:if="${@applicationPropertyService.isFeatureEnabled(T().PERSON_LAST_NAME_MANDATORY)}">

for both fields separately.


CM API for sending SMS changes

CM stopped using username and password for sending sms in their API. Now you need to use your productToken which authorizes you on the CM platform. Get it on CM.com and set it in the IDP_SMS_CM_PRODUCTTOKEN environment variable. Also endpoint changed. Set IDP_SMS_CM_URL to new message api endpoint. Global endpoint is https://gw.cmtelecom.com/v1.0/message, more information in https://docs.cmtelecom.com/en/api/business-messaging-api/1.0/index.


Idin template

select_bank.html template has been moved from idin/select_bank.html to personal/idin/select_bank.html which means that extensions that have this template styled should update the path.


Sign-up form with custom attributes

Changes were introduced to make it possible to present and amend custom attributes on signup page. In order to utilise this feature some template amendements are needed. Please read more in topic guide Fields can be prefilled similarly as regular custom attributes (feature sign-up form with prefilled attributes)

Sign-up form with prefilled attributes

Changes were introduced to display mapped attributes on registration form to make it possible for customers to verify. But in order to manage fields accessibility it's necessary to update templates that are used on registration form.

Core templates are updated, but if the're overwritten by extension there should be additional parameter added to every field that represents single SAML person attribute.

in example for:

              <input type="radio" name="gender" id="gender-f" value="F" th:field="*{gender}"

th:readonly="${#maps.containsKey(fieldConfiguration, 'GENDER') && fieldConfiguration['GENDER'].isEditable() == false}" has been added so template should look like:

              <input type="radio" name="gender" id="gender-f" value="F" th:field="*{gender}"
                     th:readonly="${#maps.containsKey(fieldConfiguration, 'GENDER') && fieldConfiguration['GENDER'].isEditable() == false}"

fieldConfiguration is a map that contains information about field configuration (i.e. whether field should be editable or not). More information can be found here

Certificates format

Due to an issue the updating of the certificates via System -> Certificates tab in the Onegini IdP's admin console was not always working correctly. As a result, some of the keys may require to be uploaded again. If you observe any issues (mostly related to signing and encryption) in your current setup we recommend to reconfigure the credentials again.


Index on email addresses in profile_emails table

SQL migration in this version adds an index on value field in order to make search api working faster. Unfortunately it may take a long time to be processed on large database so it's recommended to run in on separate node one by one.

Redis configuration changes

Since this version the Onegini IdP doesn't require Redis Sentinel in order work instead, a single node can be used. This means that the application can be integrated with AWS ElastiCache running in clustered and non-clustered modes.

As of this version the Onegini IdP is still backwards compatible which means that below configuration changes are not immediately required. At the same time please note that this support will be dropped in the upcoming releases and we strongly recommend to migrate now.

Deprecated variables:


Newly introduced variables

  • SPRING_REDIS_HOST - Redis hostname ex. redis.onegini.com
  • SPRING_REDIS_PORT - Redis port ex. 6379

Currently, the Onegini IdP requires either IDP_REDIS_SENTINEL_NODES in combination with IDP_REDIS_SENTINEL_MASTER_ID or SPRING_REDIS_HOST along with SPRING_REDIS_PORT in order to boot and work.

NOTE Please note that the newly introduced properties are defined and handled by the Spring Data Redis autoConfiguration mechanism. It means that they are expected to be defined in the Onegini IdP and not the Onegini IdP Extension.


BSN / PseudoID singature validation in eIDAS

The broker (KPN) is providing the verification points during the service provider onboarding flow. These points are used for validating the signatures of the incoming identifiers. Starting from this version it is mandatory to provide the verification point for either BSN or PseudoID while configuring the eIDAS Identity Provider in the Onegini IdP.

Idin backward compatibility**

For customers that are already integrated with Idin via ui extension set IDIN_INTEGRATION_ENABLED env variable to false


Mutual SSL configuration in DigiD identity provider

Previously for DigiD Mutual SSL configuration, existing keystore and truststore properties were used. This configuration has been moved to Admin Panel. In case DigiD identity provider was configured, please set private key and certificate in System -> Certificates. Then use created configuration in Configuration/Identity Providers/Digid in SAML Mutual SSL/TLS configuration section.


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.