Using the WiKID API in your two-factor authentication roll-out

Posted by:

admin 11 years, 6 months ago

Time to get down to business with the wAuth API. The API exposes all the key functionality of the WiKID server allowing you to automate many typical two-factor authentication tasks and push functionality to the appropriate parties, such as the corporate helpdesk or HR. In this series of blog posts, I'll show you how to create the communication channel, register users and authenticate an one-time passcode. For our example, we will be setting up a CSR application in Java on a box with the IP address of 192.168.1.10. The WiKID server has an internal IP of 192.168.1.20 and an external IP of 174.129.6.100. So, the zero-padded domain identifier for the WiKID server is 174129006100. For demonstration purposes, our CSR application will be a tomcat JSP on linux in a directory called /opt/tomcat/webapps/CSR. I assume that this application will be protected by existing credentials appropriate for this level of securing and granting access.

Note that the WiKID server ships with a file called /opt/WiKID/tomcat/webapps/WiKIDAdmin/example.jsp. You can steal all the code on that page to create your own application. It is very well commented and contains all the latest API functions. It also includes all the HTML needed for these examples.

We have API packages and sample code available in Java, Python, Ruby, PHP and C#. You can copy the WiKID jar from /opt/WiKID/lib or download it from the website. Note that the jar on your WiKID server may be newer. Copy the jar to your application server.

Connecting securely

First, we will import some libraries:

<%@ page contentType="text/html; charset=UTF-8" %>
<%@ page import="com.wikidsystems.client.wClient" %>
<%@ page import="com.wikidsystems.data.PreRegistration" %>
<%@ page import="com.wikidsystems.data.RegistrationCode" %>
<%@ page import="com.wikidsystems.data.Token" %>
<%@ page import="com.wikidsystems.data.User" %>
<%@ page import="com.wikidsystems.server.transaction.ReportDataTransaction" %>
<%@ page import="com.wikidsystems.util.Config" %>
<%@ page import="java.util.ArrayList" %>
<%@ page import="java.util.Iterator" %>
<%@ page import="java.util.List" %>

When you create a wAuth network client, the server generates an SSL client-side certificate for that IP address. We called our CSRApplication and CSRApplication.p12 was created. After creating the network client, you need to restart the WiKID service (to open the firewall). This P12 file must be on the CSR application server along with the CACertStore. Both files are found in /opt/WiKID/private. Copy them to /opt/tomcat/webapps/CSR on the network client server. This code will instantiate the connection:

<%
    String defaultservercode = "174129006100"
    String status = "";
    String chall;
    wClient wc;
    if (session.getServletContext().getAttribute("wClient") == null) {
        wc = new wClient("192.168.1.20", 8388, "/opt/tomcat/webapps/CSR/CSRApplication.p12", "CSR_passphrase",
                "/opt/tomcat/webapps/CSR/CACertStore", "changeit");
        // NOTE:  The passphrase above "changeit" is the default passphrase for the CA trust store as delivered
        // by Sun with Java.  If you change this value you will also need to change the passphrase used to
        // encrypt the CACertStore file.  You must change both if you change either.
        session.getServletContext().setAttribute("wClient", wc);
    } else {
        wc = (wClient) session.getServletContext().getAttribute("wClient");
    }
    if (wc.isConnected()) {

%>

wAuth uses port 8388. When you restarted WiKID, WiKID should have opened port 8388 for 192.168.1.10. You can validate this by running 'iptables -L -n | grep 8388'.

First up, let's register a user's software token. The WiKID software token does not use pre-shared secrets like most tokens. We use asymmetric encryption. The tokens generate public/private key pairs and exchange them with WiKID servers. After the exchange, the server sends a registration code to the token, which is hashed and presented to the user. Once this hash is entered into the WiKID server in some protected manner, the user can generate valid one-time passcodes.  From there on the user enters the PIN into the software token and get back a valid OTP from the server. Technically, the two-factors of authentication are knowledge of the PIN and possession of the private key embedded in the token.   The PIN is never stored on the token.

WiKID does not offer a hardware token.

<%
    int res;
    if (request.getParameter("action") != null && request.getParameter("action").equalsIgnoreCase("register")) {
        res = wc.registerUsername(request.getParameter("user"), request.getParameter("regcode"), request.getParameter("servercode"));
        if (res == 0) {
            status = "Success";
        } else {
            status = "Failed (" + res + ")";
        }
    }
%>

If you are using groups on the WiKID server to return specific radius attributes, you can also register users into a group.

<%
    if (request.getParameter("action") != null && request.getParameter("action").equalsIgnoreCase("Register In Group")) {
        res = wc.registerUsernameInGroup(request.getParameter("user"), request.getParameter("regcode"), request.getParameter("servercode"), request.getParameter("groupName"));
        if (res == 0) {
            status = "Success";
        } else {
            status = "Failed (" + res + ")";
        }
    }
%>

Now, let's have a user login with WiKID. This could be the method you use to validate the CSRs.

<%
    boolean isValid;
    if (request.getParameter("action") != null && request.getParameter("action").equalsIgnoreCase("Check Online")) {
        isValid = wc.CheckCredentials(request.getParameter("user"), request.getParameter("passcode"), request.getParameter("servercode"));
        if (isValid) {
            status = "Success";
        } else {
            status = "Authentication Failed";
        }
    }
%>

We're big fans of user self-service. You can see this in our other sample app that allows users to register themselves after logging with their Active Directory credentials. Once a user has a valid WiKID software token, they can validate another with a passcode from the first.

<%

    if (request.getParameter("action") != null && request.getParameter("action").equalsIgnoreCase("Add device")) {
        res = wc.registerUsername(request.getParameter("user"), request.getParameter("regcode"), request.getParameter("servercode"), request.getParameter("passcode"));
        if (res == 0) {
            status = "Success";
        } else {
            status = "Failed (" + res + ")";
        }
    }
%>

Note that a WiKID license is a unique username in a domain, so having more than one software token does not cost any more. It does increase the convenience to the user and should decrease help desk calls.

So, now we have created a simple CSR application that allows customer service reps validate your users.  We can further reduce the cost of two-factor authentication by letting users validate themselves based on some existing trusted credentials over a trusted network.

We can take this further though.  Imagine you outsource some functions to a 3rd party and you want them to use two-factor authentication.  With WiKID you can have them manage their user enrollment in your two-factor authentication server.  Or as another example, you run an enterprise-oriented SaaS company.  You need your customers to enroll and manage their users. With the WiKID server supporting multiple domains and network clients, multi-tenant two-factor authentication is simple.  Each of your customers can have a domain and network client and use these simple scripts to manage their own users.

Next up - Pre-registering users via the API.

• ← WiKID's two-factor authentication API
• PCI Compliance →