Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/h44z/wg-portal

WireGuard Configuration Portal with LDAP connection
https://github.com/h44z/wg-portal

ldap ui usermanagement vpn webinterface wireguard

Last synced: 3 days ago
JSON representation

WireGuard Configuration Portal with LDAP connection

Host: GitHub
URL: https://github.com/h44z/wg-portal
Owner: h44z
License: mit
Created: 2020-11-05T18:33:12.000Z (about 4 years ago)
Default Branch: master
Last Pushed: 2024-11-01T17:06:03.000Z (7 days ago)
Last Synced: 2024-11-01T18:18:31.371Z (7 days ago)
Topics: ldap, ui, usermanagement, vpn, webinterface, wireguard
Language: Go
Homepage: https://wgportal.org/
Size: 7.01 MB
Stars: 952
Watchers: 23
Forks: 127
Open Issues: 48
Metadata Files:
- Readme: README.md
- License: LICENSE.txt

Awesome Lists containing this project

awesome-wireguard - h44z/wg-portal - Supports LDAP and more (Projects / User Interface)

README

# WireGuard Portal (v2 - testing)

[![Build Status](https://travis-ci.com/h44z/wg-portal.svg?token=q4pSqaqT58Jzpxdx62xk&branch=master)](https://travis-ci.com/h44z/wg-portal)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
![GitHub last commit](https://img.shields.io/github/last-commit/h44z/wg-portal)
[![Go Report Card](https://goreportcard.com/badge/github.com/h44z/wg-portal)](https://goreportcard.com/report/github.com/h44z/wg-portal)
![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/h44z/wg-portal)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/h44z/wg-portal)
[![Docker Pulls](https://img.shields.io/docker/pulls/h44z/wg-portal.svg)](https://hub.docker.com/r/wgportal/wg-portal/)

> :warning: **IMPORTANT** Version 2 is currently under development and may contain bugs. It is currently not advised to use this version
in production. Use version [v1](https://github.com/h44z/wg-portal/tree/stable) instead.

Since the project was accepted by the Docker-Sponsored Open Source Program, the Docker image location has moved to: https://hub.docker.com/r/wgportal/wg-portal.
Please update the Docker image from **h44z/wg-portal** to **wgportal/wg-portal**.

A simple, web based configuration portal for [WireGuard](https://wireguard.com).
The portal uses the WireGuard [wgctrl](https://github.com/WireGuard/wgctrl-go) library to manage existing VPN
interfaces. This allows for seamless activation or deactivation of new users, without disturbing existing VPN
connections.

The configuration portal supports using a database (SQLite, MySQL, MsSQL or Postgres), OAuth or LDAP (Active Directory or OpenLDAP) as a user source for authentication and profile data.

## Features
* Self-hosted - the whole application is a single binary
* Responsive web UI written in Vue.JS
* Automatically select IP from the network pool assigned to client
* QR-Code for convenient mobile client configuration
* Sent email to client with QR-code and client config
* Enable / Disable clients seamlessly
* Generation of wg-quick configuration file (`wgX.conf`) if required
* User authentication (database, OAuth or LDAP)
* IPv6 ready
* Docker ready
* Can be used with existing WireGuard setups
* Support for multiple WireGuard interfaces
* Peer Expiry Feature
* Handle route and DNS settings like wg-quick does
* Exposes Prometheus [metrics](#metrics)
* ~~REST API for management and client deployment~~ (coming soon)

![Screenshot](screenshot.png)

## Configuration
You can configure WireGuard Portal using a yaml configuration file.
The filepath of the yaml configuration file defaults to **config/config.yml** in the working directory of the executable.
It is possible to override the configuration filepath using the environment variable **WG_PORTAL_CONFIG**.
For example: `WG_PORTAL_CONFIG=/home/test/config.yml ./wg-portal-amd64`.
Also, environment variable substitution in config file is supported. Refer to [syntax](https://github.com/a8m/envsubst?tab=readme-ov-file#docs)

By default, WireGuard Portal uses a SQLite database. The database is stored in **data/sqlite.db** in the working directory of the executable.

### Configuration Options
The following configuration options are available:

| configuration key
|----------------
| admin_user
| admin_password
| editable_keys
| create_default_peer
| create_default_
| self_provisioning_allowed
| import_existing
| restore_state
| log_level
| log_pretty
| log_json
| start_listen_port
| start_cidr_v4
| start_cidr_v6
| use_ip_v6
| config_storage_path
| expiry_check_interval
| rule_prio_offset
| route_table_offset
| use_ping_checks
| ping_check_workers
| ping_unprivileged
| ping_check_interval
| data_collection_interval
| collect_interface_data
| collect_peer_data
| collect_audit_data
| listening_address
| host
| port
| encryption
| cert_validation
| username
| password
| auth_type
| from
| link_only
| callback_url_prefix
| oidc
| oauth
| ldap
| provider_name
| display_name
| base_url
| client_id
| client_secret
| extra_scopes
| field_map
| registration_enabled
| provider_name
| display_name
| base_url
| client_id
| client_secret
| auth_url
| token_url
| redirect_url
| user_info_url
| scopes
| field_map
| registration_enabled
| url
| start_tls
| cert_validation
| tls_certificate_path
| tls_key_path
| base_dn
| bind_user
| bind_pass
| field_map
| login_filter
| admin_group
| disable_missing
| sync_filter
| sync_interval
| registration_enabled
| debug
| slow_query_threshold
| type
| dsn
| request_logging
| external_url
| listening_address
| session_identifier
| session_secret
| csrf_secret
| site_title
| site_company_name
| cert_file
| key_file | parent key | default_value | description | -----------------|------------|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | core | [email protected] | The administrator user. This user will be created as default admin if it does not yet exist. | | core | wgportal | The administrator password. If unchanged, a random password will be set on first startup. | | core | true | Allow to edit key-pairs in the UI. | | core | false | If an LDAP user logs in for the first time and has no peers associated, a new WireGuard peer will be created for all server interfaces. | peer_on_creation | core | false | If an LDAP user is created (e.g. through LDAP sync), a new WireGuard peer will be created for all server interfaces. | | core | false | Allow registered users to automatically create peers via their profile page. | | core | true | Import existing WireGuard interfaces and peers into WireGuard Portal. | | core | true | Restore the WireGuard interface state after WireGuard Portal has started. | | advanced | warn | The loglevel, can be one of: trace, debug, info, warn, error. | | advanced | false | Uses pretty, colorized log messages. | | advanced | false | Logs in JSON format. | | advanced | 51820 | The first port number that will be used as listening port for new interfaces. | | advanced | 10.11.12.0/24 | The first IPv4 subnet that will be used for new interfaces. | | advanced | fdfd:d3ad:c0de:1234::0/64 | The first IPv6 subnet that will be used for new interfaces. | | advanced | true | Enable IPv6 support. | | advanced | | If a wg-quick style configuration should be stored to the filesystem, specify a storage directory. | | advanced | 15m | The interval after which existing peers will be checked if they expired. | | advanced | 20000 | The default offset for ip route rule priorities. | | advanced | 20000 | The default offset for ip route table id's. | | statistics | true | If enabled, peers will be pinged periodically to check if they are still connected. | | statistics | 10 | Number of parallel ping checks that will be executed. | | statistics | false | If set to false, the ping checks will run without root permissions (BETA). | | statistics | 1m | The interval time between two ping check runs. | | statistics | 1m | The interval between the data collection cycles. | | statistics | true | A flag to enable interface data collection like bytes sent and received. | | statistics | true | A flag to enable peer data collection like bytes sent and received, last handshake and remote endpoint address. | | statistics | true | If enabled, some events, like portal logins, will be logged to the database. | | statistics | :8787 | The listening address of the Prometheus metric server. | | mail | 127.0.0.1 | The mail-server address. | | mail | 25 | The mail-server SMTP port. | | mail | none | SMTP encryption type, allowed values: none, tls, starttls. | | mail | false | Validate the mail server certificate (if encryption tls is used). | | mail | | The SMTP user name. | | mail | | The SMTP password. | | mail | plain | SMTP authentication type, allowed values: plain, login, crammd5. | | mail | Wireguard Portal | The address that is used to send mails. | | mail | false | Only send links to WireGuard Portal instead of the full configuration. | | auth | /api/v0 | OAuth callback URL prefix. The full callback URL will look like: https://wg.portal.local/callback_url_prefix/provider_name/callback | | auth | Empty Array - no providers configured | A list of OpenID Connect providers. See auth/oidc properties to setup a new provider. | | auth | Empty Array - no providers configured | A list of plain OAuth providers. See auth/oauth properties to setup a new provider. | | auth | Empty Array - no providers configured | A list of LDAP providers. See auth/ldap properties to setup a new provider. | | auth/oidc | | A unique provider name. This name must be unique throughout all authentication providers (even other types). | | auth/oidc | | The display name is shown at the login page (the login button). | | auth/oidc | | The base_url is the URL identifier for the service. For example: "https://accounts.google.com". | | auth/oidc | | The OAuth client id. | | auth/oidc | | The OAuth client secret. | | auth/oidc | | Extra scopes that should be used in the OpenID Connect authentication flow. | | auth/oidc | | Mapping of user fields. Internal fields: user_identifier, email, firstname, lastname, phone, department and is_admin. | | auth/oidc | | If registration is enabled, new user accounts will created in WireGuard Portal. | | auth/oauth | | A unique provider name. This name must be unique throughout all authentication providers (even other types). | | auth/oauth | | The display name is shown at the login page (the login button). | | auth/oauth | | The base_url is the URL identifier for the service. For example: "https://accounts.google.com". | | auth/oauth | | The OAuth client id. | | auth/oauth | | The OAuth client secret. | | auth/oauth | | The URL for the authentication endpoint. | | auth/oauth | | The URL for the token endpoint. | | auth/oauth | | The redirect URL. | | auth/oauth | | The URL for the user information endpoint. | | auth/oauth | | OAuth scopes. | | auth/oauth | | Mapping of user fields. Internal fields: user_identifier, email, firstname, lastname, phone, department and is_admin. | | auth/oauth | | If registration is enabled, new user accounts will created in WireGuard Portal. | | auth/ldap | | The LDAP server url. For example: ldap://srv-ad01.company.local:389 | | auth/ldap | | Use STARTTLS to encrypt LDAP requests. | | auth/ldap | | Validate the LDAP server certificate. | | auth/ldap | | A path to the TLS certificate. | | auth/ldap | | A path to the TLS key. | | auth/ldap | | The base DN for searching users. For example: DC=COMPANY,DC=LOCAL | | auth/ldap | | The bind user. For example: company\\ldap_wireguard | | auth/ldap | | The bind password. | | auth/ldap | | Mapping of user fields. Internal fields: user_identifier, email, firstname, lastname, phone, department and memberof. | | auth/ldap | | LDAP filters for users that should be allowed to log in. {{login_identifier}} will be replaced with the login username. | | auth/ldap | | Users in this group are marked as administrators. | | auth/ldap | | If synchronization is enabled, missing LDAP users will be disabled in WireGuard Portal. | | auth/ldap | | LDAP filters for users that should be synchronized to WireGuard Portal. | | auth/ldap | | The time interval after which users will be synchronized from LDAP. Empty value or `0` disables synchronization. | | auth/ldap | | If registration is enabled, new user accounts will created in WireGuard Portal. | | database | false | Debug database statements (log each statement). | | database | | A threshold for slow database queries. If the threshold is exceeded, a warning message will be logged. | | database | sqlite | The database type. Allowed values: sqlite, mssql, mysql or postgres. | | database | data/sqlite.db | The database DSN. For example: user:pass@tcp(1.2.3.4:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local | | web | false | Log all HTTP requests. | | web | http://localhost:8888 | The URL where a client can access WireGuard Portal. | | web | :8888 | The listening port of the web server. | | web | wgPortalSession | The session identifier for the web frontend. | | web | very_secret | The session secret for the web frontend. | | web | extremely_secret | The CSRF secret. | | web | WireGuard Portal | The title that is shown in the web frontend. | | web | WireGuard Portal | The company name that is shown at the bottom of the web frontend. | | web | | (Optional) Path to the TLS certificate file | | web | | (Optional) Path to the TLS certificate key file |

## Upgrading from V1

> :warning: Before upgrading from V1, make sure that you have a backup of your currently working configuration files and database!

To start the upgrade process, start the wg-portal binary with the **-migrateFrom** parameter.
The configuration (config.yml) for WireGuard Portal must be updated and valid before starting the upgrade.

To upgrade from a previous SQLite database, start wg-portal like:

```shell
./wg-portal-amd64 -migrateFrom=old_wg_portal.db
```

You can also specify the database type using the parameter **-migrateFromType**, supported types: mysql, mssql, postgres or sqlite.
For example:

```shell
./wg-portal-amd64 -migrateFromType=mysql -migrateFrom=user:pass@tcp(1.2.3.4:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local
```

The upgrade will transform the old, existing database and store the values in the new database specified in config.yml.
Ensure that the new database does not contain any data!

## V2 TODOs
* Public REST API
* Translations
* Documentation
* Audit UI

## Building

To build a standalone application, use the Makefile provided in the repository.
Go version 1.22 or higher has to be installed to build WireGuard Portal.
If you want to re-compile the frontend, NodeJS 18 and NPM >= 9 is required.

```shell
# build the frontend
make frontend

# build the binary
make build
```

## What is out of scope
* Automatic generation or application of any `iptables` or `nftables` rules.
* Support for operating systems other than linux.
* Automatic import of private keys of an existing WireGuard setup.

## Application stack

* [wgctrl-go](https://github.com/WireGuard/wgctrl-go) and [netlink](https://github.com/vishvananda/netlink) for interface handling
* [Gin](https://github.com/gin-gonic/gin), HTTP web framework written in Go
* [Bootstrap](https://getbootstrap.com/), for the HTML templates
* [Vue.JS](https://vuejs.org/), for the frontend

## Metrics

Metrics are available if interface/peer statistic data collection is enabled.

Add following scrape job to your Prometheus config file:

```yaml
# prometheus.yaml
scrape_configs:
- job_name: "wg-portal"
scrape_interval: 60s
static_configs:
- targets: ["wg-portal:8787"]
```

Exposed metrics:

```console
# HELP wireguard_interface_info Interface info.
# TYPE wireguard_interface_info gauge

# HELP wireguard_interface_received_bytes_total Bytes received througth the interface.
# TYPE wireguard_interface_received_bytes_total gauge

# HELP wireguard_interface_sent_bytes_total Bytes sent through the interface.
# TYPE wireguard_interface_sent_bytes_total gauge

# HELP wireguard_peer_info Peer info.
# TYPE wireguard_peer_info gauge

# HELP wireguard_peer_received_bytes_total Bytes received from the peer.
# TYPE wireguard_peer_received_bytes_total gauge

# HELP wireguard_peer_sent_bytes_total Bytes sent to the peer.
# TYPE wireguard_peer_sent_bytes_total gauge

# HELP wireguard_peer_up Peer connection state (boolean: 1/0).
# TYPE wireguard_peer_up gauge

# HELP wireguard_peer_last_handshake_seconds Seconds from the last handshake with the peer.
# TYPE wireguard_peer_last_handshake_seconds gauge
```

## License

* MIT License. [MIT](LICENSE.txt) or https://opensource.org/licenses/MIT