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.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 and refresh 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:

Biometry Only
Messengers Only
Biometry + Messengers
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 data:

ID - is an incremental counter of your users and is not required for any further operations
UUID - 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 - 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 - 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}}
appUUID = {{application ID from your Logintap account}}

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

sessionUUID - is a unique identifier of the new auth session
tokenUUID - a unique security token of the session
channel - you can ignore this, as it shows that no Logintap auth delivery channels, like messengers, exist for the user
warning - 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 = 1 means the IDed by objectUUID user has biometry previously connected, when = 0 - no biometry is connected
regURL - an address to send users to verify their biometry
regSHortUrl - 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 Authentication Reponse

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 in the webhook call-back with UUIDs recorded earlier from "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 user to enter. If any of this is not true - login should be forbidden.
3. Basic Use Logic for Auth
7. Browser opens the link
Mobile User
1. Let users login with your standard auth (login/pass or SSO)
3.1 Create & connect a new user to LoginTap
8. User taps a mobile messenger/channel
9. Confirms tie in a mobile messenger/channel
LoginTap.com
Your FRONT
Your BACK
6. Call on JS Widget
to render QR for UUID
2. Check if your user has LoginTap's UUID
3. Request & receive a new user Logtinap UUID & messengers links
5. Check if "LoginTap channel is set" for user
11. Update user's record to "LoginTap channel is set"
4. Create new user Logintap UUID and messenger links for every request
10. Pair user with the selected mobile channel
Mobile User
1. Let users login with your standard auth (login/pass or SSO)
3.2 Using LoginTap as the MAIN factor for user auth
LoginTap.com
Your FRONT
Your BACK
3. Check if user's "LoginTap channel is set"
10. Record confirmation or denial
6. Check user's channel and Push auth request to user's mobile
9. Receive auth response from a user's channel
1. A user opens your web site
7. Follow Push & unlock the phone
8. Confirm or deny entry in previously selected mobile messenger/channel
2. Recognise user via cookie, etc...
11. Allow or deny Entry
4. Notify user that mobile AUTH is in progress with a loader gif image
5. Request auth
3.3 Using LoginTap as the mobile 2nd factor
Just as 3.2 schema above, BUT you start the auth on Step-3, right after user's correct login action:

1. Let user pass any auth procedures you find important, for example ask for login/password (auth point 2.2 above), or just ask for an email for more convenience (auth point 2.3 above).

2. Initialize mobile auth request from Step-3 above. You can do it on a button press or automatically.
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
yes
no
>
no
no
yes
no -> "step 1 of new user"
4. Full step-by step instruction
,
VERY IMPORTANT! The purpose of this instruction is just to show an example, of a schema for mobile 2FA in your workflow. In reality, your schema can be different because you only need to comply with API calls and widget initiation. The rest - how and where and even if you store user data or session ids can be fully done the way you need to.

This instruction assumes that you have already registered with Logintap. If not - press Sign Up and check your email.

Download the technical drawing ↓↓↓ as PDF

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.
4.1 Create a new website in Logintap

Press "Add New Site" button.

The Settings form will appear. In case you don't have all the needed data now, you can always access it later from a Menu button of each of your sites.


1. "Project/site name" is a name that is sometimes visible to your users, so name it properly.

2. Create a "call back url" on your website and enter it's address, for example - https://your-site.com/logintap/callback

3. "Display site name in messenger" means that Logintap will show user this "Site's name" during auth process. If you want to hide this information from whoever accidentally sees user's push notifications - uncheck it.

4. "Limit" on requests per minute is necessary to prevent spam, in case only email is used to start mobile auth and somebody gets a hold of that email and just tries to login again and again.

5. Application UUID ( appUUID) is an auto generated connector, which you will need at a latter step.

4.2 Prepare your backend

1. Download suitable library here - (PHP5, PHP7 or WordPress plugin) or from inside your Logintap account. It is open source and has just 4 API methods.

2. Deploy the library at your back and connect it to your CMS.

3. Add 2 new tables to your website's data base - lt_auth_sessions to store all user auth requests through Logintap and lt_settings to store connections to your Account.

Add Table 1 - lt_auth_sessions (start table name with LT for your convenience):
Note - ID and Login fields are your own internal fields, which you can use to identify record and user, who is using Logintap. You can name it anything you want.

Note- the "lt_" addition is only used to make it easy to identify fields working with API requests to LoginTap.


Add Table 2 - lt_settings (for your convenience start name with LT):



4. Fill in the above "lt_settings" table with the following Logintap account data, which will be used to receive API tokens through "getUserTokens" call:

- login is your email


- password is your account's password


- tenant is your alphanumeric 3rd level domain name, for example, a123abc-admin.logintap.com, where a123abc is your tenant name


- appuuid is located in Menu -> Settings of each one of your sites:


In case your access tokens expire or were not initially received, API calls will not work. You would need to run "getUserTokens" call from the PHP library to get new ones. The standard tokens expiration is set for 1 week, so please make sure to renew more often. Contact us if your case needs any other expiration time.

5.
Add 4 new fields into your users table in your database:

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