IBM Worklight v5.0.5 > Develop IBM Worklight applications > Authentication configuration
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.
Worklight platform supports three types of security tests...
webSecurityTest wl_anonymousUserRealm and wl_antiXSRFRealm enabled by default. Must contain one testUser element with a realm definition for client authentication. mobileSecurityTest wl_anonymousUserRealm, wl_antiXSRFRealm, wl_remoteDisableRealm and wl_deviceNoProvisioningRealm enabled by default. Must contain one testUser element with a realm definition for client authentication. customSecurityTest No predefined realms. Contains only what developer will define.
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.
Default security Equivalent custom security <webSecurityTest name="webTest"> </webSecurityTest <customSecurityTest name="webTest"> <test realm="wl_antiXSRFRealm" /> <test realm="wl_anonymousUserRealm isInternalUserId="true" /> </customSecurityTest> <mobileSecurityTest name="webTest"> </mobileSecurityTest> <customSecurityTest name="mobileTest"> <test realm="wl_antiXSRFRealm" /> <test realm="wl_remoteDisableRealm" /> <test realm="wl_anonymousUserRealm isInternalUserId="true" /> <test realm="wl_deviceNoProvisioningRealm" isInternalDeviceId="true" /> </customSecurityTest>
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".
To assign a security test to an app, in the application-descriptor.xml file for the app, set...<iphone bundleId="com.NorthEast" version="1.0" securityTest="mobileTest"> <worklightSettings include="true"/> <security> <encryptWebResources enabled="false"/> <testWebResourcesChecksum enabled="false" ignoreFileExtensions="png, jpg, jpeg, gif, mp4, mp3"/> </security> </iphone> <android version="1.0" securityTest="mobileTest"> <worklightSettings include="true"/> <security> <encryptWebResources enabled="false"/> <testWebResourcesChecksum enabled="false" ignoreFileExtensions="png, jpg, jpeg, gif, mp4, mp3"/> <publicSigningKey> public key of certificate </techSigningKey> </security> </android> <common securityTest="webTest"/>
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>
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...
<procedure name="aProcedureName" securityTest="wl_unprotected" />
Note that this might not work with Worklight v5.0.5.
To define which realm is to be used as a user realm, adding isInternalUserId="true" property...
Client realms are used for...
- client identification reporting
- push subscriptions
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...
- device identification reporting
- push subscriptions
- device SSO
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.
A resource, e.g. application or adapter procedure, can be protected by either of two security tests
- Using Security test 1 means user will have to authenticate in both Realm1 and Realm2, each one with its own set of rules
- Using Security test 2 means user need to authenticate in Realm3 only
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.
- Protecting a resource with Security test1 means a need to authenticate in both Realm1 and Realm2
- Protecting a resource with Security test2 means a need to authenticate in Realm2 only
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.
- The unauthenticated request tries to access the protected resource.
- The Worklight server detects an unauthenticated request and asks the client to provide credentials (challenge).
- The challenge handler collects user credentials and sends them to the Authenticator.
- The authenticator collects the user credentials and sends them to the login module
- The login module receives the credentials and validates them.
- If successful, an identity object is created.
- An authentication success message is returned to the client application
- The client application reissues the original request.
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...
- push notification
- application usage reports
Device realms are used by Worklight for features that require a device identity, such as...
- device provisioning
- push notification
- SMS notification
Define security tests
After seting up authentication realms, define security tests to protect...
- adapter procedures
- static resources
Security test types that can be defined in authenticationConfig.xml include...
webSecurityTest Has default web security-related realms enabled. mobileSecurityTest Has default mobile security-related realms enabled. customSecurityTest Does not contain any default realm.
Parent Authentication configuration