How To: Work with IIS Configuration for SecureAuth

Version Affected: All

 

Overview

This article covers common IIS Application Pool and site-configuration tasks for a SecureAuth appliance: creating a dedicated Application Pool for specific realms, moving realms into an Application Pool in bulk, doing either of those at scale with SecureAuth-provided PowerShell scripts, copying an entire IIS site and its Application Pools to a different server, and copying IIS URL Rewrite rules between realms.

There is more than one way to do this:

• To manually create a single new Application Pool in IIS Manager, to isolate specific realms in it -- see Method 1.
• To manually move several realms into a different Application Pool at once, by editing IIS configuration directly -- see Method 2.
• To copy an entire IIS site and its Application Pools from one server to another -- see Method 3.
• To copy IIS URL Rewrite rules from one realm to another -- see Method 4.
• To create several new Application Pools at once with a PowerShell script instead of doing it manually -- see Method 5.
• To move several applications between Application Pools at once with a PowerShell script instead of doing it manually -- see Method 6.

In this article

• Method 1: How To Manually Create a New Application Pool in IIS
• Method 2: Move Realms Into an Application Pool in Bulk
• Method 3: Export and Import an IIS Site and Application Pool Configuration
• Method 4: Export and Import URL Rewrite Rules
• Method 5: Create New Application Pools via PowerShell Script
• Method 6: Move Applications Between Application Pools via PowerShell Script

Method 1: How To Manually Create a New Application Pool in IIS

Certain realms can overload the general .NET v4.5 Network Service pool if too many are assigned to it. Creating a dedicated pool for those realms isolates them from the rest.

1. Open IIS Manager.
2. Open Application Pools, then click Add Application Pool... in the Actions pane.

3. Name the new pool and leave the rest of the default settings, then click OK.

4. Right-click the new pool and select Advanced Settings.
5. Set Identity to the built-in account the realm should run as -- normally NetworkService.

Method 2: Move Realms Into an Application Pool in Bulk

This method moves multiple realms from one IIS Application Pool to another in bulk, by directly editing IIS's applicationhost.config file -- for example, moving every realm that was created in the wrong Application Pool into the pool created in Method 1.

1. Back up C:\Windows\System32\inetsrv\config\applicationhost.config.
2. Stop the World Wide Web Publishing Service. IIS may prompt to also stop a dependent logging service -- allow it to.

3. Open applicationhost.config in a text editor.
4. Use Find and Replace to change every realm's Application Pool assignment at once. For example, to move every realm from the Default App Pool to a pool named CustomPool, find  applicationPool="DefaultAppPool" and replace it with  applicationPool="CustomPool". Include the leading space before applicationPool in both the find and replace text, so only the full attribute is matched.

5. Save the file, then start the World Wide Web Publishing Service again. The dependent logging service may start back up on its own.

Method 3: Export and Import an IIS Site and Application Pool Configuration

This method copies an entire IIS site, along with its Application Pools, from one server to another -- for example, when moving to new appliance hardware and recreating every Application Pool and site binding by hand isn't practical.

1. On the source server, open an elevated command prompt and export the existing Application Pools to an XML file:

appcmd list apppool /config /xml > c:\apppools.xml

2. In the same elevated command prompt, export the site configuration too:

appcmd list site /config /xml > c:\sites.xml

3. Copy both XML files to the target server. Before importing, open sites.xml in a text editor and change its SITE.ID value to a number not already in use on the target server -- importing it with the same SITE.ID as an existing site (such as 1, the Default Web Site) conflicts with that site.

4. On the target server, remove any existing Application Pools that share a name with the ones being imported, then run:

appcmd add apppool /in < c:\apppools.xml
appcmd add site /in < c:\sites.xml

5. The target server now has two sites -- its original Default Web Site and the newly imported one. Remove the original Default Web Site, then rename the imported site to Default Web Site.

6. Open the imported site's bindings and reselect the SSL certificate for its https binding -- certificate selections are not preserved by the export/import.

7. Restart IIS (iisrestart), then confirm every realm loads correctly under its Application Pool. Also double check Application Pool permissions on the target server, especially for any Application Pool using a domain account as its identity -- a domain account valid on the source server may not have the same rights on the target.

Method 4: Export and Import URL Rewrite Rules

This method exports a set of IIS URL Rewrite rules from one SecureAuth realm and imports them into another, so the same rewrite rules do not need to be recreated manually on each realm that needs them.

1. On the realm that already has the desired rewrite rules configured, open a command prompt and run the following command to export them to an XML file (replacing SecureAuth15 with your realm's name):

C:\Windows\System32\inetsrv>appcmd list config "Default Web Site/SecureAuth15" -section:system.webServer/rewrite/rules -xml > secureauth15.xml

2. If the target realm is on a different server, copy the exported XML file to that server.
3. On the target realm, run the following command to import the rules (replacing SecureAuth16 and the file name with your target realm and exported file):

C:\Windows\System32\inetsrv>appcmd set config "Default Web Site/SecureAuth16" /in < secureauth15.xml

Method 5: Create New Application Pools via PowerShell Script

This method uses a SecureAuth-provided PowerShell script to create multiple new Application Pools at once, each set to v4.0, Integrated, and AlwaysRunning. The script backs up applicationHost.config to C:\Windows\System32\inetsrv\config before making any changes.

1. Decide how to supply the new Application Pool names: a CSV file, or names written directly in the script (no limit either way).
   • To use a CSV file, set $UseCsv to $true in the script, and save a CSV at c:\temp\appools.csv with an AppPoolName column listing the names, one per row.
   • To use names written directly in the script instead, leave $UseCsv as $false and edit the $AppPools array:
     

     $AppPools = @(
        "AppPool1",
        "AppPool2",
        "AppPool3"
     )

2. Contact SecureAuth Support to obtain this script.
3. Leave $DryRun = $true and run the script first, to see what it will do without making any changes.
4. Set $DryRun to $false and run the script again to actually create the Application Pools.

Method 6: Move Applications Between Application Pools via PowerShell Script

This is a two-script process, provided by SecureAuth Support: the first script exports every application's current Application Pool assignment to a CSV file (excluding the Default Site and the default/out-of-the-box SecureAuth apps); the second reads an edited copy of that CSV and moves each application to the Application Pool specified. Both scripts have a $DryRun toggle, so changes can be previewed before actually being made. Contact SecureAuth Support to obtain both scripts.

1. Run the export script to create D:\temp\AppPools\AppPoolMapping.csv, listing every application and its current Application Pool.
2. Edit that CSV's AppPool column with the Application Pool each application should move to, and save it in the same location.
3. Run the move script, which reads the updated CSV and moves each application to its new Application Pool.

Special Considerations

applicationhost.config controls every site and application IIS hosts on the server, not just SecureAuth realms. An incorrect edit in Method 2 -- a typo in the Find/Replace text, or replacing more than intended -- can break IIS for the entire server, not just the realms being moved. Keep the new Application Pool's name (Method 1) and the applicationhost.config backup made in Method 2's first step until the change has been verified working, and confirm the affected realms load correctly immediately after starting the service back up.


 

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.