How to configure the SSO IIS Web Agent to support virtual web-servers in the same IIS installation?

Document ID : KB000055703
Last Modified Date : 14/02/2018
Show Technical Document Details


In this document we describe how to configure the SSO IIS Web Agent to support virtual web-servers in the same IIS installation. The definition of the term virtual web servers, as used in this document, is the ability for IIS to allow the use of different web servers in the same IIS installation. The Web Server administrator should be able to configure each virtual web server to have different SSO IIS Web Agent authorization and authentication rules by defining separate configuration settings for each virtual web server.

IIS support for virtual web-servers

IIS web-servers can be defined to be virtual and can be configured using one of the following three methods:-

  • Port-Based routing
  • IP-Based routing
  • Host-Header routing

Please refer to the following Microsoft URL for further information:-

The SSO Web Agent relies on HTTP "HTTP_HOST" header values to differentiate between different virtual web-sites. To explain this in more detail, let's consider the following example and consider each of the three methods:-

Port-Based routing

Suppose we have configured a IIS virtual web-site to run on port 81. The HTTP_HOST header will be "<hostname>:81"

Figure 1

IP-Based routing

Suppose we have configured a virtual web-site to run on a different IP address, the HTTP_HOST header contains the IP address that the web-site is using.

Figure 2

Host-Header routing

Suppose we have configured a virtual web-site to have different headers, the HTTP_HOST header contains the information entered in the "Host header name" of the web-site setting

Figure 3

Installing the IIS Web Agent

The IIS Web Agent installer configures a default web-site running under IIS. In order to support virtual IIS web servers, you will need to configure the SSO IIS Web Agent after installation as follows. Please note that it is not mandatory that the default web-site should be running in order to support the web-agent on the virtual web-site.

Post installation

  1. Issue 'inetmgr" from Start->Run.

  • Expand *<host_name> folder

  • Select "MyVirtualSite". Right click "New->Virtual Directory'"

    Figure 4

  • Define a Virtual directory named "webac" in the 'Virtual Directory Alias' text field

    Figure 5

  • Enter the full path to the SSO IIS Web Agent "webac" folder in the 'Web Site Content Directory' text field.(e.g. C:\Program Files\CA\eTrustWebAccessControl\Webagent\webac)

    Figure 6

  • Set the appropriate directory permissions

    Figure 7

  • Click finish

    Figure 8

  • If you want to support NTLM authentication, browse the "webac" virtual directory, select the "ntlm" folder and show its properties. Go to the "Directory Security->Anonymous access and authentication control" tab and click on the Edit button. Deselect the "Anonymous access" checkbox and select "Integrated Windows Authentication" as in the following screenshot.

    Figure 9

  • Create a new Web Agent for the virtual web-server in the SSO Policy server. For example, create "virtual_wa" agent for the virtual web-site

    Figure 10

  • Create "/webac/sync.htm" and other protected resources, as appropriate, under the web-agent

    Figure 11

  • For IIS6, add "SSOExtII6.dll" extension for your virtual web-site. The SSOExtIIS6.dll is located under the SSO IIS Web Agent installation folder. Go to "MyVirtualSite-> Properties->Home Directory->Application Settings->Configuration->Wildcard applications maps". Click on the Insert button and enter the path to the "SSOExtIIS6.dll"

    Figure 12

  • Press "OK"

    Figure 13
  • Configuring the webagent.ini

    As discussed, the SSO IIS Web Agent distinguishes virtual web-sites based on the HTTP_HOST header value. As an example, let's say that your default web-site is http://mywebsite and you've configured to run your virtual web-site under port 81. The HTTP_HOST header for the virtual website will be "mywebsite:81".

    Open the webagent.ini file from the installed SSO IIS Web Agent directory and perform the following steps

    1. In the [Main] section, add a virtual server name.

      Figure 14

  • Make a copy of the following already existing sections




    [<auth. authentication_method_name>. Default]

    e.g. "[auth.SSO.Default]"

  • Modify the section's name to append the new virtual server name (mywebsite:81)




    [auth. <authentication_method_name>. mywebsite:81]

  • In the new [Config.mywebsite:81] section change the following

    Figure 15

    For the PrimaryWebServer attribute, if you have the configured any primary web server then also include that here, otherwise provide the same name as specified in the WebServerName field.

    The AgentName attribute is the name of the web-agent resource that has been created in the Policy server.

  • If you need to protect resources using the NTLM or X509 authentication methods, then follow these additional steps below

    In the new [auth.X509. mywebsite:81] section modify the setting

    Secure =https:// mywebsite/webac/x509 to https:// mywebsite:81/webac/x509

  • In the new [auth.NTLM.mywebsite:81] section modify the setting

    NTLMPath =http://mywebsite/webac/ntlm to http://mywebsite:81/webac/nt

    Note: The above mentioned steps are the minimal configuration steps needed in the webagent.ini file to make the integration work. You can modify other settings in the [Config.mywebsite:81] or any other sections according to your needs.

    If your web-site is configured to support both http://mywebsite:81 and, you have to add two entries in the webagent.ini namely "mywebsite:81" and "". Follow the above step 1 to step 6