Install AnyCAGateway REST on Windows under IIS

Before you begin the installation, make sure that you have reviewed the system requirements and completed the prerequisites (see Preparing), including having set up IIS (IIS Hosting).

The AnyCAGateway REST uses a PowerShell script, AnyCAGatewayInstall.ps1, which takes installation-specific parameters to install the gateway. A table of the available parameters, AnyCAGateway REST Windows Install Parameters, and a sample command, Sample Install Commands, are included in this section.

Tip:  Multiple AnyCAGateway REST gateways for different third-party CAs can be installed on the same server. To do this, run the installation process multiple times and set a unique IIS site/application for each instance and update the -Destination, -VirtualDirectory and potentially the -SiteName parameters to match each unique instance.
Tip:  Please start with Upgrading if you are upgrading an existing installation.
  1. Open PowerShell as administrator.

  2. Navigate to the install folder at the file location in which you placed the artifacts. For example:

    C:\MyFiles\AnyGatewayRESTInstall\ AnyGatewayREST\ net8.0\ Install

  3. Run the AnyCAGatewayInstall.ps1 install script using the parameterClosed A parameter or argument is a value that is passed into a function in an application. values for your installation from AnyCAGateway REST Windows Install Parameters. See the examples in Sample Install Commands.

Important:  If there is an existing application with the same SiteName/VirtualDirectory and -Force is specified, it will be removed.
Tip:  The AnyCAGateway REST checks the client certificate's revocation status during install. To turn that setting off, set the CheckClientCertCRL appsetting.json setting to False (see Appsettings.json File).
Note:  This sample will install AnyCAGateway REST as:

  • Destination file path C:\Program Files\Keyfactor\AnyGatewayREST

  • IIS default website

  • IIS application name (-virtualdirectory) AnyGatewayREST

    Tip:  Add the -destination, -sitename, or -virtualdirectory parameters to redirect the install.

The AnyCAGateway REST Management Portal will be access as:

https://<FQDN>/<-VirtualDiectory>
Sample Client Certificate Authentication Install Script

  • Optionally, set the variables.

    Copy 
    #The FQDN of the SQL server, for example, sql241.keyexample.com
    $SQLServerName = "<sql-server>"
    $SQLUsername = "<sql-user>"
    $SQLUserPassword = "<sql-password>"

    #The SQL account credentials to use to create/manage the database (if -DatabaseManagementUsesSQLAuth is true).
    $DBMCUsername = "<dbmc-sql-username>"
    $DBMCPassword = "<dbmc-sql-password>"
    $DBName = "<db-name>"

    $AuthCAFilePath = "<auth-ca-file-path>"
    $SuperAdminSerialNumber = "<serial-number>"

    $SQLAuthCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList ($SQLUsername,(ConvertTo-SecureString $SQLUserPassword -AsPlainText -Force))
    $DatabaseManagementAuthCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList ($DBMCUsername, (ConvertTo-SecureString $DBMCPassword -AsPlainText -Force))
        

  • Run the script.

    Copy 
                    
    .\AnyCAGatewayInstall.ps1 -UseOAuth "false" `
      -SQLServerName $SQLServerName `
      -DatabaseName $DBName `
      -UseSQLAuth "true" `
      -SQLAuthCredentials $SQLAuthCredentials `
      -DatabaseManagementUsesSQLAuth "true" `
      -DatabaseManagementAuthCredentials $DatabaseManagementAuthCredentials  `
      -SuperAdminType "X509Certificate_SerialNumber" `
      -SuperAdminValue $SuperAdminSerialNumber `
      -Force                
Sample Generic OAuth Install Scripts

  • Optionally, set the variables.

    Copy 
    #The FQDN of the SQL server, for example, sql241.keyexample.com
    $SQLServerName = "<sql-server>"
    $SQLUsername = "<sql-user>"
    $SQLUserPassword = "<sql-password>"

    #The SQL account credentials to use to create/manage the database (if -DatabaseManagementUsesSQLAuth is true).
    $DBMCUsername = "<dbmc-sql-username>"
    $DBMCPassword = "<dbmc-sql-password>"
    $DBName = "<db-name>"

    $IdpName = "<idp-name>"
    $AuthScheme = "<idp-auth-scheme>"
    $IdpAuthority = "<authority>"
    $AuthEnabled = "true"
    $Timeout = 60
    $ClientId = "<client-id>"
    $ClientSecret = "<client-secret-plaintext>"
    $AuthorizationEndpoint = "https://<keycloak-idp>/realms/<your-realm>/protocol/openid-connect/auth"
    $TokenEndpoint = "https://<keycloak-fqdn>/realms/<your-realm>/protocol/openid-connect/token"
    $JSONWebKeySetURI = "https://<keycloak-fqdn>/realms/<your-realm>/protocol/openid-connect/certs"
    $UserInfoEndpoint = "https://<keycloak-fqdn>/realms/<your-realm>/protocol/openid-connect/userinfo"
    $InstallScriptPath = "C:\<your-path-to>\AnyCA REST\AnyGatewayREST\net6.0\Install\AnyCAGatewayInstall.ps1"
    $DefaultIdentityProviderAuthScheme  = "<default-idp-auth-scheme>"
    $SuperAdminType = "OAuth_sub"
    $SuperAdminValue = "<super-admin-value>"

    $SQLUserPasswordSecureString = ConvertTo-SecureString $SQLUserPassword -AsPlainText -Force
    $SQLUserPSCredential = New-Object System.Management.Automation.PSCredential -ArgumentList ($SQLUsername, $SQLUserPasswordSecureString)
    $DatabaseManagementAuthCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList ($DBMCUsername, (ConvertTo-SecureString $DBMCPassword -AsPlainText -Force))

    $ClientSecretSecureString = ConvertTo-SecureString $ClientSecret -AsPlainText -Force

                                                                                
                            

  • Run the install script:

    Copy 

    .\AnyCAGatewayInstall.ps1 -UseOAuth "true" `
      -DefaultIdentityProviderAuthScheme $DefaultIdentityProviderAuthScheme `
      -SQLServerName $SQLServerName `
      -DatabaseName $DBName `
      -UseSQLAuth "true" `
      -SQLAuthCredentials $SQLUserPSCredential `
      -DatabaseManagementUsesSQLAuth "true" `
      -DatabaseManagementAuthCredentials $DatabaseManagementAuthCredentials `
      -IdentityProviderName $IdpName `
      -OAuthType "Generic" `
      -AuthenticationScheme $AuthScheme `
      -Authority $IdpAuthority `
      -AuthenticationEnabled $AuthEnabled `
      -TimeoutSeconds $Timeout `
      -ClientId $ClientId `
      -ClientSecret $ClientSecretSecureString `
      -DisplayNameClaimType "preferred_username" `
      -AuthorizationEndpoint $AuthorizationEndpoint `
      -TokenEndpoint $TokenEndpoint `
      -JSONWebKeySetURI $JSONWebKeySetURI `
      -UserInfoEndpoint $UserInfoEndpoint `
      -SuperAdminType $SuperAdminType `
      -SuperAdminValue $SuperAdminValue 
                            
Sample Auth0 Install Script

  • Set the variables:

    Copy 
    #The FQDN of the SQL server, for example, sql241.keyexample.com
    $SQLServerName = "<sql-server>"
    $SQLUsername = "<sql-user>"
    $SQLUserPassword = "<sql-password>"

    #The SQL account credentials to use to create/manage the database (if -DatabaseManagementUsesSQLAuth is true).
    $DBMCUsername = "<dbmc-sql-username>"
    $DBMCPassword = "<dbmc-sql-password>"
    $DBName = "<db-name>"

    $IdpName = "<idp-name>"
    $AuthScheme = "<idp-auth-scheme>"
    $AuthEnabled = "true"
    $Timeout = 60
    $IdpAuthority = "<authority>"
    $ClientId = "<client-id>"
    $ClientSecret = "<client-secret-plaintext>"
    $AuthorizationEndpoint = "https://<keycloak-idp>/realms/<your-realm>/protocol/openid-connect/auth"
    $TokenEndpoint = "https://<keycloak-fqdn>/realms/<your-realm>/protocol/openid-connect/token"
    $JSONWebKeySetURI = "https://<keycloak-fqdn>/realms/<your-realm>/protocol/openid-connect/certs"
    $UserInfoEndpoint = "https://<keycloak-fqdn>/realms/<your-realm>/protocol/openid-connect/userinfo"
    $SignOutURL = "<signout-url>"
    $Auth0APIURL = "<api-url>"
    $DefaultIdentityProviderAuthScheme  = "<default-idp-auth-scheme>"
    $SuperAdminType = "OAuth_sub"
    $SuperAdminValue = "<super-admin-value>"

    $SQLUserPasswordSecureString = ConvertTo-SecureString $SQLUserPassword -AsPlainText -Force
    $SQLUserPSCredential = New-Object System.Management.Automation.PSCredential -ArgumentList ($SQLUsername, $SQLUserPasswordSecureString)
    $DatabaseManagementAuthCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList ($DBMCUsername, (ConvertTo-SecureString $DBMCPassword -AsPlainText -Force))
    $ClientSecretSecureString = ConvertTo-SecureString $ClientSecret -AsPlainText -Force

                                                                                
                            

  • Run the install script:

    Tip:  If you do not include the -ServerCertificatePassword parameter in the install command, the install script will prompt for the password used to secure the SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. certificate file.
    Copy 

    .\AnyCAGatewayInstall.ps1 -UseOAuth "true" `
      -DefaultIdentityProviderAuthScheme $DefaultIdentityProviderAuthScheme `
      -SQLServerName $SQLServerName `
      -DatabaseName $DBName `
      -UseSQLAuth "true" `
      -SQLAuthCredentials $SQLUserPSCredential `
      -DatabaseManagementUsesSQLAuth "true" `
      -DatabaseManagementAuthCredentials $DatabaseManagementAuthCredentials `
      -IdentityProviderName $IdpName `
      -OAuthType "Auth0" `
      -AuthenticationScheme $AuthScheme `
      -Authority $IdpAuthority `
      -ClientId $ClientId `
      -ClientSecret $ClientSecretSecureString `
      -SignOutURL $SignOutURL `
      -Auth0APIUrl $Auth0APIURL `
      -DisplayNameClaimType "name" `
      -AuthorizationEndpoint $AuthorizationEndpoint `
      -TokenEndpoint $TokenEndpoint `
      -JSONWebKeySetURI $JSONWebKeySetURI `
      -UserInfoEndpoint $UserInfoEndpoint `
      -SuperAdminType $SuperAdminType `
      -SuperAdminValue $SuperAdminValue `
      -Force

Installation parameters for the AnyCAGateway REST on Windows are shown in Table 1047: AnyCAGateway REST Windows Install Parameters. See also the sample commands shown in Sample Install Commands. For container values file information, see Values File Settings for Containers Under Kubernetes.

Important:  Keyfactor highly recommends that you use strong passwords for any accounts or certificates related to Keyfactor Command and associated products, especially when these have elevated or administrative access. A strong password has at least 12 characters (more is better) and multiple character classes (lowercase letters, uppercase letters, numeral, and symbols). Ideally, each password would be randomly generated. Avoid password re-use.

Table 1047: AnyCAGateway REST Windows Install Parameters

Parameter Auth Type Description Container Values File Equivalent
-AppPoolName  

The name of the application pool to use for the new IIS Application. Default AnyGatewayREST.

Create the app pool as part of the installation process.

  
-Connection String Template  

Optional. A string containing additional connection string settings to use when building the SQL connection string. For example, you might set this to:

"Encrypt=false"

This addition to the SQL connection string will cause the connection to be made without TLS/SSL. This may be helpful in troubleshooting or if the SQL server does not have a TLS/SSL certificate configured.

 connection Strings

template
-Cookie Expiration Minutes   Optional. How long in minutes after login a cookie should be expired. The default value is 5.

authentication

cookie Expiration Minutes

-Database Management Auth Credentials  

Required if Database Management Console SQL Auth is true. A PSCredential object containing the SQL account credentials to use to create, update, or populate the database. This user must already exist in SQL and have sufficient permissions for the create/update/populate task. For example:

$creds = Get-Credential

dbmanagement

service Username

AND

dbmanagement

service Password Secret Key

AND

dbmanagement

service Password Secret Name

-Database Management Uses SQLAuth   Required. If true, the Database Management Console will use SQL Auth when servicing the database. n/a
-Database Name  

Required. A string specifying the name of the database to install with this instance of AnyCAGateway REST. It must be unique for each install of the AnyCAGateway REST.

Note:  When installing multiple instances of the AnyCAGateway REST on the same server, set -DatabaseName, -Destination and -VirtualDirectory to unique values for each additional gateway install. Optionally, -SiteName.
 connection Strings

database

OR

connection Strings

existing Secret Key

AND

connection Strings

existing Secret Name
-Destination  

Optional. The directory, if different than the default, C:\Program Files\Keyfactor\Keyfactor AnyCA Gateway, into which to install the AnyCAGateway REST. An empty folder should be designated, otherwise any files will be overwritten during installation. See also -Force.

Note:  When installing multiple instances of the AnyCAGateway REST on the same server, set -DatabaseName, -Destination and -VirtualDirectory to unique values for each additional gateway install. Optionally, -SiteName.
 n/a
-Force  

Optional. If specified, the installation will warn and continue on certain potential conflicts such as pre-existing files in the destination or pre-existing service name. If this parameter is not specified, such situations will be terminating errors.

Important:  If there is an existing application with the same SiteName/VirtualDirectory and -Force is specified, it will be removed.
 n/a
-Session Expiration Minutes   Optional. How long in minutes after login a session is considered valid. The default value is 60.

authentication

session Expiration Minutes

-SiteName  

Optional. The name of the IIS Site to create the application under. Default value is Default Web Site.

May be created as part of the installation process.

Note:  When installing multiple instances of the AnyCAGateway REST on the same server, set -DatabaseName, -Destination and -VirtualDirectory to unique values for each additional gateway install. Optionally, -SiteName.
  
-Source   Optional. The directory containing the files to install. This defaults to the directory containing the install script (from which the install is run). n/a
-SQL Auth Credentials  

Optional, unless -UseSQLAuth is set to True. A PSCredential object containing the username/password of the service account used by the gateway for ongoing connectivity. The account will be created in SQL, if it does not already exist, and granted the gateway_service role. For example:

$creds = Get-Credential
 connection Strings

username

AND

connection Strings

password

OR

connection Strings

existing Secret Key

AND

connection Strings

existing Secret Name
-SQL Server Name   Required. A string specifying the FQDN of the SQL server which will host the AnyCAGateway REST SQL database. connection Strings

hostname

OR

connection Strings

existing Secret Key

AND

connection Strings

existing Secret Name
-Use SQL Auth   Required. A Boolean specifying whether to use SQL Authentication for the SQL service account’s ongoing connection to the database (true) or Windows Authentication (false). See also -SQLAuthCredentials. n/a
-VirtualDirectory  

Optional. The virtual directory for the new application. This will be used as the base path for the app in the browser. Default value AnyGatewayREST.

Create the application as part of the installation process.

Note:  When installing multiple instances of the AnyCAGateway REST on the same server, set -DatabaseName, -Destination and -VirtualDirectory to unique values for each additional gateway install. Optionally, -SiteName.
  
-AuthCA File Path Client Certificate Required for Client Certificate Authentication. The local file path to the location of the Root CA certificate (see AuthCA Certificate). The private key is not required in this instance. n/a
-AuthCA Name Client Certificate Required for Client Certificate Authentication. A nickname that this instance of the AnyCAGateway REST will call the CA being installed. This CA issues client authentication certificates as a trusted root CA. n/a
-Super Admin Type Client Certificate and OAuth

Required for Client Certificate Authentication. Optional for OAuth when using a database that already has an OAuth Admin claim configured.

The Claim Type for the SuperAdmin value.

For client certificate authentication, how you will specify the initial trusted client certificate. Choice of:

  • X509Certificate_Thumbprint

  • X509Certificate_SerialNumber

For OAuth authentication, free-form OAuth claim types in the format OAuth_<claim name> where claim name is any of the standard OAuth claims. For example, OAuth_sub or OAuth_aud.

Used to provide OAuth authentication with a different admin value for superadmin.

Note:  The value entered is case-sensitive (i.e., the X must be capitalized).

authentication

superAdmin

type

-Super Admin Value Client Certificate and OAuth

Required.. The value of the -SuperAdminType selected.

For client certificate authentication, this is the thumbprint or serial number of the SuperAdmin certificate (see SuperAdmin Client Authentication Certificate).

For OAuth authentication, this is the value referenced by the type (e.g. the client’s sub). This will create two claims in the AnyCAGateway REST portal (one admin and one user) to access the portal (see Claims).

Users who have this certificate or OAuth claim will have SuperAdmin access to the AnyCAGateway REST portal for operations and configuration. For client certificate authentication, the certificate is selected upon login to the portal (see Login Claim for Client Certificate Authentication). For OAuth authentication, the user will be directed to the appropriate authentication login page and then redirected to the AnyCAGateway REST portal. For client certificate authentication, the subject of the certificate becomes the display name of the logged in user on the AnyCAGateway REST portal header. For OAuth authentication, the display name of the logged in user on the AnyCAGateway REST portal header is the value found in the field specified with the -DisplayNameClaimType parameter.

authentication

superAdmin

value

-Authentication Scheme OAuth Required for OAuth authentication. The authentication scheme (reference name) of the identity provider (for example, KeycloakAuthScheme). The Authentication Scheme should be entered without spaces. This is used in constructing URLs that reference the identity provider from the AnyCAGateway REST.

authentication

oauth

authentication Scheme

-Authority OAuth

Required for OAuth authentication. The authority of the identity provider.

For example, for an OAuth configuration of type generic:

https://appsrvr18 .keyexample.com: 1443/ realms/ Keyfactor

For an OAuth configuration of type Auth0:

https://my-auth0-account .us.auth0.com/

authentication

oauth

parameters

authority

-Authorization Endpoint OAuth

Required for OAuth authentication. A string containing the authorization endpoint of the identity provider. For example:

https://appsrvr18 .keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/auth

authentication

oauth

parameters

authorization Endpoint

-Client Secret OAuth

Required for OAuth authentication. A PowerShell secure string containing the client secret for the identity provider. For example:

ConvertTo-SecureString "<your-secret>" -AsPlainText -Force

authentication

oauth

parameters

client Secret Secret Key

-ClientId OAuth Required for OAuth authentication. The client ID of the identity provider. For example, for an OAuth configuration of type generic, RESTGateway. For an OAuth configuration of type Auth0, auth0|652054e61f074d7ea79ae176.

authentication

oauth

parameters

clientId Secret Key

-Default Identity Provider Auth Scheme OAuth Required for OAuth authentication.The authentication scheme of the default identity provider used for login. For example, Keycloak.

Upon login, if you want to point to a different provider than the default provider identified here, you can use a hint parameter in the URL. For example:

?idpHint=IDP_NAME

authentication

default Identity Provider Auth Scheme

-Disable Bearer Token Scope Requirement OAuth

Optional. If true, the scope will not be required when using OAuth token authentication with the AnyCAGateway REST. The default value is false.

Tip:  You will need to set this to true if your identity provider does not provide a scope. Some identity providers do not offer the option to include a scope value (e.g. Azure AD). Other identity providers offer this option but do not include the scope by default (e.g. Keyfactor Identity Provider).
Important:  If you configure the Disable Bearer Token Scope Requirement option to false (no), you must either configure the client you’re using to connect from Keyfactor Command to the gateway to always include the scope keyfactor-anyca-gateway in the token or you must configure the keyfactor-anyca-gateway scope on the authentication methods tab when configuring the CA record in Keyfactor Command. Your OAuth identity provider needs to be configured to recognize keyfactor-anyca-gateway as a scope.

authentication

oauth

parameters

disable Bearer Token Scope Requirement

-Display Name Claim Type OAuth

Required for OAuth authentication. The claim type to use for accessing the AnyCAGateway REST portal via OpenID Connect (OIDC). For example, for an OAuth configuration of type generic, preferred_username. For an OAuth configuration of type Auth0, nickname.

The value set with the -DisplayNameClaimType determines the username that appears in the AnyCAGateway REST portal header.

authentication

oauth

parameters

nameClaim Type

-Identity Provider Name OAuth Required for OAuth authentication. A display name or nickname that this instance of the AnyCAGateway REST will use to reference the identity provider being used. For example Keycloak. The Identity Provider Name may contain spaces. This name is used when referencing the identity provider in the AnyCAGateway REST portal.

authentication

oauth

display Name

-JSON WebKey SetUri OAuth

Required for OAuth authentication. A string containing the JWKS (JSON Web Key Set) URI of the identity provider. For example:

https://appsrvr18 .keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/certs

authentication

oauth

parameters

json Web Key Set Uri

-OAuthType OAuth Required for OAuth authentication. The OAuth type, either Auth0 (for Auth0) or Generic (for others). This controls the parameters expected by the install script to work with various OAuth types. If Auth0, additional parameters -Auth0ApiUrl and -SignOutUrl are required.

authentication

oauth

provider Type

-Super Admin Provider OAuth

Only required when an IdP configuration is not provided. The authentication scheme of the provider to tie to the SuperAdmin Claim. Defaults to the authentication scheme of the provided IdP.

authentication

superAdmin

provider

-TimeoutSeconds OAuth The number of seconds a request to the OAuth identity provider is allowed to process before timing out with an error. The default is 60.

authentication

oauth

parameters

timeout

-TokenEndpoint OAuth

Required for OAuth authentication. A string containing the token endpoint of the IdP. For example:

https://appsrvr18 .keyexample.com:1443/realms/ Keyfactor/ protocol/ openid-connect/ token

authentication

oauth

parameters

token Endpoint

-Use OAuth OAuth Required for OAuth authentication. A Boolean specifying whether to use OAuth authentication to authenticate users to the gateway (true) or client certificate authentication (false). The default is false. n/a
-UserInfo Endpoint OAuth

Only required if a user info endpoint is found in the discovery document. A string containing the user info endpoint of the IdP. For example:

https://appsrvr18 .keyexample.com:1443/realms/Keyfactor/ protocol/ openid-connect/ userinfo

authentication

oauth

parameters

userInfo Endpoint

-Valid Audience OAuth Optional. A string specifying the valid audience for the identity provider against which claims are validated. Claims are rejected if they do not contain the audience specified with this parameter—if anything has been specified with this parameter. Only one audience may be specified. This parameter applies to OpenID Connect tokens only.

authentication

oauth

parameters

oidc Audience

-Auth0 Api Url OAuth type Auth0

Required for OAuth authentication of type Auth0. The Auth0 API URL for the identity provider. For example:

https:// keyfactorAPI.com

authentication

oauth

parameters

auth0 ApiUrl

-Sign Out Url OAuth type Auth0

Required for OAuth authentication of type Auth0. The sign out URL for the identity provider. This value is only required when using Auth0 as your identity provider. For example:

https://my-auth0-account .us.auth0.com/ oidc/ logout

authentication

oauth

parameters

signOut Url