Biometric/Pin

Cotter's Android SDK helps you easily add a Biometric prompt or PIN fallback to your app. This is useful for protecting transactions or sensitive information like medical records.

There are major updates planned for this feature. Contact us in Slack so we can help you prepare for it.

Overview

Enabling PIN and Biometric using Cotter's Android SDK consists of:

1. Initializing Cotter

2. Calling functions to start Pin Enrollment and Biometric Enrollment

3. Verify Biometric or PIN before a transaction

4. Enabling and disabling Biometric or PIN in Settings

What you're building

PIN and Biometric using Cotter's Android SDK

Steps

1. Import Cotter as a dependency

2. Set allowed Authentication Methods in the Dashboard

3. Create a User

4. Initialize Cotter in your Main Activity

5. Enroll Biometrics and PIN: PIN is recommended as a fallback method

6. Verify Biometrics before a transaction

Step 1: Import Cotter as a dependency

Add JitPack repository your project level build.gradle at the end of repositories.

build.gradle

allprojects {
		repositories {
			...
			maven { url 'https://jitpack.io' }
		}
	}

Add the Cotter's SDK as a dependency in your app level build.gradle .

android {
  ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

dependencies {
  ...
  implementation 'com.github.cotterapp:android-sdk:0.3.2'
}

Check the latest version here https://github.com/cotterapp/android-sdk/releases.

Then sync your gradle files.

Step 2: Setting Authentication Methods

You need to set allowed methods for authenticating your users. To allow PIN and BIOMETRIC, go to https://dev.cotter.app/rules

Set both Biometric and PIN to be allowed

Remember to set the correct Project in the dropdown list.

Step 3: Creating a User

1. Registering a User

Your server should do this request to Cotter's server during Registration.

Request

curl -XPOST \
-H 'API_KEY_ID: <your key id>' \
-H 'API_SECRET_KEY: <your secret key>' \
-H "Content-Type: application/json" \
-d '{"client_user_id": "<Your User Identifier (string)>"}' \
'https://www.cotter.app/api/v0/user/create'

Response

{
  "ID": "9449e9e9-00e0-4d6b-a4b6-28c5b22b0b0f",
  "created_at": "2020-01-21T12:40:21.200727668Z",
  "update_at": "2020-01-21T12:40:21.200727668Z",
  "deleted_at": null,
  "issuer": "<your key ID>",
  "client_user_id": "<Your User Identifier (string)>",
  "enrolled": [],
  "default_method": null
}

Check out Create a User API Reference for full Description

2. Get user data

To retrieve user's data:

Request

curl -XGET \
-H 'API_KEY_ID: <your key id>' \
-H 'API_SECRET_KEY: <your secret key>' \
'https://www.cotter.app/api/v0/user/:your_user_id'

Response

{
  "ID": "9449e9e9-00e0-4d6b-a4b6-28c5b22b0b0f",
  "created_at": "2020-01-21T12:40:21.200727668Z",
  "update_at": "2020-01-21T12:40:21.200727668Z",
  "deleted_at": null,
  "issuer": "<your key ID>",
  "client_user_id": "<Your User Identifier (string)>",
  "enrolled": ["PIN", "BIOMETRIC"],
  "default_method": "BIOMETRIC"
}

Check out Get User API Reference for full Description

Step 4: Initialize Cotter

You can now use the SDK to enroll and verify Biometric and PIN for the user you just created.

Initialize

In your MainActivity, initialize Cotter with API keys, Cotter's URL to use (prod/test), and your User ID.

Production Endpoint: https://www.cotter.app/api/v0

Cotter.init(
    this.getApplicationContext(),
    "https://www.cotter.app/api/v0",
    "<User ID>",
    "<API_KEY_ID>",
    "<API_SECRET_KEY>"
);

Example:

MainActivity.java

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...

        Cotter.init(
            this.getApplicationContext(),
            "https://www.cotter.app/api/v0",
            "[email protected]",
            "588d6f67-0981-4718-899b-bcd512de1aca",
            "w4FK6Zz0XIhtGY3o5biI");
    }
    ...

Step 5: Enroll Biometric and PIN

to enroll both Biometric and PIN, start the PinEnrollment flow in your Activity, pass in the Callback Screen, and the Event Tag. Event Tag is used for your own logging, for example, a pin enrollment event can be called "PIN_ENROLLMENT_ANDROID" to tag a pin enrollment event from an Android device.

Cotter.PinEnrollment.startFlow(view, CallBack.class, "EVENT TAG");

Example:

// Inside your app, use a button onClick that calls
// openEnroll to start the flow
public void openEnrollment(View view) {
    Cotter.PinEnrollment.startFlow(view, Dashboard.class, "PIN_BIO_ENROLLMENT");
}

How PinEnrollment looks like

After entering the PIN, the user will automatically be prompted to Enroll Biometrics if the device supports it. Entering a PIN is required as a fallback method.

PinEnrollment Flow

Step 6: Verify Biometrics on Transactions

The PinVerification flow will automatically prompt for Biometric Verification if the user's device has an enrolled biometric, otherwise, it will fallback to entering PIN. Starting the PinVerification flow is exactly the same as starting the PinEnrollment flow.

Cotter.setOnResetPin(new PinResetInterface() {
            @Override
            public void onResetPin(User user, Callback callback) {...}
})
Cotter.PinVerification.startFlow(view, CallBack.class, "EVENT TAG");

In the verification page, there is a button called Forgot PIN . This is used to send a verification code to allow the user to reset their PIN.

setOnResetPin is used to set a callback function that will be called to reset the pin. You need to provide a function that follows the PinResetInterface. This function should call your server to initiate the PIN reset request.

When your onResetPin function is called, it should call your server, and your server needs to do the following:

1. Based on the currently logged-in user, find out the user's Email and name

2. Call Cotter's Reset PIN API to send the pin reset code

3. Receive the response from Cotter which contains the fields success, challenge_id, challenge

4. Call the callback.onSuccess with a JSONObject containing the following JSON object:

{
  "success": true,           // from the response from the Reset PIN API
  "challenge_id": 123,       // from the response from the Reset PIN API
  "challenge": "abcde12345", // from the response from the Reset PIN API
  "sending_method": "EMAIL",
  "sending_destination": "[email protected]"
}

Example:

// In onCreate, set the onResetPin callback
protected void onCreate(Bundle savedInstanceState) {
     Cotter.setOnResetPin(new PinResetInterface() {
        @Override
        public void onResetPin(User user, Callback callback) {
            // 1. Call your server
            // 2. Get the response from your server
            // 3. Construct a JSONObject and pass it to callback.onSuccess
            JSONObject req = new JSONObject();
            try {
                req.put("success", response.getBoolean("success"));
                req.put("challenge_id", response.getInt("challenge_id"));
                req.put("challenge", response.getString("challenge"));
                req.put("sending_method", sendingMethod);
                req.put("sending_destination", sendingDestination);
            } catch (Exception e) {
                callback.onError(e.toString());
            }
    
            callback.onSuccess(req);
        }
    });
}

// Inside your app, use a button onClick that calls
// openPinVerification to start the flow
public void openPinVerification(View view) {
    Cotter.PinVerification.startFlow(view, Dashboard.class, "LOGIN");
}

Reset PIN functionality is an update that is available starting from version 0.4.5

🎉 You're done!