Lock and Wipe Configuration in SAP BTP SDK for iOS¶
This feature enables the SDK to take automated actions when thresholds are reached, protecting sensitive data from unauthorized access or device misuse. The Lock and Wipe support in the iOS SDK provides a comprehensive mechanism to secure user data in alignment with SAP Mobile Services policies, helping organizations enforce stringent security protocols in a user-friendly manner.
There are two ways to enable Lock and Wipe from mobile services cockpit:
Administration and Enforcement¶
Mobile Settings Exchange¶
Administrators can configure Lock and Wipe policies directly in mobile services cockpit, and the SDK will adhere to these settings.
The Lock and Wipe Policy can be enabled and configured in the Mobile Settings Exchange within SAP Mobile Services. Follow the guidelines below to configure the settings:
Configuration Options¶
-
Offline Days Before Lock
-
Offline Days Before Wipe
Configuration Scenarios¶
1. Lock and Wipe¶
-
Enable the Lock and Wipe Policy.
-
Specify appropriate values for:
-
Offline Days Before Lock
-
Offline Days Before Wipe
-
-
Important: Ensure that the value for Offline Days Before Wipe is greater than the value for Offline Days Before Lock.
2. Lock Only¶
- Set the value for Offline Days Before Wipe to 0.
3. Wipe Only¶
- Set the value for Offline Days Before Lock to 0.
Direct Admin Actions¶
Admins can also initiate user-specific lock or wipe actions through the mobile services cockpit, triggering these policies instantly.
Enable the lock or wipe radio buttons in the User Registrations section.
Trigger Scenarios¶
Server-Initiated Lock or Wipe¶
If mobile services cockpit determines a policy threshold has been met (based on activity or administrative actions), it will respond with an HTTP 403 and an x-message-code header.
TRAFFIC_REG_WIPED¶
User’s registration is wiped, triggering the app to cancel restore and enforce a full reset.
TRAFFIC_REG_LOCKED¶
User’s registration is locked, requiring re-authentication to continue.
App-Initiated Check¶
For offline scenarios, the SDK also checks lock and wipe conditions at app launch to ensure thresholds are enforced even without a direct server connection.
Note¶
If you use SAP BTP SDK Assistant for iOS from version 24.12.0, the required code described above is automatically generated as part of the app creation process.
To Configure Lock and Wipe Functionality, Follow Below Steps¶
User Event Callback for Lock or Wipe Events¶
Update AppDelegate.swift to register a LockAndWipeEventObserver to LockAndWipeManager for handling custom behaviors when Lock or Wipe policies are met. Apps created with SAP BTP SDK Assistant for iOS 24.12+ will include auto-generated code for this feature.
Registering the Lock and Wipe Observer¶
Add the following code to register the observer to the LockAndWipeManager
// Registers the Observer to LockAndWipeManager
extension AppDelegate {
func registerLockAndWipeObserver() {
AppLockAndWipeEventObserver.shared.register()
}
}
Application Launch Setup¶
Invoke the registerLockAndWipeObserver from func afterOnboard() to enable custom lock and wipe callbacks in an assistant-generated application. If you don't use afterOnboard(), call this method once user onboarding or restore completes successfully.
func afterOnboard() {
guard let _ = sessionManager.onboardingSession else {
logger.debug("Onboarding Session Not Found")
return
}
...
registerLockAndWipeObserver()
...
}
Adding Precondition Steps¶
To ensure that the lock and wipe observer can capture responses during the authentication step, you need to add the SAPcpmsUserLockandWipeConfigurationStep before the AuthenticationStep in both the onboarding and restoring steps. This ensures that observers are registered and ready to capture the responses received from the server.
public var onboardingSteps: [OnboardingStep] {
return [
...
SAPcpmsUserLockandWipeConfigurationStep(),
AuthenticationStep(), // Supports various authentication types
...
]
}
public var restoringSteps: [OnboardingStep] {
return [
...
SAPcpmsUserLockandWipeConfigurationStep(),
AuthenticationStep(), // Supports various authentication types
...
]
}
Custom Lock and Wipe Operations¶
Create a new observer class to implement any custom handling for the lock and wipe events. This class will be registered to LockAndWipeManager in the AppDelegate.swift:
import SAPCommon
import SAPFioriFlows
import SAPFoundation
public class LockAndWipeEventObserver: LockAndWipeEventObserving {
private let logger = Logger.shared(named: "AppLockAndWipeEventObserver")
public static let shared: LockAndWipeEventObserver = LockAndWipeEventObserver()
public init() {
// Empty Intializer
}
public func register() {
// Registering the Observer to LockAndWipeManager
LockAndWipeManager.shared.register(self)
}
public func willLock() async {
// Called before locking the application. Override to perform any necessary cleanup or confirmation steps.
}
public func willWipe() async {
// Called before wiping the application. Override to perform any necessary cleanup or confirmation steps.
}
public func didLock() async {
// // Called after locking the application. Override to perform any necessary cleanup or confirmation steps.
}
public func didWipe() async {
// // Called after wiping the application. Override to perform any necessary cleanup or confirmation steps.
self.resetOnboardingSessionManager()
}
private func resetOnboardingSessionManager() {
// Pre-configured steps for handling these cases are included in the generated code from version 24.12.0.
let sessionManagerState = OnboardingSessionManager.shared.state
switch sessionManagerState {
case .initial, .inFlow, .inBackgroundProcessing:
// Avoid calling `removeSession` during onboarding or restore flows,
// as these scenarios are already handled by the OnboardingErrorHandler.
case .opened(_), .locked(_):
// For states where the session is opened or locked,
// trigger a reset via the OnboardingErrorHandler to clear the session.
}
}
}
Warning
Methods in LockAndWipeEventObserving are declared as async and must be implemented as asynchronous methods. While Swift permits synchronous implementations to meet async protocol requirements, this approach can cause unexpected behavior and subtle bugs. Therefore, it is unsupported.
Handling Lock and Wipe Errors¶
SAPcpmsLockandWipeObserver checks for the x-message-code response header which will be captured from the response received from the server if lock or wipe event is met. If the app is locked or wiped, then any request for this SAPURLSession instance will be canceled and an error is propagated to the Application Layer.
// When the app receives a `403` response with `x-message-code: TRAFFIC_REG_LOCKED`
// initiate a logout due to lock condition.
completionHandler(.cancel(LockWipePolicyError.trafficLocked))
// When the app receives a `403` response with `x-message-code: TRAFFIC_REG_WIPED`
// initiate a full reset due to wipe condition.
completionHandler(.cancel(LockWipePolicyError.trafficWiped))
If the device is offline, check for lock and wipe conditions at app launch to ensure thresholds are enforced even without a direct server connection. The user won't be able to use the application. The user must reconnect to the network to re-authenticate and continue using the app.
completionHandler(.failed(SAPcpmsLockWipePolicyError.lockDisconnectedPeriod)) // For Lock
completionHandler(.failed(SAPcpmsLockWipePolicyError.wipeDisconnectedPeriod)) // For Wipe
In case of a lock or wipe, specific errors are thrown which can be intercepted in the onboardingController(_:didFail:with:completionHandler:) method of OnboardingControllerDelegate:
func onboardingController(_ controller: OnboardingControlling, didFail flow: OnboardingFlow, with error: Error, completionHandler: @escaping (OnboardingErrorDisposition) -> Void) {
switch flow.flowType {
case .restore:
restoreFailed(with: error, controller: controller, onboardingID: flow.context.onboardingID, completionHandler: completionHandler)
...
}
}
func restoreFailed(with error: Error, controller: OnboardingControlling, onboardingID: UUID?, completionHandler: @escaping (OnboardingErrorDisposition) -> Void) {
switch error {
// Pre-configured steps for handling these cases are included in the generated code from version 24.12.0.
case LockWipePolicyError.trafficLocked:
// This error occurs when the server responds with a lock policy.
// The generated code automatically handles the lock condition, prompting the user to re-authenticate.
case LockWipePolicyError.trafficWiped:
// This error occurs when the server responds with a Wipe policy.
// The generated code performs a full app reset to securely clear user data.
case SAPcpmsLockWipePolicyError.wipeDisconnectedPeriod:
// This error occurs when the app detects a wipe condition being met while the device is offline.
// The generated code displays an alert notifying the user about the wipe action and halts further operations.
case SAPcpmsLockWipePolicyError.lockDisconnectedPeriod:
// This error occurs when the app detects a satisfied lock condition being met while the device is offline.
// The generated code shows an alert to the user about the lock condition and prevents further actions until resolved.
}
}