StoreManager

public class StoreManager : FUIPasscodeValidationDelegate, FUIPasscodeControllerDelegate

StoreManagerStep

StoreManagerStep is responsible to create, open or remove the secure store assigned to an onboarding session. It has several customization options which can be used alone or together to achieve the required functionality.

As a basic behavior the StoreManagerStep creates a new secure in the onboarding flow, opens it in the restoring flow or removes it as part of the reset flow. By default a store is assign to an onboarding session using the onboardingID. For the detailed description of the flows see Onboarding overview.

Customization options

• Using different secure storage implementations with the step: StoreManagerStep delegates the appropriate kind of store management to an instance of PersistentStoreManaging. This way the same StoreManagerStep class can use different kind of secure stores without the necessity of subclassing or replacing the whole step in the flow. The following store managers are available:
  • SecureKeyValueStoreManager
  • KeychainStoreManager
• No-passcode mode: using the StoreManagerStep in this mode it won’t present any passcode related screens and won’t pass any passcode to the PersistentStoreManaging instance. This mode activated when there is no available FUIPasscodePolicy and the defaultPasscodePolicy is set to nil on the Step instance.
• Use a custom UUID instead of the onboardingID: the onboardingID is used to differentiate the stores (using in the name of the store) and all related stored information (used in the key). Setting the storeID property on the instance will override the onboardingID. This can be used to share a store among different onboarding sessions (see sharing).
• Pre-initialized secure store usage during onboarding: in this mode the StoreManagerStep will perform a restore in onboard if the store already exists. It will run onboard if the store doesn’t exists. Use the runRestoreIfStoreExists property to activate this behavior.
• Alternate onboardingInfoKey usage: as with other onboarding steps it is possible to change the keys which are used to access information in the info field of the OnboardingContext when the automatic mode is used.

Sharing

The StoreManagerStep can be configured to support shared stores. For the description of configuration options see Customization options We can distinguish the stores by the number of users: a ‘private’ store is assigned and used by only on ‘onboarding session’ while a ‘shared’ store used among different ‘onboarding sessions’.

A ‘shared’ store can be ‘locally’ shared so it belongs to a particular application and can be shared among applications. When sharing among applications works only with the KeychainStoreManager which uses ‘keychain sharing’.

It is also possible to use more stores in an ‘onboarding session’. For example when the basic configuration data is stored in a shared store while the user specific information stored in ‘private’ store.

When more stores are used at least the following configuration options should be changed:

• Custom UUID for the store for the shared store(s)
• alternate onboardingInfoKey for one of the stores. For example if SAPcpmsSettingsDownloadStep is used you have to decide which store should use the FUIPasscodePolicy downloaded from the server.
• Pre-initialized mode for the shared store: if the StoreManagerStep should use the already existing shared store during onboarding. For exampel the connection
• When more StoreManagerSteps are used in an onboarding session wrap the StoreManagerStep (and the steps which have to use that store) into a StoreSelectoreStep.

Handles all the available operations on the application’s credentialstore:

• create store
• open store
• remove store
• change encryption of store The store instance should be an implementation of the PersistentStoreManaging protocol StoreManager uses multiple screens and passcode/TouchID/FaceID/OpticID functionalities from SAPFiori.

A StoreManager instance is initialized in StoreManagerStep during onboarding with the required parameters in the StoreManager initializer, which then starts a createStore, which throws FUIPasscodeCreateController from SAPFiori. If the device supports a biometric identifier, such as Touch ID or Face ID or Optic ID and the downloaded passcode policy also allows it, the Touch ID / Face ID / Optic ID screen displays after the passcode creation screens. The user can decide whether or not to use biometrics in the application. When setting the passcode, certain information is stored in the keychain under the application’s default accessGroup. If the developer sets an accessGroup for the StoreManager, the accessGroup must be set, and in every case a storeManager is instantiated later.

There is one exception where the passcode create screen is not shown while onboarding: If the developer does not set the defaultPasscodepolicy on StoreManagerStep, AND the policies are not assigned to the application on the server. Because of this, the passcode is turned off for the application and does not ask for a passcode when it opens later. This is less secure, and is not recommended. Note: The defaultPasscodePolicy is set to nil by default. If the defaultPasscodePolicy is set to the developers own default passcode policy, that becomes the requirement for entering the passcode whether or not the passcode policies assigned to the application on the server.

In the restore case, the StoreManagerStep calls the StoreManager’s openStore function which, if a passcode was previously set, presents a FUIPasscodeInputController from SAPFiori. If the user enters an incorrect passcode, the retry limit decrements. If the retry limit reaches zero, the store is locked and all information is lost. The user must onboard again, after resetting the application. If the entered passcode is correct, then the restore flow starts with the previously defined steps.

PasscodePolicyApplyStep is another step that can call changePasscodePolicy on StoreManager: During the restore flow, if the actual settings are downloaded from the server and the passcode policy changes, PasscodePolicyApplyStep calls the changePasscodePolicy(to newPolicy:completionHandler:) on StoreManager, which triggers a passcode change. This change is mandatory and cannot be cancelled. The change is triggered in every case where the server administrator sets a policy that is either weaker or stronger. StoreManager uses a customized FUIFeedbackScreen from SAPFiori to inform the user of any restrictions or additional possibilities regarding setting the passcode policy. The reason for the passcode change is described on that presented screen. The passcode change flow starts after the user taps the ‘Continue’ button.

Possible passcode change flows:

• No passcode -> passcode ( Turn on passcode, so passcode creation flow without the option to set Face/Touch/Optic ID.)
• No passcode -> passcode with Touch/Face/Optic ID (Turn on passcode with biometric ID, so passcode creation flow with the option to enable Face/Touch/Optic ID.)
• Passcode -> Passcode (Passcode change flow, the user has to enter the current passcode again, then set the new passcode and confirm it.)
• Passcode -> No passcode (Turn off passcode, the user will be notified about the change, has nothing to do. The passcode will be turned off.)
• Passcode -> Passcode with Touch/Face/Optic ID (Starting the automatic change flow will be supported in a later release, currently the Touch/Face/Optic ID availability will be added to the ‘availableChangePasscodeOptions’, so manually can be turned on if there is an application screen for setting these options.)
• Passcode with Touch/Face/Optic ID -> Passcode (Turn off Touch/Face/Optic ID, the user will be notified about the restriction and can not use the biometric ID from that point to unlock the application.)
• Passcode with Touch/Face/Optic ID -> No passcode (Turn off passcode, the user will be notified about the change, has nothing to do. The passcode and Touch/Face/Optic ID will be turned off.)

Developers can provide a screen similar to Settings, where the user can change their own passcode depending on passcode policy and device capabilities: The ‘availablePasscodeActions’ returns an array, which contains the passcode actions which can be performed on StoreManager’s store. This list contains elements depending on passcode policy and device capabilities. After checking the availablePasscodeActions, the developer can call the performPasscodeAction(_ action:completionHandler:) function with the correct PasscodeAction. In this case one of the possible passcode change flows starts, the only difference is that a notification screen does not display by default.