Configure device single sign-on

Configure device single sign-on

Procedures

We can configure SSO using either of the following methods...

Device single sign-on with the IBM Security Access Manager Web reverse proxy
Configure device single sign-on with a reverse proxy

SSO development notes

Single sign-on (SSO) is a property of a login module. We can enable single sign-on for custom security tests and for mobile security tests.

We can enable single sign-on from a <mobileSecurityTest> element or from a <loginModule> element of theauthenticationConfig.xml configuration file. For custom security tests, you enable single sign-on on the <loginModule> element. For mobile security tests, you enable single sign-on on the testUser realm of the <mobileSecurityTest> element.
Basically, we configure SSO in the same way for native IOS applications as for hybrid applications. However, for native SSO to work on iOS, this additional step is mandatory: In Xcode, add a Keychain Access Group with the same name for all apps that participate in device SSO.

Take the following points into consideration, depending on how you choose to configure device single sign-on:
When we configure <mobileSecurityTest> elements, enable single sign-on from the <securityTest> element by setting the value of the sso attribute to true. We can enable SSO for user realms only. If the sso attribute is not specified, it is assumed to be set to false. For example:
<mobileSecurityTest name="mst">
  <testDeviceId provisioningType="none"/>
  <testUser realm="myUserRealm" sso="true"/>
</mobileSecurityTest>
When we configure <customSecurityTest> elements, enable single sign-on by configuring an ssoDeviceLoginModule property on the user login module in the authentication configuration file, where ssoDeviceLoginModule is the name of the login module used for the device authentication realm. For example:
<loginModule name="MySSO" ssoDeviceLoginModule="WLDeviceNoProvisioningLoginModule">
  <className>com.worklight.core.auth.ext.NonValidatingLoginModule</className>
</loginModule>
In this example, "MySSO" is the name of the user login module for which single sign-on is being enabled so that its login can be shared. "WLDeviceNoProvisioningLoginModule" is the name of the login module that handles device authentication; in this case, with no provisioning. To use auto-provisioning as the device login module, set the ssoDeviceLoginModule property to the value "WLDeviceAutoProvisioningLoginModule". With custom provisioning, you define the name when you create the custom provisioning login module.
When we configure <customSecurityTest> elements, configure the user realm at least one step later than the device realm. This is necessary to ensure that the SSO feature operates correctly. When we configure SSO on <mobileSecurityTest>, the platform takes care of this prioritization automatically. The following example illustrates a correct <customSecurityTest> configuration:
<customSecurityTest name="adapter">
  <test realm="wl_deviceNoProvisioningRealm" isInternalDeviceID="true" step="1"/>
  <test realm="MySSO" isInternalUserID="true" step="2"/>
</customSecurityTest>
For Windows Phone 8, the following items must be implemented:

The Publisher ID specified in the WMAppManifest.xml file must be the same for all applications that participate in the single sign-on.

The following line must be added to the WMAppManifest.xml file:
<Capability Name='ID_CAP_IDENTITY_DEVICE' />

A cleanup task cleans the database of orphaned and expired single-sign-on login contexts. To configure the cleanup task interval, use the sso.cleanup.taskFrequencyInSeconds server property and assign the required task interval value, expressed in seconds. For information about how to specify MobileFirst configuration properties, see Application server-side configuration parameters.
Results

Device single sign-on implementations are successful if they conform to any of the following valid configurations. Avoid inconsistent states that result from configurations with built-in conflicts, as described below. Inconsistent states can result in the project.failing to start.
Valid configurations:
The <loginModule> element does not specify the ssoDeviceLoginModule attribute, and all mobile security tests that use this login module for their user realms have sso="false". In this case, SSO is disabled for all applications that are protected by security tests (mobile or custom) with this login module for a user realm. For example:
<securityTests>
    <mobileSecurityTest name="FormTest">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealm" sso="false"/>
    </mobileSecurityTest>
    <mobileSecurityTest name="AnotherFormTest">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealm" sso="false"/>
    </mobileSecurityTest>
</securityTests>
<realms>
    <realm name="SampleAppRealm" loginModule="StrongDummy">
        <className>com.worklight.core.auth.ext.FormBasedAuthenticator</className>
    </realm>
</realms>
<loginModules>
    <loginModule name="StrongDummy">
        <className>com.worklight.core.auth.ext.NonValidatingLoginModule</className>
    </loginModule>
</loginModules>
The <loginModule> element does not specify the ssoDeviceLoginModule attribute, and all mobile security tests that use this login module for their user realms have sso="true". In this case, SSO is enabled for all applications that are protected by security tests (mobile or custom) with this login module for a user realm. For example:
<securityTests>
    <mobileSecurityTest name="FormTest">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealm" sso="true"/>
    </mobileSecurityTest>
    <mobileSecurityTest name="AnotherFormTest">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealm" sso="true"/>
    </mobileSecurityTest>
</securityTests>
<realms>
    <realm name="SampleAppRealm" loginModule="StrongDummy">
        <className>com.worklight.core.auth.ext.FormBasedAuthenticator</className>
    </realm>
</realms>
<loginModules>
    <loginModule name="StrongDummy">
        <className>com.worklight.core.auth.ext.NonValidatingLoginModule</className>
    </loginModule>
</loginModules>
The <loginModule> element specifies the ssoDeviceLoginModule attribute, and all mobile security tests that use this login module for their user realms have sso="true". In this case, SSO is enabled for all applications that are protected by security tests (mobile or custom) with this login module for a user realm. For example:
<securityTests>
    <mobileSecurityTest name="FormTest">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealm" sso="true"/>
    </mobileSecurityTest>
    <mobileSecurityTest name="AnotherFormTest">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealm" sso="true"/>
    </mobileSecurityTest>
</securityTests>
<realms>
    <realm name="SampleAppRealm" loginModule="StrongDummy">
        <className>com.worklight.core.auth.ext.FormBasedAuthenticator</className>
    </realm>
</realms>
<loginModules>
    <loginModule name="StrongDummy" ssoDeviceLoginModule="WLDeviceAutoProvisioningLoginModule">
        <className>com.worklight.core.auth.ext.NonValidatingLoginModule</className>
    </loginModule>
</loginModules>
Single sign-on inconsistent state
Avoid conflicts in the single sign-on configuration of a login module. Such conflicts cause inconsistency in the single sign-on state of the login module, and can lead to unexpected results.
A conflict can exist between the configuration of a <loginModule> element and the configuration of a <mobileSecurityTest> element. Such conflict can happen when enabling single sign-on of a login module in the <loginModule> element and then disable single sign-on for the same login module, using it in a <mobileSecurityTest> without specifying sso="true" for the realm of this <loginModule>. For example:
<securityTests>
    <mobileSecurityTest name="FormTest">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealm"/>
    </mobileSecurityTest>
</securityTests> 
<realms>
    <realm name="SampleAppRealm" loginModule="StrongDummy">
        <className>com.worklight.core.auth.ext.FormBasedAuthenticator</className>
    </realm>
</realms>
<loginModules>
    <loginModule name="StrongDummy" ssoDeviceLoginModule="WLDeviceAutoProvisioningLoginModule">
        <className>com.worklight.core.auth.ext.NonValidatingLoginModule</className>
    </loginModule>
</loginModules>
Another case of conflict can happen between different <mobileSecurityTest> elements, when two <mobileSecurityTest> elements use the same login module, with conflicting values for the sso attribute. In this example, the same realm contains conflicting sso enablement states in two <mobileSecurityTest> elements.
<securityTests>
    <mobileSecurityTest name="FormTest">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealm"/>
    </mobileSecurityTest>
    <mobileSecurityTest name="FormTestWithSso">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealm" sso="true"/>
    </mobileSecurityTest>
</securityTests>
Here is another example, in which the same login module is used for different realms with conflicting SSO enablement states in two <mobileSecurityTest> elements:
<securityTests>
    <mobileSecurityTest name="FormTest">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealm"/>
    </mobileSecurityTest>
    <mobileSecurityTest name="FormTestWithSso">
        <testDeviceId provisioningType="none"/>
        <testUser realm="SampleAppRealmWithSso" sso="true"/>
    </mobileSecurityTest>
</securityTests>
<realms>
    <realm name="SampleAppRealm" loginModule="StrongDummy">
        <className>com.worklight.core.auth.ext.FormBasedAuthenticator</className>
    </realm> 
    <realm name="SampleAppRealmWithSso" loginModule="StrongDummy">
        <className>com.worklight.core.auth.ext.FormBasedAuthenticator</className>
    </realm>
</realms>
Parent topic: Device single sign-on (SSO)