DigitalPersona, Inc. Altus AUTH SDK. Version 1.1. Developer Guide

Transcription

1 DigitalPersona, Inc. Altus AUTH SDK Version 1.1 Developer Guide

2 DigitalPersona, Inc DigitalPersona, Inc. All Rights Reserved. All intellectual property rights in the DigitalPersona software, firmware, hardware and documentation included with or described 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 not expressly granted. U.are.U and DigitalPersona are trademarks of DigitalPersona, Inc. registered in the United States and other countries. Windows, Windows Server 2003/2008, Windows Vista and Windows 7 are registered trademarks of Microsoft Corporation. All other trademarks are the property of their respective owners. This DigitalPersona Altus AUTH SDK Developer Guide and the software it describes are furnished under license as set forth in the License Agreement. Except as permitted by such license, 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. The contents of this manual are furnished for informational use only and are subject to change without notice. Any mention of third-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-party products. DigitalPersona makes every effort to ensure the accuracy of its documentation and assumes no responsibility or liability for any errors or inaccuracies that may appear in it. Technical Support The DigitalPersona web site provides online technical support at You can also access our free support forum at any time at Feedback Although the information in this guide has been thoroughly reviewed and tested, we welcome your feedback on any errors, omissions, or suggestions for future improvements. Please contact us at Crossmatch 720 Bay Road, Suite 100 Redwood City, California USA (650) (650) Fax Document Publication Date: December 10, 2014

3 Table of Contents 1 Introduction Target Audience Chapter Overview Additional Resources Related Documentation Online Resources System Requirements Development system Target system Supported DigitalPersona Products Installation Preparing the Altus Server Install Altus Confirm Add Internet Information Services Import or create an SSL Certificate Set https binding Install Client Workstation Using the SDK Workflow Authentication Policies Functions The Sample Application Custom Authentication Policies How an Authentication Policy is Represented Extending an Authentication Policy Creating a New Authentication Policy DigitalPersona Altus AUTH SDK - Developer Guide iii

4 Table of Contents DigitalPersona Pro AUTH SDK - Developer Guide iv

5 Introduction 1 The DigitalPersona Pro Authentication SDK is a component of Altus Confirm, and one piece of the three-part Altus framework that delivers identity assurance through a strong multi-factor authentication client and server. The purpose of the DigitalPersona Pro Authentication SDK is to allow you to add authentication to your C++ applications. The Pro Authentication SDK lets you authenticate DigitalPersona Altus users quickly and easily using the authentication policy defined (outside of the SDK) by the Altus administrator and subsequently release their protected data (secrets). All of the authentication methods provided in the Altus solution (password, fingerprint recognition, smart cards, etc.) can be accessed through the SDK. The DigitalPersona Altus AUTH SDK provides authentication and identification only. User enrollment must be handled through an Altus client. When you install DigitalPersona Altus Workstation or Kiosk, the DigitalPersona Altus 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 and user interface used by DigitalPersona Altus Workstation/Kiosk and optionally reading a user secret. The DPAlAuthenticate function displays the multi-factor authentication dialog and matches the supplied credentials against the user's enrolled credentials. The customizable dialog box accepts the credentials DigitalPersona Altus AUTH SDK - Developer Guide 4

6 Chapter 1: Introduction Target Audience required by the authentication policy set by the Pro administrator. On successful authentication, DPAlAuthenticate can optionally return user secrets to the application. Identifying users by searching in the Altus database to find the user and authenticate them. The DPAlIdentAuthenticate function displays the multi-factor identification dialog and identifies the user based on the credentials supplied. The customizable dialog box allows the user to provide the credentials required by the current authentication policy. If the identification succeeds, DPAlIdentAuthenticate can optionally return the user name and secret to the application. 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. Implementing custom authentication policies which extend the Altus administrator s policies or create new policies. DigitalPersona Altus AUTH SDK observes all of the settings in Altus regarding its communications with the server, supported credentials, policies, etc. For advanced users, your application can require additional credentials (i.e., you can create a custom authentication policy), but if secret release is required, your application s must meet the requirements of the policy set by the Altus administrator. 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), describes the audience for which this guide is written; cites a number of resources that may assist you in using the Pro Authentication SDK; identifies the minimum system requirements needed to run the Pro Authentication SDK; and lists the DigitalPersona products supported by the Pro Authentication SDK. Chapter 2, Installation, contains instructions for installing the SDK on your development system. Chapter 3, Using the SDK, describes typical workflow and describes the functions in the API and how to run the sample application. Chapter 4, Custom Authentication Policies, describes how authentication policies are stored, how to extend an authentication policy and how to define a new authentication policy. DigitalPersona Altus AUTH SDK - Developer Guide 5

7 Chapter 1: Introduction Additional Resources Additional Resources You can refer to the resources in this section to assist you in using the Pro Authentication SDK. Related Documentation Subject Concepts and terminology for DigitalPersona Altus Document DigitalPersona Altus Administrator Guide and the DigitalPersona Altus AD Administrator Guide (available at reference-material/pro-reference-material/) Online Resources Web Site name DigitalPersona Developer Connection Forum for DigitalPersona Developers Latest updates for DigitalPersona software products URL (Requires free registration.) System Requirements Development system This section lists the minimum software and hardware requirements needed to develop applications with the Pro Authentication 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: Visual Studio 2008 or higher Target system Any Windows-based (Windows 7 or higher) workstation that has any Altus client installed. See Supported DigitalPersona Products below for a complete list of compatible clients. Note that if the logon and Password Manager applications are not needed, Altus can be installed on client workstations without applications. This installs the Pro Authentication SDK runtime only. DigitalPersona Altus AUTH SDK - Developer Guide 6

8 Chapter 1: Introduction Supported DigitalPersona Products Supported DigitalPersona Products The Pro Authentication 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. DigitalPersona Altus AUTH SDK - Developer Guide 7

9 Installation 2 The DigitalPersona Altus AUTH SDK is automatically installed as part of these Altus clients: Altus Workstation Altus Kiosk Altus AD Workstation Altus AD Kiosk This documentation, sample code (for C++ and.net), and any necessary includes are available in a separate Altus SDK package available from Crossmatch and your channel partner or reseller. 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 DigitalPersona Altus AUTH SDK are summarized below. Install Altus Confirm (begins below), and Add or configure Internet Information Services (IIS) (page 9) Import or create an SSL Certificate (page 17) Set https binding (page 17) Install Client Workstation (page 18) Install Altus Confirm To install Altus Confirm 1. Locate the Altus Confirm folder within the Altus SDK package. 2. Launch the Altus Confirm 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. DigitalPersona Altus AUTH SDK - Developer Guide

10 Chapter 2: Installation Add Internet Information Services 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 Altus Confirm, since Altus Confirm will ensure that the proper features have been configured. However, when installing outside of the Altus COnfirm 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 For installation on Windows 2008 R2, see page13. 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. DigitalPersona Altus AUTH SDK - Developer Guide

11 Chapter 2: Installation Add Internet Information Services 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. DigitalPersona Altus AUTH SDK - Developer Guide

12 Chapter 2: Installation Add Internet Information Services 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 subfeature 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. DigitalPersona Altus AUTH SDK - Developer Guide

13 Chapter 2: Installation Add Internet Information Services 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. DigitalPersona Altus AUTH SDK - Developer Guide

14 Chapter 2: Installation Add Internet Information Services 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 page9. 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. DigitalPersona Altus AUTH SDK - Developer Guide

15 Chapter 2: Installation Add Internet Information Services 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. DigitalPersona Altus AUTH SDK - Developer Guide

16 Chapter 2: Installation Add Internet Information Services 6. You may be prompted to add role services to support some of the additions. If so, click Add Required Role Services. DigitalPersona Altus AUTH SDK - Developer Guide

17 Chapter 2: Installation Add Internet Information 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. DigitalPersona Altus AUTH SDK - Developer Guide

18 Chapter 2: Installation Import or create an SSL Certificate Import or create an SSL Certificate 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 17. Import SSL Certificate 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-signed SSL Certificate 1. Open the Windows Control panel and select Administrative Tools. 2. Launch the Internet Information Services (IIS) Manager. 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. 2. Launch the Internet Information Services (IIS) Manager. 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. DigitalPersona Altus AUTH SDK - Developer Guide

19 Chapter 2: Installation Install Client Workstation 8. Select your certificate from the SSL Certificate dropdown list. 9. Click OK. Install Client Workstation To run the Altus sample code or to run and test your application, you should have Altus Workstation or Altus AD Workstation installed on your development machine. Additionally, if you are developing for an Altus Kiosk or Altus AD Kiosk environment, you should test your application with those clients. For a list of supported versions of Altus clients, refer to Supported DigitalPersona Products on page 7. Complete instructions on installing Altus clients is provided in the Altus Client Guide, which can be downloaded from our website at DigitalPersona Altus AUTH SDK - Developer Guide

20 Using the SDK 3 This chapter describes the standard workflow for using the Altus AUTH SDK API and lists the functions provided. The information in this chapter is extracted from DPAltusAuthSdkApi.h. For terminology and concepts, see the DigitalPersona Altus or Altus AD Administrator Guide. Workflow The normal process is: call DPAlInit to initialize... call functions in the SDK if an SDK function returned an array, string or BLOG, call DPAlFreeBuffer to release the memory... call DPAlTerm to release resources Note that if you are calling only one function in the SDK, then you don t need to call DPAlInit and DPAlTerm directly because the function will initialize and terminate for itself automatically. However when you are making multiple calls, it is faster and more efficient to initialize and terminate directly. The SDK provides: 1. Authentication: Verifying that a user is who they claim to be by checking that the provided credentials (password, fingerprint, etc.) match their username's credentials in the Altus database. The DPAlAuthenticate function displays the multi-factor authentication dialog and matches the supplied credentials against the user's enrolled credentials. The customizable dialog box accepts the credentials required by the authentication policy set by the Altus administrator. Optional: On successful authentication, DPAlAuthenticate can return user secrets and the type of credential(s) that the user provided for authentication. 2. Identification: Searching in Active Directory to find the user and authenticate them. For Kiosk environments only. The DPAlIdentAuthenticate function displays the multi-factor identification dialog and identifies the user based on the credentials supplied. The customizable dialog box allows the user to provide the credentials required by the current authentication policy. Optional: If the identification succeeds, DPAlIdentAuthenticate can return the user name, the type of credential(s) used to authenticate and user secrets. DigitalPersona Altus AUTH SDK - Developer Guide 19

21 Chapter 3: Using the SDK Authentication Policies Authentication Policies The simplest option provided by Altus AUTH SDK is to authenticate a user using the session authentication policy defined by the Altus administrator. In this case, you do not need to know how policies work and you may simply pass NULLs to the SDK for all parameters that take an authentication policy. For more information on authentication policies, see Chapter 4, Custom Authentication Policies, on page 24. Functions This section lists the Pro Authentication API functions. For a detailed description of each function s parameters, consult the header file DPAlAuthSdkApi.h. Function DPAlInit DPAlTerm DPAlAuthentication DPAlIdentAuthenticate DPAlReadAuthPolicy DPAlWriteSecret DPPTDoesSecretExist DPAlBufferFree DPAlFormatMessage Description Initialize the authentication functions. Calling this function is optional -- if you do not call it, the system will initialize itself. However if you are going to call multiple authentication functions, it is more efficient and provides better performance if you initialize and terminate explicitly. Terminate the authentication process, release resources. You must call DPAlTerm once for each time that you called DPAlInit. Display multi-factor authentication dialog and authenticate a user. Optionally return the type of credentials used to authenticate and/or a secret upon successful authentication. Note that this function performs a 1-to-1 comparison -- matching a user s credentials against their enrolled credentials in the Altus database. For Kiosk environments only. Display multi-factor identification dialog and identify a user. Optionally return the username, the type of credential(s) used to authenticate and/or user secret(s) upon successful identification. Note that this function performs a 1-to-many comparison -- searching Active Directory to find the user -- and then authenticates the user. Read an authentication policy. Save the requested secret (authenticated users only). Check to see if a secret exists. Release memory buffer allocated by the other functions in the SDK. Returns a message string corresponding to an error code generated by the API. The string is returned in the language of the current user. DigitalPersona Altus AUTH SDK - Developer Guide 20

22 Chapter 3: Using the SDK The Sample Application The Sample Application The sample application source code is provided in the folder UsingAltusSDK (including the Visual Studio 2008 project) from the Altus SDK package. There are two sets of sample code. One for C++ and one for.net. The sample application displays a set of buttons that demonstrate a variety of tasks that you might perform with the Altus AUTH SDK, such as Authentication, Identification, Working with Secrets and Custom Authentication Policies. When you run the sample application, the main screen looks like one of the images below. The source code header file, DPAltusAuthSdkApi.h, includes detailed comments describing what each button does. C++ Sample UI DigitalPersona Altus AUTH SDK - Developer Guide 21

23 Chapter 3: Using the SDK The Sample Application.NET Sample UI Note that to run the sample application you must have an Altus client installed. DigitalPersona Altus AUTH SDK - Developer Guide 22

24 Chapter 3: Using the SDK The Sample Application For example, to authenticate a user, click on the Authenticate the currently logged on user button. A standard Altus dialog box will appear, similar to the one shown below. The actual dialog box will vary depending on your environment and the Altus client that you have installed. You can authenticate with any method that you have set up. After you authenticate, the result of the operation will appear in the main screen of the sample program as shown below, in this case the message Authentication succeeded as shown below. DigitalPersona Altus AUTH SDK - Developer Guide 23

25 Custom Authentication Policies 4 This 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 ProSDKCAPsupport@digitalpersona.com 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 or Altus AD Administrator Guide (available at support/reference-material/pro-reference-material/) for more information on policies. NOTE: 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 Authentication Policy 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: DigitalPersona Altus AUTH SDK - Developer Guide 24

26 Chapter 4: Custom Authentication Policies How an Authentication Policy is Represented Table 1. Definition of bits in each credential mask Hex Bit Mask 0x01 0x02 0x04 0x10 0x20 0x80 0x100 0x200 Credential Password Fingerprint Smart card Face Contactless card PIN Proximity card Bluetooth The simplest authentication policy consists of a single (binary) credential mask: 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): If 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 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 A fairly typical default authentication policy is shown below. This policy allows the user to use ANY one of: password, fingerprint, or smart card DigitalPersona Altus AUTH SDK - Developer Guide 25

27 Chapter 4: Custom Authentication Policies Extending an Authentication Policy 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 Authentication Policy If you want to extend the Altus administrator s authentication policy, you can read the current policy by calling DPAlReadAuthPolicy. 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 DPAlAuthenticate or DPAlIdentAuthenticate 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: 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: 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. Creating a New Authentication Policy You can also create your own custom policy. To do this, simply create the appropriate credentials masks and pass your authentication policy to DPAlAuthenticate or DPAlIdentAuthenticate. Pro will not release secrets if your policy is less strict than the existing authentication policy set by the Altus administrator. DigitalPersona Altus AUTH SDK - Developer Guide 26

28 Index A additional resources 6 online resources 6 related documentation 6 audience for this guide 5 C chapters, overview of 5 D DigitalPersona Developer Connection Forum, URL to 6 documentation, related 6 O online resources 6 overview of chapters 5 R requirements, system See system requirements resources, additional See additional resources resources, online See online resources S system requirements 6 T target audience for this guide 5 U updates for DigitalPersona software products, URL for downloading 6 URL DigitalPersona Developer Connection Forum 6 Updates for DigitalPersona Software Products 6 W Web site DigitalPersona Developer Connection Forum 6 Updates for DigitalPersona Software Products 6 DigitalPersona Altus AUTH SDK- Developer Guide 1