Skip to content

Migration Guide - MAF Logon to DataVault

Here you can find the comprehensive guide on how to migrate applications based on the MAF Logon framework to the DataVault library. 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.

This material builds on top of the DataVault and HttpConversation developer guides. If you are not familiar with these libraries make sure to read the related guides first.

Find below the list of topics that are covered by this guide:

  1. The traditional Logon flow...
    1. ..in MAF Logon Core
    2. ..in MAF Logon UI
  2. Data migration
  3. Mapping from Logon to DataVault

The traditional Logon flow...

Using the MAF Logon framework, the onboarding process looked roughly as follows:

  1. Prepare for the registration by setting up the Logon context, configuring the SMP server coordinates, authentication mechanisms, etc..
  2. Perform the registration using the corresponding method of MAF Logon.
  3. Get a notification in a callback about the completion of the registration.
  4. Ask the user to enter the passcode if the policy acquired as part of the registration requires one.
  5. With a dedicated MAF Logon method, persist the registration. This creates the secure storage underneath which saves the registration data. The passcode created in the previous step is used to create the store.

After the above steps the application onboarding is complete in MAF Logon terms and the OData endpoint can be accessed.

The flow is pretty much similar even with MAF Logon out of the picture:

  1. Prepare for the registration by configuring a HttpConversationManager that is capable of handling any authentication challenges the SMP or SAPcpms server might present.
  2. Fire the registration request against the /odata/applications/<api version>/<application ID>/Connections endpoint. The response contains the application configuration which also includes the secure store policy.

This step can be done directly using the configured conversation manager, as the MAF Logon to HttpC developer guide elaborates. Alternatively, you can use the new ODataOnlineCore library (which also uses HttpC underneath). Nevertheless, this guide does not concentrate on the registration part of the onboarding process. Instead it focuses on the secure storage related aspects of MAF Logon. 1. Parse the policy into a DVPasswordPolicy object using the output of the previous step. 1. Ask the user to enter a password, if the policy requires. 1. Create a new data vault using the password and start saving whatever data you would want into it.

Internally, the MAF Logon framework already uses the DataVault library under its secure storage facilities. Most of the things on the MAF Logon API are therefore in 1-1 correspondence with the functionality provided by DataVault.

The key thing to understand is that all of these steps are now in your hands as an application developer. By using HttpC and DataVault directly, you can alter the onboarding process and tailor it to the needs of your application. For example, you can ignore the server configured policy and use your own in step 4, if you like.

Consequently, MAF Logon merely acts as an orchestrator of the above process. With HttpC + DataVault, the application becomes the orchestrator instead.

The following chapters help you pinpoint the key locations in your app where you used MAF Logon to implement the above steps. Read on to the next subchapters for the details.

..in MAF Logon Core

If your application uses the MAFLogonCore library only then the above mentioned key building blocks are as follows:

  • Look for the use of the com.sap.maf.tools.logon.core.LogonCore class. This is the centerpiece of this library. The registration is performed with its register(LogonCoreContext) method.
  • The registration data is configured in the LogonCoreContext object that you pass to the register() method. This stores the server coordinates and certain authentication parameters. Modify this mechanism so that it configures a HttpConversationManager instance instead (check the HttpC Developer Guide for an elaborate material on the subject).
  • Before the register() method is called, your application must have set the LogonCoreListener to get a notification about how the registration process completed. This listener is set using the setLogonCoreListener() method of LogonCore. The logic you implemented in the listener must be invoked when the registration request is received to deal with the success or failure of the operation.
  • The persistRegistration() method is responsible for completing the registration and creating the secure store. This is the point where you can start integrating the DataVault-based solution.

Up until the point the registration request is received, follow the guidance of the MAF Logon to HttpC migration guide. The creation of a DataVault may begin after the registration has completed.

The DataVault Developer Guide describes recommendations on how to build the UI flows properly around this library, including one that can be used to create a new data vault. Implement and then integrate this UI after the registration request is received. When the user enters the passcode, use it to create a new DataVault instance.

Initializing a vault therefore consists of nothing more but the passcode creation UI and the actual vault creation. MAF LogonCore handled the latter step using persistRegistration(). With only the DataVault library you would now use the createVault() method of the appropriate DataVault subclass.

..in MAF Logon UI

MAF Logon UI is responsible for enriching the MAF LogonCore experience with the onboarding user interfaces. It offers prebuilt screens for passcode management, unlock screens, onboarding, etc..

The central class of MAF Logon UI is com.sap.maf.tools.logon.logonui.api.LogonUIFacade. The onboarding flow can be started by the logon() method. The facade also makes use of a LogonContext and a LogonListener quite similarly to how LogonCore works. Make sure to find the code that sets up and initializes the context and the listener and then follow the guidance of the previous chapter.

Data migration

The MAF Logon framework managed the lifecycle of the DataVault completely. It also created a single vault for a particular registration. As MAF Logon is based on singletons, this means you couldn't have had more than one secure store in your app.

The private vault underneath MAF LogonCore uses the application ID as the vault identifier. When migrating your app, we do not recommend to keep this vault around. Instead, perform a migration as follows:

  1. When the user enters the passcode for the first time, look for a PrivateDataVault using the application ID.
  2. If you find one, open and unlock it with the passcode and extract the fields you would like to keep. If you don't want to keep any data, simply omit this step. Some of the keys that you might find useful are:
    • "VK_HOST_NAME": The server host name
    • "VK_HOST_PORT": The server port (string representation of a java.lang.Integer)
    • "VK_ISHTTPS": Whether the protocol to use is HTTPS (string representation of a java.lang.Boolean)
    • "VK_ENDPOINT_USER": The server user name (used for BasicAuth)
    • "VK_ENDPOINT_PASSWORD": The server password (belonging to the user name)
    • "VK_CONNECTION_ID": The Application Connection ID that can be used in the SMP REST API calls. Saving this value keeps the registration around.

Call DataVault.getString() with the above keys on the opened data vault to get the corresponding values. If you know the server coordinates already then you need to save only the user credentials and the connection ID. 1. Close and delete this vault. 1. Create your own DataVault instance that is secured by the same passcode and save the migrated fields there.

It is recommended to delete the data vault that MAF Logon created because it probably contains more data than what is relevant to your app.

With this logic in place the next version of your application will be able to seamlessly take over the secured data that MAF Logon left behind after an application upgrade.

Mapping from Logon to DataVault

With MAF Logon, almost all of your secure store related operations must have taken place via the LogonCore singleton. As this managed the lifecycle of your secure store already, the only thing to migrate is the code that accessed the data in the store.

The LogonCore class defines the addObjectToStore() and getObjectFromStore()/getByteObjectFromStore() methods which are effectively the setters and getters you know from the DataVault API. Simply reroute the calls away from these methods to your DataVault instance and its respective data accessors.