Passwordless.dev Documentation

Android Client SDK

The Passwordless.dev Android client SDK gives users the ability to leverage their device’s built-in fingerprint sensor and/or FIDO security keys for secure passwordless access to websites and native applications that support the FIDO2 protocols.

Requirements

Installation

Apache Maven
<dependency>
  <groupId>com.bitwarden</groupId>
  <artifactId>passwordless-android</artifactId>
  <version>1.0.1</version>
</dependency>

Permissions

In your AndroidManifest.xml, add the following permissions:

<uses-permission android:name="android.permission.INTERNET" />

Configuration (Android application)

Somewhere in your Android application, configure PasswordlessOptions.

data class PasswordlessOptions(
   // Your public API key
   val apiKey: String,

   // Identifier for your server, for example 'example.com' if your backend is hosted at https://example.com.
   val rpId: String,

   // This is where your Facet ID goes
   val origin: String,

   // Where your backend is hosted
   val backendUrl:String,

   // Passwordless.dev server, change for self-hosting
   val apiUrl: String = "https://v4.passwordless.dev"
)

In your application's AndroidManifest.xml, add the following tag under manifest::application:

<meta-data
  android:name="asset_statements"
  android:resource="@xml/assetlinks" />

In your application's res/xml/assetlinks.xml, you will then need to add the following content. This will tell our Android application where your .well-known/assetlinks.json file is hosted.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="assetlinks">https://yourexample.com/.well-known/assetlinks.json</string>
</resources>

Facet ID

The Facet ID will be used later in this guide as the origin.

To obtain the Facet ID continue the steps below, the Facet ID typically looks like:

android:apk-key-hash:POIplOLeHuvl-XAQckH0DwY4Yb1ydnnKcmhn-jibZbk

  1. Execute the following command in your terminal:
Bash
# Linux, Mac OS, Git Bash, ...
keytool -list -v -keystore ~/.android/debug.keystore | grep "SHA256: " | cut -d " " -f 3 | xxd -r -p | basenc --base64url | sed 's/=//g'

  1. The default password for the debug keystore is android. For your production keystore, enter your chosen password.

  2. Now append the result to android:apk-key-hash: to get the Facet ID:
    android:apk-key-hash:POIplOLeHuvl-XAQckH0DwY4Yb1ydnnKcmhn-jibZbk

Configuration (Your back-end)

Obtaining the SHA-256 Certificate Fingerprints

To configure your backend, you'll need to host a .well-known/assetlinks.json file at the root of your domain. This file contains a list of SHA-256 certificate fingerprints that are allowed to authenticate with your backend.

The following command will print detailed information about the keystore entry with the specified alias, including information about the certificate, its validity, and other details. It's commonly used in Android development to verify the properties of the debug keystore and the associated key used for signing applications during development.

Gradle

Go to the root directory of the project from the terminal and run the below command:

./gradlew signingReport

Put this SHA256 along with your root Android package name in your backend to generate assetlinks.json for your app at https://yourexample.com/.well-known/assetlinks.json.
If you are using example-nodejs-backend, then just put these 2 values in your .env file.

You will need store the following file at https://<your-domain>/.well-known/assetlinks.json. To generate the SHA256 hash, read the links below the snippet.

You may also have to change the 'target::namespace' and 'target::package_name' properties to match your application's.

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "web"
    }
  },
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapplication",
      "sha256_cert_fingerprints": [
        "3C:E2:29:94:E2:DE:1E:EB:E5:F9:70:10:72:41:F4:0F:06:38:61:BD:72:76:79:CA:72:68:67:FA:38:9B:65:B9"
      ]
    }
  }
]

Using the PasswordlessClient

With Dagger Hilt

You can either set the ActivityContext and CoroutineScope by injecting it with Dagger Hilt as follows:

@Module
@InstallIn(ActivityComponent::class)
class PasswordlessModule {
    @Provides
    fun provideLifecycleCoroutineScope(activity: Activity): LifecycleCoroutineScope =
        (activity as AppCompatActivity).lifecycleScope

    @Provides
    @ActivityScoped
    fun providePasswordlessClient(
        @ActivityContext activity: Context, scope: LifecycleCoroutineScope): PasswordlessClient {
        val options = PasswordlessOptions(
            DemoPasswordlessOptions.API_KEY,
            DemoPasswordlessOptions.RP_ID,
            DemoPasswordlessOptions.ORIGIN,
            DemoPasswordlessOptions.API_URL
        )

        return PasswordlessClient(options, activity, scope)
    }
}

Registration

  1. UI:
    • (Required) Specify the username for the credential.
    • (Optional) Take the alias as input from the user if it's a non-discoverable credential.
  2. Call POST /register/token implemented in your backend: Your backend should call the Passwordless.dev API to generate a registration token.
  3. Call PasswordlessClient.register():
// Pass the registration token to PasswordlessClient.register()
_passwordless.register(
    token = responseToken,
    nickname = nickname
) { success, exception, result ->
    if (success) {
        Toast.makeText(context, result.toString(), Toast.LENGTH_SHORT).show()
    } else {
        Toast.makeText(context, "Exception: " + getPasskeyFailureMessage(exception as Exception), Toast.LENGTH_SHORT).show()
    }
}

Logging in

  1. UI: Optionally, take the alias as input from the user if it's a non-discoverable credential.
  2. Call PasswordlessClient.login(): Initiate the login process with the (optional) alias and response callback.
  3. Call POST /signin/verify implemented in your backend: Your backend should call the Passwordless.dev API to generate a login token. 
// Call PasswordlessClient.login() with the alias
_passwordless.login(alias) { success, exception, result ->
    if (success) {
        lifecycleScope.launch {
            // When successful, call your backend to verify the token, which could for example return a JWT token.
            val clientDataResponse = httpClient.login(UserLoginRequest(result?.token!!))
            if (clientDataResponse.isSuccessful) {
                // Login successful. Parse the response or JWT token and proceed.
                val data = clientDataResponse.body()
                showText(data.toString())
            }
        }
    } else {
        showException(exception)
    }
}

Sample

You can find the source code for a sample application hereopen in new window.

Registration 1

Registration #1

References