This chapter covers the two 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 are unrelated mechanically, but they share an admin audience and a common theme — they determine who gets through the front door.
Both features 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 apply within a few seconds and do not restart anything.
Settings → IP Whitelist at /settings/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.
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. There is no way to block an identity from re-adding the address 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. Ten rejected authentications per minute from one address are answered with 429 for the rest of the minute.
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, or 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 semantics with an empty-equals-all escape hatch. 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 field 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 — the IP filter runs first at the middleware layer.
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 it does create a misleading failure mode where users blame the identity provider for what is actually an IP filter rejection.
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 in the current release. 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.
This is the single most common source of confusion during setup, because several identity providers present 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. The page shows an informational alert calling this out, so you do not accidentally leave two providers enabled on different tabs.
A licence in a valid state. SSO is available on every deployment and is not reserved for a paid tier — configuring and saving it is not gated 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 auto-create accounts on 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. 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; use them unless you have a reason not to.
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. In plain English: the account must 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. There is no in-Console Test button and no round-trip test pass — you validate by signing out and attempting an SSO sign-in yourself.
One gate stands between Save and the commit — a confirmation dialog:
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 is booted to the login page, including you.
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 on next open:
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. Flip 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 save with a small team warned — the restart is unavoidable.
Document the provider's redirect URI and the NetLock account's Auth Mode setting in your onboarding runbook. Most SSO support tickets arrive because one of those two was missed, not because the provider is actually misconfigured.
A handful of failure modes account for nearly every SSO incident. Recognising them early shortens the investigation:
"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.
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.
NetLock RMM Docs
