WebView Extension Points

The HttpConvAuthFlows library supports various authentication mechanisms that can be configured on a HttpConversationManager instance through the CommonAuthFlowsConfigurator class.

Some of these authentication mechanisms are Web-based, namely:
  • SAML2 authentication
  • Two-factor/one-time password (OTP) authentication
These mechanisms open a Web view during the authentication process that opens Web pages through which the user provides credentials for authentication. In versions earlier than 3.0 SP13, these mechanisms relied on the Android System WebView. Extension points allow you to "hook into" the Web view opening process, enabling you to integrate third-party Web view implementations such as Crosswalk, or plug into other Web-based mobile technologies such as Cordova.

Implementing Web Strategies

  • Basics “Web strategy interfaces” define how a Web-based authentication flow starts and finishes, and is described in the package.
    Strategy interfaces end with the WebStrategy suffix. There is one such interface for every authentication type:
    • SAML2WebStrategy
    • OTPWebStrategy

    Each of these interfaces define a single start* method which is invoked whenever the authentication subprocess that requires a Web view needs to start. The start* methods also receive a callback object as the final argument, which signals that authentication has completed with either success or failure, making these strategies asynchronous.

    The exact signature of these methods depends on the authentication method. Here is an example from the built-in default implementation of SAML2WebStrategy,which opens a separate activity that displays the Android System WebView:
    public enum DefaultSAML2WebStrategy implements SAML2WebStrategy {
        public void startSaml2Authentication(
    	Context appContext,
    	String finishEndpoint,
    	String finishEndpointParam,
    	SAML2AuthenticationCompleteCallback callback) {
            // Start the activity.
            Intent intent = new Intent(appContext, SAML2AuthActivity.class);
    		appContext.getPackageName() + EXTRA_FINISH_ENDPOINT,
    		appContext.getPackageName() + EXTRA_FINISH_ENDPOINT_PARAM,

    The above code omits how the activity communicates back to the strategy implementation at the end of the flow. The implementor must define this mechanism by invoking the callback in the argument when the authentication flow completes.

  • Principles and guidelines Developers should adhere to the following guidelines when implementing these strategies:
    • Use the HttpConvAuthFlows library to ensure a series of guarantees regarding strategy executions. Most importantly, the library ensures that there is only one current strategy running for a given authentication type.
    • Consequently, most strategy implementations can be singletons, which may manage the internal state. The start* method of a strategy is never invoked before a previous invocation completes.
    • Instructions for using the exact contracts are in the API documentation. Familiarize yourself with the concepts before implementing any strategy.

    Strategies are process-wide extension points that cannot be configured per HttpConversationManager via the CommonAuthFlowsConfigurator class. This is by design, as Web-based authentication flows are carefully managed by the library even across conversation manager instances to prevent multiple Web authentication flows from starting simultaneously.

Registering Web Strategies

  • The WebStrategy singleton Because the Web strategies are process-wide, you can configure them using the singleton class, which contains a series of register* methods that define the strategy implementations that can be added. However, instances are registered indirectly via “resolvers.”
  • Strategy resolvers A strategy resolver is an interface that has the WebStrategyResolver suffix. Each strategy interface is paired with its corresponding resolver:
    • SAML2WebStrategyResolver
    • OTPWebStrategyResolver

    These interfaces all contain a single resolve method that takes almost the same arguments as the start* method in the corresponding strategy interface, but simply returns the strategy instance to work with instead of performing the authentication.

    Resolvers allow strategies to be configured per endpoint. For example, you can implement a SAML2 resolver that returns a SAML2 Web strategy that utilizes the Crosswalk WebView for the authentication of only certain hosts. SAML2 challenges received from other hosts can be handled by other strategies, for example, the default.

    This flexibility counteracts the limitation that strategies cannot be configured per HttpConversationManager due to the process-wide management of Web-based authentication flows.

    To integrate a custom Web strategy that is used in every case, implement a resolver that simply returns the custom instance unconditionally. Here is an example for the OTP authentication type:
    WebStrategies.inst.registerResolver(new OTPWebStrategyResolver() {
    	public OTPWebStrategy resolve(
    		String finishEndpoint,
    		String finishEndpointParam,
    		String redirectToOriginalURLParam) {
    		return MyCustomOTPWebStrategy.getInstance();
  • Default strategies By default, each authentication method has default strategies that use activities to show the Android System WebView. The WebStrategies singleton falls back to these implementations if none of the resolvers produce a non-null strategy object during execution of a Web-based authentication flow. Consequently, this extension point API is backward compatible and requires no code changes. New strategies must be implemented and registered explicitly in order to deviate from the default behaviour (that was provided in versions earlier than SP13) during SAML2 and OTP authentications.

Cookie Management Considerations

Both SAML2 and OTP authentication methods in HttpConvAuthFlows rely on cookies being sent by the server. As such, when the authentication flow completes, the strategy need only signal success unless cookies are managed differently.

The HttpC library uses the class internally to manage cookies. This works with a default implementation, returning the cookie manager that is currently in use. If a particular strategy implements a mechanism that relies on a different cookie store, the cookies representing the successful authentication must be copied to the default cookie manager.

A strategy implementation that signals success without copying the relevant cookies to the cookie store that HttpC uses results in failing requests and authentication challenges repeating until either the conversation flow terminates itself due to reaching the maximum restart limit, or the server sends a response denying access (typically, an HTTP 403 or 401).

When you are implementing custom strategies, pay close attention to how cookies are managed, and, if your custom strategy uses a separate cookie store mechanism, copy the relevant cookies to the default cookie manager at the end of a successful authentication.