Scripted Authentication

Enabling Scripted Authentication 

Scripted Authentication can be enabled for a connection by providing a command line to run in the 'Auth Script Command' field in the Connection Properties screen. This command will be triggered by RED when it needs to authenticate with this connection for the first time and then again whenever the 'Auth Expires After' minutes is exceeded.

Auth Script Command field

For the initial RED Login Screen you also have the option of supplying an Auth Script Command, this will be automatically populated if your selected RED Profile has previously stored this:

Typical Script Based Authentication Workflow

When RED executes the 'Auth Script Command' this is the typical workflow: 

1. RED UI
   1. Saves the current RED Profile to disk and provides access to this Profile file and the connection name requiring authentication via environment variables.
   2. Runs the 'Auth Script Command'
2. Authentication Script
   1. Reads the RED Profile and retrieves any required Connection details from it.
   2. Performs the required authentication workflow for the connection.
   3. Updates the RED Profile on disk with refreshed Auth Tokens, Expires After mins and other Auth Configuration values as required. 
3. RED UI
   1. Merges the updated RED Profile file back into the in-memory Profile.
   2. Completes the authentication process for the connection.
   3. Resets the internal expiry for the connection based on 'Auth Expires After' mins. 

Auth Script Environment Variables

RED will set the following Environment Variables for the Auth Script Command execution.

These are the minimum set that can be relied on in all cases, but the usual WSL_TGT_* and WSL_META_* variables will also be provided when the authentication process is initiated after RED login.

WSL_TGT_* vars are set to the context of the connection being authenticated to. If your script relies on other variables to be set it is best to fall back to extracting from the Profile file when these are not set in the environment and for some situations your script may also need to acquire attributes from the ODBC DSN itself.

Auth Script Output Protocol

RED relies on Exit Code only, it is expected the script will report any errors to the user interactively or via it's own logging mechanisms.

Exit Codes

• 0 = Success, this signals to RED that it should continue with the authentication attempt.
• Non-Zero = Failure, currently ignored by RED, meaning the authentication process will still be attempted, except from the RED Login where RED simply returns to the login page.

Script Output 

• All Auth Script output streams are currently ignored by RED

Auth Script Command Usage - PowerShell Examples

The examples here use the following sample PowerShell project, which can be unzipped to a local directory on a system running RED.

ws_auth_v1.0.0.zip - MD5 hash of ws_auth_v1.0.0.zip: bbaf40e8adb558b4e834fa922478f560

In one of your connections in RED you can test the Scripted Authentication process by setting an Auth Script Command and a non-zero Auth Expires After setting, then browsing the connection to initiate the authentication process.

The sample PowerShell based authentication project has a main script and a set of modules, the main script can be extended with your own authentication types as required.

Script name and parameters

Name:

• ws_auth.ps1

Parameters: 

• AuthType - from:"Snowflake-MFA", "Snowflake-KeyPair", "Test-mode" [Default if not specified]

• LogLevel - from:"DEBUG", "INFO", "WARN", "ERROR", "FATAL" - Defaults to INFO

Logging:

This script produces logging based on the LogLevel setting, the log file will be created in the current user's temp directory with the name 'ws_auth.log'. This location can be found in Windows by typing %TEMP% in an explorer window.

Example script commands

ws_auth Test-mode

PowerShell -ExecutionPolicy bypass -f "c:\temp\ws_auth\ws_auth.ps1" -AuthType "Test-mode" -LogLevel    "DEBUG"

When executed by RED's authentication process this mode produces a dialog which provides the ability to change all fields except Auth Configuration JSON.
Test-modeTest-mode Connection mapping

ws_auth Snowflake-MFA

PowerShell -ExecutionPolicy bypass -f "c:\temp\ws_auth\ws_auth.ps1" -AuthType "Snowflake-MFA" -LogLevel    "DEBUG"

This mode produces a dialog which provides the ability to set a TOPT passcode and uses the Test ODBC functionality to establish an initial connection.

This mode should be used in conjunction with a connection string in your Snowflake connection set to: 

• dsn=$DSN$;uid=$USER$;pwd=$PASSWORD$$AUTHTKN_1$;passcodeInPassword=on;

Snowflake MFA

ws_auth Snowflake-KeyPair

PowerShell -ExecutionPolicy bypass -f "c:\temp\ws_auth\ws_auth.ps1" -AuthType "Snowflake-KeyPair" -LogLevel "DEBUG"

This mode produces a dialog which provides the ability to set a Key-Pair attributes and uses the 'Test on exit' functionality to establish an initial connection. 

NOTE: Key-Pair auth would not necessarily require a pop-up dialog at all, this is just provided as another example of how use the scripted authentication feature and how the new Auth Token fields work with connection strings. To actually use Key-Pair auth you can simply leave the Auth Script Command blank and use the Auth Token fields directly from the RED UI.

This mode should be used in conjunction with a connection string in your Snowflake connection set to: 

• dsn=$DSN$;uid=$USER$;authenticator=SNOWFLAKE_JWT;priv_key_file_pwd=$PASSWORD$;priv_key_file=$AUTHTKN_1$;