Upgrade instructions 2.x

2.39

Statistics API

New properties has been added to configure Onegini IDP Statistics API. Please define the following properties:

 - IDP_STATISTICS_API_REST_USERNAME=statistics_api_rest_user
 - IDP_STATISTICS_API_REST_PASSWORD=Y;QEZ^{9H!SSQ.08

Properties encryption

Environment variable that provides encryption key for properties decryption has been renamed form ONEGINI_PASSWORD to PROPERTIES_ENCRYPTION_KEY. Please define the environment variable accordingly in case properties encryption is used.

In case the application is set up along with Onegini IDP extension the environment variable PROPERTIES_ENCRYPTION_KEY should be defined on both core and extension machines.

2.38

Statistics generation

Statistics are generated according to cron definition provided in new property. The following environment property must be defined.

    - IDP_STATISTICS_GENERATION_CRON_DEFINITION=0 */5 * * * ?

2.37

Access to personal site, API and admin panel via separate IP ports

The following environment properties must be defined.

Admin panel URL
    - IDP_ADMIN_URL=http://dev.onegini.me:8992/admin
    - IDP_HTTP_ENABLED=false

    - IDP_HTTP_PERSONAL_PROXY_ENABLED=false
    - IDP_HTTP_PERSONAL_PROXY_PORT=80
    - IDP_HTTP_PERSONAL_PROXY_NAME=dev.onegini.me
    - IDP_HTTP_PERSONAL_PROXY_SCHEME=http
    - IDP_HTTP_PERSONAL_PROXY_SECURE=false

    - IDP_HTTP_API_ENABLED=true
    - IDP_HTTP_API_PROXY_ENABLED=false
    - IDP_HTTP_API_PROXY_PORT=80
    - IDP_HTTP_API_PROXY_NAME=dev.onegini.me
    - IDP_HTTP_API_PROXY_SCHEME=http
    - IDP_HTTP_API_PROXY_SECURE=false

    - IDP_HTTP_ADMIN_ENABLED=true
    - IDP_HTTP_ADMIN_PROXY_ENABLED=false
    - IDP_HTTP_ADMIN_PROXY_PORT=80
    - IDP_HTTP_ADMIN_PROXY_NAME=dev.onegini.me
    - IDP_HTTP_ADMIN_PROXY_SCHEME=http
    - IDP_HTTP_ADMIN_PROXY_SECURE=false

    - IDP_HTTPS_ENABLED=true

    - IDP_HTTPS_SSL-PROTOCOL=TLS
    - IDP_HTTPS_SSL-ENABLED-PROTOCOLS=TLSv1,TLSv1.1,TLSv1.2

    - IDP_HTTPS_PERSONAL_PROXY_ENABLED=false
    - IDP_HTTPS_PERSONAL_PROXY_PORT=8443
    - IDP_HTTPS_PERSONAL_PROXY_NAME=dev.onegini.me

    - IDP_HTTPS_API_ENABLED=true
    - IDP_HTTPS_API_PROXY_ENABLED=false
    - IDP_HTTPS_API_PROXY_PORT=8443
    - IDP_HTTPS_API_PROXY_NAME=dev.onegini.me

    - IDP_HTTPS_ADMIN_ENABLED=true
    - IDP_HTTPS_ADMIN_PROXY_ENABLED=false
    - IDP_HTTPS_ADMIN_PROXY_PORT=8443
    - IDP_HTTPS_ADMIN_PROXY_NAME=dev.onegini.me
Check mobile authentication callback endpoint

Property IDP_MOBILE_AUTH_CALLBACK_URL defines mobile authentication callback endpoint. The path for this endpoint starts with /api... which means that this should use API allowed port. Please verify that the port defined in this variable is a proper one.

The way of serving the application via configurable Tomcat connectors

Unless IDP_HTTP(S)_API_ENABLED or IDP_HTTP(S)_ADMIN_ENABLED properties are set to true, the application is served on single port.

Serving application through HTTP for separate access to API and admin panel

The property IDP_HTTP_API_ENABLED controls serving the application on additional port 8081 that accepts API request. The property IDP_HTTP_ADMIN_ENABLED controls serving the application on additional port 8082 that allows admin panel access.

Serving application through HTTPS for separate access to API and admin panel

The property IDP_HTTPS_API_ENABLED controls serving the application on additional port 8444 that accepts API request. The property IDP_HTTPS_ADMIN_ENABLED controls serving the application on additional port 8445 that allows admin panel access.

Removed access restriction to admin panel based on IP number

The restriction to admin panel based on IP number has been removed from the application. The java system property adminAllowedIpPattern is no longer in use.

The following properties are no longer in use and should be unset:

    - IDP_HTTP_PROXY_ENABLED=
    - IDP_HTTP_PROXY_PORT=
    - IDP_HTTP_PROXY_NAME=
    - IDP_HTTP_PROXY_SCHEME=
    - IDP_HTTP_PROXY_SECURE=

    - IDP_HTTPS_PROXY_ENABLED=
    - IDP_HTTPS_PROXY_PORT=
    - IDP_HTTPS_PROXY_NAME=

Adjusting session timeout with docker configuration

The following environment properties must be defined.

    IDP_SESSION_TIMEOUT_SECONDS=600

2.36

Custom messages localization

Custom messages has been extended by possibility to add localized messages (admin -> configuration -> custom messages).

Information Already created messages will be given nl locale. In case the nl locale selection for existing messages is not valid, it is required to rework the messages. Otherwise no action is required.

2.35

Optional notifications

User notifications that informs user about attributes change (password, email and phone number) can be disabled. By default, all notifications are sent but it can be changed via admin panel (Admin -> Configuration -> Attributes).

Strict Transport Security Header

New property has been added to configure Strict Transport Security Header. Please define the following property:

     - IDP_HEADER_INTERCEPTOR_STRICTTRANSPORTSECURITY=max-age=31536000; includeSubDomains

2.33

Rename property credentials.api.rest.encryption.key to authentication.password.encryption.key. The property is now used for password encryption in Credentials API and SAML Inline Login.

2.32

Externally delivered code

Externally delivered code step-up method has been extended by view with information that code will be send soon. This require the following properties:

    - IDP_EXTERNALLYDELIVEREDCODE_INITIAL_UNAVAILABILITY_TIME_MILLIS=30000

Custom messages

Messages can be personalized via admin panel. Before the upgrade please follow these steps:

  1. Copy the content of the HTML head custom message to a file
  2. Clear the content of the HTML head custom message in the admin console and save it
  3. Upgrade the IDP
  4. Set the content for message personal.html.head

Fixed migration for Oracle database

This instruction only applies when upgrading Onegini IDP from version 2.30 or 2.31 to newer version.

In Onegini IDP 2.32 one of the previous migrations has been modified. In particular, migration number 2.30.00.00 named change authentication tokens column type has been fixed to remove contents of the table before altering a column type. This effects in changed checksum which needs to be updated manually in schema_version table.

Please execute the following query before starting an upgraded application:

UPDATE "schema_version" SET "checksum"='-1324603942' WHERE "version"='2.30.00.00';

2.31

Externally delivered code

In Onegini IDP 2.31 externally delivered code step-up method has been added. This require the following properties:

    - IDP_EXTERNALLYDELIVEREDCODE_VALIDITYTIME_MILLIS=12960000000

The configuration for the link on the logo has been separated from the link on the "Go to home" buttons in the dashboard, e-mail verification and error pages. The default value is the dashboard. If necessary, set the value of the link on the logo via the admin console:

Configuration -> Template links -> IdP logo link

2.30

Onegini IDP 2.30 extends cookie based SAML authentication. More info about it can be found here.

New properties have been added to configure cookie based SAML authentication. Please define the following properties:

    - IDP_AUTH_TOKEN_CRON_DEFINITION=0 0 2 * * ?
    - IDP_QUARTZ_JDBC_DELEGATE=org.quartz.impl.jdbcjobstore.StdJDBCDelegate

2.28

Onegini IDP 2.28 introduced cookie based SAML authentication. More info about it can be found here.

New properties has been added to configure cookie based SAML authentication. Please define the following property:

    - IDP_AUTH_TOKEN_EXPIRATION_TIME_PERIOD_SECONDS=2592000

2.26

Events API

New properties has been added to configure Onegini IDP Events API. Please define the following properties:

<entry key="events.api.rest.username">events_api_rest_user</entry>
<entry key="events.api.rest.password"><![CDATA[Y;QEZ^{9H!SSQ.08]]></entry>

2.25

Post login actions (enrich attributes after second login)

Onegini IDP 2.25.00 introduced new view shown after second login. Thanks to that view user don't need to fill in all the information during the registration and can fill it in after second login (alternative email and mobile phone number). New read model table has been introduced therefore Axon events replay in PersonStatusAction Cluster is required. Axon events replay can be performed in Admin Panel. Be noticed that improper use of Axon events replay can break the application.

2.23

Search by phone number

Onegini IDP 2.23.00 introduced search by phone number in Person API. New read model table has been introduced therefore Axon events replay in PhoneNumber Cluster is required. Axon events replay can be performed in Admin Panel. Be noticed that improper use of Axon events replay can break the application.

2.21

New properties has been added to configure remote email service credentials. Please define the following properties:

    <entry key="email.remote.service.user">user</entry>
    <entry key="email.remote.service.user.password">password</entry>

2.20

Credentials API

New properties has been added to configure Onegini IDP Credentials API. Please define the following properties:

    <entry key="ns.accountservice.protocol">https</entry>
    <entry key="ns.accountservice.host">host.example.org</entry>
    <entry key="ns.accountservice.user">testUser</entry>
    <entry key="ns.accountservice.password">testPassword</entry>

2.19

Credentials API

New properties has been added to configure Onegini IDP Credentials API. Please define the following properties:

    <entry key="credentials.api.rest.username">credentials_api_rest_user</entry>
    <entry key="credentials.api.rest.password"><![CDATA[Y;QEZ^{9H!SSQ.08]]></entry>
    <entry key="credentials.api.rest.encryption.key"><![CDATA[cf0138d58946c6849a5d972c50830f76]]></entry>

2.16

Credentials API

New properties has been added to configure Onegini IDP Credentials API. Please define the following properties:

    <entry key="email.remote.service.uri">http://customer-website.com/email</entry>

2.14

Mail templates

Onegini IDP is now more flexible in how emails are sent from the application. This has affected the existing mail handling in Onegini IDP as well.

Configuration

A new property is introduced to configure the Spring Bean for the EmailGateway interface. The value for the default implementation is smtpEmailGateway.

  <entry key="email.provider">smtpEmailGateway</entry>
Plain text templates

The plain text part of the email body used to be generated in Java code. Since 2.14 Onegini IDP uses Mustache to render the plain text part.

All Mustache email templates are located in: onegini-mail-templates/src/main/resources/com/onegini/templates/email. The name of the mustache templates is similar to the HTML version, e.g. the plain text template of welcome.html is welcome.mustache.

If your project does not include the onegini-mail-templates jar and uses the default smtpEmailGateway implementation, you must copy the Mustache templates to your project.

HTML templates

A few HTML templates have changed. If custom HTML templates are used, apply the following changes:

  • Template invitation.html

Replace ${emailValidityText} with #{personal.invitation.emailValidity(${formattedTime})}

  • Template notification.html

Replace ${changedFields} with ${htmlChangedFields}

  • Template verify-email.html

Replace ${emailValidityText} with #{personal.verification.emailValidity(${formattedTime})}

  • Template support-notification.html

Replace ${mailSubject} with ${subject}

Replace

         <p style="font-family:Arial,Helvetica,sans-serif; font-size:14px; color:#444; margin: 2em 0;
                  line-height:20px;" th:style="${pStyle}" th:utext="${mailBody}">
          For security reasons an administrator account has been blocked. The account
          can be enabled via the admin console. Please refer to the event log to see more details regarding the event.
          <br/><br/>Blocked user: admin
         </p>

with

         <p style="font-family:Arial,Helvetica,sans-serif; font-size:14px; color:#444; margin: 2em 0;
                  line-height:20px;" th:style="${pStyle}">
          <span th:remove="tag" th:text="#{admin.support.email.accountProvisioning.configurationError.intro(${organisation}, ${errorCode})}">intro</span>
          <br />

          <span th:if="${errorMessage}" th:remove="tag"
                th:text="#{admin.support.email.accountProvisioning.configurationError.errorMessage(${organisation}, ${errorMessage})}">error message</span>
          <br th:if="${errorMessage}" />

          <span th:remove="tag" th:text="#{admin.support.email.accountProvisioning.configurationError.customerEmail(${customerEmail})}">customerEmail</span>
          <br />
          <span th:remove="tag" th:text="#{admin.support.environment(${oneginiEnv})}">oneginiEnv</span>
        </p>