digitalpersona altus android auth sdk v2 - crossmatch · •pin the digitalpersona altus android...

DigitalPersona®

Altus Android AUTH SDK v2

Developer Guide

Copyright© 2014-2016 Crossmatch. All rights reserved. Specifications are subject to change without prior notice. The Crossmatch logo and Crossmatch® are trademarks or registered trademarks of Cross Match Technologies, Inc. in the United States and other countries. DigitalPersona® is a registered trademark of DigitalPersona, Inc., which is owned by the parent company of Cross Match Technologies, Inc. All other brand and product names are trademarks or registered trademarks of their respective owners.

Published: April 1, 2016 (v2.0)

Contents

INTRODUCTION 5

Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Target Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Chapter Overview .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Addit ional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Related Documentat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Onl ine Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Development System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Target system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

INSTALLATION 8

Preparing the Altus Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Instal l Al tus Web server components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Add Internet Information Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Add I IS role and features (Windows Server 2012) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Add I IS role and features (Windows Server 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Import or create an SSL Cert i f icate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Import SSL Cert i f icate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Create a sel f-s igned SSL Cert i f icate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Set https binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Export the SSL cert i f icate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Instal l the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Conf igure the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

AVAILABLE FEATURES 20

Encrypt ion & authent icat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Authent icat ion and the Credent ials page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Fingerprint authent icat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Live quest ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Username and PIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Mult i- factor authent icat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

USING THE SDK 26

Workf low .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26The Sample Appl icat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

API REFERENCE 28

DPCode enum .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28DPCredent ialType enum .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28DPResult c lass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Field code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Field errorMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Altus Android AUTH SDK - Developer Guide 3

DPAltusCl ient .OnCompletedListener interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Method onReadSecretUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Method onWriteSecretUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Method onDoesSecretExist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Method onDeleteSecretUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Method onAuthent icateUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

DPAltusCl ient c lass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Method setConf ig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Method setContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Method setOnCompletedListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Method al tusCl ientCal lback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Method authent icateUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Method readSecretUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Method writeSecretUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Method deleteSecretUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Method doesSecretExist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

CUSTOM AUTHENTICATION POLICIES 36

How an Authent icat ion Pol icy is Represented . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Extending an Authent icat ion Pol icy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Creat ing a New Authent icat ion Pol icy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

INDEX 39


IntroductionTHIS CHAPTER PROVIDES AN OVERVIEW OF THE FUNCTIONALITY AND FEATURES OF THE ALTUS ANDROID AUTH SDK.

The purpose of the DigitalPersona Altus Android AUTH SDK is to allow you to add authentication to your Android applications. The Altus Android AUTH SDK lets you authenticate DigitalPersona Altus users quickly and easily using an Altus Server and the authentication policy defined by the Altus administrator. The following authentication methods provided in Altus can be accessed through the SDK.

• Password

• Fingerprint

• Live questions

• PIN

The DigitalPersona Altus Android AUTH SDK provides authentication only -- user enrollment must be handled through an Altus client.

When you install DigitalPersona Altus Workstation or Kiosk, the DigitalPersona Altus Android AUTH SDK runtime is installed as well. As shown in the diagram below, your application runs on workstations that are also running one of the Altus clients.

The SDK can be used for the following:

• Authenticating users with the authentication policy used by DigitalPersona Altus Workstation/Kiosk and optionally reading a user secret.

• Retrieving and saving user secrets. Secrets are cryptographically protected and are released to an application only after successful authentication of the user. Secrets are stored in the Altus database and roam with the rest of the user data.

• Using custom authentication policies which extend the Altus administrator’s policies or create new policies.

The DigitalPersona Altus Android AUTH SDK observes all of the settings in Altus regarding its communications with the server, supported credentials, policies, etc. Your application can require additional credentials (i.e., you can create a custom authentication policy), but if secret release is required, your application must meet the requirements of the policy set by the Altus administrator.

Deployment

The Altus Android AUTH SDK is deployed as an Android Archive Library (aar). The library should be referenced in the build.gradle dependencies section of your application.

Target Audience

This guide is for developers who have a working knowledge of the C++ programming language. In addition, readers must have an understanding of the DigitalPersona Altus product and its authentication terminology and concepts.

Chapter Overview

Chapter 1, Introduction (this chapter), gives an overview of the SDK’s purpose, describes its audience, cites resources that may assist you in using the SDK, identifies the minimum system requirements needed to run it and lists the DigitalPersona products supported by the Altus Android AUTH SDK.

Chapter 2, Installation, contains instructions for installing the SDK on your development system.

Chapter 3, Available features, describes the features exposed through the API and the GUI that supports them.


Chapter 4, Using the SDK, describes typical workflow and describes the functions in the API and how to run the sample application.

Chapter 5, API Reference, contains descriptions of the Altus Android AUTH API.

Chapter 6, Custom Authentication Policies, describes how authentication policies are stored, how to extend an authentication policy and how to define a new authentication policy.

Addit ional Resources

You can refer to the resources in this section to assist you in using the Altus Android AUTH SDK.

Related Documentation

Online Resources

System Requirements

Development System

Minimum software and hardware requirements - Needed to develop applications with the Altus Android AUTH SDK.

• Development system running Windows 7 or higher

• To run the sample code and test applications: DigitalPersona Altus Workstation or Kiosk (see “Supported DigitalPersona products” below for a complete list of compatible clients)

To compile sample code: Eclipse Kepler IDE or higher, Android SDK Platform (API 21 or higher).

Supported DigitalPersona productsThe Altus Android AUTH SDK is compatible with the following DigitalPersona products:

• Altus and Altus AD Server 1.1 and higher.

• Altus and Altus AD Workstation 1.1 and higher.

• Altus and Altus AD Kiosk 1.1 and higher.

As of the publication date of this guide, DigitalPersona Pro 4.3 SDK is not supported and applications written for DigitalPersona Pro SDK 4.x cannot be used with the DigitalPersona Altus AUTH SDK. Check our website or contact tech support for up-to-date information on available upgrade paths and the compatibility patches/upgrades for other Altus clients.

Subject Document

Concepts and terminology for DigitalPersona Altus DigitalPersona Altus AD and Altus LDS Administrator Guides (available at http://www.crossmatch.com/support/reference-material/digitalpersona-altus-reference-material/)

Web Site name URL

DigitalPersona Developer Connection Forum for DigitalPersona Developers

http://devportal.digitalpersona.com/(Requires free registration.)

Latest updates for DigitalPersona software products http://www.crossmatch.com/support/downloads/


http://www.crossmatch.com/Support/Reference-Material/DigitalPersona-Altus-Reference-Material/

http://www.crossmatch.com/Support/Reference-Material/DigitalPersona-Altus-Reference-Material/

http://www.crossmatch.com/support/downloads/

http://devportal.digitalpersona.com/

Target system

Rooted Android device with Android 4.0.3 or higher operating system.


InstallationTHIS CHAPTER DESCRIBES THE INSTALLATION AND CONFIGURATION OF THE ALTUS ANDROID AUTH SDK.

Preparing the Altus Server

Since Altus is a client-server solution, use of the SDK requires installation of an Altus or Altus AD Server and client, plus additional steps on the server to prepare it for use with the SDK.

The necessary steps for installation and setup of the Altus AUTH SDK are summarized below.

• Install the Altus Web Server components (begins below), and

• Add or configure Internet Information Services (IIS) (page 8)

• Import or create an SSL Certificate (page 15)

• Set https binding (page 16)

• Export the SSL certificate (page 16)

• Install the SDK (page 17)

• Configure the SDK (page 17)

Instal l Al tus Web server components

To install the Altus Web server components1. Locate the Altus Web server components folder within the Altus SDK package.

2. Launch the Altus Web server components installer by clicking the Setup.exe file.

3. Follow the instructions provided in the installation wizard.

4. If Internet Information Services (IIS) was not previously installed, the wizard will install it. Note that it is best to allow the wizard to install IIS, since the wizard does some configuration of IIS (adding features) during the installation.

Add Internet Information Services

Use of the Altus AUTH SDK requires installation of the Internet Information Services role on the Windows Server, and configuration of specific IIS-related features in IIS Manager.

If you need to install IIS yourself, you should install it prior to installing the Altus Web server components, since Altus will subsequently ensure that the proper features have been configured.

However, when installing outside of the Altus Web server components installer, use the following instructions to ensure that the necessary features have been installed.

Installations on Windows Server 2008 and Windows Server 2012 are slightly different, so steps are shown below for both operating systems.

Ensure that you have administrative user rights on the computer on which you plan to install IIS. Note that by default, you do not have administrative user rights if you are logged on as a user other than as the built-in administrator, even if you were added to the local Administrators group on the computer.

Add IIS role and features (Windows Server 2012)

These instructions are for installing IIS on Windows Server 2012. For installation on Windows 2008 R2, see page12. If IIS has not been installed on the same machine as your Altus Server, follow the instructions below to do so.


1. Open the “Server Manager” and launch the Add Roles and Features Wizard by selecting “Add Roles and Features” from the “Manage” menu.

2. On the Select installation type page, choose “Role-based or feature-based installation” and click “Next.”


3. On the Select destination server page, choose “Select a server from the server pool”, choose the server that you want to add the IIS role to, and click “Next.”

4. On the Select Server Roles page, scroll down to and select, “Web Server (IIS).” When asked to add additional features required for IIS, click Add Features.

5. On the Select Features page, select at least the features shown in the next illustration. Specifically, note that both the 3.5 and 4.5 .NET Frameworks must be selected. Under .NET Frameworks 4.5, ensure that the sub-


feature “WCF Services\HTTP Activation” is selected. When asked to add features required for HTTP Activation, click Add Features. Then click Next.

6. On the Web Server Role (IIS) page, click Next.


7. On the Select role services page, in addition to the default settings, make sure that the settings shown in the following two images are selected. Then click Next. When asked to add features required for IIS MAnagement Console, click Add Features.

8. On the Confirm installation selections page, click Next.

9. When the installation is complete, click Close.

Add IIS role and features (Windows Server 2008)

These instructions are for installing IIS on Windows Server 2008 R2. For installation on Windows 2012, see page8.

If IIS has not been installed on the same machine as your Altus Server, follow the instructions below to do so.


1. Open the “Server Manager” and choose to add a Role by selecting “Roles” in the left panel and then “Add Roles” in the right panel.

2. On the Select Server Roles page, choose “Web Server (IIS).”

3. When asked to “Add features required for Web Server (IIS)”, click “Add Required Features”.

4. Back on the Select Server Roles page, click “Next”. A page displays containing an Introduction to IIS. Click “Next.”


5. On the Select Role Services page, in addition to the default items that are selected, be sure to select the services shown in the next two illustrations as well. Specifically, note that “ASP.NET”, “.NET Extensibility” and “Windows Authentication” (under the Security node), must be selected.

6. You may be prompted to add role services to support some of the additions. If so, click “Add Required Role Services.”


7. Back on the Select Roles Services page, click “Next”. Then, on the Confirm Installation Selections page, click “Install” to begin the installation process. Once the installation is complete you should see a page that looks like the following illustration.

8. Click “Close” to return to the Server Manager. The Web Server (IIS) role should now show up in the list of server roles.

Import or create an SSL Cert i f icate

You will need an SSL Certificate to bind to the HTTPS protocol. You may already have one on your machine, in which case you can skip to the next topic, “Set https binding” on page 16. Otherwise, you can import one, or create a self-signed certificate to use.

Import SSL Certif icate

If you have an SSL Certificate in the pfx format, you can import it to use with Altus.1. Open the Windows Control panel and select Administrative Tools.

2. Launch the Internet Information Services (IIS) Manager.

3. You may be asked if you want to get started with Microsoft Web Platform. Click No.


4. In the left Connections panel of IIS Manager, select the <computer name> Home. Then double-click Server Certificates.

5. In the right Actions panel, click Import. Navigate to the .pfx file, enter the password for the file and from the Select Certificate Store dropdown list, select Web Hosting.

6. Click OK.

Create a self-s igned SSL Certif icate

1. Open the Windows Control panel and select Administrative Tools.


3. In the left Connections panel of IIS Manager, select the <computer name> Home. Then double-click Server Certificates.

4. In the right Actions panel, click Create Self-Signed Certificate.

5. Specify a friendly name for the certificate.

6. (IIS 2012 only) From the Select Certificate Store dropdown list, select Web Hosting.

7. Click OK.

Set https binding

1. Open the Windows Control panel and select Administrative Tools.


3. In the left Connections panel of IIS Manager, select the Default Web Site.

4. In the right Actions panel, click Bindings.

5. In the Site Bindings dialog, click Add.

6. In the Add Site Bindings dialog,

7. Select https from the Type dropdown list.

8. Select your certificate from the SSL Certificate dropdown list.

9. Click OK.

Export the SSL cert i f icate

The SSL certificate bound to https for the website must be exported as a .cer file for the Android device. A common way to do this is through the MMC Certificates snap-in.

To add the Certificates snap-in to an MMC for a user account1. Click Start, type mmc in the Search programs and files box, and then press ENTER.

2. On the File menu, click Add/Remove Snap-in.

3. Under Available snap-ins, double-click Certificates, and then:

•If you are logged on as an administrator, click My user account, click Finish and then click OK.•If you are logged on as a user, the Certificates snap-in automatically opens.

4. To save this console, on the File menu, click Save.

To export the certificate to a .cer file1. In MMC, locate the certificate that you bound to https.

2. Right-click the certificate and from the shortcut menu, select All Tasks, then Export. The Certificate Export Wizard launches.


3. Click Next.

4. Choose the option to not export the private key. Then click Next.

5. Select the format to export to: DER encoded binary X.509 (.CER). Then click Next.

6. Enter a name for the file. Click Browse to name the file and select the location where the file will be created. If a location is not selected, the file will be created in the Documents folder.

Instal l the SDK

The steps described below will guide you through installing and configuring the Altus Android AUTH SDK on your Android device.

1. Make sure your target system meets the requirements described in the previous chapter. Note that the device must be rooted.

2. Download and install a file explorer (such as ES File Explorer).

3. Configure DNS

• Open Settings on the Android device.

• Select “Wi-Fi.”

• Long press your current network, then select “Modify network.”

• Tap the “Show advanced options” checkbox.

• Change the “IP settings” to “Static.”

• Add your DNS server IPs to the “DNS 1”, and “DNS 2” fields.

• Add the Gateway IP to the Gateway field.

• Tap the “Save” button, disconnect from the network, and reconnect for changes to take effect.4. Copy the following files from the product package to the root of the Android device.

•Android Auth SDK Sample.apk5. altus.config.properties has to point to your IIS on the AUTH SDK website.

6. Copy the .CER (SSL certificate) file exported in the previous topic to the root of the Android device.

7. Restart the device

Conf igure the SDK

To run the sample application included with the Altus Android AUTH SDK 1. Open the File Explorer and click on Android Auth SDK Sample.apk. Follow the instructions provided to install

the sample.


2. Open the sample, tap the Action icon, and select Settings.

3. Select the path to the settings file for the sample.

4. Tap Select path to settings file.

5. Locate and tap the entry for the Altus configuration file, usually altus.config.properties.

6. Back on the Settings screen, tap Select path to certificate file.


7. Locate and tap the entry for the Altus certificate file, usually AltusCert.cer.


Available featuresTHIS CHAPTER DESCRIBES THE FUNCTIONS AND FEATURES OF THE ALTUS ANDROID AUTH SDK AS ILLUSTRATED THROUGH THE PROVIDED SAMPLE PROGRAM.

The core of Android Altus SDK is an Activity which collects policy information, enumerates supported credentials, displays UI and interacts with Altus server.

The general layout of the UI supports both landscape and portrait mode:

The activity has the following sections.

• Caption with icon.

• List of supported credentials.

• Active credential page.

The following authentication methods provided in Altus can be accessed through the SDK.

• Password

• Fingerprint

• Live questions

• PIN

Encrypt ion & authent icat ion

The SDK provides a means to encrypt and decrypt Altus stored data (secrets), and the GUI used for authentication required to access and manage the data. These features are illustrated in the sample program as follows.

• Does secret exist

• Read secret

• Write secret


• Delete secret

• Authenticate

To test these functions

1. Enter your test domain name and user name.

2. (For most functions) enter the name of a secret (data to be tested).

3. Tap on one of the available buttons to test that function.

4. You will be asked to authenticate before performing any of the functions. A new screen displays, where you will type your username and password. But first you need to grant Superuser permission to the application. Tap Grant.

5. Once authenticated, the requested operation will be performed, and a message displayed indicating the result. Or an error message will be displayed.

6. Tapping the Authenticate button takes you to the credentials page, explained in the next section.


Authent icat ion and the Credent ials page

The Credentials page displays tiles for each available and authorized credential. In the sample program, you can display this page by tapping the Authenticate button on the main screen.

Password

The user can authenticate by entering their domain name, username and password.

1. Select the Fingerprint tile on the authentication screen.

2. Enter your domain name, user name and password.

3. Tap Authenticate.

Fingerprint authenticat ion

The user can also authenticate with their fingerprint or other credentials. They can use their fingerprint to authenticate at any time, regardless of which credential page is active. The fingerprint credential supports identification mode, when a user’s name isn't known, and verification mode, when the user name is known.

1. Select the Fingerprint tile on the authentication screen.

Identification mode


Verification mode2. Place your finger on the fingerprint reader.

3. The fingerprint icon on the page shows feedback about the state of the reader, for example, authenticated, unrecognized swipe, disconnected reader etc.

The SDK supports pluggable fingerprint reader functionality. This allows the developer to easily add support for fingerprint readers from various vendors. For example, to support U.are.U fingerprint readers, you should install the corresponding plugin, uareureader.apk.


Live quest ion

The Live Question credential consists of three questions that a user can answer to gain access to protected resources when other credentials are unavailable or forgotten.

1. The initial Live question page requires the user to type their username in order to fetch the question list from the Altus server.

2. Once the questions are retrieved, the user can answer them by typing in the provided text boxes.

3. Tap Authenticate. The main screen redisplays.


Username and PIN

The PIN credential can be used in combination with other credentials to provide additional security.

Mult i- factor authent icat ion

When more than one credential is required by the authentication policy in force, an authenticated credential is shown as completed in the credential list by the presence of a checkmark overlaid on the credential tile. Any additional requisite credential pages are presented in verification mode (i.e. the user can't change the user name on the credential page). When an completed credential is enough to authenticate the user then the activity is finished. If not then the authentication process continues.

Multi-factor authentication (Password AND Fingerprint AND PIN)


Using the SDKTHIS CHAPTER DESCRIBES THE STANDARD WORKFLOW FOR USING THE ALTUS ANDROID AUTH API AND LISTS THE FUNCTIONS PROVIDED.

For basic Altus terminology and concepts, see the DigitalPersona Altus Administrator Guides.

Workf low

1. Add the Altus Android AUTH SDK library (AndroidAltusSDKLib.aar) to your Android project.

2. Create and initialize the DPAltusClient object.3. Create DPAltusClient.OnCompletedListener callback and implement their methods

(onReadSecretUI, onWriteSecretUI etc).4. Handle authentication activity result in Activity.onActivityResult by calling

DPAltusClient::altusClientCallback.

5. Use the DPAltusClient object.

The Sample Appl icat ion

The sample application source code included in the SDK is shown below.

public class MainActivity extends Activity {

private static final String SECRET_NAME = "SECRET_NAME";private static final String AUTH_SERVICE_NAME = "https://digitalpesona.com/Web/

DPWebAuthService.svc";private static final String SECRET_SERVICE_NAME = "https://digitalpesona.com/

Secrets/DPWebSecretManager.svc";private static final String POLICY_SERVICE_NAME = "http://digitalpersona.com/

Policy/DPWebPolicyService.svc";private static final String KEYSTORE_PATH = "/sdcar/AltusServer.bks";

private static final char[] KEYSTORE_PWD = {'p', 'a', 's', 's', 'w', 'o', 'r', 'd'};

private DPAltusClient mAltusClient = new DPAltusClient();

@Override protected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);

mAltusClient.setConfig(generateSettings());mAltusClient.setContext(MainActivity.this);

mAltusClient.setOnCompletedListener(new DPAltusClient.OnCompletedListener() { @Override public void onReadSecretUI(final DPAltusClient.DPResult result, final DPUser user, final String secretName, final char[] secretData) {

//TODO: implement method}

@Override public void onWriteSecretUI(final DPAltusClient.DPResult result, final DPUser user, final String secretName) {


http://www.digitalpersona.com/support/reference-material/pro-reference-material/

//TODO: implement method } @Override public void onDoesSecretExist(final DPAltusClient.DPResult result, final DPUser user, final String secretName, final boolean doesSecretExist) {

//TODO: implement method } @Override public void onDeleteSecretUI(final DPAltusClient.DPResult result, final DPUser user, final String secretName) {

//TODO: implement method } @Override public void onAuthenticateUI(final DPAltusClient.DPResult result, final DPUser user) {

//TODO: implement method }

}

@Overrideprotected void onActivityResult(int requestCode, int resultCode, Intent data) {

mAltusClient.altusClientCallback(requestCode, resultCode, data);}

private IDPConfig generateSettings() {DPConfigBuilder builder = new DPConfigBuilder();builder.setAuthServiceUrl(AUTH_SERVICE_NAME);builder.setSecretServiceUrl(SECRET_SERVICE_NAME); builder.setPolicyServiceUrl(POLICY_SERVICE_NAME);

// Certificate builder.setKeystorePath(KEYSTORE_PATH);

builder.setKeystorePassword(KEYSTORE_PWD); return builder.build();

}

}


API ReferenceTHIS CHAPTER DESCRIBES THE API EXPOSED BY THE ALTUS ANDROID AUTH SDK.

DPCode enum

DPCode enumerates possible operation result codes.

• SUCCESS - the operation is successful.

• CANCEL - the operation is cancelled, for example, user backed out.

• ERROR - the operation is failed.

DPCredent ialType enum

DPCredentialType enumerates possible credential IDs.

• DP_AUTH_PASSWORD_ID - password

• DP_AUTH_FINGERPRINT_ID - fingerprint

• DP_AUTH_PIN_ID - PIN

• DP_AUTH_SMARTCARD_ID - smart card

• DP_AUTH_PROXIMITY_ID - proximity card

• DP_AUTH_CONTACTLESS_ID - contactless card

• DP_AUTH_LIVE_ID - live questions

• DP_AUTH_BLUETOOTH_ID - Bluetooth

DPResult c lass

DPResult represents the operation result.

Constructors

Prototype:

DPResult(

DPCode code,

DPUser errorMessage,

);

Description

Creates an object with a given operation code and error message.

Parameters:

code - operation code.

errorMessage - error message.

Returns: None.

Throws: None.


Field code

Prototype:

DPCode code;

Description: Operation code.

Field errorMessage

Prototype:

String errorMessage;

Description: Error message if operation is failed or cancelled.

DPAltusCl ient .OnCompletedListener interface

Interface definition for a callback to be invoked when an operation is completed.

Method onReadSecretUI

Prototype:

void onReadSecretUI(

DPResult result,

DPUser user,

String secretName,

char[]secretData);

Description

Method is called when an operation (DPAltusClient::readSecretUI) is completed.

Parameters:

result - the operation result.

user - Altus user that requested the operation.

secretName - secret name of the data requested.

secretData - secret data.

Returns: None.

Throws: None.

Method onWriteSecretUI

Prototype:

void onWriteSecretUI(

DPResult result,

DPUser user,

String secretName);

Description

Method is called when an operation (DPAltusClient::writeSecretUI) is completed.

Parameters:



user - Altus user which requested the operation.


Returns: None.

Throws: None.

Method onDoesSecretExist

Prototype:

void onDoesSecretExist(

DPResult result,

DPUser user,

String secretName,

boolean doesSecretExist);

Description

Method is called when an operation (DPAltusClient::doesSecretExist) is completed.

Parameters:


user - Altus user that requested the operation.


doesSecretExist - boolean value which specifies whether or not a corresponding secret exists.

Returns: None.

Throws: None.

Method onDeleteSecretUI

Prototype:

void onDeleteSecretUI(

DPResult result,

DPUser user,

String secretName);

DescriptionMethod is called when an operation (DPAltusClient::deleteSecretUI) is completed.

Parameters:


user - Altus user which requested the operation.

secretName - secret name which was removed.

Returns: None.

Throws: None.

Method onAuthenticateUI

Prototype:

void onAuthenticateUI(

DPResult result,


DPUser user);

Description

Method is called when an operation (DPAltusClient::authenticateUI) is completed.

Parameters:

result – the operation result.

user - Altus user that was authenticated.

Returns: None.

Throws: None.

DPAltusCl ient c lass

The core class of Android Altus SDK which defines the high‐level structure of the authentication activity.

Constructors

Prototype:

DPAltusClient();

Description: Create an empty object.

Parameters: None.

Returns: None.

Throws: None.

Prototype:

DPAltusClient(

Activity activity);

Description: Create an object with a given parent activity.

Parameters:

activity - parent activity.

Returns: None.

Throws: None.

Prototype:

DPAltusClient(

IDPConfig config);

Description: Create an object with given configuration settings.

Parameters:

config - configuration settings.

Returns: None.

Throws: None.

Prototype:

DPAltusClient(


Activity activity,

IDPConfig config);

Description: Create an object with a given parent activity and configuration settings.

Parameters:



Returns: None.

Throws: None.

Method setConfig

Prototype:

void setConfig(

IDPConfig config);

Description: Method sets Altus server settings.

Parameters:


Returns: None.

Throws: None.

Method setContext

Prototype:

void setContext(

Activity activity);

Description: Method sets parent activity.

Parameters:


Returns: None.

Throws: None.

Method setOnCompletedListener

Prototype:

void setOnCompletedListener(

OnCompletedListener onCompletedListener);

Description: Method registers a callback to be invoked when operation has completed.

Parameters:

onCompletedListener - the callback that will run.

Returns: None.

Throws: None.


Method altusClientCallback

Prototype:

void altusClientCallback(

int requestCode,

int resultCode,

Intent data);

Description: Method handles the result of authentication activity. This method must be invoked at the top of the parent activity onActivityResult method.

Parameters:

requestCode - the request code, which identifies who this result came from.

resultCode - the result code returned by the child activity.

data - the result data.

Returns: None.

Throws: None.

Method authenticateUI

Prototype:

void authenticateUI(

String authActivityTitle,

EnumSet<DPCredentialType> credentials,

DPUser user);

Description

Method shows authentication activity. When the activity is done OnCompletedListener. onAuthenticateUI method is called.

Parameters:

authActivityTitle – activity title.

credentials – set of credential IDs that are available for authentication. If parameter is null, then all supported credentials will be used.

user - Altus user that should be authenticated. If user is empty, authentication acitvity works in verification mode, otherwise in identification mode.

Returns: None.

Throws: IllegalArgumentException, IllegalStateException.

Method readSecretUI

Prototype:

void readSecretUI(



DPUser user,

String secretName);


Description: Method shows authentication activity and returns requested secret data upon successful authentication. When the activity is done OnCompletedListener. onReadSecretUI method is called.

Parameters:



user - Altus user whose secret should be read. If user is empty, authentication acitvity works in verification mode, otherwise in identification mode.

secretName - secret name stored on the Altus server.

Returns: None.


Method writeSecretUI

Prototype:

void writeSecretUI(



DPUser user,

String secretName,

char[] secretData);

Description: Method shows authentication activity and writes requested secret data upon successful authentication. When the activity is done OnCompletedListener. onWriteSecretUI method is called.

Parameters:



user - Altus user whose secret should be written. If user is empty, authentication acitvity works in verification mode, otherwise in identification mode.


secretData - secret data.

Returns: None.


Method deleteSecretUI

Prototype:

void deleteSecretUI(



DPUser user,

String secretName);

Description: Method shows authentication activity and deletes requested secret upon successful authentication. When the activity is done OnCompletedListener. onDeleteSecretUI method is called.


Parameters:



user - Altus user whose secret should be deleted. If user is empty, authentication acitvity works in verification mode, otherwise in identification mode.


Returns: None.


Method doesSecretExist

Prototype:

void doesSecretExist(

DPUser user,

String secretName);

Description: Method checks if a secret exists for specified user. When the operation is done OnCompletedListener. doesSecretExist method is called.

Parameters:

user - Altus user whose secret should be checked.


Returns: None.



Custom Authentication PoliciesTHIS CHAPTER DESCRIBES HOW TO WORK WITH AUTHENTICATION POLICIES.

This material is for advanced developers only. Technical support queries regarding custom authentication policies should be sent to [email protected] rather than the usual DigitalPersona technical support.

If you need Altus to authenticate users and return user secrets, then you will need to satisfy the authentication policy defined by the Altus administrator. You can also choose to define your own custom authentication policy but if you do, your custom policy may not be sufficient for secret release. Altus will not release secrets unless you satisfy the authentication policy defined by the Altus administrator.

The Altus administrator must define the authentication policy or policies. Some examples of authentication policies might be:

• Users can authenticate with either a fingerprint or a password but we don’t need both fingerprint AND password.

• Users can authenticate with password OR with a smartcard; if they use their smartcard, then they must also enter their PIN.

Consult the DigitalPersona Altus AD or Altus LDS Administrator Guide (available at http://www.crossmatch.com/support/reference-material/) for more information on policies.

Note that an authentication policy is defined for a user on a specified workstation. Users may have different policies, and a policy for one user may not work if you try to use it to retrieve a secret for another user.

How an Authent icat ion Pol icy is Represented

An authentication policy is represented by an array of credential masks.

To create a data representation of the Altus administrator’s authentication policy, we make a list of all credentials or credential combinations that are permitted. Then we create a credential mask for each valid credential or combination. Each mask has a bit set for every credential that is required in this combination. As long as the user supplies one valid combination of credentials (i.e., satisfies at least one credential mask) they will be authenticated.

Each credential mask is a 64-bit value with each bit representing one valid credential. The bits are defined as:

The simplest authentication policy consists of a single (binary) credential mask:

Table 6.1: Definition of bits in each credential mask

Hex Bit Mask Credential

0x01 Password

0x02 Fingerprint

0x04 Smart card

0x10 Face

0x20 Contactless card

0x80 PIN

0x100 Proximity card

0x200 Bluetooth


http://www.digitalpersona.com/Support/Reference-Material/DigitalPersona-Pro-Reference-Material-Guides/

http://www.digitalpersona.com/Support/Reference-Material/DigitalPersona-Pro-Reference-Material-Guides/

http://www.crossmatch.com/support/reference-material/

0000000000000000000000000000000000000000000000000000000000000001

which represents a policy that requires users to provide a password (the password bit is set).

As another example, if the authentication policy requires BOTH a password and fingerprint, the authentication policy would consist of this credential mask (password and fingerprint bits both set):

0000000000000000000000000000000000000000000000000000000000000011If the user can authenticate either with a password OR a fingerprint, the authentication policy would consist of an array containing the following two credential masks. The first credential mask has the bit set for password access and the second mask has the bit set for fingerprint access. As long as a user satisfies ONE of these credentials masks, the user will be authenticated.

00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000010

As another example, the policy below shows the two credential masks for the authentication policy that requires users to authenticate by providing both their fingerprint and their password OR by providing their smartcard.

00000000000000000000000000000000000000000000000000000000000000110000000000000000000000000000000000000000000000000000000000000100

A fairly typical default authentication policy is shown below. This policy allows the user to use ANY one of: password, fingerprint, or smart card.

000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000100

The order of credential masks within the Policy array is unimportant. The bits that correspond to each credential type are consistent for all credential masks (i.e., bit 0 always represents that a password is required).

Extending an Authent icat ion Pol icy

If you want to extend the Altus administrator’s authentication policy, you can read the current policy by calling DPProReadAuthPolicy. You can then modify the credentials masks or add new credentials masks to the authentication policy array. You can then pass your authentication policy to calls to DPProAuthenticate or DPProIdentAuthenticate and your authentication policy will be used instead of the policy defined by the Altus administrator.

As a best practice, we recommend that this feature only be used to make the Altus administrator’s authentication policy more strict. Altus will not release secrets if your policy is less stringent than the existing Altus authentication policy.For example, consider the case where the existing Altus authentication policy is to allow fingerprints or passwords. In that case, the authentication policy would consist of these two credential masks:

00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000010

If you require that users also use face recognition in addition to either a fingerprint or password, you would update the authentication policy’s credential masks to this:

00000000000000000000000000000000000000000000000000000000000100010000000000000000000000000000000000000000000000000000000000010010

In this case, Altus will release secrets because the policy is stricter than the original.

However if you update the authentication policy to allow a different kind of credential entirely (for example, by adding a new credential mask that allows smart cards), then Altus will not release secret data.

Creat ing a New Authent icat ion Pol icy

You can also create your own custom policy. To do this, simply create the appropriate credentials masks and pass your authentication policy to DPProAuthenticate or DPProIdentAuthenticate.


Pro will not release secrets if your policy is less strict than the existing authentication policy set by the Altus administrator.


Altus Android AUTH SDK - Developer Guide

Index

A

Activity 20additional resources 6

online resources 6related documentation 6

audience for this guide 5

C

chapters, overview of 5Custom Authentication Policies 36

D

DigitalPersona Developer Connection Forum, URL to 6documentation, related 6

E

Encryption 20

F

FIngerprint authentication 22

L

landscape mode 20Live question 24

M

Multifactor authentication 25

O

online resources 6overview

of chapters 5

P

PIN 25portrait mode 20

R

requirements, systemSee system requirements

resources, additionalSee additional resources

resources, onlineSee online resources

S

supported DigitalPersona products 6system requirements 6

T

target audience for this guide 5Target system requirements 7

U

updates for DigitalPersona software products, URL for downloading 6

URLDigitalPersona Developer Connection Forum 6Updates for DigitalPersona Software Products 6

V

verification mode 25

W

websiteDigitalPersona Developer Connection Forum 6Updates for DigitalPersona Software Products 6

39