IBM Worklight v5.0.5 > Develop IBM Worklight applications > Authentication configuration

Security Tests


Overview

A security test is an ordered set of authentication realms that is used to protect a resource such as an adapter procedure, an application, or a static URL. A security test defines the realms that the user must authenticate against in order to get access to the protected resource, and are configured in authenticationConfig.xml

Predefined security tests are supplied for standard web and mobile security requirements.

Before starting, review the Authentication Concepts tutorial at IBM Worklight Getting Started first


Predefined authentication realms

wl_antiXSRFRealm Avoid cross-site request forgery attacks

When new session is initiated the very first request to Worklight server will get a HTTP 401 response containing WL-Instance-Id token. Worklight framework will extract this token and use it as a header on all subsequent requests. In case this header is not present in a request to Worklight server, HTTP 401 will be returned and so on. This security mechanism makes sure that all subsequent requests are coming from the same source as an initial one.

wl_anonymousUserRealm A persistent cookie used by WL server to differentiate between different application instances.

WL server looks for a WL_PERSISTENT_COOKIE cookie in each request. In case not found, it will generate a GUID and send it to back to the client in a Set-Cookie header with 1 year expire date (cookie name is WL_PERSISTENT_COOKIE). Important thing to know is that in case no other type of user identity (user authentication) is defined, the identity obtained from this realm will be considered a user identity.

wl_remoteDisableRealm Used for remote disable/remote notify functionality in hybrid and native applications.
wl_deviceNoProvisioningRealm A default device identity realm. Device identity is similar to user identity, but it is provided by the device itself.

Device identity is relevant on for hybrid/native smartphone environments only. The device identity is a must for functionality like device provisioning, push notifications, reports etc. NoProvisioning means that obtained device identity will be used as is without provisioning.

wl_deviceAutoProvisioningRealm Same as above, but obtained device identity will be automatically provisioned by a Worklight server. This realm makes sense only if used together with wl_authenticityRealm.
wl_authenticityRealm Verify that application is authentic and it was not modified by a third party.

Available on customer and enterprise versions of Worklight only. Authenticity check is based on certificates used to sign applications. You can get more information in IBM Worklight InfoCenter. Currently this functionality is supported by iOS and Android environments only.


Security tests

Worklight platform supports three types of security tests...

The default security configuration automatically include certain built-in realms, even if they are not specified. On the left is the default security, on the right is the equivalent settings using custom security provided by a Worklight platform.

If, for example, you wanted to disable wl_antiXSRFRealm, create custom security tests, and then omit referencing that test realm.

Prior to Worklight 5.0.3, another option was to disable built-in realm authentication by setting <securityTest="wl_unprotected".


application-descriptor.xml

To assign a security test to an app, in the application-descriptor.xml file for the app, set...

After deploying app, the Worklight console should show your security test assigned to the app...


Add your own authentication realm

To add your own authentication realm, replace wl_anonymousUserRealm with your user realm.

Default security Equivalent custom security 
<webSecurityTest name="webTest"> 
    <testUser realm="myRealm" />    
</webSecurityTest>

<customSecurityTest name="webTest">
    <test realm="wl_antiXSRFRealm" />
    <test realm="myRealm isInternalUserId="true" />
</customSecurityTest>

<mobileSecurityTest name="webTest"> 
    <testUser realm="myRealm" />    
    <testDeviceId provisioningType="none" />    
</mobileSecurityTest>

<customSecurityTest name="mobileTest">
    <test realm="wl_antiXSRFRealm" />
    <test realm="wl_remoteDisableRealm" />
    <test realm="myRealm isInternalUserId="true" />
    <test realm="wl_deviceNoProvisioningRealm" isInternalDeviceId="true" />
</customSecurityTest>


Types of protected resources

Application environment To protect application environments with security test other than the default one, specify securityTest in application-descriptor.xml. For example... 
<android securityTest="mobileTest" version="1.0">
    <worklightSettings include="true"/>
    <security>
        <encryptWebResources enabled="false"/>
        <testWebResourcesChecksum enabled="false">
        <publicSigningKey>...
    </security>
</android>
<mobileWebApp securityTest="webTest" version="1.0"/>

Define a separate security test for each application environment (android, iOS, etc.) BlackBerry and Windows Phone environments do not support application authenticity test.

Static resource URL access via Worklight server. Generally means the console. There are no default security tests for static resources. Worklight Console is not protected by default. To protect, define security in <staticResources> section of authenticationConfig.xml. For example... 
<staticResources>
    <resource id="worklightConsole" securityTest="WorklightConsole">
        <urlPatterns>/console*</urlPatterns>
    </resource
</staticResources>


wl_unprotected

Setting securityTest value to "wl_unprotected" means that the resource will not be protected by any of Worklight platform security mechanisms.

For example, for an unprotected adapter procedure...

Note that this might not work with Worklight v5.0.5.


customSecurityTest

To define which realm is to be used as a user realm, adding isInternalUserId="true" property...

Client realms are used for...

There must be exactly one client realm for every security configuration applied to a mobile or web resource

To define a device auto provisioning realm set...

...Device auto provisioning realms are used for...

There must be exactly one such realm for every security configuration applied to a mobile resource.

When you use device auto provisioning in customSecurityTests, an authenticity realm must also be present within the tests, otherwise provisioning will not succeed.

To specify the order in which a client must authenticate in the different realms, add the property step="n" to each test, where n indicates the sequence. If a sequence is not specified, then all tests are done in a single step.


Authentication Entities

A resource, e.g. application or adapter procedure, can be protected by either of two security tests

Each realm defines its own set of authenticators and login modules, which means that each realm has its own rules for collecting credentials and validating them

Realms, authenticators and login modules can be reused. iIn the updated configuration above, Realm2 is reused.

When a request is made to the protected entity, Worklight checks whether the session is already authenticated. If not, Worklight automatically triggers a process to verify the user's identity.

  1. The unauthenticated request tries to access the protected resource.
  2. The Worklight server detects an unauthenticated request and asks the client to provide credentials (challenge).
  3. The challenge handler collects user credentials and sends them to the Authenticator.
  4. The authenticator collects the user credentials and sends them to the login module
  5. The login module receives the credentials and validates them.
  6. If successful, an identity object is created.
  7. An authentication success message is returned to the client application
  8. The client application reissues the original request.


Challenge handlers

A challenge handler is a client side entity that controls the authentication process. A separate challenge handler instance should be created for each realm application.

A challenge handler can be used to detect and handle both the Worklight-related and the external authentication challenges, like the authentication proxies and the gateways. After a challenge handler detects an authentication challenge that is returned from the server, it is responsible for collecting the required credentials and for sending them back to the server. After the authentication flow completes, the challenge handler can send a notification back to the Worklight framework about the authentication success or failure.

Though customizable, a challenge handler is created with pre-set methods used to submit the credentials to built-in user authentication types.


user vs device realms

User realms are used by Worklight for features that require a user, such as...

Device realms are used by Worklight for features that require a device identity, such as...


Define security tests

After seting up authentication realms, define security tests to protect...

Security test types that can be defined in authenticationConfig.xml include...


Parent Authentication configuration




+

Search Tips   |   Advanced Search