[PR #5416] [client] Add client-side support for mTLS. #27917

Open
opened 2026-08-05 07:09:24 -04:00 by saavagebueno · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/netbirdio/netbird/pull/5416
Author: @reimarstier
Created: 2/23/2026
Status: 🔄 Open

Base: mainHead: 424-mtls-for-netbird-client


📝 Commits (2)

  • 258418a [client] Add client-side support for mTLS.
  • 543b4b5 [client] Migrate mTLS configuration to own struct

📊 Changes

25 files changed (+239 additions, -116 deletions)

View changed files

📝 client/grpc/dialer.go (+13 -3)
📝 client/internal/auth/auth.go (+3 -3)
📝 client/internal/connect.go (+6 -5)
📝 client/internal/debug/debug.go (+10 -4)
📝 client/internal/engine_test.go (+8 -8)
📝 client/internal/profilemanager/config.go (+28 -26)
client/internal/profilemanager/config_mtls.go (+67 -0)
📝 client/internal/profilemanager/config_test.go (+2 -1)
📝 client/server/server.go (+1 -1)
📝 relay/test/benchmark_test.go (+2 -2)
📝 relay/testec2/relay.go (+2 -2)
📝 shared/management/client/client_test.go (+8 -8)
📝 shared/management/client/grpc.go (+3 -2)
📝 shared/relay/client/client.go (+5 -2)
📝 shared/relay/client/client_test.go (+19 -19)
📝 shared/relay/client/dialer/ws/dialopts_generic.go (+7 -3)
📝 shared/relay/client/dialer/ws/dialopts_js.go (+8 -3)
📝 shared/relay/client/dialer/ws/ws.go (+15 -5)
📝 shared/relay/client/dialers_generic.go (+6 -2)
📝 shared/relay/client/dialers_js.go (+2 -0)

...and 5 more files

📄 Description

This PR adds client support for sending a certificate to management/signal/relay backend for mutual authentication (mTLS).

Background

We've been using NetBird in eclipse-opendut for over two years now and are grateful for the VPN management that it provides. For internet facing services, we are required to use client certificates (mutual TLS aka mTLS). At the moment we use NetBird behind traefik and are able to configure client certificate verification here.

Changes

I would like to add support for client certificates in the NetBird client.

This pull request adds two fields to the configuration input:

// client/internal/profilemanager/config.go
type ConfigInput struct {

	// IDPClientCert holds the mTLS cert/key paths for OAuth PKCE Authorization Flow with the identity provider (SSO)
	IDPClientCert MTLSConfig
	// MgmtClientCert holds the mTLS cert/key paths for connecting to management/signal/relay backend
	MgmtClientCert MTLSConfig

}

// client/internal/profilemanager/config_mtls.go
type MTLSConfig struct {
	CertPath string           `json:",omitempty"`
	KeyPath  string           `json:",omitempty"`
	KeyPair  *tls.Certificate `json:"-"`
}

If you configure a certificate path and key path, then the NetBird client will send the client certificate when making requests to the backend (management service, relay service, signal service).
There are already configuration fields present to configure client certificates for the identity provider, contributed in #2188. To avoid breaking existing configuration, I've opted for a descriptive longer name in the configuration.
Let me know if this is to your liking.

type Config struct {

	// IDPClientCert holds the mTLS cert/key paths for OAuth PKCE Authorization Flow with the identity provider (SSO)
	IDPClientCert MTLSConfig

	// MgmtClientCert holds the mTLS cert/key paths for connecting to management/signal/relay backend
	MgmtClientCert MTLSConfig

	// Deprecated: use IDPClientCert.CertPath instead. Kept for reading legacy config files.
	ClientCertPath string `json:",omitempty"`
	// Deprecated: use IDPClientCert.KeyPath instead. Kept for reading legacy config files.
	ClientCertKeyPath string `json:",omitempty"`
}

I have already run tests for v0.67.1:

  • Custom releases
  • CI Tests.
    Apart from that I've tested integration within our backend. I haven't tested on other operating systems than linux x86_64.

There are others who have requested more general support for client certificates and a PKI: mTLS Auth for Proxy Services.
Adding client-side support is a first step in that direction.

Checklist

  • Is a feature enhancement

By submitting this pull request, you confirm that you have read and agree to the terms of the Contributor License Agreement.

Legal notice:
Reimar Stier, reimar.stier@mercedes-benz.com, Mercedes-Benz Tech Innovation GmbH, provider information

Summary by CodeRabbit

  • New Features

    • Optional mutual TLS (mTLS) client certificate support for management, signal, and relay connections; native clients can present a client certificate when configured.
    • Configuration accepts management client certificate/key paths and will load/cache a client certificate when both paths are provided; WASM/browser builds ignore client certs.
  • Tests

    • Tests and test helpers updated to accept the new optional certificate parameter.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/netbirdio/netbird/pull/5416 **Author:** [@reimarstier](https://github.com/reimarstier) **Created:** 2/23/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `424-mtls-for-netbird-client` --- ### 📝 Commits (2) - [`258418a`](https://github.com/netbirdio/netbird/commit/258418a72062099952fbe3aac8ab88376808d741) [client] Add client-side support for mTLS. - [`543b4b5`](https://github.com/netbirdio/netbird/commit/543b4b5004d52fdf3cfdda205fedf87bfd3206e6) [client] Migrate mTLS configuration to own struct ### 📊 Changes **25 files changed** (+239 additions, -116 deletions) <details> <summary>View changed files</summary> 📝 `client/grpc/dialer.go` (+13 -3) 📝 `client/internal/auth/auth.go` (+3 -3) 📝 `client/internal/connect.go` (+6 -5) 📝 `client/internal/debug/debug.go` (+10 -4) 📝 `client/internal/engine_test.go` (+8 -8) 📝 `client/internal/profilemanager/config.go` (+28 -26) ➕ `client/internal/profilemanager/config_mtls.go` (+67 -0) 📝 `client/internal/profilemanager/config_test.go` (+2 -1) 📝 `client/server/server.go` (+1 -1) 📝 `relay/test/benchmark_test.go` (+2 -2) 📝 `relay/testec2/relay.go` (+2 -2) 📝 `shared/management/client/client_test.go` (+8 -8) 📝 `shared/management/client/grpc.go` (+3 -2) 📝 `shared/relay/client/client.go` (+5 -2) 📝 `shared/relay/client/client_test.go` (+19 -19) 📝 `shared/relay/client/dialer/ws/dialopts_generic.go` (+7 -3) 📝 `shared/relay/client/dialer/ws/dialopts_js.go` (+8 -3) 📝 `shared/relay/client/dialer/ws/ws.go` (+15 -5) 📝 `shared/relay/client/dialers_generic.go` (+6 -2) 📝 `shared/relay/client/dialers_js.go` (+2 -0) _...and 5 more files_ </details> ### 📄 Description This PR adds client support for sending a certificate to management/signal/relay backend for mutual authentication (mTLS). ## Background We've been using NetBird in [eclipse-opendut](https://github.com/eclipse-opendut/opendut/) for over two years now and are grateful for the VPN management that it provides. For internet facing services, we are required to use client certificates (mutual TLS aka mTLS). At the moment we use NetBird behind [traefik](https://doc.traefik.io/traefik/reference/routing-configuration/http/tls/tls-options/#client-authentication-mtls) and are able to configure client certificate verification [here](https://github.com/eclipse-opendut/opendut/blob/a7c2670b34dfb0213e889439d5c391d5f43f5013/.ci/deploy/localenv/data/traefik/config/mtls/mtls.yml#L4). ## Changes I would like to add support for client certificates in the NetBird client. This pull request adds two fields to the configuration input: ```go // client/internal/profilemanager/config.go type ConfigInput struct { // IDPClientCert holds the mTLS cert/key paths for OAuth PKCE Authorization Flow with the identity provider (SSO) IDPClientCert MTLSConfig // MgmtClientCert holds the mTLS cert/key paths for connecting to management/signal/relay backend MgmtClientCert MTLSConfig } // client/internal/profilemanager/config_mtls.go type MTLSConfig struct { CertPath string `json:",omitempty"` KeyPath string `json:",omitempty"` KeyPair *tls.Certificate `json:"-"` } ``` If you configure a certificate path and key path, then the NetBird client will send the client certificate when making requests to the backend (management service, relay service, signal service). There are already configuration fields present to configure client certificates for the identity provider, contributed in #2188. To avoid breaking existing configuration, I've opted for a descriptive longer name in the configuration. Let me know if this is to your liking. ```go type Config struct { // IDPClientCert holds the mTLS cert/key paths for OAuth PKCE Authorization Flow with the identity provider (SSO) IDPClientCert MTLSConfig // MgmtClientCert holds the mTLS cert/key paths for connecting to management/signal/relay backend MgmtClientCert MTLSConfig // Deprecated: use IDPClientCert.CertPath instead. Kept for reading legacy config files. ClientCertPath string `json:",omitempty"` // Deprecated: use IDPClientCert.KeyPath instead. Kept for reading legacy config files. ClientCertKeyPath string `json:",omitempty"` } ``` I have already run tests for [v0.67.1](https://github.com/eclipse-opendut/netbird-build/releases/tag/v0.67.1-e6333229d8f37878c248906b9f11fd6ba3c29e11): - [Custom releases](https://github.com/eclipse-opendut/netbird-build/releases/) - [CI Tests](https://github.com/eclipse-opendut/netbird-build/actions/runs/23643505075). Apart from that I've tested integration within our backend. I haven't tested on other operating systems than linux x86_64. There are others who have requested more general support for client certificates and a PKI: [mTLS Auth for Proxy Services](https://github.com/netbirdio/netbird/issues/5364). Adding client-side support is a first step in that direction. ### Checklist - [x] Is a feature enhancement > By submitting this pull request, you confirm that you have read and agree to the terms of the [Contributor License Agreement](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT.md). Legal notice: Reimar Stier, reimar.stier@mercedes-benz.com, Mercedes-Benz Tech Innovation GmbH, [provider information](https://github.com/mercedes-benz/foss/blob/main/PROVIDER_INFORMATION.md) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Optional mutual TLS (mTLS) client certificate support for management, signal, and relay connections; native clients can present a client certificate when configured. * Configuration accepts management client certificate/key paths and will load/cache a client certificate when both paths are provided; WASM/browser builds ignore client certs. * **Tests** * Tests and test helpers updated to accept the new optional certificate parameter. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
saavagebueno added the pull-request label 2026-08-05 07:09:24 -04:00
Sign in to join this conversation.
No Label pull-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#27917