netbird-docs/src/pages/how-to/manage-network-access.mdx

import {Note} from "../../components/mdx";

# Managing Access with NetBird: Groups and Access Policies
NetBird empowers administrators to effectively manage and control access between resources (referred to as peers) using groups and access policies.
These access policies define which peers or peer groups are allowed to connect, specify the protocols and ports available
for these connections, and optionally incorporate posture checks. By integrating posture checks, NetBird enforces
zero-trust principles, enabling dynamic and context-aware access control that adapts to the specific security needs of
your environment.

Watch our Access Control video on YouTube:

<div className="videowrapper">
    <iframe src="https://www.youtube.com/embed/WtZD_q-g_Jc" allow="fullscreen;"></iframe>
</div>

<Note>
    For a visual overview of your access policies and network topology, check out the [Control Center](/how-to/control-center), which provides an interactive graph view of peers, groups, and their access relationships.
</Note>

## Introduction
Initially, a NetBird account is configured with a `Default` policy which allows peers to connect via any protocol, resulting in the formation of a full mesh network. This setup often suits small networks or those requiring minimal security. In scenarios where higher security is needed or access to specific resources must be restricted for certain users or services, policies can be set up to determine access permissions.


Access control policies make use of groups to control connections between peers. These groups, which are sets of peers (meaning different machines with the NetBird client installed), can be added as Source or Destination of a policy. They are evaluated when the Management service distributes the list of peers across your network.

## Concepts
### Groups
A NetBird group works and follows a similar concept to tags in other platforms; they are easily created and can be associated with peers and used in policies to control traffic within your network.

Here are some key attributes of groups:
- Each group is unique.
- A single group can have multiple peers.
- Peers can be part of multiple groups simultaneously.
- Groups can be included in the 'Source' and 'Destination' lists of policies.
- Groups can be created either in `Access Control > Groups` or in places where a group input field is provided. Type the preferred group name into the input and press 'Enter' to create the new group. [Learn more](#creating-groups)
- Groups can be deleted in `Access Control > Groups` [Learn more](#deleting-groups)
- There exists a default group called `All` which cannot be deleted or renamed.

<Note>
    You can assign groups automatically with the [peer auto-grouping feature](/how-to/register-machines-using-setup-keys#peer-auto-grouping).
</Note>

### The All Group
The 'All' group serves as a default group that automatically includes every peer in your network. This group cannot be modified or removed.

### Policies
Policies act as rules governing how different resources (peers) can communicate and connect. They specify the source and destination of communication and can allow bidirectional or unidirectional connections.

Policies are processed when the Management service shares a network map with all peers of your account. Because you can only create ALLOW policies, there is no processing order or priority. So, the decision to distribute peer information is based on its association with a group belonging to an existing policy.

For ICMP and ALL protocols, as well as for TCP and UDP protocols **without** specific port restrictions, communication between groups listed in the source and destination fields is bidirectional. This means that both source and destination groups can initiate connections with each other. To establish one-way connections, you must specify a protocol (UDP or TCP), along with a port.

<Note>
If you need to allow peers from the same group to communicate with each other, you can do so by adding the same group to the `Source` and `Destination` lists.
</Note>

Without policies, a network operates by denying traffic, meaning peers cannot communicate with each other. That's why the default policy is automatically created upon account creation.


### The Default policy
The `Default` policy is created when you first create your account. This policy is very permissive because it allows communication between all peers in your network, utilizing the [`All`](#the-all-group) group as both the source and destination. It's worth noting that the [`All`](#the-all-group) group is also automatically present when the account is being created. If you want to have better control over your network, it is recommended that you delete this policy and create more restricted policies with custom groups.

<Note>
    If you need to restrict communication within your network, you can create new policies and use different groups. Then, you can remove the default policy to achieve the desired behavior.
</Note>

### Multiple Mesh Networks
As mentioned above, policies are bidirectional by default, essentially controlling how your network behaves as a mesh network. However, for TCP and UDP protocols, if you specify ports in the policy, it can become unidirectional.

There is a `Default` policy, which configures a default mesh connection between all peers of your network. With policies, you can define smaller mesh networks by grouping peers and adding these groups to `Source` and `Destination` lists. Additionally, you can create unidirectional policies to restrict traffic between groups for TCP and UDP protocols if you define ports.

## Managing Policies

### Creating Policies
After accessing the `Access Control` > `Policies` tab, click on the `Add policy` button to create a new policy.
In the popup, specify connection `Source` and `Destination` groups. You can select existing groups or create new ones by entering a name in the input box.

<Note>
    We recommend using [identity provider (IdP) integrations](/how-to/idp-sync) to provision your user groups from the IdP.
</Note>

You can limit access to specific protocol and ports by selecting the `Protocol` and providing the port numbers in the `Ports` field.
Starting version `0.48` NetBird supports port ranges in policies, allowing you to specify a range of ports in the format `start-end` (e.g., `8000-9000`).
Make sure to set traffic direction only when TCP or UDP protocols are selected. Finally, provide a name and description for your policy.

<p>
    <img src="/docs-static/img/overview/create-rule.png" alt="high-level-dia" className="imagewrapper"/>
</p>
If necessary, you can also add a [posture checks](/how-to/manage-posture-checks) to the policy. Posture checks are used to ensure that the peer meets certain security requirements before allowing it to connect. You can select from predefined posture checks or create custom ones.

Once you have finished configuring the policy, click `Add Policy` to save it. You will then see your new policy in the table.
<p>
    <img src="/docs-static/img/overview/new-rule-list.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>

<Note>
    Because of its permissiveness, new policies will take effect once you remove the `Default` policy.
</Note>

<Note>
Protocol type All or ICMP must be bi-directional. Also unidirectional traffic for TCP and UDP protocol requires at least one port to be defined.
</Note>

### Adding peers to groups
If you create a new group when defining a policy, you will need to add a peer to the group for the policy to take effect.
You can assign a peer to a group by accessing the `Peers` section. Then, choose the specific peer you want to assign to a group. Click on the `Assigned Groups` select box and select the group(s) you wish to assign to this peer.

<p>
    <img src="/docs-static/img/overview/associate-peer-groups.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>

<Note>
    You can assign groups automatically with the [peer auto-grouping feature](/how-to/register-machines-using-setup-keys#peer-auto-grouping).
</Note>

### Updating Policies

To update a policy, just click on its name and customize it according to your requirements. This action will open the same screen where you can update policy groups, descriptions, and status, or modify allowed traffic direction, protocols with ports, and posture checks, similar to the information described in the "Creating Policies" section above.

### Disabling Policies
To disable a policy, use the switch in the `Active` column of the table.
<p>
    <img src="/docs-static/img/overview/disable-rule.png" alt="high-level-dia" className="imagewrapper"/>
</p>

### Deleting Policies
To delete a policy, click on `Delete` in the table, and confirm the message that appears.

<p>
    <img src="/docs-static/img/overview/delete-rule-menu.png" alt="high-level-dia" className="imagewrapper"/>
</p>

## Managing Groups

### Creating Groups

You can create groups in two ways:

**Quick Creation (Inline)**<br/>
When you see a group input field anywhere in the dashboard (e.g. such as when creating policies), you can create groups directly from the input field.
1. Type your preferred group name into the input field
2. Press 'Enter' to create the new group

<p>
    <img src="/docs-static/img/groups/create-group-input.png" alt="Create group inline" className="imagewrapper"/>
</p>

**From Groups Page**<br/>
1. Navigate to `Access Control` > `Groups`
2. Click the `Create Group` button
3. Provide a name for your new group

<p>
    <img src="/docs-static/img/groups/create-group.png" alt="Create group from groups page" className="imagewrapper"/>
</p>

### Viewing Groups

**Groups Overview**<br/>
Navigate to `Access Control` > `Groups` to view all groups in your organization. This page shows:
- All existing groups
- Associated objects (peers, users, policies, etc.)
- Usage status (used/unused groups)

<p>
    <img src="/docs-static/img/groups/view-groups.png" alt="Groups overview page" className=""/>
</p>

**Group Details**<br/>
Navigate to `Access Control` > `Groups` and then click on any group name to view detailed information and manage associated objects:

- **Users**: View, assign, or invite users to this group
- **Peers**: Manage which peers are assigned to this group
- **Policies**: See policies where this group is used as a source or destination
- **Network Resources**: View associated resources from networks
- **Network Routes**: See network routes using this group (either part of the distribution, access control, or routing peer group)
- **Nameservers**: View nameservers using this group as a distribution group
- **Setup Keys**: See setup keys with this group as an auto-assigned group

<p>
    <img src="/docs-static/img/groups/view-group-detail.png" alt="Group details page" className=""/>
</p>

### Renaming Groups

1. Navigate to `Access Control` > `Groups`
2. Click the dropdown button (⋮) next to the group you want to rename
3. Select `Rename`
4. Enter the new name and click `Save`

<Note>
Groups synchronized from Identity Providers (Google Workspace, Entra ID, etc.) cannot be renamed.
</Note>

<p>
    <img src="/docs-static/img/groups/rename-group.png" alt="Rename group" className=""/>
</p>

### Deleting Groups

1. Navigate to `Access Control` > `Groups`
2. Click the dropdown button (⋮) next to the group you want to delete
3. Select `Delete`
4. Confirm the action by clicking `Delete` in the confirmation dialog

<Note>
Groups synchronized from Identity Providers (Google Workspace, Entra ID, etc.) cannot be deleted.
</Note>

<Note>
Groups with active dependencies cannot be deleted. First remove all dependencies in order to delete the group.
</Note>

<p>
    <img src="/docs-static/img/groups/delete-group.png" alt="Delete group" className=""/>
</p>