Using the Web Server Integration Modules

The SilverStream Application Server provides Web Server Integration modules for Microsoft's IIS and Netscape's iPlanet Enterprise servers that run on Windows NT, Windows 2000, and Solaris. The SilverStream Web Server Integration (WSI) modules allow you to integrate a SilverStream Application Server (Version 3.5 and above) into your existing IIS or iPlanet Web server framework. The WSIs support Versions 4.0 and above of IIS and iPlanet servers.

URL requests sent to the Web server are forwarded by the WSI module to the SilverStream server. The WSI then returns the URL reply from the SilverStream server to the requesting browser.

This chapter describes how to integrate the SilverStream server with your existing Web servers using the SilverStream WSI modules. It includes the following topics:

NOTE   The WSI modules for IIS and iPlanet supersede SilverStream's SilverJunction and address limitations found in SilverJunction. You should use the WSI modules instead of SilverJunction to integrate a SilverStream server with your Web server.

About the WSI modules    Top of page

The WSIs extend the URL name space of your existing Web server directory structure by allowing you to include dynamic content in your existing Web applications. URL masking means users cannot tell when they switch between static content on the Web server and dynamic content on the application server.

How the WSI modules work   Top of page

With a WSI module, the SilverStream server services a portion of your Web server's URL name space. The SilverStream WSI module services requests for specified URLs to the Web server by opening HTTP connections to a SilverStream server and forwarding the requests to it. The WSI then returns the response. You specify which URLs the WSI module will forward using a configuration file that the WSI reads when the Web server starts.

To improve response time, the WSI module will reuse socket connections between itself and the SilverStream server. The WSI maintains a connection pool to the SilverStream server that reuses these connections as needed.

With the WSI module, there is no direct communication between the browser and the SilverStream server: all calls pass through the WSI.

WSI module examples   Top of page

The following examples show how a WSI might be used in a corporate network. In each example, the WSI module forwards a client request for http://www.ABC.com/daytime/schedule.html to http://sssw.ABC.com/daytime/schedule.html (even though the URL address of the client would not change). Together the four examples show ways to reliably handle an increasing volume of requests.

WSI with one SilverStream server

In this simple scenario, the WSI forwards requests from a Web server to a single SilverStream server.

NOTE   There are many ways to set up your environment. For example, in each of the following figures, you could position your database behind the inner firewall. Positioning the corporate database outside the DMZ (the area between the two firewalls) helps protect your database.

WSI module with several SilverStream servers

Here the WSI forwards requests from a single Web server to a cluster of SilverStream servers. This approach increases database access and reduces the risk of the application server becoming a single point of failure.

Multiple Web servers and SilverStream application servers

Here the WSI forwards requests from multiple Web servers to multiple SilverStream servers. This approach is more reliable for handling a large volume of requests (several Web servers have been added to the front end).

Hardware dispatcher added for load balancing

Here again the WSI forwards requests from multiple Web servers to multiple SilverStream servers. Now the largest volume of requests can be more reliably processed--because of multiple servers at the front and back ends and of the addition of dispatcher load balancing at both ends.

Using a WSI in a cluster   Top of page

Because the SilverStream Dispatcher load balances server clusters by redirecting URLs instead of masking them, the SilverStream WSI modules do not currently work with the SilverStream Dispatcher. If the SilverStream server is running as part of a cluster, the WSI requires a third-party hardware dispatcher to securely redirect requests to appropriate SilverStream servers through one port in the firewall.

NOTE   EJBs will not use the same firewall port as the WSIs. EJBs use the IIOP protocol, controlled by the JBroker ORB. The default name service port for EJBs is 54890. For more information, see the chapter on using EJBs with SilverStream applications in the Programmer's Guide.

Planning your WSI installation   Top of page

The WSI module uses a DLL for Windows operating systems and a shared library file for Solaris. Installing the WSI module is a two-part process: installing the DLL or shared library and then enabling the WSI. Before using the WSIs, follow the IIS and/or iPlanet instructions in the following sections:

The WSI module instructions assume that you have already installed the SilverStream server.

The WSI configuration file   Top of page

The AgWSI.conf file is a text file. The following file shows the default configuration for both the WSI for IIS and the WSI for iPlanet. The settings in bold are variables you will need to enter during the procedure on Installing and configuring the WSI module.

  # ------------------------------------------ 
  # SilverStream WSI configuration file 
  # ------------------------------------------ 
  SilverServer.host=mysssw.myco.com 
  SilverServer.http.port=80 
  SilverServer.https.port=443 
  WSI.root.dir=/agisapi 
  SilverServer.urls=/mydb 
  # 
  # Optional: Additional URLS 
  SilverServer.urls=/SilverMaster 
  SilverServer.urls=/SilverStream 
  SilverServer.urls=/Pages=/mydb/SilverStream/Pages 
  # 
  # Optional Settings: 
  WSI.debug=0 
  WSI.error.url=/myerror.html 
  WSI.auth.NTLM.remove=false 
  Connection.http.max=100 
  Connection.https.max=100 
  Connection.idle.time=25 

Configuration file settings   Top of page

The following section describes each configuration setting, provides defaults and examples, and lists which settings are required.

SilverServer.host

Required.

SilverServer.host is the name of the destination SilverStream server that services URL requests from the Web server.

Example:

  SilverServer.host=mysssw.myco.com 

SilverServer.http.port

Required if the SilverStream server HTTP port is not using the default port number (80).

SilverServer.http.port is the nonsecure port of the destination SilverStream server.

Default:

  SilverServer.http.port=80 

SilverServer.https.port

Required if the SilverStream server HTTPS port is not using the default port number (443).

SilverServer.https.port is the secure port of the destination SilverStream server.

Default:

  SilverServer.https.port=443 

SilverServer.urls

Required.

SilverServer.urls specifies which URLs will be forwarded to the SilverStream server. You must specify a new setting for each URL root you want forwarded to the SilverStream server.

There are two formats: Simple URL forwarding and URL forwarding with translation (masking).

Simple URL forwarding

Format:

  SilverServer.urls=<Root_URL_to_Forward> 

Examples:

  SilverServer.urls=/SilverStream 
  SilverServer.urls=/myDb 

In the preceding example, all URLs that begin with either /SilverStream or /myDB will be forwarded to the SilverStream server. This includes:

  http://myWebServer/SilverStream/Sessions 
  http://myWebServer/SilverStream/Pages 
  http://myWebServer/myDb/SilverStream/Pages/MyPage.html 

To forward all URLs to the SilverStream server specify the following:

  SilverServer.urls=/ 

URL forwarding with translation (masking)

Format:

  SilverServer.urls=<URL_root_at_Web_server>=<translated_URL_root> 

Example:

  SilverServer.urls=/Pages=/myDb/SilverStream/Pages 

The first URL will be forwarded to the SilverStream server after the second URL is substituted for it. In this example, all URLs from the Web server that begin with /Pages will be forwarded to the SilverStream server with myDb/SilverStream/Pages substituted for /Pages. The URL sent to Web server as:

  http://myWebServer/Pages/MyPage.html  

is forwarded to the SilverStream server as:

  http://mySilverServer/myDb/SilverStream/Pages/MyPage.html 

Connection.http.max

Optional.

Connection.http.max is the maximum number of concurrent nonsecure HTTP connections between the WSI and the SilverStream server.

Users will be notified if the connection pooling limit is exceeded if you have created and specified a WSI.error.url file. The WSI reuses socket connections between itself and the SilverStream server.

Default:

  Connection.http.max=100 

Connection.https.max

Optional.

Connection.https.max is the maximum number of concurrent secure HTTPS connections between the WSI and the SilverStream server.

If you have created and specified a WSI.error.url file, users will be notified if the connection pooling limit is exceeded. The WSI reuses socket connections between itself and the SilverStream server.

Default:

  Connection.https.max=100 

Connection.idle.time

Optional.

Connection.idle.time specifies how often (in minutes) the WSI scans the connection pools for idle connections.

Default:

  Connection.idle.time=25 

WSI.root.dir

Required for IIS only.

WSI.root.dir is the WSI virtual directory name and where the WSI module runs from. Since the WSI for IIS is both a filter and an extension, you need to specify the URL for the WSI in the IIS Web root (/wwwroot) directory structure.

You need to install the WSI module for IIS in a directory that is visible from the IIS Web root directory. If you install the WSI in a physical directory beneath the Web root (for example, C:\Inetpub\wwwroot\agisapi) the WSI is automatically visible from within IIS. However, if you install the WSI module in a directory that is outside the IIS root directory, you must create a virtual directory using the MMC so the WSI appears in the IIS directory. You must also set the WSI.root.dir relative to the Web server root directory.

Examples:

Default:

  WSI.root.dir=/agISAPI 

WSI.debug

Optional.

WSI.debug specifies whether WSI logging is on (1) or off (0). The WSI logs to the AgWSI.log file, which is stored in your WSI module directory.

To log the URLs arriving at the destination server, use the SMC to configure your SilverStream server debug value to 1 or 2. For more information, see the section on low-level debugging in the Administrator's Guide.

Default:

  WSI.debug=0 

WSI.error.url

Optional.

WSI.error.url specifies a customized error page that users will see if a WSI connection error occurs. Users will see a generic browser notification when the WSI module cannot connect to the SilverStream server unless you create and then specify a WSI error URL.

It is a good idea to create an HTML file that tells users about the problem and advises them to retry the URL connection later.

Specify the WSI error file name and a directory location on your Web server. You need to store your error page file in your Web server's directory structure, since the WSI redirects the browser to this page on your Web server.

Default:

  WSI.error.url=\myerror.html 

WSI.auth.NTLM.remove

Optional for IIS only.

Set WSI.auth.NTLM.remove to true if NT authentication is enabled for your IIS directories. Setting this setting to true removes the NTLM authentication headers so users' requests can be successfully forwarded to the SilverStream server. For more information, see Using IIS NTLM authentication with the WSI module.

Default:

  WSI.auth.NTLM.remove=false 

WSI.auth.user

Optional.

When the WSI.auth.user is specified, the WSI module intercepts the authentication headers that will be forwarded to the SilverStream server and replaces them with credentials of a single known SilverStream user; then it adds HTTP authentication headers to every request that it forwards to the SilverStream server. Any existing authentication headers on incoming requests to WSI will be replaced by the authentication setting.

To protect the security of the authentication settings, the user name and password are not stored in clear text in the AgWSI.conf file. You must run the AgWSIUser utility to add this authentication setting to your configuration file. This utility will encrypt the user name and password in a way that the WSI can read. For more information on running the utility, see The AgWSIUser utility.

The authentication setting can be used:

Installing and configuring the WSI module   Top of page

The WSI module needs to be on the same machine as the Web server. Also, the WSI configuration file (AgWSI.conf) must be in the same directory as the WSI module, since the WSI will read the configuration file when the Web server starts.

To run WSI modules and maintain separate log files for both IIS and iPlanet, you should create separate directories to store the WSI DLL and the shared library file with an associated AgWSI.conf file. If you are not running both IIS and iPlanet WSI modules on the same machine, you do not need to create separate directories.

You can run the SilverStream server remotely (you do not need to run the SilverStream server from the Web server machine).

The WSI modules for IIS and iPlanet both use the AgWSI.conf file to set configuration settings. The following procedure describes only the required settings. See The WSI configuration file for a complete list of WSI configuration settings.

To install and configure the WSI module:

  1. Optional. Create a directory for the SilverStream WSI module(s). For example:

  2. Optional. Copy the following files from the bin subdirectory of the SilverStream installation directory:

  3. Open the AgWSI.conf file and edit the required values as described in the following steps. See The WSI configuration file for a complete list that includes the optional configuration settings.

  4. Specify a SilverStream server host.

    The SilverServer.host is the name of the destination SilverStream server that services URL requests from the Web server.

  5. Specify a SilverServer port number for one of the following:

  6. Specify the WSI root directory you created in step 1. This value is required for IIS only. This value is not needed for the WSI for iPlanet.

    The WSI.root.dir is the directory the WSI DLL runs from.

  7. If needed for the WSI module for IIS, specify the setting described in WSI.auth.NTLM.remove.

  8. Save the AgWSI.conf file to your WSI root directory.

  9. Configure your Web server to use the WSI by following one of these procedures:

Enabling the WSI module for IIS for Windows   Top of page

This section describes how to enable the WSI for Microsoft IIS. This procedure assumes that you have installed the SilverStream server and edited the AgWSI.conf file. Once enabled, the WSI for IIS will look for the configuration file in the location you specified in Installing and configuring the WSI module.

To enable the WSI module for IIS:

  1. Make sure your edited AgWSI.conf file is in your WSI root directory (such as C: \AgISAPI) as described in step 2 under Installing and configuring the WSI module.

  2. Start the World Wide Web Publishing Service and open the Internet Service Manager.

        For more information on Microsoft Web server configuration, see your Microsoft documentation.

  3. From the Microsoft Management Console (MMC), right-click on the Default Web Site.

  4. Select New and then Virtual Directory. The New Virtual Directory Wizard appears.

    If your WSI module does not use a virtual directory, do the following:

  5. From the New Virtual Directory Wizard, enter a virtual directory name (such as AgISAPI) and click Next.

    IIS will use this alias to access the directory that the WSI.DLL runs from. This name should match the name used in the AgWSI.conf file to define the WSI.root.dir setting as described in The WSI configuration file.

  6. Enter the physical path of the WSI directory (such as C:\AgISAPI) and click Next.

    The WSI directory is where you installed the SilverStream WSI module.

  7. Disable all permission access check boxes except Allow Execute Access (includes Script Access), which should be selected.

  8. Click Finish.

  9. Verify that the directory you just created appears in the list of Web server directories beneath the Default Web Site in the left pane of the MMC.

  10. Right-click Default Web Site and select Properties.

  11. Select the ISAPI Filters tab and click Add.

  12. In the Filter Properties dialog, enter the WSI Filter Name.

  13. In the Executable field, specify the absolute path to the agisapif.dll. For example, C:\AgISAPI\agisapif.dll.

  14. Click OK to close the Filter Properties dialog.

  15. Click Apply in the Default Web Site Properties dialog.

    The WSI module for IIS should appear in the Filter Name list. A green arrow to the left of the WSI Filter Name indicates whether (or not) the filter is enabled.

  16. Click OK to close the Default Web Site's Properties dialog.

  17. Close the Internet Service Manager.

  18. Stop and then restart the World Wide Web Publishing Service using the NT Control Panel.

  19. To verify that the WSI module is working, start the browser and connect to an URL that you specified in the AgWSI.conf file.

    When the WSI module starts successfully, it starts generating the AgWSI.log file.

    Here is a sample AgWSI log file for WSI module for IIS:

      # -------------------------------------------------- 
      # SilverStream WSI Configuration 
      # -------------------------------------------------- 
       Started at               : Tue Oct 2 14:10:19 2000 
       Root Directory           : /sssw/ 
       Host                     : richg.silverstream.com 
       Ports                    : 8080 445 
       Maximum HTTP Connection  : 8 
       Maximum HTTPS Connection : 8 
       Connection Idle Time     : 25 minutes. 
       Redirect URL on Error    : /wsi/myerror.html 
       Authentication NTLM      : true 
      ---------------------------------------------------- 
    
  20. If the WSI does not start successfully, an error message appears.

Enabling the WSI module for iPlanet for Windows or Solaris   Top of page

This section describes how to enable the WSI module for Netscape iPlanet. The WSI module for Netscape Web servers can run on Windows NT, Windows 2000, or Solaris.

This procedure assumes that you have installed the SilverStream server and edited the AgWSI.conf file as described on Installing and configuring the WSI module. By default, the WSI module for iPlanet (called agnsapi.dll for Windows and libagnsapi.so for Solaris) is installed in the SilverStream\bin directory.

In order to enable the WSI module on a Netscape server, you need to edit its obj.conf file and add four lines of text that match the settings in the AgWSI.conf file. The WSI for iPlanet determines the location of the AgWSI.conf file by the initialization parameters that you specify in the obj.conf file when you enable the WSI.

    For more information, see WSI for iPlanet sample obj.conf file.

To enable the WSI module for iPlanet:

  1. Open your Netscape Web server obj.conf file.

  2. At the end of the Init section, add the first of two lines of text. Line 1 sets the initialization function that ensures that the WSI module is loaded and its functionality is made available to the server. The text you enter depends on whether you are running Windows or Solaris.

    If you are running the WSI module for iPlanet on Windows, enter agnsapi.dll as the name of the WSI module. Enter libagnsapi.so for the WSI module name for Solaris. When you specify the WSI_module-name enter the path to the SilverStream install directory for your system.

    For example shlib="C:\AgNSAPI\AgNSAPI.dll" or

    shlib="/opt/AgNSAPI/AgNSAPI.so"

      Init fn="load-modules" shlib="WSI_module_name" funcs="AgNSAPIInit,AgNSAPINameTrans,AgNSAPIService" 
    
  3. At the end of the Init section, add one of the following lines of text which will initialize the WSI module when the iPlanet server starts. The text you enter for Line 2 depends on whether you are running Windows or Solaris.

    For Windows, enter:

      Init fn="AgNSAPIInit" LateInit="yes" 
    

    For Solaris, enter:

      Init fn="AgNSAPIInit"  LateInit=yes agroot="opt/SilverStreamDir/bin" 
    

    In the preceding Solaris example, replace SilverStreamDir with your SilverStream install directory.

  4. At the beginning of the NameTrans section, add the following:

      NameTrans fn="AgNSAPINameTrans" 
      This name translation command submits URLs to the SilverStream server for servicing and determines whether or not the requested URL gets translated. 
    
  5. Optional. If you are using enCommerce, add the following instead of the NameTrans text shown in step 4:

      NameTrans fn="AgNSAPINameTrans" agroot=AnyPath 
    

    You only need to set the agroot portion of the NameTrans parameter if you are using the enCommerce getAccess security software.

    The getAccess authentication service requires that a URL be mapped to a physical path in order to secure the URL request. The WSI module will use the path you specify to provide the physical path that getAccess requires. Because the WSI does not check for the existence or the validity of the path, you can specify any path. The WSI will set a physical path for URLs that it will service relative to the root path that you specify.

    For example, if you enter

      agroot=/opt/silverstream 
    

    in the preceding NameTrans function, an incoming URL such as

      http://server/MyDB/SilverStream/Pages/xyz.html  
    

    would be mapped by the WSI to /opt/SilverStream/MyDB/SilverStream/Pages/xyz.html.

    For more information, see enCommerce getAccess integration.

  6. At the beginning of the Service section (for both Windows and Solaris), add the following line:

      Service fn="AgNSAPIService" 
    

    This service command forwards each request to the SilverStream server and returns (echoes) a response to each incoming request.

  7. Stop and restart the Netscape Web server to verify that the WSI module was loaded correctly.

    When the WSI is running with a Netscape Web server, its configuration file can reside anywhere, as long as the file's location is specified in the Init section of the obj.conf file under Init fn=load-modules.

WSI for iPlanet sample obj.conf file   Top of page

The following is an example of a portion of an obj.conf file that specifies the WSI module running on Windows for iPlanet. The WSI entries that you must add are shown in bold.

The sample obj.conf file would also work for a WSI module for Solaris except for the first Init fn entry. Also, if your WSI module was integrated with enCommerce, you would need to enter a different NameTrans entry as described in the procedure on Enabling the WSI module for iPlanet for Windows or Solaris.

    For more information about Netscape Web Server configuration, see your Netscape documentation.

  # Use only forward slashes in pathnames--backslashes can cause problems. 
   
  Init fn="load-modules" shlib="c:/SilverStream/bin/AgNSAPI.dll" funcs="AgNSAPIInit,AgNSAPINameTrans,AgNSAPIService" 
  Init fn="NSServletEarlyInit" EarlyInit=yes 
  Init fn="NSServletLateInit"  LateInit=yes 
  Init fn="AgNSAPIInit" LateInit="yes" 
   
  <Object name=default> 
  NameTrans fn="NSServletNameTrans" name="servlet" 
  NameTrans fn="pfx2dir" from="/servlet" dir="D:/Netscape/Server4/docs/servlet" name="ServletByExt" 
  NameTrans fn=pfx2dir from=/ns-icons dir="D:/Netscape/Server4/ns-icons" name="es-internal" 
  NameTrans fn=pfx2dir from=/mc-icons dir="D:/Netscape/Server4/ns-icons" name="es-internal" 
  NameTrans fn="pfx2dir" from="/help" dir="D:/Netscape/Server4/manual/https/ug" name="es-internal" 
  NameTrans fn="pfx2dir" from="/manual" dir="D:/Netscape/Server4/manual/https"  
  NameTrans fn="AgNSAPINameTrans" 
  name="es-internal" 
  NameTrans fn=document-root root="D:/Netscape/Server4/docs" 
  PathCheck fn=nt-uri-clean 
  PathCheck fn="check-acl" acl="default" 
  PathCheck fn=find-pathinfo 
  PathCheck fn=find-index index-names="index.html,home.html" 
  ObjectType fn=type-by-extension 
  ObjectType fn=force-type type=text/plain 
  Service method=(GET|HEAD) type=magnus-internal/imagemap fn=imagemap 
  Service method=(GET|HEAD) type=magnus-internal/directory fn=index-common 
  Service method=(GET|HEAD|POST) type=*~magnus-internal/* fn=send-file 
  Service fn="AgNSAPIService" 
  AddLog fn=flex-log name="access" 
  </Object> 

About connection pooling   Top of page

The WSI module uses connection pooling to improve response time. Instead of creating and maintaining a connection to the SilverStream Application Server for each client connected to the Web server, the WSI reuses its connections to the SilverStream server for multiple client connections. The WSI will open new connections to the SilverStream server as needed for concurrent request processing. The number of concurrent connections is limited by the Connection.http.max and the Connection.https.max settings in the AgWSIconf file.

WSI maintains separate connection pools for HTTP and HTTPS protocols. To ensure that these connection pools do not use up too many system resources, the WSI periodically scans the pools and closes any connections that has not been used between scan cycles.

Connections have the following states:

The WSI periodically runs a background thread to check the connection pools for inactive and idle connections to see which connections are connected but not busy. The WSI thread marks all inactive threads as idle and closes any connection that are already marked as idle. When a connection is marked as idle, that connection is closed based on the connection idle time limit you set (or the default of 25 minutes). The interval starts when the WSI module is loaded, not when the connection was created.

A connection needs to remain inactive for two scan cycles before it is disconnected. For example, if the specified connection idle time limit is set to 15 minutes, an inactive connection will be disconnected sometime between 15 and 30 minutes after becoming inactive, because the WSI may not start pooling until the middle of an existing interval. If an idle connection is used during the time interval between the scan cycles, the connection goes back into the connection pool marked as inactive.

Authentication and security integration considerations   Top of page

Because of variations in server platforms, architecture, and third-party security providers, you may need to be aware of several security considerations when using the WSI:

Using IIS NTLM authentication with the WSI module   Top of page

If you secure your Web site using the Microsoft Windows NT LAN Manager (NTLM) authentication, the WSI default header settings will not work. After authenticating incoming requests, IIS adds an NTLM HTTP authentication header to each request. Because the NTLM HTTP authentication header is not supported by the SilverStream server, incoming requests will be rejected unless you configure the WSI for IIS module in one of the following ways:

The AgWSIUser utility   Top of page

AgWSIUser is a command-line utility that sets and stores the encrypted WSI user and password into the WSI.auth.user setting of the AgWSI.conf file. For more information, see WSI.auth.user.

To run the AgWSIUser utility:

  1. From the command line, change to your WSI root directory.

    You must run the utility in the same directory as the AgWSI.conf file.

  2. Enter the following command:

      AgWSIUser username password 
    

    Use your SilverStream user name and password. If your password is blank, you do not need to enter it.

    You can enter any valid SilverStream user. For example, to use NT credentials run the following:

      AgWSIUser myNTDomain\myNTUser myNTPassword 
    

    The AgWSIUser utility will add the appropriate WSI.auth.user setting with the username and password encrypted into the AgWSI.conf file. At startup, the WSI module will decrypt the user name and password and generate an HTTP authentication header that it will add to every request it forwards to the SilverStream server.

HTTPS client certificate authentication issues   Top of page

The WSI module cannot forward the client certificate from the browser to the SilverStream server. Because the WSI opens a new HTTPS connection to the SilverStream server, the WSI would need to access the private key of the client certificate to be able to use the client certificate for this connection. The private key is not available, because it is securely stored by the browser on the client machine.

Because the WSI cannot send client certificates to the SilverStream server, the WSI will not work with a SilverStream server that is configured to require client certificates for authentication.

enCommerce getAccess integration   Top of page

The SilverStream WSI module and the enCommerce getAccess security software can be used together on the IIS Web server. When integrated, getAccess will provide authentication and authorization services at the Web server, and the WSI module will provide access to the SilverStream Application Server.

NOTE   If your WSI module for iPlanet is integrated with getAccess security, you need to secure your Web site's URLs by entering a path statement in the NameTrans function of the obj.conf file. For more information, see Enabling the WSI module for iPlanet for Windows or Solaris.

Because authentication and authorization take place at the Web server with the getAccess service, the SilverStream Application Server does not need to know about and check the authorization of every user. Instead, it only needs to authenticate and authorize a single user (the user that the WSI module is configured to use).

As described in The AgWSIUser utility, the WSI module intercepts the authentication headers that will be forwarded to the SilverStream Application Server, and replaces the enCommerce credentials with credentials of a single known SilverStream user.

About SilverStream and getAccess security   Top of page

This section describes the SilverStream and getAccess security models and how to integrate them.

SilverStream

The SilverStream Application Server provides built-in security features including authentication, access control, data privacy, data integrity, and single signon to multiple SilverStream servers. In addition to providing its own internal users and groups, the SilverStream Application Server is integrated with several types of security providers that include NT, LDAP, NisPlus, and client certificates. You can control access to resources using simple access control lists (ACLs) or using advanced security expressions. You can specify the following types of access:

You can set SilverStream security using the SilverStream Management Console (SMC) to set security expressions or using the security management API for programmatic access. You can specify authentication for individual resources or server-wide. Security expressions that you set or for resources at the directory level can be propagated to the children of the directory.

getAccess

The getAccess services include authentication and access control. Browser requests to an IIS Web server are processed by a getAccess plug-in. The plug-in detects unauthenticated browser sessions and routes these session requests to a login page. The client can log in as an internal getAccess user or against one of the getAccess plug-in authentication modules. The getAccess plug-in checks the runtime access of the authenticated user to the URL-specified resource and associated components.

As with SilverStream security, with getAccess you can define users and groups (or roles) that control access to SilverStream resources. SilverStream and getAccess users can be authenticated against external security providers. For getAccess users, you can define password policies governing minimum password length and password expiration. You must individually specify and protect resources on the host Web server.

The SilverStream WSI module for IIS receives browser requests from a client through the Web server and forwards them to the application server.

NOTE   You can stack WSI modules to process different groups of requests so that once one WSI module is done with a request the next WSI would receive it.

The following figure shows the architecture and process used to integrate getAccess with the SilverStream server:

How it works   Top of page

getAccess plug-in

The getAccess plug-in initially receives and checks the user request since it is loaded at a higher priority than the SilverStream WSI. The getAccess plug-in checks with the getAccess services to see if the resource URL has been secured. If it has, the getAccess plug-in checks for an authentication header indicating whether the client's getAccess user identity has been established. If it has not, the request is forwarded to a getAccess login page. Once the user has logged in, the getAccess plug-in passes user credentials to the getAccess services to determine if the user is authorized to access the requested resource. If the user is not authorized, the getAccess plug-in returns an access denied error.

If the getAccess plug-in determines that the user is allowed access to a SilverStream server resource, the request is next processed by the SilverStream WSI module.

SilverStream WSI

The SilverStream WSI module forwards the request to the application server host specified in the AgWSI.conf file. Because the SilverStream server cannot verify a getAccess user, the WSI checks the request for an authentication header and then substitutes the credentials set as defaults in the AgWSI.conf file. For more information, see The AgWSIUser utility.

Once the getAccess plug-in determines that the user is allowed access, the SilverStream server returns the requested URL to the plug-in and then to the browser user.

NOTE   In the preceding scenario, all security access is controlled by getAccess. The single known set of SilverStream credentials (defined by the AgWSIUser utility) is only used to connect to the application server. You still need to set SilverStream security to secure application resources against users connecting directly to the application server (rather than through getAccess).

Configuring the integration   Top of page

This section assumes you have installed enCommerce getAccess and the SilverStream Application Server, Version 3.5 or higher into your existing IIS Web (Version 4.0 and above) server framework.

To configure enCommerce getAccess for the WSI for IIS:

  1. Select the Default Web Site from the list of Web server directories in the left pane of the MMC (Microsoft Management Console).

  2. Right-click Default Web Site and select Properties.

  3. Select the ISAPI tab and verify that the getAccess plug-in takes precedence over the SilverStream WSI. The getAccess plug-in must have a higher priority than (and must be loaded before) the WSI module.

  4. Add the WSI.auth.user setting in the AgWSI.conf file as described in The AgWSIUser utility.

    The AgWSIUser utility will add the appropriate WSI.auth.user setting with the user name and password encrypted into the AgWSI.conf file. At startup, the WSI module will decrypt the user name and password and generate an HTTP authentication header that it will add to every request it forwards to the SilverStream server.

  5. Start the SilverStream Application Server and run the SilverStream Management Console (SMC).

  6. Assign the authenticated user (specified in step 5) Execute access to all SilverStream resources accessed through getAccess. You need to set SilverStream security expressions on all resources to be protected by getAccess.

    This step is required even though getAccess (using a getAccess user login) performs the access control through the Web server. The SilverStream security expressions prevent unauthorized access to resources when a client connects directly to the application server. Because getAccess only provides runtime access, SilverStream expressions should be used to control administrative and design-time access.

    A typical scenario would be to assign Read (design-time) access and Write access to the Developers group, Set Permissions access to the Administrators group, and Execute access to both the Developers group and the authenticated WSI user defined in AgWSI.conf file.

    If access to the application server is controlled by a firewall, you may want to assign unrestricted Execute access to all users. Once getAccess and the SilverStream WSI module are configured, you should use the getAccess administration tool to protect SilverStream resources.

        For more information on configuring getAccess users and roles and plug-in authentication providers, see your enCommerce getAccess documentation.

To protect SilverStream resources:

  1. From the enCommerce getAccess Resource Administration screen, click Create.

  2. Provide values for Resource ID, Resource Name, and Description.

  3. Specify the Web server that is running getAccess.

  4. Specify the SilverStream database name and directory for the Relative URL field. For example:

      /myDatabase/Pages/ 
    
  5. Specify the path to the SilverStream WSI.DLL, appended with the URL path to the resource in the Items to Protect field. For example:

      c:\SilverStream\bin\myDatabase\Pages\paperEdit.html 
    

    You may optionally specify any additional referenced resources such as image files.

  6. Fill in the remaining fields.

    See your getAccess documentation for appropriate values.

  7. Save the newly created getAccess resource and assign roles to restrict access to specific users. In order for the new resource to be activated, the server configuration must be updated.

  8. Click the Servers button to open the Server Administration tool.

  9. Select the appropriate server and click Update Config.

  10. Click the Update button.

  11. Click the Reload Config button and then click Reload to reload the configuration. The resource is now ready to be tested.

When getAccess users request a resource through the Web server, they are authenticated and authorized by the getAccess plug-in and associated services. If users are authorized by getAccess, the SilverStream WSI module substitutes the WSI authentication headers (defined by the AgWSIUser utility) and then requests the resource from the application server.



Copyright © 2000, SilverStream Software, Inc. All rights reserved.