The PIAB server is a standard .Net web service application and, because of this can be configured in a variety of ways, including using one or multiple computers. This document suggests some typical setup patterns and describes our recommended defaults. Please note that applying these patterns requires knowledge of Windows system administration and .Net administration.

The main issue when creating and using a setup pattern is how to get the authentication correct between the various components of the system. This is simplest when all the components of the server are on a single PC, and more complex when the components are distributed among multiple PCs.

If you wish to use higher levels of security, with Windows authentication and trusted connections used throughout, then PIAB can be configured in this way. However please be aware that this requires extra technical work to ensure that the system has correct access to all these components. This is especially the case with a distributed system.

The setup issues include:

• How the PIAB client authenticates to IIS;
• How the web services application authenticates to SQL Server;
• The location of the PIAB system folders;
• Ensuring that the search function (Microsoft Index Service) can read the correct PIAB system folders.

By default, PROJECT in a Box is configured to use Anonymous Access to IIS. In this mode, any user can connect to the web service but a valid PIAB username/password must be sent with each request to gain access. Credentials are stored in the piab database itself and authentication is perfomed by the application.

Alternatively, Integrated Windows authentication may be used. In this case, IIS is set to use Windows Integrated Authentication, only the user name is stored in the piab database and the user name must match a valid Windows login name. The client's connection settings are switched to use Windows Authentication. This is the preferred mode in an Active Directoy environment as it gives improved security and simpler user management.

• piabws.config The PIAB ASP.NET web application on the server uses options contained in an XML file 'piabws.config'. You can edit this file directly, or use the 'PROJECT in a box Server' program to help you.

• web.config In addition the web application has a 'web.config' file that contains standard Microsoft .NET configuration options for an ASP.NET application.

• piabpe.config The PIAB client has a configuration file 'piabpe.config'. Again, this is in XML format and stores configuration options that you set in the client itself using 'Options' from the menu.

The patterns described here rely on a number of Windows and .Net techniques and technologies with which the administrator should be familiar:

The piab client can communicate with the server via http or https. Using HTTP, information is transimitted in plain text. Using HTTPS, the communications are encrypted. To use HTTPS, IIS must have a server certificate installed.

IIS can be configured to authenticate the client in a number of ways:

- Anonymous Access - Basic Access - Integrated Windows Access

In IIS 6.0 you can specify the user that will access system resources, or use the one supplied by the system. This is important when considering permissions to access local and remote resources.

By default a web application runs in the security context of the NT AUTHORITY\NETWORK SERVICE user on Windows 2003 Server, or %machinename%\ASPNET on Windows 2000 Server. This may be required to authenticate to a network resource such as a network file share. There are two ways to change this, via the IIS Application Pool Identity or via .NET Impersonation.

Note that any user running a web application must belong to the special IIS_WPG group and have appropriate permissions on local and remote resources.

You can change the identity that IIS uses to run the web application from the default to, for example, a valid domain user. This is carried out in the IIS Management Console | Application Pool properties.

Impersonation allows the web application to run with the credentials of a different user. This is set in the web.Config file for the piab web service using the <identity> element e.g.:

<identity impersonate="true" userName="foo" password ="bar"/>

For increased security, you can hide the credentials so that they are not written in the web.Config file using the Microsoft aspnet_setreg.exe utility, resulting in a web.Config entry like this:

<identity impersonate="true" 
  userName="registry:HKLM\SOFTWARE\MY_SECURE_APP\identity\ASPNET_SETREG,userName"
  password="registry:HKLM\SOFTWARE\MY_SECURE_APP\identity\ASPNET_SETREG,password" />

For more information see http://support.microsoft.com/kb/329290

Connections can be made to SQL Server via:

- Mixed Mode access (username and password supplied)
- Trusted Connection (using an authenticated Windows User)

In general, a Trusted Connections is preferred for improved security.

Example connection strings, set in the piabws.config file:

Mixed Mode:

Data Source=(local);Initial Catalog=piab;User ID=foo;Password=bar;

Trusted Mode:

Server=(local);Database=piab;Trusted_Connection=True;

When Anonymous Access is used in IIS, the Windows credentials used for a Trusted Connection to a Local SQL Server are

NT AUTHORITY\NETWORK SERVICE

for Windows 2003 Server, or

%machinename%\ASPNET

on Windows 2000 Server. When accessing a remote SQL Server instance, the credentials used are

%domainname%\%machinename%$

PIAB uses Microsoft Indexing Service to perform document searches. The service must contain a directory called piabdoc that includes the piab doc folder (which contains all the project files). If the folder is stored on a file share, then the Indexing Service must be modified to include that share as a UNC path.

A single server PC with Windows 2003 Server, Anonymous IIS Authentication

This pattern is the default for PIAB installed on single Windows 2003 Server. All the files/folders and the SQL Server instance are on the server itself. The remote client accesses the web service using anonymous IIS access, and a special local account is used to access file resources and to communication with SQL Server.

Set the client to use anonymous Access to IIS. Use http or https in the URL to connect to the server.

If https is used, a server certificate must be applied.The directory security settings for the piabws virtual directory are set to allow anonymous access. The web application runs under the credentials of NT AUTHORITY\NETWORK SERVICE. This is a local account used by ASP.NET web applications.

Use the default supplied

Use the default supplied. The DB connection string is set to used a trusted connection on the local SQL Server instance, and the folder locations are local to the server.

System folders, e.g. the template paths and the doc folder (which stores all the version of files) are in their default locations.

The NT AUTHORITY\NETWORK SERVICE user must have r/w permissions on the these folders.

The MS Indexing Service contains a catalog called piabdoc that contains the doc folder.

The SQL Server instance has a login called NT AUTHORITY\NETWORK SERVICE. This login is set as a user with data reader/writer privileges on the piab database.|

This pattern allows for the SQL Server databsae to be stored on a separate server. All other resources are local.

Set the client to use anonymous Access to IIS. Use http or https in the URL to connect to the server.

If https is used, a server certificate must be applied. The directory security settings for the piabws virtual directory are set to allow anonymous access.
The web application runs under the credentials of NT AUTHORITY\NETWORK SERVICE. This is a local account used by ASP.NET web applications. For trusted connection to SQL Server, however, the web application uses an account called:

%yourdomain%\%yourserver%$

Use the default supplied

Set the database connection string in the piabws.config file to access the remote SQL Server with a trusted connection e.g.

<dbconstring>Server=SVR2;Database=piab;Trusted_Connection=True</dbconstring>

System folders, e.g. the template paths and the doc folder (which stores all the version of files) are in their default locations.

The 'NT AUTHORITY\NETWORK SERVICE' user must have r/w permissions on the these folders.

The MS Indexing Service contains a catalog called piabdoc that contains the doc folder.

The SQL Server instance has a login called

%yourdomain%\%yourserver%$ 

e.g.

MYDOMAIN\SVR1$ 

This login is set as a user with data reader/writer privileges on the piab database.

In this pattern, both SQL Server and the folders containing project documents, templates etc. are on remote servers. The complication here is that the web-service needs to authenticate not just to SQL Server but also the folders on a remote file share. While Windows provides a way for the web app to authenticate to SQL Server (using the %yourdomain%\%yourserver%$ credentials) it doesn't provide a way to authenticate to the file share. The default NT AUTHORITY\NETWORK SERVICE user is local to SVR1 and therefore has permissions on the file share on SVR3.

There are a number of ways to solve this - in this pattern we replace the default web app user with our domain user, and use those credentials to authenticate to the remote resources.

Set the client to use anonymous Access to IIS. Use http or https in the URL to connect to the server.

If https is used, a server certificate must be applied. The directory security settings for the piabws virtual directory are set to allow anonymous access. Use the IIS 6.0 console to set the Identity for the Application Pool for the piabws web application to use a domain user created for this purpose:

YOURDOMAIN\piabuser

There are a number of special considerations for this user:

1. The user must be given appropriate permissions on local and remote folders.

2. The user must be (as a minimum) a member of the IIS_WPG group (IIS Worker Process Group).

3. The local policy may need to be changed to allow the user to logon as a service:

1. Run the secpol.msc console;
2. Navigate to local policies > user rights assignment > log on as service;
3. Add the user to the list.

Use the default supplied

Set the database connection string in the piabws.config file to access the remote SQL Server with a trusted connection e.g.

<dbconstring>Server=SVR2;Database=piab;Trusted_Connection=True</dbconstring>

Set the required folder references to have UNC paths (see 5. Folders, below) e.g.

<templatepath>\\SVR3\piabshare\template1.2</templatepath>
<docpath>\\SVR3\piabshare\doc</docpath>

The PIAB document folders, typically doc and template folders that hold the project files and template, are stored on SVR3. These folders are shared on the network and available as UNC paths to SVR1. Our YOURDOMAIN\piabuser user is set to have modify permissions on this share and the folders. The piabws.config file contains UNC path references to these folders (see 4. piabws.config above).

The MS Indexing Service contains a catalog called piabdoc that contains the doc folder. By default, this is set up with local folders. The location of the doc folder must be set using the MS Indexing Service control panel (from the Computer Management console). See Figure 1 below.

The web app authenticates to SQL Server using our YOURDOMAIN\piabuser. This login is set as a user with data reader/writer privileges on the piab database.

This pattern is similar to Pattern 3, in that the application is split over three servers. However, Integrated Windows Authentication is now used between the PIAB client and IIS. This presents an issue in that we cannot change use the IIS console to change the user that the web applications runs under. Instead, we use change the identity that the web application runs under to that of a domain user to allow authentication to SQL and the remote folders.

Set the client to use Integrated Windows Access to IIS.
Use http or https in the URL to connect to the server.

If https is used, a server certificate must be applied.

The directory security settings for the piabws virtual directory are set to allow Windows Access only.

1. Create a new domain user e.g. MYDOMAIN\piabuser
2. Put the new user in the following groups: 'Domain User', 'IIS_WPG' (IIS_WPG) is a group that allows the user to run the .NET worker process.
3. Set the new user to be the 'Database Owner' of the 'piab' database.
4. Set permissions on the remote share and local folders (rw on the remote share 'doc' file, rw on the local install folder).

There are two alternatives ways to change the web application identity: either modify IIS to run piabws under a different identity (recommended), or modify the web.config file to achieve the same effect.

1. Run the IIS admin console, and select the 'Application Pools'.
2. Select the Application Pool that runs the 'piabws' application.
3. Right-click and show the 'Properties' for the Application Pool.
4. On the 'Identity' tab, change the identity to 'Configurable' and enter a domain user and password.

Modify the default web.config file to include an impersonation element. This instructs the web application to run in the security context of the impersonated user:

<system.web>
  <identity impersonate="true" userName="YOURDOMAIN\piabuser"  password="yourpassword"/>

This technique involves storing the credentials of the piabuser user in the Web.config file. Although this file is normally protected by IIS from public access, it is not a desirable feature of the pattern from a security standpoint. Microsoft provide a fix for this with using the aspnet_setreg.exe utility, which allows you to encrypt and store the credentials in the registry, resulting in a Web.config entry of this form:

<identity impersonate="true" 
  userName="registry:HKLM\SOFTWARE\MY_SECURE_APP\identity\ASPNET_SETREG,userName"
  password="registry:HKLM\SOFTWARE\MY_SECURE_APP\identity\ASPNET_SETREG,password" />

For more information see http://support.microsoft.com/kb/329290

Set the database connection string in the piabws.config file to access the remote SQL Server with a trusted connection e.g.

<dbconstring>Server=SVR2;Database=piab;Trusted_Connection=True</dbconstring>

Set the required folder references to have UNC paths (see 5. Folders, below) e.g.

<templatepath>\\SVR3\piabshare\template1.2</templatepath>
<docpath>\\SVR3\piabshare\doc</docpath>

Set Enterprise Hub (the web application) to use IIS Authentication:

1. Run the 'PROJECT in a box Server' program
2. Select the 'Hub' tab
3. Enable 'IIS Authentication'
4. Save and exit.

The PIAB document folders, typically doc and template folders that hold the project files and template, are stored on SVR3.

These folders are shared on the network and available as UNC paths to SVR1.

Our YOURDOMAIN\piabuser user is set to have modify permissions on this share and the folders.

The piabws.config file contains UNC path references to these folders (see 4. piabws.config above).

The MS Indexing Service contains a catalog called piabdoc that contains the doc folder. By default, this is set up with local folders. The location of the doc folder must be set using the MS Indexing Service control panel (from the Computer Management console).

The web app authenticates to SQL Server using our YOURDOMAIN\piabuser

This login is set as a user with data reader/writer privileges on the piab database.