Additional Utility Scripts

Note:  These instructions apply only to Windows installations.

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

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

Table 963: AddOrUpdateIdentityProvider.ps1 Parameters

Parameters Description
Server Required. The FQDN of the machine hosting SQL server.
Database Required. The name of the database used by the gateway.
UseSqlAuth Required. Specify if the connection to the database should use SQL authentication.
SqlCredentials Required if UseSQLAuth is true. PSCredential of the sql user login to use when connecting to the database.
ConnectionStringTemplate Optional. A template to use when building the SQL connection strings to allow passing in additional values to the string.
AuthenticationScheme Required.The Authentication Scheme for the IdP.
DisplayName Required to create a new IdP, otherwise optional. The display name of the IdP.
ProviderType Required to create a new IdP, otherwise optional. The type of the OAuth provider ('Generic' or ‘Auth0’)
NameClaimType Required to create a new IdP, otherwise optional. The claim type to use for the users' display names.
ClientId Required to create a new IdP, otherwise optional. The client ID of the IdP.
ClientSecret Required to create a new IdP, otherwise optional. A PSSecureString of the client secret of the IdP.
Authority Required to create a new IdP, otherwise optional. The authority of the IdP.
OIDCAudience Optional. The Authority of the IdP.
SignOutUrl Required to create a new IdP, and ProviderType is Auth0, otherwise optional. The sign out URL to use for the IdP
Auth0ApiUrl Required to create a new IdP, and ProviderType is Auth0, otherwise optional. The API URLfor the IdP
AuthorizationEndpoint Required to create a new IdP. The authorization endpoint for the IdP.
TokenEndpoint Required to create a new IdP. The token endpoint for the IdP.
JSONWebKeySetUri Required to create a new IdP. The JSONWebKeySetUri for the IdP.
UserInfoEndpoint Required to create a new IdP, and the IdP's discovery document contains a UserInfo endoint. The user info endpoint for the IdP .
DisableBearerTokenScopeRequirement Optional. If true, disable the bearer token scope requirement.

Example:  Sample Script
Copy

                   
$server = " "
$database = " "
$connectionStringTemplate = " "
$authScheme = " "
$displayName = " "
$type = " "
$nameClaimType = " "
$clientId = " "
$authority = " "
$authEndpoint = " "
$tokenEndpoint = " "
$userInfoEndpoint = " "
$jsonWebKeySetUri = " "
$signOutUrl = " "
$auth0ApiUrl = " "
$disableBearerTokenScope = " "
$oidcAudience = " "
$sqlUsername = " "
$sqlPassword = " "
$clientSecretString = " "
$sqlCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList ($sqlUsername, (ConvertTo-SecureString $sqlPassword -AsPlainText -Force))
$clientSecret = ConvertTo-SecureString $clientSecretString -AsPlainText -Force
.\AddOrUpdateIdentityProvider.ps1 
    -Server $server,
    -Database $database,
    -ConnectionStringTemplate $connectionStringTemplate,
    -UseSqlAuth "true",
    -SqlCredentials $sqlCredentials,
    -AuthenticationScheme $authScheme,
    -ClientSecret $clientSecret,
    -DisplayName $displayName,
    -ProviderType $type,
    -NameClaimType $nameClaimType,
    -ClientId $clientId,
    -Authority $authority,
    -AuthorizationEndpoint $authEndpoint,
    -TokenEndpoint $tokenEndpoint,
    -UserInfoEndpoint $userInfoEndpoint,
    -JSONWebKeySetUri $jsonWebKeySetUri,
    -SignOutUrl $signOutUrl,
    -Auth0ApiUrl $auth0ApiUrl,
    -DisableBearerTokenScopeRequirement $disableBearerTokenScope,
    -OIDCAudience $oidcAudience

An OAuth script that accepts an IdP authentication scheme and a PSSecureString client secret and updates the given IdP's client secret.

Table 964: RotateClientSecret.ps1 Parameters

Parameter Description
Server Required. The FQDN of the machine hosting SQL server.
Database Required. The name of the database used by the gateway.
SqlCredentials Required if UseSQLAuth is true. PSCredential of the sql user login to use when connecting to the database.
ConnectionStringTemplate Optional. A template to use when building the SQL connection strings to allow passing in additional values to the string.
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.

Sample Script
Example:  Sample Script
Copy
$server = " "
$database = " "
$connectionStringTemplate = " "
$authScheme = " "
$sqlUsername = " "
$sqlPassword = " "
$clientSecretString = " "
$sqlCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList ($sqlUsername, (ConvertTo-SecureString $sqlPassword -AsPlainText -Force))
$clientSecret = ConvertTo-SecureString $clientSecretString -AsPlainText -Force
.\RotateClientSecret.ps1,
    -Server $server,
    -Database $database,
    -ConnectionStringTemplate $connectionStringTemplate,
    -UseSqlAuth "true",
    -SqlCredentials $sqlCredentials,
    -AuthenticationScheme $authScheme,
    -ClientSecret $clientSecret

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 965: CreateOAuthSuperAdmin.ps1 Parameters

Parameter Description
Server Required. The FQDN of the machine hosting SQL server.
Database Required. The name of the database used by the gateway.
UseSqlAuth Required. Specify if the connection to the database should use sql auth.
SqlCredentials Required if UseSQLAuth is true. PSCredential of the sql user login to use when connecting to the database.
ConnectionStringTemplate Optional. A template to use when building the SQL connection strings to allow passing in additional values to the string.
ClientSecret Required to create a new IdP, otherwise optional. A PSSecureString of the client secret of the IdP.
Provider Required.The Authentication Scheme for the IdP.
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.
Example:  Sample Script
Copy

$server = " "
$database = " "
$connectionStringTemplate = " "
$provider = " "
$type = "OAuth_ "
$value= " "
$sqlCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList ($sqlUsername, (ConvertTo-SecureString $sqlPassword -AsPlainText -Force))
.\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 966: 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.
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 967: UpdateRootCertificate.ps1 Parameters

Parameter Description
RootCAFilePath Required. The file path to the new Root CA for the gateway to use.
Example:  Sample Script
Copy
./UpdateRootCertificate.ps1 -RootCAFilePath "C:\certs\root.pem"