Single Sign-On on ntopng with OpenID Connect (OIDC)

11 min read

ntopng has always supported multiple authentication methods to fit different environments: local accounts, LDAP, RADIUS, HTTP basic auth, etc. Now it also supports OpenID Connect (OIDC), bringing native Single Sign-on (SSO) support for any standards-compliant Identity Provider (IdP), including Keycloak, Okta, Auth0, Azure AD / Entra ID, Google Workspace, and more.


Why SSO?

Managing separate credentials for every tool in a network operations centre is a maintenance burden and a security risk. Passwords get reused, accounts get forgotten, and off-boarding a staff member means hunting down every application they had access to.

With SSO, your Identity Provider is the single source of truth. Users authenticate once, with Multi-Factor Authentication (MFA) if your IdP enforces it, and are granted access to ntopng same as every other integrated application, based on their group membership and attributes. When a user leaves, disabling their Identity Provider account is all that is needed.


How SSO Works

ntopng implements the Authorization Code Flow, the recommended OAuth2 flow for server-side web applications. The token exchange happens entirely between the ntopng backend and the IdP. Credentials and tokens are never exposed to the browser.

Browser                  ntopng                   Identity Provider
  │                         │                             │
  │  Click "Login with SSO" │                             │
  │────────────────────────>│                             │
  │                         │ generate state + nonce      │
  │  302 → IdP login page   │ (stored in Redis, 10 min)   │
  │<────────────────────────│                             │
  │  Authenticate at IdP    -────────────────────────────>│
  │  (password, MFA, etc.)  │                             │
  │<──────────────────────────────────────────────────────│
  │  302 → /oidc_callback   │                             │
  │────────────────────────>│                             │
  │                         │ exchange code for tokens ──>│
  │                         │ validate JWT signature      │
  │                         │ check iss, aud, exp, nonce  │
  │                         │ map claims → ntopng user    │
  │  302 → original page    │                             │
  │<────────────────────────│                             │

After the Identity Provider validates the user and returns a signed JWT (ID token), ntopng infers the local username from the token claims in this order:

  1. preferred_username
  2. email
  3. sub

Admin vs. unprivileged role is determined by inspecting groups. If they contain the configured admin group name, the user is granted the administrator role, otherwise they are treated as an unprivileged user.

Network access restrictions (as well as other capabilities) for unprivileged users can be pushed directly from the Identity Provider via custom attributes. When present, ntopng limits the user visibility to the listed subnets, thus no manual per-user configuration inside ntopng is required. We show how to set this up in the Keycloak example below.

Auto-create users: when enabled, ntopng automatically creates a local account on the first successful OIDC login. When disabled, the account must be pre-provisioned manually, giving administrators explicit control over who can access ntopng even if they authenticate successfully at the Identity Provider.


Step-by-Step Example: Keycloak + ntopng

Let’s see how to configure a local Keycloak instance as the Identity Provider and point ntopng at it. In this example we assume that Keycloak is running on a host with IP 192.168.2.1, while ntopng is running on another host with IP 192.168.2.2.

1. Run Keycloak

We use a docker image for running Keycloak, which is really straightforward:

docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

Open http://192.168.2.1:8080 and log in with admin / admin.

2. Create a Realm

In the top-left dropdown choose Manage realms → Create realm.

  • Realm name: ntopng-realm

Click Create.

3. Create a Client

Navigate to Clients → Create client.

  • Client type: OpenID Connect
  • Client ID: ntopng

Click Next.

  • Client authentication: On
  • Authentication flow → Standard flow: On

Click Next.

  • Valid redirect URIs: http://192.168.2.2:3000/*
  • Web origins: *

Click Save.

4. Copy the Client Secret

Go to Clients → ntopng → Credentials.

Copy the generated Client Secret (e.g. naH5MpJ6Lgqy9jnS7YiFCwZaNlXNwbgT). You will need this when configuring ntopng.

5. Create the Admin Group and Add a Groups Mapper

Go to Groups → Create group.

  • Name: admin

Now add the mapper so the groups claim appears in the ID token. Navigate to:

Clients → ntopng → Client scopes → ntopng-dedicated → Configure a new mapper → By configuration → Group Membership

Name groups
Token Claim Name groups
Full group path Off
Add to ID token On
Add to access token On
Add to userinfo On

Click Save.

6. Create a User

Go to Users → Create new user.

Username Alfredo
Email verified On
Join groups admin (Administrator Users Only)

Click Create, then set a password under Credentials → Set password.

Password <your password>
Temporary Off

7. Restrict Network Access (Unprivileged Users Only)

This step shows how to push network-level access restrictions directly from Keycloak into ntopng, without any per-user configuration inside ntopng itself.

Create a custom user attribute. Go to Realm Settings → User Profile → Create attribute:

Attribute Name allowed-networks
Display name Allowed Networks
Multivalues On

Assign networks to the user. Go to Users → Alfredo → Attributes and add allowed-networks values:

192.168.1.0/24
192.168.2.0/24

Expose the attribute as a JWT claim. Navigate to:

Clients → ntopng → Client scopes → ntopng-dedicated → Configure a new mapper → User Attribute

Name ntopng networks
User Attribute allowed-networks
Token Claim Name allowed_networks
Claim JSON Type String
Add to ID token On
Add to access token On
Add to userinfo On
Multivalues On

Click Save. When ntopng reads the allowed_networks claim from the JWT it will automatically restrict the user’s visibility to those subnets.


8. Configure ntopng

Log in to ntopng as administrator and go to Settings → Preferences → User Authentication.

OIDC preferences
Screenshot

Enable OpenID Connect (OIDC) / SSO Authentication and fill in the fields:

Issuer URL http://192.168.2.1:8080/realms/ntopng-realm
Client ID ntopng
Client Secret naH5MpJ6Lgqy9jnS7YiFCwZaNlXNwbgT
Base Redirect URI http://192.168.2.2:3000
Scopes openid profile email roles
Group Claim groups
Admin Group admin
Auto-Create Users On
Allowed Networks Attribute allowed_networks

Click Save. ntopng will immediately fetch the OIDC discovery document from http://192.168.2.1:8080/realms/ntopng-realm/.well-known/openid-configuration and cache the token and JWKS endpoints for one hour.


Testing the Login

Open http://192.168.2.2:3000 in a browser. The login page now shows a “Login with SSO” button alongside the usual username/password form.

Login with sso

Click Login with SSO. The browser is redirected to the Keycloak login page for the ntopng-realm realm. After authenticating with the credentials created in step 6, Keycloak redirects back to ntopng.

ntopng will then:

  1. Verify the JWT signature using Keycloak public keys.
  2. Derive the username from the preferred_username claim.
  3. Check the groups claim: if admin is present, grant the administrator role.
  4. Auto-create the local account (because Auto-Create Users is enabled).
  5. Redirect to the originally requested page.

The user is now logged into ntopng, with no ntopng-specific password ever set.

Further configuration details are documented in the ntopng manual under Settings → Preferences → User Authentication → OpenID Connect (OIDC) / SSO Authentication.

Enjoy!

Related:ntopng, Network traffic analysis software

Try it on your own network

Download the free Community edition and see your first flows in five minutes.