Install the Agents

Most on-premises installations use an agent integrated with Usercube's server. If this is your case, and the server is already installed, no need to go further. If, on the other hand, you need separate agents, or if you are installing Usercube's agents within Usercube's SaaS offering, this is the way to go.

Please make sure that Usercube's agent requirements are met before going further.

Agent Working Directory

The agent runtime content should be extracted from the runtime archive following the instructions provided in Create a Working Directory.

In the separate agent setup, the agent is usually installed on a different workstation from the server.

The agent is configured thanks to the appsettings.agent.json file.

Create an IIS Website

It is recommended to run the Usercube agent as an IIS website.

To install Usercube's agent as a Windows service, please jump to Install the agent As a Windows Service.

Adding Usercube's agent as an IIS website can be achieved with the Internet Information Services (IIS) Manager which can be launched with the INETMGR.MSC command. You need to have an IIS 10.0 or greater.

The Microsoft Documentation provides the prerequisites and the procedure to create a new IIS site.

The information needed to go through the creation process are the following:

Usercube's agent uses an in-process hosting model.
Usercube's agent uses .Net.
Usercube agent's web.config dwells in the runtime directory.

It might require a few modifications to target the agent instead of the server:

1. Open web.config with a text editor.

2. Change the arguments and stdoutLogFile attributes of the <aspNetCore> element as indicated below:

<aspNetCore processPath="dotnet" arguments="./identitymanager-Agent.dll" stdoutLogEnabled="false" stdoutLogFile="../Temp/stdout-agent.log" hostingModel="inprocess">

When creating the website, enter the following data:

1. Site name: UsercubeAgent<Organization> is the recommended naming convention.

2. Physical path: /<agent working directory>/Runtime

3. Type: http

4. IP address: All unassigned

5. Port & Hostname: To access Usercube's agent. Use the hostname and port that has been reserved for Usercube.

After creation, the following settings are recommended:

Application Pool > Usercube<Organization> > Advanced Settings > General > Start Mode set to AlwaysRunning;
Application Pool > Usercube<Organization> > Advanced Settings > Process Model > Idle Time-out (minutes) set to 0 and Load User Profile set to True;
Application Pool > Usercube<Organization> > Recycling > Regular time intervals set to 0.

Recycling the application pool creates a discontinuation in the connection between server and agent, which can disrupt some of Usercube's features such as the job scheduler. IIS already recycles the application pool at each setting change, thus NETWRIX recommends not using periodic recycling.

The following is mandatory:

Application Pool > Usercube<Organization> > Advanced Settings > General > .NET CLR Version > No Managed Code

To sum up IIS settings:

IIS Settings

Hosting Bundle

You need to install the dotnet hosting bundle (version 8.0 or higher) to be able to run dotnet application.

Select an Agent Identity

The Usercube Agent, through the IIS Website, should be assigned a service account with the relevant permissions.

You can either:

Use the built-in application pool identity (see Check default behavior) and grant this identity the right permissions.
Use a custom Windows service account with the right permissions and use it as an IIS identity for Usercube's agent IIS Website.

Check default behavior

Usually, creating an IIS application pool, such as the one within which Usercube's server website runs, triggers the creation of a service account IIS APPPOOL/<apppool_name> (where <apppool_name> is the application pool name) known as an application pool identity. It is associated with the IIS website. This account is granted basic group membership that should enable it to access what it needs.

For more information about IIS identities, visit the Microsoft Documentation.

Building on this default behavior, the default Application Pool Identity is usually granted the necessary permissions for Usercube's server to operate.

Before going further, you should check the following points:

Find the group membership of IIS APPPOOL\<apppool_name>.
Check the permissions on the working directory. Right-click the working directory and select Security. The group section should contain one of the IIS APPPOOL/<apppool_name> groups, namely Users.

From there:

If the built-in application pool identity has been created but does not have the right permissions, you can use Set the Agent Permissions to fix it. Go back to Set an IIS Identity to make sure that the built-in application pool identity is effectively used by Usercube's server IIS Website.
If you would rather use a custom service account instead of the built-in application pool identity, start with Set an IIS Identity.
If you're not sure what to do, follow the procedure below, starting with Set an IIS Identity.

Set an IIS Identity

If you want to use the built-in application pool identity created with the application pool, you can use the Microsoft documentation.

If you'd rather use a custom service account created for Usercube's agent, follow the procedure below.

The following implies that a custom service account has already been created for Usercube's agent. This can be achieved by following the same steps as for the server:

Open the IIS Manager (INETMGR.MSC).
Open the Application Pools node underneath the machine node.
Select the UsercubeAgent/<Organization> application pool.
Right-click and select Advanced Settings.
In the Process Model section, on the Identity list item, click on the three dots to open the Application Pool Identity dialog.
Select the Custom Account radio button and click on Set.
Enter the Service Account credentials.
Click OK. You're all set.

Usercube's server IIS site will now use this identity to access the database and the working directory.

Set the Agent Permissions

Permissions

Usercube's agent needs specific permissions on its working directory to run, write synchronization output and read provisioning orders.

Up to four folders have to be considered:

The working directory
The runtime directory, usually C:/identitymanager<Organization>/Runtime
The data collection directory, usually C:/identitymanager<Organization>/Temp
The provisioning orders directory, usually C:/identitymanager<Organization>/Temp (same as for the data collection directory).

Steps

The following steps can be performed for each of the relevant directories.

First, let's check what permissions the service account already has.

Go to the working directory parent folder.
Right-click the working directory.
Select Properties.
Select Security.

From there, you have two choices.

The agent service account that was chosen in the previous step:

Already has or belongs to a group that already has the needed permissions. There is nothing more to do.
Is missing one of the needed permissions:
1. Click on Edit.
2. Click on Add.
3. In the Enter the object names to select textbox, enter the service account name in the down-level logon format. For example, if you chose the built-in application pool identity, this would be IIS APPPOOL/identitymanagerAgent<Organization>.
4. Click on OK.
5. Select the newly added user name in the Group or user names panel at the top of the window.
6. Check the Allow column for the relevant permissions. Check the Deny column for the others.
7. Apply OK.

The working directory permissions are all set.

The same steps have to be performed on the runtime, the data collection and the provisioning orders directories.

Name the Agent

Every agent is assigned a name. This name will be used in the UI to differentiate agents for the end-user, and in the XML configuration to assign connectors to specific agents.

In the appsettings.agent.json file, OpenId > AgentIdentifier can be set to any string except for Local which is already taken by Usercube's inner workings. Then the agent set in the XML configuration must have the same string as identifier.

For example:

appsettings.agent.json

"OpenId": {
  "AgentIdentifier": "MyAgent"
  }

With the following configuration:

<Agent Identifier="MyAgent" DisplayName_L1="My Agent" URI="https://contoso.com" />

Connect the Agent to the Managed Systems

The Runtime/appsettings.agent.json file is a technical configuration file that will enable you set up the connection between the agent and the target managed systems.

Every agent is associated with an appsettings.agent.json file.

The integration team should communicate the list of the managed systems to be connected to the agent, together with their configuration.

Here is an example of appsettings.agent.json connecting an agent to an Active Directory and an SAP server.

appsettings.agent.json
{
  ...
  "Connections": {
    "ADExport": {
        "Servers": [
          {
           "Server": "paris.contoso.com",
           "BaseDN": "DC=paris,DC=com"
          }
        ],
        "AuthType": "Basic",
        "Login": "Login",
        "Password": "Password",
        "Filter": "(objectclass=*)",
        "EnableSSL": "true"
    }
    "SAPExportFulfillment": {
        "Server": "serverUrl",
        "Login": "login",
        "Password": "password"
    }
  }
}

Storing sensitive managed system data in configuration files, such as login/password pairs, is strongly discouraged. Sensitive data should be protected by one of the Credentials Protection methods.

Encryption Key Pair

Usercube's agent needs an RSA key pair to perform various encryption operations, such as source, configuration, or log file encryptions.

An RSA key pair, as in an X.509 public key certificate and a private key, can be stored one of two ways:

As a PKCS #12 archive (also called Personal Information Exchange file or .pfx file) stored in the server's host file system. The file contains both the public key certificate and the private key.
As a certificate from a Windows' certificate store identified by SubjectDistinguishedName or by Thumbprint. The Windows certificate also contains both the public key certificate and the private key. This is the recommended method.

The key pair can be generated with tools such as OpenSSL or Microsoft's New-SelfSignedCertificateandpvk2pfx tool.

Here's an example showing how to generate a PKCS #12 archive (UsercubeContoso.pfx) bundling a public key certificate (usercubecontoso.cert) and a private key (usercubecontoso.key) with OpenSSL, with a 50-year expiration date:

openssl req -x509 -newkey rsa:1024 -keyout usercubecontoso.key -out usercubecontoso.cert -days 18250

openssl pkcs12 -export -out UsercubeContoso.pfx -inkey usercubecontoso.key -in usercubecontoso.cert

Public key certificates can also be bought from trusted certificate providers and bundled with a private key into a PKCS #12 archive using step 2 in the frame above.

The certificate has to be linked to Usercube via EncryptionCertificate in the appsettings.agent.json file.

For more information about configuration parameters, see EncryptionCertificate.

Certificate as a plain file

The following parameters are used to link the file to Usercube in EncryptionCertificate.

PKCS #12 archive can be password protected, hence the X509KeyFilePassword attribute.

Storing a .pfx file password in plain text in a production environment is strongly discouraged. It should always be encrypted using the Usercube-Protect-CertificatePassword tool.

appsettings.agent.json
{
  ...
  "EncryptionCertificate": {
      "File": "./identitymanagerContoso.pfx",
      "X509KeyFilePassword": "adefe$/izih"
  }
  ...
}

Certificate in the certificate store

The certificate can be stored in the certificate store instead of the file system. This is the recommended method.

appsettings.agent.json
{
  ...
  "EncryptionCertificate": {
      "DistinguishedName":"UsercubeContoso",
      "StoreLocation": "LocalMachine",
      "StoreName": "AuthRoot"
  }
  ...
}

Connect the Agent to Usercube's Server

The connection to Usercube's server is configured through:

1. The applicationUri attribute in the Runtime/appsettings.agent.json file has to be set to Usercube's server URL.

2.OpenIdClients and DefaultOpenIdClient must be used to set the agent's credentials to connect to the server.

Their content should be provided by the integration team, in relation to the OpenIdClient tag in the applicative configuration.

The following example shows an appsettings.agent.json file that sets an agent to connect to Usercube's server (https://identitymanagerserver.contoso.com) with the OpenId client identifier Job and the password secret, stored in the OpenIdClients list which also contains the "admin/secret" login/password pair.

{
    ....
    "ApplicationUri": "https://identitymanagerserver.contoso.com",
    "OpenIdClients": {
        "Job": "secret",
        "Admin": "secret"
     },
    "DefaultOpenIdClient": "Job"
}

Storing plain text passwords in configuration files is strongly discouraged. Sensitive passwords should be encrypted.

Install the Agent as a Windows Service

Installing Usercube's agent as a Windows service instead of an IIS website is mostly useful when using IIS is rendered moot by another system. For example, using a reverse proxy in front of Usercube's agent.

To install Usercube's agent as a service in Windows server, use the following command:

sc.exe create Usercube binpath= "Usercube-Agent.exe --service" displayname= "Usercube Agent" start= auto obj= "DOMAIN\USER" password= "PASSWORD"

Make sure to include a space between each parameter's equal sign = and the parameter value.

Configure the Starting Mode in IIS (optional)

This step is important if the scheduler is enabled. IIS starts Usercube's agent only if an incoming http request is made on the server and the scheduler is not launched until Usercube's agent is started. Because of that, you need to carefully set up the starting mode of IIS to force the starting of Usercube's agent.

Usercube's agent warm up is done using the <applicationInitialization> element in the web.config file, the configuration is described here: https://docs.microsoft.com/en-us/iis/get-started/whats-new-in-iis-8/iis-80-application-initialization

You need to:

Enable the Application Initialization feature
Modify the applicationHost.config file to set the startMode of the application pool as AlwaysRunning. You also need to set the preloadEnabled of your application set to true. It is advised to backup the applicationHost.config file when doing this step to prevent mistakes
Double check that the following section is set in your web.config file, in the section system.webServer:

<applicationInitialization doAppInitAfterRestart="true">  <add initializationPage="/"></applicationInitialization>

Once done, you need to check that the configured jobs are launched via the Usercube's scheduler without having to manually issue a request on Usercube's agent.

If this is not correctly configured, any restart of your IIS or application pool could prevent jobs from being launched.

What's Next?

The last step in the installation process is setting up an Email server.

Agent Working Directory​

Create an IIS Website​

Hosting Bundle​

Select an Agent Identity​

Check default behavior​

Set an IIS Identity​

Set the Agent Permissions​

Permissions​

Steps​

Name the Agent​

Connect the Agent to the Managed Systems​

Encryption Key Pair​

Certificate as a plain file​

Certificate in the certificate store​

Connect the Agent to Usercube's Server​

Install the Agent as a Windows Service​

Configure the Starting Mode in IIS (optional)​

What's Next?​