evenid-sdk

EvenID Node.js SDK

This SDK is a NodeJS client library to work with the EvenID API.

Install

 
npm install evenid-sdk --save
 

License

MIT. See LICENSE file.

Unit Tests

EvenID uses Mocha for unit testing. As usual, tests may be run by calling npm test.

Contacts

Report bugs or suggest features using GitHub issue tracker.

Usage

1 / Create a client to obtain a client ID and client secret

To create a client, register on evenid.com and go to the following page: https://www.evenid.com/clients.

Once created, you obtain a client ID and client secret which were required to communicate with the API.

2 / Add a URL to redirect the person registering in or logging in back to

To add a URL, go to your client page (the one created during previous step) and click on the "Redirection uris" category.

Once created, you obtain the links that you will need to display on your website (following the EvenID's Branding Guidelines).

3 / Use the SDK in your redirect URL

var express = require('express');
var EvenID = require('evenid-sdk');
 
var app = express();
 
// Replace with your redirect URI
app.get('/my-redirect-uri', function (req, res, next) {
    // Replace with your credentials
    var clientID = '557c46a4ecb098a994828d8e';
    var clientSecret = 'e6858d77b3b0d1f426901747096512657f1ab5b7';
 
    var evenID = new EvenID(clientID, clientSecret);
 
    var authorizationCode = req.query.code;
    var state = req.query.state;
    var expectedState = 'REPLACE_WITH_YOUR_VALUE';
 
    if (!state || !expectedState || state !== expectedState) {
        res.status(403).send('Forbidden.');
 
        return;
    }
 
    /* If you don't want to store users */
 
    evenID.exchangeCodeForTokens(authorizationCode, function (err, resp) {
        if (err) {
            return next(err);
        }
 
        evenID.getUser(resp.access_token, resp.user_id, function (err, user) {
            if (err) {
                return next(err);
            }
 
            // Login
        });
    });
 
    /* END */
 
    /* If you want to store users */
 
    evenID.exchangeCodeForTokens(authorizationCode, function (err, resp) {
        if (err) {
            return next(err);
        }
 
        if (resp.user_status === EvenID.UserStatus.EXISTING_USER) {
            // Find user by ID (resp.user_id)
            // Login
            return;
        }
 
        evenID.getUser(resp.access_token, resp.user_id, function (err, user) {
            if (err) {
                return next(err);
            }
 
            if (resp.user_status === EvenID.UserStatus.NEW_USER) {
                // Insert user
            } else { // EvenID.UserStatus.EXISTING_USER_AFTER_(TEST|UPDATE)
                
                /* Update user 
                   https://www.evenid.com/docs/guides/how-to-handle-personal-information-update */
            
                /* You may use EvenID.EntityStatus.(NEW|OLD|UPDATED|DELETED)_ENTITY 
                   to check for entity status */
            }
 
            // Login
        });
    });
 
    /* END */
});

That's it. You've just successfuly implemented login, registration, password recovering, email validation and even test accounts, if you have enabled them.

Use cases

What if I want to add persistent login to my website?

1. Store the refresh token (resp.refresh_token) in a separate cookie.

2. When an unlogged user access your website, check for cookie existence.

3. If the cookie exists, use it :

 
/* If you don't store users */
 
evenID.exchangeRefreshTokenForTokens(refreshToken, function (err, resp) {
    if (err) {
        return next(err);
    }
 
    evenID.getUser(resp.access_token, resp.user_id, function (err, user) {
        if (err) {
            return next(err);
        }
 
        // Login
    });
});
 
/* END */
 
/* If you store users */
 
evenID.exchangeRefreshTokenForTokens(refreshToken, function (err, resp) {
    if (err) {
        return next(err);
    }
 
    if (resp.user_status === EvenID.UserStatus.EXISTING_USER) {
        // Find user by ID (resp.user_id)
        // Login
        return;
    }
 
    // EvenID.UserStatus.EXISTING_USER_AFTER_UPDATE
 
    evenID.getUser(resp.access_token, resp.user_id, function (err, user) {
        if (err) {
            return next(err);
        }
 
        /* Update user 
           https://www.evenid.com/docs/guides/how-to-handle-personal-information-update */
        
        /* You may use EvenID.EntityStatus.(NEW|OLD|UPDATED|DELETED)_ENTITY
           to check for entity status */
 
        // Login
    });
});
 
/* END */
 

If the cookie doesn't exist, display links as usual. That's it.

What if I want to validate user's email?

Just call the validateEmail() method.

 
evenID.validateEmail(resp.access_token, user.id, user.emails[0].id, function (err, resp) {...});
 

The user will receive an email containing a link, which will need to be followed to confirm the ownership of the address. Once verified, user will be redirected to your redirect URL, as usual.

What if I want to inspect an access token?

Just call the inspectToken() method.

 
evenID.inspectToken(resp.access_token, function (err, resp) {...});
 

What if I want to get the notification behind signed request?

Just call the getNotificationFromSignedRequest() method.

 
var notification = evenID.getNotificationFromSignedRequest(signedRequest);
 

An exception will be triggered in case of signature mismatch.

Returned errors

Returned errors extend the default Error object and add two properties to it:

1. A httpStatusCode property, which will contain the HTTP status code, different from 200, returned by the API.

2. A jsonResponse property, which will contain the parsed JSON object, returned by the API.