README
AceBlock login package
THIS PACKAGE IS CURRENTLY FOR DEMONSTRATIVE PURPOSES ONLY, AND THUS NOT READY FOR PRODUCTION
IF YOU WANT SECURE VERSION OF AceID, PLEASE CONTACT info[AT]netis.si
THIS PACKAGE IS COMPATIBILE WITH PREDECESSOR OF AceID MOBILE APP, NxxtechID
AceID MOBILE APP WILL BE COMPATIBILE WITH VERSIONS 1.0.0 AND GRATER
[TOC]
Register to use AceBlock Login Service
Each service, that wants to use AceID login, must first register in AceID service registry, available at to be set. If service is not registered, user cant call register/login to your page.
If you intend to use only demo version, you do not have to register.
Demo version
Instructions below are written for production mode. To use it in demo mode, look at the end of this document.
Default Config fields
AceBlockConfig.json
contains the parameters, which are the same for all AceBlock login users. It is loaded from AceBlock server. Currently it is available at https://212.93.226.188.nip.io/AceBlock/AceBlockConfig.json
It has the following fields
Field | Content |
---|---|
bcURL | Http endopint to the AceBlock blockchain client |
bcABI | Interface of login contract |
contractAddress | Login contract address |
IpfsEndpoint | Http endopint to the AceBlock IPFS client |
QRrefresh | Time in ms, after QR content is refreshed |
Page Specific Config fields
AceBlockLoginConfig.json
contains the parameters, specific for every portal/page. It should be saved on server, where webpage is hosted.
It has the following fields
Field | Content |
---|---|
accessToOptionalItems | List of user data, that are not neccessary for the service, allowing user to decide to share it or not |
accessToRequiredItems | List of user data, that not neccessary for the service, allowing user to decide to share it or not |
authSC | Smart contract addreeses, for which webpage gets the authorization to perform actions on user behalf |
portalAddress | Portal or webpage address |
RedirectURL | URL where page should redirect after user logs in |
demo | Inidicator if only demo mode |
accessToOptionalItems and accessToRequiredItems
accessToOptionalItems
and accessToRequiredItems
are comma separated lists of items that we require from users. Items are represented with numerical keys, as described at
https://212.93.226.188.nip.io/AceBlock/userDataFields.json . List might be updated in the future.
For example, you want following users data
Needed for service: user's phone, first name, last name and email
Not needed for service, but might be useful for other purposes: state, zip coe, country and nationality
To get them, add following lines to AceBlockLoginConfig.json
"accessToRequiredItems": "1,2,4,6",
"accessToOptionalItems": "7,8,9,10"
authSC [to be changed from 1.0.0]
Since users private key cannot be shared directly with webpage (or any other services), we introduce this method, where webpage can perform simple actions on contracts, which are authorized by user. If webpage wants to use this feature, QR code must include list of contracts for which user grants rights.
For example, if you wants for your page to write on users behalf on contract at address "0xca23a138b9b069224d94a77edfce5c5504b0140d" add to AceBlockLoginConfig.json
"authSC": ["0xca23a138b9b069224d94a77edfce5c5504b0140d"]
Future changes: interchain operability. Together with contract you would have to specifiy on which chain it is (chainID)
portalAddress [to be deprecated from 1.0.0]
portalAddress
is unique identifier for every web portal, so ID app can know where it is loging in (or registering). Currently, this is simple field, while in the production app, app will get portal address from QR signature.
QR CODE
Code is generated from data from AceBlockLoginConfig.json
and signed with either server private key (for regular web app) or with site temporary ID (for single page web app).
Using AceBlock Login Service
Single page web app
As a node module
First install npm package
npm -i @aceblock/aceblock-login-qr
Prepare html
<body>
<div id="AceBlockQRplace"></div>
</body>
Then import it in your app.
const aceBlock = require("@aceblock/aceblock-login-qr")
// generate QR code and present it in element named elementID
const elementID = "AceBlockQRplace"
aceBlock.displayQR(elementID)
// generate QR code, and wait for QR img tag (new event every 60 sec)
aceBlock.displayQR()
window.addEventListener('qrContent', (data) => {
document.getElementById("AceBlockQRplace").innerHTML = data.qrContent
})
// get only QRData (new event every 60 sec)
aceBlock.getQRData()
window.addEventListener('qrContent', (data) => {
console.log(data.qrContent) // make image out of it and diplay on your page
})
window.addEventListener('aceBlockData', (data) => {
// if you called displayQR() or qrContent(), this events also give indication if login was succesfull or not, so you can manage login element here
if (data.userData) {
document.getElementById("AceBlockQRplace").innerHTML = "Login succesful"
setTimeout(function(){
document.getElementById("AceBlockQRplace").style.display = 'none'
}, 2000)
}
// in any case, you get user data
console.log("User data", data.userData)
});
Browserified (CDN)
Package is available on
https://212.93.226.188.nip.io/AceBlock/js/aceblock-login-qr.js
https://212.93.226.188.nip.io/AceBlock/js/aceblock-login-qr.min.js (minified)
You can either download it and load it locally, or you can load it directly from our servers (in the future also from the IPFS).
<head>
...
<script type="text/javascript" src="https://212.93.226.188.nip.io/AceBlock/js/aceblock-login-qr.js"></script>
...
</head>
Now you have 3 options to implement login on a page, with detailed description below.
- Let package display QR code on page
- Let package generate QR code html, but diplay it manually
- Let package only prepare QR content, then generate and display QR code manually
1. Let package display QR code on page
All you have to do is to create a div where QR will be displayed and button to initiate the login process. Click on a button should trigger function displayQR(elementID)
, where elementID
is div id where code should be displayed.
<body>
<div id="AceBlockQRplace"></div>
<button onclick="displayQR('AceBlockQRplace'); this.style.display = 'none'">Login with AceBlock</button>
</body>
When user succesfully logs in, you will get user data (look at section "getting user data") or error message.
2. Let package generate QR code html, but diplay it manually
Code is similar as in previous case, except displayQR()
is called without any argument. Then you need a separate js file, where you listen for event qrContent
and then act accordingly when data comes. In this case you get html img
tag, so you just need to present it wherever you want.
<body>
<div id="AceBlockQRplace"></div>
<button onclick="displayQR(); this.style.display = 'none'">Login with AceBlock</button>
</body>
In app.js
window.addEventListener('qrContent', (data) => {
document.getElementById("AceBlockQRplace").innerHTML = data.qrContent
})
3. Let package only prepare QR content, then generate and display QR code manually
Insetead of calling displayQR()
, you now call getQRData()
. Again, in separate js file, listen for event qrContent
and then act accordingly when data comes. In this case you get just a base64 encoded content of qr code, so you have to generate QR image yourself.
Note: our choice of QR code generator is optimized to work with AceBlockID app, so using your own version might lead to performance drop.
<body>
<div id="AceBlockQRplace"></div>
<button onclick="getQRData(); this.style.display = 'none'">Show QR code AceBlock</button>
</body>
In app.js
window.addEventListener('qrContent', (data) => {
console.log(data.qrContent) // make image out of it and diplay on your page
})
Getting user data
When user succesfully log in, she shares data with page. Data can fetched with listening to event aceBlockData
. Since user can change data on her mobile phone during when her session is still active or even revoke access, you need to monitor for these changes and act accoringly
In app.js
window.addEventListener('aceBlockData', (data) => {
// if you called displayQR() or qrContent(), this events also give indication if login was succesfull or not, so you can manage login element here
if (data.userData) {
document.getElementById("AceBlockQRplace").innerHTML = "Login succesful"
setTimeout(function(){
document.getElementById("AceBlockQRplace").style.display = 'none'
}, 2000)
}
// in any case, you get user data
console.log("User data", data.userData)
});
Handling access with mobile page
You do not need to cover the case, when user hase AceBlockID already installed, since package handle login from mobile device automatically (without the need to scan QR code). If user does not have app installed, you should redirect it to download page. (instructions to come)
Regular web app
WIP
Native Mobile app
WIP
Demo mode
To enable demo mode, do the following:
- In
AceBlockLoginConfig.json
set "demo" : true - Loads necessary dependencies, by adding in
index.html
to head
<head>
<script type="text/javascript" src="https://212.93.226.188.nip.io/AceBlock/js/aceblock-login-qr.js"></script>
<!-- jquery, popper, bootstrap, bootbox -->
<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootbox.js/5.3.2/bootbox.min.js"></script>
</head>