some file

Groups Settings

Updated

The Groups tab in your account settings (the page itself is titled User Groups) controls how group memberships flow from users to their devices. Its main setting is Enable user group propagation. On self-hosted deployments it also holds the JWT group sync configuration.

To find it, log in to your NetBird dashboard and navigate to Settings > Groups.

This tab is only about account-wide group behavior. To view and manage the groups themselves, go to Access Control > Groups. See Access Control for how groups are used in policies.

Enable user group propagation

When this setting is enabled, the groups assigned to a user (their auto-groups) are automatically applied to every peer that user owns. If you add a group to a user or remove one, whether manually or through your identity provider, all of that user's peers are updated to match, and their access permissions change accordingly.

This is what makes user groups work as described in Access Control: assign a group like engineering-team to a user once, and every device they log into carries that membership.

This setting is enabled by default on new accounts.

What changes when you enable it

If the setting was off and you turn it on, NetBird runs a one-time sync across the whole account: every user's peers are added to that user's groups where they are not already members. Existing group memberships are kept, nothing is removed. If the sync changes memberships that policies depend on, the affected peers receive an updated network map right away, so access changes take effect without waiting for the next login.

While the setting is on, any later change to a user's groups is propagated to their peers immediately, in both directions: groups added to the user are added to their peers, and groups removed from the user are removed from their peers.

What changes when you disable it

Turning the setting off does not remove any group memberships that were already propagated. Peers keep the groups they have. From that point on, changes to a user's groups no longer affect their peers, and you manage peer group membership yourself, either on the individual peers or in Access Control > Groups.

JWT group sync

JWT group sync is configured on self-hosted deployments only. On NetBird Cloud these controls are not shown, and groups are synchronized through the IdP integrations instead.

If your self-hosted deployment uses an external identity provider, Enable JWT group sync lets NetBird extract group names from a claim in the user's JWT access token, create matching NetBird groups automatically, and assign them to the user. With user group propagation enabled as well, those groups then reach the user's peers.

Enabling the toggle reveals two fields:

  • JWT claim: the claim in the token that contains the list of group names, for example groups or roles.
  • JWT allow groups: an optional allow list. When set, only users whose token contains one of the listed groups can access NetBird at all.

JWT allow groups can lock you out. If you save an allow group that your own user is not part of, you lose access to NetBird along with everyone else outside that group. The dashboard shows a confirmation dialog before saving for this reason. Make sure your own user is a member of the allow group in your IdP before saving.

For setup instructions, including how to configure the groups claim in specific identity providers, see JWT group sync in the identity provider documentation.

Changing the settings

  1. Go to Settings > Groups.
  2. Toggle Enable user group propagation, and on self-hosted, configure JWT group sync if needed.
  3. Click Save Changes.

You need permission to update account settings to change anything on this tab, which in practice means an owner or administrator. Roles with read-only settings access, such as Network Admin and Auditor, can open the tab but the controls are disabled for them.