Installing Panel Service

This article describes how to install the Panel Service agent for Identity Panel. This article applies to both hosted and on-premises installations.

Advanced Scenarios

This article also covers certain advanced installation scenarios including:

• Install at a non-standard location (such as a different drive)
• Running Panel Service as a GMSA
• Manual Installation
• Automated Installation

Obtaining and Running the Installer

The Panel Service installer may be obtained by downloading it from the Identity Panel application itself, at Settings / Install Service, then pressing "Download Installer". Alternatively, when scripting installs, a direct URL to the installer may be used: https://host-name/api/tenant/tools

The installer downloads as a self-extracting executable signed with an EV code signing certificate owned by SoftwareIDM Inc. After completing the download, check the properties of PanelTools.exe to verify that the file is not blocked (unblocking it if necessary). Then run the executable, which will extract to a PanelTools folder in the current directory.

Open the extracted PanelTools folder to find the main installer executable: ServiceSetup.exe

ServiceSetup runs as a console application with UAC admin required rights, and may be launched by double-clicking in the file browser, or by running it from an administrative command prompt. ServiceSetup includes commands for:

1. Initial installation: Installs a fresh copy of Panel Service
2. Panel Tool validation: Performs a run-as operation of PanelTool.exe using service account credentials, to interactively validate successful installation
3. Panel Check: Configures config settings and registers a scheduled task for Panel Check health monitoring
4. Grant Service Permissions: Helper to modify Windows Service SACLs to grant full-control permission of a Windows service to a non-admin account (such as the Panel Service account), allowing it to start, stop, etc. the service
5. Configure Password Sync: Modifies Panel Service's config file to include settings for HyperSync Panel Password Synchronization, including registering an https listener with the httpd service

Install Walkthrough

Use the following sequence of steps to install a new copy of Panel Service on a server, workstation, or VM.

.NET requirements (https://dotnet.microsoft.com/en-us/download/dotnet/8.0)

• .NET 8 Desktop Runtime (for ServiceSetup.exe)
• ASP.NET 8 Core Runtime (for PanelTool.exe and SoftwareIDM.PanelService.exe)

It is recommended that Panel Service be installed on servers with their local time set to UTC, especially when Microsoft recommendations have been followed to run domain controllers in UTC.

1. Select Option (1) Install Panel Service.
2. The first prompt in the install is to choose between (1) Software as a Service, and (2) Self-hosted. A Software as a Service installation has a few extra prompts compared to an on-premises install but is similar in most respects.
3. After choosing the correct option for your environment, the next option is to enter the Identity Panel FQDN. This should be entered as just the hostname. The value for this may be copied from the Install Service tab of Identity Panel.
4. Note: Hosted Only: Next the installer will verify connectivity. For a hosted installation, you will be prompted to paste in your Azure Tenant Id. This may be copied from the Install Service page in Identity Panel.
5. Next enter your API Key from the Install Service page.
6. The next prompt is for the DOMAIN\accountName of the service account which will run Panel Service. The NetBIOS name must be resolvable for the account being used. The service account will be validated via an NTAccount lookup, and an error will be printed if the account cannot be found. If the lookup is successful the account's object sid will be printed.
7. Next you will be prompted to enter the service account password twice. (See GMSA Installation if using a managed service account.)
8. Note: Hosted Only: Next you will be prompted to generate a SCRAM credential. The installer will print the local server name, domain, and service account name. These must be entered on the Install Service page as they appear in the installer. Then press Generate password. This will produce a large random password which should be pasted into the installer prompt.
9. The final installer step displays information for the install and asks for confirmation. When confirmation is given (by typing y and pressing enter), the service will be installed.
10. After the install completes, you may scroll up and review the install log to verify it completed successfully. If errors are printed for any of the steps, refer to Manual Installation to complete the install process. An installation (whether automatic or manual) must perform the following steps:
    1. Copy files to the installation directory.
    2. Write out settings to config.json.
    3. Create the service.
    4. Grant full control of SoftwareIDM.PanelService to the service account (to enable automatic updates later).
    5. Attempt to start the service.
11. After the installation completes you may select option 2) to launch Panel Tool and manually verify provider scans, etc.

Panel Check Installation

After Panel Service is installed, it is advisable to configure Panel Check health monitoring. This is done by selecting Option 3) in the installer. This task will add Panel Check settings to the Panel Tools config.json file and create a Panel Check task in Windows Task Scheduler.

Before installing Panel Check, verify email settings are available for either SMTP based email or Microsoft Graph. These settings are commonly the same as those used in Planning Email Settings.

1. Select option 3) in ServiceSetup.exe
2. Enter a DOMAIN\accountname for the service account that will run the scheduled task. > Note:
   > It is easiest to re-use the Panel Service account since it already has authentication permissions for the web application.
   > If the service account is not configured with password-never-expires and if it is not a managed service account, it is advisable to use a different account. Verify that the two accounts had their last password reset at least a week apart, so they are on a different reset schedule.
   > Before configuring the scheduled task, run a command prompt as the target service account, then run PanelTool.exe. This will allow you to establish a SCRAM login context for the second service account.
3. Next you will be prompted to enter the password of the service account. If the password is entered incorrectly, the config.json file will be updated, but it may be necessary to create the scheduled task manually.
4. The next prompt is to choose the email mechanism. The following prompts will differ depending on whether Microsoft Graph or SMTP methods are chosen.
5. After entering the email settings, Panel Check will install. Scroll up from the menu to see the log of activity and verify the task was successful. It is common that ServiceSetup.exe will be unable to create the scheduled task due to server permissions or third-party security software. When this happens, the installer will print out the schtask.exe command which was attempted. Sometimes re-running this command from an elevated prompt will create the task.
   In some cases it may be necessary to create the task manually using the Task Scheduler mmc.
   In this scenario, create a new task called "Panel Check". Ensure the following options are configured:
   1. Run every 15 minutes indefinitely
   2. Run action: --installdir--\PanelTool.exe --panelcheck
   3. Run as desired service account
   4. Run whether or not account is logged in
   5. Run with highest privileges

Non-Standard Location Installs

Sometimes it's desirable to install Panel Service in a non-standard location, such as a drive other than the operating system drive. This may be accomplished using a manual installation, but it is easier to use ServiceSetup.exe.

To install at a location of your choice:

1. Start a command prompt as administrator.
2. Change directory to the extracted folder containing the ServiceSetup.exe file.
3. Run ServiceSetup.exe --advanced

Running in advanced mode will add additional prompts and file pickers to choose the installation folder (for each of the ServiceSetup commands, Install, Run, Panel Check, and Upgrade).

Note: When choosing a folder, PanelTools will always be added to a sub-folder called PanelTools. For example, if you select folder D:\Program Files\SoftwareIDM, the application binary will be placed at: D:\Program Files\SoftwareIDM\PanelTools\SoftwareIDM.PanelService.exe.

GMSA Installation

Panel Service may be installed to run under a GMSA account (this is often the desired security configuration). Running as a GMSA is generally more secure because the Windows platform manages password rotation.

The general approach to configured Panel Service or Panel Check to use a GMSA, is to create the service and configure config.json with a regular or system account, such as NT Authority\LocalService, and then re-configure the service, or re-create the scheduled task using the GMSA account.

1. Install Panel Service using a regular service account or LocalService. If using a hosted installation instead of generating an application password, type a few characters (an invalid password) to bypass the required field validation for the Application Password. This will be fixed later.
2. Edit PanelTools\config.json, and find the key Auth / _comment_Password". Rename _comment_Password to just Password. In the Identity Panel Install Service page, enter the server name for the panel service machine, the GMSA domain, and the GMSA account name, and generate an application password. Paste the value into the new "Password" JSON field and save config.json.
3. Reconfigure the service or scheduled task to use the GMSA.
4. Start the service. On startup, the service will update config.json with the DPAPI encrypted password credential.

The following sample PowerShell script is one way to re-configure the Windows service to use a GMSA.

$serviceName = 'SoftwareIDM.PanelService'
$serviceObject = Get-WmiObject -Class Win32_Service -Filter "Name='$serviceName'"
$serviceObject.StopService() | out-null

# Change logon as settings
$serviceObject.Change($null, $null, $null, $null, $null, $null, 'DOMAIN\ACCOUNT$', $null, $null, $null, $null)
$ServiceObject.StartService()

Automated Installation

When adding a large number of Panel Service installs against the same instance of Identity Panel, it may be desirable to configure automated installation. This may be done through the use of an answer file. Use Option 6) Make Answer File Template from the ServiceSetup.exe menu to generate a text file that contains placeholders for all of the prompts in an install.

Edit the file, and uncomment the desired commands. Following each command, the file lists every prompt asked by the installer, along with the value that will be given for it. To configure partial automation, where some answers are provided and others must be entered at runtime, use the special value --prompt-- to require Service Setup to ask for manual entry.

To execute the install with answers:

1. Run an elevated command prompt and change to the directory containing ServiceSetup.exe
2. Run ServiceSetup.exe --answers "<path-to-answers-file>"
3. Manually provide any answers with a --prompt-- flag

Manual Installation

In some cases a Panel Service installation may fail due to the configuration of third-party security tools. In these scenarios it may be necessary to install Panel Service manually.

Fortunately, Panel Service is relatively easy to install manually. ServiceSetup.exe does not write any registry keys or make changes to server configuration (beyond permissions and service registration). The following high-level tasks must be completed to install Panel Service manually:

1. Copy files to the installation directory.
2. Write out settings to config.json.
3. Create the service.
4. Grant full control of SoftwareIDM.PanelService to the service account (to enable automatic updates later).
5. Start the service.

Add and Configure Files

1. Create the desired installation folder. The path should end with the name PanelTools. The default is C:\Program Files\SoftwareIDM\PanelTools.
2. Download, unblock (if necessary), and extract PanelTools.exe. Inside the PanelTools folder, as a sibling to ServiceSetup.exe, is another folder called PanelTools. Copy the complete contents of this folder into the installation directory.
3. Edit the properties of the installation directory, and grant full control to the service account which will be used to run Panel Service. This permissions elevation allows the service account to rotate files for automated upgrades and to make changes to the config.json file, such as when encrypting a password.

Modify config.json

Edit the new copy of config.json in the installation directory. It may be necessary to save the file to a new location and move it back, overwriting the existing file, if the chosen editor is unable to perform a UAC elevation.

The following keys should be modified:

Create the Service

Creating the SoftwareIDM Panel Service may be done with the following command (assuming a normal service account user with a password). The command must be run from an elevated prompt.

sc create SoftwareIDM.PanelService binPath= "<Install Dir>\SoftwareIDM.PanelService.exe" DisplayName= "SoftwareIDM Panel Service" start= "auto" obj= "<domain\accountname>" password= "<password>"

Grant Full Control

After the service is created, ServiceSetup.exe option 4) may be used to grant full control of the service to the service account itself. This is required if the service is intended to support automatic updates, Panel Check restarts, or scheduler driven service restarts.

Start the Service

Finally, verify the installation was successful by starting the service, verifying that it is running, and checking the event log for errors.