Identity Manager

The Identity Manager brokers all authentication requests from Clients to GlobalSearch. This includes the both the desktop and browser clients, in additional to standalone applications like GlobalSearch Extensions, File XChange, and Image XChange. Clients using Identity Manager leverage an API Key for application to application communication, which will be generated automatically at the time of installation or upgrade. Calling applications use a saved version of the API Key, normally found in the application's Config file. There may be times where additional keys are required, or existing keys should change. An interface is provided to manage these changes.

Identity Manager is specific to the task of Authentication. Authentication confirms the user is who they say they are. This is different than Authorization, which is the ability to secure a specific resource. Identity Manager assumes the role of authentication in the product. GlobalSearch directly keeps track of what a user is secured to.

Database

The Identity Manager uses its own SQL Server database named Square9.IdentityManager. The database is used to keep track of user and group accounts that are created through the GlobalSearch User Manager, or provisioned through 3rd party identity services like Okta or Azure AD.

BACKUP YOUR DATABASES

The Identity Manager's database should be part of a normal SQL backup process. Please ensure all SQL databases are properly backed up, and ensure those back ups are tested.

It is not recommended that customers interact directly with the data in this database.

The GlobalSearch system database, SSMaster, keeps a log of legacy Square 9 users that were migrated into the Identity Manager. In a table named Migrations a row with the Name value of RolesToS9IM will detail the users and groups that were migrated. In almost all cases, migrations happen automatically and don't require any user/admin involvement. If necessary, you can trigger the migration to run again by deleting the row with Name value RolesToS9IM and restarting IIS. The Square9API on application start will recognize the user migration entry is missing and it will attempt to migrate again.

Installation

Identity Manager will install as part of the GlobalSearch installation as a server side component. When installed, it will run as a service on the GlobalSearch Server, with the name Square 9 Identity Manager. Like all GlobalSearch applications, the Identity Manager application and supporting files can be found in C:\Program Files\Square 9 Softworks if the default installation path was chosen. The primary executable, Square9.IdentityManager.exe, can be run as a console application for support / debugging purposes.

RDS Servers

Windows Installer packages have known limitations in environments where RDS is enabled on the server. Server's configured for RDS need to be put into install mode, or the IM installation will hang. Refer to the documentation on common installation issues here. This behavior is a problem with Windows Installer chaining, and can also be bypassed by telling the installer to skip the chained installation. Run the GlobalSearch installer with a 'no chaining' option, setup.exe /v"DO_NOT_CHAIN=TRUE". Identity Manager is a required service for proper GlobalSearch operations. If the identity manager install is skipped or bypassed, it will need to be installed separately.

Note: Uninstalling GlobalSearch from an environment will not uninstall Identity Manager. The service will be listed in the Server Add/Remove Programs list as a separate application (with the name Square 9 Identity Manager) that would need to be uninstalled separately.

Configuration files deployed to support the application are located in a Config folder beneath the installation directory:

Square9.IdentityManager.exe.connectionStrings.config
- Holds the connection string the to Square9.IdentityManager database.
Square9.IdentityManager.exe.appSettings.config
- Holds the host address / port the identity manager runs on. The default identity manager port is 8080.
- Holds the access key required to access the Identity Manager's web interface. The "master key" is unique and randomly generated for each installation. If you wish to change the master key, it may be updated here.
- Temporarily holds a "seed key" which is a random GUID used to initially seed the Identity Manager's database. After a successful installation, the seed key should not be present in the config.

User Accounts

The Identity Manager should be set to run as Local System. While the application runs in the context of Local System, any internal actions like accessing the database are performed in the context of the Square 9 Admin Authenticated user. This user, traditionally SSAdministrator, has cached credentials on the server that are leveraged by Square 9 applications for performing these types of actions. Use the Square 9 Service Console to view the currently configured user. At startup, Identity Manager will leverage its configuration files to provision the Square9.IdentityManager database in the context of this user.

Usage

Square 9 Identity Manager operates in an unattend fashion in almost all cases. For troubleshooting purposes or for configuring SCIM support of 3rd party auth providers, a browser interface is provided. From an Admin perspective, the Identity Manager's primary purpose is to manage API keys that are used by client applications. A typical installation will have only a single API key generated at the time of install. That API key is automatically provided to the Square 9 applications that need it,and their configuration files are updated with that key during installation / upgrade. Client configuration generally includes both a reference to the location of the identity manager, in addition to a valid key.

As of GlobalSearch 6.1, you may find entries like this in the appSettings of Square9API. If the key or base URL were to ever change, these settings would in turn need updating.

Access

The default address for the interface is: http://localhost:8080/static/admin. When connected, you will be prompted to authenticate with the master password from the config in the Installation section above.

Once authenticated, an interface is available to provision keys:

The default key available in the interface is the key used by any Square 9 internal client applications. If a customer intends on using other applications (Okta, Azure AD), it's advised to create a new key for each application.