LiveEnsure Python SDK

This is the LiveEnsure® Python DEMO SDK for LiveEnsure Authentication (www.liveensure.com)

From this SDK you will be able to launch a full API stack in Django and demonstrate the full capabilities of LiveEnsure® Authentication for web, cloud, apps and mobile.

The SDK is provided to illustrate how to integrate LiveEnsure® with your identity, web or app platforms. For futher information, visit the SDK docs at http://developer.liveensure.com

You will need to obtain LiveEnsure® developer API keys to test this API and sign up for a paid LiveEnsure service subscription to use the API/SDK in production.

This SDK functions in desktop-browser and mobile-browser (app to app) modes, depending on how you access the pages. From a desktop, you will scan with the free LiveEnsure app to authenticate based on the settings you configure to drive the API. If you acccess the pages from your mobile device, the SDK will behave in an app-to-app fashion, rolling over to authenticate as in an app or mobile HTML implementation, without providing or requiring a scan step.

For questions about this SDK or LiveEnsure® authentication, visit support.liveensure.com

Getting Started

• First, sign up at http://www.liveensure.com/signup.html for your developer API keys.
• Second, download the free LiveEnsure app for iOS or Android http://www.liveensure.com
• Third, download, configure and run this SDK on your local or networked machine as instructed.

Prerequisites

Below packages need to be installed and configured:

• network accessible server (or virtual instance)
• Python 2.7+, Django - 1.10.2, requests-2.10.0.
• Obtain LiveEnsure® developer API keys by signup (http://www.liveensure.com/signup.html) and then click the link "Send me my credentials by email" after login
• Google MAP api key (optional for location factors)

Installing

To install liveensuredemo app, run the following command

pip install -e git+https://github.com/LiveEnsure/PythonDjangoSDK#egg=liveensuredemo

Configuration

• Add following names to INSTALLED_APPS in your settings (settings.py) like this:

  INSTALLED_APPS = [
     ...
     'liveensuredemo',
     'sslserver'
   ]

• Include the app URLconf in your project urls.py like this:

  url(r'^liveensure/', include('liveensuredemo.urls')),

• Include following setting in your settings.py file:

LIVE_ENSURE = {
  "API_KEY": "<API key for liveensure>",
  "API_PASSWORD": "<API password>",
  "AGENT_ID": "<Agent ID for liveensure>",
  "API_HOST": "<API host to access liveensure API>",
  "GOOGLE_MAP_KEY": "<Optional Google Map key to access map to run location auth demo>"
}

• This app uses session to store session data, if django installation is new and migrations were never run, then run the migrations using:

python manage.py migrate

• Start server on specific port to access app using below command:

python manage.py runsslserver 0.0.0.0:8000

Running the SDK

Explain how to launch, run the automated tests for this system Make sure you cover how to bind Django to extenral IP so they can see it from their phone if need be (ifconig -a, find IP, etc)

Desktop/Browser Authentication via Mobile Scan

Walk through each factor tab and how to test/engage desktop with mobile scan.

[1] To test to basic device authentication factor, simply click [DEVICE] tab, enter your email and click login. Scan screen to authenticate.

On your first login, you will get an emailed OOB token to enter/register in app.

[2] To test knowledge challenge, click the [Knowledge] tab, enter your email and choose a challenge question and anwner/response. This is teeing up the API, as the end-user would not see this. Then click and scan, enter response to challenge in the device, to authenticate.

[3] To test location, click the [Location] challenge, enter email and click the map to register your current lat/long. If you want location to pass, simply login, scan and pass location proximity test. If you want it to fail, drag the map to an alternate location, login and fail due to proximity difference.

[4] To test behavior, click the [Behavior] tab and choose an orientation, and a grid pattern (up to 2 places) for single or multi-touch on the device.

Click login and touch and hold the desired locations AS YOU SCAN, until it beeps. To fail, tap wrong locations on the screen or release before you scan.

In the demo you can only choose one factor per test, but in the full API SDK you can add multiple challenges in combination as needed.

App to App Mobile Authentication via App Only

Walk through each factor and how to test/engage from mobile browser to the mobile app, from app-to-app (no QR scan).

First, access the demos from a mobile browser on iOS on Android.

For the mobile demos, repeat the steps as above, except you will rollover from mobile browser to app to authenticate after each "login" press/tap.

For behavior, you must hold the touch locations while and until the clock sweeps, since there is no scan.

The rest of the demos function as they do in the desktop version.

Using the SDK with your own stack/app/code

To use the SDK in your own code, You can copy api.py in your own stack. It is a class based implementation of all the api, which internally calls the liveensure API using requests.

This can be used as follows:

• Create LiveEnsure object (required)

  # api_key is the API key for liveensure
  # api_password is the API password for liveensure 
  # agent_id is the Agent ID for liveensure
  # host_to_access_API is the Host location where API's are hosted
  
  # Make sure you have all these keys before you start using the APIs
  
  liveAuthObj = LiveEnsure("<api_key>", "<api_password>", "<agent_id>", "<host_to_access_api>")

• Start session (required)

  # email is the user id for which authentication is to be done

  liveAuthObj.initSession("<email>")

It will return JSON object which have the sessionToken, that will be used in all subsequent calls.

• Add factors (optional)

  • Add knowledge challenge

    ```          
      # question is the question to be asked after scanning the code
      # answer is the answer to the question 
      # session Token is the session key that is returned by initSession call.
    
      liveAuthObj.addPromptChallenge('<question>', '<answer>', '<sessionToken>')
    ```
    

    It will return json object with status of the API call.

  • Add location challenge

    ```
      # lat is latitude of location
      # lang is the longitude of the location
      # radius is the radius limit of location authentication
      
      liveAuthObj.addPromptChallenge('<lat>', '<lang>', <radius>, '<sessionToken>')
    ```
    

  • Add behaviour challenge

    ```
      # orientation is the orientation of mobile phone used to scan the 
      # code. It can have 4 values range from 0 to 3
      # 0 -> Portrait
      # 1 -> Upside down
      # 2 -> Landscape Left
      # 3 -> Landscape Right
      
      # touches number of touch points up to 6
      liveAuthObj.addTouchChallenge('<orientation>', '<touches>', '<sessionToken>')
    ```
    

• Get the session token (required)

liveAuthObj.getAuthObj("<TYPE>", "<sessionToken>")

• Create the login object/link to scan or tap (required)

TBD ....

This is the moment the user scans or taps on mobile to authenticate and performs their authentication factors as configured above. During this process you may poll for status in the background.

• Poll for session status (required)

liveAuthObj.pollStatus('<sessionToken>')

• Delete user (optional)

  # email: email of the user that is to be deleted
  liveAuthObj.deleteUser('<email>')

Built With

• Django-1.10.2
• Bootstrap
• Google Map APIs
• LiveEnsure Authentication APIs

Versioning

Current Version: 0.01

Authors

• Christian Hessler - Author - LiveEnsure
• Narender Poonia - Author - LiveEnsure

License

This project is proprietary software (c) 2020 LiveEnsure Inc. Visit http://www.liveensure.com for more information.

Contact

• Web: http://www.liveensure.com
• Dev: http://developer.liveensure.com
• Support: http://support.liveensure.com

=======