diff --git a/public/docs-static/img/manage/reverse-proxy/reverse-proxy-auth-modal.png b/public/docs-static/img/manage/reverse-proxy/reverse-proxy-auth-modal.png index ff548d52..722be2dd 100644 Binary files a/public/docs-static/img/manage/reverse-proxy/reverse-proxy-auth-modal.png and b/public/docs-static/img/manage/reverse-proxy/reverse-proxy-auth-modal.png differ diff --git a/src/pages/manage/reverse-proxy/authentication.mdx b/src/pages/manage/reverse-proxy/authentication.mdx index 511411c6..4b402df1 100644 --- a/src/pages/manage/reverse-proxy/authentication.mdx +++ b/src/pages/manage/reverse-proxy/authentication.mdx @@ -1,7 +1,7 @@ import {Note, Warning} from "@/components/mdx" export const description = - 'Configure SSO, password, PIN, and header authentication methods, plus IP and country access restrictions, for NetBird Reverse Proxy services.' + 'Configure SSO, password, PIN, mTLS, and header authentication methods, plus IP and country access restrictions, for NetBird Reverse Proxy services.' # Reverse Proxy Authentication and Access Restrictions @@ -13,10 +13,10 @@ NetBird Reverse Proxy supports multiple authentication methods and connection-le ## Authentication methods -NetBird offers four authentication methods, each suited to different access patterns. You can enable any combination of them on a single service. +NetBird offers five authentication methods, each suited to different access patterns. You can enable any combination of them on a single service. - SSO, password, PIN, and header authentication all require HTTP (Layer 7) and are only available for HTTP services. For L4 services (TCP, UDP, TLS), use [access restrictions](#access-restrictions) to control access. + SSO, password, PIN, mTLS, and header authentication all require HTTP (Layer 7) and are only available for HTTP services. For L4 services (TCP, UDP, TLS), use [access restrictions](#access-restrictions) to control access. ### SSO (Single Sign-On) @@ -76,6 +76,24 @@ PIN code authentication works similarly to password authentication but is limite **Best for:** Quick access scenarios, kiosk-style interfaces, or situations where a simple numeric code is easier to share than a full password. +### mTLS (client certificate authentication) + +mTLS authentication requires the client to present a certificate during the TLS handshake. NetBird validates that client certificate against a CA certificate bundle you configure on the service. Requests without a valid client certificate are rejected before they reach your backend. + +**Key details:** + +- Upload or paste a PEM-encoded CA certificate bundle when configuring the service. +- The service accepts client certificates that chain back to that CA bundle. +- If the client does not present a certificate, or presents one signed by a different CA, the proxy returns **401 Unauthorized**. +- mTLS can be combined with other HTTP authentication methods such as SSO or header authentication for layered protection. +- The configured CA certificate is treated as sensitive configuration and is hidden when editing an existing service unless you replace it. + + + The uploaded value must be PEM certificate data (`-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----`). Paste the CA certificate or CA chain that issued your client certificates, not the client certificate's private key. + + +**Best for:** Machine-to-machine integrations, admin endpoints, internal tools used with managed devices, and any environment where you want strong client identity based on certificates instead of shared secrets. + ### 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. @@ -125,6 +143,8 @@ Common combinations include: |-------------|----------| | **SSO + Password** | Team members use SSO; external collaborators use a shared password | | **SSO + Header Auth** | Team members authenticate in a browser; automated systems use an API key | +| **mTLS + SSO** | Managed devices must present a client cert; users still identify themselves with SSO | +| **mTLS + Header Auth** | Automated systems need both a trusted client cert and an API key/header | | **SSO + PIN Code** | Team members use SSO; quick access via PIN for specific scenarios | | **Password + PIN Code** | Different shared credentials for different groups of users | | **Any auth + Access Restrictions** | IP/country restrictions as a first layer, then authentication for identity | @@ -205,7 +225,7 @@ This layered approach lets you, for example, restrict a service to your corporat 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 +- **Authentication** tab (HTTP services only): SSO, password, PIN, mTLS, and header authentication - **Access Control** tab (all service modes): IP CIDR and country restrictions

@@ -258,6 +278,20 @@ Authentication and access control are configured in separate tabs of the service 6. To add additional headers, click **Add Another Header**. Any matching header grants access. 7. Click **Save** (or **Save Changes** when editing). +### Setting up mTLS authentication + +1. Open the service modal (create or edit). +2. Switch to the **Authentication** tab. +3. Click **mTLS**. +4. Paste the PEM-encoded CA certificate, or upload a `.pem`, `.crt`, or `.cer` file containing it. +5. Click **Save** (or **Save Changes** when editing). + +When editing an existing service, you can leave the stored CA certificate unchanged, replace it with a new CA certificate, or remove mTLS entirely using the **Remove** action in the modal. + + + NetBird validates the CA certificate format in the dashboard before saving. The PEM must contain at least one certificate block and no unrelated text. + + ### Setting up access restrictions 1. Open the service modal (create or edit). @@ -318,6 +352,10 @@ Authenticated sessions for reverse proxy services are managed using JWT (JSON We - **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. + + mTLS itself is checked on every TLS connection and does not rely on the browser session cookie. If you combine mTLS with session-based methods such as SSO, password, PIN, or header authentication, the client certificate must still be valid for the connection to succeed. + + ## Related pages - [Reverse Proxy Overview](/manage/reverse-proxy) - learn how the reverse proxy feature works and create your first service diff --git a/src/pages/manage/reverse-proxy/index.mdx b/src/pages/manage/reverse-proxy/index.mdx index b411ad5b..bb3d0de2 100644 --- a/src/pages/manage/reverse-proxy/index.mdx +++ b/src/pages/manage/reverse-proxy/index.mdx @@ -27,7 +27,7 @@ When you create a reverse proxy service, NetBird provisions a public domain with NetBird supports two categories of service: -- **HTTP services** operate at Layer 7. The proxy terminates TLS at the edge and forwards HTTP requests to your backend. This mode supports path-based routing, host header forwarding, redirect rewriting, and browser-based authentication (SSO, password, PIN). +- **HTTP services** operate at Layer 7. The proxy terminates TLS at the edge and forwards HTTP requests to your backend. This mode supports path-based routing, host header forwarding, redirect rewriting, and authentication methods such as SSO, password, PIN, mTLS, and header authentication. - **L4 services** (TCP, UDP, TLS) operate at Layer 4. The proxy forwards raw connections or datagrams directly to your backend without inspecting application-layer content. TLS mode performs SNI-based routing, passing the encrypted connection through to the backend without terminating it. You can optionally require authentication before users can reach the service, and restrict access by IP address or country. See [Authentication](/manage/reverse-proxy/authentication) for all available options. @@ -41,7 +41,7 @@ A service is the core configuration unit of the Reverse Proxy. Each service maps - **Service mode** - HTTP (Layer 7) or TCP/UDP/TLS (Layer 4) - **Domain** - the public URL where the service is reachable - **Targets** - one or more backend destinations that handle incoming requests -- **Authentication** - optional SSO, password, PIN, or header-based protection +- **Authentication** - optional SSO, password, PIN, mTLS, or header-based protection - **Access restrictions** - optional IP CIDR, country, and CrowdSec IP reputation access control - **Settings** - advanced options (varies by service mode) - **Enabled/Disabled toggle** - turn the service on or off without deleting it @@ -52,7 +52,7 @@ The service mode determines how the proxy handles traffic between clients and yo | Mode | Layer | Description | |------|-------|-------------| -| **HTTP** | L7 | TLS termination at the proxy, HTTP-level forwarding. Supports path-based routing, host header forwarding, redirect rewriting, and browser-based authentication (SSO, password, PIN). | +| **HTTP** | L7 | TLS termination at the proxy, HTTP-level forwarding. Supports path-based routing, host header forwarding, redirect rewriting, and HTTP authentication methods including SSO, password, PIN, mTLS, and header authentication. | | **TCP** | L4 | Raw TCP relay. The proxy accepts TCP connections on a dedicated port and forwards them to your backend. | | **UDP** | L4 | UDP relay with session tracking. The proxy accepts UDP packets on a dedicated port and forwards them to your backend. Sessions are reaped after an idle timeout. | | **TLS** | L4 | TLS passthrough with SNI-based routing. The proxy inspects the TLS ClientHello to read the SNI hostname and forwards the encrypted connection to your backend without terminating TLS. | @@ -128,6 +128,7 @@ You can protect a service with one or more authentication methods. When multiple | **SSO (Single Sign-On)** | Yes | No | Authenticate via your identity provider using OIDC. Optionally restrict access to specific user groups. | | **Password** | Yes | No | Protect with a shared password. | | **PIN Code** | Yes | No | Protect with a numeric PIN code. | +| **mTLS** | Yes | No | Require a client certificate signed by a configured CA certificate bundle. | | **Header Authentication** | Yes | No | Validate a static header value (API key, Bearer token, Basic auth). Useful for programmatic access. | | **Access Restrictions** | Yes | Yes | Restrict access by IP CIDR range, country, or CrowdSec IP reputation. Works at the connection level, so it applies to all service modes. |