humanID Core API

humanID API server. API doc and demo https://humanid.herokuapp.com

Details about humanID Web SDK can be found here

Demo data:

Admin

{
    "email": "admin@local.host",
    "password": "admin123"
}

Apps

[{
    "id": "DEMO_APP",
    "secret": "2ee4300fd136ed6796a6a507de7c1f49aecd4a11663352fe54e54403c32bd6a0",
    "platform": "ANDROID",
	"serverKey": "AAAA....S4"    
},
{
    "id": "DEMO_APP_IOS",
    "secret": "541ec90bf636f0a8847885af37faedc258dcc875481f870d507c64d0e785bc1e",
    "platform": "IOS",
	"serverKey": null
}]

Users

{
    "countryCode": "62",
    "phone": "81234567890",
    "hash": [
        "7a009b9c3203ac3ff081146137e658583d2d60cf867acdb49716b84f1603f8a4", // For DEMO_APP
        "0c88468123e1c193a5f2e925d360266025f739f30ed0eeab7321887905f8c68c", // For DEMO_APP_IOS
    ]
}

Prerequisites

Node.js >= 12 LTS
RDBMS (MySQL >= 14.14 or SQLite3 >= 3.22)

Setup

Install nodejs >= 10.x.x
Clone repo & install dependencies npm i
Run test npm test
Generate database (drop & create) by running npm run db:refresh on Linux/MacOS
Generate doc npm run doc (requires apidoc http://apidocjs.com/)
Build client SDK (javascript) npm run build

To generate database on Windows maybe you can run setx NODE_ENV=DATABASE && npx sequelize db:drop && sequelize db:create && npx sequelize db:migrate && npx sequelize db:seed:all (UNTESTED)

Configuration

App configuration is read from config.json. You can reuse the provided example in config.json.example.

Database

For DATABASE configuration please refer to Sequelize configuration. Some common examples:

Sqlite3 file storage

{
    ...
    "DATABASE": {
        "username": "root",
        "password": null,
        "database": "humanid",
        "dialect": "sqlite",
        "storage": "db.sqlite"
    },
    ...
}

MySQL with connection pooling

{
    ...
    "DATABASE": {
        "username": "root",
        "password": "root",
        "database": "humanid",
        "dialect": "mysql",
        "pool": {
            "max": 5,
            "min": 0,
            "acquire": 30000,
            "idle": 10000
        }    
    },
    ...
}

SMS OTP/Verification

To enable phone number verification SMS using Nexmo please provide valid configuration like below (replace values with your own account details):

{
    "NEXMO_REST_URL": "https://rest.nexmo.com",
    "NEXMO_API_KEY": "abcd1234",
    "NEXMO_API_SECRET": "abcdefgh12345678",
}

If one or more value are missing, no verification SMS will be triggered and verification code is not validated (always considered valid)

Push Notification

To enable push notification using Firebase Cloud Messaging, provide valid like below (replace values with your own account details):

{
    "FIREBASE_SERVER_KEY": "AAAAVo...BmFpE",
}

Currently this is only used for IOS. For Android, serverKey for each apps are used

Class/Entity Relationship Diagram

The API server stores data in given structure:

SequelizeMeta is just ORM migration metadata which is not related to business process

Web Login Examples

Web login implementation example can be found in http://localhost:3000/examples/login.html (publishing from examples/ dir).

To simulate web login with push notification, follow these steps:

Make sure Push Notification configuration above has been done
Open in a tab http://localhost:3000/examples/confirm.html and allow notification. Leave it open
Open in another tab http://localhost:3000/examples/login.html enter country code & phone number (demo data provided above) and click Login by App
Go to previous tab that points to http://localhost:3000/examples/confirm.html. A confirmation dialog should be shown. Click Confirm
Return to tab http://localhost:3000/examples/login.html. In less than 5 seconds, you should be redirected to http://localhost:3000/examples/secured.html

In the actual implementation, every actions in confirm.html can only be done from mobile device. Because it requires login hash which should be kept secret per user/app.

To simulate web login with OTP SMS, follow these steps:

Make sure SMS OTP/Verification above has been done, and you have register a valid phone number using POST /mobile/users/register
Open http://localhost:3000/examples/login.html enter country code & phone number (demo data provided above) and click Login by SMS
Wait for SMS containing OTP, enter it to the form, then click Verify & Login
You should be redirected to http://localhost:3000/examples/secured.html

Mobile API Recipes

Registration

Fresh login (no other partner app logged-in yet):

POST /mobile/users/verifyPhone Verify user phone number (request OTP SMS)
POST /mobile/users/register Register user. Get the hash from response and store safely in device

Login

POST /mobile/users/login Login using existing partner app hash. Get the hash for the new app and store it safely

Validation

Check if a hash is still valid:

GET /mobile/users/login Get login status

Switch Device

The same as new registration. Everything else is handled in server/backend

POST /mobile/users/verifyPhone Verify user phone number (request OTP SMS)
POST /mobile/users/register Register user. Get the hash from response and store safely in device

Update phone

Update phone number from an logged-in app:

POST /mobile/users/verifyPhone Verify user new phone number (request OTP SMS)
POST /mobile/users/updatePhone Update phone

Web login confirmation

Confirm login request from web client:

PUT /mobile/users Update notification ID (get it from Firebase Cloud Messaging SDK)
POST /web/users/confirm Confirm (after receiving push notification)
POST /web/users/reject Or reject

Push notification payload that need to be handled:

{
    "type": "WEB_LOGIN_REQUEST", 
    "requestingAppId": "APP_ID"
}

bluenumberfoundation/humanid-api