The Security page of the Console: IP allowlisting for the Console, country restrictions for the Console and the server, rate limiting (request limits and temporary blocks for agent traffic on the server), and OpenID Connect single sign-on with Azure AD, Keycloak, Google, Okta, and Auth0.
This chapter covers the security controls that most deployments configure early in their lifecycle: restricting which source IPs can reach the product, and replacing local passwords with single sign-on. The two features work independently of each other, but both control who can reach the Console, and the same administrators usually configure them.
The page Settings → Security at /settings/security holds four tabs, each behind its own permission:
IP whitelist (?tab=ip-whitelist): which source addresses may reach the Web Console, see A.4.1.
Country restriction (?tab=countries): admits connections to the Web Console and to the NetLock server only from selected countries, see A.4.1a.
Sessions (?tab=sessions): how long a sign-in to the Web Console stays valid, see A.4.1c.
Rate limiting (?tab=rate-limiting): request limits and temporary blocks for the agent traffic of the NetLock server, see A.4.1b.
The first two tabs are shown to accounts with settings_ip_whitelist_enabled, Sessions to accounts with settings_sessions_enabled and Rate limiting to accounts with settings_rate_limiting_enabled; the menu entry Security appears for any of them. Single sign-on has a page of its own, Settings → SSO, see A.4.2.
All of these apply to cloud and self-hosted deployments. Changing the SSO configuration restarts the Web Console and disconnects every signed-in user, so plan that change for a maintenance window (see Chapter A.2.2). Changes to the IP whitelist and to the country restriction apply within a few seconds, changes to rate limiting within thirty, and none of them restarts anything.
The tab IP whitelist of Settings → Security (/settings/security?tab=ip-whitelist) controls which source IP addresses may reach the Web Console. Two mechanisms feed one whitelist:
a static list of addresses an administrator types on the page, and
dynamic entries that Relay App users add for their own current address for a limited time.
The Web Console re-reads the whitelist from the database every ten seconds and applies it in memory. Saving the static list, turning dynamic whitelisting on or off, revoking an entry, an entry expiring: each takes effect within that window, with no restart and without ending anyone's session.
The whitelist restricts the Web Console only. The agent, file server and relay endpoints of the NetLock server are not filtered by IP address: agents and Relay Apps connect from wherever the fleet and the administrators happen to be, and they authenticate with their own credentials. That is also what makes dynamic whitelisting possible: the Relay App can always reach the server, and the server can therefore whitelist the address it sees the Relay App connect from. To limit the server by the country of the source address, use the country restriction, which has a list of its own for the server.
The page opens with an informational alert and a five-line text area labelled Allowed IP Addresses (comma-separated) with the helper text Example: 192.168.1.100, 10.0.0.5, 172.16.0.1.
Enter one IP address per comma-separated item. Each entry is validated with standard IP-address parsing; an invalid value raises an inline error like Invalid IP address: <ip> and prevents the save. An empty field is a legitimate value that means allow all source IPs while dynamic whitelisting is off; this is the default state on a fresh deployment. Addresses are compared as addresses, not as text, so an IPv4 address written by a proxy in its IPv6-mapped form (::ffff:203.0.113.5) still matches its IPv4 entry. IPv6 addresses match exactly.
Save writes the list and applies it at once. If the list you are about to save is not empty and does not contain the address your own browser session comes from, the page asks for confirmation first, because your next request would be rejected. An address that is covered by an active dynamic entry counts as contained.
Caution: If you lock yourself out anyway, recovery is direct database access on the Console host. Run the statement below in MySQL; the Console picks it up within ten seconds:
UPDATE settings SET ip_whitelist_dynamic_enabled = 0, ip_whitelist_web_console = NULL;
On a cloud instance, use the Reset IP whitelist action in the members portal instead; it does the same and also removes all dynamic entries.
Administrators who work from a connection without a fixed address (home office, hotspot, a provider that rotates addresses) cannot be on a static list. The section Dynamic whitelisting via Relay App lets them keep the whitelist anyway: the Relay App, which they already run and which authenticates against the NetLock server with its relay identity, asks the server to whitelist the public address it connects from. The server records that address as a temporary entry; the Web Console admits it while the entry has not expired.
Three things have to be true for a Relay App to use this:
The switch Allow Relay App users to whitelist their address on this page is on (off by default; nothing changes for an existing installation until an administrator turns it on).
The account behind the relay identity holds the permission Whitelist own address for the web console (Relay App) in the Relay Server group of Users → <account> → Settings (relay_server_ip_whitelist), and Relay Server access itself is enabled for that account. Existing accounts start without the permission.
The account is enabled. A relay identity whose account is disabled or deleted is refused on every relay route, not only on this one.
Lifetime of an entry (hours) sets how long an entry lasts after it was added or last refreshed: 1 to 168 hours, default 24. The same lifetime applies to entries added with the button and to entries the Relay App refreshes automatically.
Enabling with an empty static list. When you turn the switch on while the static list is empty, the whitelist changes from "everyone" to "only dynamic entries". So that you keep access, the page asks for confirmation and then writes a seed entry for your own current address with the configured lifetime. The seed entry shows in the table with the source Seed and the relay identity Web console. Whitelist your own address from a Relay App, or add it to the static list, before the seed entry expires.
Active dynamic entries. The table lists every entry that has not expired: address, owning account, relay identity, source (Manual for the button, Auto for the timer, Seed for the row the console wrote), the machine name the Relay App reported, when the entry was created and last refreshed, and when it expires. Refresh reloads the list; the Revoke icon in the actions column deletes an entry after a confirmation, and the address is rejected with its next request. Revoking does not stop the identity from adding the address again a minute later. To stop an identity, remove the permission from its account, delete the identity, or turn the switch off.
Automatic removal. Entries are deleted, and their addresses rejected at once, when the owning account is saved as disabled or without the permission, when the account is deleted, and when the relay identity that added them is deleted or has its hardware id reset. A password change does not affect entries.
Limits. An account may hold ten active entries and an instance five hundred; the Relay App reports limit reached beyond that, and an existing entry is always refreshed regardless of the limits. A refresh less than thirty seconds after the previous one is answered without a write. Repeated failed authentications from one address are answered with 429.
Audit. Creating an entry, removing it from the Relay App, revoking it here, and changing the switch or lifetime are recorded in the audit log under the entity ip_whitelist_dynamic; a refresh is not, so auto mode does not fill the log.
Once the server confirms the feature, the header button row of the Relay App shows Whitelist my IP, Remove my IP and the checkbox Auto-whitelist every minute. On a server that does not know the feature the controls stay hidden; while the switch on this page is off or the account lacks the permission they are shown disabled, with the reason as tooltip.
Whitelist my IP adds or refreshes the entry for the address the server sees. The status line at the bottom reports the address and the local time the entry lasts until, for example Address 203.0.113.5 whitelisted for the web console until 03.09.2026 14:22.
Auto-whitelist every minute refreshes the entry every sixty seconds while the app runs, including while it is locked. The setting is remembered across restarts. When the public address changes, the new address is whitelisted on the next tick; the previous address stays until its entry expires. A temporary failure (server unreachable, too many requests, console not yet updated) keeps the timer running and reports once in the status line. A hard failure (feature disabled in the console, permission removed, account disabled, limit reached, server without the feature) turns the checkbox off and explains why.
Remove my IP deletes the entry for the current address and turns auto mode off, because auto mode would add the address again within a minute.
The Relay App and the NetLock server are released in lockstep: this feature needs a Relay App build that knows it and a server that expects that build.
The Relay App whitelists the address the server sees it connect from; the browser has to reach the Web Console from that same address. Normally both leave through the same NAT and this holds. It does not hold when the browser and the Relay App take different routes:
a VPN with split tunnelling,
a browser proxy or PAC file,
privacy tools that route the browser only,
a dual-stack mismatch where the Web Console host has an AAAA record and the server host does not (the browser then arrives over IPv6 while the Relay App whitelisted the IPv4 egress, or the reverse).
The 403 page prints the rejected address and the Relay App shows the whitelisted one, so the mismatch is visible. The fix is on the client side.
For deployments behind a reverse proxy or load balancer, both the NetLock server and the Web Console have to trust the forwarded client address (X-Forwarded-For with the proxy configured as trusted). If the server sees only the proxy's address, that is what gets whitelisted; if the Web Console sees only the proxy's address, every request appears to come from the same source.
Allowlist, empty means all. An empty static list with dynamic whitelisting off means "allow all"; anything else means "allow only these".
Instance-wide. The list applies to all administrators equally; dynamic entries are bound to the account and relay identity that added them only for the purpose of listing, revoking and automatic removal.
No description per static entry. If you need to remember why a specific IP is in the list, keep a separate note.
IP addresses only. Individual IPv4 and IPv6 addresses; no CIDR blocks, DNS names or wildcards.
Add your new address before removing the old one; the list is live at the moment of save.
After changing the static list, confirm you can still sign in as an unprivileged account as well as your admin account.
Review the static list annually and the active dynamic entries whenever an administrator leaves. Rotate the whitelist on the same day you disable the account; disabling the account already removes its dynamic entries.
If you rely on dynamic whitelisting alone, keep at least one administrator with the permission and a working Relay App, or a static entry for a fixed site, so the switch can always be reached.
IP whitelisting and SSO are complementary, not alternatives. When both are in effect, a request must pass the IP filter and satisfy an SSO-compatible identity before it gets in. In practice this means:
A user on a whitelisted IP with the wrong identity is still refused.
A user with a valid SSO identity but an unwhitelisted source IP never sees the SSO sign-in page, because the IP filter applies first.
If you operate a strict IP-restricted environment and also use SSO, verify that both gates are configured independently before rolling out. Missing one does not compromise the other, but users can easily mistake an IP filter rejection for a problem with the identity provider.
The country restriction limits who can reach the Web Console and the NetLock server by the country of the source address. It lives on the same page as the IP whitelist, Settings → Security, on the tab Country restriction (/settings/security?tab=countries), behind the same permissions (settings_enabled and settings_ip_whitelist_enabled). Unlike the whitelist it covers both applications: one list for the Web Console and one for the server.
The country of an address comes from the GeoIP database that already drives the device world map. The Web Console and the server both ship that database as geodb/geoip.mmdb next to their binaries, and read it locally without asking an external service. The database needs no configuration, key or volume. The same database fills the country of every device, see Country of a device.
Country restriction for the web console and Country restriction for the server each consist of a switch, a country picker and a Save button of their own:
Restrict web console access to the selected countries and Restrict server access to the selected countries turn the respective list on.
Allowed countries is a picker over the ISO 3166-1 countries (plus Kosovo): type a two-letter code or a name in the language of your console, pick the country, and it appears as a chip with its flag. The codes are stored; the names follow the console language.
Copy from web console list fills the server picker with the web console selection; it does not save.
A list is in effect only while its switch is on and it holds at least one country. Saving a list with the switch on and no country is refused (Select at least one country or turn the switch off.). By default both switches are off and both lists are empty, so nothing changes until you turn a list on.
A third block, Addresses without a country, holds one switch that applies to both lists: Allow addresses the GeoIP database has no country for, on by default. Turned off, an address the database has no record for is refused wherever a list is active.
Every request to the Web Console and every request to the server is checked before anything else handles it: page loads, the Blazor connection, static files and sign-in callbacks on the Web Console; agent check-ins, downloads, file operations, the SignalR hubs, relay routes and the public API on the server.
While no list is active, everything passes.
Addresses from private networks, the local machine and link-local ranges always pass: the RFC 1918 ranges, carrier-grade NAT (100.64.0.0/10), 169.254.0.0/16, fe80::/10, fc00::/7 and loopback. They are never looked up and never counted. On a single-host Docker installation the Web Console reaches the server through such an address, and so do the agents on the LAN of an on-premises server.
Calls the Web Console makes to the server for a signed-in user are not filtered, so a Web Console hosted in another country keeps working. Browsers and apps that connect to the server directly are filtered (see the next section).
The country of the address is looked up in the database and cached in memory. A listed country passes; any other country is refused with 403.
An address the database has no country for follows the Addresses without a country switch.
If the GeoIP database is missing or cannot be opened, the failure is written to the log and the settings page shows a warning banner with its path.
The Web Console re-reads the settings every ten seconds and the server every sixty, so a saved change is live within that window without a restart. A Blazor session that is already open is not cut; it ends at its next reconnect or page load.
A refused request receives status 403. The Web Console answers with a small page that shows Access denied, Connections from your region are not permitted by this installation. and Your address: 203.0.113.5 (US). The server answers with the same sentence as plain text: Access denied. Connections from your region are not permitted by this installation. Your address: 203.0.113.5 (US). The address and the two-letter country are named so that a legitimate administrator can tell the operator what to add; an address without a country shows (unknown). Agents in a country that is not listed receive that answer on every endpoint: they stop syncing, are reported as disconnected and trigger the disconnection notifications.
A server sensor of the kind Device country turns the server list into events, with the severity and notification channels of the sensor:
Monitor before you enable. Maintain the server list but leave its switch off. The trigger outside_countries reports every device that checks in from a country outside the list, while the device keeps working. Together with the Connections by country tile below, this shows which devices a restriction would cut off before it is turned on.
Refused devices. With the switch on, the trigger refused reports an authorized device the server has refused because of its country. The device is identified by its access key and hardware ID in the refused request. Unknown devices, new installations in a refused country and browsers or apps produce no event; they appear in the log and the statistics only.
Country changes. The trigger country_changed reports a device whose country differs from its last known one, independent of the list.
Each device is reported once per country and trigger until it checks in from a listed country again, and the same country no earlier than 24 hours after the last event for it. A new or changed sensor takes effect within a minute. Below the server list, the page links to /manage_sensors for accounts with the sensor permission.
The exception for the Web Console only covers calls it makes on the server side. Several functions connect the browser of an administrator, or one of the apps, to the server directly, and the server list filters them like any other client:
remote screen control and audio calls (the browser connects to the screen hub of the server),
agent installer downloads, file downloads from the file browser and the installer links the console offers,
the Relay App, which connects to the tunnel hub for relay sessions and dynamic whitelisting,
the Console App, which checks its version against the server,
clients of the public API and the Swagger page.
So the server list must contain every country administrators and Relay App users work from, in addition to the countries of the fleet. The alert above the server list says so. The licence check against the Members Portal is an outgoing connection of the server and is not affected.
Each save checks the list you are about to save against your own current address, resolved with the same rules the check uses:
Web Console list. A list that does not contain your own country is not saved: Not saved: your current address 203.0.113.5 resolves to United States (US), which is not in the list. You would lose access to the web console with your next request. The same applies when your address has no country in the database and addresses without a country would be refused.
Server list. The same condition asks for confirmation instead of refusing, because the server list blocks remote screen control, downloads and the Relay App from your address, not the console itself: Your current address 203.0.113.5 resolves to United States (US), which is not in the server list. Remote screen control, downloads and the Relay App from your address will be refused by the server. Do you want to continue?
Addresses without a country switch. Turning it off is checked against both saved lists in the same way: refused for the Web Console list, confirmed for the server list.
Your own address is a private or local one (the console is reached over the LAN or through a VPN into its network): the list is saved and an info message reminds you that the rule never applies to your address and that the list should contain the countries administrators connect from.
Your address cannot be determined, or the database is not available: the page asks whether to save anyway.
The Status and lookup block shows what the page sees: Your current address 203.0.113.5 resolves to Germany (DE). (or that it is private, unknown to the database or not determinable), the counter Connections refused by the web console since start, and Look up an address, which resolves any address to its country, city and region against the bundled database. Use it to check how a customer site or a colleague's address will be treated before a list is turned on.
Caution: If you lock yourself out anyway, typically as an administrator behind a VPN exit or on a roaming connection, recovery works as for the IP whitelist. On a cloud instance, the Reset IP whitelist action in the members portal also turns both country switches off. On a self-hosted instance, run the statement below in MySQL; the Web Console picks it up within ten seconds and the server within a minute, without a restart. The lists themselves are kept, so the restriction can be turned on again once the missing country has been added.
UPDATE settings SET geo_allowlist_web_console_enabled = 0, geo_allowlist_server_enabled = 0;
Two tiles below the lists show where connections come from, whether or not a list is active, so that the countries a fleet connects from are known before a restriction is turned on:
Connections by country counts, per day and country, the connections the Web Console and the server admitted and refused. One address counts at most once per ten minutes and country, so page assets and agent polling do not inflate the numbers. Only the country and the counters are stored, never an address, and the rows are kept for 90 days. While the database file is not available, nothing is counted. The table has:
a period selector (Today, Last 7 days, Last 30 days, All),
the columns Web console allowed, Web console blocked, Server allowed, Server blocked and Last seen, and a row Unknown for addresses without a country,
per row the actions Add to web console list and Add to server list, which put the country into the picker above (the list still has to be saved).
Reset statistics deletes all counted rows of both applications after a confirmation and writes an audit entry.
Devices by country counts the authorized devices of the tenants you are assigned to by the country of their external address: the ten largest countries, a row … more countries for the rest and a row No country (private address or not synced yet).
A refused request is written to the log with severity WARNING, module Middleware, event Geo allowlist: Address 203.0.113.5 (US) refused for /downloads/…: Blocked. At most one line per address is written every ten minutes, so a scanner cannot flood the log. In the Web Console the line lands in warning.log and combined.log (Settings → Logging → Web Console Logs), on the server in the files of the same name (Server Logs tab); see A.9. Both applications echo the database path, its build date and the state of the restriction at start-up.
Saving a list, changing the switch for addresses without a country and resetting the statistics are recorded in the audit log under the entities geo_allowlist_web_console, geo_allowlist_server, geo_allowlist_unknown_allowed and geo_allowlist_statistics, with the previous and the new value.
Until the Web Console has restarted after the update, the tab shows a notice and its controls are disabled.
A server that is older than the Web Console treats the server list as off, writes no device country and logs that once.
On a split-host installation (Web Console and server on different hosts with public addresses), update the Web Console before you turn the server list on. Otherwise its relay pages, remote control tokens and hub connections are refused as soon as the country of the Web Console host is not listed.
Rate limiting restricts how many requests each agent may send to the NetLock server and blocks, for a limited time, devices and addresses that keep exceeding their limits. It lives on the tab Rate limiting of Settings → Security (/settings/security?tab=rate-limiting), behind settings_enabled and settings_rate_limiting_enabled. It covers the agent-facing side of the server only: check-ins, events, reports, the tray ticket and end-user chat endpoints, hub connections of the agents, device file transfers and installer downloads. The Web Console, the Relay App, the public API and the Members Portal are not subject to it.
The purpose is to keep one misbehaving device (a compromised agent, a reinstall loop, a script that floods the event queue) from taking the server down for the rest of the fleet, and to keep floods of requests without a valid identity away from the database. Legitimate traffic, including the backlog a device delivers after a week offline and a large SNMP collector, stays far below the limits. The limits catch abnormal traffic and are not usage quotas.
Mode has three values; the server applies a change within thirty seconds.
Off: nothing is counted or limited.
Observe: everything is counted, requests that would have been refused and blocks that would have been imposed are recorded, but no request is refused. Observe is the default on self-hosted installations; cloud instances run in Enforce, see NetLock cloud.
Enforce: requests above a limit are answered with 429, and a device or address that keeps exceeding its limit is blocked for a while.
Run in Observe first. The tab shows an info banner while it is on, the KPI tiles Would be refused (24 h) and Would be blocked (24 h) fill up, and a block that would have been imposed appears in the Blocks table with the chip Observed and writes an event whose title reads … would be blocked by rate limiting (observe mode; …). After seven days in observe mode without such a block the banner changes to No block has been recorded for 7 days; rate limiting can be enforced. Switching to Enforce asks for confirmation and names how many devices and addresses would have been blocked in the last 24 hours.
Blocks recorded in observe mode never refuse anything, not even after the switch to Enforce. The levels of the two modes are counted separately, so the first enforced block of a device starts at level 1.
The limits are derived from two settings, so no individual values need tuning:
Device count.Counted devices is the number of devices the instance knows, pending ones included, refreshed every minute. Expected devices is optional and only ever raises that number, for a planned rollout; a value that is too low never tightens the limits.
Sensitivity.Relaxed doubles the limits and blocks later, Normal (the default) keeps the limits, Strict halves the limits and blocks sooner.
A third setting, Daily data volume per device (MB), is a budget of its own: how many bytes of request bodies a device may send per day, counted after decompression, across check-ins and inventory uploads, events, reports and the interactive endpoints. Default 1024 MB, allowed 64 to 102,400. The budget starts full and refills continuously over the day (a 1 GB budget refills at about 12 KB per second); it does not reset at midnight.
File transfers between the device and the file server, the screen, tunnel and command hubs, and downloads are not counted. A typical device uses well under 100 MB per day. An SNMP collector needs roughly hosts × runs per day × 2 KB; 2,048 hosts polled every 15 minutes come to about 0.4 GB per day. Raise the budget or add an exemption for a collector beyond that.
Derived limits (an expandable table under the settings) shows the rate and burst of every class for devices, addresses and the instance that follow from your device count and sensitivity, before you save them.
Every request that reaches an agent endpoint is assigned to a class and to a subject:
A request from a known device (its access key is in the device table, pending devices included) is charged to that device. Known devices are never limited or blocked by their address, so a site with hundreds of devices behind one NAT address needs no special treatment.
A request without a known identity (no identity, an invalid one, or an access key the instance does not know) is charged to the source address (IPv4 addresses individually, IPv6 addresses as their /64 network). Installer and update downloads are charged to the address as well. Two instance-wide limits sit above the per-address ones.
Per-device limits do not depend on the device count; an agent sends the same amount whether the fleet is small or large. The requests of a device fall into these classes:
Class
What it covers
Can block
Sync
Check-in, version check, policy download, inventory upload, deployment and uninstall pulls; check-in and sync of mobile devices
yes
Events
Delivery of events from the agent queue
yes
Telemetry and reports
SNMP results and discovery, application and device control reports, patch, BitLocker and custom field reports, deployment and uninstall acknowledgements
yes
Interactive
Tray tickets and the end-user AI chat
yes
Hub connections
Connection set-up of the command hub and the screen hub
yes
Tunnel connections
Connection set-up of the tunnel hub — one per NetMesh link or relay session
yes
Device files
Uploads to and downloads from the device through the file server, counted as requests only, never by size
only on a clear flood
Data volume
The daily budget above
yes
Hub messages
Calls on an open command hub connection
no; observed only
Each class has a rate a device may send continuously and a burst it may send at once on top of that; Derived limits shows both. An offline credit of the events class keeps a backlog from looking like a flood: a device that was out of contact with the server for up to seven days delivers its queued events without a violation. After a server restart the credit is derived from each device's last check-in.
The limits per address and per instance grow with the device count, because a larger fleet has larger sites and larger rollouts; Derived limits shows their current values. The sensitivity applies to the per-device and per-address limits and to the instance-wide limit for requests without a known identity. The two capacity limits of the instance, hub handshakes and all agent requests, are not scaled, answer with 503 instead of 429 and never count against a device or an address.
The answer is sent before the request reaches the database, in plain text, with Cache-Control: no-store:
Above a limit:429 with body rate_limited and a Retry-After header that says after how many seconds the next request fits.
Daily volume spent:429 with body volume_exceeded; Retry-After is the time until one percent of the budget has refilled, about 14 minutes at 1 GB.
Blocked:429 with body blocked; Retry-After is the remaining time of the block.
Instance overloaded (hub handshakes or all agent requests): 503 with body overloaded and a Retry-After of 5 to 30 seconds. This spreads a herd of reconnecting agents after a server restart; it is never a violation.
Request body too large:413 with body payload_too_large. The limits are 64 MB for the inventory upload, 4 MB for events and 16 MB for every other agent request, measured after decompression; the tray ticket endpoints keep their own 512 KB (8 MB for attachments). In observe mode only the ticket limits are applied and an oversized body is counted; in enforce mode an oversized body is refused and counts as a violation. Device file transfers have no size limit.
Nothing is discarded. An event that was refused stays in the queue of the agent and is delivered later; a refused check-in is repeated at the next interval.
A violation minute of a class is a minute in which many requests of a subject were refused, or in observe mode would have been refused. A subject that collects several violation minutes within ten minutes is blocked; the sensitivity sets how many. Too many parallel event requests or hub connections of one device and an oversized request body count as a violation minute at once.
Device blocks last 5 minutes at level 1, 15 at level 2 and 60 from level 3 on; the level falls back to 1 after 24 hours without a block. While a device is blocked, every request from it is answered with blocked, its open command hub and screen hub connections are ended (on other server instances within thirty seconds), and it shows the chip Blocked until <time> next to its name in the devices list. A block does not extend itself: the polling of a blocked agent is not a violation, and after the block ends the device needs a fresh set of violation minutes for the next one. Because of the 60-minute cap, a false positive is released automatically within the hour.
Address blocks follow floods of requests with an unknown identity or repeated failed authentication from one address; they last 15, 60 and 240 minutes. A blocked address is refused for requests without a known identity and for downloads; known devices behind the same address keep working.
Every block start writes an event of the type Rate limiting (in enforce mode with severity High, in observe mode with Moderate) that names the device or address, the class, the reason, the measured rate against the limit, the violation minutes, the level, the duration and the instance that decided it. Reported by reads Rate limiting. These events are not sent to notification channels or as push messages; they are visible on /events, on the device's Events tab and in the event widgets. Address blocks have no device and are shown only to accounts with access to every tenant. Throttling alone writes no event; the statistics on the tab cover it. See Chapter 12.2.
Unblocking.Unblock on a row and Unblock all above the table release blocks after a confirmation; the server picks the release up within thirty seconds and then grants the subject fifteen minutes of grace in which it can be throttled but not blocked again. Both are written to the audit log. Expired blocks and manual releases stay in the History filter of the table for 90 days, with Released by naming the account or Expired. Export data writes the current filter as JSON, CSV or HTML.
Exemptions. A device, or an address or CIDR range, on the Exemptions table is still counted but never throttled, blocked or shed. An exempt address also covers the known devices behind it. Use it for a collector that outgrows the volume budget or a site whose NAT address keeps producing unknown-identity floods you have accounted for. Address exemptions can be added by accounts with access to every tenant; device exemptions by anyone who may see the device. Adding and deleting an exemption is audited.
Above the settings a KPI row shows the blocked devices (with a caption for blocks recorded in observe mode), the blocked addresses (accounts with access to every tenant only), and the refused, would-be refused and would-be blocked counts of the last 24 hours.
Below the Blocks table, Top subjects (24 h) lists the fifty devices and addresses with the most refused and would-be refused requests per class, with the peak per minute and the last contact, and Top data volume lists per device the largest daily volume of the last seven days, summed over all server instances, as a share of the budget. Both refresh with their Refresh button; the statistics behind them are written by the server once a minute.
The mode, the device count, the sensitivity and the daily volume are instance-wide. The tables follow the tenant scope of the account: device rows of the tenants you are assigned to; address rows, the Blocked addresses tile and address exemptions only with access to every tenant.
Saving the settings, releasing a block, adding or deleting an exemption and exporting the blocks are recorded in the audit log under system_setting (entity name agent_protection, with the previous and the new values), agent_protection_block and agent_protection_exemption.
On NetLock cloud instances rate limiting always runs in Enforce with sensitivity Normal and the default daily volume of 1,024 MB per device, and Expected devices is the device limit of your license, so the limits follow the licensed device count rather than only the devices enrolled so far. These values cannot be changed, so the tab does not show the settings. The KPIs, the blocks, the top lists and the statistics work as described above, and Unblock, Unblock all and the Exemptions table stay available.
Blocks, releases, exemptions and the settings reach every server instance within thirty seconds; the other instances also end the hub connections of a blocked device. A server restart never causes a block, and a backlog that piled up during the downtime is delivered without a violation.
The server logs its state at start ([Rate limiting] observe, preset normal, 512 devices counted, N = 512, volume 1024 MB per device and day, 0 active block(s), 0 exemption(s)), every block as a warning with the class, the reason and the measured rate, and the hub connections it ended. Statistics and top subjects are kept for 30 and 7 days, daily volumes for 30 days, released blocks for 90 days; the server deletes older rows once a day.
The tab Sessions of Settings → Security (/settings/security?tab=sessions) sets how long a sign-in to the Web Console stays valid. It needs settings_enabled and settings_sessions_enabled.
Idle timeout (minutes): a session without an open Console tab ends after this time (5 to 43200, default 720). A lowered value also applies to existing sessions from their next activity.
Maximum lifetime (hours): a session ends after this time even while it is in use (1 to 8760, default 168). It applies to new sessions; existing sessions keep the lifetime they got at sign-in.
Offer "Stay signed in" on the sign-in page: when on (default), users can stay signed in across browser restarts. Turning it off removes the option; existing sessions keep their lifetime.
"Stay signed in" lifetime (days): a session created with Stay signed in ends after this many days, regardless of activity (1 to 365, default 30).
Saving writes an entry to the audit log. Nothing restarts.
Settings → SSO at /settings/sso configures OpenID Connect for the Web Console. Once SSO is enabled and a user account's authentication mode allows SSO, that user signs in through their identity provider instead of (or in addition to) a local password.
Five providers are supported, each on its own tab:
Azure AD
Keycloak
Google (Workspace / Identity)
Okta
Auth0
All five are OpenID Connect. SAML 2.0 is not supported. There is no SAML metadata file to export from the Console or import into it. If your identity provider is reached through SAML only, you will need a bridge (such as a federation layer that translates SAML to OIDC) between it and NetLock RMM.
Several identity providers offer SAML as their default path. Register NetLock RMM as an OpenID Connect client instead: App registrations in Microsoft Entra ID (not Enterprise applications → Single sign-on → SAML), an OIDC — Web Application in Okta, and a Regular Web Application in Auth0.
Only one SSO provider can be active at any given time. Each provider tab has its own Enable <Provider> switch; turning one on automatically turns the others off. An informational alert on the page points this out.
A licence in a valid state. SSO is available on every deployment, and configuring and saving it does not depend on the licence plan. SSO sign-in is refused while the deployment's licence is banned, expired or deactivated, which is the same condition that blocks the Console as a whole.
Pre-provisioned user accounts. NetLock RMM does not create accounts automatically on the first SSO sign-in. Every user who will sign in via SSO must already exist in Users with their Auth Mode set to SSO or Password & SSO, and the username on the NetLock account must match the email claim the provider returns. When the username is matched against the email claim, the address has to be verified at the provider: a sign-in whose ID token carries email_verified with the value false is refused, with a message on the sign-in page and the line SSO | <Provider> email_not_verified in the web console log. A username matched against preferred_username or upn, or an ID token without the claim (as with Microsoft Entra ID by default), signs in as before. See Chapter 14.2 for how to create users with the correct auth mode.
A registered application on the identity provider. The identity provider needs a client registration pointing back at your Console. The redirect URI is https://<public-host>/<callback-path>; see the section on callback paths below.
Each provider tab asks for a Callback Path (and its signed-out counterpart) as a path, not a full URI. The Console constructs the full redirect URI at runtime by combining the public host of the Console with the path. When you register the application at the identity provider, you assemble the full URI manually:
https://<public-host>/<callback-path>
For example, with a Console at https://console.example.com and the default Azure AD callback path of /signin-oidc, the redirect URI you register at Azure AD is https://console.example.com/signin-oidc.
If you leave the callback path field blank, the Console falls back to the per-provider default listed in the helper text on each field (/signin-oidc for Azure AD, /signin-keycloak for Keycloak, and so on). The defaults work and are the recommended choice.
Each provider tab shows the resulting sign-in and post-logout redirect URI below the path fields, with a copy button. The values follow the address the page is opened with and the Force https in redirect URLs switch as it will apply after saving.
SSO login does not create NetLock accounts on demand. When a user signs in via SSO, the Console extracts the email address from the identity provider's token and looks for an account with a matching username that has an SSO-compatible authentication mode. The account must therefore already exist, and its Auth Mode must be either SSO or Password & SSO.
If the account does not exist, or if it exists but its Auth Mode is Password only, the Console rejects the sign-in with:
User is not authorized for SSO login. Please contact your administrator.
When a new technician joins your team, provision their NetLock account first (see Chapter 14.2), set their Auth Mode to SSO or Password & SSO, and make sure the username exactly matches the email address they will authenticate with at the identity provider. Only then point them at the Console's login page.
When you create a user, you pick one of three auth modes (also covered in Chapter 14.2):
Password: local password only. Cannot sign in via SSO.
SSO: SSO only. The local password slot is disabled.
Password & SSO: either mechanism. Useful during migrations, where you want to keep password fallback available until every user has successfully used SSO at least once.
The SSO Settings page has a single Save button. The page has no Test button. To validate the configuration, sign out and attempt an SSO sign-in yourself.
Before the configuration is written, a confirmation dialog appears:
The web console will automatically restart after saving the SSO configuration. All active user sessions will be terminated. Do you want to continue?
Confirming writes the configuration and restarts the Console. Every signed-in user, including you, is returned to the login page.
If the stored SSO configuration fails to load at application startup, for example because a provider secret was rotated without the Console being updated, the page shows a red banner the next time it is opened:
SSO Configuration Error! The SSO configuration could not be loaded during application startup and SSO is currently DISABLED.
When you see that banner, fix the misconfiguration, save again, and restart.
Pilot with a single power user first. Set one user's Auth Mode to Password & SSO, confirm they can sign in either way, then roll out across the team.
Keep at least one break-glass local account with Auth Mode set to Password. If the identity provider is unavailable, that account is your only route back into the Console.
Rotate provider secrets in the identity provider and the NetLock SSO page on the same day, and warn the team before you save, because saving always restarts the Console.
Document the provider's redirect URI and the NetLock account's Auth Mode setting in your onboarding runbook.
"User is not authorized for SSO login." The account either does not exist with the expected username, or its Auth Mode is Password. Confirm the username on the NetLock account exactly matches the email claim the provider issues, and confirm Auth Mode is SSO or Password & SSO.
Callback URI mismatch reported by the provider. The redirect URI registered on the provider side does not match what the Console constructs. Re-derive the URI from https://<public-host>/<callback-path> and register exactly that value at the identity provider, with no trailing slash differences.
Post-restart red banner on the SSO page. The saved configuration could not be loaded at startup. A typical cause is a secret that was rotated at the provider but not updated in the NetLock SSO page, or an Authority / Instance URL that contains a typo. Fix the stored value and save again to retry the startup load.
Everything works except sign-out. The Signed Out Callback Path is either missing or not registered at the identity provider. Add it in both places.
The provider reports a redirect URI mismatch and the URI it received begins with http://. The Console is behind a reverse proxy that terminates HTTPS without forwarding X-Forwarded-Proto, so the redirect URL is built from the internal scheme. Enable Force https in redirect URLs at the top of the SSO page and save. The log line SSO | <Provider> challenge names the URI that was sent.
The log shows Message contains error: 'invalid_request', error_description: 'Invalid parameter: redirect_uri'. Keycloak rejected the redirect URI at its pushed authorization endpoint, before the browser was redirected; the sign-in returns to the login page with the SSO error message. The Console writes the URI it sent to its log (SSO | Keycloak challenge), and the Keycloak tab on the SSO page shows the URI to register. The entries under Valid redirect URIs must match it character for character. If the log line contains forwarded_headers_applied=False, the reverse proxy is not listed in Kestrel:KnownProxies of the Console's appsettings.json (the install template lists 172.18.0.2).
If the failure does not fit one of these, confirm the licence is still in a valid state (Settings → Licensing, Chapter A.1.2). SSO sign-in is refused while the licence is banned, expired or deactivated, even though the stored configuration itself remains intact.
Chapter 8.3 — Server sensors — the Device country sensor, which reports devices outside the server list, refused by it or with a changed country.
Chapter 12.2 — Events — the event type Rate limiting and the Occurred (device) time of an event.
Chapter A.2.2 — Maintenance. Use a window to silence notifications during an IP or SSO change.
Chapter X.3 — Troubleshooting — covers common SSO callback and IP filter failure modes, a device blocked by rate limiting and a failed download from a device.