Direct Update as a security realm

Since IBM® Worklight Foundation V6.2.0, Direct Update has been part of the MobileFirst security framework, and is defined as a security realm.

The incorporation of Direct Update into the MobileFirst security framework provides greater flexibility and consistency. Direct Update is enabled by default on all supported platforms, including iPhone, iPad, Android, and Microsoft Windows Phone Silverlight 8. Checks for Direct Update occur during requests to the server. If an update is available, the client displays a confirmation dialog. When the user accepts, the new resources are downloaded from the MobileFirst Server and the app restarts.

Configuring the Direct Update realm

You configure Direct Update in the authenticationConfig.xml file. A Direct Update test can be added to any mobile security test or custom security test.

Example of a Direct Update test in a mobile security test

<mobileSecurityTest name="mobileWithDirectUpdate">
  <testDirectUpdate mode="perRequest"/>
  <testDeviceId provisioningType="none"/>
  <testUser realm="wl_anonymousUserRealm"/>
</mobileSecurityTest>

Example of a Direct Update test in a custom security test

<customSecurityTest name="customWithDirectUpdate">
  <test realm="wl_directUpdateRealm" mode="perRequest" step="1"/>
  <test realm="wl_anonymousUserRealm" isInternalUserID="true" step="1"/>
  <test realm="wl_deviceNoProvisioningRealm" isInternalDeviceID="true" step="2"/>
</customSecurityTest>

Mode

You can use the optional mode property to configure when the server checks for direct updates. The following table describes the possible modes:

Table 1. Values of the `mode` attribute
Mode	Description
`perSession`	The server checks whether a Direct Update is available (and if so, delivers it) once per session, on the first request to the server. This is the default mode.
`perRequest`	The server checks whether a Direct Update is available (and if so, delivers it) on every request to the server.
`disabled`	The server never checks whether a Direct Update is available (not even during an explicit call to `WL.Client.login`, as described in Check for Direct Update on demand).

Note: If code that uses the Direct Update realm accesses a resource that is protected by OAuth authentication, and the client has a valid token, the MobileFirst Server is not called. As a result, the server does not check for an available Direct Update, regardless of the value of the mode property. The MobileFirst Server is called when the token expires or when the Direct Update realm inside the token expires. When the realm expires, the Direct Update authenticator is invoked and the server checks for an available Direct Update.

Mobile security test

If a Direct Update test is not specified in a mobile security test, it is enabled with the default perSession mode. To change the direct update mode to perRequest in a mobile security test, add a direct update test with mode="perRequest" to a mobile security test: <testDirectUpdate mode="perRequest"/>. To disable direct update in a mobile security test, add a direct update test with mode="disabled" to the mobile security test: <testDirectUpdate mode="disabled"/>.

Custom security test

To add a Direct Update test to a custom security test, add the following test to the security test: <test realm="wl_directUpdateRealm"/>. The default mode is perSession. To change the mode, specify a value for the mode attribute: <test realm="wl_directUpdateRealm" mode="perRequest"/>. To disable automatic Direct Update in a custom security test, either set the mode to disabled or do not add a test with a Direct Update realm.

Changes from previous versions of IBM MobileFirst Platform Foundation

In IBM Worklight V6.1.0 and earlier versions, the server checks for direct updates as part of the WL.Client.connect() request. Since IBM Worklight Foundation V6.2.0, the server checks for updates outside the WL.Client.connect() request. Because Direct Update is now part of the security framework, the server can check for direct updates on every request from the client to the server, on first request, or not at all, depending on the configuration.

In IBM Worklight V6.1.0 and earlier versions, returning the application to the foreground triggered a server request to check for direct updates. Since IBM Worklight Foundation V6.2.0, you can configure MobileFirst Server to check for direct updates on every request; therefore direct updates are no longer explicitly checked when the application returns to the foreground. You can impose the behavior of earlier versions by listening to the "resume" event fired by Cordova and manually checking for direct updates:

$(document).on("resume", function(){
    WL.Client.login("wl_directUpdateRealm", {onSuccess:..., onFailure:...});
});

Check for Direct Update on demand

You can configure Direct Update so that the server checks for direct updates only when there is an explicit call to do so. To apply this setting, protect the application with a custom security test that does not contain a test with wl_directUpdateRealm. In the application code, use WL.Client.login("wl_directUpdateRealm", {onSuccess:.., onFailure:...}), which causes the server to check for direct updates. (See the documentation for the login method of WL.Client.) This configuration does not work if the custom security test that protects the application contains wl_directUpdateRealm with mode="disabled".

Native applications and Direct Update

Direct Update is supported only by the JavaScript WL.Client. For applications that are protected by a direct update realm that is configured to use perSession mode, when such applications initiate a server session by using a native WLClient call, the server assumes that Direct Update is not required for this session even if subsequent requests are made by using a JavaScript WL.Client call. In such cases, to enable Direct Update to work when using the JavaScript WL.Client, configure the direct update realm to use perRequest mode.

Direct Update Customization

Developers can customize the Direct Update process for hybrid applications on iOS, Android, and Microsoft Windows Phone Silverlight 8. For more information, see Customizing the direct update interface and process.

Upgrading projects

When you import a project from Worklight Studio V6.1.0 or earlier versions into MobileFirst Studio, the following Direct Update test is added automatically to every custom security test in the project authenticationConfig.xml file: <test realm="wl_directUpdateRealm" step="1"/>. Direct Update then continues to work in a similar way to how it worked in versions earlier than V6.2 (that is, Direct Update checks are made once per session).