YubiKey

Introduction

This document describes the screen layouts and database changes to support YubiKey strong authentication for Yubico webstore admin and customer accounts. The Yubico webstore is based on osCommerce version v2.2 Release Candidate 2a.

This integration feature makes it mandatory to use YubiKey OTP based strong two-factor authentication for osCommerce administrator accounts and optionally makes it available to customer accounts.

YubiKey authentication for webstore administrator account

Yubico osCommerce webstore administrator login screen:

Yubico webstore administrators need to enter a valid YubiKey OTP and the password to login to the webstore. For convenience, there is no need to provide the user name for admin login; only the YubiKey OTP and Password is required to authenticate an admin user.

The User name field is derived from the YubiKey OTP. Token ID which are the first 12 char. of the 44 char. OTP is treated as the User name for osCommerce admin user. For better user experience and convenience in identifying a realworld user for a given admin account, we have added two new fields in administrator table for storing administrator first and last name.

At the time of initial setup and configuration of osCommerce, the first administrator account needs to be created. This osCommerce behavior remains the same with the only change that the administrator will see the above screen and will need provide the OTP, the password and click the "Create" button that appears in place of the "Login" button above.

Yubico osCommerce webstore administrator list screen:

We have modified the administrator screen to display more information like the first and last name etc.

Admin screen to create a new "Administrator":

We have modfified the create administrator interface for accepting first and last name alongwith YubiKey OTP as well as the password.

Admin screen to update an "Administrator" account:

We have modfified the update administrator interface for modifiying (editing) first and last name information alongwith YubiKey OTP as well as the password.

We can also use this interface for replacing the assigned YubiKey for existing administrators as well as changing the password.

There is one to one mapping between the YubiKey and the administrator i.e. an admininstrator can only be assigned one YubiKey.

YubiKey authentication for webstore user account

When a user creates a new customer account, he/she will get an option to select authentication preferences. Below the "Your Password" box on the Create new user account screen a new box "Your Authentication Preferences" is added as shown below. It has options for setting customers authentication preferences:

The default is "Use YubiKey OTP and password". Users ordering the YubiKeys for the first time can choose the option "Use Email-Address and Password (select this if you do not already have a yubiKey)" at the time of registration and after receiving their first key, can edit their account settings to choose "Use YubiKey OTP and password" to enable strong authentication.

Customer login screen is modified as follows:

Customers who have selected YubiKey strong authentication need to enter their YubiKey and the password. Other customers need to provide the email ID specified at the time of account creation and the password.

Customers can update their authentication preferences by logging into their account and select "My Account" + "View or change my authentication scheme":

Step 1

Step 2 The following screen is shown. The customer can now update the authentication preferences as desired:

Each customer can assign multiple YubiKey to its account provided that the YubiKey is not already assigned to any other account.

Forgotten password interface for webstore user account

Password forgotten interface is modifyed as follows:

If a customer has not opted for YubiKey authentication, the password reset mechanism remains unchanged. i.e. on click of "Continue" button, the server resets the password and sends an email with the new password to the registered email ID.

If a customer has registered for YubiKey authentication; on click of "Continue" button, the customer is presented with 3 selection options (radio buttons) on the screen as follows:

The following logic is implemented on the server for each of the above options:

• Option a - "I forgot my Password": The OTP is validated and if valid, the password is reseted and sent in an email to the registered email ID.
• For the other two options: the User authentication preference is set to "Use Email-Address and Password" mode and the password is reset and sent in email to the registered email ID.

Database schema modifications

We have added a table customers_yubikey_mapping for maintaining the YubiKey and the customer ID mapping. Table schema is as follows:

DROP TABLE IF EXISTS `customers_yubikey_mapping`;
CREATE TABLE `customers_yubikey_mapping` (
  `customers_yubikey_mapping_id` int(11) NOT NULL auto_increment,
  `customers_id` int(11) NOT NULL,
  `customers_yubikey_tokenId` varchar(44) NOT NULL,
  PRIMARY KEY  (`customers_yubikey_mapping_id`),
  KEY `IDX_CUSTOMERS_KEY_MAP` (`customers_id`,`customers_yubikey_tokenId`)
) ENGINE=MyISAM AUTO_INCREMENT=7 DEFAULT CHARSET=latin1;

We have added a new column in the customer table for storing the customer authentication type:

ALTER TABLE `customers` ADD `customers_authentication_type` int(1) NOT NULL default '1';

We have modified the administrator table scheme as follows:

ALTER TABLE `administrators` ADD `admin_firstname` varchar(32) NOT NULL;
ALTER TABLE `administrators` ADD `admin_lastname` varchar(32) NOT NULL;

Validation of YubiKey OTP

We use the php-yubico module (Auth_Yubico-1.8.tgz file) from Yubico available at http://code.google.com/p/php-yubico/ to validate the YubiKey OTPs with online Yubico validation server.

More details and documentation for the php validation module are available at:

http://www.yubico.com/developers/api/
http://code.google.com/p/php-yubico/wiki/ReadMe