Configuration
Using the Configuration
interface (java, swift, flutter), you define the server and endpoints the SDK has to use to do authentication. You can also specify network timeouts.
Authentication Cloud backend
If your application is using the Nevis Authentication Cloud as backend, the SDK offers a convenience interface for each platform:
Configuration.AuthCloudBuilder
for javaConfiguration(authCloudHostname:)
for swiftConfiguration.authCloud(hostname:)
for flutter
With these interfaces, you only need to provide the hostname of your cloud environment ($instance.mauth.nevis.cloud
).
- Android/Kotlin
- Android/Java
- iOS/Swift
- Flutter/Dart
On-premise backends
For those cases where your application interacts with an on-premise deployment, use the generic initializers (java: Configuration.Builder, swift: Configuration(baseUrl:), flutter: Configuration(baseUrl:)) to obtain a Configuration
object. These initializers allow you to specify the relative paths for each of the endpoints required by the SDK.
- Android/Kotlin
- Android/Java
- iOS/Swift
- Flutter/Dart
Facet ID
The facet ID of your application has to match the list of allowed facets stored provided by the facet service of the backend.
The most common developer issue when integrating and testing the SDK is a mismatch between the client and backend facetIDs, specifically for applications running on the Android platform.
Always ensure, that your backend facetID configuration matches the client one.
The backend HTTP API serving the facets must be unprotected according to the UAF 1.1 specification. If you know the correct URL, you will be able to quickly verify the backends facets configuration.
- Nevis Authentication Cloud:
https://<your-cloud-instance>.mauth.nevis.cloud/_app/uaf/1.1/facets
- On-Premise:
https://<your-domain>/nevisfido/uaf/1.1/facets
(This can differ according to configuration)
For backend configuration instructions, see one of the following documents:
- The Admin4 guide for on-premise backends configured using Admin4.
- The nevisFIDO reference guide for on premise backends configured manually.
- The Authentication Cloud documentation if you are using the Nevis Customer Authentication Cloud.
The format of the facet ID differs between platforms:
Android facet ID
According to the FIDO UAF 1.1 Specifications, the facet ID on Android should follow the android:apk-key-hash:HASH_VALUE
format where the HASH_VALUE
is Base64 encoded SHA-256 hash of the APK signing certificate.
For example android:apk-key-hash:z7Xkw62dAn/Bue3mKpYrOZ9zSPC7b4mbgzJmdZEDO5w
.
If you modify the certificate used to sign your application, the value of the facet ID changes. So, a change of the certificate implies the need to recalculate the facet ID again, and reconfiguring the server with the new facet ID.
Providing the facet ID in Configuration
For convenience, the Configuration.facetId method allows you to provide the facet ID of the application. By providing a constant facet ID, temporary changes in the application signing certificate do not require changes in the backend. However, for production code, the FIDO UAF specification must be used, that is, by calculating the facet ID as described above.
- Kotlin
- Java
In the example above, the facet ID to add to the list of facet IDs in the server is android:apk-key-hash:fakehash
.
Calculating the facet ID inside a mobile application
The following code returns the facet ID when executed from inside the application:
- Kotlin
- Java
Calculating facet ID using keytool command-line
You can calculate the hash using the following command:
keytool -keystore <path-to-apk-signing-keystore> \
-alias <alias-of-entry> \
-exportcert -storepass <keystore-password> 2> /dev/null | \
openssl sha256 -binary | \
openssl base64| \
sed 's/=//g'
iOS facet ID
In the case of an iOS application, the format of the facet ID is ios:bundle-id:<ios-bundle-id-of-app>
.
For example ios:bundle-id:ch.nevis.accessapp
Flutter facet ID
In the case of a Flutter application, both Android and iOS facet IDs are needed. Read the chapters above on how you calculate them.