Generic selectors
Exact matches only
Search in title
Search in content

Node.js API

Two-Factor Authentication with SecSign ID

Use SecSign ID Node.js two factor authentication on your Node.js project with an easy and highly secure user login using iOS or Android mobile devices as well as for desktop use.

Find out why our Two-Factor Authentication is the best, some key-facts for developers and why you should upgrade to SecSign for your business.

Learn more about the options of on-premise use and your own customized ID App in your corporate design.

Download the plugin as cloud version for a free and convenient protection.

Table of contents

    SecSign ID two factor authentication adds another layer of security to your website by using a second token. In this case the physical token is your smartphone.

    If you seek for more information about about two-factor authentication have a look at the Github site.

    Questions? Feel free to get in touch with us if you need help setting up your SecSign ID plugin or to request a plugin for a not yet supported environment.

    1. Setup the example

    In the Node.js API archive you will find the API-class ‘SecSignIDApi.nodejs.js’ and a fully functional example with Node.js two factor authentication. The actual range of the API consists only of two classes with which the two-factor authentication (in short 2FA) can be realized:

    SecSignIDAPI: The class includes all functions for requesting a so-called authentication session

    AuthSession: This class includes all information of a so-called authentication session (in short AuthSession)

    1. Download the SecSign ID Node.js example archive and extract it
    2. Install Node.js on your computer and open the console or terminal
    3. Switch to the secsign-nodejsapi folder and type node secsignid-server.js
    4. Open http://localhost:8080/ in your browser to test the SecSign ID 2-factor authentication process


    SecSignIDApi.nodejs.js – The SecSign ID Node.js Api itself. The file contains the module SecSignIDApi which contains two exported classes: SecSignIDApi and AuthSession

    secsignid-example.js – A small example how to request and check an authentication session on serverside.

    secsignid-server.js – A small example of a webserver based on Node.js framework. The webserver will accept and redirect some requests to the SecSign ID Server. The requested and checked authentication session data is sent to the browser.

    web-example/index.html – html page to be used by the webserver example.

    web-example/access-pass.html – html page to be used by the webserver example.

    web-example/login-success.html – html page to be used by the webserver example.

    2. Integration of the API

    Download the SecSign ID Node.js API (SecSignIDApi.nodejs.js) and add it to your Node.js project

    // include SecSign ID Api for node.js
    var SecSignIDApi = require('./SecSignIDApi.nodejs.js');

    3. Request a session

    Request a new session (authentication session) from the ID server. In order to request a session, the user name, respectively the SecSign ID as well as the name of the website, web service or Node.js project have to be sent to the server. The name of the website, respectively web service will be shown to the user on the smart phone.

    An authentication session consists of a session ID, the SecSign ID as well as a so-called ‘Access Pass‘. The class for the session is called ‘AuthSession’. The Access Pass includes a Base64 encoded PNG image. This image must be shown to the user. The same image will be shown to the user on his smart phone.

    By the comparison of the images the session will be accepted on the smart phone.

    // this auth session object will encapsulate all required data such as request id, authentication session id and the secsign id
    var authSession = null;
    // example for whom an auth session could be requested.
    // the value for secsignid should be your SecSign ID which you have created before.
    var authenticationSessionFor = {
        "secsignid" : "zoidberg", // the secsign id itself
        "servicename" : "Node.js test", // a name which will be shown in the push notification
        "serviceaddress" : "localhost" // an address which is shown at top in the app, when user has to pick the correct access pass
    // start by requesting an authentication session
    secSignIDApi.requestAuthSession(authenticationSessionFor, receivedAuthSessionCallback);

    4. Show access pass to the user and save session parameters

    After a session (authentication session) has been requested from the server the access pass must be shown to the user, e.g on the website. The Access Pass consists of a Base64-coded PNG image. The user compares this image with the images shown on his smart phone. By selecting the correct symbol the user confirms the session.

    For websites this session information must be stored in order to later request the state of the session. On websites this can be done via form fields. The example shows the required information for requesting the state of the session later on.

    1. Request ID: The Request ID is the ID of the currently requested session. Through this ID all further requests, e.g. a request for the state of the session are assigned
    2. SecSign ID: The user name
    3. AuthSession ID: The ID of the requested session
    4. Service Name: The name of the Node.js project, respectively of the web site
    5. Service Address: The IP address, respectively the URL of the Node.js project, respectively of the web site

    // call back function for the call of secSignIDApi.requestAuthSession(...)
    var receivedAuthSessionCallback = function(authSessionObj){
    		console.log("Error " + authSessionObj.errorcode + " : " + authSessionObj.errormsg);
    	} else {
    		// received an authentication session
    		// sent data is an url encoded parameter list: authsessionid=-429097454724893700&servicename=Node.js test&secsignid=samplesecsignid&authsessionstate=1&serviceaddress=localhost&requestid=.....
    		// when data was parsed, it looks like:
    		// {
    		//	secsignid: 'zoidberg',
    		//	requestid: 'F2C5F138E72008AD0ABCC2E83ACCD7B71B415FF58DA35DEAA5AA79D83B939246',
    		//	authsessionid: '-8337412603900330717',
      		//	authsessionstate: '1',
      		//      servicename: 'Node.js test',
      		//	serviceaddress: 'localhost',
      		//	authsessionicondata: 'iVBORw0KGgoA ... MAAAAABJRU5Er',
      		// }
      		// again, this is just an example so you know that you will get a hashmap/object or an associative array.
      		// the authentication session icon data must be shown to user e.g. by sending it back to the caller or the website.
      		// to check the authentication state the request id and the authentication session is needed.
      		// therefor the auth session object must be stored by sending it to the browser, so it could be posted back, by storing it in a session object or somewhere else
    		secSignIDApi.log("received auth session: ", authSessionObj);
    // create an authentication object. this stores the data about secsign id, request id and auth session id
    authSession = new SecSignIDApi.AuthSession(authSessionObj);
    // secSignIDApi.getAuthSessionState(authSession);
    // secSignIDApi.getAuthSessionState(authSessionObj);
        "secsignid" : authSessionObj.secsignid,
        "requestid" : authSessionObj.requestid,
        "authsessionid" : authSessionObj.authsessionid
    }, receivedAuthSessionStateCallback);

    5. Request the state of the session

    The session which is requested from the server can have different states. As soon as the session is requested from the server, the session has the state „Pending“. When a user wants to confirm the session on the smart phone, the session receives the state „Fetched“. When the user accepts the session by selecting the correct symbol, the state changes to „Authenticated“.

    Other possible states are ‘Denied’, ‘Cancelled’, ‘Expired’ and ‘Suspended’. More detailed information can be found in the comments of the class ‘AuthSession‘.
    It is necessary to react to the user´s acceptance (‘Authenticated’) or denial (‘Denied‘) of the session.

    This can either be done by an action of the user so that, for example, the form (see point 3) can be sent to the server via buttons or via polling. It can be reacted to the state of the server upon receipt. The session can either be accepted, denied or remain pending. The state can be compared with constants of the class ‘AuthSession‘.
    In case of a failure during the request of the state an exception will be thrown that can, respectively should be caught.

    // call back function for the call of secSignIDApi.getAuthSessionState(...)
    var receivedAuthSessionStateCallback = function(authSessionObj){
            console.log("Error " + authSessionObj.errorcode + " : " + authSessionObj.errormsg);
        } else {
            // the received parsed data:
            // {
            //	authsessionid: '-6928134574892437226',
            //	secsignid: 'local',
            //	authsessionstate: '1'
            // }
            secSignIDApi.log("auth session state: ", authSessionObj);
            // check which state the session has
            if(authSessionObj.authsessionstate == SecSignIDApi.AuthSession.PENDING){
                console.log("the authentication session is pending");
            if(authSessionObj.authsessionstate == SecSignIDApi.AuthSession.AUTHENTICATED){
                //release authSession and log user in
                secSignIDApi.releaseAuthSession(authSession, userIsLoggedInCallback);
            if(authSessionObj.authsessionstate == SecSignIDApi.AuthSession.Denied){
                console.log("the authentication session was denied");
                // cancel session
                secSignIDApi.cancelAuthSession(authSession, canceledAuthSessionCallback);
            // store the new state in auth session object

    6. Cancellation of the session

    If the session is supposed to be cancelled via the client, this can be done via ‘cancelAuthSession‘.

    // call back function for the call of secSignIDApi.cancelAuthSession(...)
    var canceledAuthSessionCallback = function(authSessionObj){
    		console.log("Error " + authSessionObj.errorcode + " : " + authSessionObj.errormsg);
    	} else {
    		// the received parsed data:
    		// {
    		//	authsessionid: '-6928134574892437226',
    	  	//	authsessionstate: '6'
    	  	// }
    		secSignIDApi.log("canceled auth session: ", authSessionObj);

    7. The SecSignIDApi Object

    The communication with the ID server runs via ‘SecSignIDApi.nodejs.js’. SecSignIDApi objects do not have to be particularly initiated (see the example under 2).

    The method for requesting a session requires as parameter the SecSign ID, the name of the web site or project as well as an IP address, respectively the URL of the web site. An AuthSession object will be received, all other functions of the SecSign ID Api require as parameter a valid AuthSession object.

    The functions are:

    1. requestAuthSession
    2. getAuthSessionState
    3. releaseAuthSession
    4. cancelAuthSession

    8. Available APIS

    We provide an ever growing list of APIs and plugins to easily integrate the SecSign ID Two-Factor Authentication in any project. An overview is available at Plugin and APIs.
    We do not only offer APIs in different programming languages but also plugins for CMS, Server and VPN environments, oAuth2 and many more. These plugins use our APIs and offer additional functionalities, for example user management, easy and native installation, logging or integration in firewalls or Active Directory.

    The JIRA plugin for example uses the JAVA-API. The PHP-Api and JS-API is used by WordPress, Joomla, Drupal, Typo3 and many more. The is used for the Windows and Cisco VPN and the C-API is used for protecting Unix SSH services. The Objective-C API is used by our AppleTV and iPhone/iPad apps.


    9. See for yourself

    You can experience the SecSign ID two-factor authentication and the two-factor login by simply integrating the plugin into your website or test environment. Or you can try out the login process on our website without having to register first. You already have a SecSign ID or you want one? Login now and use the portal or use our hassle free registration.

    See for yourself how fast and convenient the login process using challenge-response authentication with 2048-bit key pairs is. There is no need for passwords, and no passwords or other confidential information are ever transmitted. It is easy to integrate and simple to use.

    For more information about the patented SafeKey procedure and it's unique security can be found here.

    If you are missing an API for the programming language you are working with, feel free to contact us and we’ll find a solution with you. If you need help with the integration into an existing system or you can’t find the plugin for your content management system you are working with, don’t hesitate to contact our support team.

    Your own ID-Server

    On premise installations of SecSign ID offer the flexibility to connect with your preferred servers, services, and devices. And you can customize the SecSign ID with your own organization’s branding.


    Why upgrade to SecSign?

    On-premise or in the cloud

    Choose between our SecSign ID Cloud or operate your own on-premise Two-Factor Authentication server.

    Easy customization

    Operate your own YourBrand ID app - Two-Factor Authentication customized to your needs.

    Ready-to-use SDK

    Integrate SecSign ID Two-Factor Authentication in existing apps with our ready-to-use SDK.

    Easy user management

    Use the Two-Factor Authentication Server to secure your company Active Directory/LDAP. Your own Identity and Access Management System, for example for mandatory updates and additional security features.

    Cover all logins

    Integration in any login environment: web, local, VPN, remote desktop, mobile logins and many more.

    Plugins for all your needs

    No need for complex integration: we have plugins for almost all environments.

    SecSign 2FA