How to Install a NIM Agent?

BOUTOT · September 1, 2026, 8:32am

Why a NIM Agent?

Goals of an agent

Bridge between NIM Server and your Information System
Network/security segmentation allowing access to an isolated network
Execute NIM connectors
- Connector dedicated credentials/permissions are stored and used exclusively within the client network, never transmitted to SaaS infrastructure

Architecture schema

Prerequisites & Requirements

System

Download the UsercubeAgent.zip installation package from your Netwrix customer/partner portal
Windows Server with IIS 10.0 minimum (recommended)
ASP .NET Runtime hosting bundle installed (after IIS installation)

Network & Certificates

HTTPS connectivity between agent and server
SSL/TLS certificate for secured communication
Hostname and DNS
Strongly recommended: use a dedicated service account for IIS

Full agent requirements: Agent | Netwrix Product Documentation

IIS Role Installation — Role Services

Key Role Services to Enable

Web Server (IIS) → Common HTTP Features
Security → Windows Authentication, Request Filtering
Management Tools → IIS Management Console, Scripts and Tools

Source: Agent | Netwrix Product Documentation

Remember: .NET Core hosting bundle installed after IIS installation

Server-Side Configuration

Agent XML Configuration on the server side

Location: Server configuration file

<Agent
 Identifier="AgentAPI"
 DisplayName_L1="Agent API"
 DisplayName_L2="API Agent"
 URI="https://agent-api.netwrix.local"
/>

Key Attributes:

Identifier: Unique agent ID (used for references)
DisplayName_L1, _L2, …: Multilingual display names
URI: HTTPS URL of the agent endpoint, only URL that will be allowed to request the server

Server configuration reference: Agent | Netwrix Product Documentation

Secret Generation: Usercube-New-OpenIDSecret

Tool Location: <NIM installation>/Runtime utilities/

Process

Use Usercube-New-OpenIDSecret.exe to
- Generate a 32 characters random secret
- Hash the secret store
ONLY the hash is to be stored on the server-side configuration (like the OpenIdClients.xml file)
The plain secret will be used on the agent-side configuration (appsettings.agent.json)

> .\Runtime\Usercube-New-OpenIDSecret.exe
Shared secret for 'hnPVJ2oK3zOtTMG6Uzl31lmpbxd2Hkcz' is '4BKmeHky79Ls7fIAbu7lkHQgJChfwSp214HzfSUbKZo='

Security Best Practices

Each ClientId must get its own unique secret
Never store plain-text secrets in configuration
Use strong randomization for secret generation
Rotate secrets periodically in production

Usercube-New-OpenIDSecret reference: Usercube-New-OpenIDSecret | Netwrix Product Documentation

OpenIdClient Configuration on the server side

Location: <NIM installation>/Conf/OpenIdClients.xml (for example)

<OpenIdClient
 Identifier="JobAPI"
 DisplayName_L1="AgentAPI"
 HashedSecret="4BKmeHky79Ls7fIAbu7lkHQgJChfwSp214HzfSUbKZo="
 Profile="Administrator"
/>

Key Attributes:

Identifier: Unique client ID for agent jobs
HashedSecret: Hash ONLY (never plain text!)
Profile: Access level (e.g., Administrator, or the dedicated profile)

OpenIdClient reference: OpenIdClient | Netwrix Product Documentation

Agent-Side Configuration

Agent appsettings.json Configuration

Located in the agent’s runtime directory

//NIM Server's URL
"ApplicationUri": "https://server.netwrix.com",
//NIM Agent's URL
"UsercubeAgent": { "Url": "https://agent-api.netwrix.local" },
//IdentityServer (Certificate Configuration): use Windows Certificate Store (recommended)
"IdentityServer": {
 "X509Thumbprint": "A45DB45DE40C87F72A15[…]4D9",
 "X509StoreLocation": "My",
 "X509StoreName": "LocalMachine"
},
//Authentication delegate at the Customer's IDP
 "Cors": {
 "AllowAnyHeader": true,
 "AllowAnyMethod": true,
 "AllowCredentials": true
 },

Notice: No License, No Database parameters are necessary on the agent side.

appsettings.json reference: Application Settings | Netwrix Product Documentation

Agent appsettings.json - Best Practice - Don’t omit the Encryption Certificate

//For security reasons, encrypting data passing through the agent is a best practice.
"EncryptionCertificate": {
"Thumbprint": "A9D64D34F10B8EE4D[…]3C2",
"StoreLocation": "My",
"StoreName": "LocalMachine"
},
//Active the scheduler after the validation of this installation
"Scheduler": {
"Enabled": true,
"LockFilePath": "../Temp/scheduler.lock"
},

If you don’t use an external scheduler, you can activate the NIM one, at the end of the agent installation.

appsettings.json reference: Application Settings | Netwrix Product Documentation

Agent appsettings.agent.json Configuration

Located in the agent’s runtime directory

//OpenId Agent Credentials
"OpenId": {
"OpenIdClients": {
"JobAPI": "hnPVJ2oK3zOtTMG6Uzl31lmpbxd2Hkcz"
},
"DefaultOpenIdClient": "JobAPI"
},
//Allows you to access source files and scripts
"SourcesRootPaths": [
"C:\\NIMDemo\\Sources",
"C:\\NIMDemo\\Scripts"
]

appsettings.agent.json reference: appsettings.agent | Netwrix Product Documentation

Agent web.config check

web.config – agent Runtime folder – check ~line 13

<aspNetCore processPath="dotnet"
 arguments=".\Usercube-Agent.dll"
// must NOT read Usercube-Server.dll
 stdoutLogEnabled="false" />

Confirm the agent binary is targeted (Usercube-Agent.dll), not the server binary (Usercube-Server.dll).

Notice: If the agent was deployed from the same package as the server, web.config may still point to Usercube-Server.dll — always check before starting the site.

Web.config reference: Configure the Agent's Settings | Netwrix Product Documentation

IdentityServer Certificate Setup

Option 1: File-Based (.pfx)

PKCS#12 format with password protection
Path: X509KeyFilePath
Password: X509KeyFilePassword (should be encrypted)

Option 2: Windows Certificate Store (Recommended)

X509Thumbprint (Number of certificate)
X509StoreLocation (e.g., “LocalMachine”)
X509StoreName (e.g., “My”, “AuthRoot”)

Important: IIS Service Account Access

The service account running IIS must have read access permissions on the certificate
Configure certificate store permissions correctly
Test certificate access before deployment

For detailed certificate management: refer to Netwrix documentation on certificate configuration

Source: Agent | Netwrix Product Documentation

IIS Role

Role configuration

Add “Web Server (IIS)” role: Common HTTP Features, Security (Windows Authentication + Request Filtering)
Management Tools: IIS Management Console + Scripts and Tools

Source: Agent | Netwrix Product Documentation

Web Site Installation

Application Pool Settings

NET CLR version: “No Managed Code”, pipeline: Integrated
Identity: run under the dedicated <IIS_Login_Account>
Start Mode: AlwaysRunning
Load User Profile: True
Idle Time-out: 0

Directory Permissions — IIS Service Account

Grant the <IIS_Login_Account> full (Modify) access on the whole <Usercube_Directory>
Including the \Runtime subfolder — hosts appsettings.json, appsettings.agent.json and web.config
Without this, the Application Pool fails to start or cannot read configuration/log files

Source: Agent | Netwrix Product Documentation

IIS — Tools — Add Website

Configure Site name / Physical path / Connect as / URL / SSL certificate

Source: Agent | Netwrix Product Documentation

IIS — Application Pool — Advanced Settings

Configure Start Mode / Identity / Load User Profile / Idle Time-out / Regular Time Interval

Source: Agent | Netwrix Product Documentation

Directory Access Control

By default, the website does not have access rights to the NIM directory. Therefore, you must grant read and write permissions to the IIS pool service account.

Installation & Validation

Complete Installation Checklist

Prerequisites & Validation

Prerequisites

Validate Windows Server & IIS requirements
Create service account with proper permissions
Acquire and configure SSL certificate

Validation

Verify agent to server HTTPS connectivity
Test credential authentication
Validate configuration file syntax

Deployment & Parameters

Server-Side Setup

Add Agent XML to server configuration
Generate strong secret with Usercube-New-OpenIDSecret
Create OpenIdClient entry

Agent-Side Setup

Configure appsettings.json (URLs) and Cors
Configure appsettings.agent.json (OpenId credentials)
Deploy certificate to certificate store
Set proper permissions on certificate for IIS account
Set proper permissions on NIM directory for IIS account

Key Takeaways & Next Steps

Key Points to Remember

Agent requires separate configuration on both server and agent sides
OpenIdClient secrets: Always hash, never plain text in configuration
Certificates: Use Windows Certificate Store when possible (recommended)
Service Account: Must have permissions on certificate store and managed systems
HTTPS Only: All communication between agent and server must be encrypted
Validation: Always test connectivity and authentication before production use

Next Steps

Deploy to non-production environment first
Use the interface to create connectors and enter the credentials that will be encrypted by design
Test all connector scenarios
Document any custom configurations
(Optional) Plan security review before production cutover

Agent Version & Updates

Why update the NIM agent?

Version updates include bug fixes, improvements, and new connectors; to take advantage of them, you must update the agent.
The agent must use a version that is the same as or older than the version of the Identity Manager server to which it connects (never use an earlier version of the agent than the server).

Upgrade Procedure

IIS: Stop the agent’s Application Pool and Web Site before replacing any files
Agent-side: Back up appsettings.json, appsettings.agent.json, web.config and the certificate — the agent has no XML configuration to migrate
Unzip the new Runtime into the NIM Agent folder and copy the backed-up configuration files into it
Restart the Application Pool and re-validate agent-to-server connectivity

Best Practice

Always test the upgrade in a non-production environment first
Keep existing OpenIdClient secrets and certificates — do not regenerate them during an upgrade

Migration Guide reference: Migration Guide | Netwrix Product Documentation

Troubleshooting

Enable Agent Logs

web.config — activate stdout logging if the agent fails to start

<aspNetCore processPath="dotnet" arguments=".\Usercube-Agent.dll"
// Activate if necessary
 stdoutLogEnabled="true"
 stdoutLogFile=".\Agent_Log\stdout"
/>

Revert stdoutLogEnabled to “false” once resolved — avoid unbounded log growth in production.

If in doubt, reinstall the required ASP.NET Runtime Hosting Bundle.

Web.config reference: Configure the Agent's Settings | Netwrix Product Documentation

ASP.NET reinstall

.NET Core must be installed after IIS, as the .NET Core Hosting Bundle adds the required components and libraries to IIS.
The .NET Core SDK is not required, as it is not used by the application.
In short terms, when problems arise, it’s often enough to simply reinstall the .NET Core Hosting Bundle that’s compatible with your version of NIM.

.NET Core hosting bundle: Agent | Netwrix Product Documentation

Verify Access to certificate

Verify or, if necessary, ensure that your pool’s service account has access rights to the certificate, for example, “IIS AppPool\IdentityManager”. By default, the account does not have these access rights.