Install AnyCAGateway REST on Windows
Before you begin the installation, make sure that you have reviewed the system requirements and completed the prerequisites (see Preparing).
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.
The PowerShell install script for the AnyCAGateway REST runs the Database Management Console tool to create the database and manages the installation and configuration of the AnyCAGateway REST as a Windows service.
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:\MyFiles\AnyGatewayRESTInstall\ AnyGatewayREST\ net8.0\ 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. See the examples in Sample Install Commands.
Sample Install Commands
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 = "<ql-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>"
$SSLCertPassword = "<ssl-cert-password>"
$SSLCertPath = "<ssl-cert-path>"
$AuthCAName = "<auth-ca-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))
$SSLCertPasswordSecureString = ConvertTo-SecureString $SSLCertPassword -AsPlainText -Force
-
Run the 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 "false" -SQLServerName $SQLServerName -DatabaseName $DBName -UseSQLAuth "true" -SQLAuthCredentials $SQLAuthCredentials -DatabaseManagementUsesSQLAuth "true" -DatabaseManagementAuthCredentials $DatabaseManagementAuthCredentials -ServerPort "8443" -ServerCertificatePath $SSLCertPath -ServerCertificatePassword $SSLCertPasswordSecureString -AuthCAName $AuthCAName -AuthCAFilePath $AuthCAFilePath -SuperAdminType "X509Certificate_SerialNumber" -SuperAdminValue $SuperAdminSerialNumber -ServiceSuffix "MyCCCA" -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 = "<ql-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>"
$SSLCertPassword = "<ssl-cert-password>"
$SSLCertPath = "<ssl-cert-path>"
$IdpName = "<idp-name>"
$AuthScheme = "<idp-auth-scheme>"
$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"
$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))
$SSLCertPasswordSecureString = ConvertTo-SecureString $SSLCertPassword -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 certificate file.Copy
.\AnyCAGatewayInstall.ps1 -UseOAuth "true" -DefaultIdentityProviderAuthScheme $DefaultIdentityProviderAuthScheme -SQLServerName $SQLServerName -DatabaseName $DBName -UseSQLAuth "true" -SQLAuthCredentials $SQLUserPSCredential -DatabaseManagementUsesSQLAuth "true" -DatabaseManagementAuthCredentials $DatabaseManagementAuthCredentials -ServerPort "8443" -ServerCertificatePath $SSLCertPath -ServerCertificatePassword $SSLCertPasswordSecureString -IdentityProviderName $IdpName -OAuthType "Generic" -AuthenticationScheme $AuthScheme -Authority $IdpAuthority -ClientId $ClientId -ClientSecret $ClientSecretSecureString -DisplayNameClaimType "preferred_username" -AuthorizationEndpoint $AuthorizationEndpoint -TokenEndpoint $TokenEndpoint -JSONWebKeySetURI $JSONWebKeySetURI -UserInfoEndpoint $UserInfoEndpoint -SuperAdminType $SuperAdminType -SuperAdminValue $SuperAdminValue -Force
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 = "<ql-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>"
$SSLCertPassword = "<ssl-cert-password>"
$SSLCertPath = "<ssl-cert-path>"
$IdpName = "<idp-name>"
$AuthScheme = "<idp-auth-scheme>"
$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))
$SSLCertPasswordSecureString = ConvertTo-SecureString $SSLCertPassword -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 certificate file.Copy
.\AnyCAGatewayInstall.ps1 -UseOAuth "true" -DefaultIdentityProviderAuthScheme $DefaultIdentityProviderAuthScheme -SQLServerName $SQLServerName -DatabaseName $DBName -UseSQLAuth "true" -SQLAuthCredentials $SQLUserPSCredential -DatabaseManagementUsesSQLAuth "true" -DatabaseManagementAuthCredentials $DatabaseManagementAuthCredentials -ServerPort "8443" -ServerCertificatePath $SSLCertPath -ServerCertificatePassword $SSLCertPasswordSecureString -IdentityProviderName $IdpName -OAuthType "Auth0" -AuthenticationScheme $AuthScheme -Authority $IdpAuthority -ClientId $ClientId -ClientSecret $ClientSecretSecureString -SignOutURL $SignOutURL -Auth0APIUrl $Auth0APIURL -DisplayNameClaimType "preferred_username" -AuthorizationEndpoint $AuthorizationEndpoint -TokenEndpoint $TokenEndpoint -JSONWebKeySetURI $JSONWebKeySetURI -UserInfoEndpoint $UserInfoEndpoint -SuperAdminType $SuperAdminType -SuperAdminValue $SuperAdminValue -Force
AnyCAGateway REST Windows Install Parameters
Installation parameters for the AnyCAGateway REST on Windows are shown in Table 956: 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 956: AnyCAGateway REST Windows Install Parameters
Parameter | Description | Notes | Container Values File Equivalent |
---|---|---|---|
-Auth0 Api Url |
Required for OAuth authentication of type Auth0. The Auth0 API URL for the identity provider. For example: https:// keyfactorAPI.com
|
Used for OAuth authentication of type Auth0 only. |
authentication oauth parameters |
-AuthCA File Path | Required for client cert 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. | Used for client certificate authentication only. | n/a |
-AuthCA Name | Required for client cert 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. | Used for client certificate authentication only. | n/a |
-Authentication Scheme | 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. | Used for OAuth authentication only. |
authentication oauth |
-Authority |
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/
|
Used for OAuth authentication only. |
authentication oauth parameters authority |
-Authorization Endpoint |
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
|
Used for OAuth authentication only. |
authentication oauth parameters |
-ClientId | 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. | Used for OAuth authentication only. |
authentication oauth parameters |
-Client Secret |
Required for OAuth authentication. A PowerShell secure string containing the client secret for the identity provider. For example: ConvertTo-SecureString "<your-secret>" -AsPlainText -Force
|
Used for OAuth authentication only. |
authentication oauth parameters |
-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 | |
-Cookie Expiration Minutes | Optional. How long in minutes after login a cookie should be expired. The default value is 5. |
authentication |
|
-Database Management Uses SQLAuth | Required. If true, the Database Management Console will use SQL Auth when servicing the database. | n/a | |
-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 AND dbmanagement AND dbmanagement |
|
-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 as Windows services on the same server, set -DatabaseName, -Destination, -ServiceSuffix, and -ServerPort to unique values for each additional gateway service.
|
connection Strings database OR AND |
|
-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 as Windows services on the same server, set -DatabaseName, -Destination, -ServiceSuffix, and -ServerPort to unique values for each additional gateway service.
|
n/a | |
-Default Identity Provider Auth Scheme | 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 |
Used for OAuth authentication only. |
authentication |
-Disable Bearer Token Scope Requirement |
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, 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.
|
Used for OAuth authentication only. |
authentication oauth parameters |
-Display Name Claim Type |
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. |
Used for OAuth authentication only. |
authentication oauth parameters |
-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. | n/a | |
-Identity Provider Name | 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. | Used for OAuth authentication only. |
authentication oauth |
-JSON WebKey SetUri |
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
|
Used for OAuth authentication only. |
authentication oauth parameters |
-OAuthType | 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. | Used for OAuth authentication only. |
authentication oauth |
-Session Expiration Minutes | Optional. How long in minutes after login a session is considered valid. The default value is 60. |
authentication |
|
-Server Certificate Password |
Required. The password for the PFX file specified with the -ServerCertificatePath parameter. If not supplied in the install command, it will be prompted for during the install. The password must be provided as a SecureString. For example: ($Secure_String_Pwd = ConvertTo-SecureString "MySecurePFXPassword" -AsPlainText -Force)
|
ingress |
|
-Server Certificate Path | Required. The file path of the location of the certificate PFX file for the AnyCAGateway REST server TLS (SSL) connection (as identified in AnyCAGateway REST TLS (SSL) Certificate). Both the private and public key need to be available for the certificate. You will be prompted for the password when the install script runs, if you don’t provide a value in -ServerCertificatePassword. |
ingress |
|
-Server Port |
Optional. The port number to access the AnyCAGateway REST portal from a browser. The value must be unique. This becomes a part of the URL for the AnyCAGateway REST portal (with -SQLServerName). The default value is 8443. Note: When installing multiple instances of the AnyCAGateway REST as Windows services on the same server, set -DatabaseName, -Destination, -ServiceSuffix, and -ServerPort to unique values for each additional gateway service.
|
n/a | |
-Service Credential |
Optional. PSCredential object containing the username/password of the account that the service will run as. If using Windows Auth, this account will be used to connect to the database. For example, $creds = Get-Credential. By default, the service runs as NT AUTHORITY\Network Service. |
n/a | |
-Service Suffix |
Optional. The suffix to append to the Window’s service name Keyfactor AnyCAGateway Service - for this installation of the AnyCAGateway REST. This is primarily for use when installing multiple AnyCA Gateways as Windows services on the same machine. It will display in parenthesis (e.g. (Default)). The default value is Default. Note: When installing multiple instances of the AnyCAGateway REST as Windows services on the same server, set -DatabaseName, -Destination, -ServiceSuffix, and -ServerPort to unique values for each additional gateway service.
|
n/a | |
-Sign Out Url |
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
|
Used for OAuth authentication of type Auth0 only. |
authentication oauth parameters |
-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 password OR AND |
|
-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 AND |
|
-Super Admin Type |
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—either X509Certificate_Thumbprint, or 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. Note: The value entered is case-sensitive (i.e., the X must be capitalized).
|
Used to provide OAuth authentication with a different admin value for superadmin. |
authentication superAdmin type |
-Super Admin Value |
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. |
Used for both client certificate authentication and OAuth authentication with different values. |
authentication superAdmin value |
-Super Admin Provider |
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. |
Used for OAuth authentication only. |
authentication superAdmin provider |
-TokenEndpoint |
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
|
Used for OAuth authentication only. |
authentication oauth parameters |
-Use 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. | Used for OAuth authentication only. | n/a |
-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 | |
-UserInfo Endpoint |
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
|
Used for OAuth authentication only. |
authentication oauth parameters |
-Valid Audience | 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. | Used for OAuth authentication only. |
authentication oauth parameters |