Developer

Support for Common Authentication and Authorization Flows

The HttpConversation library with its filter mechanism makes a conversation flow possible by allowing controlled implementation of scenarios that involve authentication and authorization. The HttpConvAuthFlows library used with HttpConversation lets you manage common authentication/authorization flows, for example, Basic authentication and SAML flow. A manager configurator called CommonAuthFlowsConfigurator lets you configure your HttpConversationManager to manage the authentication/authorization flow of its conversations.

To utilize the CommonAuthFlowsConfigurator, obtain an instance by using its constructor that expects an application context:
CommonAuthFlowsConfigurator configurator = new CommonAuthFlowsConfigurator(context);

Basic Authentication

You can add support for Basic authentication by setting a specified UsernamePasswordProvider to the CommonAuthFlowsConfigurator using the supportBasicAuthUsing(provider) method.

The supportBasicAuthUsing(provider) method enables usage of IBasicAuthCredentialsObserver objects: if a conversation manager is configured using a configurator of this type, supporting basic authentication and that manager is then extended with IBasicAuthCredentialsObserver objects. After which these observers are invoked. This method can be invoked multiple times with different providers, each placed in a list. During a conversation flow, the first provider that returns a non-null value (which can be either a username/password combination or a cancellation object) is invoked.

Credentials can be provided either in the implementation of UsernamePasswordProvider, or in response to a challenge from the corresponding onCredentialsNeededUpfront() and onCredentialsNeededForChallenge() methods. Credentials are expected to be provided by returning a UsernamePasswordToken instance from these methods, not from being stored within the manager context.

The code below provides credentials for an authentication challenge with the help of the CommonAuthFlowsConfigurator. Credentials are provided by UsernamePasswordProvider because onCredentialsNeededUpfront() returns null. onCredentialsNeededForChallenge() returns the expected UsernamePasswordToken..

SAML2 Flow

Add support for SAML2 authentication by setting the SAML2ConfigProvider to the CommonAuthFlowsConfigurator with the method supportSaml2AuthUsing(provider). You can invoke this method multiple times with different providers, using a list. During a conversation flow, the first provider that returns a non-null value is invoked.

You must implemnet the SAML2ConfigProvider to supply SAML configuration parameters when they are required. The implementation is expected to return an instance of the SAML2Config from the onSAML2Challenge() method. Failing to provide a configuration object cancels the conversation; SAML2AuthCancellation is the cancellation object.

The SAML2Config constructor has these parameters:
  • header (optional) The server HTTP response header name that indicates the SAML challenge, and facilitates SAML challenge detection if the server supports the sending of this header.
  • finish endpoint The URL the client must send the request to start the SAML authentication.
  • finish endpoint parameter The URL parameter that detects flow completion.

Add the SAML2AuthActivity to the Android Manifest before using SAML2 this way. SAML2AuthActivity shows a WebView whenever browser-based authentication is required.

Use the SAPCookieManager, since the cookies received by the WebView are used in the native HTTP communication as well.

This code illustrates how to use the CommonAuthFlowsConfigurator to configure the manager to process the SAML2 flow.

The WebView appears repeatedly even when authentication is done correctly by the end user. This may be because the cookies used during authentication are incorrect, which in turn causes the conversation flow to be restarted repeatedly until the maximum number of restarts is reached. To troubleshoot this, and other issues, turn on the DEBUG log level and use an HTTP traffic logging tool such as Fiddler to capture the network data exchanged (including cookies).

If more conversations are started in parallel,even using different HttpConversationManagers, which has one common finishEndpoint, the WebView appears only once and after a successful authentication, all initiated conversations continue simultaneously with their SAML flow.

One-Time Password (OTP) Flow

An administrator (SAP Mobile Platform Server or mobile service for development and operations) can require a one-time password (OTP) as a second-factor verification step, together with existing authentication mechanisms (for example OAuth and SAML) for the native app to establish a valid session with a server or mobile services. For example, in a banking app, only basic authentication is required to check an account balance; however, two-factor authentication is required (via a OTP sent by SMS message) to make a transfer.

Add support for OTP authentication by setting the OTPConfigProvider to the CommonAuthFlowsConfigurator with the method supportOTPUsing(provider).You can invoke this method multiple times with different providers. During a conversation flow, the first provider that returns a non-null value is invoked.

You must implement OTPConfigProvider to supply OTP configuration parameters when they are required. The implementation is expected to return an instance of the OTPConfig from the onOTPChallenge() method. Failing to provide a configuration object cancels the conversation; OTPAuthCancellation is the cancellation object. The OTPConfig constructor includes these parameteres:
  • header the server HTTP response header name that indicates the OTP challenge, and facilitates OTP challenge detetection if the server supports the sending of this header.
  • headerValue the server HTTP response header value that indicates the OTP challenge.
  • finish endpoint the URL to which the client must send the request to start the OTP authentication.
  • finish endpoint parameter the URL parameter that indicates the end of the authentication flow.
Add the OTPAuthActivity to the Android Manifest before using OTP as follows:
<activity 
android:name="com.sap.smp.client.httpc.authflows.OTPAuthActivity">
</activity>
The OTPAuthActivity shows a WebView. The content of the webview is downloaded from the the finish endpoint. You can define an intent filter for the OTPAuthActivity for seamless navigation with the SAP authenticator, as illustrated by this code snippet, which should be added as a child element under the activity element:
<intent-filter>
    <data android:scheme="<<package name>>.xcallbackurl" />
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
</intent-filter>
This code illustrates how to use the CommonAuthFlowsConfigurator to configure the manager to process the OTP flow:

The WebView appears repeatedly even when authentication is performed correctly by the end user. This may be because the cookies used during authentication are incorrect, which in turn causes the conversation flow to restart repeatedly until the maximum number of restarts is reached. To troubleshoot this and other issues, turn on the DEBUG log level and use an HTTP traffic logging tool such as Fiddler to capture the network data exchanged (including cookies).

If more conversations are started in parallel, even using different HttpConversationManagers, which has one common finishEndpoint, the WebView appears only once and after a successful authentication, all initiated conversations continue simultaneously with their OTP flow.