IdentityGuard 8.1 Programming Guide for the.net Framework

Transcription

1 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0 Date of Issue: April 2007

2 2007 Entrust. All rights reserved. Entrust is a trademark or a registered trademark of Entrust, Inc. in certain countries. All Entrust product names and logos are trademarks or registered trademarks of Entrust, Inc. in certain countries. All other company and product names and logos are trademarks or registered trademarks of their respective owners in certain countries. This information is subject to change as Entrust reserves the right to, without notice, make changes to its products as progress in engineering or manufacturing methods or circumstances may warrant. Export and/or import of cryptographic products may be restricted by various regulations in various countries. Licenses may be required. 2 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework

3 Table of contents About this guide Documentation conventions Note and Attention text Related documentation Obtaining documentation Documentation feedback Obtaining technical assistance Technical support Professional Services CHAPTER 1 API overview and samples Entrust IdentityGuard APIs V1 and V2 services Authentication V2 API Administration V2 API V2 Web service definition files V2.NET class files Sample applications Sample command-line applications Running the sample authentication client Running the sample administration client Using the administration commands CHAPTER 2 Client application setup Setting up your application

4 Using SSL communication Configuring trust Configuring SSL with Entrust IdentityGuard replicas Create a binding object Create an authentication binding object Create an administration binding object Updating V1 services to V Update service URLs Update proxy class library Update proxy class namespace CHAPTER 3 Authentication approaches Anonymous grid authentication One-step API methods One-step API code sample String conversion sample Two-step grid authentication Generic authentication Generic API methods Grids Tokens Out-of-band authentication Knowledge-based questions External authentication Generic API code sample Machine authentication Machine authentication API methods Machine authentication API code example Sources of machine information Storing and retrieving machine information Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

5 Mutual authentication Grid serial number and location replay Token serial number replay Knowledge-based authentication Image and message replay Serial number replay sample Image and caption replay samples Image management Multifactor authentication CHAPTER 4 Administration tasks Administration setup and login Basic administration tasks Create and register a user Create and assign preproduced cards Create and send an OTP Assign and modify a token Create and modify a temporary PIN Set up a user s questions and answers Unlock users Administrative monitoring tasks Check for expiring cards Check card inventory Check token inventory Check for unused assigned cards or tokens CHAPTER 5 API exceptions SoapException returned by proxy classes ErrorCode class Authentication warning faults Administration Password Change Index

6 4 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

7 About this guide The Entrust IdentityGuard Programming Guide provides detailed information on how to use the C# version of the Entrust IdentityGuard Authentication and Administration APIs to integrate an existing secure application with Entrust IdentityGuard. This guide discusses the 8.1 version (known as V2) of these APIs. This chapter includes the following sections: Documentation conventions on page 6 Related documentation on page 7 Obtaining documentation on page 8 Obtaining technical assistance on page 9 5

8 Documentation conventions The following typographic conventions appear in this guide: Table 1: Typographic conventions Convention Purpose Example Bold text (other than headings) Italicized text Blue text Underlined blue text Courier type Angle brackets < > Square brackets [courier type] Indicates graphical user interface elements and wizards Used for book or document titles Used for hyperlinks to other sections in the document Used for Web links Indicates installation paths, file names, Windows registry keys, commands, and text you must enter Indicates variables (text you must replace with your organization s correct values) Indicates optional parameters Click Next. Entrust IdentityGuard Administration Guide For more information on initialization see, Initializing IdentityGuard. For more information, visit our Web site at init [-sernum <num>] [-overwrite] [-force] user delete <userid> [-import <file>] [-force] [-continue [true false]] [-errorfile <file>] init [-sernum <num>] [-overwrite] [-force] Note and Attention text Throughout this guide, there are paragraphs set off by ruled lines above and below the text. These paragraphs provide key information with two levels of importance, as shown below. Note: Information to help you maximize the benefits of your Entrust product. Attention: Issues that, if ignored, may seriously affect performance, security, or the operation of your Entrust product. 6 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

9 Related documentation Entrust IdentityGuard is supported by a complete documentation suite: For instructions on installing and configuring Entrust IdentityGuard Server, see the Entrust IdentityGuard Installation Guide. For instructions on administering Entrust IdentityGuard users and groups, see the Entrust IdentityGuard Administration Guide. For information on deploying Entrust IdentityGuard, refer to the Entrust IdentityGuard Deployment Guide. For information on configuring Entrust IdentityGuard to work with a supported LDAP repository Active Directory, Active Directory Application Mode, Critical Path InJoin Directory, IBM Tivoli Directory, Novell edirectory, or Sun ONE Directory see the Entrust IdentityGuard Directory Configuration Guide. For information on configuring Entrust IdentityGuard to work with a supported database IBM DB2 Universal Database, Microsoft SQL Server, or Oracle Database see the Entrust IdentityGuard Database Configuration Guide. For information on Entrust IdentityGuard error messages, see the Entrust IdentityGuard Error Messages. For information on new features, limitations, and known issues in the latest release, see the Entrust IdentityGuard Release Notes. For information on integrating the authentication and administration processes of your applications with Entrust IdentityGuard, see the Entrust IdentityGuard Programming Guide that applies to your development platform (either Java Platform or.net Framework). For Entrust IdentityGuard product information and a data sheet, go to For information on identity theft protection seminars, go to About this guide 7

10 Obtaining documentation Entrust product documentation, white papers, technical notes, and a comprehensive Knowledge Base are available through Entrust TrustedCare Online. If you are registered for our support programs, you can use our Web-based Entrust TrustedCare Online support services at: Documentation feedback You can rate and provide feedback about Entrust product documentation by completing the online feedback form. You can access this form by clicking the link located in the footer of Entrust s PDF documents (see bottom of this page following this link: You can also direct feedback concerning documentation to the Customer Support address. support@entrust.com 8 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

11 Obtaining technical assistance Entrust recognizes the importance of providing quick and easy access to our support resources. The following subsections provide details about the technical support and professional services available to you. Technical support Entrust offers a variety of technical support programs to help you keep Entrust products up and running. To learn more about the full range of Entrust technical support services, visit our Web site at: If you are registered for our support programs, you can use our Web-based support services. Entrust TrustedCare Online offers technical resources including Entrust product documentation, white papers and technical notes, and a comprehensive Knowledge Base at: If you contact Entrust Customer Support, please provide as much of the following information as possible: your contact information product name, version, and operating system information your deployment scenario description of the problem copy of log files containing error messages description of conditions under which the error occurred description of troubleshooting activities you have already performed Telephone numbers For support assistance by telephone call one of the following numbers: in North America outside North America address The address for Customer Support is: support@entrust.com About this guide 9

12 Professional Services The Entrust team assists e-businesses around the world to deploy and maintain secure transactions and communications with their partners, customers, suppliers, and employees. We offer a full range of professional services to deploy our e-business solutions successfully for wired and wireless networks, including planning and design, installation, system integration, deployment support, and custom software development. Whether you choose to operate your Entrust solution in-house or subscribe to hosted services, Entrust Professional Services will design and implement the right solution for your e-business needs. For more information about Entrust Professional Services please visit our Web site at: 10 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

13 Chapter 1 API overview and samples This chapter describes the various APIs available for use with a client application. It also includes details on the sample applications included with Entrust IdentityGuard. It contains the following topics: Entrust IdentityGuard APIs on page 12 Sample applications on page 16 11

14 Entrust IdentityGuard APIs Entrust IdentityGuard includes two Web services: Authentication service and Authentication API Administration service and Administration API Use the Authentication service to integrate Entrust IdentityGuard authentication methods, such as grid or token authentication, into your Web applications. Use the Administration service to add end-user services to your application. These services are features such as user self-registration, user requests for cards or tokens, a self-reporting mechanism for lost cards or tokens, and more. Entrust IdentityGuard 8.1 supports Microsoft.NET Framework 2.0 for authentication and administration services. Topics in this section: V1 and V2 services on page 12 Authentication V2 API on page 13 Administration V2 API on page 13 V2 Web service definition files on page 13 V2.NET class files on page 14 V2.NET API documentation on page 15 V1 and V2 services There are two versions of the Web services and APIs included with Entrust IdentityGuard: V1 and V2. The V1 version is exactly the same as the APIs in Entrust IdentityGuard 8.0. They do not include any 8.1 functionality. Your pre-8.1 applications can continue to access them from: You do not need to recompile pre-8.1 applications in order to use the V1 services. The V2 versions are new to Entrust IdentityGuard. They include the new features available in 8.1 and are modified to be WS-I compliant. You cannot use V2 versions with applications built using pre-8.1 APIs. Your 8.1 applications can access these services from: Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

15 The ports shown are the defaults for installations with embedded Tomcat server and will differ with installations on an existing WebSphere 6.0 and WebLogic 8.1 or 9.1 application server. <host> refers to the server where you installed Entrust IdentityGuard. You must update these interface names in the client code. For upgraded coding samples, see Updating V1 services to V2 on page 45. Note: This guide only discusses the V2 APIs. Authentication V2 API The Entrust IdentityGuard Authentication service is a set of Web service methods used for retrieving challenge requests and authenticating user responses. It is designed to integrate with your existing authentication applications to provide multifactor authentication. Administration V2 API The Entrust IdentityGuard Administration service is a servlet running on the Entrust IdentityGuard Server that manages administrators, users, cards, tokens, and temporary PINs. You can create a client application that uses the Administration service to automate Entrust IdentityGuard user administration tasks and incorporate these tasks into existing user management systems. V2 Web service definition files The Authentication API is defined in AuthenticationServiceV2.wsdl. The Administration API is defined in AdminServiceV2.wsdl. Common data types are found in ServiceV2Common.xsd. You can locate these files: On UNIX in <$IDENTITYGUARD_HOME>/identityguard81/client/doc where <$IDENTITYGUARD_HOME> is usually /opt/entrust/identityguard81 On Windows in <IG_INSTALL_DIR>\identityguard81\client\doc, where <IG_INSTALL_DIR> is usually C:\Program Files\Entrust\IdentityGuard. API overview and samples 13

16 You can also view a Web service definition file from a browser by doing the following: 1 Open the identityguard.properties file in a text editor. You can locate this file in the etc directory under identityguard81. 2 Add the following line to the configuration file: identityguard.service.wsdlquery.enable=true 3 Save the file. 4 Restart the server. 5 Enter one of the following URLs in a browser: dl V2.NET class files Entrust IdentityGuard 8.1 supports Microsoft.NET Framework 2.0. The Entrust IdentityGuard installation includes the following files used for.net development: IdentityGuardAuthServiceV2CSharpAPI.cs, which is the C# proxy class code in C# for Authentication V2 service. IdentityGuardAuthServiceV2CSharpAPI.dll, which is the.net class library for the proxy class of the Authentication V2 service. IdentityGuardAdminServiceV2CSharpAPI.cs, which is the C# proxy class code in C# for the Administration V2 service. IdentityGuardAdminServiceV2CSharpAPI.dll, which is the.net class library for the proxy class of the Administration V2 service. You can locate these: on UNIX, in $IDENTITYGUARD_HOME/client/C#/lib on Windows, in <IG_INSTALL_DIR>\identityguard81\client\C#\lib 14 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

17 V2.NET API documentation Your Entrust IdentityGuard installation also includes a set of XML files generated from the C# proxy class code, IdentityGuardAdminServiceV2CSharpAPI.xml and IdentityGuardAuthServiceV2CSharpAPI.xml, that explain the.net API toolkits. An XSL style sheet, IdentityGuardServiceCSharpAPI.xsl, is also included to help you read the XML documentation. You can locate these: on UNIX, in $IDENTITYGUARD_HOME/client/C#/doc/ on Windows, in <IG_INSTALL_DIR>\identityguard81\client\C#\doc You can also find the API documentation in the Authentication and Administration WSDL files. API overview and samples 15

18 Sample applications Entrust provides two command-line sample applications to help guide your Entrust IdentityGuard implementation. Topics in this section: Sample command-line applications on page 16 Running the sample authentication client on page 16 Running the sample administration client on page 29 Sample command-line applications Entrust IdentityGuard includes sample applications that you can use to test the APIs that perform challenge, authentication, and administration requests. The sample application code is written in C#, and supports Microsoft.NET Framework 2.0. For the Authentication service, the file IdentityGuardAuthCSharpClient.cs contains the C# source code for a sample command-line application. The compiled version is IdentityGuardAuthCSharpClient.exe. For instructions on running this sample, see Running the sample authentication client on page 16. For the Administration service, the file IdentityGuardAdminCSharpClient.cs contains the C# source code for a sample command-line application. The compiled version is IdentityGuardAdminCSharpClient.dll. For instructions on running this sample, see Running the sample administration client on page 29. Running the sample authentication client Complete the following procedure to run the sample Entrust IdentityGuard command-line C# authentication sample. It provides examples of how different authentication approaches work. Before running the samples, you may want to create sample users with grids, tokens, or other types of authentication methods. See the Entrust IdentityGuard Administration Guide, especially the explanations of the -genericauthtype and -machineauthtype userspec policy attributes, for information on setting the allowed and default authentication methods for users. You must install Microsoft.NET Framework Version 2.0 on the Windows machine running the C# samples. 16 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

19 Note: Run C# administration sample client on a Windows machine with Microsoft.NET Framework 2.0 installed. You cannot run the C# samples from UNIX or Linux. To run the C# authentication sample on Microsoft Windows 1 If your Entrust IdentityGuard Server is installed on UNIX or Linux, copy all.net files to a Microsoft Windows based machine. 2 Import the Entrust IdentityGuard SSL certificate to the Windows machine running the sample client application. Ensure that the Windows user running the application has proper permissions to access the certificate. 3 Open runauthv2csharpclient.bat in a text editor. 4 Change IdentityGuardAuthServiceV2Client to IdentityGuardAuthCSharpClient. 5 Change the authentication service URL to your Entrust IdentityGuard Authentication V2 Service URL. 6 Save runauthv2csharpclient.bat. 7 Run runauthv2csharpclient.bat from the command prompt. Using the authentication commands ================================================================== Entrust IdentityGuard Authentication Client C# Sample App ================================================================== Welcome to Entrust IdentityGuard Authentication Service sample application. This application gives the samples of the usage of the IdentityGuard authentication API, which is a set of web services used for retrieving challenge requests and authenticating user responses. The following authentication mechanisms can be implemented using the APIs: - one-step authentication: 1. getanonymouschallenge or getanonymouschallengeforgroup 2. authenticateanonymouschallenge API overview and samples 17

20 - two-step authentication 1. getchallenge 2. authenticate - two-step authentication with shared secrets 1. getchallenge 2. authenticatewithsharedsecrets - generic authentication 1. getgenericchallenge 2. authenticategenericchallenge - machine authentication 1. checkmachineregistration 2. registermachine To display all available commands, type 'help'. Connected to IdentityGuard authentication service URL: ionservicev2 For more information on the authentication mechanisms listed, see Authentication approaches starting on page 47. Enter Help on the command line to see the syntax for all commands. Table 2 provides syntax details. In the syntax: The asterisk (*) means you can include zero or more occurrences of an attribute. The plus sign (+) means you must include one but may include more than one occurrence of an attribute. Many commands require a user ID. A user ID consists of both the user unique identifier and the group the user belongs to, in the following format: <groupname>/<username>. If you do not include the group name, Entrust IdentityGuard finds the correct group if the user name is unique; otherwise it returns an error. See Documentation conventions on page 6 for an explanation of standard syntax conventions. 18 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

21 Table 2: Authentication sample command Command help debugoff debugon exit authenticate Description Returns a list of the commands and their syntax. Turns debug mode off. Turns debug mode on. Closes the sample application. Allows you to respond to the challenge obtained when you ran getchallenge and authenticate the user. Syntax: authenticate <userid> <res>+ Where: <userid> identifies the user. <res>+ is the challenge response, based on the grid or temporary PIN of the user. Ensure that you separate each cell value with a space. For example, enter: > authenticate IGuser1 H Y 7 A typical response is: authenticated with card 1 expiry date: never superseded date: never Authentication successful For example, enter: > authenticate iguser3 N7V3FK7K A typical response is: authenticated with PIN. Authentication successful API overview and samples 19

22 Table 2: Authentication sample command (continued) Command authenticateanonymouschalle nge Description Allows you to authenticate a particular user based on the challenge received when you run getanonymouschallenge or getanonymouschallengeforgroup. Note: This is valid only if the -disableanonymous attribute is set to false in the cardspec policy of the user s group. Syntax: authenticateanonymouschallenge <userid> <res>+ Where: <userid> identifies the user. <res>+ is the challenge response, based on the grid or temporary PIN of the user. Add a space between values. For example, enter: > authenticateanonymouschallenge IGuser1 3 D 3 A typical response is: Using last anonymous challenge: ChallengeSet = [A,1] [F,5] [I,5] Using given response: ChallengeResponse = 3,D,3 authenticated with card 1 expiry date: never superseded date: never Authentication successful 20 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

23 Table 2: Authentication sample command (continued) Command authenticategenericchallenge Description Allows you to respond to a challenge obtained when you ran getgenericchallenge, authenticate the user, and manage authentication secrets. Syntax: authenticategenericchallenge [-] <userid> <res>+ [-authtype GRID QA OTP TOKENRO EXTERNAL] [-auth [-get ([-] <name>)*] [-remove ([-] <name>)*] [-set [-merge] ([-] <name> <value>)*]] Where: <userid> identifies the user. <res>+ is the challenge response. If you are responding to a grid challenge, be sure to separate each cell value with a space. -authtype specifies the authentication challenge method you are responding to. -auth -get <name> provides a list of authentication secrets belonging to the user. -auth -remove <name> removes authentication secrets from the user s list. -auth -set <name> <value> replaces the existing list of authentication secrets with one or more new ones. -auth -set -merge <name> <value> adds new authentication secrets the user s list. This example uses a temporary PIN to respond to a grid challenge: > authenticategenericchallenge iguser1 CPKM22YE -authtype GRID A typical response is: No authentication secrets returned. Authentication successful API overview and samples 21

24 Table 2: Authentication sample command (continued) Command Description authenticatewithsharedsecrets Allows you to respond to a challenge obtained when you ran getchallenge and authenticate the user. Optionally, you can manage the user s shared secrets. Syntax: authenticatewithsharedsecrets <userid> <res>+ [-secret [-get ([-] <name>)*] [-remove ([-] <name>)*] [-set [-merge] ([-] <name> <value>)*]] Where: <userid> identifies the user. <res>+ is the challenge response, based on the grid or temporary PIN of the user. Be sure to separate each cell value with a space. <name> is the name of the shared secret. <value> is the value of the shared secret. To have Entrust IdentityGuard return a specific shared secret, enter: authenticatewithsharedsecrets <userid> <res>+ -secret -get <name> To have Entrust IdentityGuard delete a specific shared secret, enter: authenticatewithsharedsecrets <userid> <res>+ -secret -remove <name> To have Entrust IdentityGuard create a shared secret, enter: authenticatewithsharedsecrets <userid> <res>+ -secret -create <name> <value> 22 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

25 Table 2: Authentication sample command (continued) Command checkmachineregistration Description Checks a user s machine for the identifying nonce or nonces. If none are found, it provides a second-factor challenge. Syntax: checkmachineregistration [-] <userid> [-authtype GRID QA OTP TOKENRO EXTERNAL] [-authtypelist (GRID QA OTP TOKENRO EXTERNAL)*] [-machine <nonce>] [-sequence <nonce>] [-appdata ([-] <name> <value>)+] [-auth ([-] <name>)*] Where: <userid> identifies the user. -authtype specifies the alternative authentication challenge method to use if the machine authentication is not available (for example, the user is using a different machine). -authtypelist sets a list of desired authentication challenge alternatives. A challenge is generated for the first one in the allowed auth type list that is defined by the policy used by the user group. -machine supplies the machine secret. When not provided, Entrust IdentityGuard creates one. -sequence is the optional sequence nonce. When not provided, Entrust IdentityGuard creates one if the attribute -machinesecretreqsequence is set to true in the userspec policy for the user s group. -appdata lists the application data to add to the machine nonce. -auth lists the names of the authentication secrets you wish to return with the challenge. If a secret name is more than one word, use quotation marks. The -authtype and -authtypelist options are mutually exclusive. One should be used. If -authtype is set, -authtypelist is overwritten. API overview and samples 23

26 Table 2: Authentication sample command (continued) Command getallowedauthenticationtype s Description Returns the authentication types available to a user. Syntax: getallowedauthenticationtypes <userid> Where <userid> identifies the user. For example, enter: > getallowedauthenticationtypes IGuser1 A typical response is: Running getallowedauthenticationtypes using userid 'IGuser1'... Generic Authentication: GRID (default) QA OTP TOKENRO Machine Registration: GRID (default) QA OTP TOKENRO Auth Types Can View Secrets: GRID QA OTP TOKENRO Auth Types Can Modify Secrets: GRID QA OTP TOKENRO The default generic and machine authentication method is set on the -genericauthtype and -machineauthtype userspec policy attributes of the user s group. 24 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

27 Table 2: Authentication sample command (continued) Command getallowedauthenticationtype sforgroup Description Returns the authentication types available for a group. Syntax: getallowedauthenticationtypesforgroup [<group>] Where <group> is the name of the group. If you do not specify a group name, the group flagged as the default is used. For example, enter: > getallowedauthenticationtypesforgroup IGgroup1 A typical response is: Running getallowedauthenticationtypesforgroup using group 'IGgroup1'... Generic Authentication: GRID (default) QA OTP TOKENRO Machine Registration: GRID (default) QA OTP TOKENRO Auth Types Can View Secrets: GRID QA OTP TOKENRO Auth Types Can Modify Secrets: GRID QA OTP TOKENRO The default generic and machine authentication method is set on the -genericauthtype and -machineauthtype userspec policy attributes of the user s group. API overview and samples 25

28 Table 2: Authentication sample command (continued) Command getanonymouschallenge getchallenge Description Allows you to create an anonymous (one-step) challenge. It applies to grid or temporary PIN authentication only. Note: This is valid only if the -disableanonymous attribute is set to false in the cardspec policy of the user s group. For example, enter: > getanonymouschallenge A typical response is: Running getanonymouschallenge'... ChallengeSet = [A,1] [F,5] [I,5] You can now run authenticateanonymouschallenge to answer the challenge for a particular user. Allows you to create a grid challenge for a particular user. Syntax: getchallenge <userid> Where <userid> identifies the user. For example, enter: > getchallenge IGuser1 A typical response is: Running getchallenge using userid 'IGuser1'... ChallengeSet = [D,3] [E,2] [J,1] Once you have run this command, you can run authenticate or authenticatewithsharedsecrets to answer the challenge for the user. 26 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

29 Table 2: Authentication sample command (continued) Command getgenericchallenge Description Allows you to create a challenge for any of the Entrust IdentityGuard authentication types. Syntax: getgenericchallenge [-] <userid> [-authtype GRID QA OTP TOKENRO EXTERNAL] [-authtypelist (GRID QA OTP TOKENRO EXTERNAL)*] [-auth ([-] <name>)*] Where: <userid> identifies the user. -authtype specifies the authentication challenge method to create. The method must correspond to what the user has; for example, do not use TOKENRO if the user has no tokens. If you specify OTP as the -authtype, then Entrust IdentityGuard server generates a one-time password for the user. -authtypelist sets a list of desired authentication challenge alternatives. A challenge is generated for the first one in the allowed auth type list that is defined by the policy used by the user group. -auth lists the names of the authentication secrets you wish to return with the challenge. Use quotes for names longer than one word. No secret is returned unless the -returnauthsecretwithchallenge attribute is true in the userspec policy for the user s group. The -authtype and -authtypelist options are mutually exclusive. One should be used. If -authtype is set, -authtypelist is overwritten. For example, enter: > getgenericchallenge iguser2 -authtype TOKENRO API overview and samples 27

30 Table 2: Authentication sample command (continued) Command getgenericchallenge (continued) registermachine Description A typical response is: Running getgenericchallenge using userid 'iguser2'... Token Challenge. Token: Has PIN: true PIN Change Supported: true PIN Change Required: true Min. Token PIN Length: 4 Once you run this command, run authenticategenericchallenge to respond. Allows you to register a user s computer so that second-factor authentication is transparent after the initial challenge response is successful. Syntax: registermachine [-] <userid> <response>+ [-authtype GRID QA OTP TOKENRO EXTERNAL] [-machine <nonce>] [-sequence <nonce>] [-appdata ([-] <name> <value>)+] [-storesecret [true false]][-auth [-get ([-] <name>)*] [-remove ([-] <name>)*] [-set [-merge] ([-] <name> <value>)*]] Where: <userid> identifies the user. <response>+ is the challenge response. If you are responding to a grid challenge, ensure that you separate each cell value with a space. -authtype specifies the authentication challenge method to use for the initial second-factor challenge. -machine supplies the machine secret. When not provided, Entrust IdentityGuard creates one. -sequence is the optional sequence nonce. When not provided, Entrust IdentityGuard creates one if the -machinesecretreqsequence attribute is set to true in the userspec policy for the user s group. 28 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

31 Table 2: Authentication sample command (continued) Command Description registermachine (continued) -appdata lists the application data to add to the machine nonce. -storesecret, when set to true (the default), specifies that Entrust IdentityGuard will store the machine secret. -auth -get <name> provides a list of authentication secrets belonging to the user. -auth -remove <name> removes authentications secrets from the user s list. -auth -set <name> <value> replaces the existing list of authentication secrets with one or more new ones. -auth -set -merge <name> <value> adds new authentication secrets the user s list. Running the sample administration client Complete the following procedure to run the sample Entrust IdentityGuard command-line administration client. This client lets you test how different administration commands work. Note: Run C# administration sample client on a Windows machine with Microsoft.NET Framework 2.0 installed. You cannot run the.net samples from UNIX or Linux. To run the C# administration sample client application 1 Ensure that the Entrust IdentityGuard Server is running. 2 Ensure that Microsoft.NET Framework 2.0 is installed on the machine to run the sample application. 3 Import the Entrust IdentityGuard SSL certificate to the Windows machine running the sample client application. Ensure that the Windows user running the application has proper permissions to access the certificate. 4 If you are running the sample client from a Windows computer that is different from the machine on which Entrust IdentityGuard installed, do the following: a Copy all files from <IG_INSTALL_DIR>\identityguard81\client\C#\sample\admin. API overview and samples 29

32 b Open the runadminv2csharpclient.bat file in a text editor. The runadminv2csharpclient.bat file contains the commands and parameter to run the administration sample client application. c Update the URL to ensure that it points to your Entrust IdentityGuard administration service. d Save and close the file. 5 Run runadminv2csharpclient.bat from the command prompt. ============================================================ Entrust IdentityGuard AdminService Client C# Sample App ================================================================== Welcome to Entrust IdentityGuard Administration Service sample client application. This application gives the sample usage of the Entrust IdentityGuard admin service API, which is a set of web services that allow an administrator to perform administration tasks to users, PINs, cards and tokens. To perform the administration tasks, you must first login with a valid admin id and password. To display all available commands, type 'help'. Connected to Entrust IdentityGuard admin service URL: es/adminservicev2 Using the administration commands To perform the administration tasks, you must first login with an administration id. The login command is: login <admin id> <admin password> > login sampleadmin0 adminpswd Login to Admin Service: sampleadmin0 Administrator sampleadmin0 has been successfully logged in to Admin Service. 30 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

33 Using the administration commands Table 3 lists the principal commands available in the administration command-line sample. The table does not provide detailed explanations of every command option. In most cases, the options are identical to the attributes of similarly-named master user shell commands. For example, the administration sample command usercreate does the same thing as the master user shell command user create, though the latter has a few more attributes. Sample command options are explained when they differ from master user shell attributes. See the following chapters in the Entrust IdentityGuard Administration Guide for applicable master user shell information: for group-related commands, see Configuring groups for user-management commands, see Administering users for one-time password commands, see Configuring authentication methods for card-related commands, see Configuring Entrust IdentityGuard cards for temporary PIN commands, see Configuring temporary PINs for token-related commands, see Configuring tokens Note: Not all attributes available on master user shell commands are also available as options on administration sample commands. In the syntax: The asterisk (*) means you can include zero or more occurrences of an attribute. The plus sign (+) means you must include one, but may include more than one occurrence of an attribute. Many commands require a user ID. A user ID consists of both the user unique identifier and the group the user belongs to, in the following format: <groupname>/<username>. If you do not include the group name, Entrust IdentityGuard finds the correct group if the user name is unique; otherwise it returns an error. See Documentation conventions on page 6 for an explanation of standard syntax conventions. API overview and samples 31

34 In the following table, all commands listed are identical to those in the Administration API unless otherwise noted. Table 3: Administration sample commands Command cardcreate carddelete cardexport cardget cardlist cardset challengeauthenticate Explanation Creates one or more preproduced cards. Syntax: preproducedcardcreate [-numcards <num>] [-group <group>] [-comment <text>] Deletes an unassigned card. Syntax: preproducedcarddelete <sernum> Exports unassigned preproduced card information to a file. Syntax: preproducedcardexport [-group ([-] <group>)+] [-create [-from <date>] [-to <date>]] [-sernum <sernum>] [-max <num>] Displays information about an unassigned card. Syntax: preproducedcardget <sernum> Lists one or more unassigned cards and related information. Syntax: preproducedcardlist [-group ([-] <group>)+] [-create [-from <date>] [-to <date>]] [-sernum <sernum>] [-max <num>] Changes details of an unassigned card. Syntax: preproducedcardset <sernum> [-group <group>] [-comment <text>] Authenticates a challenge response provided when an administrator authenticates a user s card. Syntax: challengeauthenticate <userid> <response> 32 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

35 Table 3: Administration sample commands (continued) Command challengeget groupget grouplist tokendelete tokenget tokenlist tokenset usercardcreate Explanation Gets a challenge for an administrator to use to authenticate a user s card. Syntax: challengeget <userid> Displays information about a particular group. Syntax: groupget <groupname> Displays a list of existing groups and related information. Syntax: group list [-policy <policyname>+] Deletes an unassigned token. Syntax: tokendelete <sernum> Displays information about a particular token. Syntax: tokenget <sernum> Displays a list of unassigned tokens and related information. Syntax: tokenlist [-load [-from <date>] [-to <date>]] [-sernum <sernum>] [-group ([-] <group>)+] [-max <num>] Changes details of an unassigned token. Syntax: tokenset <sernum> [-group <group>] [-comment <text>] Creates a card for a user. A card number is assigned automatically if not specified. Syntax: usercardcreate <userid> [-assign <serialnumber>] [-state pending hold_pending current hold] [-lifetime <num>] [-supersede <num>] [-comment <text>] API overview and samples 33

36 Table 3: Administration sample commands (continued) Command usercarddelete usercardexport usercardget usercardlist Explanation Deletes a card assigned to a user. Syntax: usercarddelete <userid> [<sernum> -all (pending hold_pending current hold canceled)+] Exports assigned card information to a file. Syntax: usercardexport [-create [-from <date>] [-to <date>]] [-expire [-from <date>] [-to <date>]] [-state (pending hold_pending hold current canceled)+] [-haspin] [-locked] [-userid <userid>] [-alias <alias>] [-id <id>] [-sernum <sernum>] [-group ([-] <group>)+] [-challengecount [-min <count>] [-max <count>]] [-leastusedcellusagecount [-min <count>] [-max <count>]] [-usagethreshold (none warning replacement)+] [-max <num>] Displays information about a user s assigned card. Syntax: usercardget <userid> [<sernum> -all (pending hold_pending current hold canceled)+] Displays a list of assigned cards and related information. Syntax: usercardlist [-create [-from <date>] [-to <date>]] [-expire [-from <date>] [-to <date>]] [-state (pending hold_pending hold current canceled)+] [-haspin] [-locked] [-userid <userid>] [-alias <alias>] [-id <id>] [-sernum <sernum>] [-group ([-] <group>)+] [-challengecount [-min <count>] [-max <count>]] [-leastusedcellusagecount [-min <count>] [-max <count>]] [-next <nextuser>] [-usagethreshold (none warning replacement)+] [-max <num>] Where: -next is used to get the next user value set by a previous list usercardlist command. <nextuser> provides the number of users returned previously. 34 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

37 Table 3: Administration sample commands (continued) Command usercardset usercardunassign usercreate userdelete userget userlist Explanation Changes details of a user s assigned card. Syntax: usercardset <userid> [<sernum> -all (pending hold_pending current hold canceled)+] [-state pending hold_pending hold current canceled] [-lifetime <num>] [-supersede <num>] [-challengecount <num>] [-leastusedcellusagecount <num>] [-comment <text>] Unassigns a card previously assigned to a user. Syntax: usercardunassign <userid> (<sernum> -all (pending hold_pending current hold canceled)+) [-comment <text>] Only applies to preproduced cards. Creates a new user entry. Syntax: usercreate <userid> [-group <group>] [-alias ([-] <alias>)+] [-qa ([-] <question> <answer>)+] [-auth ([-] <name> <value>)+] Deletes an existing user entry. Syntax: userdelete <userid> Displays information about a particular user. Syntax: userget <userid> Displays a list of users and related information. Syntax: userlist [-next <nextuser>] [-max <count>] [-userid <userid>] [-alias <alias>] [-lock] [-group ([-] <group>)+] [-haspin] Where: -next is used to get the next user value set by a previous userlist command. <nextuser> provides the number of users returned previously. API overview and samples 35

38 Table 3: Administration sample commands (continued) Command userset userotpcreate userotpdelete userotpget userpincreate userpindelete userpinget userpinset Explanation Changes details about a user. Syntax: userset <userid> [-userid <olduserid>] [-group <group>] [-secret <name> <value>] [-qa ([-merge] ([-] <question> <answer>)*) (-remove ([-] <question>)+)] [alias [-add -remove] ([-] alias)*] [-clearlockout] [clearmachinesecrets] Creates a new one-time password for a user. Syntax: userotpcreate <userid> [-lifetime <num>] [-force] Deletes an existing one-time password. Syntax: userotpdelete <userid> Displays information about a user s one-time password. Syntax: userotpget <userid> Creates a new temporary PIN for a user. Syntax: userpincreate <userid> [-lifetime [-days -hours] <num>] [-maxuses <num>] [-comment <text>] [-force] Deletes an existing temporary PIN. Syntax: userpindelete <userid> Displays information about a user s temporary PIN. Syntax: userpinget <userid> Changes details of a user s temporary PIN. Syntax: userpinset <userid> [-lifetime [-days -hours] <num>] [-maxuses <num>] [-comment <text>] [-force] 36 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

39 Table 3: Administration sample commands (continued) Command usertokenassign usertokenauthenticate usertokendelete usertokenget usertokenlist Explanation Assigns a token to a user. Syntax: usertokenassign <userid> <sernum> [-state pending hold_pending current hold] [-tokenpin <value> [-update [true false]] [-comment <text>] Allows verification of a token. Syntax: usertokenauthenticate <userid> <res> [-state pending hold_pending current hold] Where <res> is the challenge response, based on the token or temporary PIN of the user. If the token is set to require a new token PIN when first used, you must include a new token PIN in the response and confirm it. The format is (<oldpin><token response><new pin><new pin>). Deletes a user s token. Syntax: usertokendelete <userid> [-state pending hold_pending current hold] Displays information about an assigned token. Syntax: usertokenget <userid> [-state pending hold_pending current hold] Displays a list of assigned tokens and related information. Syntax: usertokenlist [-tokenload [-from <date>] [-to <date>]] [-tokenlastused [-from <date>] [-to <date>]] [-haspin] [-locked] [-userid <userid>] [-alias <alias>] [-id <id>] [-next <nextuser>] [-tokensernum <sernum>] [-group ([-] <group>)+] [-tokenstate (pending hold_pending hold current canceled)+] [-max <num>] Where: -next is used to get the next user value set by a previous tokenlist command. <nextuser> provides the number of users returned previously. API overview and samples 37

40 Table 3: Administration sample commands (continued) Command usertokenset usertokenunassign Explanation Changes details of a user s token. Syntax: usertokenset <userid> (<sernum> -all (pending hold_pending current hold canceled)+) [(-tokenpin <value>) -disabletokenpin] [-updatetokenpin [true false]] [-state pending hold_pending hold current canceled] [-comment <text>] Unassigns a user s token. Syntax: usertokenunassign <userid> (<sernum> -all (pending hold_pending current hold canceled)+) [-comment <text>] 38 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

41 Chapter 2 Client application setup The Entrust IdentityGuard.NET Framework APIs are a set of services and operations used for retrieving challenge requests, authenticating user responses, administrating users, and authentication mechanisms. They are designed to integrate with an existing client application. This chapter describes how to set up a client application to use the APIs. It contains the following topics: Setting up your application on page 40 Using SSL communication on page 41 Create a binding object on page 43 Updating V1 services to V2 on page 45 39

42 Setting up your application You must set up your application to use the Entrust IdentityGuard.NET proxy class libraries, which provide a convenient API for your client application. Your client application makes API calls to the Entrust IdentityGuard.NET proxy classes. The details on conforming to the WSDL definition and communicating with the Entrust IdentityGuard Web services are handled automatically. To use the Entrust IdentityGuard APIs, copy the following files from the <IG_INSTALL_DIR>\identityguard81\client\C#\lib directory and make them available to your client application: IdentityGuardAuthServiceV2CSharpAPI.dll (if you are using the Authentication API) IdentityGuardAdminServiceV2CSharpAPI.dll (if you are using the Administration API) 40 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

43 Using SSL communication The Entrust IdentityGuard Authentication and Administration Web services can communicate with client applications using SSL. Note: The Authentication Web service does not require a secure connection. The Administration Web service does. Topics in this section: Configuring trust on page 41 Configuring SSL with Entrust IdentityGuard replicas on page 42 Configuring trust Entrust IdentityGuard with embedded Tomcat server stores certificates in the keystore file under <IG_INSTALL_DIR>\identityguard81\etc. During installation, Entrust IdentityGuard creates its own self-signed certificate, and stores it under the tomcat alias. It uses this to perform SSL communications. See the Entrust IdentityGuard Installation Guide if you want to replace the self-signed certificate with your own certificate (or if you want to generate a new self-signed certificate). Your client application must trust the certificate associated with the tomcat alias in order for it to communicate using SSL to the Entrust IdentityGuard Web services. You can configure your client application to trust the Entrust IdentityGuard certificate directly, or to trust the associated CA certificate. To configure your client application to trust the Entrust IdentityGuard certificate 1 Open Internet Explorer, pointing it to your Entrust IdentityGuard administration service URL. 2 Double-click the lock sign on the lower right corner of the browser. 3 From the pop-up Certificate window, click Install Certificate. 4 Follow the instructions of the Certificate Import Wizard to install the certificate. Client application setup 41

44 Configuring SSL with Entrust IdentityGuard replicas An Entrust IdentityGuard deployment consists of one primary server and zero or more replica servers. The Authentication and Administration Web services are available on all Entrust IdentityGuard servers (the primary and all replicas). The following guidelines apply when using Entrust IdentityGuard replicas: Your client application can contact the Web services on any of these Entrust IdentityGuard servers; it is up to your client application to decide which Web IdentityGuard server(s) to contact. Note: Depending on your Entrust IdentityGuard deployment scenario, the Web services running on the Entrust IdentityGuard replica servers may not provide the same functionality as the primary Entrust IdentityGuard service. For example, if you are using an LDAP Directory or Active Directory repository and you have the file-based preproduced card functionality enabled, then any Administration API functions associated with these preproduced cards will only work on the primary server. The same goes for unassigned tokens stored in a file-base repository. See the Storing unassigned cards and tokens section of the Entrust IdentityGuard Installation Guide for details. Configure your application to trust the certificates for each Entrust IdentityGuard instance. You can either import each Entrust IdentityGuard certificate individually into your client application s keystore, or you can import the CA certificate associated with the Entrust IdentityGuard certificates. If all Entrust IdentityGuard instances use their own self-signed certificates, import all the required Entrust IdentityGuard certificates into your client application s keystore. If you installed your own certificates after the Entrust IdentityGuard installation, you can import them. If these certificates are all generated by the same CA, then you only need to import the CA certificate into your client application s keystore. 42 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

45 Create a binding object By using specific.net proxy classes, you can retrieve a binding object that understands how to connect to the Entrust IdentityGuard services. These services perform all the transformations necessary to send a SOAP XML request to the server. Topics in this section: Create an authentication binding object on page 43 Create an administration binding object on page 44 Create an authentication binding object To create a new binding object that invokes authentication operations, you need to know the location of the authentication service. The following code sample illustrates the use of the AuthenticationService_Service interface class: // the URL where the authentication service is located: string urlstring = " ationservicev2"; // Create a new binding using the URL just created: AuthenticationService authbinding = new AuthenticationService(); authbinding.url = urlstring; // Time out after 10 seconds authbinding.timeout = 10000; Challenge retention When you use getchallenge or getgenericchallenge for a user, the challenge information is retained. That is, Entrust IdentityGuard issues the same challenge each time the user requests one until the user answers the original challenge correctly. When you use getanonymouschallenge or getanonymouschallengeforgroup, the challenge information is not retained. Entrust IdentityGuard does not track challenges for the user and issues a new challenge each time the user requests one. Therefore, anonymous challenges create a potential security risk. Attackers who have already captured some challenge responses can cycle through challenges until they get a challenge they can answer. Client application setup 43

46 With an anonymous challenge, the client application is responsible for tracking the challenge and user in order to prevent a user from cycling through multiple challenges until receiving a previously compromised challenge request. Create an administration binding object To create a new binding object that invokes administration operations, you need to know the location of the administration service. The following code sample illustrates the use of the AdminService_Service interface class: AdminService adminbinding = null; string urlstring = " vicev2"; // Create the URL where the administration service is located: adminbinding = new AdminService(); adminbinding.cookiecontainer = new CookieContainer(); adminbinding.url = urlstring; // Time out after 10 seconds adminbinding.timeout = 10000; 44 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

47 Updating V1 services to V2 Entrust IdentityGuard 8.0 authentication service supports Microsoft.NET Framework 2.0. After upgrading to Entrust IdentityGuard 8.1, your.net authentication client application can still access the V1 authentication service. You can also update your client application to access V2 authentication service. This section provides you with the information you need to upgrade from V1 services to V2. Topics in this section: Update service URLs on page 45 CallParms classes for Authentication service on page 46 Update service URLs The URLs for accessing the V2 services are the same Entrust IdentityGuard 8.0 URLs with V2 appended to the end. You must update the URLs to access V2 services. For example, instead of accessing the Authentication service from use Update proxy class library Update the V1 authentication proxy class library to V2. The V2 authentication proxy class library is IdentityGuardAuthServiceV2CSharpAPI.dll. Update proxy class namespace In your application code, update the namespace of V1 proxy class to V2. For example, instead of using V1 namespace using IdentityGuardAuthenticationService; update it to using IdentityGuardAuthServiceV2CSharpAPI; Client application setup 45

48 CallParms classes for Authentication service All methods in the AuthenticationService now accept a single parameter, which is an instance of a class that contains the parameters. The class containing the parameters has the name of the method in the AuthenticationService interface with CallParms appended. The CallParms classes have constructors that accept these parameters. If you are upgrading an application from V1 to V2, you need to update your code as follows: V1 coding sample for AuthenticationService_Port The following provides an example of AuthenticationService coding for V1 applications: AuthenticationService binding = getbinding(); AuthenticateResponse resp = binding.authenticate(userid, challengeresponse); V2 coding sample for AuthenticationService_PortType The following shows how you must update the code of AuthenticationService for V2 applications: AuthenticationService binding = getbinding(); AuthenticateCallParms callparms = new AuthenticateCallParms(); callparms.userid = userid; callparms.challengeresponse = challengeresponse; AuthenticateResponse resp = binding.authenticate(callparms); Update message field in AuthenticationFault The message field in AuthenticationFault class, and its sub class AuthenticationServiceFault and AuthenticationSystemFault, are changed to errormessage. For example, in the V1 application code, the following lines AuthenticationFault warningfault = resp.warningfault; log(warningfault.message); should be updated to AuthenticationFault warningfault = resp.warningfault; log(warningfault.errormessage); 46 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

49 Chapter 3 Authentication approaches This chapter explains the various Entrust IdentityGuard authentication approaches you can take using the Entrust IdentityGuard authentication APIs. It contains the following topics: Anonymous grid authentication on page 48 Two-step grid authentication on page 52 Generic authentication on page 54 Machine authentication on page 61 Mutual authentication on page 71 Multifactor authentication on page 77 47

50 Anonymous grid authentication Note: This approach applies to grid or temporary PIN authentication only. Use this approach if you want to combine first and second-factor authentication on a single page that is, you do not want to present your users with two authentication pages. In this approach, the existing system does not know the identity of the user until after login and authentication the user is anonymous until both first and second-factor authentication are complete. Topics in this section: One-step API methods on page 49 One-step API code sample on page 49 String conversion sample on page 50 In one-step authentication, you add an Entrust IdentityGuard challenge to your existing authentication page, as in Figure 1. Figure 1: One-step authentication example 48 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

51 Attention: When you use one-step authentication, Entrust IdentityGuard does not track challenges per user. Your own authentication application must ensure that the challenge returned to Entrust IdentityGuard by authenticateanonymouschallenge is the same as the challenge returned for the user by getanonymouschallenge. Otherwise, a previously used challenge response can be successfully used again. This increases the risk of an attacker capturing and reusing a challenge. One-step API methods If the user and group are unknown, implement anonymous grid authentication using getanonymouschallenge to issue the challenge, and authenticateanonymouschallenge to authenticate the response. The policy associated with the default group is used to generate the challenge. If the user is unknown, but the group is known, implement anonymous grid authentication with getanonymouschallengeforgroup to issue the challenge and authenticateanonymouschallenge to authenticate the response. The policy associated with the specified group is used to generate the challenge. Note: It is possible for the client application to construct its own challenge set and bypass getanonymouschallenge. This procedure requires complete knowledge of the applicable user policy. One-step API code sample The following code fragments show how to issue an anonymous challenge for a user or a user in a specific group, and how to authenticate the response. If the user is part of the default group, get the challenge set this way: ChallengeSet challengeset = authbinding.getanonymouschallenge(); For a user in a group other than the default, get the challenge set this way: GetAnonymousChallengeForGroupCallParms callparms = new GetAnonymousChallengeForGroupCallParms(); callparms.group = groupid; ChallengeSet challengeset = authbinding.getanonymouschallengeforgroup(callparms); Authentication approaches 49

52 Convert the challenge if required by the client application interface (see String conversion sample on page 50). Once the client application receives the user ID and challenge response, authenticate the response as follows: AuthenticateAnonymousChallengeCallParms callparms = new AuthenticateAnonymousChallengeCallParms(); callparms.userid = userid; callparms.challengeset = challengeset; callparms.challengeresponse = response; AuthenticateResponse resp = authbinding.authenticateanonymouschallenge(callparms); String conversion sample Entrust IdentityGuard returns a grid challenge as a set of integers. The client application can convert the challenge to anything it needs before displaying it. This example converts the challenge to a string, such as [A,1] [B,2] [C,3]. StringBuilder builder = new StringBuilder(""); Challenge[] challarr = challengeset.challenge; for (int i = 0; i < challarr.length; i++) { if (i!= 0) { builder.append(" "); } Challenge chall = challarr[i]; builder.append('['); builder.append((char)(chall.column + (int)'a')); builder.append(','); builder.append(chall.row + 1); builder.append(']'); } string challengestring = builder.tostring(); 50 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

53 Through conversion, you can apply additional security to make challenges difficult to steal. For instance, you can obfuscate entries and avoid machine-readable characters by converting the challenge to images rather than text. Authentication approaches 51

54 Two-step grid authentication Use this approach to add second-factor authentication on a separate page. If you use getchallenge, you are limited to a grid or a temporary PIN. If you use getgenericchallenge, you can use a grid, a temporary PIN, a one-time password, questions and answers (knowledge-based), or a token. The user logs in on one page and is then shown a second page containing the Entrust IdentityGuard challenge, such as the grid challenge in Figure 2. Because the user has already passed first-factor authentication, the user s identity is known. Entrust IdentityGuard tracks the current challenge issued to that user and continues to validate user responses against this challenge until a successful authentication occurs. Figure 2: Two-step authentication with a grid John Smith ****** To implement two-step authentication using a grid or temporary PIN, use getchallenge to issue the challenge and authenticate to authenticate the response. The following code fragments show how to issue a grid challenge to a user who has already logged in, and how to authenticate the response. First, get a challenge set for a user as follows: GetChallengeCallParms callparms = new GetChallengeCallParms(); callparms.userid = userid; ChallengeSet challengeset = authbinding.getchallenge(callparms); and convert it to a string if necessary (see String conversion sample on page 50). Next, authenticate the response as follows: AuthenticateCallParms callparms = new AuthenticateCallParms(); 52 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

55 callparms.userid = userid; callparms.challengeresponse = response; AuthenticateResponse resp = authbinding.authenticate(callparms); For information on two-step authentication using other authentication methods, see Generic API methods on page 54. Authentication approaches 53

56 Generic authentication This approach can include one or more authentication methods grid authentication, a token, a one-time password, knowledge-based authentication, shared secrets, and external authentication. Topics in this section: Generic API methods on page 54 Grids on page 54 Tokens on page 55 Out-of-band authentication on page 55 Knowledge-based questions on page 55 External authentication on page 56 Generic API code sample on page 57 Generic API methods To implement generic authentication, use getgenericchallenge to issue the challenge and authenticategenericchallenge to authenticate the response. The authentication method or methods available to getgenericchallenge are set based on the setting of the userspec policy attribute genericauthtype. You can also overwrite the default setting and specify the authentication type as shown in the sample code in Generic API code sample on page 57. For more information on the userspec policy, see the Entrust IdentityGuard Administration Guide. Grids When used with generic authentication, grid authentication is similar to Two-step grid authentication on page 52, but it is more versatile. Generic grid authentication can include authentication secrets such as the image replay (see Image and message replay on page 72). Grid challenges accept Temporary PIN as a response. Set the AuthenticationType object to GRID when calling getgenericchallenge and use the getgridchallenge method. For a more detailed example, see Generic API code sample on page Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

57 Tokens You can authenticate users with a dynamic password generated by a token device and, optionally, a token PIN. Tokens provide an alternative to card authentication. Token challenges accept temporary PINs as a response, just as cards do. As of patch , Entrust IdentityGuard supports the Entrust IdentityGuard Mini Token and the Entrust IdentityGuard Pocket Token (response-only mode). The Mini Token is available in an AT version (a time+event synchronous token) and an OE version (an OATH compliant token). Set the AuthenticationType object to TOKENRO when calling getgenericchallenge and use the gettokenchallenge method. Out-of-band authentication You can authenticate users with a one-time password (OTP). Use one-time passwords for new users or as an additional security step in multifactor authentication. Your organization can issue a one-time password by , a text message, or phone call. The user then enters the password online to enter your site or to initiate a secure transaction. Set the AuthenticationType object to OTP and use the getgenericchallenge operation. For a code example, see Generic API code sample on page 57. After Entrust IdentityGuard generates the one-time password, your application must use features of the Entrust IdentityGuard Administration Service API to retrieve the password. This API is described in the administration API.NET toolkit. Also see Create and send an OTP on page 87 for more information. Knowledge-based questions Your organization can question the user to confirm information that the user entered in the past through a registration process (see Figure 3). Alternatively, you can base questions on previous transactions or relationships. Either way, you provide mutual authentication. For a code sample, see Generic API code sample on page 57. Authentication approaches 55

58 Figure 3: Question-and-answer challenge For example, during enrollment the consumer may select and provide answers to easily-remembered questions, such as Your most memorable cartoon character, Year you bought your first car, Which historical figure do you most admire, and so on as shown in Figure 3. In addition, questions can be drawn from previous user interactions with the organization. Examples include: What was the balance on your last statement? How often do you make mortgage payments? Set the AuthenticationType object to QA and use the getgenericchallenge operation. For a code sample see Generic API code sample on page 57. External authentication In a normal VPN and Radius implementation, the VPN server communicates with the VPN client and with the Radius server, while the Radius server communicates directly with the VPN server. When you integrate with Entrust IdentityGuard, the Entrust IdentityGuard Radius proxy intercepts messages between the VPN server and the first-factor authentication resource, which may be one of a: Radius server Windows domain controller LDAP directory 56 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

59 Once your VPN server uses the Radius proxy for first-factor authentication, you can configure Entrust IdentityGuard to add the grid, token, or temporary PIN multifactor authentication methods to the first-factor authentication performed by the Radius proxy. Set the AuthenticationType object to external and use the getgenericchallenge operation. For code example see Generic API code sample on page 57. Generic API code sample The sample shows how to create or retrieve a generic challenge method for a given user, how to issue the generic challenge, and how to authenticate it. // Create the generic challenge parameters as follows: GenericChallengeParms genericchallengeparms = new GenericChallengeParms(); // Optionally retrieve the allowed authentication types for the // user or group like this: AllowedAuthenticationTypes types; GetAllowedAuthenticationTypesCallParms gettypecallparms = new GetAllowedAuthenticationTypesCallParms(); gettypecallparms.userid = userid; types = authbinding.getallowedauthenticationtypes (gettypecallparms); // or like this: GetAllowedAuthenticationTypesForGroupCallParms gettypeforgroupcallparms = new GetAllowedAuthenticationTypesForGroupCallParms(); gettypeforgroupcallparms.group = groupid; types = authbinding.getallowedauthenticationtypesforgroup (gettypeforgroupcallparms); // Next, set the authentication method to use. If one is not set, // the default type is used. Authentication approaches 57

60 AuthenticationType? authtype = null; // Use the first type in the list now AuthenticationType[] genericauthtypes = types.genericauth; if(genericauthtypes.length > 1) { authtype = genericauthtypes[0]; } genericchallengeparms.challengetype = authtype; // If applicable, set authsecparms to true to retrieve and display // the authentication secrets used for image and caption replay. AuthenticationSecretParms authsecparms = new AuthenticationSecretParms(); authsecparms.getall = true; genericchallengeparms.secretparms = authsecparms; // Get the generic challenge GetGenericChallengeCallParms callparms = new GetGenericChallengeCallParms(); callparms.userid = userid; callparms.parms = genericchallengeparms; GenericChallenge genericchallenge = authbinding.getgenericchallenge(callparms); // Separate the authentication secrets from the challenge NameValue[] secrets = genericchallenge.authenticationsecrets; // Add code to display the authentication secrets to the user. // If the authentication method is a grid, do the following: if (genericchallenge.type == AuthenticationType.GRID) { 58 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

61 ChallengeSet challengeset = genericchallenge.gridchallenge; } // At this point, add code to convert the challenge // if necessary. // If the authentication method is a token, do the following: if( genericchallenge.type == AuthenticationType.TOKENRO) { TokenChallenge tokenchallenge = genericchallenge.tokenchallenge; } // If the authentication method is knowledge-based // (questions and answers), do this: if( genericchallenge.type == AuthenticationType.QA) { String[] questions = genericchallenge.qachallenge; // Add code to display the questions to end user } // If the authentication method is one-time password, do this: if( genericchallenge.type == AuthenticationType.OTP) { // Use the administration service API to retrieve the password // and add code to deliver OTP to user, and prompt the user // for it. } // If the authentication method NONE, do the following: if (genericchallenge.type == AuthenticationType.NONE) { // For NONE, do not call authenticatgenericchallenge -- Authentication approaches 59

62 } // the user is not authenticated in any way // Once the client application gets a challenge response from the // user, authenticate the response try { AuthenticateGenericChallengeCallParms authcallparms = new AuthenticateGenericChallengeCallParms(); authcallparms.userid = userid; authcallparms.authenticationtype = authtype; // string array of response authcallparms.response = challengeresponse; GenericAuthenticateResponse response = authbinding.authenticategenericchallenge(authcallparms); } catch (Exception ex) { // Add code for exception handling if authentication fails 60 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

63 Machine authentication Machine authentication provides seamless authentication without any noticeable impact to the user experience. It is an especially attractive method if users usually access their accounts from the same computer. Topics in this section: Machine authentication API methods on page 62 Machine authentication API code example on page 62 Sources of machine information on page 65 Storing and retrieving machine information on page 69 This approach is typically combined with one or more of these authentication approaches: grid token one-time password knowledge-based authentication To establish the machine identity, you first generate a fingerprint of the user s computer. This fingerprint is based on a set of machine parameters chosen by your code that can be transparently read from the user s computer. Once it obtains this fingerprint, Entrust IdentityGuard generates a machine identity reference and stores it on the Entrust IdentityGuard server for future authentication. This machine registration process is similarly performed for all computers a user wishes to register. In Figure 4, the simple action of selecting the option Remember me on this machine puts machine authentication into action. Authentication approaches 61

64 Figure 4: Login page with machine authentication Machine authentication API methods To implement machine authentication, use registermachine to collect and register the machine fingerprint on the Entrust IdentityGuard Server and checkmachineregistration to check fingerprints. Machine authentication API code example The code sample provided demonstrates how to check to see whether a machine is registered. If it is registered, the fingerprint is updated. If it is not registered, a challenge is issued. The workflow in this method of authentication goes as follows: check for machine registration if the machine is registered update the fingerprint display the authentication secrets (the image and caption replay) prompt for the user name and password if machine is not registered register the machine prompt for the user name and password 62 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

65 This sample shows how to integrate machine integration with a client application: // Build the machine secret (the fingerprint) // Add code to store the secret as a cookie in the browser MachineSecret machinesecret = buildmachinesecret(); // authentication secrets NameValue[] authsec = null; CheckMachineRegistrationCallParms checkmaccallparms = new CheckMachineRegistrationCallParms(); checkmaccallparms.userid = userid; checkmaccallparms.machinesecret = machinesecret; // check machine registration using the default // machine authentication type MachineRegisterResponse machineregisterresponse = null; try { machineregisterresponse = authbinding.checkmachineregistration(checkmaccallparms); } catch(exception e) { // add code to handle exception } GenericChallenge genericchallenge = machineregisterresponse.challenge; // if the machine has not been registered, a challenge // is returned if (genericchallenge!= null) { // get the challenge response from user Authentication approaches 63

66 string[] challengeresponse = getchallengeresponse(genericchallenge); AuthenticationSecretParms authsecparms = new AuthenticationSecretParms(); authsecparms.getall = true; // get all secrets MachineRegisterParms machregparms = new MachineRegisterParms(); machregparms.authenticationsecretparms = authsecparms; // update machine secrets in IdentityGuard store machregparms.updatemachinesecret = true; RegisterMachineCallParms regmachcallparms = new RegisterMachineCallParms(); regmachcallparms.userid = userid; regmachcallparms.machinesecret = machinesecret; regmachcallparms.response = challengeresponse; regmachcallparms.registerparms = machregparms; // register machine try { machineregisterresponse = authbinding.registermachine(regmachcallparms); } catch (Exception e) { // add code to handle exception } } // update the fingerprint (for sequence nonce) machinesecret = machineregisterresponse.machinesecret; // add code here to update the local machine fingerprint // setlocalmachineregistrationobject(machinesecret); 64 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

67 GenericAuthenticateResponse authresponse = machineregisterresponse.authenticateresponse; authsec = authresponse.authenticationsecrets; // add code here to display the authentication secrets // (e.g., image, text caption,...) // add code to process the primary authentication (username and // password) Sources of machine information There are several ways to create a fingerprint of a particular computer. The choice depends on the method chosen to gather fingerprint data. Basic Web browser without client-side software: This requires a Web browser only. From the user s perspective, it is the least invasive method of gathering the information for a machine fingerprint. Your program needs to set a cookie within the browser for subsequent authentication comparisons of the user s machine fingerprint. Take this into consideration when deploying machine authentication. There are two ways of gathering data from a Web browser without requiring client-side software. You can use the browser Get request or JavaScript. Through a Web browser Get request, the application can identify a browser using the HTTP headers present in the browser s request to the server. Unfortunately, all data returned is quite predictable, even to an attacker who has never seen a particular browser s request. Figure 5 shows a sample Get request. Figure 5: Sample browser Get request GET /cgi-bin/inputdump.exe HTTP/1.1 Accept: */* Accept-Language: en-us Accept-Encoding: gzip, deflate User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;.NET CLR ;.NET CLR ) Host: anyserver.anybank.com Connection: Keep-Alive Cookie: intranetredirecturl=; GA_SHOW_TABS=; LASTSITE=intranet Due to the predictability of standard Get requests from a browser, it is recommended that you do not use these fields on their own. Some fields (such as user-agent) may be useful as part of a broader machine fingerprint. Use other methods described in this section to create a unique machine fingerprint. Authentication approaches 65

68 Instead of Get requests, your Web application can use standard JavaScript calls to gather information. This involves a minor modification to the application s login page to collect the wider range of data needed for the machine fingerprint. All the following pieces of information are available through standard Javascript calls without requiring any client-side software. Note: The properties in Table 4 were collected using JavaScript on an Internet Explorer browser running on Windows. Similar properties are available on other browsers, but the names and values will vary. Table 4: General properties Property Value navigator.appcodename Mozilla navigator.appname Microsoft Internet Explorer navigator.appminorversion ;SP2; navigator.cpuclass x86 navigator.platform Win32 navigator.systemlanguage en-us navigator.userlanguage en-us navigator.appversion 4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;.NET CLR ;.NET CLR ) navigator.useragent Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;.NET CLR ;.NET CLR ) navigator.online true navigator.cookieenabled true screen.availheight 1170 screen.availwidth 1600 screen.bufferdepth 0 screen.colordepth 32 screen.devicexdpi 96 screen.deviceydpi 96 screen.fontsmoothingenabled true 66 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

69 Table 4: General properties (continued) Property Value screen.height 1200 screen.logicalxdpi 96 screen.logicalydpi 96 screen.updateinterval 0 screen.width 1600 Note: The properties in Table Note: and Table 6 show just a portion of the MIME and plug-in information available. They were collected using JavaScript on a Firefox browser running on Microsoft Windows. Similar properties are available on other browsers, but the names and values will vary. Table 5: MIME properties (partial list) Property Value navigator.mimetypes[0].description Mozilla Default Plug-in navigator.mimetypes[0].suffixes * navigator.mimetypes[0].type * navigator.mimetypes[1].description Java navigator.mimetypes[1].enabledplugin. NPOJI610.dll filename Table 6: Plug-in information (partial list) Property Value navigator.plugins[0].description Default Plug-in navigator.plugins[0].filename npnul32.dll navigator.plugins[0].length 1 navigator.plugins[0].name Mozilla Default Plug-in navigator.plugins[1].description Java Plug-in for Netscape Navigator (DLL Helper) Authentication approaches 67

70 Given the wide range of information available, some of which may be too common to be useful, we recommend that organizations consider the use of a combination of elements gathered through JavaScript such as: browser version browser plug-ins present browser language being used browser platform (user s operating system) screen size of user s computer (height and width) screen color depth Basic Web browser with client-side software: You can deploy signed Java applets or ActiveX controls that leave the Java sandbox and allow the applet to access the system directly. This involves the user seeing and accepting security notifications on a regular basis. While more secure, it is less than ideal for large-scale deployments. However, there may be instances where this is the best practice since it allows organizations to gather more detailed physical machine data for use in a machine fingerprint. Elements that could be gathered in this scenario include: media access control (MAC) address of the user s Ethernet card exact operating system (OS) information including the service pack and patch level system information including native byte order and number of available processors hardware information (manufacturer, model, version, and so on) of various hardware devices (network card, video card, hard drive, CD reader/writer, processor type) CPU processor ID (if enabled) user information (account name and home directory) You can combine these elements with other available elements to create the machine fingerprint. Web application (server-side): You can augment the information available through JavaScript and client-side software with data available from the Web application. Figure 6 shows information gathered by a simple server-side CGI. Figure 6: Sample Web application data HTTP_USER_AGENT=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-us; rv:1.7.10) Gecko/ Firefox/1.0.6 HTTP_ACCEPT=text/xml,application/xml,application/xhtml+xml,text/ht ml;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5 HTTP_ACCEPT_LANGUAGE=en-us,en;q=0.5 HTTP_ACCEPT_ENCODING=gzip,deflate 68 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

71 HTTP_ACCEPT_CHARSET=ISO ,utf-8;q=0.7,*;q=0.7 HTTP_KEEP_ALIVE=300 HTTP_CONNECTION=keep-alive HTTP_COOKIE=LASTSITE=anybank; intranetredirecturl=https%3a//anyserver.anybank.com/download/cnbc. htm; GA_SHOW_TABS=0%2C1%2C2%2C4 REMOTE_ADDR= REMOTE_PORT=1294 Much of this information is derived from the HTTP headers in the Get request (see Figure 5 on page 65). This list includes a port and IP address for the user. Port information may change each time and is not a useful property for a machine fingerprint.you can use a user s IP address to look up geolocation information. Entrust IdentityGuard can store additional application data specified by your organization, including data that may be gathered with standard APIs through external data sources. (For example, geolocation services can estimate the geographic location of the user based on their PC s IP address.) Storing and retrieving machine information For machine authentication, organizations need to modify their application to first gather the information available as described in Sources of machine information starting on page 65. Once gathered, you can pass this information to Entrust IdentityGuard through standard Web service APIs for storage. The contents of a machine fingerprint in Entrust IdentityGuard include at least the machine nonce, and optionally a sequence nonce and application data. Machine nonce: This is an arbitrary number generated by Entrust IdentityGuard for authentication purposes when Entrust IdentityGuard registers the machine. You must store the nonce on the client machine by the application, typically in a cookie or a Flash MX shared object. This nonce value does not change. Note: Flash MX shared objects are a feature in Macromedia Flash that allow applications to store information similar to cookies on a machine and retrieve it at a later time. It stores information without the need for to enable cookies. For Entrust IdentityGuard, Flash MX shared objects can store both the machine nonce and the sequence nonce. Optional sequence nonce: Entrust IdentityGuard generates and changes the sequence nonce each time authentication occurs. A sequence nonce assures that the machine secret is only valid until the next login attempt. This increases security by reducing the validity period of the machine information, and by making it more difficult for an attacker to use the cookies without being detected. Authentication approaches 69

72 You must store the sequence nonce on the client machine by the application, typically in a cookie or a Flash MX shared object. The inclusion of a sequence nonce is a recommended approach to strengthen machine authentication. Optional application data: When Entrust IdentityGuard first creates the machine secret, the client application specifies and sets a list of name and value pairs. A client application can provide Entrust IdentityGuard with application data specific to the user s computer. This can include operating system and browser versions gathered through simple methods that do not require client-side software, as described in Sources of machine information starting on page 65. During authentication, the application must retrieve and pass the contents of the fingerprint to Entrust IdentityGuard for comparison and validation. You can decide how many properties must successfully match in the fingerprint for successful authentication (for example, five of six must be correct). Failure may depend on the property in question. If one of the properties captured is the browser version and in subsequent authentications that version changes (perhaps the user upgraded the browser), it may still make sense to allow that user access. It is recommended that organizations examine their user base carefully before configuring this option in order to maximize security and overall usability. 70 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

73 Mutual authentication Users need confidence that they are transacting with the intended organization. Likewise, the organization needs to have confidence in the identity of the user. Entrust IdentityGuard provides ways for both parties to authenticate each other. Mutual authentication refers to replay features or specific authentication methods that allow the user to validate the organization at the same time the organization authenticates the user. Topics in this section: Grid serial number and location replay on page 71 Token serial number replay on page 72 Knowledge-based authentication on page 72 Image and message replay on page 72 Serial number replay sample on page 73 Image and caption replay samples on page 74 Image management on page 76 Grid serial number and location replay Grid authentication not only provides a secure, low cost, and easy way to authenticate users, it includes built in mechanisms for mutual authentication. One mechanism is based on the serial number of the grid itself. Each grid card has a unique serial number that is known only to the organization that issued it and the user. During login, you can display this number to the user before prompting for user authentication. Before entering a password or grid challenge response, users simply confirm that the serial number displayed on the Web site matches the one on their grid card. If it does, users can be confident they are on the legitimate Web site. Another mechanism available with the grid card is to replay specific grid coordinates. When displayed to the user, this confirms that the site has specific knowledge of the contents of the user s grid and, therefore, must be legitimate. Authentication approaches 71

74 Token serial number replay Token authentication lets your end users further authenticate themselves using a token dynamic password after completing first-factor authentication. Tokens represent a stronger method of user authentication than knowledge factors alone because they combine possession (the token) and knowledge (the dynamic password or PIN). One mechanism is based on the serial number of the token itself. Entrust tokens have a unique serial number that is known only to the organization that issued it and the user. During login, you can display this number to the user before prompting for user authentication. Before entering a password or token challenge response, users simply confirm that the serial number displayed on the Web site matches the one on their token. If it does, users can be confident they are on the legitimate Web site. Knowledge-based authentication You can provide questions that challenge users to provide information that only they know. This helps an organization verify the user, but since the user recognizes the source or origin of the questions, the user also recognizes the site is legitimate (see Knowledge-based questions on page 55 for more information). Image and message replay Another feature available with generic authentication is image and caption replay. In this case, as part of the registration process, a user selects an image from a gallery and and enters a custom image caption that is later shown during login. By personalizing the login with the image and message, as shown in Figure 7 on page 73, the user recognizes the site is legitimate during login because a fraudulent one would not have this information to replay. 72 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0

75 Figure 7: Choosing a custom image and caption Serial number replay sample For a grid challenge, you can display the grid card serial number to the user in the challenge. Use code like the following: // Get the card serial number string[] sernum = challengeset.cardserialnumbers; Since users may have more than one valid card (active and pending), this returns a string array. For a token challenge, you can display the token serial number to the user in the challenge. Use code like the following: // Get the token serial numbers TokenInfo[] tokens = tokenchallenge.tokens; String[] tokensernum = new string[tokens.length]; for (int i = 0; i < tokens.length; i++) { tokensernum[i] = tokens[i].serialnumber; } Authentication approaches 73