Custom Logintap 0Auth Integration

LoginTap is set up much like any other 0Auth service (like Google or Facebook logins, for example).

Just 2 API methods and a call-back URL on your side allow for over 10 different auth use cases.

Note, that examples we provide are just samples, not a dogma. You can modify any parts, to better fit your needs.


2
Biometry only, Messengers + Biometry, Messengers only
3
API Methods
A step by step instruction to start Logintap at any site
Quick overview

1. Register with LoginTap and create a new project. Decide on auth points and auth method.

2. Prepare your backend - you will need a call-back URL and a couple of API calls. To speed up API work download our PHP library (PHP5, PHP7 or WordPress plugin as archive, or from the WP Plugins Store). You can also download the Postman collection of API methods.

3. Make desired changes to your front end. You can use our JS code samples and our premade icons/buttons if you want to.

1. Ways to use Logintap (Auth Points)

You can implement various auth starting points to initiate the mobile auth, for example:

Https://yourwebsite.com
2.1 No Login, No Password
2.2 Login, but No Password
>
>
>
Https://yourwebsite.com
>
>
Https://yourwebsite.com
Enter Login
Press for Mobile Auth
2.3 Full auth, then 2FA
Https://yourwebsite.com
>
>
Https://yourwebsite.com
You Login
& Pass are Correct
Waiting for your Mobile Confirmation
Waiting for your Mobile Confirmation
User is recognised via cookie (or alike). No logins/passwords, all is done through Logintap mobile 2FA.

It is for maximum speed and convenience for your users.
User enters login, presses the Login button, and the rest is done via Logintap 2FA.

As a sub case - user forgot a password, gets instant access from just the login.
User first passes full standard auth with login and password, then start the Logintap's mobile 2FA.

Less convenient, but some maximum security is perceived.
2. Authentication methods

There are 3 basic authentication methods with different level of convenience and security:

2.1 Messengers only
Best for use cases where a simple Yes or No from a user in a mobile instant messenger is enough. Like e-commerce or non business crucial products.

Security is provided by tokens from each messenger. If a user has it installed elsewhere, say on desktop, a Yes response will also be accepted.
2.2 Biometry only
2.3 Biometry + Messengers
Best for use cases where using a messenger is not an option, for example some corporate software; or when all users are on mobiles only and messenger becomes an extra step.

Security is extremely high and provided by biometry of the mobile device using the WebAuthn protocols.
Best for cases where user base is highly desktop ( so it is very fast to open Push on a mobile) maximum security is needed and messengers can be used without any corporate related concerns.

Security is provided by both messenger tokens and device biometry through WebAuthn.
3. API Methods
3.1 Authenticate API Calls
3.2 Create Users and Authenticate their Logins
3.3 Important Options ( like your own user ID, to make integration easier)
3.4 An overall logical schema

3.1 Authenticate API Calls
There are 2 methods to receive and update API tokens.

To get new tokens:

GET - {{url}}/api/v8/auth?login={{userLogin}}&password={{userPassword}}

where:
URL = is ALWAYS your account's URL address, for example -
https://test-admin.logintap.com/api/v8...
login = your email on the Lofgintap account- password = your Logintap account password

In response, you get access (varchar1000) and refresh (varchar1000) tokens and Unix time expiration date for the access token (7 days forward by default):
Please make sure you update the Access token BEFORE it expires using:

GET - {{url}}/api/v8/refresh?refresh_token={{refreshtoken}}

You will get new Access, Refresh and Expiration.

For all further requests use the access token in API headers as:

Bearer {{access_token}}
note the SPACE symbol in between
3.2 Create Users and Authenticate Logins

These are 2 major API methods:

POST - {{url}}/api/v8/object - creates new users

POST - {{url}}/api/v8/logintap/loginrequest - starts authentication process for users


CHOOSE YOUR AUTH TYPE BELOW, to see API calls and options for the 2 methods:

Create Users

Use the POST "object" call with 2 required and 1 optional parameter:

Key=Values for the Biometry Only type of auth:
Enabled = 1
ApplicationUUID = {{application ID from your Logintap account}}
webAuth_confirm = 1
In the response ↑ you get the following addributes for the object:

ID - integer - is an incremental counter of your users and is not required for any further operations
UUID - varchar255 - the same as objectUUID - a Unique User IDentifier is required for user authentication requests (see an option below called CustomUUID if you want to use your own UUID instead.
regURL - varchar255 - An address where you need to forward users to create a new biometric ID for them.

NOTE 1 - Biometric authentication tokens can ONLY be created from this POST - Object method, so make sure you provide this link only to known and verified users, for example after they passed your usual login/password, or in SMS/TXT to their known phone numbers.

NOTE 2 - transform this URL into QR when you want to auth users on desktops with their smartphones

NOTE 3 - if you are using biometric auth for mobile apps and website it is best to open this regURLs in iFrame inside of your existing UI, to keep the UX flow as simple as possible for users.

regShortUrl - varchar255 - same as above regURL, but shortened so you can insert it into SMS/TXT, email messages, and other places where it matters. Note that it uses our own AUT.HK address, standing for "auth key". You can send users the short URL with or without HTTPS:// as well.

Request User Authentication

Use the POST "loginrequest" call with 3 parameters for the Biometry Only type of auth:

objectUUID = {{from the POST object method above}} - the UUID received from object creation method
appUUID = {{application ID from your Logintap account}}

webAuth_confirm = 9
In the response you get the following data:

sessionUUID - varchar255 - is a unique identifier of the new auth session
tokenUUID - varchar255 - a unique security token of the session
channel - varchar255 - you can ignore this, as it shows that no Logintap auth delivery channels, like messengers, exist for the user
warning - varchar255 - should be empty if all is ok, an example would be a notification that your plan is over limit (auth will still happen)
webAuth_state - integer = 1 means the IDed by objectUUID user has biometry previously connected, when = 0 - no biometry is connected
regURL - varchar255 - an address to send users to verify their biometry
regSHortUrl - varchar255 - same as above, for places where you need a short link

NOTE - if you are using biometric auth for mobile apps and website it is best to open this regURLs in iFrame inside of your existing UI, to keep the UX flow as simple as possible for users

NOTE - transform this URL into QR when you want to auth users on desktops with their smartphones

Get User Authentication Response

Logintap will send a POST request of user authentication to the webhook's call back URL you set up and connect in Logintap project's settings:

Contect of each POST message:
sessionUUID - is a unique identifier of the auth session
tokenUUID - a unique security token of the session
objectUUID - a unique identifier of the object/user
loginState = 1 or 0, shows if user has passed (1) or not passed (0) biometry test


COMPARE data received of the call-back received with UUIDs from the earlier "loginrequest" API call.

For example::

$id = $pdb->exist([
                'sessionuuid' => $_POST['sessionUUID'],
                'objectuuid' => $_POST['objectUUID'],
                'tokenuuid' => $_POST['tokenUUID'],
            ], $table)['id'];

If all UUID records match and "loginstate" = 1 - you can allow the user to enter.
If any of this is not true - login should be forbidden.
The Overall Integration Schema

1. Steps 1-2-3 at the bottom - Create New User (green), Connect User to Auth (orange), Auth on Entry (pale red)

2. Every step has outgoing and incoming data points, colored to match the steps above for easy view of sources and destinations.

3. Bright Red are REQUIRED elements of the schema to make0Auth work, the rest are for user convenience, internal stats, etc.

Two of the fields above are filled by running "createObject" method from the PHP library. Response of it are two fields "objectuuid" and "shortlinks" for each of you users. Record the following response into corresponding fields of your user's table above:

            "type": "objects",
            "id": "1",
            "attributes": {
                "uuid": "dlb01ce9-d13a-4f5b-8k71-e3c1ffb58030",
                "shortlinks": {
                    "viber": "https://auth.logintap.com/5AnlT",
                    "facebook": "https://auth.logintap.com/9z3Ka",
                    "telegram": "https://auth.logintap.com/17LWo",
                    "vk": "https://auth.logintap.com/1kY07"
                } } 


Object's "UUID" is your user's ID within Logintap, it is alphanumeric, record it to "lt-objectuuid". We call it "object" to be different from your "user", to avoid confusion, which ID is used and when. The "shortlinks" field contains JSON array for mobile messenger connections, record it in full to "lt_shortlinks".

IMPORTANT: Two different strategies for "createObject" method:

(1) pre-create all objects for your users in advance, one by one, and allow any time period between object creation and user opt in to use mobile 2FA;
(2) create objects for you users, only when a user opts in for mobile 2FA.

First strategy cuts a bit of time for each user during 2FA setup process. Second is a simpler and continuous flow process. We don't charge for just storing idle objects, so the choice is yours.


6.
The other two lines of the above table you fill when user actually connects a messenger. Place a listener/handler at the CallBack URL address you have chosen in setting for the website. It must recieve POST requests. It will recieve two kinds of POST messages from Logintap:


First, a POST response when your new user actually connects a messenger for Logintap auth. Identify for which user/object you just got a call back and add that into "lt_channel" and "lt_channelstate" fields of your user table:


ObjectUUID is for ID purposes, you already have it from "createObject" method. ChannelState as "1" indicates that a messenger is set and valid. "Channel" itself is just a name for your own stats, to see who is using which messenger.

You can use this data to show users reminders about a need to connect their second factor auth to improve safety or ease or both. For example, if "channel" is not 1, show a pop up offering a security of 2FA.




Second, a POST response to callback URL after each of "loginRequest" API calls. You make these calls to auth every login of every user to your website. Record data from this POST to your "lt_auth_sessions" table:

VERY IMPORTANT - as before, storing auth sessions depends on your needs, if you have many users login at the same time, you do need to store these in a DB table, or in any other kind of storage available for you, otherwise you might skip this.

IMPORTANT - ONLY "LOGIN STATE" NEEDS RECORDING from this callback. Because at the moment when you receive this callback, you should have already recorded sessionUUID, objectUUID and tokenUUID from "loginRequest" method (see 4.3.3 below) and be just waiting for "loginState" response (1 = user confirms the login, 0 = does not).

So, when you get this call back - COMPARE all 3 pre-recorded UUIDs with the ones in this callback, to make sure the request has not been tampered with. If all matches, record the received 1 (yes) or 0 (no) "loginState" into "lt_logintstate" of the "lt_auth_sessions" table. An example of how to make a comparison:

$id = $pdb->exist([
                'lt_sessionuuid' => $_POST['sessionUUID'],
                'lt_objectuuid' => $_POST['objectUUID'],
                'lt_tokenuuid' => $_POST['tokenUUID'],
            ], $table)['id'];


All UUIDs matching and a "1" for loginState means auth is good and you can allow the user to enter.

4.3 Prepare your frontend


1. Place the following JS code into <head> sections of pages on which users will be offered to connect the mobile 2FA.

<script src="https://docs.logintap.com/mbst-qrw.js"></script>


2. Create a mechanism by which you will NOTIFY & ASK users to connect a mobile second factor auth. You can use a timer with a pop up, or it can be a button. For example, this is how it is done in your own Logintap account:


In this case a button press uses the following to call upon a JS widget:

var {meta: {shortlinks}} = await http.get('/logintap', {});
const messengers = shortlinks;
const QRW = window.MBST.qrw;
QRW.show(messengers);


Pass here the "shortlink" and "uuid", which you got with "createObject" API method and saved to your users table into fields "lt_shortlink" and "lt_objectuuid".

AGAIN NOTE (as in 4.2.5) - when to run "createObject" API method is entirely up to you. You can sync all of your users upon launching Logintap, or you can quickly run it when a user starts connecting the 2FA procedure.


3. Customize your standard login form according to how you want to Logintap (refer to section 2 - Auth Points above, with examples 2.1, 2.2 and 2.3). Below is an example of how Logintap uses it's own auth:


In this case when a user presses "Logintap" button, we perform "loginRequest" API call. It is up to you to decide how you recognise your users, we do it with email (again refer to section 2 - Auth Points).

Logitap service responds to "loginRequest" with new "sessionUUID" and "tokenUUID". You create a new record in your "lt_auth_sessions" table with it and ADD the current objectUUID, as well.


4. Inform user with text and Logintap's loader graphic element that mobile auth is in progress. Wait till user reacts in a messenger with YES or NO. You will get a POST to your call back described in 4.2 Prepare you backend, paragraph 6, point 2.



5. Now, COMPARE these records, as described here, with the data you get on the call back url, to make sure it has not been compromised. If all is identical and the "loginState" came back as 1 - let the user in, otherwise show any kind of "no entry" message.
THAT'S IT