Additional Utility Scripts

In addition to the updates made to the primary install script, some supplementary scripts have been added to the AnyCAGateway REST install folder.

See Install of AnyCAGateway REST as Windows Service for information on installing AnyCAGateway RESTas a windows service.

An OAuth script that takes the given IdP parameters and calls the database management console to either create or update the IdP.

Table 1056: AddOrUpdateIdentityProvider.ps1 Parameters

Parameters Description
Auth0ApiUrl Required to create a new identity provider, and ProviderType is Auth0, otherwise optional. The API URLfor the identity provider. This parameter is only used when Auth0 is selected at the provider type.
AuthenticationEnabled

Optional. True/False. This allows identity providers to be disabled and (re-)enabled in the AnyCAGateway REST. Optional, but set to true by default if not explicitly set.

Note:  Identity providers cannot be False/disabled if the provider is used as the default identity provider for login in the appsettings.json file. Users cannot authenticate with identity providers that are False/disabled.
AuthenticationScheme Required.The Authentication Scheme for the identity provider.
Authority Required to create a new identity provider, otherwise optional. The authority of the identity provider.
AuthorizationEndpoint Required to create a new identity provider. The authorization endpoint for the identity provider.
ClientId Required to create a new identity provider, otherwise optional. The client ID of the identity provider.
ClientSecret Required to create a new identity provider, otherwise optional. A PSSecureString of the client secret of the identity provider.
ConnectionStringTemplate Optional. A template to use when building the SQL connection strings to allow passing in additional values to the string.
Database Required. The name of the SQL database used by the gateway.
DisableBearerTokenScopeRequirement Optional. If true, disable the bearer token scope requirement.
DisplayName Required to create a new identity provider, otherwise optional. The display name of the identity provider.
JSONWebKeySetUri Required to create a new identity provider. The JSONWebKeySetUri for the identity provider.
NameClaimType Required to create a new identity provider, otherwise optional. The claim type to use for the users' display names.
OIDCAudience Optional. The audience value for tokens issued from the identity provider.
ProviderType Required to create a new identity provider, otherwise optional. The type of the OAuth identity provider (Generic or Auth0).
Server Required. The FQDN of the machine hosting SQL server.
SignOutUrl Required to create a new identity provider, and ProviderType is Auth0, otherwise optional. The sign out URL to use for the identity provider. This parameter is only used when Auth0 is selected at the provider type.
SqlCredentials Required if UseSQLAuth is true. PSCredential of the SQL user login to use when connecting to the database.
TimeoutSeconds Optional. The number of seconds a request to the OAuth identity provider is allowed to process before timing out with an error.
TokenEndpoint Required to create a new identity provider. The token endpoint for the identity provider.
UserInfoEndpoint Required to create a new identity provider, and the identity provider's discovery document contains a UserInfo endoint. The user info endpoint for the identity provider.
UseSqlAuth Required. Specify if the connection to the database should use SQL authentication.

Example:  Sample Script
Copy
# Populate variables
$server = "YourSQLServer"
$database = "YourSQLDatabase"
$connectionStringTemplate = "YourOptionalSQLConnectionStringTemplate"
$authScheme = "YourIdPProviderName"
$displayName = "YourIdPDisplayName"
$type = "Generic"
$nameClaimType = "preferred_username"
$clientId = "RESTGateway"
$authority = "https://appsrvr18.keyexample.com:1443/realms/Keyfactor"
$authEndpoint = "https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/auth"
$tokenEndpoint = "https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token"
$userInfoEndpoint = "https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/userinfo"
$jsonWebKeySetUri = "https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/certs"
$disableBearerTokenScope = "true"

$sqlUsername = "YourSQLUsername"
$sqlPassword = "YourSQLPassword"
$clientSecretString = "YourClientSecret"

# Convert credentials to secure strings
$sqlCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList ($sqlUsername, (ConvertTo-SecureString $sqlPassword -AsPlainText -Force))
$clientSecretSecureString = ConvertTo-SecureString $clientSecretString -AsPlainText -Force

# Execute the script
.\AddOrUpdateIdentityProvider.ps1 `
    -Server $server `
    -Database $database `
    -ConnectionStringTemplate $connectionStringTemplate `
    -UseSqlAuth $true `
    -SqlCredentials $sqlCredentials `
    -AuthenticationScheme $authScheme `
    -ClientSecret $clientSecretSecureString `
    -DisplayName $displayName `
    -ProviderType $type `
    -NameClaimType $nameClaimType `
    -ClientId $clientId `
    -Authority $authority `
    -AuthorizationEndpoint $authEndpoint `
    -TokenEndpoint $tokenEndpoint `
    -UserInfoEndpoint $userInfoEndpoint `
    -JSONWebKeySetUri $jsonWebKeySetUri `
    -DisableBearerTokenScopeRequirement $disableBearerTokenScope

A script that accepts an OAuth identity provider authentication scheme and a PSSecureString client secret and updates the given identity provider's client secret.

Table 1057: RotateClientSecret.ps1 Parameters

Parameter Description
ClientSecret Required to create a new IdP, otherwise optional. A PSSecureString of the client secret of the IdP.
ConnectionStringTemplate Optional. A template to use when building the SQL connection strings to allow passing in additional values to the string.
Database Required. The name of the database used by the gateway.
Server Required. The FQDN of the machine hosting SQL server.
SqlCredentials Required if UseSQLAuth is true. PSCredential of the sql user login to use when connecting to the database.
UseSqlAuth Required. Specify if the connection to the database should use sql auth.
Example:  Sample Script
Copy
# Populate variables
$server = "YourSQLServer"
$database = "YourSQLDatabase"
$connectionStringTemplate = "YourOptionalSQLConnectionStringTemplate"
$authScheme = "YourIdPProviderName"
$sqlUsername = "YourSQLUsername"
$sqlPassword = "YourSQLPassword"
$clientSecretString = "YourNewClientSecret"

# Convert credentials to secure strings
$sqlCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList ($sqlUsername, (ConvertTo-SecureString $sqlPassword -AsPlainText -Force))
$clientSecretSecureString = ConvertTo-SecureString $clientSecretString -AsPlainText -Force

# Execute the script
.\RotateClientSecret.ps1 `
    -Server $server `
    -Database $database `
    -ConnectionStringTemplate $connectionStringTemplate `
    -UseSqlAuth $true `
    -SqlCredentials $sqlCredentials `
    -AuthenticationScheme $authScheme `
    -ClientSecret $clientSecretSecureString

An OAuth script that accepts a given SuperAdmin config and creates an admin and user claim for the user by calling the DatabaseManagementConsole.exe.

Table 1058: CreateOAuthSuperAdmin.ps1 Parameters

Parameter Description
ConnectionStringTemplate Optional. A template to use when building the SQL connection strings to allow passing in additional values to the string.
SqlCredentials Required if UseSQLAuth is true. PSCredential of the sql user login to use when connecting to the database.
ClientSecret Required to create a new IdP, otherwise optional. A PSSecureString of the client secret of the IdP.
UseSqlAuth Required. Specify if the connection to the database should use sql auth.
Server Required. The FQDN of the machine hosting SQL server.
Database Required. The name of the database used by the gateway.
Type Required. The token claim to use for the new user. Must start with OAuth_.
Value Required. The value of the token claim to use.
Provider Required.The Authentication Scheme for the IdP.
Example:  Sample Script
Copy
# Populate variables
$server = "YourSQLServer"
$database = "YourSQLDatabase"
$connectionStringTemplate = "YourOptionalConnectionStringTemplate"
$sqlUsername = "YourSQLUsername"
$sqlPassword = "YourSQLPassword"
$authScheme = "YourIdPProviderName"
$type = "OAuth_sub"
$value= "YourNewAdminUsersSub"

# Convert credentials to secure string
$sqlCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList ($sqlUsername, (ConvertTo-SecureString $sqlPassword -AsPlainText -Force))

# Execute script
.\CreateOAuthSuperAdmin.ps1 `
    -Server $server `
    -Database $database `
    -ConnectionStringTemplate $connectionStringTemplate `
    -UseSqlAuth $true `
    -SqlCredentials $sqlCredentials `
    -Provider $authScheme `
    -Type $type `
    -Value $value

A client certificate authentication script that accepts a client cert superadmin configuration and updates the appsettings.json with these values.

Table 1059: UpdateClientCertSuperAdmin.ps1 Parameters

Parameter Description
Type Required. The type of the SuperAdmin claim - eitherX509Certificate_SerialNumber or X509Certificate_Thumbprint.
Value Required.The value of the thumbprint or serial number of the certificate claim.
UseKestrel If provided, the windows service corresponding to the AnyCA Gateway REST installation will be restarted to apply changes. Otherwise, the application pool associated with the IIS application for the installation will be restarted, if it exists.
Example:  Sample Script
Copy
./UpdateClientCertSuperAdmin.ps1 -Type "X509Certificate_SerialNumber" -Value "ABC1230000000"

A client certificate authentication script that accepts a new root caClosed 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. file path and copies it to the configuration folder and changes the file path of the configured authca in the appsettings.json.

Table 1060: UpdateRootCertificate.ps1 Parameters

Parameter Description
RootCAFilePath Required. The file path to the new Root CA for the gateway to use.
UseKestrel If provided, the windows service corresponding to the AnyCA Gateway REST installation will be restarted to apply changes. Otherwise, the application pool associated with the IIS application for the installation will be restarted, if it exists.
Example:  Sample Script
Copy
./UpdateRootCertificate.ps1 -RootCAFilePath "C:\certs\root.pem"