Security: IP whitelist & SSO

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. Both, when changed, restart the Web Console and disconnect every signed-in user. Plan the change accordingly, and if possible do it during a maintenance window so notifications are suppressed for the duration (see Chapter A.2.2).

A.4.1 IP Whitelist

Settings → IP Whitelist at /settings/ip-whitelist controls which source IP addresses are permitted to reach either the Web Console or the Backend services. The page has two tabs — Web Console and Backend — and each tab maintains an independent list.

The two scopes

The whitelist is split because the two surfaces serve different traffic. The Web Console is where your administrators sign in; its traffic originates from their workstations and office networks. The Backend is where agents and other server-to-server components talk to NetLock RMM; its traffic originates from the fleet's devices, relays.

A whitelist that is correct for the Web Console is almost never correct for the Backend, and vice versa. Treat them as separate decisions. Most deployments end up with a narrow Web Console whitelist (admin workstations and a VPN range) and a wider — often empty — Backend whitelist (agents connect from anywhere the fleet runs).

The Web Console tab

The tab opens with an informational alert:

Configure IP addresses that are allowed to access the Web Console. Enter IP addresses separated by commas. Leave empty to allow access from all IPs. The application will restart after saving.

Beneath the alert is a five-line text area labelled Allowed IP Addresses (comma-separated) with 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 — this is the default state on a fresh deployment.

Below the textarea is a Save & Restart button. Clicking it opens a confirmation dialog with the title Warning:

The web console will automatically restart after saving the IP whitelist configuration. All active user sessions will be terminated. Do you want to continue?

Confirming the dialog saves the value and immediately restarts the Web Console. Every signed-in user — including you — is booted to the login page. If your new whitelist does not include your own source IP, you will not be able to sign in again afterwards. Double-check the list before you confirm.

Caution: The whitelist is the only gate here. There is no master kill-switch on the page that bypasses it. If you lock yourself out, the only recovery is direct database access — an operator on the Console host must clear settings.ip_whitelist_web_console in MySQL and restart the Console.

The Backend tab

The Backend tab has the same textarea and the same helper text, and it enforces the same validation. Its informational alert is slightly different:

Configure IP addresses that are allowed to access the Backend services. Enter IP addresses separated by commas. Leave empty to allow access from all IPs. This configuration will be applied when the backend services restart.

The button is also labelled Save & Restart, but this tab does not show a confirmation dialog before saving. Clicking the button writes the value and surfaces a snackbar that reads Backend IP Whitelist saved successfully!. The backend services pick the new list up when they next restart.

The asymmetry is deliberate. Saving the Web Console whitelist terminates the admin's own session, so a confirmation makes sense. Saving the Backend whitelist does not disturb the admin's session at all, so no confirmation is needed.

The agent backend is designed to be exposed directly to the public internet — that is its normal operating posture, because agents connect to it from wherever the managed devices run: home networks, branch offices, mobile connections. Agents authenticate to the backend with credentials provisioned into the installer when it is built, so reaching the backend endpoint is not the same as being able to use it: a caller without valid agent credentials for your deployment gets nowhere. This is why the Backend whitelist is optional — it is defense-in-depth layered on top of the application-layer authentication, not the primary gate. Leaving the Backend list empty is a supported and common configuration. Populate it only when your fleet genuinely egresses from a fixed, known set of IP addresses and you want the additional network-layer restriction; for a fleet that connects from anywhere, an empty Backend list is the expected setup.

What the whitelist does and does not do

The whitelist is a network-layer control. It compares the source IP of an incoming request to the configured list and rejects requests outside it at the authentication and middleware layers. It has the following properties:

• Allowlist semantics with an empty-equals-all escape hatch. An empty list means "allow all"; a non-empty list means "allow only these". There is no explicit block list.
• No per-user scope. The list applies to all administrators equally. You cannot say "this IP is allowed for Alice but not Bob."
• No per-API-key scope. The list applies to all authentication types on the relevant surface.
• No description or comment field per entry. If you need to remember why a specific IP is in the list, keep a separate note — the UI stores the IPs only.
• IP addresses only. The field accepts individual IP addresses; it does not accept CIDR blocks, DNS names, or wildcards.

For deployments that operate behind a reverse proxy or load balancer, make sure the proxy is configured to forward the client's real IP (for example via X-Forwarded-For with trusted-proxy handling). If the proxy terminates the connection and the Console sees only the proxy's IP, every request will appear to come from the same source.

Operating tips

• Add your new IP before removing the old one. The list is live at the moment of save; replacing an entry on the same save means there is no window during which both are valid.
• Test from a device on the new network before saving — for example, by temporarily tethering a laptop to the new connection and verifying reachability.
• After changing the Web Console list, confirm you can still sign in as an unprivileged account as well as your admin account. An unprivileged account that cannot sign in because of IP filtering will not be able to report the problem to you.
• Review the list annually. Old office ranges and defunct VPN gateways accumulate quickly.
• When a technician leaves and the reason for the departure was contentious, rotate the whitelist on the same day you disable the account. Whitelists sometimes survive an account deletion longer than they should, and a stale entry pointing to a home IP is a sharper risk than most admins realise.

Interaction with SSO

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.

A.4.2 Single Sign-On

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.

Supported providers

Five providers are supported, each on its own tab:

1. Azure AD
2. Keycloak
3. Google (Workspace / Identity)
4. Okta
5. Auth0

All five are OpenID Connect. SAML 2.0 is not supported in the current release. 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.

One provider at a time

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.

Pre-requisites before you open the page

• A valid paid licence. Saving the SSO configuration requires code-signing availability on your licence (License.CodeSigned). Without it, a licence reminder dialog blocks the save and points you to the pricing page.
• 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.

Azure AD fields

Required: Client ID, Client Secret, Tenant ID, Domain.

Keycloak fields

Required: Authority, Client ID, Client Secret.

Google fields

Required: Client ID, Client Secret.

Okta fields

Required: Domain, Client ID, Client Secret.

Auth0 fields

Required: Domain, Client ID, Client Secret.

Callback paths and redirect URIs

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.

User provisioning — the one rule to remember

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.

Auth modes recap

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.

Saving the configuration

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.

Two gates stand between Save and the commit:

1. The licence reminder dialog opens if the deployment does not hold a code-signing-capable licence. There is no way through this dialog other than upgrading the licence.

2. A confirmation dialog reads:

   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.

Operating tips

• 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.

Troubleshooting common SSO failures

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.

If the failure does not fit one of these, confirm the licence is still valid (Settings → Licensing, Chapter A.1.2) — SSO saves are gated on a code-signing-capable licence, and a lapsed licence disables further changes even if the previously-saved configuration continues to run.

Permissions

Related chapters

• How-to H.11 — Enable SSO with Azure AD / Google. Step-by-step walkthrough for the two most common providers.
• Chapter 14.2 — Creating a user, including the Auth Mode field.
• 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.