Getting started
Introduction
This topic guide describes how you should get started with the SDK. It outlines how the API is set up, how the SDK generally works and what the requirements are.
We first advice you to read the App developer quickstart before reading this topic guide.
General setup of the Android SDK
OneginiClient
The main facade of the SDK is the OneginiClient
. This class exposes the other Onegini client objects (UserClient
and DeviceClient
) that you can access. The
OneginiClient
is a singleton of which you can only construct a single instance using the OneginiClientBuilder
class. The other clients that can be accessed
through the OneginiClient
are:
UserClient
- only contains user related functionalityDeviceClient
- only contains device related functionality
Thread safety
All methods that you call on the SDK must be performed on the main thread of your mobile application. The SDK will not enforce this, hence you might expect strange behaviour if you do not execute the methods on the main thread. Internally the SDK will use multiple threads to make sure it does not block the main thread. You as a developer only have to make sure that you execute the SDK methods from the main thread.
Delegating control from the app to the SDK and vice versa
To utilize the functionality that the SDK provides you must integrate it into your application. The functionality that the SDK provides sometimes require interaction with the end-user. The SDK itself does not contain any UI but will request you to implement specific actions for your end-users.
The general setup is that you must trigger a functionality in the SDK by calling one of it's methods. Let's take user authentication as an example.
In order to start the user authentication you must call the UserClient.authenticateUser()
method. Below is an example of this method call (taken from the
Android example app):
The second parameter that you must provide is a handler. This handler is responsible for giving you the feedback whether the result of the triggered action
was successful or not. However as a part of the authentication functionality a few things happen. Depending on the authentication method that is preferred
for a user the user will be requested to enter his/her PIN or perform fingerprint authentication. This action is triggered by the SDK. The SDK provides special
RequestHandlers
for this that need to be implemented by you.
A RequestHandler
is a class that contains methods to hand over control from the SDK to your application. When the preferred method of authentication for a
user is PIN authentication the startAuthentication
method of the class that implements the OneginiPinAuthenticationRequestHandler
interface is called. After
the end-user has entered his/her PIN, the PIN needs to be provided to the SDK to continue the authentication flow. The startAuthentication
method contains a
callback object to submit the PIN to the SDK.
Since the SDK is a stateful library, you should not call asynchronous methods (like authenticateUser()
or start()
) in parallel. In particular, if you will
try to call the same method multiple times while the first call has not finished yet, you can receive an ACTION_ALREADY_IN_PROGRESS
error.
Error handling
Interaction with the SDK can result in errors. Please check out our Error handling topic guide for more details on error handling.
SDK Requirements
The SDK supports apps running on API level 23+ (Android Marshmallow and newer), so make sure that your project also sets it's minimum API level to 23 or higher.
Reasons why older platforms are not supported
The core functionalities of the SDK use hardware-backed crypto services (Android Keystore) that were not fully available on Android before the API 23. Fortunately, the number of devices with API lower than 23 is relatively small and it's constantly decreasing.
Supporting many different API versions is getting more and more complex over time. Different versions of Android's API have different bugs, including security vulnerabilities. Some of the vulnerabilities force us to protect the app with additional workarounds, that significantly increase development time and in some cases, it also slows down the performance of an app. Other vulnerabilities can't be solved at all by the SDK.
Third party libraries
The SDK depends on a number of third party libraries. The SDK does not contain the libraries it depends on but we clearly describe here on which libraries we depend on. We try to keep this to a minimum to not bother you with a huge list of dependencies that you must add to your application. Our policy is to always use the latest available versions of the libraries used by us.
Library | Version | Description |
---|---|---|
com.squareup.okhttp3:okhttp | 4.12.0 | Http client |
com.squareup.okhttp3:okhttp-urlconnection | 4.12.0 | |
com.squareup.okhttp3:logging-interceptor | 4.12.0 | |
com.squareup.retrofit2:retrofit | 2.11.0 | REST client |
org.bouncycastle:bcprov-jdk15on | 1.70 | Implementation of cryptographic algorithms |
org.bouncycastle:bcpg-jdk15on | 1.70 | Implementation of the OpenPGP protocol |
com.goterl.lazycode:lazysodium-android | 5.1.0 | Implementation of the Libsodium library |
net.java.dev.jna:jna | 5.13.0 | Library for simplified native access |
com.google.dagger:dagger | 2.51.1 | Dependency injection library |
io.reactivex.rxjava3:rxjava | 3.1.8 | Library for reactive programming |
io.reactivex.rxjava3:rxandroid | 3.0.2 | Library for reactive programming on Android |
net.zetetic:sqlcipher-android | 4.6.0 | Encryption library for SQLite database |
androidx.sqlite:sqlite-ktx | 2.4.0 | - |
androidx.core:core | 1.13.1 | Android support library |
androidx.biometric:biometric | 1.1.0 | Android BiometricPrompt |
Android User-Permissions
The SDK declares following permissions in the AndroidManifest.xml
file:
Those permissions are required to gain access to the network and in order to use fingerprint authenticator. During a build process of an app those permissions will be merged to the app's AndroidManifest automatically by a tool called Manifest Merger
Integrity check
SDK does provide tampering protection mechanism, even though it is recommended to provide additional integrity check within the code of your app, read more here.