Skip to main content

Agent

This section identifies the requirements for a Usercube agent.

Software​

The agent is a .NET application.

Running an agent requires installing the ASP.NET 8.0 Runtime.

Hosting​

When used separated from the server, the agent can be run as:

Integrated agent​

Some installations require multiple separate agents, but most of them use a single integrated agent that runs within the Usercube server process. In that case, the server executable contains the agents and no agent executable needs to be executed. It means that if a Usercube server is already installed, no further installation is required.

In this case, the agent working directory is the same as the server working directory, and both the agent's and server's appsettings share the same configuration. The appsettings.agent configuration set is still configured through environment variables or via a separate appsettings.agent.json file stored next to the Usercube-Server.exe executable, in the common working directory.

Service Accounts​

The agent should be assigned a Windows Server service account.

The installation of the server as part of an Active Directory domain requires the use of an account with sufficient privileges to create a service account on the domain.

It can be either the IIS built-in application pool identity, or a custom Windows Server service account.

Working directory permissions​

The agent's service account needs specific permissions on the working directory:

  • Read and List folder contents on the working directory;
  • Read & Execute and List folder contents on the Runtime directory, usually C:/identitymanager<Organization>/Runtime, in order to run the agent executable;
  • Read and List folder contents on the directory for provisioning orders, whose path depends on the Work folder's path;
  • Read, List folder contents, and Write on the directory for data collection, whose path depends on the Work folder's path.

Other permissions should be denied.

FAQ: How to set up directory permissions in Windows Server?

Managed systems' permissions​

Every Usercube agent needs one or several service accounts on the target managed systems, able to read and write to said managed systems.

For example, using Usercube with an Active Directory instance requires the agent to be assigned an Active Directory service account that can read, write, change users' passwords, update group memberships, and synchronize the whole Active Directory.

Before going further, make sure the integration team has provided:

  • The list of all managed systems;
  • service accounts with the necessary permissions for the agent to perform Read and/or Write operations on the systems associated with a connector allowing respectively synchronization and/or provisioning;
  • service accounts' credentials.

Managed systems credentials are stored in the appsettings.agent configuration set and can be protected.

Database permissions​

The agent needs a service account that can authenticate to SQL Server.

Hostname and DNS​

The agent needs to be assigned a hostname within the organization's domain. End-user browsers must be able to resolve the agent's hostname.

The associated DNS zone needs to be updated accordingly.

The DNS alias should be written in lowercase in order to comply with as many security rules as possible.

SSL Certificate​

The agent requires the use of HTTPS ports and an SSL certificate in order to perform HTTPS communication with the server.

Emails​

The agent needs access to an SMTP server to send email notifications.

Encryption Key Pair​

An RSA-2048 encryption key pair is required for the agent in order to perform various encryption operations, such as source, configuration, or log file encryptions;

Such a certificate does not need to be integrated into the target organization's Public Key Infrastructure and does not require an expiration date. They are only relevant to internal and temporary Usercube data and can be changed at any time.

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

  • As a PKCS #12 archive (also called Personal Information Exchange file or .pfx file) stored in the server's host file system. The archive 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.

What's Next?​

To start the installation, follow either the quick start guide or the production-ready installation guide.