Migration Guide - MAF Logon to HttpConversation¶
Here you can find the comprehensive guide on how to migrate applications based on the MAF Logon framework to the HttpConversation libraries. This document is strongly recommended for anyone who is considering to upgrade their MAF Logon based apps created using SMP SDK 3.0 to SMP SDK 3.1.
Find below the list of topics that are covered by this guide:
- Preparing for the migration
- Use cases
A solid understanding of the HttpConversation libraries is a must before proceeding with this guide. It is recommended to read the HttpC Developer Guide and some parts of the API docs before reading further.
MAF Logon framework contains a lot of components to help applications build their onboarding and user authentication functionalities. It consists of mainly two parts: a core (implemented by the
MAFLogonCore library) and a UI (implemented by the
These two components work in conjunction to show the related onboarding user interfaces and perform registration, unregistration, secure store management, etc.. Typically, when the application starts up for the first time, MAF Logon UI can be instructed to show a screen on which the server coordinates (host, port, etc.) can be specified. Then, the onboarding usually continues by asking for the user credentials. Finally, a successfully authenticated session is established using which data requests (typically, OData requests) may be fired against the endpoint.
The MAF Logon framework offers a very wide range of features, making it rather versatile. However, it also has a couple of limitations. Namely:
- The framework is inherently single-user. Building a multi-user solution is not currently supported, although there are parts of the framework which point in that direction. In short: if you want your app to be used by more than one user then building the solution with Logon is going to be more difficult.
- Logon supports only proactive authentication, that is, when you establish the session upfront. The data requests then rely on the availability of this session. If it expires, the application has to catch the relevant authentication failures occuring in data requests and re-route the application back to the Logon screens.
Furthermore, the wide range of features that are included in Logon over time made its API rather complex and ofentimes hard to work with. Experience shows that in the majority of the cases this level of complexity is not required, thus a simpler solution would suffice.
With the experiences gained the MAF Logon framework has been deprecated in SMP SDK 3.0 SP16 and is removed from SMP SDK 3.1. This guide helps you move away from MAF Logon to pure HttpConversation library which offers a lot more flexibility meanwhile helping you to build the most sensitive parts with greater ease.
This section discusses the scope of the guide in terms of which MAF Logon features are covered. Certain features of Logon are taken over by other libraries.
One of the most important features of Logon is that it is capable of performing authentication in a variety of ways (BasicAuth, X.509 client credentials, SAML2, etc.). All of these authentication mechanisms (and more) can be implemented using the
The goal of this guide therefore is to help you rewrite the parts that perform authentication using MAF Logon to use HttpC instead.
Proactive vs. reactive¶
As mentioned already, MAF Logon treats the authentication step as a prerequisite that needs to be fulfilled before doing anything else. Your application therefore is likely to follow (roughly) the below flow after startup:
- (if application is not configured) Obtain configuration, if required then via MAF Logon UI screens.
- Login screen to log the user in.
- (if SMP server or Mobile Services on SAPcp is used) Registration with the server.
- Application main screen is entered. Data requests may be fired from this point onward. The app is ready for use.
- If the session expires in the middle of data requests, the application has to handle the error and re-route the user back to the Logon screens.
Recall that this guide deals with only the authentication-related features of MAF Logon. For example, the passcode management steps that take place as part of step no. 3 are not elaborated any further.
The proactive nature of MAF Logon is more than obvious from the above. With HttpC, the flow on the other hand is quite different:
- (if application is not configured) Obtain configuration, if required then via some configuration screens.
- Configure the
HttpConversationManagers that are going to be used for data requests. This configuration is often done with the help of the
- Application main screen is entered. Data requests may be fired from this point onwards. As the servers require authentication, the running HTTP conversations will react to the challenges and display the login screens as required.
The difference is more than outstanding. The user is not bothered with login screens 'till it is absolutely necessary. Note that how the reactive philosophy of HttpC also takes care of the use case when the session expires. In that case the server will issue another authentication challenge that a properly configured
HttpConversationManager will handle under the hood.
If required, adding some proactive behaviour to a HttpC-based application is rather easy. If you prefer to have the login screens show as soon as possible then simply send a preflight request to your data endpoints to provoke the server to present an authentication challenge If you're using an OData endpoint, this preflight request can be as simple as an HTTP HEAD sent to the service document endpoint, for example.
Note on user interfaces¶
In the previous section we did not mention what the fate of MAF Logon UI screens would be and how to migrate away from them. Below we summarize the key ideas regarding this.
MAF Logon comes with a range of pre-built user interfaces for the login screens, configuration screens, passcode management screens, etc.. These intended to help the application developer integrate and customize these screens with ease and without having to deal with building a UI on their own.
With new versions of the Android platform and the advent of Android Studio, building sophisticated user interfaces for various form factors and orientations has become easier than ever. You can easily create various layout XMLs, style them with the WYSIWYG editors, attach listeners to controls or use bindings to link them to variables and methods in your activities or fragments.
Therefore, the need for easily configurable pre-built user interfaces is now gone. This is why HttpC does not have any UI components at all. If you want to create your own onboarding, configuration or login screens, simply build your own UIs with the platform provided mechanisms. The goal of HttpC is instead to allow you to easily integrate such solutions into your application.
The HttpC Developer Guide already contains an example snippet briefly explaining the key ideas concerning how to create a username/password dialog with Android Fragments and how to integrate it with a
UsernamePasswordProvider implementation, for example.
As all conversations run on a separate thread (provided that background executors are configured for the
HttpConversationManager in question), it is permitted to block these threads 'till a UI interaction completes. The username/password dialog example uses
java.util.concurrent.Future objects to get this done.
Feel free to user your imagination, build your simple layout XMLs to implement whatever onboarding & authentication screens your app might need. Migrating away from MAF Logon UI therefore requires you to build the authentication and onboarding screens yourself. However, with the flexibility offered by the platform you'll be able to customize these screens precisely to your needs and then integrate them into HttpC at certain parts as you wish.
Preparing for the migration¶
This section covers the preparation steps to perform before starting the migration. The actual migration guide is separated per use cases and describe how to rebuild the functionality you created using MAF Logon with HttpC.
Changes in the project setup¶
The below guide assumes your application is using SMP SDK 3.0 SP16, however most of the steps are applicable to earlier Service Packs too.
If your application is using an earlier SP and you are not sure how all this applies to your project then first upgrade your app to SP16, verify that it's working and then perform the below steps.
The first step is to remove MAF Logon libraries from the project setup. Luckily, for quite a few SPs by now, MAF Logon itself uses HttpC internally. This means that HttpC need not be added to the project as it should already be there.
Therefore, remove the
MAFLogonUI.aar from your project. If you're not using MAF Logon UI, then the latter need not be removed, of course.
After this move your project, quite obviously, will not compile. That's your starting point.
Implications on the application logic¶
The philosophy of how MAF Logon and HttpC approach the question of onboarding and authentication is so fundamentally different that there's little room for a migration guide that could give you a comprehensive before/after picture of your code.
Of course, where this is possible, these comparisons are made to make your job easier. You can find them among the various documented use cases.
Here we'd like to recommend a different approach. Instead of thinking in how to replace MAF Logon with HttpC, we recommend you think through the onboarding and authentication flows of your application again. What are your exact requirements? How would you like to obtain configuration? What kind of authentication types does your app support?
As mentioned previously, the most complex task is to recreate the UIs with the standard developer tools available for Android. Below is a table that summarizes what you'll likely have to do, depending on the authentication type your application is working with currently:
|Auth. type||Onboarding/Configuration||Authentication Challenge|
|BasicAuth||No upfront configuration is required.||Build your own username/password UI with layout XMLs and activities/fragments, as needed. Integrating with HttpC means creating a
|Mutual SSL/TLS||Consider integrating one of the certificate providers (see the related guides and API docs for the details), if they suit your needs. For simpler cases, obtaining certificates from files or the Android KeyChain can be enough.||Authentication screen is not recommended as per the HttpC Developer Guide (as the screen would block the SSL/TLS handshake process very likely resulting in a timeout).|
|SAML2||SAML2 configuration needs to be provided which is dependent on the server address. If it's fixed and thus can be hard-coded then no onboarding UI is needed. Otherwise a UI might be required to let the user enter the server coordinates.||The challenge screen is taken care of by
|OAuth2||Same as SAML2...||Same as SAML2...|
|OTP||The configuration is fixed in 99.9% of the cases and is independent of the server address. Very likely nothing else needs to be done on top of what the HttpC Developer Guide already covers.||Same as SAML2...|
The above table reflects the requirements and the possible options for the most likely scenarios. As you can see, in many cases performing onboarding can be a lot more simpler than it was with MAF Logon. In several cases, you can simply get away with a configuration screen that asks for the server address once and then saves it to a persistent storage for subsequent application startups.
The key resides in how authentication challenges are handled. The complex web-based auth. types (SAML2, OAuth2, OTP) already have their own
android.webkit.WebView-based UIs out of the box. Creating a UI for Mutual SSL/TLS is not recommended. The only authentication type that might require you to create your own user interface is BasicAuth, but it's also one of the simplest thing to do. That's why there are code examples included in the HttpC Developer Guide for this case.
You can find the - more or less - step-by-step guides in this chapter for the most important use cases. This lets you replace calls to MAF Logon libraries with those targeting SmpClient instead.
Registration with an SMP/SAPcpms server¶
See SmpClient dev guide for registration here
Check for deregistration in SmpClient dev guide here
Application settings retrieval & update¶
See the SmpClient dev guide for details here