Digital Person a Online Administrator Guide 20131009

7/21/2019 Digital Person a Online Administrator Guide 20131009

1/65

DigitalPersona, Inc.

DigitalPersona OnlineVersion 5.5.0

Administrator Guide


2/65

DigitalPersona, Inc.

19962013 DigitalPersona, Inc. All Rights Reserved.

All intellectual property rights in the DigitalPersona software, firmware, hardware and documentation included with ordescribed in this guide are owned by DigitalPersona or its suppliers and are protected by United States copyright laws,other applicable copyright laws, and international treaty provisions. DigitalPersona and its suppliers retain all rights notexpressly granted.

DigitalPersona, One Touch, and U.are.Uare trademarks of DigitalPersona, Inc., registered in the United States and othercountries. Microsoft, ActiveX, Internet Explorer, JScript, Windows, Windows NT, and Windows Server are registeredtrademarks and SQL Server is a trademark of Microsoft Corporation in the United States and other countries. Oracle, Javaand JavaScript are trademarks or registered trademarks of Oracle America, Inc. in the United States and other countries. Allother trademarks are the property of their respective owners.

This document and the software it describes are furnished under license as set forth in the License Agreement screen(s)may be shown during the installation process.

Except as permitted by such license or by the terms of this guide, no part of this document may be reproduced, stored,transmitted, and translated, in any form and by any means, without the prior written consent of DigitalPersona. Thecontents of this guide are furnished for informational use only and are subject to change without notice. Any mention ofthird-party companies and products is for demonstration purposes only and constitutes neither an endorsement nor a

recommendation. DigitalPersona assumes no responsibility with regard to the performance or use of these third-partyproducts. DigitalPersona makes every effort to ensure the accuracy of its documentation and assumes no responsibility orliability for any errors or inaccuracies that may appear in it.

Technical Support

Upon your purchase of a Developer Support package (available from http://buy.digitalpersona.com), you are entitled to aspecified number of hours of telephone and email support.

Feedback

Although the information in this guide has been thoroughly reviewed and tested, we welcome your feedback on anyerrors, omissions, or suggestions for future improvements. Please contact us at

[email protected]

or

DigitalPersona, Inc.720 Bay Road, Suite 100Redwood City, California 94063USA

(650) 474-4000(650) 298-8313 Fax

Document Publication Date: October 9, 2013


3/65

Table of Contents

DigitalPersona Online | Administrator Guide 3

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Target Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Whats new in this version? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Migrating from version 4.4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2 Functional Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Deploying DigitalPersona Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Using a DigitalPersona Online-Secured Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Registering User Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Authenticating with DigitalPersona Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Account Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Additional client features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3 Online Authentication Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Set up the Online Authentication Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Configure IIS (Internet Information Server) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Create the Authentication Server databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Application ID and Key Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Tracking System Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Operation Field Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Other Operation Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Deployment Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Database Security and Privacy by Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Application ID and Key Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Distributing Client Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Uninstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4 Online Client Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30


Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Developer Sample Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31


4/65

Table of Contents


5 Online Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32


Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Installing the sample Online Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Configuring IIS (Internet Information Server) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Uninstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6 Code Integration Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Initializing and Embedding the ActiveX Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

ActiveX Control Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Listening for events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Adding and configuring AppControl.ASP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Integrating DigitalPersona Online in Web Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Account Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

7 ActiveX Control API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

DpOnlineClient.DpOnline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Event Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Event Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

SysError Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

A Warranties and General Provisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Limited Warranties and Warranty Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

General Provisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62


5/65

Table of Contents



6/65

Table of Contents



7/65

Table of Contents



8/65


Introduction 1

The DigitalPersona Online Administrator Guide provides instructions on installing, configuring and utilizingDigitalPersona Online, an end-to-end server and client software solution that enables businesses to provide

increased security to customers, partners and employees by adding the security of advanced fingerprintauthentication to their Web-based applications.

DigitalPersona Online also provides a sample website demonstrating its features and contains detailedinstructions showing developers how to quickly and easily integrate fingerprint authentication functionalityinto a Web application using the DigitalPersona Online ActiveX control and its API.

There is also a companion document, the DigitalPersona Online Quick Start Guide, located in the Docsdirectory within the product package. It may be used to quickly set up a prototype or demonstration site, andcan be used as a general reference when setting up your production environment. More detailed instructionsfor setting up your production environment are provided later in this document.

Target Audience

This guide provides information and procedures for those who will install, configure and administerDigitalPersona Online, as well as the developers who will create web-based applications incorporatingfingerprint authentication using this software.

Developers should have

A high-degree of familiarity with Microsoft Internet Information Server, which is required not only toserve Web applications to users, but to run the code that provides the fingerprint authenticationfunctionality.

Basic knowledge of Microsoft SQL Server in order to create the required databases, tables, and fieldsneeded for DigitalPersona Online.

Strong programming skills in languages supported by Microsoft Internet Information Server (IIS) such asActie Server Pages (ASP), JScript and VBScript.

Basic knowledge of HTML, JavaScript and ActiveX is also required in order to embed Online Clientcomponents into your web application using the sample code provided with the DigitalPersona OnlineApplication Server SDK.


9/65

Chapter 1: Introduction System Requirements


System Requirements

The major components may all be installed on the same computer for testing purposes. However, in mostscenarios, each major component (i.e. the Authentication Server, the sample Application Server and the SQL

Server) will be installed on separate computers. The list below shows recommended or minimum requirementsfor the entire system. For specific requirements for each component, see the chapter on that component.

Microsoft Windows 2008 or later

Microsoft SQL Server (or SQL Server Express) 2005 or later

Microsoft Internet Information Server (IIS) 7 or 8 (Optional install requiring OS install disc)

JRE (Java Runtime Environment) x86, 1.7 or later

.NET Framework 2.0 or later

Classic ASP (not ASP.NET)

DigitalPersona Online client

Microsoft Windows XP/7/8

Internet Explorer 8 - 11

Chapter Overview

Chapter 1, Introduction(this chapter), describes the target audience for this guide, lists system requirementsand provides an overview of each chapter in this document.

Chapter 2, Functional Overview, describes the software and hardware components that interoperate to providethe fingerprint authentication functionality of DigitalPersona Online and an overview of a typicalDigitalPersona Online server and client deployment. It demonstrates how DigitalPersona Online operates froman end-users perspective and describes the functionality developers must incorporate in Web applications toachieve fingerprint authentication functionality.

Chapter 3, Online Authentication Server, describes the Authentication Server, its installation and configuration.

Chapter 5, Online Application Server, describes the sample Application Server, its installation and configuration.

Chapter 4, Online Client Installation, describes the Online Client and the Developer Sample Site, includinginstallation instructions and an overview of the DigitalPersona Online ActiveX Control features.

Chapter 6, Code Integration Guidelines, describes how to use the ActiveX control, HTML and JavaScript tofacilitate the registration and authentication processes at the API level.

Chapter 7,ActiveX Control API Reference, provides the API documentation for properties, methods and events ofthe ActiveX control that facilitates the authentication and registration process.


10/65

Chapter 1:Introduction Compatibility


Appendix 8, Warranties and General Provisions, contains the DigitalPersona limited warranties and warrantyservice and the general provisions statements.

An index is also included for your reference.

Compatibility

This product is compatible with DigitalPersona Pro Enterprise 5.5 and later.

DigitalPersona Online 5.5.0 Authentication and sample Application Servers are compatible with theDigitalPersona Online Client, versions 4.4.1 and 5.5.0.

Whats new in this version?

Database changes

A new Templates table has been added to the UareUOnlineUsers database to store fingerprints templatesfor multiple fingers. Update script provides automatic migration of all existing fingerprint data to the newtable.

Structural integrity of database is improved using foreign keys.

Direct access to tables is eliminated, all data access logic is moved to stored procedures.

Performance is improved with data indexing.

SQL server security is improved by using Windows Integrated Security for all database connections.

Application Server SDK sample changes

Safe password authentication - Uses better practices for safe password authentication (password hashingvs clear text passwords) while keeping the sample code simple.

ASP programming - Uses better practices for ASP programming (master pages, server includes) to reducesample code base and get you closer to the essential logic.

Web programming - Uses better practices for web programming (CSS vs direct page scripting) to furtherreduce the sample code base.

Online Client changes

Support for multiple finger enrollment. Simplified configuration of the ActiveX component, while supporting backward compatibility.


11/65

Chapter 1:Introduction Migrating from version 4.4.1


Migrating from version 4.4.1

The recommended procedure for migrating from version 4.4.1 to version 5.5.0 is provided below. For versionsprevious to 4.4.1, you should upgrade to 4.4.1 and then migrate to 5.5.0.

1. Install DigitalPersona Online Authentication Server 5.5.0 on a computer that meets the minimumrecommended requirements for the server. (see Chapter 3, Online Authentication Server,onpage 18). Donot remove or attempt to upgrade the 4.4.1 Authentication Server at this time.

2. Copy your existing UareUOnlineUsers database containing fingerprint data to the SQL Server on the newcomputer and and upgrade it by running the UareUOnlineUsers.db.5.5.0.upd.sqlandUareUOnlineUsers.sp.5.5.0.sqlscripts provided in the DigitalPersona Online Authentication Server\Databasescriptsfolder within the product package.

3. Create a new UareUOnlineSessions database by running the UareUOnlineSessions.db.5.5.0.sqlandUareUOnlineSessions.sp.5.5.0.sqlscripts provided in the DigitalPersona Online AuthenticationServer\Database scriptsfolder within the product package. (Note that the previous data in this database

does not need to be copied as there is no permanent user data that needs to be migrated.)4. Configure the new Authentication Server 5.5.0 and its database connection as described in Chapter 3,

Online Authentication Server,onpage 18.

5. Set up a staging environment containing a copy of your current web application and a snapshot of yourcurrent user database (or a test database).

6. Reconfigure your staging web application by modifying the AuthServerAddress parameter of the OnlineClient ActiveX, so that it starts using the new Authentication Server (See page 36.)

7. Test your web application in the staging environment to ensure that it is working with the new OnlineAuthentication Server.

8. When configuration has been tested and is ready to deploy, you may need to repeat step 2 again tosynchronize with the existing UareUOnlineUsers database.

9. Deploy the web application and Online Authentication Server to the production environment byswitching from the current production server to the staging one. If any problem arises, you can safelyswitch back with a minimal service interruption.

10. Upgrade the DigitalPersona Online Client on all computers that will be accessing your Online-securedapplication.

11. After you are sure that the production environment is stable, you can remove the 4.4.1 OnlineAuthentication Server.


12/65

Chapter 1:Introduction Additional Resources


Additional Resources

The following additional resources are available to assist you in using this product.

Description Document or URL

Fingerprint recognition, including the history and basicsof fingerprint identification and the advantages ofDigitalPersonas Fingerprint Recognition Algorithm

The DigitalPersona White Paper: Guide to FingerprintRecognition (Fingerprint Guide.pdf located in the Docsfolder in the DigitalPersona Online SDK product package)

Late-breaking news about the product The Readme.txt files provided in the root directory of theproduct package as well as in some subdirectories

Web Portal & Forum for DigitalPersona Developers http://devportal.digitalpersona.com

Latest updates for DigitalPersona software products http://www.digitalpersona.com/support/updates
http://www.digitalpersona.com/webforums/http://www.digitalpersona.com/support/downloads/software.phphttp://www.digitalpersona.com/support/downloads/software.phphttp://www.digitalpersona.com/webforums/


13/65


Functional Overview 2

The DigitalPersona Online SDK allows you to control access to protected Web applications using fingerprintauthentication functionality. A DigitalPersona Online-secured application allows users to register

authentication credentialsincluding a user name, password and fingerprintand provides a way for a userto authenticate to the application using those credentials.

This chapter provides an overview of how DigitalPersona Online components are deployed to providefingerprint authentication functionality. In addition, it demonstrates the end-user experience when interactingwith a DigitalPersona Online-secured application.

Deploying DigitalPersona Online

Any DigitalPersona Online deployment must contain at least one authentication server, an application server

and a client workstation, as illustrated in the following figure.

The authentication server performs the authentication for authorized DigitalPersona Online-secured Webapplications, which are hosted on the application server. The client workstation must have the DigitalPersonaOnline Client software and a U.are.U Fingerprint Reader to provide fingerprint authentication functionality tousers accessing DigitalPersona Online-secured Web applications.

Using a DigitalPersona Online-Secured Web Application

This section illustrates the functionality of DigitalPersona Online by describing a simple Web site that integrates

fingerprint authentication functionality, demonstrating how DigitalPersona Online could be used in yourapplication.

DigitalPersona Online Deployment Authentication Server performs authentication for authorized DigitalPersona Online-secured web applications

Application Server hosts DigitalPersona Online-secured web application and stores authentication credentials

Client software with reader allows user to authenticate to DigitalPersona Online-secured web applications

Authentication Server Application Server Client Workstation with Reader


14/65

Chapter 2:Functional Overview Registering User Credentials


Our sample implementation contains three Web pages. The first is where users can register their credentials,such as fingerprints and/or passwords, to later be used for accessing a protected section of the Web site. Then,in order to actually access the protected section, the site provides another Web page that allows a user toauthenticate to the site using their supplied credentials prior to accessing the protected section. Finally, a thirdpage gives registered users the ability to modify their credentials by registering another fingerprint.

NOTE: The examples described in this section are for instructional purposes only; they are not intended torecommend any particular installation, configuration or deployment. DigitalPersona Online fingerprintauthentication functionality can be integrated in a variety of ways to suit the needs of any Webapplication.

Registering User Credentials

Any DigitalPersona Online-secured Web application must allow a user to register their credentials, fingerprintsand passwords. In the following figure, a Web page was created with user name and password fields and abutton the user can click to register fingerprints with the Web application. In addition, this Web page allows the

user to determine their authentication policy.

NOTE: A typical Web application will determine the authentication policy not the user.

When presented with this page, the users can type their user name and password in the appropriate fields andclick the Register for DigitalPersona Online button to start the fingerprint registration process.

NOTE: Web applications can, of course, request other credential information, such as a PIN number.

Users must first register theircredentials with their Web site to

access protected sections orfunctions of their online application.


15/65

Chapter 2:Functional Overview Registering User Credentials


When the DigitalPersona Online button is clicked, the Fingerprint Registration wizard launches, allowing theusers to choose a fingerprint to register. Then on-screen instructions guide them through the registrationprocess.

When users supply all required authentication credentials and submits the form, the registration data must beprocessed by a component of the Web application to

Evaluate the supplied credentials against the authentication policy to ensure validity and completeness.

Determine whether the user is permitted to register with the Web application in order to gain access toprotected data or functions.

Add the authentication credentials to a database for later use during authentication.

A Web page that implements DigitalPersona Online registration functionality must also contain event handlersto listen for events related to the registration process, as described in Fingerprint Registration Event Handleron

page 41.

Users choose the finger they want to use to log on

and then follow the on-screen instructions to register it.


16/65

Chapter 2:Functional Overview Authenticating with DigitalPersona Online


Authenticating with DigitalPersona Online

A DigitalPersona Online-secured Web application must provide a way for users who have registered theircredentials to log on to protected sections of the application.

Any Web page implementing fingerprint authentication must contain the necessary authentication credentialfields, which include the user name and any other field needed to fulfill the requirements of the authenticationpolicy.

The example in the previous figure allows a user to type their password and click the Logon with Password Onlybutton or simply touch the fingerprint reader to gain access to the protected section of the Web site. Thisassumes the authentication policy permits these methods of authentication.

When the form is submitted, a component of the Web application must process the authentication data in thefollowing ways:

Evaluate the supplied credentials against the credentials required by the authentication policy for validityand completeness.

Perform the authentication process to determine whether there is a match between the suppliedcredentials and the stored credentials.

Grant access to the DigitalPersona Online-secured portions of the Web application.

A Web page that implements DigitalPersona Online authentication functionality should contain event handlersto listen for authentication events, which is described in detail in Fingerprint Authentication Event Handlerson

page 46.

When users register their credentials,they can log on to the protected

sections of their online application.


17/65

Chapter 2:Functional Overview Account Modification


Account Modification

The DigitalPersona Online SDK allows developers to provide account modification functionality for registeredusers, where they can specify a new authentication policy or even change the fingerprint they use forauthentication.

The Web component that processes the new credential information must do the following:

Evaluate the supplied credentials against the credentials required by the authentication policy for validityand completeness.

Add the new credentials to the database, ensuring that the records being updated correspond to theappropriate user.

Similar to the registration process described in Registering User Credentialsonpage 14, event handlers shouldbe added to the account modification Web page to help facilitate the fingerprint registration process.

Additional client features

Additional features available through the DigitalPersona Online ActiveX Control are described in Chapter 7,ActiveX Control API Reference.

A DigitalPersona Online SDK allows registeredusers of a Web application to change their

authentication policy and the fingerprint they use.


18/65


Online Authentication Server 3

The DigitalPersona Online Authentication Server is a reliable and scalable back-end authentication server builtto provide fingerprint authentication for any DigitalPersona-secured web application.

This chapter provides instructions on the installation of the DigitalPersona Online Authentication Server,including system requirements, setting up the requisite databases, configuring your web server to work withDigitalPersona Online and uninstallation of the component.

This chapter covers the following topics relating to the DigitalPersona Online Authentication Server.

System Requirements

Set up the Online Authentication Server

Configure IIS (Internet Information Server)

Create the Authentication Server databases Tracking System Usage

Deployment Considerations

Uninstallation

System Requirements

Before installing the DigitalPersona Online Authentication Server, ensure that your target computer meets theminimum hardware and software requirements specified below.

Hardware Requirements

Following are the minimum hardware requirements:

Processor: 1 GHz (x86 processor) or 1.4 GHz (x64 processor)

Memory: 4 GB RAM on both the authentication database server and authentication server PCs

5 GB available hard-disk space on both the database and server PCs

Software Requirements

Following are the minimum software requirements:DigitalPersona Online servers

Microsoft Windows 2008 or later

Microsoft SQL Server (or SQL Server Express) 2005 or later


19/65

Chapter 3:Online Authentication Server Set up the Online Authentication Server


Microsoft Internet Information Server (IIS) 7 or 8 (Optional install requiring OS install disc)


.NET Framework 2.0 or later

Classic ASP (not ASP.NET)DigitalPersona Online client

Microsoft Windows XP/7/8

Internet Explorer 8 - 11

Set up the Online Authentication Server

To install and set up the Online Authentication Server

1. Install the DigitalPersona OnlineAuthentication Server by running Setup.exe from the following

location within the product package: DigitalPersona Online Authentication Server\.2. The Installation Wizard will launch.


20/65

Chapter 3:Online Authentication Server Set up the Online Authentication Server


3. Follow the online instructions to complete the wizard.

4. When requested, enter the name of the database server you will be using with DigitalPersona Online.

5. Upon completion of the wizard, you will be asked to restart your system.

6. Create the Online database - During the installation of the Online Authentication Server, several SQLscripts are copied to the target computer. They are also available in the DigitalPersona Online

Authentication Server\Database scriptsfolder of the product package.

These scripts can be used to create the databases used by the Online Authentication Server and theOnline Developer Sample Site. Alternatively, you can create the tables manually by following the detailed

instructions in the section Create the Authentication Server databasesonpage 22

In your Microsoft SQL Server management tool, select File, Openand navigate to the followingdirectory on your computer: C:\Program Files\DigitalPersona\Online Server\SQLScripts

For new installations, execute the provided SQL scripts in the following order.

UareUOnlineSessions.db.5.5.0.sql

UareUOnlineSessions.sp.5.5.0.sql

UareUOnlineUsers.db.5.5.0.sql

UareUOnlineUsers.sp.5.5.0.sql

For upgrading an installation (from version 4.4.1 only), execute the provided SQL scripts in thefollowing order.

UareUOnlineSessions.db.5.5.0.upd.sql

UareUOnlineUsers.db.5.5.0.upd.sql

7. Configure IIS (refer to the section Configure IIS (Internet Information Server)onpage 21.


21/65

Chapter 3:Online Authentication Server Configure IIS (Internet Information Server)


Configure IIS (Internet Information Server)

In IIS, you will need to enable Anonymous Authentication.

1. Enable Anonymous Authentication - In IIS Manager, select the website. In Features View, under the IIS

heading, open the Authenticationfeature.

2. Select Anonymous Authenticationin the list. Then click Enablein the Actions pane. Click Edit, and in theresulting dialog, select Application pool identity.


22/65

Chapter 3:Online Authentication Server Create the Authentication Server databases


Create the Authentication Server databases

You must create two databases used by the server software for authentication service operations, on theauthentication server database computer.

These databases may be created using the SQL scripts provided with the software package (see step 6 of Set upthe Online Authentication Serveronpage 19), or you may create them manually by following the detailedinstructions provided in the following sections.

UareUOnlineUsers Database

Create the UareUOnlineUsers database, and then add the specified tables and their respective fields accordingto the details provided in the following sections.

Applications Table

The Applications table contains the Application ID and Application Key used by application providers whenintegrating DigitalPersona Online Server into their applications. In addition, you must specify the maximumnumber of users allowed for a given application provider.

Create the Applications table, and then add these fields to it.

Records table

The Records table contains data used in the authentication process. It stores the Record ID and the associatedfingerprint template and private key for use during the authentication and account modification processes. Italso stores the Application ID to associate a user record with an application provider.

Create the Records table, and then add these fields to it.

Fieldname Type Size Nulls Default Key

App_Id char 100 no Primary, clustered

App_Key char 100

Max_Users int 4


RecordId int 4 no identity(1,1) primary key, clustered

HexPrivKey varchar 1400

HexPubKey varchar 1400


23/65

Chapter 3:Online Authentication Server Create the Authentication Server databases


The RecordId field of the records table is a key field. It auto-increments (identity if set to true), starting at 1 (seedequals 1), and increments by 1 (increment equals 1).

Templates table

The Templates table contains fingerprint templates required for fingerprint matching.

Fingerprint template data is stored in the Data field.

The Finger field keeps a finger number (N) as a bit field with 1 in the Nth position (I.e. 2N). The finger numbersgo from 1 (left pinky) to 10 (right pinky).

The RecordId field associates the fingerprint template with an authentication record. There may be up to 10templates stored for every record.

Create the Templates table, and then add these fields to it.

UsageLog table

The UsageLog table contains data that allows you to monitor registration and authentication activity on yourDigitalPersona Online Server.

NOTE: Monitoring activity using the data in this table, as well a description of each field, is described in thesection Tracking System Usageonpage 26.

Create the UsageLog table, and then add these fields to it.

App_Id char 100 foreign key, references Applications (App_Id)

Status tinyint 1 no 1


RecordId int 4 no Foreign key, references Records (RecordId)

Data text

Finger int 4 no 64


RecordId int 4 no foreign key, references Records (RecordId)

LogNow datetime 8 no GetDate()



24/65

Chapter 3:Online Authentication Server Application ID and Key Generation


UareUOnlineSessions Database

The UareUOnlineSessions database consists of only one table that contains information used by theauthentication server software to establish sessions between the client and the authentication server.

Session Table

Create the Session table, and then add these fields to it.

The SessionId field of the session table is a key field. It auto-increments (identity is set to true), starting at 1(seed equals 1), and increments by 1 (increment equals 1).

Application ID and Key GenerationEvery application is identified by Application ID, and it must be provided with a unique Application Key whichwill be used for encryption together with user keys. The key must be generated at the moment when theApplication ID is added to the Online Authentication Server database. The key is generated in theAddApplication stored procedure of the UareUOnlineUsers database.

A sample key generator is provided in the DigitalPersona Online Server software package to demonstrate howsoftware can be written to generate IDs and keys automatically and store them in the authentication serverdatabase. The sample generator uses an Application ID and concatenates it with a random 9-digit decimalnumber. You may want to modify this algorithm or/and increase the key length to improve security.

Following are the specifications for application IDs and keys:

Application keys are case-sensitive

Application IDs and keys cannot contain spaces

When an application key is generated, it must be added to the appropriate fields in the authenticationserver database.

LogAgent char 24

LogOper char 1

SerialNum char 48


SessionId int 4 no identity(1,1) primary key

Nonce int 4 no

DateTime datetime 8 no GetDate()



25/65

Chapter 3:Online Authentication Server Application ID and Key Generation


Connecting to the Databases

When both databases are created, connect to them by registering an ODBC data source with Windows for eachon the authentication server computer.

To create a DSN for each database on the authentication server computer

1. Click Start, and then point to Programs. Point to Administrative Tools, and then click Data Sources(ODBC).

2. Click the System DSNtab.

3. Click the Addbutton.

4. Select SQL Serverin the list, and then click Finish.

5. In the Nametext box, type UareUOnlineUsers.

If you are creating a DSN for the second database, type UareUOnlineSessions.6. In the Serverlist, click the name of the database server computer, and then click Next.

7. Click the first option button, indicating that Integrated Windows authentication will be used whenconnecting to the database.

8. Click Next. Click the Change the default database tobutton, and then in the list, click the databasename: UareUOnlineUsersor UareUOnlineSessions.

9. Click Next, and then click Finish.

10. Click the Test Data Sourcebutton to ensure the settings are correct. If they are not, repeat the steps inthis section; otherwise, click OKon each subsequent dialog box to close it.

Choose Integrated Windows authentication


26/65

Chapter 3:Online Authentication Server Tracking System Usage


Tracking System Usage

This chapter explains how data involved in three operationsregistration, authentication, and accountmodificationcan be used to track the usage of your DigitalPersona Online Server.

When users register their credentials, authenticate with your server, or modify their registered credentials,certain data is logged in the usagelog table of the UareUOnlineUsers database: the record ID, date, and time ofthe operation, and the type of operation performed.

NOTE: The data is logged only when the operation is successfully completed; there is no data recorded whenany of these operations fails, and, as a result, the failure cannot be traced.

How this data is used depends on your needs as an authentication service provider. Typically, it can be used tobill application providers who subscribe to your service. Reports can be compiled based on the total number ofnew registrations, registered users, or authentications performed, for example. To acquire data for a report, SQLqueries can be issued to the authentication server database that obtains data meeting the criteria required for

the report.

Operation Field Data

The following describes the data logged after successful completion of the registration, authentication, andaccount modification operation:

Record ID.The record ID is logged in the recordid field after each operation and is associated with theapplication ID in the records table of the UareUOnlineUsers database. This is beneficial if you areproviding authentication service to multiple application providers and require a way to identify whichoperations belong to a specific application provider.

Event date and time.The date and time an operation is completed is logged in the lognow field.Specifying a date range in a SQL query using the values in this field can group operations that correspondto billing cycles, for example.

Operation type.The type of operation is logged in the logoper field, indicated by one of threecharacters R, A, or Uwhich indicates registration, authentication, or update (account modification),respectively.

Other Operation Data

There is an additional field in the usagelog table that is used to ensure that the client making the request for anoperation is permitted to do so:

HTTP agent component name.Logged in the logagent field, the HTTP agent component name is usedin conjunction with the client IP address in the operation permission process described previously.

NOTE: These fields are not used to track system usage; they are only included in this table because they areassociated with each operation.


27/65

Chapter 3:Online Authentication Server Deployment Considerations


Deployment Considerations

This chapter discusses some of the areas that should be considered when planning the deployment ofDigitalPersona Online Server, such as security, privacy, application key generation, and software distribution. It

is intended for anyone who manages and is responsible for the deployment of the DigitalPersona OnlineServer.

Database Security and Privacy by Design

You should design methods that ensure database security and the privacy of end users when deployingDigitalPersona Online Server.

Following are two suggested methods for ensuring security and privacy:

Maintain separate application provider and authentication server databases. Information in theauthentication server database can be directly linked to end-user personal information stored in an

application providers database. By separating the data, the security of two databases must becompromised instead of one, effectively doubling security.

Store the authentication server database on a computer that is only accessible by the authenticationserver computer and not by the Internet. This will reduce the risk of unauthorized access to yourauthentication server database by reducing remote access options. As an added security measure, youshould install firewall software between them.

Application ID and Key Generation

Every application is identified by Application ID, and it must be provided with a unique Application Key whichwill be used for encryption together with user keys. The key must be generated at the moment when the Appli-

cation ID is added to the Online Authentication Server database. The key is generated in the AddApplicationstored procedure of the UareUOnlineUsers database.

A sample key generator is provided in the DigitalPersona Online Server software package to demonstrate howsoftware can be written to generate IDs and keys automatically and store them in the authentication serverdatabase. The sample generator uses an Application ID and concatenates it with a random 9-digit decimalnumber. You may want to modify this algorithm or/and increase the key length to improve security.

Following are the specifications for application IDs and keys:

Application keys are case-sensitive

Application IDs and keys cannot contain spaces

When an application key is generated, it must be added to the appropriate fields in the OnlineAuthentication Server database


28/65

Chapter 3:Online Authentication Server Distributing Client Software


Distributing Client Software

In order for end users to use your authentication serverin conjunction with the online application providedby the application providerthey will need a U.are.U Fingerprint Reader and DigitalPersona Online Clientsoftware that is compatible with the authentication server software installed on your site. End users can acquirethe reader from resellers listed on the DigitalPersona Web site at www.digitalpersona.com.

You are solely responsible for devising a method, such as a download or CD, to distribute versions of theDigitalPersona Online Client software to your application providers who, in turn, distribute it to their end users.


29/65

Chapter 3:Online Authentication Server Uninstallation


Uninstallation

This section provides instructions for removing the Online Authentication Server software.

To remove the Online Authentication Server software1. Open Control Panel, and then open Add/Remove Programs.

2. Click DigitalPersona Online Authentication Server, and then click the Change/Removebutton.

A dialog box prompts you to confirm that you want to remove the software.

3. Click Yesto proceed.

A dialog box prompts you to close all open applications before proceeding with the removal of thesoftware.

4. Click OK.

When the software is removed, you are prompted to restart the computer.

5. Click OKto restart the computer and to complete removal of the authentication server software.


30/65


Online Client Installation 4

The DigitalPersona Online Client provides the user interface for fingerprint enrollment and matching, andsecure communications between the client, Online Authentication Server and the web server.

System Requirements



Following are the minimum hardware requirements:

Pentium processor

USB port for peripheral fingerprint reader, or built-in reader


Following are the minimum software requirements:

Microsoft Windows XP or later

Internet Explorer 8-11

InstallationInstallation of the DigitalPersona Online client provides your web application with the support files necessaryto display a basic functional UI for fingerprint enrollment, management and authentication. It does not provideyou with a complete client web application.

Your web application, developed using the Online API (see Chapter 7,ActiveX Control API Reference), will usethese files in conjunction with the code that you develop.

A sample web application/site demonstrating this UI is included in the installation of the DigitalPersona Onlinesample Application Server. In order to test that the installed sample site is working correctly, you will need toinstall the DigitalPersona Online client and connect a supported fingerprint reader to the client computer.When deploying your web application, end-users will need to have the DigitalPersona Online Client and a

supported fingerprint reader installed on their computers in order to enable biometric authentication.

Although the Online client can be installed on the same computer as the Authentication and/or ApplicationServer for testing purposes, we suggest that you install this on a separate computer in order to verifyfunctionality over your network.


31/65

Chapter 4:Online Client Installation Developer Sample Site


1. Install the DigitalPersona OnlineClient by running Setup.exe from the following location within theproduct package: DigitalPersona Online Client\.

2. When the installation wizard launches, click Next.

3. Next, read the License Agreement. If you agree to its terms, click I accept the terms of this agreementand then click Next.

4. On the next page, indicate the directory in which to install the client software and then click Next.

The installer copies the necessary client software files to the path you specified.

5. After the files are copied, click Finishto close the installer.

6. Reboot the PC when prompted.

7. Attach a supported fingerprint reader.

8. Open the Developer Sample Site in Internet Explorer by entering

http:///Application.Server.Site, or

http:///Application.Server.Site

9. Test the functionality of the sample site, or your own web application, including enrolling and deletingfingerprints and using your fingerprints for authentication as applicable.

Developer Sample Site

The features of the DigitalPersona Online client are demonstrated through a sample site included in theproduct package and installed as part of the Online sample Application Server installation.

In order to create a fully functioning sample site, you first need to have installed and configured the OnlineAuthentication Server, Online sample Application Server and the Online Client as described in the previouschapters.

For an overview of the features implemented in the Developer Sample Site, see Using a DigitalPersona Online-Secured Web Applicationonpage 13.


32/65


Online Application Server 5

The DigitalPersona Online Application Server that you will install is a sample server component that works withMicrosoft IIS (Internet Information Services) Application Server to host web applications that utilize fingerprint

authentication provided by DigitalPersona Online.

Note that this sample component is for educational purposes only, and shows how the DigitalPersona OnlineSDK may be used to create your application server and website. It is not intended for use in a productionenvironment.

This chapter covers the following topics relating to the sample DigitalPersona Online Application Server.

System Requirements

Installing the sample Online Application Server

Configuring IIS (Internet Information Server)

Uninstallation

System Requirements



Following are the minimum hardware requirements: Processor: 1 GHz (x86 processor) or 1.4 GHz (x64 processor)

Memory: 4 GB RAM

5GB available hard-disk space

Additional processors, memory and HD space may be required depending on application needs.


Following are the minimum software requirements:

Microsoft Windows Server 2008, 2008 R2 or 2012

Microsoft SQL Server 2005/2008

Microsoft Internet Information Server (IIS) 7/8



33/65

Chapter 5:Online Application Server Installing the sample Online Application Server


Installing the sample Online Application Server

1. Install the sample DigitalPersona Online Application Server - Run Setup.msi from the following locationwithin the product package: DigitalPersona Online Application SDK\.

2. Create the required database - In your SQL management tool, navigate to the following directory on yourcomputer: C:\Program Files\DigitalPersona\Online Server\SQLScripts. Execute the provided SQL script.

UareUExampleUsers.sql

3. Create the system DSN for the database - In Windows Explorer, navigate to C:\ProgramFiles\DigitalPersona\Online Server\SQLScripts and double click on UareUExampleUsers.regto create theDSN.

4. Configure IIS (refer to the section Configuring IIS (Internet Information Server)onpage 34.

5. Configure the sample Application Server- Navigate to C:\inetpub\wwwroot\Application.Server.Site, and editthe fileAppConfig.js, changing "localhost" in the AuthServer and AppServer parameters to the name ofthe computer where your database server is located. For external access, use the fully qualified computer

name.


34/65

Chapter 5:Online Application Server Configuring IIS (Internet Information Server)


Configuring IIS (Internet Information Server)

In IIS, you will need to enable Anonymous Authentication.

1. Enable Anonymous Authentication - In IIS Manager, select the website. In Features View, under the IIS

heading, open the Authenticationfeature.

2. Select Anonymous Authenticationin the list. Then click Enablein the Actions pane. Click Edit, and in theresulting dialog, select Application pool identity.


35/65

Chapter 5:Online Application Server Uninstallation


Uninstallation

This section provides instructions for removing the sample Online Application Server component.

To remove the sample Online Application Server software1. Open Control Panel, and then open Add/Remove Programs.

2. Click DigitalPersona Online Application Server, and then click the Change/Removebutton.

A dialog box prompts you to confirm that you want to remove the software.

3. Click Yesto proceed.

A dialog box prompts you to close all open applications before proceeding with the removal of thesoftware.

4. Click OK.

When the component is removed, you are prompted to restart the computer.

Click OKto restart the computer and to complete removal of the component.


36/65


Code Integration Guidelines 6

This chapter describes the registration, authentication and account modification processes at the API level andprovides guidelines for using ActiveX, HTML and JavaScript to integrate DigitalPersona Online functionality in

your Web application.

Initializing and Embedding the ActiveX Control

Every Web page that implements DigitalPersona Online functionality must initialize and embed the ActiveXcontrol. To use the control, acquire the following information:

URL of the authentication server

Note: The previous Online Client 4.4.1 allowed use of only a host name without its schema and path, andused a hardcoded path (/uareuonlineserver/request.asp) and additional Flags property to define the

schema (HTTP or HTTPS).The Online Client 5.5.0 supports the previous URL format, but also accepts a fully-defined URL withschema, host name and path. This adds flexibility to specifying the location of an Authentication Serverand simplifies configuration. It is preferable to use the fully defined URL over the previous URL form,although the new format is not supported by older clients.

Application ID, which is used by the authentication server to verify that your online application ispermitted to use the authentication service and is supplied by the authentication service provider.

The absolute URL of the online application component, appcontrol.asp, on the Web server.

Note: The previous Online Client 4.4.1 allowed use of only a host name and path without schema, andused an additional Flag property to define the schema (HTTP or HTTPS).

The Online Client 5.5.0 supports the previous URL format, but also accepts a fully-defined URL withschema, host name and path. This allows you to embed schema information in one place and simplifiesconfiguration. It is preferable to use the fully defined URL over the previous URL form, although the newformat is not supported by older clients.

Using this information, embed the code shown in the next two sections in every Web page that implementsDigitalPersona Online functionality.

ActiveX Control Initialization

To initialize the ActiveX control for the Microsoft Internet Explorer Web browser:


37/65

Chapter 6:Code Integration Guidelines Listening for events


Listening for events

Following is the JavaScript code that listens for the events generated by the ActiveX control:

function isIE { return (ActiveXObject in window); }.. isIE() && OnCredComplete(); isIE() ? OnRegistrationCancelled() : false;

isIE() ? OnRegistrationComplete(recid, pubkey) : false;

isIE() && OnAuthComplete(otp); isIE() && OnAuthServerReady(uname); isIE() && OnAuthFailed(); isIE() && OnNotRegistered();

isIE() && OnSysError(code,desc); isIE() && OnBadVersion(); isIE() && OnInvalidUser(); isIE() && OnInvalidPassword();

isIE() && OnEnterPassword(); isIE() && OnEnterUser();


38/65

Chapter 6:Code Integration Guidelines Adding and configuring AppControl.ASP


Adding and configuring AppControl.ASP

Every Web application that integrates DigitalPersona Online functionality must include an ASP page which willhandle HTTP requests from Online Client. URL to this page must be provided to the Online Clients using the

AppAddressparameter.

It is recommended to follow the pattern of AppControl.asp provided with Application Server sample. TheAppControl.asp page must handle HTTP POST requests with the following parameters:

When ?request=auth is received, the handler ASP must generate an encrypted one-time password (OTP) usingthe AppSvr.Nonce COM helper object. The helper accepts a users public key stored in database, applicationkey, and produces the OTP (plain and hex-encoded) and ephemeral encryption key (hex-encoded). The plainOTP must be stored in user database record and validated during the next logon. The hex-encoded OTP andencryption key must be returned with a record ID in response headers:

HTTP POST: ?request=auth&username=&password=HTPP POST: ?request=update&username=&password=

/* Find the user and retrieve associated Online record ID and public key.

db.GetUser(username, /*out*/ user);var recordId = Trim(user("RecordId").Value+"");var pubkey = user("PublicKey").Value || "";...var appControl = Server.CreateObject("AppSvr.Nonce");/* Note: Jscript doesnt support [out] parameters, so we pass nulls and retrieve data viaproperties. VBasic supports [out] parameters, so you may pass references directly into theGenerate function.*/app ontrol Generate( pubkey, //

$Config.AppKey, // your application key stored in configuration file/object null, // [out] hexNonce null, // [out] hexEncKey null // [out] otp);var otp = appControl.Nonce || "";var hexNonce = appControl.HexNonce || "";var hexEncKey = appControl.HexEncKey || "";

// store users one-time password in database for further logon verificationdb.SetOTPassword(username, otp);

// return hex-encoded OTP, record ID and encryption keyResponse.AddHeader("return1", hexNonce);Response.AddHeader("return2", recordId);Response.AddHeader("return3", hexEncKey);


39/65

Chapter 6:Code Integration Guidelines Integrating DigitalPersona Online in Web Applications


IMPORTANT

The application key is case-sensitive. Failing to use proper case will result in the inability of the Webapplication to connect to the authentication server.

Dont forget to delete the one-time password from database after it was successfully used. When ?request=update is received, the handler ASP should update a password.

This is not a one-time password but a regular one. It is less secure as it is passed within POST requestparameters as a clean text every time user logons with a regular password and opens a possibility forreplay attacks.

Integrating DigitalPersona Online in Web Applications

The following three sections show the HTML code used in the registration, authentication and accountmodification forms.

Registration

The function of the registration process is to acquire a fingerprint template from the user to be used as acredential for authentication and store it, along with other data used during authentication, on theauthentication server.

The following figure shows the events and methods called during the registration process.

TheRegister method is called when a user (or the application) starts the registration process. When called,

the Registration dialog box opens, allowing a user to register a fingerprint.

When the user successfully completes the registration process, the fingerprint templategenerated by theclient software from samples acquired by the readeris stored on the authentication server database.

RegistrationComplete() RegistrationCancelled()

User completes

fingerprint regis-

tration process

User closes

the registration

dialog box

Register()

Events

Methods

User

Interaction


40/65

Chapter 6:Code Integration Guidelines Registration


The authentication server generates a record ID and a public/private key pair. The private key and record ID arestored on the authentication server database. Then, the public key and record ID are sent through theRegistrationComplete event to the client.

Upon receiving the event, the client sends the public key and record IDplus the username supplied on theregistration Web pageto the provider site database where it is stored.

If the user closes the Registration dialog box at any time during the registration process, theRegistrationCancelled method is fired and registration is cancelled.

Implementing the Registration Process in Web Pages

Web applications that facilitate the registration process must provide a mechanism for starting the registrationprocess and allowing the user to supply other authentication credentials, such as user name and password,and, if desired, authentication policy settings.

Following is HTML code for a FORM on a Web page where users register fingerprints, their user name andpassword and specifies the desired authentication policy:

The HTML code creates a form that allows a user to supply their user name, password and the authenticationpolicy to use when authenticating to a DigitalPersona Online-enabled Web application. There are two buttons:the first for initiating the fingerprint registration process and the second for submitting the registration formdata, for example, both the registered fingerprints and the user name, password and authentication policysetting.

When the first button is clicked, the event handler that starts the fingerprint registration process is called, asdescribed in Fingerprint Registration Event Handleronpage 41.

When the FORM is submitted, an event handler is called to ensure the supplied credentials match the requiredauthentication policy setting. For example, if the authentication policy requires both a fingerprint and

Password or FingerprintFingerprint OnlyFingerprint and Password


41/65

Chapter 6:Code Integration Guidelines Registration


passwordbut only a fingerprint was registered the event handler should inform the user and stop the formfrom being submitted to the form processor application component. An example of such an event handler isdescribed in Registration Form Event Handleronpage 42.

If the supplied credentials are complete, the form forwards the request data to the Web application component(supplied by the action attribute in theFORM tag), which then should store the username, password, recordid,pubkey, and policy data in the DigitalPersona Online database.

NOTE: In the example code in the previous figure, the user is given the option to choose the authenticationpolicy; however, the authentication policy can be set explicitly in the Web component handling theregistration process request data.

The credentials in the form should be added to the table created in the DigitalPersona Online database.

Fingerprint Registration Event Handler

When a user initiates the registration process, the handler of theOnClick event is called and its associatedfunction ensures that the DigitalPersona Online Client software is loaded and runs theRegister method:

In the startEnrollment event handler code, you must write the error handling routine for instances where theDigitalPersona Online Client software is not installed.

If the registration process was successfully completed, the OnRegistrationCompletefunction is called:

The OnRegistrationCompletefunction stores in hidden fields the public key and record ID received by theevent for later reference by the application provider site script, for example, RegisterExisting.asp.

If the registration process was cancelled, the OnRegistrationCancelled() function is called, which resets therecord ID and public key values:

function startEnrollment(theForm) { var loaded = isIE() ? uareuonline.loaded : window["uareuonline"]; if (loaded) { uareuonline.Register(); } else { /* Online Client is not installed, handle the error */ }}

function OnRegistrationComplete(recid, pubkey){ if (recid != 0) { document.forms.updateform.pubkey.value = pubkey; document.forms.updateform.recordid.value = recid; }}


42/65

Chapter 6:Code Integration Guidelines Authentication


Registration Form Event Handler

If the user did not cancel registration and the registration process was completed successfully, then thecheckresults function is called when the user clicks the Submit button:

Thecheckresults function ensures that the username and password fields are not empty and that afingerprint was supplied if it is required by the authentication policy.

AuthenticationThe process of authentication involves matching the fingerprint template stored on the authentication server(which is acquired at registration) to a fingerprint template acquired by the client at the time of authentication.The events and methods are illustrated in the following figure and are followed by a description of their roles inthe authentication process.

function OnRegistrationCancelled() { document.forms.regform.pubkey.value = ""; document.forms.regform.recordid.value = "";}

function checkresults(inpform){if ((inpform.policy.selectedIndex == 1 || inpform.policy.selectedIndex == 2) &&inpform.startreg.checked == false) {

/* display an error; policy requires a fingerprint */}

if (inpform.username.value == "" || inpform.password.value == "") {/* display an error; user name or password missing */

}inpform.submit();window.status = "submit done";}


43/65



Before the user authenticates, theInitAuthentication method is called by either the user or Webapplication. This method checks the version of DigitalPersona Online running on the client with the version on

the authentication server to verify compatibility. If the versions are compatible, then theAuthServerReadyevent is fired and authentication proceeds; otherwise, theBadVersion event is fired.

When the user is prompted for (and supplies) a registered fingerprint, theCredentialsComplete event isfired and the fingerprint template and the username (and password, if applicable) are passed to theCompleteAuthentication method.

AuthServerReady()

CredentialsComplete()

User supplies

fingerprint

credential

InitAuthentication()

CompleteAuthentication()

AuthenticationFailed()

AuthenticationComplete()

InvalidPassword()*

InvalidUser()

EnterPassword()*

EnterUser()

NotRegistered()

BadVersion()

Events

Methods

User

Interaction

* set mpassword

set muser


44/65



If credentials or other information are missing or invalid, five events can be fired, depending on the nature ofthe error:

TheEnterUser event is fired if a username was not supplied. If this occurs, you can supply a method forthe user to supply their username and set theMuser property to that value to resume authentication.

TheEnterPassword event is fired if the password was not supplied and is required by theauthentication policy. In this case, you can supply a method for the user to supply their password and settheMpassword property to this value to resume authentication.

TheInvalidUser event is fired if the user is not registered with the application provider site. Theapplication can set theMuser property to empty to cancel authentication or set it to the name of anexisting account. The control then fires theCredentialsComplete event again to restartauthentication without acquiring a new fingerprint template.

TheInvalidPassword event is fired if the password, which is required by the authentication policy,was checked but found to be invalid. The application can set theMpassword property to empty tocancel authentication or set it to a valid password for the given user. The control then fires the

CredentialsComplete event again to restart authentication without acquiring a new fingerprinttemplate.

TheNotRegistered event is fired if the user has an account but has not registered a fingerprint. Theapplication can prompt the user to register a fingerprint by redirecting them to the registration page.

If the credentials supplied are not missing or invalid, this method retrieves the associated record ID fromapplication provider site and generates a one-time password which is then encrypted with two keys: one is theApplication Key (provided by the authentication server provider) and one that is a session key encrypted usingthe public key which was generated at registration, as described in Registrationonpage 39. The client forwardsthe record ID, one-time password and session keyplus the fingerprint templateto the authenticationserver.

The authentication server compares the stored fingerprint template with the one sent by the client. If thefingerprint templates do not match, theAuthenticationFailed event is fired.

If the fingerprint templates match, the authentication server decrypts the session key using the stored privatekey (acquired at registration, as described in Registrationonpage 39) and then decrypts the one-time passwordwith the decrypted session key in conjunction with the application key. The decrypted one-time password isthen sent to the client through theAuthenticationComplete event. The client then forwards the one-timepassword to the application provider site. The application provider site compares the one-time password itgenerated to the one it just received from the client. If they match, authentication is successful.

Implementing the Authentication Process in Web Pages

To enable DigitalPersona Online authentication in a Web application, a Web page must initiate theauthentication process by calling theInitAuthentication method after the Online Client component isloaded. This function is typically called when the page loads; however, it may be initiated by the user clicking abutton. For example:


45/65



Following is the HTML code for a form the Web page that implements authentication functionality:

When submitted, the form should forward the request data to the Web application component that processesauthentication, which then should compare the request data with credentials stored in the database created inthe DigitalPersona Online database. The comparison should not only be based on a credential match, but alsothe authentication policy applied to the user account.

The authentication processor Web component should check the DigitalPersona Online database for theexistence of the user, get the authentication policy and then query the database based on the policy for theauthentication credentials to use for a match.

function isIE { return (ActiveXObject in window); }

function OnLoad() { if (!isIE()) { /* This browser doesnt support ActiveX, handle the error */ return; } if (!uareuonline) { /* The Online Client is not loaded, handle the error*/ return; } uareuonline.InitAuthentication(); }


46/65



Fingerprint Authentication Event Handlers

When theInitAuthentication method is called and a session with the authentication server has beensuccessfully established, theAuthServerReady event is fired and the associated handler,OnAuthServerReady,runs:

TheOnAuthServerReady function displays the username of the last person to authenticate (with theuname property) and provides the developer an opportunity to indicate to the user that authentication isready, such as displaying a graphical animation, an alert or other indication.

Then, the DigitalPersona Online Client software version is checked to ensure that it matches the version of the

authentication server software. If they do not match, theBadVersion event is fired, which calls theOnBadVersion function, in which you must write code that displays the error message for this event:

Otherwise, when users submit a registered fingerprint, theCredentialsComplete event is fired, which ishandled by theOnCredComplete function:

ThehndCredComplete function calls theCompleteAuthentication method with the username andpassword.

If authentication fails because the acquired fingerprint template does not match a template on theauthentication server, theAuthFailed event runs theOnAuthFailed function, in which can inform theuser that authentication failed:

function OnAuthServerReady(uname){document.forms.logonform.username.value=uname;

}

function OnBadVersion(){/* display a message telling that the client is obsolete and that a new one needsto be downloaded */

}

function OnCredComplete(){ uareuonline.CompleteAuthentication( document.forms.logonform.username.value, document.forms.logonform.pwd.value);}

function OnAuthFailed(){/* display a message telling the client that a match was not found */}


47/65



If authentication is successful, theAuthComplete event is fired, which calls theOnAuthComplete handlerfunction to submit the form to the authentication processor component:

The decrypted one-time password sent to this function is stored in a hidden field and the handler calls thesubmit method of the form to pass the authentication credentials to the authentication processorcomponent.

While theCompleteAuthentication method executes, one of five events could be fired in the case ofmissing or invalid credentials and other information.

If the user name is empty, theEnterUser event is fired, which runs theOnEnterUser function:

This function prompts the user for their username and sets themuser property to this value so theauthentication process can resume.

If the password is not supplied, but the authentication policy requires it, theEnterPassword event is fired,which calls theOnEnterPassword function:

function OnAuthComplete(otp){ document.forms.logonform.otp.value = otp; // submit immediately // document.logonform.submit();

// or show a visual feedback to notify about successful match // and delay submit so the user can see the good fingerprint checkmark setStatus("good"); setTimeout("document.logonform.submit();", 1000);}

function OnEnterUser(){ var elname = prompt("Please enter your username:", "") || ""; document.forms.logonform.username.value = elname; uareuonline.muser = elname;}

function OnEnterPassword(){ var pwd = prompt("In addition, your password is required for logon. Password:",

"") || ""; document.forms.logonform.password.value = pwd; uareuonline.mpassword = pwd;}


48/65



TheOnEnterPassword function prompts the user for the password and sets thempassword property tothe supplied value and resumes authentication.

If the supplied username is invalid, theInvalidUser event is fired, which calls theOnInvalidUserfunction:

TheOnInvalidUser function prompts the user for a valid username and sets themuser property to thisvalue and resumes authentication.

If a password is required by the authentication policy and the supplied password is invalid, theInvalidPassword event is fired, which calls theOnInvalidPassword function:

TheOnInvalidPassword function prompts the user for a valid password and set thempassword

property to this value and resumes authentication.

If the user supplies a fingerprint and it is not registered, theNotRegistered event is fired, which calls theOnNotRegistered function:

function OnInvalidUser(){ var elname = prompt("INVALID USERNAME - Please enter your username:", "") || ""; document.forms.logonform.username.value = elname; uareuonline.muser = elname;}

function OnInvalidPassword(){ var pwd = prompt("Your password did not match, please try again. Password:", "")|| ""; document.forms.logonform.password.value = pwd; uareuonline.mpassword = pwd;}

function OnNotRegistered(){if (confirm( "This account is not registered for use with the U.are.U Online authenticationserver.\n\n" + "Click OK to proceed with registration.") ){

window.location = "[existing registration component]" }}


49/65

Chapter 6:Code Integration Guidelines Account Modification


TheOnNotRegistered function displays a dialog box, allowing the user to specify whether they want toregister a fingerprint or cancel authentication using the existing registration component, as described in

Account Modificationonpage 49.

Account ModificationAccount Modification allows an already registered user to replace an existing registered fingerprint with a newone. The following illustration shows the events and methods of the account modification process.

When a Web application calls theUpdate method, which passes the use name and password as parameters,the ActiveX control acquires the record ID from the application provider site and ensures the password is valid.

InvalidUser()

User supplies

fingerprint

credential

Update()

InvalidPassword()

EnterUser()

Re

Digital Person a Online Administrator Guide 20131009

Documents

Transcript of Digital Person a Online Administrator Guide 20131009