IBM Support

IBM Worklight Project Auto-upgrade to Authentication Model

Product documentation


This document outlines the details of upgrading IBM Worklight projects to, outlining enhancements that were made to the underlying authentication framework.


IBM Worklight has many improvements in the authentication framework. In order for existing projects to continue functioning, Worklight Studio will automatically upgrade them to comply with

The main server-side improvement of the authentication framework is a flexible protection mechanism that allows a developer to:

IMPORTANT - Before making any modifications to your project Worklight Studio will create its backup in the apps-backup folder

Changes in the authenticationConfig.xml file

  • Prior to the authenticationConfig.xml file had <realms> and <loginModules> elements
  • A new element called <securityTests> was added in
  • <securityTests>'s child element defines a security configuration for an application or adapter procedure
  • <securityTests> 's child element can be of three types
    • <webSecurityTest> - used for preview and web environments. Contains a hardcoded set of web related tests
    • <mobileSecurityTest> - used for mobile environments. Contains a hardcoded set of mobile device related tests
    • <customSecurityTest> - completely custom security test. Does not contain any hardcoded security tests.
  • If this was your authenticationConfig.xml prior to
  • This is how it's going to look after upgrade
  • (1) The realm definition did not change
  • (2) The login module definition does not have canBeResourceLogin and isIdentityAssociationKey attributes anymore. Any login module can be used to protect a resource. The identity association feature was deprecated.
  • (3) If your project had a protected adapter, a new <customSecurityTest> element will be created containing a reference to the realm that was used to protect the adapter
  • (4) and (5) In case your application was defined with requireAuthentication="onStartup", the new <webSecurityTest> and <mobileSecurityTest> elements will be added
  • <testUser …> and isInternalUserID="true" means that an identity from this realm is considered a userIdentity for internal purposes like reports
  • securityTests defined in authenticationConfig.xml will be used in the adapter's XML files and application-descriptor.xml files as described below

Changes in the adapter's xml file

  • Each procedure that previously required authentication has a securityTest definition instead of an authenticationRequired="true" property
  • The securityTest name corresponds to the one created in authenticationConfig.xml
  • The authenticationRealm attribute is removed and is no longer necessary as the securityTest attribute on the protected resource call already references the appropriate realm to use as defined in the authenticationConfig.xml

Changes in application-descriptor.xml file

  • The application-descriptor.xml file in each application was upgraded to comply with
  • The <usage> element was removed, instead of it each environment, including common, contains a definition of a security test to use
  • If this was your application-descriptor.xml prior to
  • This is how it's going to look after upgrade
  • (1) In case your application had a requireAuthentication="onStartup" attribute, a common environment with a web securityTest definition is added
  • (2) In case your application had a requireAuthentication="onStartup" attribute, each mobile environment will have a mobile securityTest defined
  • The securityTest name corresponds to the one created in authenticationConfig.xml

Changes in auth.js file

  • A new entity called ChallengeHandler was introduced in
  • ChallengeHandler has a unified API for handling all types of Worklight internal and external security challenges and tests
  • Your Authenticator object was not modified
  • In order for your original Authenticator to comply with a ChallengeHandler wrapper was added to the auth.js file instead
  • The Worklight framework code will invoke the ChallengeHandler's functions
  • Most of the functionality is performed by the isCustomResponse function of ChallengeHandler
  • Below see the functionality invocation map between ChallengeHandler and Authenticator

Other considerations

  • AuthenticationResult API changes:
    • So for example: the following code needs to be changed as follows:
      This is repeated for all the existing enumerations that used to exist for AuthenticationResult
  • com.worklight.server.auth.api.WorkLightAuthenticator API changes:
  • Changes needed for the Adapter implementation Javascript file as it relates to the WL.Server.createEventSource API
    • The API call now should specify a securityTest parameter in addition to the name attribute and other parameters
    • Once again the securityTest name corresponds to the one created in authenticationConfig.xml, however the securityTest type for this is Mobile Security Test
    • For example as defined in the authenticationConfig.xml:
      <mobileSecurityTest name="PushApplication-strong-mobile securityTest">
      <testDeviceId provisioningType="none"/>
      <testUser realm="MyAppRealm"/>
  • For more information, see the training modules related to authentication in the Getting Started Guide.

Cross reference information
Segment Product Component Platform Version Edition
Mobile- Speech and Enterprise Access IBM Mobile Foundation Studio AIX, HP-UX, Linux, Mac OS X, Solaris, Windows 5.0 Consumer, Enterprise

Document information

More support for: IBM Worklight

Software version:

Operating system(s): AIX, HP-UX, Linux, OS X, Solaris, Windows

Software edition: Consumer, Enterprise

Reference #: 7036063

Modified date: 04 January 2013