Setting up the project

This section describes the first steps to integrate the Android SDK with an existing Android project. In this sample, you integrate the Android SDK into the Android example application, using the Android Studio IDE and Gradle build automation system.

Android API requirements

The Android SDK supports apps running on Android API level 23+ (Android Marshmallow and newer). Ensure that your application is using Android API level 23+.

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

android {
    defaultConfig {
        minSdkVersion 23
        // ...
    }
    // ...
}
// ...

android {
defaultConfig {
    minSdk = 23
    // ...
}
// ...
}

Required third-party libraries

The Android SDK does not include third-party library dependencies. You require the following third-party libraries.

Disable the allowBackup attribute in the Android manifest

The Android SDK cannot operate with the android:allowBackup="true" setting in your AndroidManifest.xml. If android:allowBackup="true" is declared, we recommend deleting the attribute. For more information about allowBackup, see back up user data with auto backup.

Adding the Android SDK as a dependency

To use the Android SDK, you must add the Android SDK dependency to the module-level build.gradle file. We recommend this method for the following reasons:

• It requires fewer manual steps to add the Android SDK and update the SDK version.
• This method automatically resolves all third-party dependencies.

You require credentials to authenticate your build access to the OneWelcome Identity Platform Artifactory repository. To obtain credentials, visit the Customer Support Portal and submit an access request for the Artifactory repository.

When you have credentials, set your OneWelcome Identity Platform artifactory_user and artifactory_password in the gradle.properties file in your Gradle home directory (such as ~/.gradle on Linux/OS X).

Then set up the repository usage:

allprojects {
    repositories {
        if (project.hasProperty('artifactory_user') && project.hasProperty('artifactory_password')) {
        maven {
            url "https://repo.onewelcome.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.")
        }
        // ...
    }
    // ...
    }

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

Add the dependency:

dependencies {
implementation('com.onegini.mobile.sdk.android:onegini-sdk:X.X.X@aar') {
    transitive = true
}
}

dependencies {
implementation("com.onegini.mobile.sdk.android:onegini-sdk:X.X.X@aar") {
    transitive = true
}
}

Gradle downloads any third-party dependencies that the Android SDK requires. In the event of dependency conflicts, see the App build dependencies documentation.

Configuring the IDAAS-core

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

The Android SDK expects that the app will provide a proper configuration in a class that implements the OneginiClientConfigModel interface. Also, you must provide a server's SSL certificate in order to perform certificate pinning.

When the IDAAS-core configuration is complete, you will be able to download a configurable zip for your mobile client configuration.

1. Download the configuration zip from the IDAAS-core.

   

Application thumbprint

The Android SDK uses a SHA-256 fingerprint of the app signing key. See application integrity to learn how to obtain your signing key certificate. The calculated hash must be entered into the IDAAS-core configuration.

Configuring the client

Configure the client using the sdk-configurator. The sdk-configurator configures your application to use the Mobile SDKs.

1. Download the sdk-configurator.

2. Run the sdk-configurator.

   1. Provide the sdk-configurator the path to your configuration zip from the IDAAS-core.

   2. Provide the sdk-configurator the path to your application /src directory.

   3. Verify the SSL Certificate.

   4. Override any existing OneWelcome Identity Platform configuration model.

   Tip

   We recommend creating a backup of any existing OneWelcome Identity Platform configuration model.

3. Validate that the sdk-configurator completed successfully by verifying the following:

4. A new keystore file exists in your project's assets containing the SSL certificate.

5. A new class exists in your sources called OneginiConfigModel.
6. Compile and run your application.

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";
        private final String serverPublicKey = "355C555820D47CB2010F601D96CB134A3026BFEC7F23732E0890CD5E62AB2D24";

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

        // ...
    }

    class OneginiConfigModel : OneginiClientConfigModel {
    private val appIdentifier = "ExampleApp"
        private val appPlatform = "android"
        private val redirectionUri = "oneginiexample://loginsuccess"
        private val appVersion = "7.5.0"
        private val baseURL = "https://demo-msp.onegini.com"
        private val resourceBaseURL = "https://demo-msp.onegini.com/resources/"
        private val keystoreHash = "99e629cc3f8a50316123bab1fdc1caeaa98e557ebafce89e41d96c2e536816dd"
        private val serverPublicKey = "BBFFCC164C1AC014069B6C2C96E012E434D064F1EB736EF0E2470EFF15410D9D"

        override fun getAppIdentifier(): String {
            return appIdentifier
        }

        // ...
    }

The configurator will also state that you need to specify the data scheme in the AndroidManifest.xml, in the intent filter section. It's going to be the baseUrl of the declared redirectionUri in the OneginiConfigModel class.

    <manifest>
    // ...
        <application>
        // ...
            <activity>
            // ...
                <intent-filter>
                <data android:scheme="oneginiexample" />
                // ...
                </intent-filter>
            </activity>
        </application>
    </manifest>

Working with the SDK during development

The 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, the Android SDK will not allow you to execute any security-related flow. To disable this feature during development, follow the security controls.

Attaching Javadocs to the Android SDK

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

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

1. In the Project view, expand External libraries, right-click the SDK and select Library Properties:

   

2. Click Specify Documentation URL and provide an URL to a local javadocs file (when downloaded from Artifactory) or simply paste the URL.

   

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