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 under IIS, and sample commands, Sample Install Commands, are included in this section.
Install the AnyCAGateway REST
- Open PowerShell as administrator.
-
Navigate to the install folder at the file location in which you placed the artifacts. For example:
C:\Temp-Files\AnyGatewayRESTInstall\ AnyGatewayREST\ Install -
Run the AnyCAGatewayInstall.ps1 install script using the parameter
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 under IIS. See the examples in Sample Install Commands.
In environments where CRL A Certificate Revocation List (CRL) is a list of digital certificates that have been revoked by the issuing Certificate Authority (CA) before their scheduled expiration date and should no longer be trusted. checking is not available during installation, this behavior can be turned off by setting CheckClientCertCRL to False in the appsettings.json file before installation. For more information, see Appsettings.json File.
The appsettings.json file is located under the AnyGatewayREST\Configuration directory within the installation files.
Sample Install Commands
Installation directory: C:\Program Files\Keyfactor\Keyfactor AnyCA Gateway
IIS site: Default Web Site
IIS application name: AnyGatewayREST
Tip: Add the -Destination, -SiteName, or -VirtualDirectory parameters to customize the installation paths and IIS configuration.
After installation, access the AnyCAGateway REST Portal using the following URL format:
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 SSL 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
AnyCAGateway REST Windows Install Parameters under IIS
Installation parameters for the AnyCAGateway REST on Windows are shown in Table 1273: 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.
Table 1273: AnyCAGateway REST Windows Install Parameters
|
Parameter |
Auth Type | Description | Container Values File Equivalent |
|---|---|---|---|
|
-AppPoolName
|
Optional. The name of the IIS app pool to create, configure, and attach to the application. The default value is AnyGatewayREST. If this pool already exists and is not attached to another application, it will be used and not modified if -Force is specified. Note: Specify this parameter to reference an existing application pool with a non-default name or create a new application pool with a non-default name at install time.
|
n/a | |
| -AppPoolUser |
Optional. A PSCredential object containing the username/password of the service account used by the gateway for the application pool under IIS if a non-default is desired. The default is the built-in ApplicationPoolIdentity. For example: $creds = Get-Credential
Note: If the application pool is created before the installation script is run using a non-default user, this parameter does not need to be specified since the application pool already exists at install time. This parameter is used only to create the application pool on install for a non-default application pool user.
|
n/a | |
| OAuth type Auth0 |
Required for OAuth authentication of type Auth0. The Auth0 API URL of the identity provider. For example: https:// keyfactorAPI.com
|
authentication
oauth
parameters
auth0ApiUrl
|
|
| Client Certificate | Required for Client Certificate Authentication. The local file path to the location of the Root CA certificate (see Client Authentication CA (AuthCA) Certificate). The private key is not required in this instance. | n/a | |
| 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
authenticationScheme
|
|
| 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
|
|
| 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
authorizationEndpoint
|
|
| 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
clientIdSecretKey
|
|
| 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
clientSecretSecretKey
|
|
|
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. |
connectionStrings
template
|
||
| Optional. How long in minutes after login a cookie should be expired. The default value is 5. |
authentication
cookieExpirationMinutes
|
||
|
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
|
DatabaseManagementAuthCredentials
serviceUsername
AND DatabaseManagementAuthCredentials
servicePasswordSecretKey
AND DatabaseManagementAuthCredentials
servicePasswordSecretName
|
||
| Required. If True, the Database Management Console will use SQL authentication when servicing the database. | n/a | ||
|
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.
|
connectionStrings
database
OR connectionStrings
existingSecretKey
AND connectionStrings
existingSecretName
|
||
| 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
defaultIdentityProviderAuthScheme
|
|
|
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 | ||
| OAuth |
Optional. If True, the scope will not be required when using OAuth token authentication with the AnyCAGateway REST. The default 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 (for example, Azure AD). Other identity providers offer this option but do not include the scope by default (for example, Keyfactor Identity Provider).
Important: If you configure the DisableBearerTokenScopeRequirement 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
disableBearerTokenScopeRequirement
|
|
| 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
nameClaimType
|
|
|
-Force
|
Optional. If specified, the installation issues a warning and continues despite certain potential conflicts, such as pre-existing files in the destination or a pre-existing service name. If this parameter is not specified, these situations result in terminating errors. Important: If there is an existing application with the same SiteName/VirtualDirectory and -Force is specified, it will be removed.
|
n/a | |
| 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
displayName
|
|
| 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
jsonWebKeySetUri
|
|
| 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
providerType
|
|
| Optional. How long in minutes after login a session is considered valid. The default value is 60. |
authentication
sessionExpirationMinutes
|
||
| OAuth type Auth0 |
Required for OAuth authentication of type Auth0. The sign out URL of 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
signOutUrl
|
|
|
-SiteName
|
Optional. The name of the IIS Site to create the application under. The default value is Default Web Site. This site must exist before installation. 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 | |
|
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
|
connectionStrings
username
AND connectionStrings
password
OR connectionStrings
existingSecretKey
AND connectionStrings
existingSecretName
|
||
| Required. A string specifying the FQDN of the SQL server which will host the AnyCAGateway REST SQL database. |
connectionStrings
hostname
OR connectionStrings
existingSecretKey
AND connectionStrings
existingSecretName
|
||
| OAuth |
Only required when an identity provider configuration is not provided. The authentication scheme of the provider to tie to the SuperAdmin Claim. Defaults to the authentication scheme of the provided identity provider. |
authentication
superAdmin
provider
|
|
| 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. Supported values are:
For OAuth authentication, free-form OAuth claim types in the format OAuth_<claim name> where claim name is any of the standard OAuth claims. Valid OAuth claim types include OAuth_sub and OAuth_aud. Used to provide OAuth authentication with a different admin value for superadmin. Note: The value entered is case-sensitive. For example, the X in X509Certificate_Thumbprint must be capitalized.
|
authentication
superAdmin
type
|
|
| 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 (for example, 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 on login to the portal (see Login Claim 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 user will be directed to the appropriate authentication login page and then redirected to the AnyCAGateway REST portal. 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
|
|
|
-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 value is 60. |
authentication
oauth
parameters
timeout
|
|
-TokenEndpoint
|
OAuth |
Required for OAuth authentication. A string containing the token endpoint of the identity provider. For example: https://appsrvr18 .keyexample.com:1443/realms/ Keyfactor/ protocol/ openid-connect/ token
|
authentication
oauth
parameters
tokenEndpoint
|
| 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 | |
| OAuth |
Only required if a user info endpoint is found in the discovery document. A string containing the user info endpoint of the identity provider. For example: https://appsrvr18 .keyexample.com:1443/realms/Keyfactor/ protocol/ openid-connect/ userinfo
|
authentication
oauth
parameters
userInfoEndpoint
|
|
| 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 | ||
| 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
oidcAudience
|
|
|
-VirtualDirectory
|
Optional. The virtual directory for the application that is created under SiteName. This is used as the base path for the URL of the webserver. The URL of the gateway will be https://<fqdn>/<virtual-directory>). If there is an existing application with the same SiteName/VirtualDirectory and -Force is specified, it will be removed. The default value is AnyGatewayREST. 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.
|
Was this page helpful? Provide Feedback