Skip to content

Understanding Flow Capabilities

The onboarding and restore flows handle a significant amount of complex logic for you. In this topic, we explain some of the details of this logic.

Activation

Activation is one of the onboarding steps from which you can retrieve a complete application configuration so that the flowsv2 component knows how to authenticate users. The application configuration can be retrieved either from the Discovery Service, a QR code, or managed configurations.

Managed Configurations

To retrieve the application configuration from the managed configurations, after specifying the activation option in FlowOptions as MDM_ONLY, the client code can override the following function in the child class of FlowActionHandler, to construct an instance of AppConfig from the given 'bundle'.

open fun activateFromManagedConfig(bundle: Bundle): AppConfig { ... }

The default logic of the above function will try to find the JSON string from the appConfig property of the bundle, then try to construct an AppConfig instance out of it. The schema is the same as the QR code JSON string generated using the mobile services cockpit. For example:

    "appConfig" : {
                "certificate_provider": "com.sap.cloud.mobile.foundation.authentication.SystemCertificateProvider",
                "host": "xxxx.hana.ondemand.com",
                "appID": "your.app.id",
                "auth": [
                    {
                        "type": "oauth2",
                        "config": {
                            "oauth2.clients": [
                                {
                                    "clientID": "3563f9a51-39d9-43fd-9c97-1b23bade9215",
                                    "redirectURL": "https://xxx.hana.ondemand.com",
                                    "grantType": "authorization_code"
                                }
                            ],
                            "oauth2.authorizationEndpoint": "https://xxxx.hana.ondemand.com/oauth2/api/v1/authorize",
                            "oauth2.tokenEndpoint": "https://xxx.hana.ondemand.com/oauth2/api/v1/token",
                            "oauth2.endUserUI": "https://xxxxx.hana.ondemand.com/oauth2"
                        },
                        "requireOtp": false
                    }
                ]
            }

In the preceding example, certificate_provider (the class name of your certificate provider) is optional. If certificate_provider is provided, the SAP BTP SDK for Android will try to initialize the provider at the appropriate time using JavaClass.newInstance. If your certificate provider is complex and cannot be initialized using this method, provide the instance in your FlowActionHandler before starting the onboarding flow.

For apps that use certificate authentication type, certificate_provider will be ignored. You will need to override onCertificateSslClientAuthPrepared in FlowActionHandler and specify the certificate provider there. For example:

    override fun onCertificateSslClientAuthPrepared(): SslClientAuth? {
        val sslClientAuth = SslClientAuth(ChooseCertificateProvider())
        application.sslClientAuth = sslClientAuth
        return sslClientAuth
    }

Simplified QR Code

Scanning a QR code is another common way to retrieve the application configuration. Since the application configuration may contain a significant amount of detailed information, some older devices may have difficulties when scanning the code. To handle this scenario, the SAP BTP SDK for Android version 7.1 introduces a new feature that simplifies the QR code scanning process.

The simplified QR code will be in the following format:

{
    "schema": "2.0",
    "mobileServicesHost": "testhost.sap.com",
    "customProperty": {
        "key1": "value1",
        "key2": "value2"
    }
}

After retrieving this information from the QR code, the SDK will try to retrieve the complete application configuration in JSON format from mobileServicesHost by calling the Well Known Service. The schema of the JSON is different than the normal QR code, SDK will be responsible for parsing it and returning an instance of AppConfig.

The following properties of the JSON schema are custom properties:

  • custom: Any object with custom parameters required during onboarding.
  • featureVectorPolicies: A map of available feature vector policies and their current status: the key is a string and the value is a Boolean.

Because the SDK can not know the details of these custom properties, they're all saved inside AppConfig as AppConfigCustomizedProperty, including the properties (other than mobileServicesHost) in the simplified QR code.

Passcode Policy Management

Passcode policy is one of the important security features for the mobile app. Usually in an enterprise, the administrator will define the passcode policy from the cockpit, then every onboarding user must respect this policy and create the passcode to protect the mobile app.

Here is how the onboarding and restore flows manage the passcode policy.

Create Passcode

During the onboarding flow, right after the user is authenticated, the flows component will retrieve the passcode policy from 'SAP Mobile Services', so a passcode can be created according to the policy.

The administrator can choose to disable the passcode policy, but this will be used mostly for testing apps. When the passcode policy is disabled at the server side for single-user mode apps, there will be no passcode creation steps following the authentication step. But for multiple-user mode apps, even if the passcode policy is disabled, a default one will be created, and the passcode must be created for this onboarding user.

If the passcode policy is enabled when a user is onboarded for a single-user mode app, after the passcode is created a step to enable biometrics may follow if the passcode policy also enables the 'Biometric Authentication Allowed' property. For multiple-user mode apps, there will be no biometric creation step even this property is enabled.

Passcode Retrieval Failure

During the onboarding flow, there may be occasions when the retrieval of the passcode policy fails. When this happens, the flows component will prompt the user with a dialog so that the user can choose to retry or continue. If the user clicks Retry, the API will be called again.

If the user clicks Continue in a single-user mode app, there will be no passcode creation steps and the user can invoke the change passcode flow to create the passcode. But for multiple-user mode apps, a default passcode policy will be used to create the passcode.

For the forgot passcode flow, the logic is a little different after the user clicks Continue because the user already has an effective passcode policy, so the current policy will be used to create the new passcode.

Passcode Policy Update

After the restore flow, the flows component will also call the API to retrieve the passcode policy from the server side, then try to notify the user to update the passcode, if necessary.

Whether the flows component notifies the user to update the passcode depends on whether the current passcode meets the requirement of the policy or not.

If the user unlocks the app with the passcode, the flows component will verify the passcode against the new policy. If it does not meet the requirements, a notification will be sent to the user, who can then click on the notification to change the passcode immediately, or change the passcode later without interrupting the current workflow.

When a change passcode notification is received and the user invokes the change passcode flow explicitly, the new passcode policy will be used. After the passcode is updated, the user will not be forced to change passcode for the next login.

However, if the user forgets to change the passcode, then the next time the app is unlocked, the change passcode steps will automatically be appended after the Sign-In screen, forcing the user to change the passcode.

For single-user mode apps, if the user unlocks the app using their fingerprint, there will be no notification to update the passcode. But if the current passcode is going to expire in 3 hours, there will be a notification. After the passcode expires, the change passcode steps will also automatically be appended after the Sign-In screen.

Passcode Policy Downgrade

There may also be cases where the administrator chooses to downgrade the passcode policy at the server side, for example, the enabled passcode policy may be disabled. In this case, the change will affect the newly onboarding users. For a user who was already onboarded with the enabled passcode policy, there is no opportunity for the user to remove the passcode on the secure store.

Usage data collection and crash report upload both require user consent to be enabled. This is handled by UsageService and CrashService, respectively.

When the onboarding flow starts, the flows component will automatically insert the corresponding user consent screen for the service that was initialized using SDKInitializer. The service will only be started when the user clicks the Allow button, and the user consent status will also be saved to the user's secure store.

When the user next unlocks the app, the consent status will be retrieved from the database, the corresponding service will be started automatically by the flows component if the user provided consent during the onboarding flow, and the consent status will also be notified to the client code with the onConsentStatusChange callback function of FlowStateListener.

The client code can also review the user consent status at a later time and change the consent if necessary. When revoking user consent, the client code may not need to provide the user interface to allow the user to click the Disagree button, but you must ensure that the updated user consent status is written back into the user secure database using the updateConsentStatus API in UserSecureStoreDelegate.

The app generated by the SAP BTP SDK Wizard for Android provides detailed sample code for this topic.


Last update: February 29, 2024