Download the Java-API Zip-archive and unzip it.

Both *.jar files have to be added to the Java Project. This can be achieved either with Eclipse in Settings > Java > Build Path > User Libraries or by transferring both .*jar files in the corresponding Java-project folder. Eclipse automatically recognizes the files and integrates them in the project.

With application server the basis structure determines the process of integration. Oracle Glassfish for example requires the *.jar files to be converted to *.war files before deploying them.

Import the required class from the package ‘com.secsign.secsignid’in the corresponding class in your project.:

import com.secsign.secsignid.SecSignIDApi;
import com.secsign.secsignid.AuthenticationSession;
import com.secsign.secsignid.AuthenticationSessionState;
import com.secsign.secsignid.SecSignIDException;

Overview of the Java-API zip-archive structure:

README.md
secsign_logo.png
developer/
lib/SecPKIApi.jar
lib/SecSignIDApi.jar
lib/secpki.properties
lib/secsign.com-wildcard-rapidSSL-2014-09-29.der
src/com/secsign/secsignid/AuthenticationSession.java
src/com/secsign/secsignid/AuthenticationSessionState.java
src/com/secsign/secsignid/SecSignIDApi.java
src/com/secsign/secsignid/SecSignIDException.java
src/com/secsign/secsignid/example/SecSignIDApiJavaSwingExample.java

In order to log a user in a web application or content-management-system (CMS) with his SecSign ID an authentication-session, short AuthSession, has to be requested from the SecSign ID Server. This AuthSession can be accepted from the user on his smart phone, which in turn logs him into the system. To request an AuthSession the method ‘SecSignIDApi.requestAuthenticationSession’ is used.

// create the SecSignID-API instance which can send requests to the SecSignID server
SecSignIDApi secSignIdApi = new SecSignIDApi();
String secSignID = secSignIdTextField.getText();
AuthenticationSession authSession = null;
try
{
	authSession = secSignIdApi.requestAuthenticationSession(secSignID,
		"SecSignID Java integration example",
		"www.example.com",
		"127.0.0.1");
}
catch (SecSignIDException exception)
{
	exception.printStackTrace();
	JOptionPane.showMessageDialog(null, exception.getLocalizedMessage());
}

The return value is the object ‘AuthenticationSession’. The class holds all information like SecSign ID, AuthSession ID, the access pass as png-image and the information provided during login.

The method ‘SecSignIDApi.requestAuthenticationSession’ includes the SecSign ID, which is supposed to be logged in, as a parameter, as well as the name of the web application ( ‘SecSignID Java integration example’ in the example) and an URL.

The name of the web application is displayed to the user as push notification on the smartphone while the URL is displayed to the user when choosing the access pass.

Swing Application

In the example the Swing Application contains a label ‘accessPassImage’. The received access pass will be displayed on this label by loading the byte-array in the imgageicon instance.

/**The label to show the logo and access pass**/
private JLabel accessPassImage;
//etc.
if (authSession != null){
    // Show the Access Pass
    final byte[] passIcon = session.getAuthSessionIconData();
    javax.swing.SwingUtilities.invokeLater(new Runnable() {
        public void run() {
            accessPassImage.setIcon(new ImageIcon(passIcon));
        }
    });
}

JSF-Application

In Java-Server-Faces-Web applications data are usually written in HTML-pattern, which are then sent to the browser. Using a XHTML-template objects and class variable can be embedded using

#{secsignid.iconData}. As soon as the template is rendered, an object ‘secsignid’ is requested that possesses the getter- and setter-method for the variable ‘iconData’.

/**
 * The iconData of the access pass
 */
private String iconData;
try
{
	AuthenticationSession authSession = secSignIdApi.requestAuthenticationSession(secSignID,
		"SecSignID Java integration example",
		"www.example.com",
		"127.0.0.1");
	sessionID = authSession.getAuthSessionID();
	// this field is read when the xhtm pattern is rendered and the value is inserted at: #{secsignid.iconData}
	iconData = new BASE64Encoder().encode(authSession.getAuthSessionIconData());
	log.log(Level.INFO,"Received the authentication session with ID '" + sessionID + "' for SecSignID user ID '" + userId + "'.");
	return "accesspass?faces-redirect=true"; // go to the page showing the access pass and update the displayed URL in the browser
}
catch(SecSignIDException exception)
{
	log.log(Level.SEVERE, "Error when requesting an authentication session for SecSignID '" + secSignID + "'", ex);
}

The AuthSession requested by the ID server may have several different statuses.

To request whether the AuthSession was accepted or declined, or if it is expired, the API method ‘SecSignIDApi.getAuthenticationSessionState’ can be used.

// Get the State
AuthenticationSessionState state = null;
try
{
	state = secSignIdApi.getAuthenticationSessionState();
}
catch (SecSignIDException exception)
{
	exception.printStackTrace();
}

It is necessary to react to the user accepting (‘AUTHENTICATED’) or denying (‘DENIED’) the session. The session can either be accepted, denied or remain in a state of uncertainty (‘PENDING’ or ‘FETCHED’).

The status can be compared to the constant from the class ‘AuthenticationSessionState’. If the session is accepted by the user he can be logged in to the underlying system or web application.

switch (state.getAuthSessionState()) {
	case AuthenticationSessionState.FETCHED:
	case AuthenticationSessionState.PENDING:
	{
		msg = "The session is still pending. Please accept the session in the SecSignApp on your smart phone.";
		break;
	}
	case AuthenticationSessionState.DENIED:
	{
		msg = "The session has been denied on the smart phone.";
		checkForState = false;
		break;
	}
	case AuthenticationSessionState.AUTHENTICATED:
	{
		try
		{
			secSignIdApi.releaseAuthenticationSession();
		} catch (SecSignIDException exception)
		{
			exception.printStackTrace();
		}
		msg = "Successfully Authenticated SecSign ID ""+state.getAuthenticatedSecSignId()+""";
		checkForState = false;
		break;
	}
//etc.
}

If the user or the client want to cancel the login process, the method ‘SecSignIDApi.cancelAuthenticationSession’ is used.

A new login with the same SecSign ID API instance can be implemented after that.

try
{
	secSignIdApi.cancelAuthenticationSession();
}
catch (SecSignIDException exception)
{
	exception.printStackTrace();
}

SECSIGN API CLASSES

The zip archive includes the folder ‘developer’, which contains the JavaDoc about the SecSign ID Java API classes.

Constructor and Description

• SecSignIDApi() – Constructor of the SecSign ID API bean
• SecSignIDApi(java.lang.String idServer, int idServerPort)
• requestAuthenticationSession(java.lang.String secSignID, java.lang.String serviceInfo, java.lang.String serviceAddress)
• getAuthenticationSessionState()
• cancelAuthenticationSession()
• releaseAuthenticationSession()

SECSIGN AUTHENTICATION SESSION

• byte[] getAuthSessionIconData()
• long getAuthSessionID()
• java.lang.String getRequestingServiceAddress()
• java.lang.String getRequestingServiceName()
• java.lang.String getSecSignID()
• void setAuthSessionIconData(byte[] authSessionIconData)
• void setAuthSessionID(long authSessionId)
• void setRequestingServiceAddress(java.lang.String requestingServiceAddress)
• void setRequestingServiceName(java.lang.String requestingServiceName)
• void setSecSignID(java.lang.String secSignId)

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 ASP.net/C#-API 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.

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.