Concepts: Learn about how Sign in with Device works.

Overview

Authenticating users using Trusted Devices with Cotter's Android SDK consists of the following steps:

1. Import and Initialize Cotter

2. Sign up a new user and trust the current device

3. Sign in existing user from a Trusted and a Non-Trusted Device

What you're building

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.4.0'
}

Check the latest version here https://github.com/cotterapp/android-sdk/releases. Then sync your gradle files.

Step 2: Initialize Cotter

You can now use the SDK to sign up a new user and setup the device as trusted, or sign in an existing user using the trusted device

In your MainActivity, initialize Cotter with your API_KEY_ID. You can get it from the Dashboard.

Cotter.init(
    this.getApplicationContext(),
    "<API_KEY_ID>",
);

Example:

MainActivity.java
public class MainActivity extends AppCompatActivity {
​
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
​
        Cotter.init(
            this.getApplicationContext(),
            "<API_KEY_ID>",
        );
    }
    ...

Step 3: Sign Up a New User and Register This Device as Trusted

1. The user should enter an identifier (an email, phone number, or username).

2. The SDK will register a new user with that identifier, and then enroll the current device as a Trusted Device.

Cotter.signUpWithDevice(this, userEmail, new Callback() {
    @Override
    public void onSuccess(JSONObject result) {
        Toast.makeText(getApplicationContext(), result.toString(), Toast.LENGTH_SHORT).show();
        Log.e("Success Register Device", result.toString() );
    }
​
    @Override
    public void onError(String error) {
        Toast.makeText(getApplicationContext(), error, Toast.LENGTH_SHORT).show();
    }
});

{
  "ID": "abcdefgh-abcd-abcd-abcd-571d2e2772c7", // Cotter User ID
  "client_user_id": "abcdefgh-abcd-abcd-abcd-571d2e2772c7",
  "created_at": "2020-07-23T23:29:21.85269Z",
  "default_method": "TRUSTED_DEVICE",
  "deleted_at": "0001-01-01T00:00:00Z",
  "enrolled": [
    "TRUSTED_DEVICE"
  ],
  "identifier": "[email protected]",
  "identifiers": null,
  "issuer": "YOUR_API_KEY_ID", // this is your API Key ID
  "oauth_token": {
    "access_token": "eyJhbGciO...",
    "id_token": "eyJhbGciOiJFU...",
    "refresh_token": "3:LGOY0pIVof6LgkWo...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "auth_method": "TRUSTED_DEVICE"
  },
  "updated_at": "2020-07-23T23:29:22.090131709Z"
}

This method is only for the first Trusted Device. You will get an error if you attempt to enroll another Trusted Device using enrollDevice when there's already a Trusted Device for the account. To enroll other devices, see Add a new Trusted Device.

Step 4: Authenticate from a Trusted Device

To authenticate a device, call the Cotter.signInWithDevice function. This will automatically detect whether the current device is a Trusted Device or not.

Cotter.signInWithDevice(this, userEmail, this, Dashboard.class, new Callback() {
    @Override
    public void onSuccess(JSONObject result) {
        Toast.makeText(getApplicationContext(), result.toString(), Toast.LENGTH_SHORT).show();
        Log.e("Success logging in", result.toString() );
    }
​
    @Override
    public void onError(String error) {
        Toast.makeText(getApplicationContext(), error, Toast.LENGTH_SHORT).show();
    }
});

Parameters

signInWithDevice(Context ctx, String identifier, AppCompatActivity act, Class callbackClass, Callback callback)

• identifier: Your user's identifier (email/phone/username) that was used to register this user in Step 3.

• callbackClass : The next activity class that you want to redirect to when the authentication request is finished

• callback : A custom Callback function that implements 2 methods: onSuccess and onError.

When an Authentication Event is requested using method TRUSTED_DEVICE, there are 2 possible cases:

Case 1: The current device is a Trusted Device

If the current device is a Trusted Device, it should automatically be approved, and you will receive a JSON result containing the requested Event and whether or not it's approved. The approval is based on whether or not the signature included in the request from the SDK is valid.

{
  ...
  "method": "TRUSTED_DEVICE",
  "new": false, // Is this a new pending event (should be false).
  "approved": true, // Is this event approved (should be true).
  
  "oauth_token": {
    "access_token": "eyJhbGciOiJFUz...", // validate this access token
    "id_token": "eyJhbGciOiJFUz...",
    "refresh_token": "5:cYIfabtspE1cBeD7KP...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "auth_method": "TRUSTED_DEVICE"
  }
}
​

You should see a result that the event is not new, and that it's approved. This is because the signature from the Trusted Device is sufficient to prove that the device is authorized.

When passing this Response to your backend, you need to check if this JSON is valid and if it comes from Cotter's server by validating the access token.

Checkout how to verify the OAuth Tokens from Cotter here:

Case 2: The current device is NOT a Trusted Device

We'll cover this in the next guide:

🎉 You're done!

Next Steps