Skip to main content
Version: 4.4.x.x RR (Android, iOS) / 4.5.x.x RR (Flutter) / 5.x.x.x RR (React Native)

Android installation

To satisfy customers with the highest security requirements, the Nevis Mobile Authentication SDK is hardened with state-of-the-art protection mechanisms.

SDK Versions 3.5 and lower

Between versions 3.5 and 3.6 the used hardening framework was changed. If you are using SDK version 3.5 or lower refer to this guide

The Nevis Mobile Authentication SDK binaries for Android are provided by Nevis in an archive file.

For convenience, Nevis also offers a public Maven repository where the debug flavor of the SDK is available.

info

To obtain the release flavor of the SDK, download it from our portal.

You will see a package called nevis-mobile-authentication-sdk-android-NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION.zip where NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION is the actual version of the Nevis Mobile Authentication Android SDK e.g.: 4.4.0.1814.

Installation from public Maven repository​

The nevis-mobile-authentication-sdk-android-package GitHub repository, contains the debug flavor of the Nevis Mobile Authentication SDK. You can follow the following steps to integrate the SDK in your application using this repository.

The following steps assume that the NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION contains the SDK version. Set the console environment variable as follows:

  1. In the Gradle build files add the repository containing the SDK dependency:

Add repository in the build.gradle file of your root project.

build.gradle file using public Maven repository
buildscript {
    repositories {
        maven {
            url "https://maven.pkg.github.com/nevissecurity/nevis-mobile-authentication-sdk-android-package"
            credentials {
                username = <GITHUB_USERNAME>
                password = <GITHUB_PERSONAL_ACCESS_TOKEN>
            }
        }
    }
}
tip
  1. In the Gradle build files add the SDK dependency and its required dependencies:

Add dependency in the build.gradle file of your application module.

Dependency for debug flavor
dependencies {
    debugImplementation "ch.nevis:nevis-mobile-authentication-sdk-android-debug:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}"
}

Installation from ZIP archive​

The SDK is provided as compressed archive. After unpacking, you see the following structure:

  • debug contains the binary files and POM file of the debug flavor.
  • release contains the binary files POM file of the release flavor.
  • finalizer contains the finalization library.

For example the content of package version 4.4.0.1814 will look like:

Nevis Mobile Authentication SDK Android archive content
▼📁debug
📄nevis-mobile-authentication-sdk-android-debug-4.4.0.1814-javadoc.jar
📄nevis-mobile-authentication-sdk-android-debug-4.4.0.1814.aar
📄nevis-mobile-authentication-sdk-android-debug-4.4.0.1814.pom
▼📁finalizer
📄*.protect-android-*.pom
📄*.protect-android.jar
▼📁finalizers
▼📁linux
📄finalizer
▼📁macos
📄finalizer
▼📁windows
📄finalizer.exe
▼📁release
📄nevis-mobile-authentication-sdk-android-4.4.0.1814-javadoc.jar
📄nevis-mobile-authentication-sdk-android-4.4.0.1814.aar
📄nevis-mobile-authentication-sdk-android-4.4.0.1814.pom
Finalizer version

The version of finalizer binaries and Gradle plugin differ from SDK version. This is deliberate.

  1. Publish the SDK to a dependency management framework

In this section we describe how to publish the SDK to a Maven repository. If you are using a different framework than Maven, you have to manage the publishing of the SDK and its transitive dependencies accordingly. The transitive dependencies of each flavor of the SDK are declared in the POM files.

You have to configure the Maven repository where the Android SDK is available. There are multiple choices.

tip

For more information about declaring Gradle repositories read the official guide.

You may install the debug and release flavors of the Android SDK into your local Maven repository. To do this, execute the following commands in terminal:

Installation to local Maven repository
export NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION=4.4.0.1814

mvn install:install-file -Dfile=debug/nevis-mobile-authentication-sdk-android-debug-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.aar -DgroupId=ch.nevis -DartifactId=nevis-mobile-authentication-sdk-android-debug -Dversion=${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION} -DpomFile=debug/nevis-mobile-authentication-sdk-android-debug-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.pom

mvn install:install-file -Dfile=release/nevis-mobile-authentication-sdk-android-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.aar -DgroupId=ch.nevis -DartifactId=nevis-mobile-authentication-sdk-android -Dversion=${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION} -DpomFile=release/nevis-mobile-authentication-sdk-android-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.pom
note

We assume that you are in the root directory of the unpacked SDK package.

Declare mavenLocal() repository:

Local Maven repository declaration
allprojects {
    repositories {
        mavenLocal()
    }
}
  1. Add debug flavor dependency (for development)

Add dependency in the build.gradle file of your application module.

Dependency for debug flavor
dependencies {
    debugImplementation "ch.nevis:nevis-mobile-authentication-sdk-android-debug:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}"
}
  1. Add release flavor dependency (for production)

Add dependency in the build.gradle file of your application module.

Dependency for release flavor
dependencies {
    releaseImplementation "ch.nevis:nevis-mobile-authentication-sdk-android:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}"
}

ProGuard / R8 compatibility​

The SDK includes a consumer ProGuard rules file (proguard.txt) inside the .aar. When the SDK is consumed as a standard Gradle dependency through a Maven repository, these rules are automatically applied during the R8/ProGuard processing of your application — no manual rule management is required.

Automatic consumer rules require Maven dependency resolution

Consumer ProGuard rules are only applied automatically when the SDK is declared as a Gradle dependency resolved through a Maven repository (remote, local, or file-based). If the .aar is imported directly via files() or fileTree(), Gradle skips the artifact extraction pipeline and the rules will not be applied. See Installation from ZIP archive for supported installation methods.

Minification is not recommended

Setting minifyEnabled to true will disable some security guards such as the checksum guard and is strongly not recommended.

If you must enable R8 processing, do not enable obfuscation — the SDK is already obfuscated and additional obfuscation will cause build failures. Add -dontobfuscate to your ProGuard rules file.

Finalization​

There are a number of protection mechanisms only included in the release flavor that require a procedure during the building of the application called finalization.

The finalization updates the binaries of the library with information about your application to execute those protection mechanisms during runtime. If you use Gradle to build the application, the finalization can be done using a Gradle plugin.

The debug flavor does not require finalization.

Remove references of previous finalization tool​

In case you are already a user of the Nevis Mobile Authentication SDK for Android version 3.5.x or prior, and you want to change to version 3.6.x or above first you have to remove the references of previous finalization tool following this chapter. Otherwise, you can skip this chapter.

info

Apply the following changes in build.gradle file of your application module.

  1. Delete the finalizer plugin dependency from buildscript block in build.gradle file where NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION is the version of the currently used Nevis Mobile Authentication SDK for Android.
buildscript {
    dependencies {
        classpath "ch.nevis:nevis-mobile-authentication-sdk-android-finalizer:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}"
    }
}
  1. Delete applying finalize plugin line in build.gradle file.
apply plugin: 'finalize'
tip

You probably apply it inside a condition that ensures it is applied only in case of release builds, in this case delete it and the condition as well. E.g.:

if (project.gradle.startParameter.taskNames.find { name -> name.endsWith("Release") } != null) { apply plugin: 'finalize' }

Install Finalization Gradle plugin​

  1. Declare Maven repository

You have to configure the Maven repository where the Finalization Gradle plugin is available. There are multiple choices.

tip

For more information about declaring Gradle repositories read the official guide.

You may install the Finalization Gradle plugin into your local Maven repository. To do this execute the following commands in terminal:

note

Replace the placeholders (*) in the commands below with the real file names and versions.

We assume that you are in the root directory of the unpacked SDK package.

Installation to local Maven repository
# Linux / macOs
mvn install:install-file -Dfile=finalizer/*.protect-android.jar -DpomFile=finalizer/*.protect-android-*.pom

# Windows
mvn install:install-file -Dfile=finalizer\*.protect-android.jar -DpomFile=finalizer\*.protect-android-*.pom

Declare Maven local repository:

In build.gradle of your root project, add mavenLocal() to buildscript repositories.

Maven local repository
buildscript {
    repositories {
        mavenLocal()
    }
}
  1. Add Finalization Gradle plugin dependency
note

Replace the placeholders (*) in the gradle plugin references below with the real package namespace as indicated by the finalizer file name and versions.

In build.gradle of your root project, add plugin dependency buildscript dependencies.

Dependency for Finalization Gradle plugin
buildscript {
    dependencies {
        classpath group: '*.protect-android', name: '*.protect-android', version: '*'
    }
}

Set FINALIZE_ANDROID_ROOT environment variable​

FINALIZE_ANDROID_ROOT environment variable must be set for *.finalize-android Gradle plugin to specify the path of the finalizer executable. Replace the placeholders (*) in the environment variable with the real package namespace as indicated by the finalizer file name. If you unpacked the content of the zip file into a directory called nevis-mobile-authentication-sdk-android-4.4.0.1814 inside your HOME directory then the environment variable should look like:

# On Linux
export FINALIZE_ANDROID_ROOT=$HOME/nevis-mobile-authentication-sdk-android-4.4.0.1814/finalizer/finalizers/linux

# On macOS (ARM64)
export FINALIZE_ANDROID_ROOT=$HOME/nevis-mobile-authentication-sdk-android-4.4.0.1814/finalizer/finalizers/macos-arm64

# On macOS (X86)
export FINALIZE_ANDROID_ROOT=$HOME/nevis-mobile-authentication-sdk-android-4.4.0.1814/finalizer/finalizers/macos-x86

# On Windows
set FINALIZE_ANDROID_ROOT=%HOME%\nevis-mobile-authentication-sdk-android-4.4.0.1814\finalizer\finalizers\windows

Modify Gradle build files​

Apply the finalizer plugin and configure it. Note that if you use product flavors, the buildVariants values of the finalization plugin configuration are a combination of the product flavors and build types.

The example below assumes that the product flavor testEnv with the release build type requires finalization (and thus the buildVariant is testEnvRelease):

note

Replace the placeholders (*) in the gradle plugin references below with the real package namespace as indicated by the finalizer file name.

In build.gradle file of your application module, apply the finalizer plugin and configure it.

Apply and configure finalizer plugin
apply plugin: '*.finalize-android'

finalizeAndroid {
    buildVariants {
        testEnvRelease {
            disabled false
            log "$buildDir/finalization.log"
        }
    }
}

Manifest placeholders​

The plugin requires access to the AndroidManifest.xml when executed. So, if you use manifest placeholders, they have to be resolved before the plugin runs. If you want to resolve the placeholders on a variant basis, use androidComponent as in the following example:

Manifest placeholders
android {

    androidComponents {
        onVariants(selector().all(), variant -> {
             variant.manifestPlaceholders = [attributeName   : "$attributeValue"]
    })

Multi-module project setup​

In a multi-module Android project, you can keep the SDK dependency in an Android library module and apply the finalization plugin in the application module. Before you start, complete the standard Finalization setup, including the root-project repository and plugin dependency configuration.

SDK dependency in a library module​

Add the SDK dependency to the Android library module that uses it. Apply the com.android.library Gradle plugin to that module. Pure Kotlin/JVM modules (java-library) cannot consume AAR artifacts such as the SDK.

Use the variant-specific dependency configurations as described in the installation sections above:

Library module build.gradle
plugins {
    id 'com.android.library'
}

dependencies {
    debugImplementation "ch.nevis:nevis-mobile-authentication-sdk-android-debug:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}"
    releaseImplementation "ch.nevis:nevis-mobile-authentication-sdk-android:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}"
}

Add the library module as a dependency in the application module so that the SDK is included in the resolved dependency graph:

Application module build.gradle
dependencies {
    implementation project(':presentation')
}
note

By default, implementation dependencies are not visible at compile time to modules that consume the library module. If the library module exposes SDK types through its public API and other modules need to compile against those types, use debugApi and releaseApi instead of debugImplementation and releaseImplementation in the library module.

Finalization in a multi-module project​

Apply the finalization plugin to the application module only. The application module is the module that applies the com.android.application Gradle plugin. Do not apply the finalization plugin to a library module.

The finalization plugin resolves SDK binaries from the dependency graph of the application module. When the application module depends on the library module that contains the SDK and the SDK uses the supported separate debug/release artifact setup, the plugin locates and processes the SDK binaries.

If your project contains multiple application modules that produce release builds, apply the finalization plugin to each application module.

Troubleshooting​

If the finalization plugin cannot find SDK binaries, the build fails with:

No .fin files found for configuration <buildVariant>. Make sure you are finalizing protected AARs

To resolve this issue:

  • Verify that the finalization plugin is applied to the application module, not to a library module.
  • Verify that the application module depends on the library module that declares the SDK dependency.
  • Verify that you installed the SDK with separate debug and release artifacts, as described in the installation sections above. Do not use a single SDK artifact with debug/release classifiers. The finalization plugin does not support classifier-based artifact declarations.

Enable Multidexing​

If your Android Gradle plugin does not enable multidexing by default, set multiDexEnabled to true in the defaultConfig section of your top level build.gradle file. The finalization can cause the total number of methods to go beyond the Dalvik Executable specification limit of 64k. Therefore, multiDexing must be enabled for your application.

Device Migration and Backup/Restore​

The Android Mobile Authentication SDK does not support backing up and restoring its contents. For more information on device migration and the recovery flow, see Device Migration and Backup/Restore.

If your application does not require backing up any of its contents, disable the backup in the AndroidManifest.xml of your application as described in the Android documentation:

Android Manifest Backup Configuration
<manifest ... >
    ...
    <application android:allowBackup="false" ... >
        ...
    </application>
</manifest>

If your application requires backing up contents, you must list them explicitly in AndroidManifest.xml to avoid backing up the SDK contents.

caution

If the contents of the Android Mobile Authentication SDK are backed up and then restored, the SDK can fail during initialization.

Last updated on