IIS Hosting

The Keyfactor AnyCA Gateway REST is by default hosted using a built-in Kestrel web server. This section contains instructions on how to host the AnyCAGateway REST using Microsoft IIS instead.

Complete the full installation of the AnyCA Gateway prior to setting up IIS hosting.

Setup

The AnyCAGateway REST requires only the default IIS features for operation and requires neither Windows Integrated nor Basic authentication. The correct PowerShell command to install the necessary roles and features is:

Install-WindowsFeature Web-Server, Web-Asp-Net45, Web-Default-Doc, Web-Dir-Browsing, Web-Http-Errors, Web-Static-Content, Web-Http-Logging, Web-Stat-Compression, Web-Filtering, Web-Net-Ext45, Web-ISAPI-Ext, Web-ISAPI-Filter, Web-Mgmt-Console

To configure the AnyCAGateway REST to run under IIS:

1. In the IIS management console, configure an application under either the Default Web Site or a new website you have created. Point the physical path of this application to the directory where the AnyCAGateway REST is installed. By default this is:

   C:\Program Files\Keyfactor\Keyfactor AnyCA Gateway\AnyGatewayREST\net8.0
2. Set up an HTTPS Binding on the site. Use an SSL TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. certificate for the machine you are on or issue one to use if you have not already done so.
3. Set up a new application pool with a user that is not a domain admin for your application to use.

4. Update the SSL Settings under your new application to Require SSL and Require Client Certificates.

   Note:  If using OAuth, set it to Ignore Client Certificates.

5. Give Read and Write permissions for the user running the application pool to the KestrelSecret.json and SQLSecret.json files in the configuration folder. This is found by default at:

   C:\Program Files\Keyfactor\Keyfactor AnyCA Gateway\AnyGatewayREST\net8.0\configuration
6. Give database permissions to the user running the application pool on the your SQL server.

7. Delete the AnyGatewayREST.staticwebassets.runtime.json file. This is found in the following path by default:

   C:\Program Files\Keyfactor\Keyfactor AnyCA Gateway\AnyGatewayREST\net8.0

8. Add a web.config file to the AnyGatewayREST\net8.0 folder under the AnyCAGateway REST installation folder for IIS to point to for the application. By default this is found at:

   C:\Program Files\Keyfactor\Keyfactor AnyCA Gateway\AnyGatewayREST\net8.0
   Copy

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <location path="." inheritInChildApplications="false">
       <system.webServer> 
         <handlers>
           <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
         </handlers>
         <aspNetCore processPath=".\AnyGatewayREST.exe" arguments="" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess">
         </aspNetCore>
       </system.webServer>
     </location>
       <system.webServer>
           <staticContent>
             <clientCache cacheControlMode="DisableCache" />
           </staticContent>    
       </system.webServer>
   </configuration>

9. For installation of AnyCAGateway REST v24.4 or higher, in the appsettings.json file add the BasePath setting (see Appsettings.json File). For example:

   "BasePath": "<your virtual directory in IIS>"
10. You should now be able to navigate to the URL you set up in IIS with the corresponding application name, select your client authentication certificate, and then use the AnyCAGateway REST as you would if it was set up using the default Kestrel web server.

{
    "ConnectionStrings": {
        "AnyGatewayREST": "data source={SQLServerName};initial catalog={DatabaseName};Integrated Security=true"
    }
}

Troubleshooting Tips

If you encounter any errors when trying to access the portal, check the Windows Event Log on the AnyCAGateway REST server in addition to the AnyCAGateway REST.

500.30 Error

If you encounter a 500.30 error and a .NET Runtime error of “Key not valid for use in specified state” in the Windows Event Log, perform the following two additional steps:

1. Edit the KestrelSecret.json file, remove the encrypted contents, and replace it with the following:

   Copy

   {
       "Kestrel": {
           "Certificates": {
               "Default": {
                   "Password": "TemporaryPlaceholderPassword"
               }
           }
       }
   }

   The value in the Password field does not need to be configured.

1. Edit the SQLSecret.json file, remove the encrypted contents, and replace it with the following, using a connection string appropriate to your environment and referencing your existing database:

   Copy

   {
       "ConnectionStrings": {
           "AnyGatewayREST": "data source=SQL_SERVER_FQDN;initial catalog=SQL_SERVER_DATABASE_NAME;Integrated Security = true"
       }
   }

   The following is a simple connection string if Integrated Security is false:

   Data Source=SQL_SERVER_NAME;Initial Catalog=SQL_SERVER_DATABASE_NAME;Integrated Security=False;Persist Security Info=True;User ID=SQL_SERVER_USER;Password=SQL_SERVER_PASSWORD;

   

   Figure 778: Key Not Valid for Use Error Under IIS

403.16 Error

You may receive a 403.16 error while trying to authenticate the AnyCAGateway REST using certificate authentication. On the face of it, this error indicates that the chain for the certificate you're using to authenticate is not trusted by the AnyCAGateway REST server. First, check to be sure that your certificate is trusted by the AnyCAGateway REST server. But if your certificate is fully trusted and you're still getting this error, what then?

This error can indicate that the trusted root store on the AnyCAGateway REST server contains a certificate that is not a root certificate (for example, an intermediate certificate is accidentally in the root store). To check this, open the Local Computer certificates MMC on the AnyCAGateway REST server, drill down to Certificates under the Trusted Root Certificate Authorities and scan for any certificates where the Issued To does not match the Issued By. Remove any certificates you find like this.

Additional Setup for Windows Server 2022

If you’re on a version of Windows Server that has TLS TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. 1.3, ensure it is disabled on the site that is hosting the AnyCAGateway REST application. That setting can be found here:

Adding an IIS Hosted CA to Keyfactor Command

When adding an IIS Hosted CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. to Keyfactor Command, on the Certificate Authority A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. Basic Tab (see Add the AnyCAGateway REST as a CA in Keyfactor Command), for the Host URL enter the FQDN (fully qualified domain name) of the server on which the gateway is installed and /<IIS Base Path>/EJBCA, where <IIS Base Path> is as identified in step 10 above. For example, CAGateway24.keyexample.com/<IIS Base Path>/EJBCA. The Host URL is unique for each CA.