Help

Integration

NetBird OIDC Integration

Updated 16 Nov 2026 7 min read

This document explains how to implement Monosign with NetBird, the open source WireGuard based network (VPN) platform. It covers Single Sign-On with OpenID Connect (OIDC) for the NetBird dashboard. In the self-hosted NetBird server the sign-in is handled by the built-in identity provider; an external provider such as Monosign is added to it as an Identity Provider of the type OIDC (Generic). NetBird uses the Authorization Code flow, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the NetBird documentation (opens in a new tab).

This configuration was tested with NetBird management 0.83.1 and dashboard 2.97.0 (self-hosted combined server with the built-in identity provider, Docker). If your version is different, please check the NetBird documentation.

The identity provider is added in the NetBird dashboard under Settings → Identity Providers. SAML is not covered in this document.

Monofor has no responsibility to do NetBird configurations. If you need support please contact the NetBird community or your NetBird support provider.

Instructions

This documentation contains 5 main steps for integration.

  1. Creating an application on Monosign

  2. Configuring the OIDC/OpenID settings on Monosign

  3. Assign a user to the NetBird application

  4. Configuration Single Sign-On for NetBird

  5. Sign In Test

1- Creating an Application on Monosign

Create your application on Monosign first. Open the Applications page from the left menu and click Add New.

image-20261030-191725.png

NetBird is not in the application catalog, so click Create from scratch.

image-20261030-191750.png

Fill in the application details on the Application tab and click Next.

netbird-01-application.jpg

Property

Value

Description

Name

NetBird

Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.

Type

Web

The NetBird dashboard is accessed through a web browser. Options: Web, Mobile, Desktop, API.

Url

Optional

Leave empty or enter the address of NetBird (for example https://<netbird-address>).

Logo

Optional

Browse and upload a logo (PNG or JPG, max 1 MB); it is also shown on the Monosign sign-in page.

Users can see this application on their list

Enabled

Displays the application on the user portal.

On the Access tab define who can reach the application and click Create Application.

image-20261030-192040.png

Property

Value

Description

User Access Type

System Default

Defines which users can access this application. Options: Only Assigned Users, All Users, System Default.

User Group Access Type

System Default

Defines the application’s user group access.

Source Using Type

System Default

Defines which user sources the application can use.

Profile Access Type

System Default

Defines which user profile attributes are available to the application (Options: Restricted, All). NetBird needs the e-mail address and the name of the user.

After the application is created, click Keys and add a new Access Key for OIDC/OpenID access.

image-20261030-192203.png

Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically.

netbird-02-key-type.jpg

Configuration details for the NetBird application are provided as follows:

netbird-04-key-details.jpg

Monosign value

Example

Used in NetBird as

Client Id

<client-id>

Client ID

Client Secret

<client-secret>

Client Secret

Issuer

https://<monosign-host>/

Issuer URL. Enter the address with the slash at the end; it is the address of the Configuration Url without .well-known/openid-configuration.

2- Configuring the OIDC/OpenID Settings on Monosign

Open the Keys tab of the application and click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings.

image-20261031-211438.png

Add the callback address of NetBird to Allowed Redirect URIs, enter the scopes in the Scope field, then press Update.

netbird-03-oidc-settings.jpg

Property

Value

Description

Allowed Redirect URIs

https://<netbird-address>/oauth2/callback

The address where Monosign sends the user back after sign-in. NetBird shows the same value as Redirect / Callback in the Add Identity Provider window (step 4).

Scope

openid profile email

Enter the three scopes one by one.

Other fields

Empty / default

The other fields (Issuer, Audience, Resource, token lifetimes, CORS) are not needed.

To make the sign-out work, also add the logout address of NetBird to the application. Open the application settings (Edit), go to the Login tab, enter the address in Allowed Redirect Urls for Logout and click Save.

netbird-05-logout-redirect.png

Property

Value

Description

Allowed Redirect Urls for Logout

https://<netbird-address>/oauth2/logout/callback

NetBird shows the same value as Logout in the Add Identity Provider window (step 4).

3- Assign a User to the NetBird Application

Open the application in Monosign, click the Assignments tab and click Assign a User.

image-20261030-193315.png

Search and select the users who can sign in to NetBird, check the Expiration Date and save. You can select more than one user. Every user needs an e-mail address in Monosign.

image-20261030-193652.png

4- Configuration Single Sign-On for NetBird

As we mentioned at the start, please check out the NetBird documentation first. Log in to the NetBird dashboard with an owner (administrator) account, open Settings → Identity Providers and click Add Identity Provider.

netbird-06-add-identity-provider.jpg

Field

Value

Description

Provider Type

OIDC (Generic)

The provider type list also contains ready-made types for some well-known providers; Monosign uses the generic OIDC type.

Name

Monosign

A friendly name; it is shown on the sign-in button (Continue with Monosign).

Issuer URL

https://<monosign-host>/

Address of Monosign with the slash at the end.

Client ID

Client Id

Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.

Client Secret

Client Secret

Copied from the same page.

Click Add Provider. The provider appears in the list.

netbird-07-identity-providers.jpg

The window also shows the Redirect / Callback and Logout addresses (https://<netbird-address>/oauth2/callback and https://<netbird-address>/oauth2/logout/callback) that have to be registered in Monosign (step 2). When NetBird is behind a reverse proxy, the public HTTPS address must be the address of NetBird in the server configuration, otherwise these addresses are wrong.

5- Sign In Test

Now try to log in to NetBird using Monosign SSO. Open a new browser window (or a private window) and type the address of the NetBird dashboard. The sign-in page shows the Continue with Monosign button next to Continue with Email.

netbird-08-login-page.jpg
  1. Click Continue with Monosign once.

  2. On the Monosign sign-in page log in passwordless with your QR code (Monofor Identity), with a Passkey or with your user name and password (Sign in with Password). If you are already signed in to Monosign, the page is skipped.

  3. After the sign-in Monosign redirects the browser back to NetBird (/oauth2/callback). At the first sign-in NetBird creates the user. If the account requires new users to be approved, NetBird shows Waiting for Approval until an owner of the NetBird account approves the user in the dashboard.

  4. The user is signed in to the NetBird dashboard. A user without administrator rights sees the page Add new device to your network, which explains how to connect a device (screenshot below).

Dashboard after the sign-in: the page shows the installation steps for the selected operating system (here macOS) and the Management server URL of the self-hosted NetBird server (https://<netbird-address>) that has to be entered in the client.

image-20261116-213356.png

Connecting a device: download and install the NetBird client from the page. On the first launch select Self-hosted and enter the Management server URL shown on the dashboard page. If the first screen was skipped, click the NetBird icon in the menu bar, open Settings → General and set Management Server to Self-hosted. Then click Connect in the menu of the NetBird icon and sign in when the client asks. The client window shows Disconnected until the device is connected.

image-20261116-213104.png

The users that sign in through Monosign are separate NetBird users; they are not merged with users that already sign in with an e-mail address and a password. Approval of new users is a setting of the NetBird account; if new Monosign users should join without approval, change this setting in the account settings of the NetBird dashboard (see the NetBird documentation).

Troubleshooting

Symptom

Cause

Solution

The Continue with Monosign button is not shown

The identity provider was not saved or the page is cached.

Check Settings → Identity Providers (step 4) and reload the sign-in page.

Monosign shows a redirect URI error

The callback address does not exactly match the Allowed Redirect URIs, for example because NetBird is configured with another public address.

Use https://<netbird-address>/oauth2/callback exactly as NetBird shows it (step 2).

An error appears after returning from Monosign

The Client Id or Client Secret is wrong, the Issuer URL has no slash at the end, or NetBird cannot reach Monosign.

Copy the values again from the Monosign access key (step 1) and check that Monosign opens from the NetBird server.

NetBird shows Waiting for Approval

The account requires new users to be approved by an owner.

Approve the user in the NetBird dashboard or change the approval setting (step 5).

Signing out of NetBird fails or returns an error

The logout address is not registered in Monosign.

Add https://<netbird-address>/oauth2/logout/callback to Allowed Redirect Urls for Logout (step 2).

A user cannot sign in

The user is not assigned to the application.

Assign the user in step 3.

After completing the configuration on NetBird and Monosign, it is better to test in a new private browser window if the OIDC SSO doesn’t work, because old session cookies may cause errors.

Permanent link