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.

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 MAFLogonManagerNG library only then the above mentioned key building blocks are as follows:

  • Look for the use of the MAFLogonCore class (defined in the MAFLogonCore.h header). This is the centerpiece of this library. The registration is performed with its registerWithContext: method.
  • The registration data is configured in the MAFLogonCoreContext object that you pass to the registerWithContext: 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 registerWithContext: method is called, your application must have set the MAFLogonCoreDelegate to get a notification about how the registration process completed. This delegate is set using the logonCoreDelegate property of MAFLogonCore. The logic you implemented in the delegate must be invoked when the registration request is received to deal with the success or failure of the operation.
  • The persistRegistration:logonContext:error: 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:logonContext:error:. With only the DataVault library you would now use the createVault:password: method of the DataVault class.

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 MAFLogonMediator (found in the same named header). The onboarding flow can be started by the logon method. The facade also makes use various context objects and a MAFLogonNGDelegate quite similarly to how MAFLogonManagerNG works. Make sure to find the code that sets up and initializes the contexts and the delegate 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 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 DataVault using the application ID. Keep the library in private mode for now.
  2. If you find one, delete this vault. Saving the fields in it is not possible as it is encoded in a form that only the MAF Logon libraries can read.

If you insist on trying to save as many data as possible then consider leaving just the MAFLogonManagerNG library in your app for one more version. The below code can help you get the data out of it: cppNSString* applicationId = ...; // The application ID.NSString* passcode = ...; // The passcode the user just entered.MAFLogonCore* core = [[MAFLogonCore alloc] initWithApplicationId:applicationId];if ([core unlockSecureStore:passcode error:nil]) {MAFLogonContext* logonContext = [core getContext];MAFLogonRegistrationContext* registrationContext = logonContext.registrationContext;} The extracted registrationContext variable above now contains the parameters to access the server with, including credentials. You can use these to perform a registration in the background. Unfortunately, the application connection ID cannot be retrieved.

Usually, the benefit does not outweigh that the Logon library needs to be kept around in your application. The recommendation is to reset your app and restart the onboarding after the user has upgraded.

No matter how you do the migration, it is recommended to delete the data vault that MAF Logon created at the end because it probably contains more data than what is relevant to your app.

When your application is upgraded the new HttpC + DataVault based solution will likely require the user to register again, unless the above code snippet is enough to perform a registration silently in the background.

Mapping from Logon to DataVault

With MAF Logon, almost all of your secure store related operations must have taken place via the MAFLogonCore class. 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 MAFLogonCore class defines the setObjectInSecureStore:key:error:, deleteObjectFromSecureStore: and objectFromSecureStore: 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.