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 PHP 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. regarding the reason.

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.

If no session can be requested, an exception will be thrown which should be caught. The exception contains an error message

try
{
   $secSignIDApi = new SecSignIDApi();
   $authsession = $secSignIDApi->requestAuthSession($_POST['secsignid'], 'Name of Webservice', $_SERVER['SERVER_NAME']);
}
catch(Exception $e)
{
   echo "An error occured when requesting session: " . $e->getMessage();
}

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 request later 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.

• 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
• SecSign ID: The user name
• AuthSession ID: The ID of the requested session
• Service Name: The name of the PHP project, respectively of the web site
• Service Address: The IP address, respectively the URL of the PHP project, respectively of the website

if(isset($authsession))
{
   // Show the access pass
   echo "<img alt='' src='data:image/png;base64," . $authsession->getIconData() . "'/>";
   // Store the session data in a form
   // ...
   echo "<input type='hidden' name='requestid' value='" . $authsession->getRequestID() . "'>";
   echo "<input type='hidden' name='secsignid' value='" . $authsession->getSecSignID() . "'>";
   echo "<input type='hidden' name='authsessionid' value='" . $authsession->getAuthSessionID() . "'>";
   echo "<input type='hidden' name='servicename' value='" . $authsession->getRequestingServiceName() . "'>";
   echo "<input type='hidden' name='serviceaddress' value='" . $authsession->getRequestingServiceAddress() . "'>";
   // ...
}

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 will be caught.

// Create a new session instance, which is needed to check its status.
$authsession = new AuthSession();
$authsession->createAuthSessionFromArray(array(
   'requestid' => $_POST['requestid'],
   'secsignid' => $_POST['secsignid'],
   'authsessionid' => $_POST['authsessionid'],
   'servicename' => $_POST['servicename'],
   'serviceaddress' => $_POST['serviceaddress']
));
// Get the state of the session
// server: https://httpapi.secsign.com
// port: 443
$secSignIDApi = new SecSignIDApi();
$authSessionState = $secSignIDApi->getAuthSessionState($authsession);

After the session has been accepted by the user via the smart phone the session shows the state ‘Authenticated‘.

The user can now be logged into the PHP project or the website, respectively another login can be accepted. If the user denies the session, a corresponding notification can be sent. If the user accepts the session, it must be released with ‘releaseAuthSession‘. If the session is denied or cancelled by the server, a release will not be necessary.

The explicit release is required as the server does not know how long the accepted session shall be kept until the client, respectively the web site, requests the state.

If the session is neither accepted nor denied, it remains pending. The Access Pass can then be shown again. If the session is cancelled by the server or has expired, the user should not be logged in.

// The authentication session has been accepted. This is the only case
// where the web application can login the user in the underlying system.
if($authSessionState == AuthSession::AUTHENTICATED)
{
   $secSignIDApi->releaseAuthSession($authsession);
   echo "Welcome" . $_POST['secsignid'] . " Your account...";
}
// The user has denied the session.
else if($authSessionState == AuthSession::DENIED)
{
   echo "You have denied the session...";
}
// The authentication session is still pending. The user didn't accept or denied the auth session yet.
else if(($authSessionState == AuthSession::PENDING) || ($authSessionState == AuthSession::FETCHED))
{
   echo "The auth session is still pending... it has neither been accepted nor denied.";
   // Show access pass again...
}
else
{
   echo "The auth session has an unknown status " . $authSessionState . ". therefore you cannot be logged in...";
}

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

$secSignIDApi->cancelAuthSession($authsession);

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

The method for requesting a session requires the SecSign ID as parameter, the name of the website or of the PHP project as well as an IP address, respectively the URL of the website. An AuthSession object will be received as return value.

All other functions of the SecSignIDApi class require a valid AuthSession object as a parameter.

The functions are:

• requestAuthSession($secsignid, $servicename, $serviceadress)
• getAuthSessionState($authSession)
• cancelAuthSession($authSession)
• releaseAuthSession($authSession)

As the single values of the session must be stored there is the auxiliary function ‘createAuthSessionFromArray’ in the class ‘AuthSession‘. A named array, respectively an associative array, is accepted as parameter.

The fields of the array are as follows:

• requestid
• secsignid
• authsessionid
• servicename
• serviceaddress
• authsessionicondata

Each of these fields must exist in order to have an AuthSession object created out of it. This object can then request Get functions as normal.

The Get functions are:

• getRequestID()
• getSecSignID()
• getAuthSessionID()
• getRequestingServiceName()
• getRequestingServiceAddress()
• getIconData()

All return values are of the type ‘String‘.

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.