Configuration
Add the Android SDK to your project
If you are using Gradle, you can add the library with the following dependency:
Gradle dependency
Instantiating the Android SDK
All functions of the Android SDK are available from a single facade, the OneginiClient
. The OneginiClient
is a singleton that has to be set up once with the OneginiClientBuilder
class. It can can be fetched via a OneginiClient.getInstance()
method afterwards.
Note
The Application (not Activity) context must be used to instantiate the OneginiClient
.
Client instantiation
The first method that must be called on OneginiClient
after application startup is OneginiClient#start()
. This method is responsible for asynchronous initialization of the Android SDK. During this process, the Android SDK can return errors, for example if the device is using a deprecated Android version or when the app version is outdated. The method expects a OneginiInitializationHandler
to return initialization results.
Client initialization
Configuration model
Configuration properties should be provided to the Android SDK via an implementation of the OneginiClientConfigModel
interface. The implementation can be provided in two ways:
-
If the Mobile SDK Configurator script was used to apply configuration and certificate pinning to your app project, the
OneginiClientConfigModel
implementation is added to the app's main directory. In such case, the Android SDK uses reflection and theContext#getPackageName()
method to search for a class called{your.application.package}.OneginiConfigModel
that implements theOneginiClientConfigModel
interface. If the proper class can't be found, the Android SDK throws aOneginiConfigNotFoundException
exception. -
To create the implementation manually, or to move the generated implementation to a different (sub)package, then you can explicitly provide the config using the
OneginiClientBuilder#setConfigModel()
method.
Code example OneginiClientConfigModel implementation
Certificate pinning
The Android SDK provides functionality to pin your servers certificate. If you pin the servers certificate itself, you will need to deploy a new version of the application when you change the servers certificate. We recommend using the intermediate certificate of the Certificate Authority used to get the server certificate (the second level in the certificate chain). This gives you the option to renew the server certificate without having to deploy a new version of the application.
Export the certificate
You can use Firefox to export the certificate. Click on the lock of the SSL website. Choose: more information. In the security tab, press View certificate, then go to the details tab. And there you can choose which certificate in the chain you wish to export.
Creating a keystore
In order to create a keystore you need a Java JDK installed to get a keytool. And for Android you need Bouncy Castle 1.46 (newer versions of Bouncy Castle create a keystore with a different header, which is not accepted by Android).
http://mvnrepository.com/artifact/org.bouncycastle/bcprov-jdk15on/1.46
Create keystore
Add the keystore to the project
The keystore has to be added to the raw directory of your Android project. And your configuration needs to provide the keystore within the configuration. For example:
Keystore configuration
Keystore tampering protection
As the keystore is stored on the file system of the device, theoretically it is possible to tamper it. This is possible if the device is rooted and some malicious application is installed. To prevent a tampered keystore, an SHA 256 hash of the keystore has to be provided by the application. It is recommended to have the hash hardcoded and not in a separate property file or any other file on the file system.
Calculating the keystore hash
Example code of hash in config model
Providing your own authentication request handlers and callbacks
When the IDAAS-core returns oAuth 2.0 refresh tokens, the user needs to provide a PIN or a fingerprint to store those credentials. For this, you need to provide your own authentication request handlers using OneginiClientBuilder
methods. The OneginiCreatePinRequestHandler
and OneginiPinAuthenticationRequestHandler
are required to perform basic registration and authentication with PIN. Other handlers are optional and should be provided only when the app uses functionalities like fingerprint or mobile authentication. See Registration/Authentication request handlers for more information.
Other OneginiClient settings
OneginiClientBuilder
exposes additional methods to customize OneginiClient
behavior:
shouldStoreCookies(final boolean shouldStoreCookies)
method can be used to specify if the HTTP client should store cookies between requests. The default value is TRUE.setHttpConnectTimeout(final int timeout)
method can be used to specify the HTTP client's connection timeout (in milliseconds). Default value is60000
(60s).setHttpReadTimeout(final int timeout)
method can be used to specify the HTTP client's read timeout (in milliseconds). Default value is60000
(60s).setDeviceConfigCacheDurationSeconds(final long cacheDurationSeconds)
method can be used to specify device configuration cache duration (in seconds). Default value is300
(5 minutes). Passing0
will disable the cache.
Sample initialization call