What you're building

Steps

1. ​Import Cotter as a dependency​

2. ​Set up Cotter in your Project​

3. ​Set Allowed Methods in the Dashboard to allow Trusted Devices

4. ​Register the current device as a Trusted Device​

5. ​Authenticate from a Trusted Device and Non-Trusted Device​

Step 1: Import Cotter as a dependency

yarn add react-native-cotter react-native-device-info rn-secure-storage react-native-randombytes react-native-camera react-native-svg react-native-securerandom buffer react-native-inappbrowser-reborn react-native-sha256
npx pod-install ios

npm install --save react-native-cotter react-native-device-info rn-secure-storage react-native-randombytes react-native-camera react-native-svg react-native-securerandom buffer react-native-inappbrowser-reborn react-native-sha256
npx pod-install ios

(Optional) Checkout additional steps for Android, React Native < 0.60, and Manual Installation.

Step 2: Set up Cotter in your Project

To allow Cotter to display modals, wrap your root component with connectCotterWrapper :

import {connectCotterWrapper} from 'react-native-cotter';
​
class MyApp extends Component {
}
​
MyApp = connectCotterWrapper(MyApp);

Step 3: Setting Authentication Methods

You need to set allowed methods for authenticating your users. To allow TRUSTED DEVICES, go to https://dev.cotter.app/rules​

Step 4: Register this device as a Trusted Device

After registering your user_id to Cotter using the API above, you should enroll the current device as the user's first Trusted Device.

import { Cotter } from "react-native-cotter";
​
class SignUp extends Component {
  ...
  onFinishRegistration = (userID) => {
    // Initialize Cotter
    var cotter = new Cotter(
      <API_KEY_ID>,
      userID,
      [email] // (optional) associated array of emails or phone numbers for the user
    );
    // Enroll device as Trusted Device
    cotter.trustedDevice.enrollDevice(
      this.onEnrollSuccess, 
      this.onEnrollError
    );
  };
​
  onEnrollSuccess = resp => {
    alert('Success');
    console.log(resp);
    
    //navigate to dashboard
    this.props.navigation.navigate('Dashboard');
  };
  
  onEnrollError = err => {
    alert('Error');
    console.log(err);
  };
  ...
}

​

Step 5: Authenticate from a Trusted Device and Non-Trusted Device

To request an authentication from Cotter's SDK, you would need to call cotter.trustedDevice.requestAuth . This will automatically detect whether the current device is a Trusted Device or not.

// Requesting an authentication using Cotter
var cotter = new Cotter(
  <API_KEY_ID>,
  userID,
);
cotter.trustedDevice.requestAuth(
  'EVENT NAME',
  this.onRequestSuccess,
  this.onRequestError,
);

{
  "ID": 1361, // Event ID
  "CreatedAt": "2020-02-27T22:22:48.705212512Z",
  "UpdatedAt": "2020-02-27T22:22:48.705212512Z",
  "DeletedAt": null,
  "client_user_id": "1014", // your client's User ID
  "issuer": "afcabd98-745f-4b9e-98de-af968d9951d3", // your API Key
  "event": "<EVENT NAME>",// requested event (LOGIN, or TRANSACTION, etc)
  "ip": "192.168.232.2", 
  "location": "Unknown",
  "timestamp": "1582842167",
  "method": "TRUSTED_DEVICE", // auth method: TRUSTED_DEVICE (other choices are PIN / BIOMETRIC)
  "new": false, // Is this a new pending event. More explanation below about Non-Trusted Device
  "approved": true, // Is this event approved.
  "signature": "oonMGCAxp3..." // Signature to make sure this event comes from Cotter's server
}

How it works with your Login system:

For example, on your "Login" button, set onPress to this.authenticate . This will invoke Cotter's SDK to authenticate the user. You would need to:

1. (optional) Fetch the user_id you used for this user on Step 4 when you registered the user to Cotter. You can do this using a function like this.getUserID below to get user_id based on the email/phone. (If you're just using the email/phone as the user_id, that's fine too.)

2. Use the user_id to initialize a cotter object, and call cotter.trustedDevice.requestAuth. You can pass in an EVENT NAME here. This could be any string to tag the event type (LOGIN, TRANSACTION , etc).

3. Login your user by validating the Cotter's response in your backend server.

import { Cotter } from 'react-native-cotter';
​
class Login extends Component {
​
  // Start Authentication here
  authenticate = async () => {
    // (1) Getting user ID 
    // that you registered in Step 4 from YOUR BACKEND SERVER
    // based on the email/phone number 
    const userID = await this.getUserID(this.state.email);
​
    // (2) request authentication
    var cotter = new Cotter(
      <API_KEY_ID>,
      userID,
    );
    cotter.trustedDevice.requestAuth(
      'EVENT NAME',
      this.onRequestSuccess,
      this.onRequestError,
    );
  };
​
  onRequestError = (errorMessage, error) => {
    alert(errorMessage);
    console.log(error);
  };
​
  onRequestSuccess = response => {
    alert('Success');
    console.log(response);
    
    // (3) Login user in backend
    // Check how the `response` look like in the next tab above
    // Pass in the `response` to YOUR BACKEND SERVER when:
    // Logging in your users, making a transaction, or fetching sensitive data
    this.submitLogin(response);
  };
  ...
}

Trusted and Non-Trusted Device

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 response 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).
  "signature": "oonMGCAxp3..." // Signature to make sure this event comes from Cotter's server
}

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 Event Response to your backend, you need to check if this JSON is valid and if it comes from Cotter's server.

Learn how to Validate Cotter's Event Response here:

Case 2: The current device is NOT a Trusted Device

We'll cover this in the next guide:

🎉 You're done!