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.
Creating an application on Monosign
Configuring the OIDC/OpenID settings on Monosign
Assign a user to the NetBird application
Configuration Single Sign-On for NetBird
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.
NetBird is not in the application catalog, so click Create from scratch.
Fill in the application details on the Application tab and click Next.
Property | Value | Description |
|---|---|---|
Name |
| Name of the application shown to users on the Monosign portal and on the Monosign sign-in page. |
Type |
| 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 |
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 |
| Displays the application on the user portal. |
On the Access tab define who can reach the application and click Create Application.
Property | Value | Description |
|---|---|---|
User Access Type |
| Defines which users can access this application. Options: Only Assigned Users, All Users, System Default. |
User Group Access Type |
| Defines the application’s user group access. |
Source Using Type |
| Defines which user sources the application can use. |
Profile Access Type |
| 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.
Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically.
Configuration details for the NetBird application are provided as follows:
Monosign value | Example | Used in NetBird as |
|---|---|---|
Client Id |
| Client ID |
Client Secret |
| Client Secret |
Issuer |
| Issuer URL. Enter the address with the slash at the end; it is the address of the Configuration Url without |
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.
Add the callback address of NetBird to Allowed Redirect URIs, enter the scopes in the Scope field, then press Update.
Property | Value | Description |
|---|---|---|
Allowed Redirect URIs |
| 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 |
| 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.
Property | Value | Description |
|---|---|---|
Allowed Redirect Urls for Logout |
| 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.
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.
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.
Field | Value | Description |
|---|---|---|
Provider Type |
| The provider type list also contains ready-made types for some well-known providers; Monosign uses the generic OIDC type. |
Name |
| A friendly name; it is shown on the sign-in button (Continue with Monosign). |
Issuer URL |
| 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.
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.
Click Continue with Monosign once.
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.
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.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.
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.
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 |
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 |
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.
















