diff --git a/README.md b/README.md index c5a2968..018b748 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ The configuration portal supports using a database (SQLite, MySQL, MsSQL, or Pos * Sends email to the 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) +* User authentication (database, OAuth, or LDAP), Passkey support * IPv6 ready * Docker ready * Can be used with existing WireGuard setups diff --git a/docs/assets/images/interface_view.png b/docs/assets/images/interface_view.png new file mode 100644 index 0000000..09f5b1b Binary files /dev/null and b/docs/assets/images/interface_view.png differ diff --git a/docs/assets/images/landing_page.png b/docs/assets/images/landing_page.png new file mode 100644 index 0000000..4bb72bb Binary files /dev/null and b/docs/assets/images/landing_page.png differ diff --git a/docs/assets/images/passkey_setup.png b/docs/assets/images/passkey_setup.png new file mode 100644 index 0000000..af39e89 Binary files /dev/null and b/docs/assets/images/passkey_setup.png differ diff --git a/docs/documentation/configuration/overview.md b/docs/documentation/configuration/overview.md index 158d060..70496aa 100644 --- a/docs/documentation/configuration/overview.md +++ b/docs/documentation/configuration/overview.md @@ -552,6 +552,8 @@ Below are the properties for each LDAP provider entry inside `auth.ldap`: ```text (&(objectClass=organizationalPerson)(mail={{login_identifier}})(!userAccountControl:1.2.840.113556.1.4.803:=2)) ``` +- **Important**: The `login_filter` must always be a valid LDAP filter. It should at most return one user. + If the filter returns multiple or no users, the login will fail. #### `admin_group` - **Default:** *(empty)* diff --git a/docs/documentation/usage/general.md b/docs/documentation/usage/general.md new file mode 100644 index 0000000..6ebf5be --- /dev/null +++ b/docs/documentation/usage/general.md @@ -0,0 +1,57 @@ +This documentation section describes the general usage of WireGuard Portal. +If you are looking for specific setup instructions, please refer to the *Getting Started* and [*Configuration*](../configuration/overview.md) sections, +for example, using a [Docker](../getting-started/docker.md) deployment. + +## Basic Concepts + +WireGuard Portal is a web-based configuration portal for WireGuard server management. It allows managing multiple WireGuard interfaces and users from a single web UI. +WireGuard Interfaces can be categorized into three types: + + - **Server**: A WireGuard server interface that to which multiple peers can connect. In this mode, it is possible to specify default settings for all peers, such as the IP address range, DNS servers, and MTU size. + - **Client**: A WireGuard client interface that can be used to connect to a WireGuard server. Usually, such an interface has exactly one peer. + - **Unknown**: This is the default type for imported interfaces. It is encouraged to change the type to either `Server` or `Client` after importing the interface. + +## Accessing the Web UI + +The web UI should be accessed via the URL specified in the `external_url` property of the configuration file. +By default, WireGuard Portal listens on port `8888` for HTTP connections. Check the [Security](security.md) section for more information on securing the web UI. + +So the default URL to access the web UI is: + +``` +http://localhost:8888 +``` + +A freshly set-up WireGuard Portal instance will have a default admin user with the username `admin@wgportal.local` and the password `wgportal-default`. +You can and should override the default credentials in the configuration file. Make sure to change the default password immediately after the first login! + + +### Basic UI Description + +![WireGuard Portal Web UI](../../assets/images/landing_page.png) + +As seen in the screenshot above, the web UI is divided into several sections which are accessible via the navigation bar on the top of the screen. + +1. **Home**: The landing page of WireGuard Portal. It provides a staring point for the user to access the different sections of the web UI. It also provides quick links to WireGuard Client downloads or official documentation. +2. **Interfaces**: This section allows you to manage the WireGuard interfaces. You can add, edit, or delete interfaces, as well as view their status and statistics. Peers for each interface can be managed here as well. +3. **Users**: This section allows you to manage the users of WireGuard Portal. You can add, edit, or delete users, as well as view their status and statistics. +4. **Key Generator**: This section allows you to generate WireGuard keys locally on your browser. The generated keys are never sent to the server. This is useful if you want to generate keys for a new peer without having to store the private keys in the database. +5. **Profile / Settings**: This section allows you to access your own profile page, settings, and audit logs. + + +### Interface View + +![WireGuard Portal Interface View](../../assets/images/interface_view.png) + +The interface view provides an overview of the WireGuard interfaces and peers configured in WireGuard Portal. + +The most important elements are: + +1. **Interface Selector**: This dropdown allows you to select the WireGuard interface you want to manage. + All further actions will be performed on the selected interface. +2. **Create new Interface**: This button allows you to create a new WireGuard interface. +3. **Interface Overview**: This section provides an overview of the selected WireGuard interface. It shows the interface type, number of peers, and other important information. +4. **List of Peers**: This section provides a list of all peers associated with the selected WireGuard interface. You can view, add, edit, or delete peers from this list. +5. **Add new Peer**: This button allows you to add a new peer to the selected WireGuard interface. +6. **Add multiple Peers**: This button allows you to add multiple peers to the selected WireGuard interface. + This is useful if you want to add a large number of peers at once. \ No newline at end of file diff --git a/docs/documentation/usage/ldap.md b/docs/documentation/usage/ldap.md new file mode 100644 index 0000000..d0ebc77 --- /dev/null +++ b/docs/documentation/usage/ldap.md @@ -0,0 +1,37 @@ +WireGuard Portal lets you hook up any LDAP server such as Active Directory or OpenLDAP for both authentication and user sync. +You can even register multiple LDAP servers side-by-side. When someone logs in via LDAP, their specific provider is remembered, +so there's no risk of cross-provider conflicts. Details on the log-in process can be found in the [Security](security.md#ldap-authentication) documentation. + +If you enable LDAP synchronization, all users within the LDAP directory will be created automatically in the WireGuard Portal database if they do not exist. +If a user is disabled or deleted in LDAP, the user will be disabled in WireGuard Portal as well. +The synchronization process can be fine-tuned by multiple parameters, which are described below. + +## LDAP Synchronization + +WireGuard Portal can automatically synchronize users from LDAP to the database. +To enable this feature, set the `sync_interval` property in the LDAP provider configuration to a value greater than "0". +The value is a string representing a duration, such as "15m" for 15 minutes or "1h" for 1 hour (check the [exact format definition](https://pkg.go.dev/time#ParseDuration) for details). +The synchronization process will run in the background and synchronize users from LDAP to the database at the specified interval. +Also make sure that the `sync_filter` property is a well-formed LDAP filter, or synchronization will fail. + +### Limiting Synchronization to Specific Users + +Use the `sync_filter` property in your LDAP provider block to restrict which users get synchronized. +It accepts any valid LDAP search filter, only entries matching that filter will be pulled into the portal's database. + +For example, to import only users with a `mail` attribute: +```yaml +auth: + ldap: + - id: ldap + # ... other settings + sync_filter: (mail=*) +``` + +### Disable Missing Users + +If you set the `disable_missing` property to `true`, any user that is not found in LDAP during synchronization will be disabled in WireGuard Portal. +All peers associated with that user will also be disabled. + +If you want a user and its peers to be automatically re-enabled once they are found in LDAP again, set the `auto_re_enable` property to `true`. +This will only re-enable the user if they where disabled by the synchronization process. Manually disabled users will not be re-enabled. \ No newline at end of file diff --git a/docs/documentation/usage/security.md b/docs/documentation/usage/security.md new file mode 100644 index 0000000..41f36aa --- /dev/null +++ b/docs/documentation/usage/security.md @@ -0,0 +1,160 @@ +This section describes the security features available to administrators for hardening WireGuard Portal and protecting its data. + +## Authentication + +WireGuard Portal supports multiple authentication methods, including: + +- Local user accounts +- LDAP authentication +- OAuth and OIDC authentication +- Passkey authentication (WebAuthn) + +Users can have two roles which limit their permissions in WireGuard Portal: + +- **User**: Can manage their own account and peers. +- **Admin**: Can manage all users and peers, including the ability to manage WireGuard interfaces. + +### Password Security + +WireGuard Portal supports username and password authentication for both local and LDAP-backed accounts. +Local users are stored in the database, while LDAP users are authenticated against an external LDAP server. + +On initial startup, WireGuard Portal automatically creates a local admin account with the password `wgportal-default`. +> :warning: This password must be changed immediately after the first login. + +The minimum password length for all local users can be configured in the [`auth`](../configuration/overview.md#auth) +section of the configuration file. The default value is **16** characters, see [`min_password_length`](../configuration/overview.md#min_password_length). +The minimum password length is also enforced for the default admin user. + + +### Passkey (WebAuthn) Authentication + +Besides the standard authentication mechanisms, WireGuard Portal supports Passkey authentication. +This feature is enabled by default and can be configured in the [`webauthn`](../configuration/overview.md#webauthn-passkeys) section of the configuration file. + +Users can register multiple Passkeys to their account. These Passkeys can be used to log in to the web UI as long as the user is not locked. +> :warning: Passkey authentication does not disable password authentication. The password can still be used to log in (e.g., as a fallback). + +To register a Passkey, open the settings page *(1)* in the web UI and click on the "Register Passkey" *(2)* button. + +![Passkey UI](../../assets/images/passkey_setup.png) + + +### OAuth and OIDC Authentication + +WireGuard Portal supports OAuth and OIDC authentication. You can use any OAuth or OIDC provider that supports the authorization code flow, +such as Google, GitHub, or Keycloak. + +For OAuth or OIDC to work, you need to configure the [`external_url`](../configuration/overview.md#external_url) property in the [`web`](../configuration/overview.md#web) section of the configuration file. +If you are planning to expose the portal to the internet, make sure that the `external_url` is configured to use HTTPS. + +To add OIDC or OAuth authentication to WireGuard Portal, create a Client-ID and Client-Secret in your OAuth provider and +configure a new authentication provider in the [`auth`](../configuration/overview.md#auth) section of the configuration file. +Make sure that each configured provider has a unique `provider_name` property set. Samples can be seen [here](../configuration/examples.md). + +#### Limiting Login to Specific Domains + +You can limit the login to specific domains by setting the `allowed_domains` property for OAuth or OIDC providers. +This property is a comma-separated list of domains that are allowed to log in. The user's email address is checked against this list. +For example, if you want to allow only users with an email address ending in `outlook.com` to log in, set the property as follows: + +```yaml +auth: + oidc: + - provider_name: "oidc1" + # ... other settings + allowed_domains: + - "outlook.com" +``` + +#### Limit Login to Existing Users + +You can limit the login to existing users only by setting the `registration_enabled` property to `false` for OAuth or OIDC providers. +If registration is enabled, new users will be created in the database when they log in for the first time. + +#### Admin Mapping + +You can map users to admin roles based on their attributes in the OAuth or OIDC provider. To do this, set the `admin_mapping` property for the provider. +Administrative access can either be mapped by a specific attribute or by group membership. + +**Attribute specific mapping** can be achieved by setting the `admin_value_regex` and the `is_admin` property. +The `admin_value_regex` property is a regular expression that is matched against the value of the `is_admin` attribute. +The user is granted admin access if the regex matches the attribute value. + +Example: +```yaml +auth: + oidc: + - provider_name: "oidc1" + # ... other settings + field_map: + is_admin: "wg_admin_prop" + admin_mapping: + admin_value_regex: "^true$" +``` +The example above will grant admin access to users with the `wg_admin_prop` attribute set to `true`. + +**Group membership mapping** can be achieved by setting the `admin_group_regex` and `user_groups` property. +The `admin_group_regex` property is a regular expression that is matched against the group names of the user. +The user is granted admin access if the regex matches any of the group names. + +Example: +```yaml +auth: + oidc: + - provider_name: "oidc1" + # ... other settings + field_map: + user_groups: "groups" + admin_mapping: + admin_group_regex: "^the-admin-group$" +``` +The example above will grant admin access to users who are members of the `the-admin-group` group. + + +### LDAP Authentication + +WireGuard Portal supports LDAP authentication. You can use any LDAP server that supports the LDAP protocol, such as Active Directory or OpenLDAP. +Multiple LDAP servers can be configured in the [`auth`](../configuration/overview.md#auth) section of the configuration file. +WireGuard Portal remembers the authentication provider of the user and therefore avoids conflicts between multiple LDAP providers. + +To configure LDAP authentication, create a new [`ldap`](../configuration/overview.md#ldap) authentication provider in the [`auth`](../configuration/overview.md#auth) section of the configuration file. + +#### Limiting Login to Specific Users + +You can limit the login to specific users by setting the `login_filter` property for LDAP provider. This filter uses the LDAP search filter syntax. +The username can be inserted into the query by placing the `{{login_identifier}}` placeholder in the filter. This placeholder will then be replaced with the username entered by the user during login. + +For example, if you want to allow only users with the `objectClass` attribute set to `organizationalPerson` to log in, set the property as follows: + +```yaml +auth: + ldap: + - provider_name: "ldap1" + # ... other settings + login_filter: "(&(objectClass=organizationalPerson)(uid={{login_identifier}}))" +``` + +The `login_filter` should always be designed to return at most one user. + +#### Limit Login to Existing Users + +You can limit the login to existing users only by setting the `registration_enabled` property to `false` for LDAP providers. +If registration is enabled, new users will be created in the database when they log in for the first time. + +#### Admin Mapping + +You can map users to admin roles based on their group membership in the LDAP server. To do this, set the `admin_group` and `memberof` property for the provider. +The `admin_group` property defines the distinguished name of the group that is allowed to log in as admin. +All groups that are listed in the `memberof` attribute of the user will be checked against this group. If one of the groups matches, the user is granted admin access. + + +## UI and API Access + +WireGuard Portal provides a web UI and a REST API for user interaction. It is important to secure these interfaces to prevent unauthorized access and data breaches. + +### HTTPS +It is recommended to use HTTPS for all communication with the portal to prevent eavesdropping. + +Event though, WireGuard Portal supports HTTPS out of the box, it is recommended to use a reverse proxy like Nginx or Traefik to handle SSL termination and other security features. +A detailed explanation is available in the [Reverse Proxy](../getting-started/reverse-proxy.md) section. \ No newline at end of file diff --git a/frontend/src/views/HomeView.vue b/frontend/src/views/HomeView.vue index a771004..0291ca7 100644 --- a/frontend/src/views/HomeView.vue +++ b/frontend/src/views/HomeView.vue @@ -65,7 +65,7 @@ const auth = authStore()

{{ $t('home.about-portal.headline') }}

{{ $t('home.about-portal.content') }}

- {{ $t('home.about-portal.button') }}
diff --git a/mkdocs.yml b/mkdocs.yml index 9bafbe5..e6b988b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -78,6 +78,10 @@ nav: - Configuration: - Overview: documentation/configuration/overview.md - Examples: documentation/configuration/examples.md + - Usage: + - General: documentation/usage/general.md + - LDAP: documentation/usage/ldap.md + - Security: documentation/usage/security.md + - REST API: documentation/rest-api/api-doc.md - Upgrade: documentation/upgrade/v1.md - Monitoring: documentation/monitoring/prometheus.md - - REST API: documentation/rest-api/api-doc.md