Creating Custom Launchers

This guide walks you through the process of creating a custom launcher, including defining launcher settings, and specifying command-line parameters. Follow the steps below to build a launcher that fits your organization’s unique needs.

Procedure

See Custom Launcher Errors if errors arise.

To create a new custom launcher:

  1. Search for and select Secret Templates. The Secret Templates page appears.

  2. Access the Launchers tab.

  3. Click the Create button. The New Launcher page appears.

  4. Configure the page as needed, see Settings below for details.

  5. Click the Save button.

See the following section for details on General, Windows and Mac settings.

Settings

Not all of the following settings are available for all types of launchers.

General Settings

The following settings are available in the General Settings section:

  • Launcher Type: you can select either Process, Batch File, Proxied SSH Process, or the Session Connector Launcher.

  • Launcher Name: Name of the launcher that is displayed to the user.

  • State: Whether the launcher is active for use.

  • Use Additional Prompt: If selected, the user is prompted for additional information when using the launcher. When selected, the Additional Prompt Field Name text box appears.

    This option is mutually exclusive with Use SSH Tunneling with SSH Proxy.

  • Additional Prompt Field Name: Name of the text field providing the prompt when the user activates the launcher. This value can be referenced in the process arguments with a $ prefix.

After selecting a launcher type, a combination of the following additional fields appears:

  • Track Multiple Windows: When this checkbox is selected, all visible windows of the primary process, not just the primary window of the primary process, are tracked. This helps record applications with multiple windows or dialog boxes. In addition, if the primary process (or one of its children) spawns child processes, any visible windows are recorded too.

    For example, if you run cmd.exe and then the notepad.exe application from the command prompt, notepad is recorded along with the command prompt. This checkbox is enabled by default. Enabling this setting is a prerequisite for Record Additional Processes.

  • Record Additional Processes: Add a comma-separated list of additional process names to record if they are running. When a launcher is in progress and recording, any visible windows from the listed processes are also recorded. This only applies to processes running in your session—other users running the same process are not recorded. The processes themselves are not affected—they remain running after the launch is finished. This setting is only active if Record Multiple Windows is enabled too.

  • Wrap Custom Parameters with Quotation Marks: This setting wraps the variables in the process argument fields with quotation marks. This is a security and disambiguation feature.

    For example, given these process arguments:

    --host=$HOST --port=$PORT --username=$USERNAME --password=$PASSWORD

    With no quotation mark wrap, the problematic process arguments for a launcher mapped to a secret might look like this:

    --host=xyz --port=123 --username=user --password=x x x

    The final parameter would be ambiguous, causing the last three characters to be misinterpreted, with the process thinking a single "x" is the password. Text could be injected, causing the value to be interpreted as another parameter, resulting in a security issue. Wrapping the parameter values fixes these potential problems:

    --host="xyz" --port="123" --username="user" --password="x x x"

    This checkbox is selected by default.

  • Preserve SSH Client Process: When enabled, the proxy session and SSH client process will not be terminated and closed if the process launched is exited. This allows tabbed SSH clients to be used.

  • Use SSH Tunneling with SSH Proxy: When enabled and the launcher is mapped to a secret template, the user can select host and port fields. You can provide a default port, which can be referenced using $HOST and $PORT in the process arguments. If the launching secret has proxying enabled and a Secret Server SSH proxy is available, those process arguments are replaced with SSH tunnel values (localhost [127.0.0.1] and a random port).

    This causes the launched process to connect to the local tunnel, and traffic then flows from the client to the Secret Server SSH proxy, which connects to the real endpoint. This is useful when users are not allowed to directly connect to the endpoint but Secret Server or distributed engines can.

    The checkbox is disabled by default. This option is mutually exclusive with Use Additional Prompt.

    To use this feature, you must first map the host and port fields when you map the launcher to a template. To do so, edit the secret template and click Configure Launcher.

  • Use SFTP Tunneling with SSH Proxy: Enable this setting when using SFTP to allow multiple data connections through the SSH Proxy. Many SFTP clients will not function correctly without this being enabled.

Windows Settings

The following settings are available in the Windows Settings section:

  • Process Name: Name of the process that is launched. Example: PowerShell.

  • Process Arguments: Process arguments depend on the process that is being launched. View the built-in SQL Server launcher for examples on how the text-entry fields are substituted. For greater flexibility, other secrets can be linked in the Launcher tab onto the secret. The text-entry field values from those secrets can also be used in the process arguments using the same prefix $[1][FieldName] syntax as the SSH custom commands.

    There is a launcher-specific token $SESSIONKEY that can be passed to the command line. This passes an identifier to the customer launcher that can be used to anonymously check-in the secret using the CheckInSecretByKey Web service method.

    Example: -user $USERNAME -pwd $PASSWORD -f. See Custom Launcher Process Arguments for details.

  • Run Process as Secret Credentials: This option allows the process to authenticate with the secret credentials (username, domain, and password) instead of the client user that is using the launcher. This can be overridden at the secret level to use a privileged account to run the process.
  • Use Operating System Shell: this option allows for the use of the OS shell for the launcher. Useful for processes requiring UAC Confirmation.
  • Escape Character: Enter the character to use as an escape character in passwords. Escape characters are required to allow the use of characters that are otherwise not allowed in passwords because they have special meaning to the launcher's target application.
  • Characters to Escape: Enter the characters that require escaping for the target application.
  • Batch file: Upload the batch file needed when the launcher is initiated.

Mac Settings

The following settings are available in the Mac Settings section:

  • Process Name: Name of the process that is launched. Example: /Applications/TextEdit.app/Contents/MacOS/TextEdit.

  • Process Arguments: Process arguments depend on the process that is being launched. View the built-in SQL Server launcher for examples on how the text-entry fields are substituted. For greater flexibility, other secrets can be linked in the Launcher tab onto the secret. The text-entry field values from those secrets can also be used in the process arguments using the same prefix $[1][FieldName] syntax as the SSH custom commands.

    There is a launcher-specific token $SESSIONKEY that can be passed to the command line. This passes an identifier to the customer launcher that can be used to anonymously check-in the secret using the CheckInSecretByKey Web service method.

    Example: -user $USERNAME -pwd $PASSWORD -f. See Custom Launcher Process Arguments for details.

  • Shell Script: Upload the script file needed when the launcher is initiated.