mw-delog v0.0.4

Delog

Introduction

Delog is a server-side library that implements a middleware for any express-based web server. It can be used to manage the login and access control as well as user management in a web application without the need for a prior registration. It is a light-weight library built for ease-of-use and easy implementation. To start, simply use the middleware and it will handle the authentication of incoming requests automatically. The library allows for generation of disclosure requests and has a built-in cache where it saves authentication data.

Installation

npm install mw-delog

After installing the library, you can import the middleware in the following way:

const Delog = require('mw-delog')

Usage

To initialize the middleware, you need to call the init() function.

It is called with the route you want to use for login, the callback route, the requested information and optionally required claims for access control (see below).

Example:

Delog.init('/login', '/callback', ['name'])

As you can see, the paths are relative and the required claims is an array of claim objects consisting of an issuer DID and a certificate name.

To use the middleware, you need an express server that uses delog. Please make sure to install a body-parser aswell.

Pleasse be aware that uport only supports https callback addresses, so you have to make sure your server is using that protocol.

Example

const express = require('express')
const bodyParser = require('body-parser')

const app = express()
app.use(bodyParser.json({ type: '*/*' }))

Delog.init('/login', '/callback', [{issuer: 'did:ethr:0x1420cedd4ce6db3b05161277f55f71db2310bcf3', name: 'Testkurs'}])

app.use(Delog.delog)

From now on, every incoming request will first pass through the delog middleware. It will check if an access token is set in the request header. If it is, the token will be validated and the request is forwarded to its original destination. If the access token is not set, or not valid, the request will fail.

Test Server

To test your application locally, you can set up a ngrok server, so your uport app is able to address your localhost directly. For more information on how to set up a ngrok server, click here.

Alternatively, go to Delog-TestApp and follow instructions to set up the application. This is a simple React App that allows you to login and displays your name and DID once successful.

Test Certificate

You can visit MW-Verification and follow the instructions there. This application will allow you to create verified claims, with issuer and claimname being customizable. You can then use this claim with Delog.

Set required claims

You may want to require some verified claims to be send with the credentials of your user, to verify that this identity is allowed to access the application. This can be set in the init-function as additional parameter - an array of objects consisting of the issuer DID as key and the claim name as value.

Example

Delog.init('/login', '/callback', ['name'], [{issuer: 'did:ethr:0x1420cedd4ce6db3b05161277f55f71db2310bcf3', name: 'Testkurs'}])

Beware that the issuer and name of the course are just examples and need to be replaced with the correct claim that you want to require. Delog will check if the claim issuer is valid and if the claim name is corrrect.

Start Login Request

To start a login request to get an access token, the client will have to construct a POST request to the predefined login route. It needs to include the attribute network, which for now can only be 'uport'.

Example

import axios from 'axios'

axios.post('https://1c865c9e.ngrok.io/login', {
    network: 'uport'
}).then(res => {
    console.log(res.data.qr, res.data.jwt)
})

The response is an object containing the jwt token for the request and the encoded QR-Code image. The QR Code can be displayed by embedding it in an HTML img-tag.

<img src={qr} alt="QR Code" />

Alternatively, you may want to install the frontend library uport-connect to be able to send the jwt through this library, which automatically uses the standard popup for uport.

import { Connect } from 'uport-connect'
let uport = new Connect('DeLog')
...
uport.send(jwt, 'disclosureReq')

The QR code can be scanned by the uport app on the user's phone. The user can then decide to share his credentials, in which case the response will be sent to the callback URL specified in the request.

The response will be catched by the delog middleware and the signature of the JWT is validated. If it is valid, the token will be saved into the delog cache with the corresponding request URL as key.

To get the access token, the client will have to poll the server. To identify the request, the request JWT token has to be included in the headers of the request.

Example:

axios.get('https://1c865c9e.ngrok.io', {
      network: 'uport',
      headers: {
        'x-access-token': jwt
      }
    }).then(res => {
      if(res) {
        console.log(res)
      }
    })

If the server has received a valid response token from the user's uport app, it will return this token and the decoded credentials to the client.

This new token can be used for interaction with the server from now on by setting it in the request header under the attribute x-access-token. You can put the token and credentials into a cookie to preserve the login information over a session.

To access user data in the backend, you can decode the JWT access token to get the credentials. A method for this is implemented in the Delog class.

Example

delog.decode(jwt).then(res => console.log(res))