Skip to content

Enforcing brand specific messsages

This guide will walk you through the process of configuring the multi-brand functionality. The multi-brand support allows the Onegini IdP to serve brand-specific messages based on the configuration properties defined in the Onegini IdP's extension and also the requested brand. The functionality utilises locale variant code (language_country_variantCode, ex. nl_NL_Onegini) to send information about the requested brand name.

Prerequisites

To successfully complete this topic guide you need to ensure following prerequisites:

  • Onegini IdP instance must to be running, for the sake of this guide we assume it's available under http://idp-core.dev.onegini.me address
  • access to Onegini IdP's extension sources

Configuration

The extension project must support the PreSessionProcessExtension extension point, where user brand will be determined. Please note that the brand id that will be used as locale variant must be a valid variant code - this means must be 5 to 8 chars long when starting with a letter or exactly 4 when starting with a number and contain alphanumeric characters only.

Enforcing brand specific messages can only be applied at Onegini IdP's extension source level. You can configure it by adding specific message files in the extension project. Assuming you are using english as default language, your extension project contains extension-resources/messages/messages-personal-branding.properties file along with extension-resources/messages/messages-personal-branding_en.properties

You can now add branding files by extending the name of the file. All of those will be valid:

  • extension-resources/messages/messages-personal-branding_en_US_brandX.properties
  • extension-resources/messages/messages-personal-branding_en_US_brandY.properties
  • extension-resources/messages/messages-personal-branding_en__brandX.properties (notice the double _)
  • extension-resources/messages/messages-personal-branding_en__brandY.properties (notice the double _)

Assuming PreSessionProcessExtension returns brand brandX in response on user login, user interface will use the extension-resources/messages/messages-personal-branding_en__brandX.properties messages file.

There is a fallback mechanism in place, for situations where PreSessionProcessExtension returns invalid brand or does not return brand information at all. Assuming default locale is en_US, and the brand id is invalid, unsupported or empty, the fallback mechanics will search for messages in such order:

  • extension-resources/messages/messages-personal-branding_en_US.properties exists, this file will be used
  • if extension-resources/messages/messages-personal-branding_en_US.properties does not exist, extension-resources/messages/messages-personal-branding_en.properties will be used if file exists
  • otherwise extension-resources/messages/messages-personal-branding.properties will be used

You can also set the default brand along with locale by setting the IDP_DEFAULT_LOCALE property on startup to the value containing brand. All of the below are valid settings:

  • IDP_DEFAULT_LOCALE=en
  • IDP_DEFAULT_LOCALE=en_US
  • IDP_DEFAULT_LOCALE=en_US_brandX
  • IDP_DEFAULT_LOCALE=en__brandX

Testing

To check if the messages are working as expected:

  1. Make sure your Onegini IdP's extension project contains the extra messages files with correct naming (see configuration).
  2. Implement the PreSessionProcessExtension to always return the brandX.
  3. After running the extension project along with the IdP you should see that the messages are resolved from the brandX messages file.
  4. Now change the implementation of PreSessionProcessExtension to always return the brandY.
  5. After running the extension project along with the IdP you should see that the messages are resolved from the brandY messages file.