Security-relevant configuration

Defining accessible URLs

By default, only the Unblu base URL passed to the client in the UnbluClientConfiguration during initialization (and its subroutes) are accessible from the SDK’s internal WebView.

To allow access to other URLs, the Unblu Android mobile SDK provides two different mechanisms, an internal whitelist and an external file handler.

Internal whitelist

The URLs in the internal pattern whitelist are those used internally by your Unblu-enabled application.

If your application needs to grant the WebView access to other URLs—when redirecting to a different domain, say, or retrieving external resources such as fonts to display in the Unblu WebView—you can provide a list of regular expressions matching those URLs by calling UnbluClientConfiguration.Builder.setInternalUrlPatternWhitelist.

Any URL called, including iframes, is checked against the whitelist before sending the request to the Collaboration Server.

If you only need the Unblu base URL, there’s no need to configure the internal pattern whitelist.

If you use Google fonts in your mobile app, bear in mind that https://fonts.googleapis.com redirects to https://fonts.gstatic.com. You must include a pattern for the latter domain in the internal whitelist.

External link handler

The Unblu chat UI distinguishes different types of link:

URLs such as https://<domain>
mailto:<email_address>
tel:<phone_number>

These links are clickable by agents or visitors. Doing so opens another application, such as a browser or an email client.

If you want to specify URL patterns that may be accessed by having your application open another application, you can do so in the UnbluClientConfiguration you use when you initialize the client instance.

When you create an UnbluClientConfiguration, you must provide an object of a class that implements the UnbluExternalLinkHandler interface. The default implementation is UnbluPatternMatchingExternalLinkHandler, which has two constructors:

UnbluPatternMatchingExternalLinkHandler() matches the patterns ^"https://"., ^"mailto://"., and ^"tel:".*.
UnbluPatternMatchingExternalLinkHandler(List<java.util.regex.Pattern>) lets you pass in list of regular expression patterns to match URLs against. this allows you to restrict links to those within your organization’s domains, for example.

Download handler

During a conversation, participants may exchange files. These files can be downloaded and must then be stored somewhere on the user’s device. How the SDK handles files is determined by an instance that implements the UnbluDownloadHandler interface. You must set the instance on the UnbluClientConfiguration used to initialize the UnbluClient instance.

By default, files are stored in the device’s external storage. If this is sufficient for your app’s needs, you can obtain an instance of the default implementation by calling the UnbluDownloadHandler.createExternalStorageDownloadHandler method.
For security reasons, you may prefer to ensure that files are only accessible from within your app and that the app manages downloaded files itself. In that, you must provide the SDK with a custom implementation of the UnbluDownloadHandler interface by calling the UnbluClientConfiguration.Builder.setUnbluDownloadHandler method.

When you’ve done that, downloads initiated by a user trigger your custom download handler. It must handle the download itself and store the file somewhere within your app.

Data storage

The Unblu View has access to the contents of the data/data/<com.package.name>/app_webview directory. However, the mobile SDK doesn’t store any sensitive data in this location, and neither should your app. If you need the mobile SDK to store sensitive data, your app must provide a custom store.

Encrypting stored preferences

The SDK needs to store some internal values within your app. This is necessary so the Collaboration Server can identify the user’s device after restarting the app.

By default, Unblu stores these values in a shared preference file in private mode. Often this is secure enough because normally, only the app itself has access to this data. Sometimes, though, you may wish to encrypt the values before storing them. To do so, provide the SDK with a custom implementation of the UnbluPreferencesStorage interface via UnbluClientConfiguration.Builder.setPreferencesStorage. The SDK will then use this storage when it needs to read from or write to the shared preferences file.

Log stripping

The logging^ section of the Logging and error handling article describes how to configure the log level and the values logged in a log statement.

If you prefer, you can remove log statements from the binary entirely by adapting the app’s proguard-rules.pro file. The SDK already defines the following rules to strip out DEBUG and VERBOSE level logs. You can do the same for all other log levels, too:

Listing 1. ProGuard rules to remove different log level statements from the app binary

-assumenosideeffects class com.unblu.sdk.core.internal.utils.Logger {
    public static *** d(...); (1)
    public static *** v(...); (2)
    public static *** i(...); (3)
    public static *** w(...); (4)
    public static *** e(...); (5)
}

1	Removes `DEBUG` log statements; stripped out by default
2	Removes `VERBOSE` log statements; stripped out by default
3	Add rule to remove `INFO` log statements
4	Add rule to remove `WARN` log statements
5	Add rule to remove `ERROR` log statements

Certificate pinning

From Android 7.0 Nougat (API 24) on, it’s possible to use certificate pinning within your app’s network security configuration file. This may be done for the whole app including all WebViews, so there’s no need for the SDK part to include any configuration for it.

For more information on certificate pinning in Android, refer to the Android documentation.

mTLS support

The Unblu Android mobile SDK supports mutual TLS (mTLS), a protocol that enhances security by requiring both the client and the server to authenticate each other before establishing a connection.

The implementation of mTLS in the SDK library leverages the WebViewClient#onReceivedClientCertRequest method from the Android SDK. This method is a callback that’s invoked when the server requests that the client present a certificate for mTLS authentication. For detailed information on how the method is used within the Android ecosystem, refer to the official Android documentation.

The SDK provides the UnbluClientCertRequestData class. The class lets you specify a private key and its associated certificate chain, both of which are required for the mTLS authentication process. You provide your UnbluClientCertRequestData by calling UnbluClientConfiguration.Builder.setUnbluClientCertRequestData.