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:
- The traditional Logon flow...
- Data migration
- Mapping from Logon to DataVault
The traditional Logon flow...¶
Using the MAF Logon framework, the onboarding process looked roughly as follows:
- Prepare for the registration by setting up the Logon context, configuring the SMP server coordinates, authentication mechanisms, etc..
- Perform the registration using the corresponding method of MAF Logon.
- Get a notification in a callback about the completion of the registration.
- Ask the user to enter the passcode if the policy acquired as part of the registration requires one.
- 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:
- Prepare for the registration by configuring a
HttpConversationManagerthat is capable of handling any authentication challenges the SMP or SAPcpms server might present.
- Fire the registration request against the
/odata/applications/<api version>/<application ID>/Connectionsendpoint. 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
ODataOnlineCorelibrary (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
DVPasswordPolicyobject 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
DataVaultlibrary 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.LogonCoreclass. This is the centerpiece of this library. The registration is performed with its
- The registration data is configured in the
LogonCoreContextobject that you pass to the
register()method. This stores the server coordinates and certain authentication parameters. Modify this mechanism so that it configures a
HttpConversationManagerinstance 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
LogonCoreListenerto get a notification about how the registration process completed. This listener is set using the
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.
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
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
..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.
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:
- When the user enters the passcode for the first time, look for a
PrivateDataVaultusing the application ID.
- 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
"VK_ISHTTPS": Whether the protocol to use is HTTPS (string representation of a
"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.
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.
LogonCore class defines the
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.