Android installation
To satisfy customers with the highest security requirements, the Nevis Mobile Authentication SDK is hardened with state-of-the-art protection mechanisms.
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.
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.: 3.9.0.1674
.
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:
- In the Gradle build files add the repository containing the SDK dependency:
- Groovy
- Kotlin
Add repository in the build.gradle
file of your root project.
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>
}
}
}
}
Add repository in the build.gradle.kts
file of your root project.
buildscript {
repositories {
maven {
url = uri("https://maven.pkg.github.com/nevissecurity/nevis-mobile-authentication-sdk-android-package")
credentials {
username = <GITHUB_USERNAME>
password = <GITHUB_PERSONAL_ACCESS_TOKEN>
}
}
}
}
Accessing GitHub packages requires you to have a GitHub account. You have to provide a Personal Access Token, as described here.
- In the Gradle build files add the SDK dependency and its required dependencies:
- Groovy
- Groovy with Version Catalog
- Kotlin
- Kotlin with Version Catalog
Add dependency in the build.gradle
file of your application module.
dependencies {
debugImplementation "ch.nevis:nevis-mobile-authentication-sdk-android-debug:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}"
}
Add SDK version and library in the libs.versions.toml
file.
[versions]
nevis-mobile-authentication-sdk-version = "3.9.0.1674"
[libraries]
nevis-mobile-authentication-sdk-android-debug = { group = "ch.nevis", name = "nevis-mobile-authentication-sdk-android-debug", version.ref = "nevis-mobile-authentication-sdk-version" }
Add dependency in the build.gradle.kts
file of your application module.
dependencies {
debugImplementation libs.nevis.mobile.authentication.sdk.android.debug
}
Add dependency in the build.gradle.kts
file of your application module.
dependencies {
debugImplementation("ch.nevis:nevis-mobile-authentication-sdk-android-debug:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}")
}
Add SDK version and library in the libs.versions.toml
file.
[versions]
nevis-mobile-authentication-sdk-version = "3.9.0.1674"
[libraries]
nevis-mobile-authentication-sdk-android-debug = { group = "ch.nevis", name = "nevis-mobile-authentication-sdk-android-debug", version.ref = "nevis-mobile-authentication-sdk-version" }
Add dependency in the build.gradle.kts
file of your application module.
dependencies {
debugImplementation(libs.nevis.mobile.authentication.sdk.android.debug)
}
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 thedebug
flavor.release
contains the binary files POM file of therelease
flavor.finalizer
contains the finalization library.
For example the content of package version 3.9.0.1674
will look like:
├── debug
│ ├── nevis-mobile-authentication-sdk-android-debug-3.9.0.1674-javadoc.jar
│ ├── nevis-mobile-authentication-sdk-android-debug-3.9.0.1674.aar
│ └── nevis-mobile-authentication-sdk-android-debug-3.9.0.1674.pom
├── finalizer
│ ├── *.protect-android-*.pom
│ ├── *.protect-android.jar
│ └── finalizers
│ ├── linux
│ │ └── finalizer
│ ├── macos
│ │ └── finalizer
│ └── windows
│ └── finalizer.exe
└── release
├── nevis-mobile-authentication-sdk-android-3.9.0.1674-javadoc.jar
├── nevis-mobile-authentication-sdk-android-3.9.0.1674.aar
└── nevis-mobile-authentication-sdk-android-3.9.0.1674.pom
The version of finalizer binaries and Gradle plugin differ from SDK version. This is deliberate.
- 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.
For more information about declaring Gradle repositories read the official guide.
- Local Maven repository
- Relative/file Maven repository
- Custom Maven repository
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:
export NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION=3.9.0.1674
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
We assume that you are in the root directory of the unpacked SDK package.
Declare mavenLocal()
repository:
allprojects {
repositories {
mavenLocal()
}
}
You may install the debug
and release
flavors of the Android SDK into a relative/file Maven repository. Let's say you want to use the native-dependecies
folder in your Android project root. In this case you have to add the following repository declaration to allprojects
part of your build.gradle
.
- Groovy
- Kotlin
allprojects {
repositories {
maven {
name = "Native-Dependencies"
url = new File(rootProject.rootDir, 'native-dependencies')
}
}
}
allprojects {
repositories {
maven {
name = "Native-Dependencies"
url = File(rootProject.rootDir, "native-dependencies").toURI()
}
}
}
Now you have to install the package to this relative/file Maven repository. To do this run the following commands in terminal:
export NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION=3.9.0.1674
# Absolute path of the previosly created Android native dependencies directory. E.g.: /Users/username/projects/your_android_app/native-dependencies
export LOCAL_REPOSITORY=/Users/username/projects/your_android_app/native-dependencies
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 -DlocalRepositoryPath=${LOCAL_REPOSITORY}
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 -DlocalRepositoryPath=${LOCAL_REPOSITORY}
for f in ${LOCAL_REPOSITORY}/**/maven-metadata-local.xml; do mv "$f" "$(dirname $f)/maven-metadata.xml"; done
We assume that you are in the root directory of the unpacked SDK package.
Add the following files to your custom Maven repository and declare that repository.
release/nevis-mobile-authentication-sdk-android-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.aar
debug/nevis-mobile-authentication-sdk-android-debug-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.aar
We assume that you are in the root directory of the unpacked SDK package.
NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION
is the actual version of the Nevis Mobile Authentication Android SDK e.g.: 3.9.0.1674
.
Please check the related *.pom
file for groupId
, artifactId
and version
.
- Add
debug
flavor dependency (for development)
- Groovy
- Groovy with Version Catalog
- Kotlin
- Kotlin with Version Catalog
Add dependency in the build.gradle
file of your application module.
dependencies {
debugImplementation "ch.nevis:nevis-mobile-authentication-sdk-android-debug:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}"
}
Add SDK version and library in the libs.versions.toml
file.
[versions]
nevis-mobile-authentication-sdk-version = "3.9.0.1674"
[libraries]
nevis-mobile-authentication-sdk-android-debug = { group = "ch.nevis", name = "nevis-mobile-authentication-sdk-android-debug", version.ref = "nevis-mobile-authentication-sdk-version" }
Add dependency in the build.gradle.kts
file of your application module.
dependencies {
debugImplementation libs.nevis.mobile.authentication.sdk.android.debug
}
Add dependency in the build.gradle.kts
file of your application module.
dependencies {
debugImplementation("ch.nevis:nevis-mobile-authentication-sdk-android-debug:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}")
}
Add SDK version and library in the libs.versions.toml
file.
[versions]
nevis-mobile-authentication-sdk-version = "3.9.0.1674"
[libraries]
nevis-mobile-authentication-sdk-android-debug = { group = "ch.nevis", name = "nevis-mobile-authentication-sdk-android-debug", version.ref = "nevis-mobile-authentication-sdk-version" }
Add dependency in the build.gradle.kts
file of your application module.
dependencies {
debugImplementation(libs.nevis.mobile.authentication.sdk.android.debug)
}
- Add
release
flavor dependency (for production)
- Groovy
- Groovy with Version Catalog
- Kotlin
- Kotlin with Version Catalog
Add dependency in the build.gradle
file of your application module.
dependencies {
releaseImplementation "ch.nevis:nevis-mobile-authentication-sdk-android:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}"
}
Add SDK version and library in the libs.versions.toml
file.
[versions]
nevis-mobile-authentication-sdk-version = "3.9.0.1674"
[libraries]
nevis-mobile-authentication-sdk-android-release = { group = "ch.nevis", name = "nevis-mobile-authentication-sdk-android", version.ref = "nevis-mobile-authentication-sdk-version" }
Add dependency in the build.gradle.kts
file of your application module.
dependencies {
releaseImplementation libs.nevis.mobile.authentication.sdk.android.release
}
Add dependency in the build.gradle.kts
file of your application module.
dependencies {
releaseImplementation("ch.nevis:nevis-mobile-authentication-sdk-android:${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}")
}
Add SDK version and library in the libs.versions.toml
file.
[versions]
nevis-mobile-authentication-sdk-version = "3.9.0.1674"
[libraries]
nevis-mobile-authentication-sdk-android-release = { group = "ch.nevis", name = "nevis-mobile-authentication-sdk-android", version.ref = "nevis-mobile-authentication-sdk-version" }
Add dependency in the build.gradle.kts
file of your application module.
dependencies {
releaseImplementation(libs.nevis.mobile.authentication.sdk.android.release)
}
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.
Apply the following changes in build.gradle
file of your application module.
- Delete the finalizer plugin dependency from
buildscript
block inbuild.gradle
file whereNEVIS_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}"
}
}
- Delete applying
finalize
plugin line inbuild.gradle
file.
apply plugin: 'finalize'
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
- Declare Maven repository
You have to configure the Maven repository where the Finalization Gradle plugin is available. There are multiple choices.
For more information about declaring Gradle repositories read the official guide.
- Local Maven repository
- Custom Maven repository
You may install the Finalization Gradle plugin into your local Maven repository. To do this execute the following commands in terminal:
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.
# 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:
- Build script
- Plugin management
In build.gradle
of your root project, add mavenLocal()
to buildscript
repositories.
buildscript {
repositories {
mavenLocal()
}
}
In settings.gradle
or settings.gradle.kts
of your project, add mavenLocal()
to pluginManagement
repositories.
pluginManagement {
repositories {
mavenLocal()
}
}
Add the following file to your custom Maven repository and declare that repository.
finalizer/*.protect-android.jar
We assume that you are in the root directory of the unpacked SDK package.
Please check the related *.protect-android-*.pom
file for groupId
, artifactId
and version
.
- Add Finalization Gradle plugin dependency
Replace the placeholders (*
) in the gradle plugin references below with the real package namespace as indicated by the finalizer file name and versions.
- Build script
- Plugin management (Groovy)
- Plugin management and version catalog (Groovy)
- Plugin management (Kotlin)
- Plugin management and version catalog (Kotlin)
In build.gradle
of your root project, add plugin dependency buildscript
dependencies.
buildscript {
dependencies {
classpath group: '*.protect-android', name: '*.protect-android', version: '*'
}
}
In settings.gradle
of your project, add resolutionStrategy
and plugin declaration as in the following example.
pluginManagement {
resolutionStrategy {
eachPlugin {
if (requested.id.id == "*.protect-android") {
useModule("*.protect-android:*.protect-android:${requested.version}")
}
}
}
}
plugins {
id '*.protect-android' version '*' apply false
}
[versions]
protect-android-version = "*"
[plugins]
protect-android = { id = "*.protect-android", version.ref = "protect-android-version"}
In settings.gradle
of your project, add resolutionStrategy
and plugin declaration as in the following example.
pluginManagement {
resolutionStrategy {
eachPlugin {
if (requested.id.id == "*.protect-android") {
useModule("*.protect-android:*.protect-android:${requested.version}")
}
}
}
}
plugins {
alias(libs.plugins.protect.android) apply false
}
In settings.gradle.kts
of your project, add resolutionStrategy
and plugin declaration as in the following example.
pluginManagement {
resolutionStrategy {
eachPlugin {
if (requested.id.id == "*.protect-android") {
useModule("*.protect-android:*.protect-android:${requested.version}")
}
}
}
}
plugins {
id("*.protect-android") version "*" apply false
}
[versions]
protect-android-version = "*"
[plugins]
protect-android = { id = "*.protect-android", version.ref = "protect-android-version"}
In settings.gradle.kts
of your project, add resolutionStrategy
and plugin declaration as in the following example.
pluginManagement {
resolutionStrategy {
eachPlugin {
if (requested.id.id == "*.protect-android") {
useModule("*.protect-android:*.protect-android:${requested.version}")
}
}
}
}
plugins {
alias(libs.plugins.protect.android) apply false
}
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-3.9.0.1674
inside your HOME
directory then the environment variable should look like:
# On Linux
export FINALIZE_ANDROID_ROOT=$HOME/nevis-mobile-authentication-sdk-android-3.9.0.1674/finalizer/finalizers/linux
# On macOs
export FINALIZE_ANDROID_ROOT=$HOME/nevis-mobile-authentication-sdk-android-3.9.0.1674/finalizer/finalizers/macos
# On Windows
set FINALIZE_ANDROID_ROOT=%HOME%\nevis-mobile-authentication-sdk-android-3.9.0.1674\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
):
Replace the placeholders (*
) in the gradle plugin references below with the real package namespace as indicated by the finalizer file name.
- Groovy
- Kotlin
In build.gradle
file of your application module, apply the finalizer plugin and configure it.
apply plugin: '*.finalize-android'
finalizeAndroid {
buildVariants {
testEnvRelease {
disabled false
log "$buildDir/finalization.log"
}
}
}
In build.gradle.kts
file of your application module, apply the finalizer plugin and configure it.
plugins {
id("*.finalize-android")
}
finalizeAndroid {
buildVariants {
testEnvRelease {
disabled(false)
log(layout.buildDirectory.file("./finalization-release.log").get().toString())
}
}
}
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, and you use Android Gradle Plugin 7.0 or newer, use androidComponent
as in the following example:
android {
androidComponents {
onVariants(selector().all(), variant -> {
variant.manifestPlaceholders = [attributeName : "$attributeValue"]
})
If you use an earlier version of the Android Gradle Plugin than 7.0, and use the merged flavor of the variant to resolve the placeholders, execute the plugin after project evaluation:
android { applicationVariants.all {
variant ->
variant.getMergedFlavor().manifestPlaceholders = [attributeName : "$attributeValue"]
}
}
[...]
project.afterEvaluate { apply plugin: 'finalize' }
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.
Backup Setup
The Android Mobile Authentication SDK does not support backing up and restoring its contents.
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:
<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.
If the contents of the Android Mobile Authentication SDK are backed up and then restored, the SDK can fail during initialization.