Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0 Date of Issue: April 2007
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
Table of contents About this guide..............................................5 Documentation conventions.................................... 6 Note and Attention text................................... 6 Related documentation........................................ 7 Obtaining documentation...................................... 8 Documentation feedback.................................. 8 Obtaining technical assistance................................... 9 Technical support........................................ 9 Professional Services..................................... 10 CHAPTER 1 API overview and samples......................................11 Entrust IdentityGuard APIs..................................... 12 V1 and V2 services...................................... 12 Authentication V2 API................................... 13 Administration V2 API................................... 13 V2 Web service definition files............................. 13 V2.NET class files...................................... 14 Sample applications.......................................... 16 Sample command-line applications......................... 16 Running the sample authentication client..................... 16 Running the sample administration client..................... 29 Using the administration commands........................ 31 CHAPTER 2 Client application setup........................................39 Setting up your application.................................... 40
Using SSL communication..................................... 41 Configuring trust....................................... 41 Configuring SSL with Entrust IdentityGuard replicas............. 42 Create a binding object....................................... 43 Create an authentication binding object...................... 43 Create an administration binding object...................... 44 Updating V1 services to V2.................................... 45 Update service URLs.................................... 45 Update proxy class library................................ 45 Update proxy class namespace............................. 45 CHAPTER 3 Authentication approaches......................................47 Anonymous grid authentication................................. 48 One-step API methods................................... 49 One-step API code sample................................ 49 String conversion sample................................. 50 Two-step grid authentication................................... 52 Generic authentication........................................ 54 Generic API methods.................................... 54 Grids................................................ 54 Tokens............................................... 55 Out-of-band authentication............................... 55 Knowledge-based questions............................... 55 External authentication.................................. 56 Generic API code sample................................. 57 Machine authentication....................................... 61 Machine authentication API methods........................ 62 Machine authentication API code example.................... 62 Sources of machine information............................ 65 Storing and retrieving machine information................... 69 2 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
Mutual authentication........................................ 71 Grid serial number and location replay....................... 71 Token serial number replay............................... 72 Knowledge-based authentication........................... 72 Image and message replay................................ 72 Serial number replay sample.............................. 73 Image and caption replay samples.......................... 74 Image management..................................... 76 Multifactor authentication..................................... 77 CHAPTER 4 Administration tasks.......................................... 79 Administration setup and login................................. 80 Basic administration tasks..................................... 82 Create and register a user................................ 82 Create and assign preproduced cards........................ 86 Create and send an OTP................................. 87 Assign and modify a token............................... 88 Create and modify a temporary PIN........................ 89 Set up a user s questions and answers....................... 90 Unlock users.......................................... 91 Administrative monitoring tasks................................ 93 Check for expiring cards................................. 93 Check card inventory.................................... 94 Check token inventory................................... 95 Check for unused assigned cards or tokens................... 96 CHAPTER 5 API exceptions.............................................. 99 SoapException returned by proxy classes......................... 100 ErrorCode class............................................ 101 Authentication warning faults................................. 103 Administration Password Change......................... 103 Index.................................................... 105 3
4 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
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
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 www.entrust.com. 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
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 http://www.entrust.com/strong-authentication/identityguard/index.htm For information on identity theft protection seminars, go to http://www.entrust.com/events/identityguard.htm About this guide 7
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: https://www.entrust.com/trustedcare 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: http://www.entrust.com/products/feedback/index.cfm You can also direct feedback concerning documentation to the Customer Support email address. support@entrust.com 8 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
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: http://www.entrust.com/ 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: https://www.entrust.com/trustedcare 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: 1-877-754-7878 in North America 1-613-270-3700 outside North America Email address The email address for Customer Support is: support@entrust.com About this guide 9
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: http://www.entrust.com 10 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
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
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: http://<host>:8080/identityguardauthservice/services/authenticationservice https://<host>:8443/identityguardauthservice/services/authenticationservice https://<host>:8444/identityguardadminservice/services/adminservice 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: http://<host>:8080/identityguardauthservice/services/authenticationservicev2 https://<host>:8443/identityguardauthservice/services/authenticationservicev2 12 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
https://<host>:8444/identityguardadminservice/services/adminservicev2 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
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: http://<host>:8080/identityguardauthservice/services/authenticationservicev2?wsdl https://<host>:8443/identityguardauthservice/services/authenticationservicev2?ws dl https://<host>:8444/identityguardadminservice/services/adminservicev2?wsdl 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
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
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
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
- 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: http://ig81demo:8080/identityguardauthservice/services/authenticat 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
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
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
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
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
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
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
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
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
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
Table 2: Authentication sample command (continued) Command getgenericchallenge (continued) registermachine Description A typical response is: Running getgenericchallenge using userid 'iguser2'... Token Challenge. Token: 0065923412 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
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
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: https://ig81demo.entrust.com:8444/identityguardadminservice/servic 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
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
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
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
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
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
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
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
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
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
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
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
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
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 = "http://localhost:8080/identityguardauthservice/services/authentic 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
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 = "http://localhost:8444/identityguardadminservice/services/adminser 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
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 http://<host>:8080/identityguardauthservice/services/authenticationservice use http://<host>:8080/identityguardauthservice/services/authenticationservicev2 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
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
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
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
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
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
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
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
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
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 57. 54 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
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 129366, 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 email, 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
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
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
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
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
} // 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
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
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
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
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
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 1.1.4322;.NET CLR 2.0.50727) 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
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 1.1.4322;.NET CLR 2.0.50727) navigator.useragent Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;.NET CLR 1.1.4322;.NET CLR 2.0.50727) 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
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 1.5.0 for Netscape Navigator (DLL Helper) Authentication approaches 67
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/20050716 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
HTTP_ACCEPT_CHARSET=ISO-8859-1,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=10.4.132.9 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
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
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
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
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
Image and caption replay samples In generic authentication, the generic challenge response and generic authentication response can contain authentication secrets, such as images and captions, used for mutual authentication. Note: To use getgenericchallenge to retrieve authentication secrets, the user policy for the user group must have the returnauthsecretwithchallenge attribute set to true. The default is false. To retrieve authentication secrets, you must do one of the following: Set AuthenticationSecretParms so that the authentication secrets are retrieved with the challenge. If you want to retrieve all secrets, use a line like this: authsecparms.getall = true; If you want to retrieve the secrets by specifying their names, use a line like this: authsecparms.get = auth_sec_name_array; Add the AuthenticationSecretParms object to GenericChallengeParms, which is used in getgenericchallenge operation. Add the AuthenticationSecretParms object to AuthenticateGenericChallengeCallParms, which is used in authenticategenericchallenge operation. Retrieve the authentication secrets from the generic challenge object. The following sample code retrieves authentication secrets using the getgenericchallenge operation: /// the following code retrieves authentication secrets // from a get generic challenge operation // Set AuthenticationSecretsParms to get secrets AuthenticationSecretParms authsecparms = new AuthenticationSecretParms(); authsecparms.getall = true; // or specifically retrieve the authentication secret names // using authsecparms.setget(auth_sec_name_array); // Add authsecparm to genericchallengeparms GenericChallengeParms genchallparms = 74 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
new GenericChallengeParms(); genchallparms.secretparms = authsecparms; // Get a challenge GetGenericChallengeCallParms callparms = new GetGenericChallengeCallParms(); callparms.userid = userid; callparms.parms = genchallparms; 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 The following sample code retrieves authentication secrets using the authenticategenericchallenge operation: // the following code retrieves the authentication secrets // from the authenticate generic challenge operation // Set AuthenticationSecretsParms to get secrets AuthenticationSecretParms authsecparms = new AuthenticationSecretParms(); authsecparms.getall = true; // authentiate challenge response AuthenticateGenericChallengeCallParms callparms = new AuthenticateGenericChallengeCallParms(); callparms.userid = userid; callparms.response = response; callparms.authsecretparms = authsecparms; GenericAuthenticateResponse authresponse = authbinding.authenticategenericchallenge(callparms); //Separate the authentication secrets from the challenge Authentication approaches 75
NameValue[] secrets = authresponse.authenticationsecrets; //Add code to display the authentication secrets to the user Include the code fragments above in the correct position in your application code. See the sample under Generic API code sample on page 57 for a more comprehensive example. Image management In some applications, users can upload their own images. You need to create the application code to upload and store the images. You can store user images in two ways: Use Administration API operations before the first user authentication process starts Use the Authentication API during the generic authentication process To store or update any authentication secrets, including images, use the authenticategenericchallenge operation. All authentication secrets are stored as strings; so, images must be converted. To store and retrieve images 1 Read the image as bytes. 2 Convert bytes to string using an encoding method such as Base 64. 3 Send the string to Entrust IdentityGuard as an authentication secret. To retrieve and display an image 1 Get the authentication secret string from Entrust IdentityGuard. 2 Convert string to bytes using an encoding method such as Base 64. In order for users to see the authentication secrets before the users are authenticated, the userspec policy for the user group must have the returnauthsecretwithchallenge attribute set to true. The default is false. For more information on the userspec policy, see the Entrust IdentityGuard Administration Guide. 76 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
Multifactor authentication If your organization has an e-commerce application for which the risk associated with a transaction increases with its monetary value or potential for fraud, you may want to implement multifactor authentication (also called layered or step-up authentication). The Web interface to a bank serves as a good example of where multifactor authentication can heighten security. Machine authentication is a perfectly acceptable way to authenticate a user if the user is just checking account balances or transferring small amounts of money. For large fund transfers or for signing up for new services (like a brokerage account), the bank can add a second authentication step (such as an out-of-band password or grid card) for extra security. Additionally, the bank can add serial number replay or image replay to ensure mutual authentication. There are no specific APIs for multifactor authentication. To implement multifactor authentication, amend the logic of your application to call one or more of the authentication methods documented in this chapter when specific events occur. Authentication approaches 77
78 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
Chapter 4 Administration tasks This chapter explains the various Entrust IdentityGuard administration tasks you can manage using the Entrust IdentityGuard Administration API. It contains the following topics: Administration setup and login on page 80 Basic administration tasks on page 82 Administrative monitoring tasks on page 93 79
Administration setup and login For a client application to use the Administration API, the client must have administrator credentials. Its administrator role must include any privileges required to complete the tasks assigned. For instructions on setting up an administrator, see the Entrust IdentityGuard Administration Guide. The following sample code generates an administration service binding object that connects to the Administration services URL: // the following sample code generates an administration service // binding object that connects to the Administration services // URL, and login the admin id // Create the URL where the administration service is located: try { AdminService adminbinding = new AdminService(); adminbinding.cookiecontainer = new CookieContainer(); adminbinding.url = adminserviceurl; // Time out after 10 seconds adminbinding.timeout = 10000; LoginParms loginparms = new LoginParms(); loginparms.adminid = admin_id; loginparms.password = admin_pswd; loginparms.response = resps; LoginCallParms callparms = new LoginCallParms(); callparms.parms = loginparms; LoginResult loginresult = adminbinding.login(callparms); if (loginresult.state.equals(loginstate.complete)) { // login complete } 80 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
else if (loginresult.state.equals(loginstate.need_second_factor)) { ChallengeSet challset = loginresult.challengeset; // add code to handle second factor authentication } else { // login failed, add code to handle login failure } } catch (Exception e) { // add code to handle login failure } Administration tasks 81
Basic administration tasks This section explains how to use the Administration API to handle day-to-day administration tasks. Topics in this section: Create and register a user on page 82 Create and activate a user s card on page 84 Create and assign preproduced cards on page 86 Create and send an OTP on page 87 Assign and modify a token on page 88 Create and modify a temporary PIN on page 89 Set up a user s questions and answers on page 90 Unlock users on page 91 Clear machine secrets on page 92 Create and register a user You must add new end users to the Entrust IdentityGuard repository when they register as an Entrust IdentityGuard user through your application. This example shows one approach: UserParms userparms = new UserParms(); // These attributs are ignored by the user create operation. // userparms.addaliases; // userparms.removealiases; // userparms.clearlockout; // userparms.clearmachinesecrets; // userparms.mergeauthenticationsecrets; // userparms.mergeqasecrets; // userparms.mergesecrets; // userparms.removeallauthenticationsecrets; // userparms.removeallqasecrets; // userparms.removeallsecrets; // userparms.removeauthenticationsecrets; // userparms.removeqasecrets; 82 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
// userparms.removesharedsecrets; // set attributes userparms.userid = userid; userparms.group = groupid; userparms.aliases = aliases; userparms.phonenumber = phone; userparms.emailaddress = email; userparms.authenticationsecrets = authsecrets; userparms.qasecrets = qasecrets; userparms.sharedsecrets = sharedsecrets; UserCreateCallParms callparms = new UserCreateCallParms(); callparms.userid = userid; callparms.parms = userparms; adminbinding.usercreate(callparms); Note: If your application stores users in a directory repository, make sure a user entry exists in the repository before you create the user in Entrust IdentityGuard. Administration tasks 83
Create and activate a user s card There are two ways to create cards for your end users. You can create a set of unassigned cards and assign them to users, as described in Create and assign preproduced cards on page 86. Alternatively, you can create and assign a single card in one step using the usercardcreate method. The following example creates a single card for a user in HOLD_PENDING state and activates it to the Current state: Create a user card UserCardParms usercardparms = new UserCardParms(); usercardparms.serialnumber = sernum; usercardparms.comment = comment; usercardparms.lifetime = lifetime; usercardparms.supersede = supersede; // set card state to HOLD_PENDING usercardparms.state = State.HOLD_PENDING; UserCardCreateCallParms callparms = new UserCardCreateCallParms(); callparms.userid = userid; callparms.parms = usercardparms; adminbinding.usercardcreate(callparms); Activate a user card // the following code activates a user card // change the card state to PENDING first // if the card state is HOLD_PENDING, change it // to PENDING first UserCardFilter usercardfilter = new UserCardFilter(); usercardfilter.serialnumber = cardserialnumber; UserCardParms usercardparms = new UserCardParms(); usercardparms.state = State.PENDING; 84 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
UserCardSetCallParms callparms = new UserCardSetCallParms(); callparms.userid = userid; callparms.filter = usercardfilter; callparms.parms = usercardparms; int r = adminbinding.usercardset(callparms); try { // authenticate the user using authentication service // see chapter 3 of this guide for grid authentication using // the auth service API example } catch (Exception e) { // if authentication failed, change the card state back // to HOLD_PENDING usercardparms.state = State.HOLD_PENDING; callparms.parms = usercardparms; adminbinding.usercardset(callparms); } Remember, you must manufacture and distribute the physical cards to your end users. See the Entrust IdentityGuard Deployment Guide for suggestions. Note: You can never unassign a card created this way. You can only unassign preproduced cards. Administration tasks 85
Create and assign preproduced cards You can create a specific number of unassigned cards in one operation using the cardcreate method. Cards are later assigned to users using the usercardcreate method, as shown: Create preproduced cards // The following code creates preproduced cards for a group. PreproducedCardParms preproducedcardparms = new PreproducedCardParms(); preproducedcardparms.numcards = numcards; preproducedcardparms.group = group; PreproducedCardCreateCallParms callparms = new PreproducedCardCreateCallParms(); callparms.parms = preproducedcardparms; PreproducedCardCreateResult result = adminbinding.preproducedcardcreate(callparms); Assign preproduced card // The following code assigns a preproduced card to a user. UserCardParms usercardparms = new UserCardParms(); usercardparms.serialnumber = sernum; usercardparms.lifetime = lifetime; // set the card state to HOLD_PENDING usercardparms.state = State.HOLD_PENDING; UserCardCreateCallParms callparms = new UserCardCreateCallParms(); callparms.userid = userid; callparms.parms = usercardparms; adminbinding.usercardcreate(callparms); 86 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
Create and send an OTP In some multifactor authentication scenarios, your application may require a one-time password (OTP) to authenticate a user for a single transaction or to tie a login to the application. Optionally, you create and update an OTP using the Administration API. You should distribute the OTP to your end user through an out-of-band method, such as by text message or email. The following example creates and retrieves an OTP: Note: This step is optional as getgenericchallenge in the authentication API automatically creates an OTP if required. However, using the method shown in this example guarantees the return of a valid OTP. Create an OTP // The following code generates the OTP for a given user id UserOTPParms userotpparms = new UserOTPParms(); // The lifetime of the OTP in milliseconds userotpparms.lifetime = lifetime; UserOTPCreateCallParms callparms = new UserOTPCreateCallParms(); callparms.userid = userid; callparms.parms = userotpparms; UserOTPInfo otp = adminbinding.userotpcreate(callparms); Retrieve an OTP // The following code retrieves the OTP for a given user id UserOTPGetCallParms callparms = new UserOTPGetCallParms(); callparms.userid = userid; UserOTPInfo otp = adminbinding.userotpget(callparms); string otpstring = otp.otp; Administration tasks 87
Assign and modify a token Once tokens are loaded into Entrust IdentityGuard, you can assign them to your end users. Token devices generate a dynamic password for use in authenticating users. Token authentication may also require a token PIN. The following example assigns a token to a user, sets the initial value for the token PIN, and requires that the user enter a new token PIN at the first authentication: Assign a token // The following code assigns a token to the given user // and sets the token state to HOLD_PENDING UserTokenParms usertokenparms = new UserTokenParms(); usertokenparms.state = State.HOLD_PENDING; usertokenparms.tokenpin = tokenpin; usertokenparms.updatetokenpin = true; UserTokenAssignCallParms callparms = new UserTokenAssignCallParms(); callparms.userid = userid; callparms.serialnumber = sernum; callparms.parms = usertokenparms; adminbinding.usertokenassign(callparms); Modify a token // The following code changes the state of a user token // to PENDING UserTokenFilter usertokenfilter = new UserTokenFilter(); usertokenfilter.serialnumber = sernum; UserTokenParms usertokenparms = new UserTokenParms(); usertokenparms.state = State.PENDING; UserTokenSetCallParms callparms = new UserTokenSetCallParms(); 88 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
callparms.userid = userid; callparms.filter = usertokenfilter; callparms.parms = usertokenparms; adminbinding.usertokenset(callparms); Create and modify a temporary PIN If end users lose a card or token, or if users are waiting for their first card or token, you can issue them a temporary PIN. The following example creates a temporary PIN for a user and sets its lifetime to one day: Create a user temporary PIN // The following code creates a temporary PIN for // a given user and replaces the existing temporary PIN UserPINParms userpinparms = new UserPINParms(); // The lifetime of the PIN in milliseconds userpinparms.lifetime = lifetime; // replace the existing temporary PIN userpinparms.force = true; UserPINCreateCallParms callparms = new UserPINCreateCallParms(); callparms.userid = userid; callparms.parms = userpinparms; adminbinding.userpincreate(callparms); Administration tasks 89
Retrieve a user temporary PIN // The following code retrieves a temporary PIN for a given user UserPINGetCallParms callparms = new UserPINGetCallParms(); callparms.userid = userid; UserPINInfo pin = adminbinding.userpinget(callparms); Modify a user temporary PIN // The following code modifies the lifetime and maximum use times // of the user temporary PIN UserPINParms userpinparms = new UserPINParms(); // The lifetime of the PIN in milliseconds userpinparms.lifetime = lifetime; userpinparms.maxuses = max; UserPINSetCallParms callparms = new UserPINSetCallParms(); callparms.userid = userid; callparms.parms = userpinparms; adminbinding.userpinset(callparms); Set up a user s questions and answers For knowledge-based authentication to work, you must first ask users a series of questions to which the user must respond with answers. Your organization creates these questions, which are usually personalized to ensure that only the user can respond correctly. Users provide their stock answers at registration. Entrust IdentityGuard stores the questions and answers for later user authentication. The following shows how to present questions, collect the answers, and store the results: // The following code sets the questions // for the user's QA authentication NameValue[] qapairs = new NameValue[questionArray.length]; for (int i = 0; i < qapairs.length; i++) 90 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
{ qapairs[i].name = questionarray[i]; qapairs[i].value = answerarray[i]; } UserParms userparms = new UserParms(); userparms.qasecrets = qapairs; UserSetCallParms callparms = new UserSetCallParms(); callparms.userid = userid; callparms.parms = userparms; adminbinding.userset(callparms); Unlock users Entrust IdentityGuard locks out users if they failed a specified number of authentication attempts. When lockout occurs, your application can provide a way for the locked-out users to request an unlock. The following shows one approach to unlocking users: // The following code unlocks the user UserParms userparms = new UserParms(); userparms.clearlockout = true; UserSetCallParms callparms = new UserSetCallParms(); callparms.userid = userid; callparms.parms = userparms; adminbinding.userset(callparms); Administration tasks 91
Clear machine secrets User s machine secrets are stored at the Entrust IdentityGuard repository. An administrator can remove all machine secrets for the user. If the machine secrets are removed, users will be required to re-register the machine during their next attempt to access the Web site. // The following code clears all machine secrets for the user UserParms userparms = new UserParms(); userparms.clearmachinesecrets = true; UserSetCallParms callparms = new UserSetCallParms(); callparms.userid = userid; callparms.parms = userparms; adminbinding.userset(callparms); 92 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
Administrative monitoring tasks This section explains how to monitor your card and token inventory. Topics in this section: Check for expiring cards on page 93 Check card inventory on page 94 Check token inventory on page 95 Check for unused assigned cards or tokens on page 96 Check for expiring cards For planning purposes, it is useful to know how many assigned cards will expire in the near future. This lets you create, manufacture, and distribute new cards in a timely fashion. The following shows how to check for cards that will soon expire: // The following code returns the cards // that will expire in 10 days UserFilter userfilter = new UserFilter(); // set the expire end date to 10 DateTime expirydate = DateTime.Today; expirydate = expirydate.adddays(10); userfilter.expireenddate = expirydate; // return 50 cards for this call. The default value for // max return is 100. userfilter.maxreturn = 50; // optionally, starting from the nextuser value // of the previous search userfilter.nextuser = usertostart; Administration tasks 93
UserCardListCallParms callparms = new UserCardListCallParms(); callparms.filter = userfilter; UserCardListResult cards = adminbinding.usercardlist(callparms); // the nextuser value can be used at subsequent search string nextuser = cards.nextuser; Check card inventory For planning purposes, it is useful to know how many unassigned preproduced cards are still available. The following shows an easy way to count your remaining unassigned cards: // The following code returns the number of // preproduced cards for the given groups int numberofcards = 0; string nextcard = "-1"; while(!nextcard.equals("0")) { PreproducedCardFilter preproducedcardfilter = new PreproducedCardFilter(); preproducedcardfilter.groups = groupids; // start from the next card of previous search if (!nextcard.equals("-1")) { preproducedcardfilter.nextcard = nextcard; } PreproducedCardListCallParms callparms = new PreproducedCardListCallParms(); callparms.filter = preproducedcardfilter; 94 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
PreproducedCardListResult result = adminbinding.preproducedcardlist(callparms); // get the new next card serial number nextcard = result.nextcard; numberofcards = numberofcards + result.cards.length; } Check token inventory For planning purposes, it is useful to know how many unassigned tokens are still available. The following shows an easy way to count your remaining unassigned tokens: // The following code returns the number of // unassigned tokens for the given groups int tokennumber = 0; string nexttoken = "-1"; while (!nexttoken.equals("0")) { TokenFilter tokenfilter = new TokenFilter(); tokenfilter.groups = groupids; // start from the next token of previous search if (!nexttoken.equals("-1")) { tokenfilter.nexttoken = nexttoken; } TokenListCallParms callparms = new TokenListCallParms(); callparms.filter = tokenfilter; TokenListResult result = adminbinding.tokenlist(callparms); // get the new next token serial number nexttoken = result.nexttoken; tokennumber = tokennumber + result.tokens.length; } Administration tasks 95
Check for unused assigned cards or tokens For planning and monitoring purposes, it may be useful to know which users have not yet used their assigned cards or tokens. If you issue new cards and tokens in the Pending state, their state changes to Current the first time a user successfully authenticates with them. The following shows how to count and list cards and tokens in the Pending state: Check for unused assigned cards // The following code returns the assigned cards // that have never been used, e.g., card state is // PENDING or HOLD_PENDING UserFilter userfilter = new UserFilter(); State[] states = new State[2]; states[0] = State.PENDING; states[1] = State.HOLD_PENDING; userfilter.states = states; // return 50 cards for this call. The default value for // max return is 100. userfilter.maxreturn = 50; // optionally, starting from the nextuser value of // the previous search userfilter.nextuser = usertostart; UserCardListCallParms callparms = new UserCardListCallParms(); callparms.filter = userfilter; UserCardListResult result = adminbinding.usercardlist(callparms); // the nextuser value can be used at subsequent search String nextuser = result.nextuser; UserCardInfo[] cardinfoarray = result.cards; 96 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
Check for unused assigned tokens // The following code returns the assigned tokens // that have not been used for past 14 days UserFilter userfilter = new UserFilter(); // set the last used end date to 14 days ago DateTime tokenlastusedenddate = DateTime.Today; tokenlastusedenddate = tokenlastusedenddate.adddays(-14); userfilter.tokenlastusedenddate = tokenlastusedenddate; // return 50 tokens for this call. The default value for // max return is 100. userfilter.maxreturn = 50; // optionally, start from the nextuser value of // the previous search userfilter.nextuser = usertostart; UserTokenListCallParms callparms = new UserTokenListCallParms(); callparms.filter = userfilter; // return the tokens UserTokenListResult result = adminbinding.usertokenlist(callparms); // the nextuser value can be used at subsequent search string nextuser = result.nextuser; UserTokenInfo[] tokeninfoarray = result.tokens; Administration tasks 97
98 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
Chapter 5 API exceptions This chapter explains how to handle the exceptions returned by the Entrust IdentityGuard APIs. This chapter contains the following topics: SoapException returned by proxy classes on page 100 ErrorCode class on page 101 Authentication warning faults on page 103 99
SoapException returned by proxy classes Unlike the Java API, which returns AuthenticationFault and AdminServiceFault when an error occurs, the Authentication and Administration.NET proxy classes return a SoapException instead. The SoapException contains errormessage, ErrorCode string, internalcode, and id. Your application can retrieve this information from the returned SoapException using the XML retrieval methods. The following example provides coding to retrieve the error information from the SoapException and then output to the screen: try { an_api_service_that_fails.that_fails(); } catch (System.Web.Services.Protocols.SoapException soapexception) { Console.WriteLine("Error occurred: " + soapexception.message); System.Xml.XmlNode detailnode = soapexception.detail; System.Xml.XmlNodeList nodelist = detailnode.childnodes; for (int i = 0; nodelist!= null && i < nodelist.count; i++) { System.Xml.XmlNode xmlnode = nodelist.item(i); Console.Write(xmlNode.Name + ": "); Console.WriteLine(xmlNode.InnerText); } } 100 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
ErrorCode class ErrorCode is a container class for an enumerated set of error codes that enable the client to perform cleaner error checking. Many internal error codes may result in a more general external error codes that the client can use for general error detection. See the Entrust IdentityGuard Error messages file for a description of errors. Using the ErrorCode information to detect errors The SoapException returned by the.net proxy classes contain the ErrorCode information. The following is an example of string comparison of error code: try { AuthenticateResponse resp = binding.authenticate(callparms); } catch (System.Web.Services.Protocols.SoapException soapexception) { System.Xml.XmlNode detailnode = soapexception.detail; System.Xml.XmlNodeList nodelist = detailnode.childnodes; for (int i = 0; nodelist!= null && i < nodelist.count; i++) { System.Xml.XmlNode xmlnode = nodelist.item(i); if (xmlnode.name.compareto("errorcode") == 0 { if (xmlnode.innertext.compareto("invalid_response") == 0) { // Do something } else if (xmlnode.innertext.compareto("no_active_cards") == 0) { // Do something else } else { API exceptions 101
} } } } // Do something more 102 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
Authentication warning faults Warning faults are AuthenticationFault objects returned as part of an AuthenticateResponse. Your application can retrieve the WarningFault property. A warning fault does not stop processing or cause an authentication to fail, because the client application supplied a correct response to a challenge. Nevertheless, the client application receives a report of the error and the system logs it to further diagnose the situation if necessary. All exceptions relating to authentication secret and shared secret functions are returned as warning faults. Ensure that your client application is aware that a failure occurred while setting secret information; however, it is unlikely that the failure results in an authentication failure. Only failures that occur after a successful authentication are returned as a warning fault. Any failure that occurs before authentication results in an immediate authentication failure being returned to the client. Administration Password Change When a login operation fails because the administrator requires a password change, the Administration proxy class returns a SoapException containing the message A password change is required. This following is an example of handling the Administration password change request: try { LoginParms loginparms = new LoginParms(); loginparms.adminid = admin_id; loginparms.password = admin_pswd; loginparms.response = resps; LoginCallParms callparms = new LoginCallParms(); callparms.parms = loginparms; LoginResult loginresult = binding.login(callparms); if (loginresult.state.equals(loginstate.complete)) { log("administrator " + admin_id + " has been successfully" + " logged in to Admin Service."); } API exceptions 103
else if (loginresult.state.equals(loginstate.need_second_factor)) { log("second factor authentication required:"); ChallengeSet challset = loginresult.challengeset; dumpchallenges(challset.challenge); } else { log("admin " + admin_id + " login failed."); } } catch (SoapException soapexception) { if (soapexception.message.contains("a password change is required")) { // code to change admin password } else { // code to handle the soap exception 104 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
Index - A B C D E F G H I J K L M N O P Q R S T U V W X Y Z-.NET proxy classes 101 A activate card 84 ActiveX 68 Administration activate card 84 cards 93, 94 create cards 84 knowledge-based questions 90 one-time password 87 preproduced cards 86 retrieve one-time password 87 service binding object 80 temporary PIN 89 token 88 unlock users 91 Administration commands cardcreate 32, 86 carddelete 32 cardexport 32 cardget 32 cardlist 32 cardset 32 challengeauthenticate 32 challengeget 33 groupget 33 grouplist 33 tokendelete 33 tokenget 33 tokenlist 33 tokenset 33 usercardcreate 33, 84 usercarddelete 34 usercardexport 34 usercardget 34 usercardlist 34 usercardset 35 usercardunassign 35 usercreate 35 userdelete 35 userget 35 userlist 35 userotpcreate 36 userotpdelete 36 userotpget 36 userpincreate 36 userpindelete 36 userpinget 36 userpinset 36 userset 36 usertokenassign 37 usertokenauthenticate 37 usertokendelete 37 usertokenget 37 usertokenlist 37 usertokenset 38 usertokenunassign 38 AdminService_Service 44 AdminServiceFault 100 API overview Administration API 12, 80 V2 13 Authentication API 12 Authentication V2 API 13 V1 and V2 services 12 Authentication first-factor 48 generic 54 grid 52, 54, 61 knowledge-based 61 knowledge-based questions 52, 72 layered 77 machine 69, 70, 77 multifactor 87 one-step (anonymous) 48 one-time password 52, 55, 61 questions and answers 52, 61 second-factor 48, 52 temporary PIN 52 token 52, 55, 61 two-step grid 52 Authentication commands 105
- A B C D E F G H I J K L M N O P Q R S T U V W X Y Z- authenticate 19, 52 authenticateanonymouschallenge 20, 49 authenticategenericchallenge 21 authenticatewithsharedsecrets 22 checkmachineregistration 23, 62 debugoff 19 debugon 19 exit 19 Get 65, 69 getallowedauthenticationtypes 24 getallowedauthenticationtypesforgroup 25 getanonymouschallenge 26, 43, 49 getanonymouschallengeforgroup 43 getchallenge 26, 43, 52 getgenericchallenge 27, 43, 87 help 19 registermachine 28, 62 AuthenticationFault 100 AuthenticationService 46 B binding object creating 43, 44 C CallParms 46 cards check inventory 94 create 93 distribute 93 manufacture 93 create card 84 Customer support 9 E Entrust IdentityGuard replica servers 42 Entrust IdentityGuard repository 82 ErrorCode 101 F fingerprint machine fingerprint 68 first-factor authentication 48 Flash MX 69, 70 G generic authentication 54 code sample 57 grid 54 knowledge-based questions 55 one-time password 55 token 55 Getting help Technical Support 9 grid authenticate 52, 61 J Java 68 Java API 100 K keystore 41 knowledge-based questions 72 authenticate 52, 61 set up 90 M machine authentication 69, 77 nonce 70 machine nonce 69 multifactor authentication 87 Mutual authentication grid 71 knowledge-based questions 72 token 72 N namespace 45 nonce machine 69 optional sequence 69 106 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0
- A B C D E F G H I J K L M N O P Q R S T U V W X Y Z- O one-step (anonymous) authentication 48 one-time password 55, 87 authenticate 52, 61 create 87 retrieve 87 optional application data 70 optional sequence nonce 69 P preproduced cards 86 assign 86 create 86 Professional Services 10 R Radius implementation 56 replay grid values 71 image and message 72 serial number 71, 73 replica servers 42 S second-factor authentication 48, 52 serial number 71, 73 serial numbers 72 replay 71, 72 service binding object 80 shared secret 103 SOAP 43 SoapException 100 string conversion 50 T Technical Support 9 temporary PIN assign 89 authenticate 52 create 89 modify 89 token assign 88 authenticate 52, 61 check inventory 94 modify 88 Tomcat 41 two-step grid authentication 52 typographic conventions 6 U unlock users 91 W warning faults 103 WarningFault property 103 Web services 12 WSDL files 13 X XML 100 Index 107
- A B C D E F G H I J K L M N O P Q R S T U V W X Y Z- 108 Entrust IdentityGuard 8.1 Programming Guide for the.net Framework Document issue: 2.0