Installation

Jump to Upgrading

Note: Software prerequisites have changed in Identity Panel 3.1. Server 2008 R2 and lower is no longer supported.

Prerequisites

See Server Prerequisites

A Panel Helper PowerShell script is available to guide you through pre-requisites, installation, and post-install activities. http://download.identitypanel.com/PanelHelper.zip

Upgrading from 2.0 Pre-Install

  • Backup the 2.0 database following the procedure below.
  • Completely uninstall version 2.0
    • Stop the SoftwareIDM.* services
    • Uninstall through add-remove programs
    • Open a command prompt and sc delete SoftwareIDM.IdentityPanelDB , sc delete SoftwareIDM.IdentityPanelSearch , and if present, sc delete SoftwareIDM.PanelService

Upgrading from 3.0

If upgrading from 3.0, see below

Before Install

  1. Configure server as web application server
    • Add the Application server role (see PowerShell below)
    • Add the Web Server role
    • Ensure that .NET 4.5 and ASP.NET are installed
  2. Install Java
    • Ensure a current Java runtime is installed (either JRE or JDK)
    • Ensure that an environment variable is created for JAVA_HOME pointed to the runtime folder
      JAVA_HOME
  3. Create DNS host entry for Identity Panel application (without this you will have to use the server FQDN)
  4. Create and install a domain SSL certificate (recommended) to enable HTTPS access to Identity Panel
  5. Install Visual Studio 2013 Redistributable (used by database engine). This may be skipped if Visual Studio is installed on the server.
  6. Install IIS Hosting Pre-requisites
  7. Perform an IIS Reset
  8. Download Identity Panel installer using your license key (see Licensing)

License Download

The following helper script can be used to install web server roles with PowerShell (see step 1 above):

Import-Module ServerManager
Add-WindowsFeature -Name Web-Common-Http,Web-Asp-Net,Web-Net-Ext,Web-ISAPI-Ext,Web-ISAPI-Filter,Web-Http-Logging,Web-Request-Monitor,Web-Windows-Auth,Web-Filtering,Web-Performance,Web-Mgmt-Console,Web-Mgmt-Compat,Web-Server,Web-Static-Content,WAS -IncludeAllSubFeature

Run the Installer

  1. Select Modules to Install
    • Identity Panel Web application - This is the core component of Identity panel, and should always be selected, unless splitting the scheduler service and application on different servers.
    • Identity Panel Full Text Search - Installs Elastic Search full text search engine for Identity Panel.
    • Database Engine - Installs MongoDB database engine.

Choose all modules unless configuring a High Availability environment.

Extra 2.0 Upgrade Step Restore the database backup taken prior to uninstalling 2.0.

  1. Stop SoftwareIDM.IdentityPanelDB service
  2. Replace the Program Files\SoftwareIDM\IdentityPanelWeb\MongoDB\data\db folder with the previously backed up db folder
  3. Start the database service

Configure IIS

Edit App Pool

Open IIS, select IIS Application pools, and edit the Basic Settings of the IdentityPanelv3Pool. Change the .NET CLR version to "No Managed Code". This is necessary because ASP.NET 5 uses the HTTP Platform Handler in lieu of the IIS .NET pipeline.

IIS App Pool

Enable Authentication

Find the IdentityPanelv3 virtual directory. It will usually be in a stopped state.

IIS Virtual Directory

Select the directory, choose authentication, and verify Windows authentication is enabled. You may choose between NTLM and Kerberos (Negotiate) authentication.

  • NTLM
    • Select the Identity Panel website in IIS. Open Authentication, and select Windows authentication.
    • Under providers ensure NTLM is selected
  • Kerberos
    • Select the Identity Panel website in IIS. Open Authentication, and select Windows authentication.
    • Under advanced settings enable Kernel-mode authentication
    • Under providers ensure Negotiate is selected
    • Register an SPN for the host(s) used for Identity Panel. SetSPN -A HTTP/<host> <domain>\<computer>$
      The <host> parameter should be the URL used to access the application.

Edit Binding

On the far right click Bindings and create a binding with the desired DNS name and port. An SSL binding is recommended for production environments. If you have multiple HTTPS hostnames on a single server choose "Require Server Name Indication" to have separate certificates for each binding. Note: this feature does not work with older versions of Internet Explorer.
HTTPS Binding

Start Virtual Directory

Finally, start the IdentityPanelv3 virtual directory and navigate to the Identity Panel home page.

There are a few common issues you may need to resolve at this point:

  • If your organization configures browsers to display intranet sites in IE compatibility view, the site will not display correctly unless you create an exception. This is preferably done by GPO.
    IIS Compatibility View
  • Identity Panel uses font embedding to provide an enhanced experience, and to display icons. Some organizations block font embedding in some security zones. It may be necessary to use GPO to specify a more trusted zone for Identity Panel.
    IIS Fonts
  • If you have configured Kerberos/Negotiate authentication and you have a custom DNS name, your server's loopback protection settings may prevent successful authentication. This issue may be resolved by following Microsoft Support Instructions method one.

Setup Walkthrough

Once the web application is authenticating and loading correctly, you will be guided through a setup walkthrough.

Licensing

Start by adding at least one license key. After adding a license key you will have the option to click through to the next setup step, but if you have multiple keys to add, such as an express and trial key, or an Enterprise and Encrypted Storage key you should go ahead and add them now.

After being applied your license key is displayed in Settings. You will need to re-apply one key each time you upgrade Identity Panel.

Add License

Enter your license key and click the Add button. You will be required to enter your company name and contact email. Claim License

If you are installing Identity Panel on a server without internet access you have two options:

  1. If you can an access Identity Panel from another computer with internet access, you can use that browser to apply the license.
  2. You may use the offline license claim process. Select the no network access checkbox and follow the onscreen instructions.

After completing the email confirmation code you will be able to move on to the next step by pressing the Next Step button. Next Step

Security

The next step is to choose your security roles. During the setup process you may only choose which groups to associate to roles. Full role customization is available in Settings once the setup process is complete.

Security Setup

When you select the group dropdown you will be prompted to enter at least the first three characters of a group name. Identity Panel will search your directory (or tenant if using Azure authentication) for groups that can be used for authorization.

Choose Group

Group principals are stored by objectSid for Active Directory, and by Guid for Azure AD. This means that it is unnecessary to update Identity Panel when a group is renamed.

By default, Identity Panel constructs an LDAP connection string based on the server domain settings while running the installer. If you need to customize this value, it is located in C:\Program Files\SoftwareIDM\IdentityPanelWeb\approot\packages\IdentityPanel\3.x.x.x\root\config.json . Edit this file, find the "Auth" section, and edit the "GroupSearch" key. If you customize this file be sure to back it up in case you need to revert or re-apply changes.

"Auth": {
  "Mode": "Windows",
  "_comment": "TenantId is a default id for windows authentication. Azure authentication gets tenantId from the token",
  "TenantId": "f98fcc9e-30bd-4b2d-8f83-c6663492457b",
  "GroupSearch": "LDAP://DC=softwareidm,DC=local"
}

After you have select your security groups, press the save icon. Your page will refresh and a Next Step button will appear.

Providers

Important: If you are upgrading from Identity Panel 2.5 or earlier, create a temporary provider which you will remove after installing Panel Tools.

In Identity Panel 3.x several settings sections have been combined under Providers. These include:

Provider List

It is often a good idea to start with one or more data collection providers (such as MIM Sync), for the initial setup, then circle back and add health checks and workflows later. When creating providers it is good to use a very short name, because it is prepended by default to all silo names.

Provider Name

For details on configuring provider connection settings see click the above provider settings links.

After you have created and saved at least one provider you will be able to continue to the next step.

Install Tools

The Install Tools step requires you to download the Panel Tools installer and install the agent on at least one server.

Before downloading the installer you must create an API Key. In addition to Windows or Claims authentication, Identity Panel uses randomly generated keys to protect all API endpoints with either a secret API Key, or a CSRF browser token.

API Key

After creating a key you can use the Settings interface to manage and expire the current key. If you choose to Reset a key you have one week to update all your Panel Tools installations unless you choose the "Expire Previous Key Immediately" checkbox.

Next populate the service account value. After you populate the settings, the web application will construct and display an msiexec command you can execute to run the installer.

Service Account

MSIExec command

If you copy the msiexec command, the only value you will have to provider in the installer UI is the service account password.

After running the installer open a command prompt and type PanelTool.exe . You should see a message saying it "Connected to Web Service".

Connected to Web Service

After Panel Tools has connected, refresh the page and you will be able to continue to the next step.

Extra 2.0 Upgrade Step

This is the point at which you run the Upgrade Tool.

  • Open a command prompt in Program Files\SoftwareIDM\PanelTools and run UpgradeTool.exe
  • After it finishes go the web application and remove the temporary provider you created to continue to the next step.
  • Validate the connection settings of each provider.

Scan Data

The scan data step will prompt you to use PanelTool to perform a scan for each of the data collection providers you created. Typically this will include a Full Scan of FIM/MIM/AADSync, as well as scans of ADFS and Azure if you set them up.

Once the scans are complete you should open services, find SoftwareIDM Panel Service, change the startup type to automatic and start the service.

Panel Service

After completing scans, press the refresh icon, then you will be able to continue to the Schedule step. You can create schedules and dashboards right away, or circle back and create them later.

Finishing Up

Finally press the Finish icon. At this point the Setup walkthrough is complete, and you can proceed to detailed customization, including:

If you are upgrading from Identity Panel 2.x, re-create Schedules, Workflows, and Health Checks.

  • Ensure that the SoftwareIDM.Elastic service is started, and that you can access it with a web browser at http://localhost:9200.
  • Set the SoftwareIDM Web Maintenance v3 service to start type of delayed automatic, and start the service

Upgrading

Upgrade from 2.x

Upgrading from Identity Panel 2.x involves making a database backup, uninstalling, installing 3.x, then running a program which copies and transforms data from the old environment to the new one. The procedure includes:

  1. Ensure the old version of Identity Panel is migrated to the Wired Tiger storage engine
    • Open an administrative PowerShell prompt and navigate to %Program Files%\SoftwareIDM\IdentityPanelWeb\MongoDB
    • Execute .\upgrade_db.ps1 This script will:
      • Backup the database to a new .\migrate folder
      • Clear the .\data\db folder
      • Change the storage engine
      • Re-import data
    • After the upgrade script completes, you should manually remove the backup files located in MongoDB\migrate and MongoDB\data\db_old. The script leaves these files in place in case it becomes necessary to reverse the upgrade.
  2. Stop the SoftwareIDM.IdentityPanelDB service, and make a backup by copying the Program Files\SoftwareIDM\MongoDB\data\db folder.
  3. If you have customized the database location, backup mongodb.cfg
  4. Uninstall Identity Panel 2.x
  5. Follow the install procedure above, including the additional steps for upgrading.
  6. After installing Panel Tools on the web server run UpgradeTool.exe. This will migrate your historical data and initialize data connections.
  7. Verify that the SoftwareIDM.Elastic service is started, and that you can access the REST service with a browser at http://localhost:9200/
  8. After running UpgradeTool run WebAgent.exe --reindex on the web application server. This will re-build the full-text search index. If the reindex command prints an error message you should run it a second time.
  9. See Sync Engine Upgrade
  10. Complete the setup walkthrough, and create your schedules, workflows, and health checks as needed.

Upgrade from 3.x

Backup both databases ( IdentityPanelv3 and idp_f98fcc9e-30bd-4b2d-8f83-c6663492457b_db ) by stopping the SoftwareIDM Identity Panel Database service and making a copy of %Program Files%\SoftwareIDM\IdentityPanelWeb\MongoDB\data

Extra Upgrade Steps from 3.0 to 3.x Only

  • Remove Elastic Search:
    • Stop SoftwareIDM.Elastic service
    • run sc delete SoftwareIDM.Elastic
    • Remove %Program Files%\SoftwareIDM\IdentityPanelWeb\Elastic
  • Ensure Java is installed (on web application server only)
    • Install JRE or JDK Java Runtime
    • Add Java runtime folder location to JAVA_HOME environment variable

Upgrade

  1. Download the latest version of the installer using your license key
  2. Run the installer to upgrade Identity Panel
  3. Open the Identity Panel web application
    1. Re-apply your license key
  4. Upgrade Panel Tools
    1. Navigate to Settings / Install Tools
    2. Download and run the tools installer on each agent server to upgrade
    3. Edit service properties of each installation and set to automatic startup, and set the password for the service account identity

Extra Upgrade Steps from 3.0 to 3.x Only

  • Find %Program Files%\SoftwareIDM\IdentityPanelWeb\Web\config.json and remove it or rename it to config_old.json
  • Location the config.json file matching your version number (e.g. config_3.1.17.499.json).
  • Rename the file to config.json. If you have made customizations to config settings you will need to re-apply them.
  • Verify that the SoftwareIDM.Elastic service is started, and that you can access the REST service with a browser at http://localhost:9200/
  • Run WebAgent.exe --reindex . If the reindex command prints an error message you should run it a second time.
  • Ensure SoftwareIDM Web Mainenance v3 service is set to startup type of Delayed Automatic, and start the service.
  • On each server with Panel Tools locate %Program Files%\SoftwareIDM\PanelTools\config.json and repeat the process of renaming to activate the config file for the current version.

Un-install

  1. Make sure the SoftwareIDM Scheduler, Database, and Search services are stopped.
  2. Remove Identity Panel (AKA Sync Panel) through add-remove programs.
  3. Remove Identity Panel Tools through add-remove programs.
  4. Run sc delete SoftwareIDM.IdentityPanelDB to remove the MongoDB service.
  5. Run sc delete SoftwareIDM.Elastic to remove the search service.
  6. Run sc delete SoftwareIDM.WebAgent to remove the web maintenance service.
  7. On each server with panel tools run sc delete SoftwareIDM.PanelService
  8. Delete the IdentityPanelWeb directory to remove the database and web application files if desired.

Copyright © SoftwareIDM

Table of Contents