Security-relevant configuration
There are several security-related configuration possibilities when integrating the Unblu Android mobile SDK. Take the following points into consideration to ensure the SDK is configured in the most secure way without restricting the availability of Unblu features.
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 theUnbluClientConfiguration.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:
-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
.
See also
-
For more information on the topics discussed in this article, refer to Unblu Android mobile SDK reference.
-
For information on logging in the Unblu Android mobile SDK, refer to Logging and error handling^.
-
For general configuration information, refer to Code setup and initialization^.