Upgrade instructions 3.x

3.27.2

Introduced MariaDB MySQL driver

In this version new MySQL driver has been made available. To use MariaDB MySQL driver:

Please redefine the following property:

IDP_DATABASE_DRIVER=org.mariadb.jdbc.Driver

Change JDBC URL prefix from jdbc:mysql: to jdbc:mariadb::

IDP_DATABASE_URL=jdbc:mariadb://database.dev.onegini.me:3306/onegini?autoReconnect=true

The previous MySQL driver com.mysql.jdbc.Driver is still available.

Changed defaultTransactionIsolation level for JDBC

The defaultTransactionIsolation property has been exposed and can be modified by IDP_DATABASE_TRANSACTION_ISOLATION environmental variable. By default the Onegini IDP sets it's value to -1 - UNDEFINED, so that the defaults for underlying database should be used.

3.27.0

Upgrade reCAPTCHA to V2

Since reCAPTCHA's V1 end of life is set to 31 March 2018 we decide to upgrade reCAPTCHA to V2. Because reCAPTCHA V2 has a different API the public key variable name needs to be changed from reCaptchaPublicKey to reCaptchaSiteKey. The following template needs to be updated in case it has beed customized:

  • personal/components/recaptcha.html
 <div th:if="${reCaptchaSiteKey}">
    <script th:inline="javascript">
      /*<![CDATA[*/
      var RecaptchaOptions = {
        theme: 'custom',
        custom_theme_widget: 'recaptchaWidget',
        lang: /*[[${#locale.language}]]*/ 'en'
      };
      /*]]>*/
    </script>
    <div id="recaptchaWidget" style="margin-left:17px">
      <div class="control-group captcha-challenge">
        <div class="controls">
          <script src="https://www.google.com/recaptcha/api.js"
                  th:src="'https://www.google.com/recaptcha/api.js?hl=' + ${#locale.language}">
          </script>
          <div class="g-recaptcha" th:attr="data-sitekey=${reCaptchaSiteKey}"></div>
          <noscript>
            <div>
              <div style="width: 302px; height: 422px; position: relative;">
                <div style="width: 302px; height: 422px; position: absolute;">
                  <iframe src="https://www.google.com/recaptcha/api/fallback?k=6Lc5aTgUAAAAAEMB86t8YDHXIXUaSmt6xJKB8d0Q"
                          th:src="'https://www.google.com/recaptcha/api/fallback?k=' + ${reCaptchaSiteKey}"
                          frameborder="0" scrolling="no"
                          style="width: 302px; height:422px; border-style: none;">
                  </iframe>
                </div>
              </div>
              <div style="width: 300px; height: 60px; border-style: none;
                   bottom: 12px; left: 25px; margin: 0px; padding: 0px; right: 25px;
                   background: #f9f9f9; border: 1px solid #c1c1c1; border-radius: 3px;">
                <textarea id="g-recaptcha-response" name="g-recaptcha-response"
                          class="g-recaptcha-response"
                          style="width: 250px; height: 40px; border: 1px solid #c1c1c1;
                                    margin: 10px 25px; padding: 0px; resize: none;" >
                </textarea>
              </div>
            </div>
          </noscript>
        </div>
      </div>
    </div>

In case javascript is disabled the Security Preference option needs to be set to Easiest for users during reCAPTCHA keys creation.

Attributes mappings for LDAP IdP has been moved from environmental variables to admin console

Since this version Onegini IDP will not read IDP_LDAP_ATTRIBUTE_EMAIL and IDP_LDAP_ATTRIBUTE_PHONE environmental variables to get the knowledge about attributes mappings for LDAP IdP type. Please edit configuration of your LDAP IdP in order to apply correct mappings.

3.26.0

Property APPLICATION_ENVIRONMENT replaced with SPRING_PROFILES_ACTIVE

Since this version please use SPRING_PROFILES_ACTIVE instead of APPLICATION_ENVIRONMENT or CLOUD_STACK properties to activate specific environment.

3.25.0

IdentityProvider type was changed in wayf_box and dashboard_unused_idps

The /sessions/couple/{IDP_TYPE} and `/sessions/new/{IDP_TYPE} endpoints are now consuimg additonal optional path parameter - IdentityProvider identifier. Please see below examples.

wayf_box

<div class="control-group">
  <div class="controls login-buttons">
    <div class="third-party-login">
      <ul class="inline">
        ...
        <li th:each="idp : ${idps}"
            th:if="${idp.type !=  T(com.onegini.web.WebConstant).IDP_TYPE_UNP}">
          <a href="sign-up.html" th:href="@{'/sessions/new/{idpType}/{idpId}'(idpType=${idp.type},idpId=${idp.id})}"
             th:id="${idp.type}" data-onegini-toggle="tooltip"
             th:title="${idp.name}" th:alt="${idp.name}"></a>
        </li>
      </ul>
    </div>
  </div>
</div>

dashboard_unused_idps.html

<div class="span4 social-list-action">
  <a
      class="add-identity"
      th:text="#{personal.general.add}"
      th:href="@{'/sessions/couple/{idpType}/{idpId}'(idpType=${unused.type},idpId=${unused.id})}">
    _Add
  </a>
</div>

Property IDP_LOGGING_LEVEL replaced with properties logging.level.<package-name>

Since this version please use logging.level.<package-name> properties to set logging level, eg.

logging.level.com.onegini=DEBUG
logging.level.org.springframework=INFO

Please keep in mind that environment variable should be in form logging.level.package-name as LOGGING_LEVEL_PACKAGE_NAME won't work.

Property CLOUD_STACK replaced with APPLICATION_ENVIRONMENT

Since this version please use APPLICATION_ENVIRONMENT instead of CLOUD_STACK property to activate specific environment.

3.23.0

Enabling end user to decide whether Mobile login should be enabled

Since this version user can decide whether he allows the Mobile login functionality to be enabled. It's done by sending additional optionalMobileLogin field within the login form to the Onegini IDP.

The following template needs to be updated in case it has been customized:

  • personal/fragments/login/wayf_box.html
<div class="controls login-buttons">
  ...
  <label th:for="optionalMobileLogin" class="checkbox" th:if="${optionalMobileLoginEnabled}">
    <input type="checkbox" th:id="optionalMobileLogin" th:field="*{optionalMobileLogin}" />
    <th:block th:text="#{personal.login.mobileLogin.optional}">_Allow mobile login for this device</th:block>
  </label>
  ...
</div>

Https properties renamed

Properties used to configure https have been renamed:

Old name New name
IDP_HTTPS_SSL-PROTOCOL IDP_HTTPS_SSL_PROTOCOL
IDP_HTTPS_SSL-ENABLED-PROTOCOLS IDP_HTTPS_SSL_ENABLED_PROTOCOLS

CSRF Token for Mobile login

The Mobile login intialization page /connect/auth/mobile_login requires CSRF Token. The token is available within the modelMap under csrfToken name in wayf_box.html template.

The following template needs to be updated in case it has been customized:

  • personal/fragments/login/wayf_box.html
<a href="sign-up.html" th:href="@{'/connect/auth/mobile_login'(csrfToken=${csrfToken})}"
   th:id="mobile_login" data-onegini-toggle="tooltip"
   title="Mobile login" alt="mobile login"></a>

Changes in idp-extension-config-common start-dockers development script

The script to start dockers for development is now a python script. Please refer to the help start-dockers.py -h for more details.

Most significant changes that affect extensions development:

  • maven resolve-local-specific-properties execution has been removed from SDK
  • the following files are no longer supported:
    config/idp-extension-specific-local-specific.env
    config/idp-extension-specific-local-specific.env.default
    config/idp-extension-specific-localdev.env
    
  • to start integration dockers for local development run:
    python start-dockers.py -e local -x false
    

3.19.0

LDAP identity provider password

LDAP identity provider password encryption has been modified. In case the application contains a configured LDAP identity provider the previous password has been removed. The administrator should configure LDAP identity provider password manually in Administration Panel. The configuration should be edited in the page Configuration -> Identity Providers.

Mobile login

The IDP_MOBILE_LOGIN_CALLBACK_URL property has been removed.

The Mobile login identity provider type has been removed, in order to enable users to use Mobile login functionality it needs to be explicitly enabled in the Onegini IDP Administration Panel. Please refer to (Mobile login documentation page) for more info.

Mobile step-up

The IDP_MOBILE_AUTH_CALLBACK_URL property has been removed.

3.17.0

Captcha configuration changes

ReCaptcha configuration has been moved from system environment properties to Administration Panel. After upgrading IDP to this version please move below properties to Administration Panel (Smart security -> ReCaptcha configuration).

IDP_RECAPTCHA_PUBLICKEY=
IDP_RECAPTCHA_PRIVATEKEY=

3.13.0

Properties encryption

Version 3.13 requires PROPERTIES_ENCRYPTION_KEY environment variable to be set. Please refer to properties description for more info.

Microsoft SQL Server support

To run IDP with Microsoft SQL Server below properties should be updated

IDP_DATABASE_MIGRATIONS_FOLDER=/db/migrations/mssql
IDP_DATABASE_DRIVER=com.microsoft.sqlserver.jdbc.SQLServerDriver
IDP_DATABASE_URL=jdbc:sqlserver://database.example.com:1433;DatabaseName=databaseName
IDP_DATABASE_USER=dbUserName
IDP_DATABASE_PASSWORD=dbUserPassword
IDP_DATABASE_VALIDATION_QUERY=select 1
IDP_DATABASE_PLATFORM=org.hibernate.dialect.SQLServer2008Dialect
IDP_DATABASE_TYPE=SQL_SERVER
IDP_QUARTZ_JDBC_DELEGATE=org.quartz.impl.jdbcjobstore.MSSQLDelegate
IDP_HIBERNATE_GLOBALLY_QUOTED_IDENTIFIERS=true

Web template changes

Attribute loginUnrestrictedFormat added to the template wayf_box

Since default Username and Password login form validates whether entered username has a valid email format, in order to allow logging in with LDAP the form must have the username input validation disabled. The IDP sets loginUnrestrictedFormat flag which is available in the frontend and can be used to enable / disable validation.

The loginUnrestrictedFormat property is set to true when any of following requirements is met:

  • migration feature is enabled in the admin console
  • at least one Identity Provider of type LDAP is configured and enabled

Example property usage:

  <div class="controls">
    <input th:unless="${loginUnrestrictedFormat}" type="email" name="email" id="email" autocomplete="off"
           tabindex="1" th:field="*{email}"
           th:attr="data-msg-required=#{personal.fields.email.error.emptyUsername},data-msg-email=#{personal.fields.email.error.malformed}"/>
    <input th:if="${loginUnrestrictedFormat}" type="text" name="email" id="email" autocomplete="off"
           tabindex="1" th:field="*{email}"
           th:attr="data-msg-required=#{personal.fields.email.error.emptyUsername.migration}"/>
    <th:block th:include="personal/components/field_error :: field_error" th:with="fieldName='email'"/>
  </div>

3.11.00

LDAP Identity Provider configuration change

LDAP configuration has been moved from system environment properties to admin panel. After upgrading IDP to this version please move below properties to admin panel:

IDP_LDAP_SERVER_URLS
IDP_LDAP_SERVER_BASE
IDP_LDAP_SERVER_USERDN
IDP_LDAP_SERVER_PASSWORD
IDP_LDAP_AUTHENTICATE_DN_TEMPLATE

Remote cache provider changed

From now IDP will require a Redis server, to work properly. Redis server should be operative before IDP is deployed. Cache replication with infinispan is no longer supported.

Additional properties have been introduced for Redis server configuration:

  IDP_REDIS_SENTINEL_NODES
  IDP_REDIS_SENTINEL_MASTER_ID
  IDP_REDIS_PASSWORD
  IDP_CACHE_ENCRYPTION_KEY

More details on these properties can be found on the Remote cache configuration page

3.07

Template changes

Listed templates has been changed (<input type="submit"/> has ben replaced with <button type="submit"/>):

  • templates/personal/components/submit_cancel.html
  • templates/personal/fragment_common.html
  • templates/personal/sign-up-unp.html

Please keep it in mind in case of template customization in idp extension.

Migration interfaces

API of interfaces in package com.onegini.extension.migrate used during migration changed thanks to which it is possible to migrate all user data defined in Profile class.

3.05

Person Search API

Changes that has been introduced for person search api requires to personAttributeCluster replay. It can be done via admin panel.

Upgrade Instructions 3.04.02

Additional properties have been introduced for SAML Artifact Resolution Service feature:

IDP_SAML_ENTITY_PROTOCOL=http
IDP_SAML_ARTIFACT_RESOLUTION_PROTOCOL=http

More details on these properties can be found on the properties page.

3.04

SAML Artifact Resolution Properties configuration

From this version SAML Artifact Resolution Service is served on API port. In case separate API port is enabled via IDP_HTTP_API_ENABLED property, the following properties must be configured:

IDP_SAML_ENTITY_HOST=172.16.10.10:8990
IDP_SAML_ARTIFACT_RESOLUTION_HOST=172.16.10.10:8991

More details on these properties can be found on the properties page.

3.03

Property names changes

Two docker properties has been changed:

Previous (wrong) name New (correct) name
IDP_DATABASE_VALIDATION-query IDP_DATABASE_VALIDATION_QUERY
IDP_HEADER_INTERCEPTOR_P3ppolicy IDP_HEADER_INTERCEPTOR_P3PPOLICY

SAML artifact binding

SAML artifact binding has been introduced in this version and because of that two things needs to be taken into account while sending AuthnRequest from Service Provider to Onegini IDP:

  1. Before artifact binding has been introduced, Onegini IDP did not validate ProtocolBinding so please keep in mind that ProtocolBinding attribute that is part of AuthnRequest needs to be consistent with Service Provider metadata:
    • for post binding (browser response) Service Provider needs to send ProtocolBinding equal to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
    • for artifact binding (SOAP response) Service Provider needs to send ProtocolBinding equal to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact
  2. The response sent back to Service Provider is resolved by looking at the AuthnRequest parameters:
    • if AuthnRequest contains AssertionConsumerServiceIndex then Onegini IDP will look at the Service Provider metadata and answer to the AssertionConsumerService with appropriate index
    • if AuthnRequest contains AssertionConsumerServiceURL and ProtocolBinding then Onegini IDP will look at the Service Provider metadata and answer to the AssertionConsumerService with appropriate AssertionConsumerServiceURL and ProtocolBinding

3.00

Email gateway configuration

Deprecated property

Extension Email Gateway has been introduced therefore property IDP_EMAIL_PROVIDER is deprecated. Please define property IDP_EXTENSION_EMAILGATEWAY_ENABLED in order to use Extension Email Gateway instead of default SMTP Email Gateway.

 - IDP_EXTENSION_EMAILGATEWAY_ENABLED=true
Deprecated remote email service credential properties

The following properties are deprecated. Please remove them and use extension specific properties to set credentials.

 - IDP_EMAIL_REMOTE_SERVICE_USER
 - IDP_EMAIL_REMOTE_SERVICE_PASSWORD
 - IDP_EMAIL_REMOTE_SERVICE_URI
Extension configuration properties

The following properties are required in case application is set up with the extension:

IDP_EXTENSION_PROTOCOL=http
IDP_EXTENSION_BASEURL=172.17.42.1:8182
IDP_EXTENSION_USERNAMEVALIDATION_ENABLED=false
IDP_EXTENSION_AUTHENTICATION_ENABLED=false
IDP_EXTENSION_PROFILEATTRIBUTESUPDATE_ENABLED=false
IDP_EXTENSION_ACCOUNTLINK_ENABLED=false
IDP_EXTENSION_DELIVEREXTERNALCODE_ENABLED=false
IDP_EXTENSION_EMAILGATEWAY_ENABLED=false
IDP_EXTENSION_USERINFO_ENABLED=false
IDP_EXTENSION_RESOURCES_ENABLED=false
IDP_EXTENSION_MIGRATION_DEFAULTPROCESSING_ENABLED=false
IDP_EXTENSION_MIGRATION_PASSWORDRESETMIGRATION_ENABLED=false