MobileFirst security configuration

For MobileFirst Server to protect a resource, such as an adapter procedure or an application environment, the administrator must first configure the MobileFirst Server instance.

Defining a login module

A login module is the most basic security element in the MobileFirst authentication configuration. You can define a login module in the <loginModules> element in the authenticationConfig.xml file. The following example shows a login module definition:

<loginModules>
...
  <loginModule name="HeaderLogin"
               audit="true
               expirationInSeconds="-1">
    <className>com.worklight.core.auth.ext.HeaderLoginModule</className>
    <parameter name="user-name-header" value="userid" />
    <parameter name="display-name-header" value="username" />
  </loginModule>
...
</loginModules>

In this example, the login module is called HeaderLogin and is referred to from a realm element. The <className> element must contain the full Java™ namespace to a login module implementation. The HeaderLoginModule is a login module that is included by default. It checks that the user entered any, non-empty user name and password.

Defining a realm

After a login module is defined, you must specify a realm. You can add a realm to the <realms> element in the authenticationConfig.xml file. The following example shows a realm definition:

<realms>
...
  <realm name="RequiresUserHeaders" loginModule="HeaderLogin">
    <className>com.worklight.core.auth.ext.HeaderAuthenticator</className>
  </realm>
...
</realms>

Defining a security test

You can define a security test in the <securityTests> element in the authenticationConfig.xml file. The following example shows a security test definition:

<securityTests>
...
  <customSecurityTest name="BasicRequirements">
    <test realm="wl_antiXSRFRealm" />
    <test realm="wl_authenticityRealm" />
    <test realm="wl_remoteDisableRealm" />
    <test realm="RequiresUserHeaders" isInternalUserID="true" />
    <test realm="wl_deviceNoProvisioningRealm" isInternalDeviceID="true" />
  </customSecurityTest>
...
</securityTests>

This custom security test is called BasicRequirements, and contains a list of tests. The tests define which realms are required for authorization into the protected resource. The tests in this example are built-in realms. Built-in realms are prefixed with wl_.

Note: If one test fails, then the entire security test fails.

The isInternalUserID attributes can be set to true only on a single realm. This attribute is used as the default identity for a user in the security test. The isInternalDeviceID attribute is similar, but sets a default device identity.

This example uses the RequiresUserHeaders realm in the previous example.

Creating a challenge handler

You must create a challenge handler for your MobileFirst app to handle any custom challenges.

For more information about challenge handlers, see the tutorials on the following Getting Started pages of the Developer Center: Custom Authentication and Creating the client-side authentication components.

MobileFirst application environment protection

After a security test is configured with the appropriate realms, you can protect any resource. One option is to completely protect an application’s environment with that security test.

To set up this protection, you must add the securityTest attribute to the environment’s element in the applicationDescriptor.xml file. The following example shows the environment protection definition:

<iPhone version="1.0" securityTest="BasicRequirements">
...
</iPhone>

This definition requires every iPhone device that connects to the server through your application to log in to the BasicRequirements security test.

MobileFirst adapter procedure protection

Another option is to protect a MobileFirst adapter procedure. Using the same security test, you can protect an adapter procedure. When the procedure is called and the user is not already authenticated into the security test, the client is required to authenticate. If you have an adapter procedure named GetSecretData, you can protect it in the adapter’s XML configuration file by adding the securityTest attribute to the <procedure> element:

<procedure name="GetSecretData" securityTest="BasicRequirements" />