Reverse Proxy Authentication and Access Restrictions

NetBird Reverse Proxy supports multiple authentication methods and connection-level access restrictions to control who can access your exposed services. You can enable one or more methods on each service, or leave a service completely public. Authentication and access restrictions are configured per service in the Authentication tab when creating or editing a service.

Authentication methods

NetBird offers four authentication methods, each suited to different access patterns. You can enable any combination of them on a single service.

SSO (Single Sign-On)

SSO authentication requires users to authenticate through your identity provider (IdP) using OIDC before they can access the service. When a user visits the service URL, they are redirected to your IdP login page. After successful authentication, they are granted access to the service.

You can optionally restrict access to specific distribution groups from your IdP. When groups are configured, only users who belong to at least one of the selected groups are allowed through after authenticating.

Key details:

• Users authenticate via your existing identity provider (OIDC)
• Sessions last 24 hours before re-authentication is required
• Optionally restrict access to specific distribution groups synced from your IdP
• When no groups are selected, any authenticated user in your organization can access the service

Best for: Team services where you want to leverage existing identity management, internal tools that require user-level accountability, and services where you need group-based access control.

Password

Password authentication protects a service with a shared password that you define. When a user visits the service URL, they are prompted to enter the password before they can proceed. Passwords are securely hashed using Argon2id on the backend - the plaintext password is never stored.

Key details:

• Set a shared password when configuring the service
• Users must enter the correct password to access the service
• Passwords are hashed with Argon2id before being stored
• Sessions last 24 hours before re-authentication is required

Best for: Simple shared access to internal tools, staging environments, or services shared with external partners who do not have accounts in your identity provider.

PIN Code

PIN code authentication works similarly to password authentication but is limited to numeric input. When a user visits the service URL, they are prompted to enter the PIN code. PINs are securely hashed using Argon2id on the backend, just like passwords.

Key details:

• Set a numeric PIN code when configuring the service
• Users must enter the correct PIN to access the service
• PINs are hashed with Argon2id before being stored
• Sessions last 24 hours before re-authentication is required

Best for: Quick access scenarios, kiosk-style interfaces, or situations where a simple numeric code is easier to share than a full password.

Header Authentication

Header authentication validates a static header value on each request. This is designed for programmatic or machine-to-machine access where clients can include a custom HTTP header with their requests. The proxy checks the header before forwarding the request to your backend and strips the header so that authentication credentials are not leaked to the backend.

NetBird supports three header presets to simplify configuration:

You can configure multiple header entries on a single service. If multiple headers are configured, a request that matches any one of them is granted access (OR logic).

Key details:

• Header values are hashed with Argon2id before being stored, the same as passwords and PINs. The plaintext value is never stored.
• The matching header is stripped from the request before it is forwarded to the backend.
• Sessions last 24 hours before re-authentication is required.
• Header authentication works at the HTTP level, so it is available for HTTP services. It is not available for L4 services.

Best for: API clients, CI/CD pipelines, webhooks, monitoring probes, and any scenario where a browser-based login flow is not practical. Also useful alongside SSO: team members authenticate via SSO in a browser, while automated systems use header auth.

No authentication (public access)

Services can also be configured without any authentication. When no authentication method is enabled, anyone with the service URL can access it without any restrictions.

Best for: Public-facing websites, APIs that handle their own authentication internally, or services that are intentionally open to the internet.

Combining authentication methods

You can enable multiple authentication methods on a single service simultaneously. When more than one method is active, users can authenticate using any of the enabled methods - they choose which one to use when accessing the service.

For example, you could enable both SSO and Password on the same service. Team members who have accounts in your identity provider can authenticate with SSO, while external partners or contractors can use a shared password. This gives you flexibility without requiring everyone to be in your IdP.

Common combinations include:

Access restrictions

Access restrictions control which connections are allowed to reach your service based on the client's IP address or geographic location. Unlike authentication methods, access restrictions operate at the connection level and work for both HTTP and L4 services.

Access restrictions are evaluated before authentication. If a connection is blocked by an IP or country rule, it is rejected immediately without any authentication check.

IP CIDR restrictions

You can define IP allowlists and blocklists using CIDR notation:

• Allowed CIDRs: if non-empty, only connections from IPs matching these CIDRs are permitted. All other IPs are rejected.
• Blocked CIDRs: connections from IPs matching these CIDRs are rejected. Evaluated after the allowed list.

The evaluation order is: if an allowed list is present, the IP must match it first. Then the blocked list is checked. This means you can use an allowed list to broadly permit a range, then use the blocked list to carve out exceptions.

Example: allow your office network but block a specific subnet:

Country restrictions

You can restrict access based on the client's country, determined by GeoIP lookup on the source IP address:

• Allowed countries: if non-empty, only connections from these countries are permitted. Specify ISO 3166-1 alpha-2 country codes (e.g., US, DE, GB).
• Blocked countries: connections from these countries are rejected.

The evaluation logic mirrors CIDR restrictions: if an allowed list is present, the country must match. Then the blocked list is checked.

Combining restrictions with authentication

Access restrictions and authentication methods are independent layers:

1. Connection arrives at the proxy.
2. Access restrictions are evaluated first: IP CIDRs, then country. If the connection is blocked, it is rejected with no further processing.
3. Authentication is evaluated next (for HTTP services): SSO, password, PIN, or header auth.
4. If both layers pass, the request is forwarded to the backend.

This layered approach lets you, for example, restrict a service to your corporate IP ranges while still requiring SSO for identity verification. Or you can use access restrictions as the sole protection for an L4 service that cannot use browser-based auth.

Configuring authentication

Authentication and access control are configured in separate tabs of the service creation or edit modal. Navigate to Reverse Proxy > Services, then either click Add Service to create a new service or click an existing service to edit it.

• Authentication tab (HTTP services only): SSO, password, PIN, and header authentication
• Access Control tab (all service modes): IP CIDR and country restrictions

Setting up SSO

1. Open the service modal (create or edit).
2. Switch to the Authentication tab.
3. Click SSO (Single Sign-On).
4. Enable SSO using the toggle.
5. Optionally, select one or more distribution groups to restrict access to specific users. If no groups are selected, all authenticated users in your organization can access the service.
6. Click Save (or Save Changes when editing).

Setting up a password

1. Open the service modal (create or edit).
2. Switch to the Authentication tab.
3. Click Password.
4. Enter a password in the input field.
5. Click Save (or Save Changes when editing).

Setting up a PIN code

1. Open the service modal (create or edit).
2. Switch to the Authentication tab.
3. Click PIN Code.
4. Enter a numeric PIN in the input field.
5. Click Save (or Save Changes when editing).

Setting up header authentication

1. Open the service modal (create or edit).
2. Switch to the Authentication tab.
3. Click Header Auth.
4. Select a preset type: Basic Auth, Bearer Token, or Custom Header.
5. Fill in the required fields:
   • For Basic Auth: enter a username and password. The value is automatically encoded as Basic base64(username:password).
   • For Bearer Token: enter the token value. The value is automatically prefixed with Bearer .
   • For Custom Header: enter the header name (e.g., X-API-Key) and the expected value.
6. To add additional headers, click Add Another Header. Any matching header grants access.
7. Click Save (or Save Changes when editing).

Setting up access restrictions

1. Open the service modal (create or edit).
2. Switch to the Access Control tab. This tab is available for all service modes (HTTP and L4).
3. To restrict by IP:
   • Enter CIDRs in the Allowed CIDRs field to create an allowlist (e.g., 10.0.0.0/8, 203.0.113.0/24).
   • Enter CIDRs in the Blocked CIDRs field to create a blocklist.
4. To restrict by country:
   • Select countries in the Allowed Countries field to create a country allowlist.
   • Select countries in the Blocked Countries field to create a country blocklist.
5. Click Save (or Save Changes when editing).

Removing authentication

To remove an authentication method from a service:

1. Open the service modal by clicking the service in the services list.
2. Switch to the Authentication tab.
3. Click on the authentication method you want to remove.
4. Use the Remove option to disable it.
5. Click Save Changes.

If you remove all authentication methods, the service becomes publicly accessible. The dashboard will display a warning before saving, as described in the No authentication section above.

Session management

Authenticated sessions for reverse proxy services are managed using JWT (JSON Web Token) technology. Here is how sessions work:

• Token signing: Sessions use JWT tokens signed with Ed25519 key pairs. Each service has its own unique key pair, ensuring that tokens for one service cannot be used to access another.
• Session duration: Authenticated sessions expire after 24 hours. After expiry, users must re-authenticate using whichever method they originally used.
• Scope: Sessions are scoped to individual services. Authenticating with one service does not grant access to other services, even if they use the same authentication method.

Related pages

• Reverse Proxy Overview - learn how the reverse proxy feature works and create your first service
• Custom Domains - configure your own domain names for reverse proxy services
• Access Logs - monitor and audit traffic to your reverse proxy services
• Single Sign-On - configure your identity provider for SSO across NetBird
• Provision Users and Groups - sync users and groups from your identity provider
• Geolocation Database - configure MaxMind GeoLite2 for country-based access restrictions (self-hosted)