Setting up your project

This section describes the first steps to integrate the Onegini Android SDK with an existing Android project. In this sample we'll integrate the SDK into a sample Android application: Example App, using the Android Studio IDE and Gradle build automation system.

Requirements

The Onegini Android SDK supports apps running on API level 16+ (Android Jelly Bean and newer), so make sure, that your project also aims API level 16+. You can find more information about minimum API level requirements in the getting started topic guide.

For example, your app's configuration in build.gradle file could look like this:

android {
  compileSdkVersion 25
  buildToolsVersion "25.0.3"

  defaultConfig {
    applicationId "com.onegini.mobile.exampleapp"
    minSdkVersion 16
    targetSdkVersion 25
    versionCode 3
    versionName "2.0.0"
  }
  // ...
}
// ...

Adding dependencies

There are two ways to add the SDK (and it's dependencies) to your project:

  1. Let Gradle resolve the SDK dependency (preferred)
  2. Manually add the SDK aar and all SDK dependencies to your project.

The first option is by far the most preferable option. The main reasons being that it involves the least amount of manual steps when adding the SDK to your project or updating it to a newer version. The second reason is that it will automatically resolve any third-party dependencies that the SDK has. So if Onegini decides to update one of the SDK dependencies you don't have to worry about using the correct version because Gradle will take care of this for you.

Let Gradle resolve the SDK

In order to use the SDK you need to add a dependency to the build.gradle file. Assuming, that you gained access to the Onegini Artifactory repository, you can setup the repository usage according to the example below:

allprojects {
  apply plugin: 'maven'

  repositories {
    mavenLocal()
    mavenCentral()
    if (project.hasProperty('artifactory_user') && project.hasProperty('artifactory_password')) {
      maven {
        url "https://repo.onegini.com/artifactory/onegini-sdk"
        credentials {
          username artifactory_user
          password artifactory_password
        }
      }
    } else {
      throw new InvalidUserDataException("You must configure the 'artifactory_user' and 'artifactory_password' properties in your project before you can build it.")
    }
  }
}

You need to set your artifactory_user and artifactory_password in the gradle.properties file in your Gradle home directory (e.g. ~/.gradle on Linux/OS X).

Next add the dependency itself:

dependencies {
  // Onegini SDK v7.0.0 - you can choose a different version by simply changing the "7.0.0" part
  compile('com.onegini.mobile.sdk.android:onegini-sdk:7.0.0@aar') {
    transitive = true
  }
}

Any third party dependencies that the Onegini SDK depends on will be automatically resolved (and downloaded) by Gradle.

Providing the SDK as an aar archive

If you don't want (or can) let Gradle automatically download the SDK you also have the option to manually add it. Follow the steps below to add the SDK to your project. If you already added the SDK in the previous step you can skip this paragraph.

Go to File > New > New module from your Android Studio IDE and choose Import .JAR/.AAR Package. In the File name field provide a valid path to the Onegini Android SDK aar archive and enter a name for the module in the Subproject name field (ex.onegini-sdk). You will see that a new build.gradle file will be added to your project with the following contents:

configurations.create("default")
artifacts.add("default", file([RELATIVE_PATH_TO_YOUR_AAR_ARCHIVE]))

Now you need to add a dependency within your main application project to the onegini-sdk module. You can use a regular compile project directive within your main application's build.gradle file to achieve this.

dependencies {
   ...
   compile project(':onegini-sdk')
   ...
}

If you provide the SDK as an aar archive you manually need to specify all the dependencies that are required by the SDK. In case you let Gradle fetch the SDK from Artifactory this is not required because Gradle will automatically resolve any dependencies that are required by the SDK.

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. 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 that we include.

The following libraries (with the specified versions) have to be added to your application project:

dependencies {
  // Http Client
  compile 'com.squareup.okhttp3:okhttp:3.9.0'
  compile 'com.squareup.okhttp3:okhttp-urlconnection:3.9.0'
  compile 'com.squareup.okhttp3:logging-interceptor:3.9.0'

  // Rest Client
  compile('com.squareup.retrofit2:retrofit:2.3.0') {
    // exclude Retrofit’s OkHttp peer-dependency module and define your own module import
    exclude module: 'okhttp'
  }
  compile ('com.squareup.retrofit2:converter-gson:2.3.0') { // Retrofit 2 doesn’t ship with Gson by default
    // exclude Retrofit’s OkHttp peer-dependency module and define your own module import
    exclude module: 'okhttp'
  }
  compile ('com.squareup.retrofit2:adapter-rxjava2:2.3.0') { // Also RxJava isn’t integrated by default anymore
    // exclude Retrofit’s OkHttp peer-dependency module and define your own module import
    exclude module: 'okhttp'
  }
  //Onegini OCRA
  compile 'com.onegini.misc:og-ocra:100.00.00'

  //Firebase Cloud Messaging (FCM)
  compile "com.google.firebase:firebase-messaging:11.6.0"

  // Spongy castle
  compile 'com.madgag.spongycastle:core:1.58.0.0'
  compile 'com.madgag.spongycastle:prov:1.58.0.0'
  compile 'com.madgag.spongycastle:pg:1.58.0.0'
  compile 'com.madgag.spongycastle:pkix:1.58.0.0'

  // Apache Commons IO
  compile 'commons-io:commons-io:2.6'

  // SQLite
  compile 'net.zetetic:android-database-sqlcipher:3.5.7@aar'

  // RxJava
  compile 'io.reactivex.rxjava2:rxandroid:2.0.1'
  compile 'io.reactivex.rxjava2:rxjava:2.1.8'
}

Please note, that adding a lot of dependencies to the project can lead to a build exception that indicates your app has reached a limit of the Android app build architecture. In such case you should use multidex.

Attaching Javadocs to the Onegini SDK

If you use Android Studio, you can easily add the Onegini SDK Javadocs to your project in order to see them in your IDE and get more explanation about the SDK functions and it's parameters.

Follow the steps below to add the Javadocs to your project:

1. In the Project view expand "External libraries", right click on the SDK and select "Library Properties...": Attaching Javadocs

2. Click "Specify Documentation URL" and provide an URL to a local javadocs file (when downloaded from Artifactory) or simply paste the URL to the proper page, for example https://docs.onegini.com/msp/android-sdk/6.04.00/javadocs/index.html to get javadocs for the 6.04.00 version of the SDK. You can also use the following link https://docs.onegini.com/msp/latest/android-sdk/javadocs/index.html to automatically keep up-to date with the Javadocs but doing so remember to always use latest stable release of the SDK to have them inlined. Attaching Javadocs

3. After that you will be able to see Javadocs for the Onegini SDK in Android Studio: Attaching Javadocs

Token Server configuration

Before you can start configuring the client (or App) side, we should first prepare the server side. Follow the Token Server documentation in order to define your app's platform, configuration, pin policies, SSL certificates, etc.

Configuring the app on the TS will also allow you to download a configuration ZIP file for the mobile client, which will make the next step a lot easier.

Client configuration using the SDK Configurator

When you have the proper configuration done on the server side, you can provide a matching configuration to the client (SDK).

The SDK expects, that the app will provide a proper configuration in a class, that implements the OneginiClientConfigModel interface. Also, must provide a server's SSL certificate in order to perform certificate pinning. You can do both steps manually as described in the configuration section.

Sounds too complicated? Luckily, you can use a tool called the Onegini SDK Configurator that will make it a lot simpler.

Downloading configuration file from the Token Server

Start with downloading a configuration ZIP file from the Token Server. Make sure, that you're downloading the correct configuration - in particular the platform and app version must be correct.

Example configuration that can be downloaded from the Token Server

Downloading configuration from the Token Server

Running the SDK Configurator

Next download and run the SDK Configurator. You will be asked about a path to the ZIP file and src directory of your project. You will be also asked to verify the SSL certificate and to override OneginiConfigModel - if there's already one in your project.

Verifying

When the configurator finishes the task, you should be able to find a new keystore file in your project's assets, that contains the SSL certificate. You should also notice a new class in your sources called OneginiConfigModel - that's the generated config class.

Sample OneginiConfigModel generated by the SDK configurator

public class OneginiConfigModel implements OneginiClientConfigModel {

  private final String appIdentifier = "ExampleApp";
  private final String appPlatform = "android";
  private final String redirectionUri = "oneginiexample://loginsuccess";
  private final String appVersion = "2.0.0";
  private final String baseURL = "https://demo-msp.onegini.com";
  private final String resourceBaseURL = "https://demo-msp.onegini.com/resources";
  private final String keystoreHash = "910638c3e6c17ec9ab2a74969abab06b34470d29c21d8ad8a65af243a1ccb69f";

  @Override
  public String getAppIdentifier() {
    return appIdentifier;
  }

  // ...
}

Application signature

Since version 3.02.01 the Android SDK uses an signature of the compiled application to let the application proof it's identity to the Token Server. This approach provides additional security protecting an app against tampering/modification. See the application signature chapter to learn how to calculate your application' signature. The calculated signature must be entered into the Token Server's configuration. Read more about that topic in the Token Server documentation.

Instantiating the SDK

The main functionality to the Onegini Android SDK is available from a single facade, the OneginiClient. The OneginiClient is a singleton which has to be set up once with a OneginiClientBuilder and fetched via OneginiClient.getInstance() afterwards.

If you used the SDK Configurator in order to generate a config model, you can simply use OneginiClientBuilder#build() method to initialize the SDK. In such case the SDK will use reflection and the Context.getPackageName() method to search for the generated class <your.application.package>.OneginiConfigModel, that implements the OneginiClientConfigModel interface. If proper class can't be found, the SDK will throw a OneginiConfigNotFoundException exception.

If you created your own implementation of the OneginiClientConfigModel, you can provide it explicitly via OneginiClientBuilder#setConfigModel() method.

Example

  public static OneginiClient getOneginiClient(final Context context) {
    OneginiClient oneginiClient = OneginiClient.getInstance();
    if (oneginiClient == null) {
      final Context applicationContext = context.getApplicationContext();
      final RegistrationRequestHandler registrationRequestHandler = new RegistrationRequestHandler(applicationContext);
      final CreatePinRequestHandler createPinRequestHandler = new CreatePinRequestHandler(applicationContext);
      final PinAuthenticationRequestHandler pinAuthenticationRequestHandler = new PinAuthenticationRequestHandler(applicationContext);

      // will throw OneginiConfigNotFoundException if OneginiConfigModel class can't be found
      oneginiClient = new OneginiClientBuilder(applicationContext, registrationRequestHandler, createPinRequestHandler, pinAuthenticationRequestHandler).build();
    }
    return oneginiClient;
  }

The OneginiClientBuilder#build() method can throw an OneginiInitializationException exception when one of the necessary handler implementations is not provided. This can be avoided by passing an instance for the OneginiRegistrationRequestHandler, OneginiCreatePinRequestHandler and OneginiPinAuthenticationRequestHandler handlers (see next chapter).

Working with the SDK during development

Please note that Android SDK has an ability to detect if the app works in debug mode or with debuggable environment and this feature is enabled by default. When debug mode detection is enabled and debug is detected, then the SDK will not allow to execute any security related flow. To disable this feature during development please follow the security controls guide.

Updating ProGuard rules

If your app uses obfuscation tool like Proguard, you will have to update obfuscation rules. You can use attached configuration proguard-onegini.pro as a base for your project.

Compiling the app

That was a basic setup of the SDK. In order to verify that everything worked as expected you should try to compile and run your application.