Configuring LDAP client certificate authentication in IAG

Article
02/10/2010

Applies To: Intelligent Application Gateway (IAG)

Client certificate authentication schemes require users to authenticate by supplying a client certificate, which is installed on their local disks. No login information--user name and password--is required for the authentication process. Client certificate authentication can only be used for Whale Communications Intelligent Application Gateway (IAG) 2007 sites published over an HTTPS connection.

The LDAP client certificate authentication scheme supported by IAG operates with one or two LDAP authentication servers. LDAP authentication servers keep information about users in directories, including authentication and authorization information such as user properties and access rights. When the trunk is configured to apply the LDAP client certificate authentication scheme, and a connection request arrives to IAG, the authentication scheme goes through the following stages:

Authenticate the user: a user requesting to connect is prompted by the browser to select a client certificate. When the user selects a certificate, IAG verifies the validity of the certificate and the identity of the user.
Authorize the user: once the certificate is validated and the user is recognized, IAG User Manager checks with the LDAP authentication server to verify that the user is authorized to access the Application server.

Each registered user in the LDAP server is assigned a Distinguished Name (DN), which includes a hierarchical address. For example: organization\organizational_unit\username .

When the LDAP client certificate scheme operates with two LDAP authentication servers, if the primary LDAP server fails, the User Manager accesses the alternate LDAP server.

LDAP client certificate authentication flow

The following figure illustrates the authentication process users go through when the LDAP client certificate authentication scheme is implemented with one authentication server.

LDAP client certificate Authentication Flow

26bd513b-625b-4eda-b2bd-9aafc0cf6cd8

Configuring IAG

To configure the LDAP client certificate authentication scheme

In the IAG Configuration console, access the Authentication and User/Group Servers dialog box, where you define an LDAP server that will be used for this scheme. LDAP servers include the following: Active Directory; Netscape LDAP Server; Notes Directory; Novell Directory.
Copy the file site_secure_cert.inc from:

...\Whale-Com\e-Gap\von\InternalSite\samples

To the following custom folder; if it does not exist, create it:

...\Whale-Com\e-Gap\von\InternalSite\inc\CustomUpdate
Rename the file as follows:

<Trunk_Name>1cert.inc

For example:

For a trunk named WhalePortal, name the file:

WhalePortal1cert.inc

Tip

The digit 1, which is part of the file name, indicates that this is an HTTPS trunk.

By default, this file checks the user's email address in order to verify the certificate. You can edit the file to change this functionality or add other functions, if required.

Important

cert.inc must set the number of parameters that are checked.

For example : in the default settings, where one parameter (email) is checked, cert.inc sets the following:
Dim subject_array(0)
If you edit the file, make sure you change this function accordingly.
From the samples folder you accessed in step 2, copy the file site_secure_login_for_cert.inc to the CustomUpdate folder. Rename the file as follows:

<Trunk_Name>1login.inc
From the samples folder, copy the file site_secure_validate_for_cert.inc to the CustomUpdate folder. Rename the file as follows:

<Trunk_Name>1validate.inc
In the validate.inc file you copied in step 5, enter the name of the authentication server that you defined in step 1, in the line:

Session("repository1") = ""

For example:

If you named the server "LDAPCert", this line should read:

Session("repository1") = "LDAPCert"
From the samples folder, copy the file repository_for_cert.inc to the CustomUpdate folder. Rename the file as follows:

<Server_Name>.inc

Where < Server_Name> is the name of the authentication server you defined in step 1, in the Name field of the Add Server dialog box.

For example:

If you named the server "LDAPCert", name the file LDAPCert.inc

Note

If you want to enable Kerberos constrained delegation on any application that belongs to this trunk, open this file, and make the following modification:

KCDAuthentication_on = true

If you have changed the default functionality of the cert.inc file, in step 3, make the corresponding changes in the file you copied in step 7, as well. Otherwise, you do not need to edit this file.
- The file includes lines that are commented out, which can be used to implement one function. Search for param_x , un-comment the line, and edit the text as required.
- You need to repeat the above for each function you add.
- To remove the function that checks the email address, search for param_email and comment out the relevant lines.

Configuring the LDAP authentication server or servers

The system administrator has to register all the users in the LDAP server, and assign each user a Distinguished Name (DN), which includes a hierarchical address.

For example: organization\organizational_unit\username

The LDAP server or servers used in the scheme have to be configured to allow anonymous search access to the folder or folders where users are registered.

Preparing the client endpoint browser

In order to use the client certificate authentication scheme, end-users have to install a client certificate on the browser that is used to access the site. The Certification Authority (CA) that signs the client certificate must be trusted by both the endpoint browser and the IIS on IAG.