Your suggested change has been received. Thank you.

close
Thales Logo

All

  • All
  • CipherTrust Manager
  • CipherTrust Application Data Protection (CADP)
  • CipherTrust Application Key Management (CAKM)
  • CipherTrust Batch Data Transformation (BDT)
  • CipherTrust Cloud Key Management (CCKM)
  • CipherTrust Data Discovery and Classification (DDC)
  • CipherTrust Data Protection Gateway (DPG)
  • CipherTrust Database Protection (CDP)
  • CipherTrust Intelligent Protection (CIP)
  • CipherTrust Integrations
  • CipherTrust Migrations
  • CipherTrust RESTful Data Protection (CRDP)
  • CipherTrust Transparent Encryption (CTE)
  • CipherTrust Transparent Encryption Userspace (CTE-U)
  • CipherTrust Secrets Management (CSM)
  • CipherTrust Vaulted Tokenization (CT-V)
  • CipherTrust Vaultless Tokenization (CT-VL)
  • CTE-Linux
  • CTE-Windows
  • CTE-AIX
  • CTE-K8s
  • CTE-U
  • Crypto Command Center
  • Data Protection on Demand
  • Luna Cloud HSM
  • Luna Network HSM
  • Luna PCIe HSM
  • Luna USB HSM
  • OneWelcome Identity Platform
  • ProtectApp LUKS
  • ProtectServer 2 HSM
  • ProtectServer 3 HSM
  • SafeNet Trusted Access (STA)
  • SafeNet MobilePASS+
  • SafeNet MobilePASS+ for Android
  • SafeNet MobilePASS+ for Chrome
  • SafeNet MobilePASS+ for macOS
  • SafeNet MobilePASS+ for iOS
  • SafeNet MobilePASS+ for WatchOS
  • SafeNet MobilePASS+ for Windows
  • SafeNet Synchronization Agent
  • SafeNet Logging Agent
  • SafeNet Agent for FreeRADIUS
  • SafeNet Agent for NPS
  • SafeNet Agent for Windows Logon
  • SafeNet Authentication Service Private Cloud Edition (SAS PCE)
  • SafeNet Remote Logging Agent
  • SafeNet Keycloak Agent
  • SafeNet IDPrime Virtual (IDPV)
  • SafeNet FIDO Key Manager
  • SafeNet FIDO Key Manager for Android
  • SafeNet FIDO Key Manager for iOS
  • SafeNet FIDO Key Manager for Windows
back

Android SDK

Setting up the project

search
printsuggest an edit

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.

copy link to clipboardAndroid 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+.

Note

The core functionalities of the Android SDK use hardware-backed crypto services (Android Keystore) that were not fully available on Android API level 22 and older.

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

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

copy link to clipboardRequired third-party libraries

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

Tip

If you add the Android SDK as a dependency using Gradle, Gradle automatically resolves third-party dependencies.

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.15.0 Library for simplified native access
com.google.dagger:dagger 2.53 Dependency injection library
io.reactivex.rxjava3:rxjava 3.1.10 Library for reactive programming
io.reactivex.rxjava3:rxandroid 3.0.2 Library for reactive programming on Android
net.zetetic:sqlcipher-android 4.6.1 Encryption library for SQLite database
androidx.sqlite:sqlite-ktx 2.4.0 -
androidx.core:core 1.15.0 Android support library
androidx.biometric:biometric 1.1.0 Android BiometricPrompt

copy link to clipboardDisable 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.

copy link to clipboardAdding 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.

copy link to clipboardConfiguring 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.

    Example config from IDAAS-core

copy link to clipboardApplication 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.

copy link to clipboardConfiguring 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.

copy link to clipboardSample 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>

Note

If you are using external browsers during registration, you must update your AndroidManifest.xml file <intent-filter> section to include <data android:scheme="oneginiexample" />. You should set the value as the baseUrl of your redirectionUri.

If you are using WebView, you must address this redirect.

copy link to clipboardWorking 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.

copy link to clipboardAttaching 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:

    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.

    Android javadocs URL example

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

    Javadocs in Android Studio

On this page