IBM Worklight Project Auto-upgrade to 5.0.0.3 Authentication Model

Content

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

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

• Define a new entity called security test – a set of realms a user/device/application must authenticate against in order to gain access to a protected resource
• Have a unified client-side API for all types of security tests including user authentication
• Have predefined security test sets for mobile and web environments
• Build completely custom security test sets
• Protect applications by any number of realms
• Protect each adapter procedure by any number of realms
• Define the order in which security checks will be made

• Prior to 5.0.0.3 the authenticationConfig.xml file had <realms> and <loginModules> elements
• A new element called <securityTests> was added in 5.0.0.3
• <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 5.0.0.3:
  
• 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

• The XML file of each adapter was upgraded to comply with 5.0.0.3
• 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

• The application-descriptor.xml file in each application was upgraded to comply with 5.0.0.3
• 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 5.0.0.3
  
• 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

• A new entity called ChallengeHandler was introduced in 5.0.0.3
• 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 5.0.0.3 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

• AuthenticationResult API changes:
• The enumerations in the AuthenticationResult object have been moved to AuthenticationStatus.
• So for example: the following code needs to be changed as follows:
  From:
  AuthenticationResult.CLIENT_INTERACTION_REQUIRED
  To:
  AuthenticationResult.createFrom(AuthenticationStatus.CLIENT_INTERACTION_REQUIRED)
  This is repeated for all the existing enumerations that used to exist for AuthenticationResult
• com.worklight.server.auth.api.WorkLightAuthenticator API changes:
• A new method, “boolean changeResponseOnSuccess(HttpServletRequest, HttpServletResponse)”, has been added to the interface. It is invoked after the authentication succeeds and allows the addition of custom data to the HttpServletResponse when needed
• 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"/>
  </mobileSecurityTest>
• Prior to 5.0.0.3 the process to notify that the user session was authenticated had to be done manually. This is no longer necessary as the "submitSuccess" method in ChallengeHandler takes care of resubmitting the original request automatically once the user is authenticated.
• For more information, see the training modules related to authentication in the Getting Started Guide.