Home

Awesome

WebAuthnDemo Kotlin

Introduction

Welcome to the WebAuthnDemo Kotlin! This sample application demonstrates how to integrate and utilize the webauthn-kotlin SDK in an Android application. It provides practical examples of using the SDK for implementing strong, password-less authentication using both biometric and device credential authenticators.

Features

Prerequisites

Before you begin, ensure you have the following installed:

Getting Started

To get started with the webauthndemo-kotlin, follow these steps:

1. Clone the git repositories:

# webauthndemo-kotlin
$ git clone https://github.com/line/webauthndemo-kotlin.git
# webauthn-kotlin
$ git clone https://github.com/line/webauthn-kotlin.git

2. Build the SDK using Gradle to create AAR file:

  1. Open webauthn-kotlin in Android Studio.
  2. Open Run Anything (Double Ctrl) or Gradle - Execute Gradle Task.
  3. Run gradle assembleRelease task.

Or you can use the command line:

$ cd webauthn-kotlin
$ ./gradlew assembleRelease

3. Publish the AAR file to the local Maven repository:

  1. Open Run Anything (Double Ctrl) or Gradle - Execute Gradle Task.
  2. Run gradle publishToMavenLocal task.

Or you can use the command line:

$ ./gradlew publishToMavenLocal

4. Launch a WebAuthn server.

We use the FIDO2 server here to run the sample application. Please refer to the README for instructions on how to run the server.

When setting up the server, you need to register the origin for your Android application. The origin is derived from the facetId as described in the FIDO AppID and Facet Specification for the Android case.

How to Obtain Facet ID for FIDO2 Server Registration

Debug Mode

To obtain the facet ID in debug mode, use the following command:

keytool -exportcert \
    -alias androiddebugkey \
    -keystore $HOME/.android/debug.keystore \
    -rfc | \
    openssl x509 -inform PEM -outform DER | \
    openssl dgst -sha256 -binary | \
    openssl base64 | \
    tr -d '=' | \
    tr -d '\n'
Release Mode

To obtain the facet ID in release mode, you need to replace the alias and keystore with your release key alias and keystore file. Use the following command:

keytool -exportcert \
    -alias your_release_key_alias \
    -keystore path/to/path_of_your-release-key.jks \
    -rfc | \
    openssl x509 -inform PEM -outform DER | \
    openssl dgst -sha256 -binary | \
    openssl base64 | \
    tr -d '=' | \
    tr -d '\n'

For instructions on creating keystore.jks / keystore.properties for release mode, please refer to the Additional configuration section below.

5. Change the domain of relying party in RetrofitClient.kt.

  1. Open webauthndemo-kotlin in Android Studio.
  2. Open RetrofitClient.kt file.
  3. Replace the domain "https://example.com" with the server domain you want to test.
private val BASE_URL_FIDO2 = "https://example.com"  <-  replace here

6. Install and run the application on your android device:

  1. From the top menu, select File > Sync Project with Gradle Files.
  2. Connect your Android device to your computer and run the application.

Additional Configuration

1. Create keystore.jks and set up keystore.properties for release

To sign your application for release, you need to create a keystore.jks file and set up a keystore.properties file. This step is optional and only necessary if you are planning to release your application.

1-1. Create keystore.jks file.

You can use Android Studio to create a new keystore file:

  1. Open Android Studio.
  2. Click on Build > Generate Signed Bundle / APK.
  3. Click on Create new... to create a new keystore file.
  4. Fill in the required fields and click OK.

Or, Use the keytool command to create a new keystore file. Open a terminal and run the following command:

keytool -genkeypair -v -keystore my-release-key.jks -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

1-2. Create keystore.properties file:

Create a new file named keystore.properties in the root directory of the project. Add the following lines to the file:

storeFile=path_of_your_keystore.jks
storePassword=your_store_password
keyAlias=your_key_alias
keyPassword=your_key_password

Now, build.gradle(app) automatically reads the keystore.properties file to sign the application for release.

Usage

The webauthndemo-kotlin is designed to demonstrate the functionality of the webauthn-kotlin SDK through a user-friendly interface. Below are the key features of the app and how to use them:

SIGN UP and SIGN IN Buttons

Account Management

LOG WINDOW

These features collectively showcase the capabilities of the WebAuthn Kotlin SDK, making it easier for developers and testers to understand and evaluate the implementation of FIDO2-based authentication in a real-world scenario.

Screenshots

Biometric Authenticator

<img src="./images/Biometric.gif" width="300" align="center" alt="biometric"/>

Device Credential Authenticator

You can use it in the same way as Biometric if you select "Use Device Credential" on the first screen.

License

Apache License 2.0. See LICENSE.

Contact Information

We are dedicated to making our work open-source to assist with your specific needs. We are eager to learn how this library is being utilized and the issues it resolves for you. To communicate, we recommend the following approach:

Please avoid sharing any sensitive or confidential information in the issues. If there is a need to discuss sensitive matters, please indicate so in your issue, and we will arrange a more secure communication method.