diff --git a/.gitbook/assets/activity-log-date-range.png b/.gitbook/assets/activity-log-date-range.png new file mode 100644 index 0000000..aa964c6 Binary files /dev/null and b/.gitbook/assets/activity-log-date-range.png differ diff --git a/.gitbook/assets/activity-log-overview.png b/.gitbook/assets/activity-log-overview.png new file mode 100644 index 0000000..f035a5d Binary files /dev/null and b/.gitbook/assets/activity-log-overview.png differ diff --git a/.gitbook/assets/defguard-client-tray-view.png b/.gitbook/assets/defguard-client-tray-view.png new file mode 100644 index 0000000..d19f460 Binary files /dev/null and b/.gitbook/assets/defguard-client-tray-view.png differ diff --git a/.gitbook/assets/google-oauth2.png b/.gitbook/assets/google-oauth2.png new file mode 100644 index 0000000..957b949 Binary files /dev/null and b/.gitbook/assets/google-oauth2.png differ diff --git a/.gitbook/assets/group-based-policies.png b/.gitbook/assets/group-based-policies.png new file mode 100644 index 0000000..acabe5e Binary files /dev/null and b/.gitbook/assets/group-based-policies.png differ diff --git a/.gitbook/assets/location-wizard-posture-check.png b/.gitbook/assets/location-wizard-posture-check.png new file mode 100644 index 0000000..421171c Binary files /dev/null and b/.gitbook/assets/location-wizard-posture-check.png differ diff --git a/.gitbook/assets/oidc-disable-password-management.png b/.gitbook/assets/oidc-disable-password-management.png new file mode 100644 index 0000000..0f0649c Binary files /dev/null and b/.gitbook/assets/oidc-disable-password-management.png differ diff --git a/.gitbook/assets/posture-check-defguard-client-version.png b/.gitbook/assets/posture-check-defguard-client-version.png new file mode 100644 index 0000000..03d2bd3 Binary files /dev/null and b/.gitbook/assets/posture-check-defguard-client-version.png differ diff --git a/.gitbook/assets/posture-check-name-and-description.png b/.gitbook/assets/posture-check-name-and-description.png new file mode 100644 index 0000000..eab27f9 Binary files /dev/null and b/.gitbook/assets/posture-check-name-and-description.png differ diff --git a/.gitbook/assets/posture-check-summary.png b/.gitbook/assets/posture-check-summary.png new file mode 100644 index 0000000..3c14ec4 Binary files /dev/null and b/.gitbook/assets/posture-check-summary.png differ diff --git a/.gitbook/assets/smtp-configuration-options.png b/.gitbook/assets/smtp-configuration-options.png new file mode 100644 index 0000000..da2d2c2 Binary files /dev/null and b/.gitbook/assets/smtp-configuration-options.png differ diff --git a/.gitbook/assets/synchronize-users-from-groups-google.png b/.gitbook/assets/synchronize-users-from-groups-google.png new file mode 100644 index 0000000..823da3e Binary files /dev/null and b/.gitbook/assets/synchronize-users-from-groups-google.png differ diff --git a/.gitbook/assets/users-table-bulk-action-menu.png b/.gitbook/assets/users-table-bulk-action-menu.png new file mode 100644 index 0000000..e6cdc11 Binary files /dev/null and b/.gitbook/assets/users-table-bulk-action-menu.png differ diff --git a/.gitbook/assets/users-table-group-filter.png b/.gitbook/assets/users-table-group-filter.png new file mode 100644 index 0000000..95cc94d Binary files /dev/null and b/.gitbook/assets/users-table-group-filter.png differ diff --git a/README.md b/README.md index b891b19..c917e0f 100644 --- a/README.md +++ b/README.md @@ -9,16 +9,18 @@ Welcome to the Defguard documentation. Here, you’ll learn how to explore the f * [Getting started](getting-started/one-line-install.md)\ Lets you quickly set up your own Defguard instance to explore its features an user interface. * [Features and configuration](features/overview.md)\ - Helps you, as a future Defguard administrator, get familiar with all of Defguard’s features and how to configure them to suit your needs. + Helps you, as a future Defguard administrator, get familiar with all of Defguard’s features and how to configure them to suit your needs, including integrations such as the REST API and webhooks. * [Deployment strategies](deployment-strategies/overview.md)\ Walks you through the most common deployment strategies to help you set up your Defguard instance as a production-grade solution. -* [License](https://app.gitbook.com/s/tIboBQe0Rz5YT3cHdNlh/enterprise)\ +* [License](enterprise/license.md)\ Outlines the scope, limits, and purchasing process for the Defguard Enterprise license. * [Using Defguard (for end users)](using-defguard-for-end-users/overwiew.md)\ Helps you, as a Defguard end user, get familiar with the client applications and their features so you can quickly connect to your Defguard instance. +* [Support](support.md)\ + Shows you where to get help, how to report an issue, and where to find the troubleshooting guides for every component. +* [Compliance](compliance/defguard-compliance.md)\ + Describes how Defguard helps you meet the requirements of common security standards and regulations. * [In depth](in-depth/architecture-decision-records/)\ In-depth information about the platform and its development, reflecting our commitment to transparency. * [For developers](for-developers/contributing.md)\ All the information you need to become a Defguard contributor — join us in building a better solution. -* [Resources](support-1/troubleshooting/)\ - A collection of essential resources, including troubleshooting guides, API documentation, and more. diff --git a/SUMMARY.md b/SUMMARY.md index e51624c..d3628df 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -15,6 +15,7 @@ ## Features * [Overview](features/overview.md) +* [User management](features/user-management.md) * [Zero-Trust VPN with 2FA/MFA](features/wireguard/README.md) * [Create/Manage VPN Location](features/wireguard/create-your-vpn-network/README.md) * [Split Tunnel Configuration](features/wireguard/create-your-vpn-network/split-tunnel-configuration.md) @@ -68,7 +69,6 @@ * [Integrations](features/integrations/README.md) * [Webhooks](features/integrations/webhooks.md) * [REST API](features/integrations/api-tokens.md) -* [OPNSense Configuration](features/gateway.md) * [SSH Authentication](features/ssh-authentication.md) * [Forward auth](features/forward-auth.md) * [User SNAT bindings](features/user-snat-bindings.md) @@ -215,6 +215,7 @@ * [Security concepts](in-depth/architecture/security-concepts.md) * [MFA Architecture](in-depth/architecture/architecture.md) * [Architecture Decision Records](in-depth/architecture-decision-records/README.md) + * [2.1](in-depth/architecture-decision-records/2.1.md) * [2.0](in-depth/architecture-decision-records/2.0.md) * [1.6](in-depth/architecture-decision-records/1.6.md) * [1.5](in-depth/architecture-decision-records/1.5.md) diff --git a/about/about-defguard.md b/about/about-defguard.md index b9f2c79..53e4159 100644 --- a/about/about-defguard.md +++ b/about/about-defguard.md @@ -16,7 +16,7 @@ Defguard helps organizations: * Automate device enrollment. * Simplify network segmentation and access control using policies. -For a detailed list of features go to the [Features overview](https://github.com/DefGuard/docs/blob/v1.6/about/broken-reference/README.md) section. +For a detailed list of features go to the [Features overview](features-overview.md) section. ## Why choose Defguard? @@ -60,7 +60,7 @@ End users enjoy one-click VPN access via the Defguard apps, while admins gain gr #### 🧩 Modular and Scalable -Each component (Core, Gateway, Proxy) can be deployed independently, allowing flexible scaling - from a single office setup to multi-region enterprise deployments. +Each component (Core, Gateway, Edge) can be deployed independently, allowing flexible scaling - from a single office setup to multi-region enterprise deployments. #### 🧱 Security Built into the Development Process diff --git a/about/features-overview.md b/about/features-overview.md index fc25c12..2815bde 100644 --- a/about/features-overview.md +++ b/about/features-overview.md @@ -30,6 +30,14 @@ _Defguard is not an official WireGuard project, and WireGuard is a registered tr * Allow or deny access based on users or groups * Changes are applied in **real time** +### [Device posture verification](../features/device-posture-verification.md) + +* Check the security state of a device before it connects to a location +* Minimum operating system, Linux kernel and Defguard client versions +* Disk encryption, antivirus, Active Directory membership and device integrity conditions +* Limits on the age of Windows security updates and Android security patches +* Several checks can be assigned to one location, and a device has to satisfy all of them + ### Identity Management: * [**OpenID Connect**](https://openid.net/developers/how-connect-works/) **based SSO** @@ -47,8 +55,8 @@ _Defguard is not an official WireGuard project, and WireGuard is a registered tr ### Account Lifecycle Management: -* Secure remote (over the internet) [user enrollment](https://defguard.gitbook.io/defguard/help/remote-user-enrollment) -* User [onboarding after enrollment](https://defguard.gitbook.io/defguard/help/remote-user-enrollment/user-onboarding-after-enrollment) +* Secure remote (over the internet) [user enrollment](../features/remote-user-enrollment/) +* User [onboarding after enrollment](../features/remote-user-enrollment/user-onboarding-after-enrollment.md) * Self-service for password reset ### [Network devices](../features/network-devices.md) diff --git a/deployment-strategies/amis-and-aws-cloudformation/README.md b/deployment-strategies/amis-and-aws-cloudformation/README.md index af56fe2..15f9e1b 100644 --- a/deployment-strategies/amis-and-aws-cloudformation/README.md +++ b/deployment-strategies/amis-and-aws-cloudformation/README.md @@ -17,7 +17,7 @@ The template consists of the following main components: * **Defguard Edge** * **PostgreSQL Database** -We recommend reading the [Architecture documentation](https://docs.defguard.net/in-depth/architecture) to understand how these components interact. +We recommend reading the [Architecture documentation](../../in-depth/architecture/) to understand how these components interact.

Diagram showing how the components are deployed using the template

@@ -88,7 +88,7 @@ Make sure to also check the rest of the pre-filled parameters, as you may want t #### Stack options -Next, select the behavior on deployment failure: +Next, select the behaviour on deployment failure:
@@ -130,7 +130,7 @@ Use the token displayed in the `AdminFirstDeviceToken` CloudFormation output to
-Check this [guide](https://docs.defguard.net/using-defguard-for-end-users/desktop-client/instance-configuration#adding-instance) on adding a new instance in the Desktop client, to learn more about the process. As the instance URL, use the URL you defined in your Defguard Edge instance configuration section of the CloudFormation template (`ProxyUrl`). +Check this [guide](../../using-defguard-for-end-users/desktop-client/instance-configuration.md#manually-adding-instance) on adding a new instance in the Desktop client, to learn more about the process. As the instance URL, use the URL you defined in your Defguard Edge instance configuration section of the CloudFormation template (`ProxyUrl`). #### Accessing the dashboard @@ -176,7 +176,7 @@ To login, use the default `admin` username and the password defined in `CoreDefa #### Edge Instance * `ProxyGrpcPort` (optional): The gRPC port for the Edge, default is `50051`. -* `ProxyHttpPort` (optional): The HTTP port for the Edge, default is `8000`. This is where the Defguard Edge web UI will be accessible. The proxy UI is used for user enrollment. +* `ProxyHttpPort` (optional): The HTTP port for the Edge, default is `8000`. This is where the Defguard Edge web UI will be accessible. The Edge UI is used for user enrollment. * `ProxyInstanceType` (optional): The instance type for the Edge, default is `t3.micro`. * `ProxyLogLevel` (optional): The log level for the Edge, default is `info`. You can also set it to `error`, `debug` or `trace`. * `ProxyUrl` (required): The URL where the Defguard Edge will be accessible (e.g., `https://proxy.defguard.example.com`). This should be the URL that users will use to access the Defguard Edge web UI. diff --git a/deployment-strategies/configuration.md b/deployment-strategies/configuration.md index 9ac21db..703c78a 100644 --- a/deployment-strategies/configuration.md +++ b/deployment-strategies/configuration.md @@ -42,6 +42,8 @@ The following sections describe the supported deployment parameters for each Def * `--grpc-bind-address` / `DEFGUARD_GRPC_BIND_ADDRESS`: IP address the Core gRPC server binds to. * `--adopt-gateway` / `DEFGUARD_ADOPT_GATEWAY`: Gateway address used to launch the auto-adoption wizard. * `--adopt-edge` / `DEFGUARD_ADOPT_EDGE`: Edge address used to launch the auto-adoption wizard. +* `--rate-limit-per-second` / `DEFGUARD_RATELIMIT_PERSECOND`: Maximum number of requests per second per client IP before rate limiting kicks in. Set to `0` to disable rate limiting (default: `0`). +* `--rate-limit-burst` / `DEFGUARD_RATELIMIT_BURST`: Maximum burst size for the rate limiter (token bucket capacity per client IP). Set to `0` to disable rate limiting (default: `0`). #### Deprecated Core deployment parameters @@ -69,35 +71,28 @@ Since Defguard 2.0, much of the configuration that was previously provided throu * `--http-port` / `DEFGUARD_PROXY_HTTP_PORT`: Port used by the Edge HTTP server. * `--grpc-port` / `DEFGUARD_PROXY_GRPC_PORT`: Port used by the Edge gRPC server. * `--log-level` / `DEFGUARD_PROXY_LOG_LEVEL`: Sets the Edge log verbosity. -* `--ratelimit-persecond` / `DEFGUARD_PROXY_RATELIMIT_PERSECOND`: Sets the per-second request rate limit for the HTTP API. -* `--ratelimit-burst` / `DEFGUARD_PROXY_RATELIMIT_BURST`: Sets the allowed burst size for rate limiting. -* `--config:` Path `to` a TOML configuration file for Edge. +* `--rate-limit-per-second` / `DEFGUARD_PROXY_RATELIMIT_PERSECOND`: Sets the per-second request rate limit for the HTTP API. +* `--rate-limit-burst` / `DEFGUARD_PROXY_RATELIMIT_BURST`: Sets the allowed burst size for rate limiting. +* `--config`: Path to a TOML configuration file for Edge. * `--http-bind-address` / `DEFGUARD_HTTP_BIND_ADDRESS`: IP address the Edge HTTP server binds to. * `--grpc-bind-address` / `DEFGUARD_GRPC_BIND_ADDRESS`: IP address the Edge gRPC server binds to. * `--cert-dir` / `DEFGUARD_PROXY_CERT_DIR`: Directory where Edge stores its certificate files. * `--https-port` / `DEFGUARD_PROXY_HTTPS_PORT`: Port used by the Edge HTTPS server when TLS certificates are installed. * `--acme-staging` / `DEFGUARD_PROXY_ACME_STAGING`: Enables the Let’s Encrypt staging environment for ACME certificate issuance. - -#### Deprecated Edge deployment parameters - -* \`--grpc-cert / DEFGUARD\_PROXY\_GRPC\_CERT: Deprecated. gRPC certificates are now automatically generated by the Core CA. -* `--grpc-key` / `DEFGUARD_PROXY_GRPC_KEY`: Deprecated. gRPC certificates are now automatically generated by the Core CA. -* `--url` / `DEFGUARD_PROXY_URL`: Deprecated. The public Edge URL is now generated by Core instead. +* `--adoption-timeout` / `DEFGUARD_ADOPTION_TIMEOUT`: Time limit for the auto-adoption process, in minutes. ### Gateway deployment parameters * `--log-level` / `DEFGUARD_LOG_LEVEL`: Sets the Gateway log verbosity. * `--grpc-port` / `DEFGUARD_GRPC_PORT`: Port used by the Gateway gRPC server. -* `--grpc-cert` / `DEFGUARD_GATEWAY_GRPC_CERT`: gRPC TLS certificate used by Gateway. -* `--grpc-key` / `DEFGUARD_GATEWAY_GRPC_KEY`: gRPC TLS private key used by Gateway. * `--userspace` / `DEFGUARD_USERSPACE`: Enables a userspace WireGuard implementation. * `--stats-period` / `DEFGUARD_STATS_PERIOD`: Defines how often interface statistics are sent to Defguard Core. * `--ifname` / `DEFGUARD_IFNAME`: Sets the WireGuard interface name. -* `--pidfile:` Writes `the` Gateway process ID to the specified file. -* `--use-syslog:` Enables `logging` to syslog. -* `--syslog-facility:` Sets `the` syslog facility. -* `--syslog-socket:` Sets `the` syslog socket path. -* `--config:` Path `to` a TOML configuration file for Gateway. +* `--pidfile`: Writes the Gateway process ID to the specified file. +* `--use-syslog`: Enables logging to syslog. +* `--syslog-facility`: Sets the syslog facility. +* `--syslog-socket`: Sets the syslog socket path. +* `--config`: Path to a TOML configuration file for Gateway. {% hint style="danger" %} Defguard is built with highest security standards in mind, thus the pre/post options below **accept only a full path to one command and its arguments.** @@ -116,11 +111,16 @@ To run multiple commands, create an appropriate shell script. * `--http-bind-address` / `DEFGUARD_HTTP_BIND_ADDRESS`: IP address used for the Gateway health endpoint bind. * `--cert-dir` / `DEFGUARD_GATEWAY_CERT_DIR`: Directory where Gateway stores its certificate files. * `--adoption-timeout` / `DEFGUARD_ADOPTION_TIMEOUT`: Time limit for the auto-adoption process, in minutes. +* `--clean-on-quit` / `DEFGUARD_CLEAN_ON_QUIT`: On quit, removes the network interface and the VPN configuration. ### Config file Edge and Gateway can be configured not only through command-line options and environment variables, but also through a TOML configuration file. This is useful when you want to keep component configuration in a single file instead of passing all parameters at startup. +{% hint style="warning" %} +When a configuration file is passed with `--config`, it becomes the only source of configuration for that component: command-line options and environment variables are ignored, and every option not present in the file falls back to its default value. Either keep the whole component configuration in the file, or don't use the file at all. +{% endhint %} + When using a TOML file, the available keys correspond to the same configuration options exposed by the component through CLI arguments and environment variables. In the TOML file, these options should be written in snake\_case, matching the internal option names used by the component configuration. This makes the file-based configuration equivalent in scope to the startup parameters, while providing a more convenient format for managing persistent configuration. Example Edge configuration parameters: ```toml @@ -132,13 +132,12 @@ grpc_port = 50051 log_level = "info" rate_limit_per_second = 0 rate_limit_burst = 0 -url = "http://localhost:8080" acme_staging = false ``` ## Settings -This section describes the configuration that is managed from within the Defguard web interface after the system has been deployed. Unlike deployment parameters, which control how individual services are started, Settings are used to manage operational behavior directly from Core and can be updated by administrators through the UI. +This section describes the configuration that is managed from within the Defguard web interface after the system has been deployed. Unlike deployment parameters, which control how individual services are started, Settings are used to manage operational behaviour directly from Core and can be updated by administrators through the UI. This includes: @@ -151,7 +150,7 @@ This includes: * license and enterprise-related settings * SMTP and email delivery configuration * webhook configuration -* statistics retention and purge behavior +* statistics retention and purge behaviour * API tokens and integration-related settings * component adoption and setup workflows where managed through the UI @@ -162,8 +161,8 @@ Settings page is accessible only for admin users. It can be accessed with a navi The page is split into tabs that group related settings: * General: contains the main instance-level administration pages. - * Instance settings: configures the Core URL, instance name, public Edge URL, authentication period, statistics retention and purge behavior, and password reset timeouts. - * Client behavior: configures client-side permissions and policy controls, including device management, self-service client activation, and client traffic-routing policy. + * Instance settings: configures the Core URL, instance name, public Edge URL, authentication period, statistics retention and purge behaviour, and password reset timeouts. + * Client behaviour: configures client-side permissions and policy controls, including device management, self-service client activation, and client traffic-routing policy. * Notifications: contains outbound notification settings. * SMTP: configures the mail server connection used by Defguard, including server address, port, credentials, sender address, and encryption mode. * Gateway notifications: configures gateway disconnect and reconnect email notifications, including the inactivity threshold. @@ -214,6 +213,6 @@ The selected syslog socket may be wrong. See the `syslog_socket` configuration o `Cookie “defguard_session” has been rejected for invalid domain.` (browser console error) -This issue most often takes the form of not being able to login without any obvious cause. The login button doesn't redirect and no relevant error message is displayed in the Defguard Core logs. In this case we recommend checking the browser logs (usually right click > inspect should open the developer tools along with the browser console). If you can see the above error, this means that your `DEFGUARD_URL` configuration option doesn't match the URL you use to access the dashboard at the moment. +This issue most often takes the form of not being able to login without any obvious cause. The login button doesn't redirect and no relevant error message is displayed in the Defguard Core logs. In this case we recommend checking the browser logs (usually right click > inspect should open the developer tools along with the browser console). If you can see the above error, this means that the Core URL configured in Defguard (**Settings → General → Instance settings**) doesn't match the URL you use to access the dashboard at the moment. -For example, if your login screen is at `http://my.domain.com:8000/auth/login` set `DEFGUARD_URL` to `` http://my.domain.com:8000` `` . +For example, if your login screen is at `http://my.domain.com:8000/auth/login` set the Core URL to `http://my.domain.com:8000`. diff --git a/deployment-strategies/deploying-to-production.md b/deployment-strategies/deploying-to-production.md index f90eb48..1194f13 100644 --- a/deployment-strategies/deploying-to-production.md +++ b/deployment-strategies/deploying-to-production.md @@ -39,7 +39,7 @@ Follow our [guide](production-deployment-verification-guide.md) to test if your {% step %} **Configure features** -Follow detailed descriptions of [Defguard’s features](https://github.com/DefGuard/docs/blob/v1.6/deployment-strategies/broken-reference/README.md). As you follow along, you can adjust the configuration directly within your instance. +Follow detailed descriptions of [Defguard’s features](../features/overview.md). As you follow along, you can adjust the configuration directly within your instance. For a detailed list of all configurable things through environmental variables, options or configuration files follow [this reference](configuration.md). {% endstep %} diff --git a/deployment-strategies/docker-compose.md b/deployment-strategies/docker-compose.md index 22cffc3..a71a395 100644 --- a/deployment-strategies/docker-compose.md +++ b/deployment-strategies/docker-compose.md @@ -75,7 +75,7 @@ docker compose up Depending on your infrastructure, you may choose to keep the setup simple and let Defguard handle SSL termination for you. Learn more about this functionality [here](../tutorials/initial-setup-wizard-setting-up-from-scratch.md#configure-ssl-for-core). In that case skip stis step. -Alternatively, you can place a reverse proxy in front of your Core service to manage SSL termination. +Alternatively, you can place a reverse proxy in front of your Core service to manage SSL termination. Here is an example [nginx](https://nginx.org/) configuration to provide SSL termination: @@ -130,7 +130,7 @@ services: Depending on your infrastructure, you may choose to keep the setup simple and let Defguard handle SSL termination for you. Learn more about this functionality [here](../tutorials/initial-setup-wizard-setting-up-from-scratch.md#configure-ssl-for-edge). In that case skip stis step. -Alternatively, you can place a reverse proxy in front of your Edge service to manage SSL termination. +Alternatively, you can place a reverse proxy in front of your Edge service to manage SSL termination. Here is an example [nginx](https://nginx.org/) configuration to provide SSL termination: diff --git a/deployment-strategies/hardware-os-network-and-firewall-recommendations.md b/deployment-strategies/hardware-os-network-and-firewall-recommendations.md index 2c86b23..4b02bb4 100644 --- a/deployment-strategies/hardware-os-network-and-firewall-recommendations.md +++ b/deployment-strategies/hardware-os-network-and-firewall-recommendations.md @@ -69,7 +69,7 @@ The server on which the Edge is installed does not need to have the IP address a If this address is assigned for example to a firewall, a load balancer or a reverse proxy, rather than the server hosting the Edge, then just [forward proper ports acording to instruction below](hardware-os-network-and-firewall-recommendations.md#port-and-firewall-exposure-summary). {% hint style="warning" %} -If the Proxy is behind a reverse proxy or load balancer, preserve Defguard-specific headers. +If Edge is behind a reverse proxy or load balancer, preserve Defguard-specific headers. Forward request headers: `defguard-client-version`, `defguard-client-platform` diff --git a/deployment-strategies/health-check.md b/deployment-strategies/health-check.md index 0247849..0076183 100644 --- a/deployment-strategies/health-check.md +++ b/deployment-strategies/health-check.md @@ -1,8 +1,8 @@ # Health check -## Proxy +## Edge -[Proxy](https://github.com/defguard/proxy) provides health endpoint at `GET /api/v1/health` which checks whether the application is running. +[Edge](https://github.com/defguard/proxy) provides health endpoint at `GET /api/v1/health` which checks whether the application is running. Example request: @@ -12,9 +12,9 @@ curl https://enroll.example.com/api/v1/health Response: -* `alive` with status code 200 – Proxy is working +* `alive` with status code 200 – Edge is working -To verify gRPC services for **Proxy** are alive, there is endpoint at `GET /api/v1/health-grpc` that verify it. +To verify gRPC services for **Edge** are alive, there is endpoint at `GET /api/v1/health-grpc` that verify it. Example request: @@ -24,8 +24,8 @@ curl https://enroll.example.com/api/v1/health-grpc Response: -* `alive` with status code 200 – Proxy is working and is connected to Core -* `Not connected to Defguard Core` with status code 503 – Proxy is working, but is not connected to Core +* `alive` with status code 200 – Edge is working and is connected to Core +* `Not connected to Defguard Core` with status code 503 – Edge is working, but is not connected to Core ## Core @@ -63,9 +63,9 @@ In Gateway configuration, a health check port can be enabled by adding the follo health_port = 55003 ``` -In this example, Gateway will open an additional HTTP port number 55003. Now we can use `GET /api/v1/health` endpoint to verify whether Gateway is working correctly. +In this example, Gateway will open an additional HTTP port number 55003. Now we can use `GET /health` endpoint to verify whether Gateway is working correctly. -If running in Docker you can also enable it by setting the `HEALTH_PORT` [environment variable](configuration.md#environmental-variables-arguments). +If running in Docker you can also enable it by setting the `HEALTH_PORT` [environment variable](configuration.md#gateway-deployment-parameters). By default the HTTP server will listen on all interfaces, but if you prefer to bind only a specific IP you can set it by using the `http_bind_address` config option (or `DEFGUARD_HTTP_BIND_ADDRESS` environment variable). For example: @@ -76,7 +76,7 @@ http_bind_address = 10.0.10.20 Example request: ```sh -curl http://gateway.example.com:55003/api/v1/health +curl http://gateway.example.com:55003/health ``` Response: diff --git a/deployment-strategies/high-availability-and-failover/gateway-with-carp.md b/deployment-strategies/high-availability-and-failover/gateway-with-carp.md index 0520f34..adf2801 100644 --- a/deployment-strategies/high-availability-and-failover/gateway-with-carp.md +++ b/deployment-strategies/high-availability-and-failover/gateway-with-carp.md @@ -12,7 +12,7 @@ At least two OPNsense machines are required for high availability. These machine In this setup, one node normally owns the virtual IP address and handles traffic. If that node fails, the secondary node can take over the same IP address, which helps keep the gateway reachable without changing the VPN endpoint configured on clients. -To use CARP with Gateway on [OPNsense](https://opnsense.org/), first [install the Gateway package for OPNsense](https://github.com/DefGuard/docs/blob/v2.0/deployment-strategies/high-availability-and-failover/deployment-strategies/running-gateway-on-opnsense-firewall.md). +To use CARP with Gateway on [OPNsense](https://opnsense.org/), first [install the Gateway package for OPNsense](../running-gateway-on-opnsense-firewall.md). In the OPNsense user interface, go to **Interfaces → Virtual IPs → Settings**, click "+" (plus), and create a new CARP Virtual IP: diff --git a/deployment-strategies/high-availability-and-failover/wireguard-udp-load-balancing.md b/deployment-strategies/high-availability-and-failover/wireguard-udp-load-balancing.md index 1b84b7d..920a257 100644 --- a/deployment-strategies/high-availability-and-failover/wireguard-udp-load-balancing.md +++ b/deployment-strategies/high-availability-and-failover/wireguard-udp-load-balancing.md @@ -74,7 +74,7 @@ Reasons: * Native UDP proxy support * Health checks with fine-grained timing controls * Proper backend ejection on failure -* Production-grade L4 behavior +* Production-grade L4 behaviour Recommended configuration characteristics: @@ -108,7 +108,7 @@ Envoy has multiple health-check timing parameters: * healthy\_edge\_interval * unhealthy\_edge\_interval -If only `interval` is configured, the effective behavior may differ depending on traffic state. +If only `interval` is configured, the effective behaviour may differ depending on traffic state. Symptoms: @@ -142,7 +142,7 @@ As a result: * Tunnel recovery may take up to the configured keepalive interval. * Shorter keepalive intervals result in faster failover recovery. -#### Expected failover behavior +#### Expected failover behaviour With proper configuration: diff --git a/deployment-strategies/ova.md b/deployment-strategies/ova.md index 059a068..2c23654 100644 --- a/deployment-strategies/ova.md +++ b/deployment-strategies/ova.md @@ -15,10 +15,6 @@ After importing the image, make sure to: Once booted, the virtual machine will have all Defguard components pre-configured. To complete the setup, simply visit the Defguard Core dashboard: http://\:8000. Follow the on-screen wizard to finalize your configuration. -{% hint style="info" %} -For example setup walkthrough [see this guide](/broken/pages/nNsN8zKGZVhPboFEtp8E#example-setup). -{% endhint %} - If you would like to setup a reverse-proxy beforhand (which enables automated SSL Certificates with Let's Encrypt), [go to this section for more details](ova.md#setting-up-a-reverse-proxy). ### Accessing the VM diff --git a/deployment-strategies/overview.md b/deployment-strategies/overview.md index 87d1ce7..efbea9e 100644 --- a/deployment-strategies/overview.md +++ b/deployment-strategies/overview.md @@ -77,13 +77,13 @@ If this directory is missing or empty at startup, the component detects the abse Include the certificate directory in your server backup alongside your database if you want zero-downtime recovery - re-enrollment requires manual action in the admin UI for each affected Gateway and Edge instance. {% hint style="info" %} -Because the CA is stored in the database, a restored Core can always re-issue new component certificates. +Because the CA is stored in the database, a restored Core can always re-issue new component certificates. Losing the local cert directory does not cause permanent data loss - it requires re-running the [setup flow](../tutorials/adding-edge-component.md) for that component. {% endhint %} ## Failover/High Availability/Clustering -[Defguard Gateway](https://github.com/DefGuard/docs/blob/v2.0/deployment-strategies/gateway.md) can be deployed on multiple servers, firewalls, or routers for failover and high availability (HA). Even if the connection to the Core is lost, a Gateway continues to operate using its local cache and data, ensuring that the VPN remains functional. Conversely, if a Gateway becomes unavailable, other Core features such as OpenID continue to work normally. +[Defguard Gateway](standalone-package-based-installation/gateway.md) can be deployed on multiple servers, firewalls, or routers for failover and high availability (HA). Even if the connection to the Core is lost, a Gateway continues to operate using its local cache and data, ensuring that the VPN remains functional. Conversely, if a Gateway becomes unavailable, other Core features such as OpenID continue to work normally. For details on deploying multiple Gateways, refer to the [High Availability and Failover](high-availability-and-failover/) documentation. diff --git a/deployment-strategies/programmatic-gateway-adoption.md b/deployment-strategies/programmatic-gateway-adoption.md index 404aec8..9eda397 100644 --- a/deployment-strategies/programmatic-gateway-adoption.md +++ b/deployment-strategies/programmatic-gateway-adoption.md @@ -15,7 +15,7 @@ curl -X POST 'https://defguard.example.com/api/v1/network/42/gateways/adopt' \ }' ``` -Here, `ip_or_domain` is the address of the Gateway, and `grpc_port` is the Gateway gRPC port (`50066` by default). To authorize the request, first obtain an [API token](https://app.gitbook.com/s/qPYuWxfmxFk6sz1LLLwd/features/integrations/api-tokens#generating-api-token) and replace `` with it. +Here, `ip_or_domain` is the address of the Gateway, and `grpc_port` is the Gateway gRPC port (`50066` by default). To authorize the request, first obtain an [API token](../features/integrations/api-tokens.md#generating-api-token) and replace `` with it. -For more information about using the Defguard API, see [REST API documentation](https://docs.defguard.net/features/integrations/api-tokens#rest-api-documentation). +For more information about using the Defguard API, see [REST API documentation](../features/integrations/api-tokens.md#rest-api-documentation). diff --git a/deployment-strategies/running-gateway-on-opnsense-firewall.md b/deployment-strategies/running-gateway-on-opnsense-firewall.md index a9509e7..a3b3df5 100644 --- a/deployment-strategies/running-gateway-on-opnsense-firewall.md +++ b/deployment-strategies/running-gateway-on-opnsense-firewall.md @@ -27,15 +27,58 @@ opnsense-patch 5. Fill out the form with appropriate values, click **Save**, and then click **Start/Restart.** {% hint style="info" %} -You can find detailed description of all fields [here](configuration.md#gateway-configuration). +You can find detailed description of all fields [here](configuration.md#gateway-deployment-parameters). {% endhint %} -If everything went well, Defguard Gateway should be connected to Defguard Core and you can start [adding new devices to your network](../features/wireguard/remote-desktop-activation.md). +At this point the Gateway should be connected to Defguard Core. Before users can reach anything through it, OPNsense itself still needs an interface, a NAT rule and a firewall rule - continue with [#opnsense-network-configuration](running-gateway-on-opnsense-firewall.md#opnsense-network-configuration "mention"). -See also: [how to configure Defguard in OPNsense](../features/gateway.md) +## OPNsense network configuration + +The steps below are based on the [WireGuard Road Warrior Setup](https://docs.opnsense.org/manual/how-tos/wireguard-client.html) from the OPNsense documentation. + +### Assign a network interface to Defguard + +1. Go to **Interfaces → Assignments** +2. Under **Assign a new interface**, select the Defguard Gateway network interface (e.g. _wg0_) +3. Add a description, for example _ParisOfficeVPN_ +4. Click **Add** + +
Interface Assignments
+ +5. Select the newly create interface by clicking on its name (in this example _\[ParisOfficeVPN]_). +6. Select **Enable Interface** +7. Select **Prevent interface removal** +8. Click **Save**, and then **Apply changes** + +### Create an outbound NAT rule + +1. Go to **Firewall → NAT → Outbound** +2. Make sure the selected **Mode** is **Hybrid outbound NAT rule generation**; if it wasn't selected, click **Save** and then **Apply changes** +3. Under **Manual rules**, add a new rule by clicking **+**. +4. Select **Interface** – this should be either WAN or LAN, depending on the needs. +5. Select **TCP/IP version** – either IPv4 or IPv6. +6. Select **Source address** – this should be interface name assigned above plus _net_, e.g. _ParisOfficeVPN net_. +7. Click **Save**, and then **Apply changes** + +
Outbound NAT rule
+ +### Add firewall rules to allow WireGuard traffic in + +1. Go to **Firewall → Rules → WAN** +2. Click **+** (plus) to add a new rule +3. The rule should _Pass_ the traffic _in_ with _quick_ option enabled +4. Select **WAN** interface +5. Choose **TCP/IP version** of your desire +6. Select **UDP** protocol. +7. Set **Destination** to **WAN address** and port to the port number provided in Defguard Core: _Location configuration → Gateway port_ +8. Click **Save**, and then **Apply changes** + +Once this is done you can start [adding new devices to your network](../features/wireguard/remote-desktop-activation.md). ## Binary Install +Use this method if you are not running the OPNsense plugin. + 1. Checkout Gateway releases [here](https://github.com/DefGuard/gateway/releases) and download compatible binary from GitHub page. 2. Decompress and move to bin directory @@ -45,4 +88,10 @@ sudo chmod +x gateway sudo mv gateway /usr/bin/ ``` -3. Start gateway `gateway -g -t ` +3. Start the gateway, pointing it at its configuration file: + +```sh +gateway --config /etc/defguard/gateway.toml +``` + +4. Adopt the gateway in Defguard Core, as described in [Adopt the Gateway component](../tutorials/initial-setup-wizard-setting-up-from-scratch.md#adopt-the-gateway-component). diff --git a/deployment-strategies/running-gateway-on-vyos.md b/deployment-strategies/running-gateway-on-vyos.md index e4db32a..b403f11 100644 --- a/deployment-strategies/running-gateway-on-vyos.md +++ b/deployment-strategies/running-gateway-on-vyos.md @@ -64,9 +64,9 @@ show container sudo podman ps -a ``` -At this point, the gateway container should be running on VyOS and ready to be adopted by Defguard Core service. +At this point, the gateway container should be running on VyOS and ready to be adopted by Defguard Core service. -Adopt it by following [those steps](https://docs.defguard.net/tutorials/initial-setup-wizard-setting-up-from-scratch#adopt-the-gateway-component). +Adopt it by following [those steps](../tutorials/initial-setup-wizard-setting-up-from-scratch.md#adopt-the-gateway-component). {% hint style="warning" %} Gateway accepts adoption requests only for a limited time after startup. Start the adoption process in Defguard Core shortly after starting the container. diff --git a/deployment-strategies/standalone-package-based-installation/README.md b/deployment-strategies/standalone-package-based-installation/README.md index 5d73f4a..c810d87 100644 --- a/deployment-strategies/standalone-package-based-installation/README.md +++ b/deployment-strategies/standalone-package-based-installation/README.md @@ -35,7 +35,7 @@ These prerequisites are meant to help you avoid the most common deployment issue * Administrative (sudo) privileges. * A server with a public IP address (and knowledge of what that IP address is and which interface it is assigned to) - in this example, we use `185.33.37.51`. * A domain name, and knowledge of how to assign IP addresses and manage subdomains. In our example, the main Defguard URL is _my-server.defguard.net_ (and the subdomain points to `185.33.37.51`). -* A Defguard [enrollment service](https://defguard.gitbook.io/defguard/help/enrollment) (run by the proxy) that enables [remote onboarding and enrollment](https://defguard.gitbook.io/defguard/help/enrollment), as well as [easy configuration for our Desktop Clients (by adding Defguard instances)](../../using-defguard-for-end-users/desktop-client/instance-configuration.md#adding-instance) using the instance URL and a simple token. In this tutorial, we use _enroll.defguard.net_ (this subdomain also points to `185.33.37.51`). +* A Defguard [enrollment service](../../features/remote-user-enrollment/) (run by the proxy) that enables [remote onboarding and enrollment](../../features/remote-user-enrollment/), as well as [easy configuration for our Desktop Clients (by adding Defguard instances)](../../using-defguard-for-end-users/desktop-client/instance-configuration.md#manually-adding-instance) using the instance URL and a simple token. In this tutorial, we use _enroll.defguard.net_ (this subdomain also points to `185.33.37.51`). * If you have a **firewall**, we assume you have **opened port 443** in order to expose both Defguard and the enrollment service, and to automatically issue SSL certificates for these domains. Port 444 (used for internal gRPC communication) **should not be publicly exposed**. * System clock is synchronized using [Network Time Protocol (NTP)](https://www.ntp.org/). This is important for time-based one-time password (TOTP) codes. * A PostgreSQL [database](database.md) @@ -117,7 +117,7 @@ sudo rpm -Uvh defguard-X.Y.Z-x86_64-unknown-linux-gnu.rpm # or Proxy package pkg delete defguard-proxy ``` -2. Install a newer version (as described [above](./#installing-packages)). +2. Install a newer version (as described [above](./#defguard-packages)). 3. Restart the service. ```sh diff --git a/deployment-strategies/standalone-package-based-installation/defguard-apt-repository.md b/deployment-strategies/standalone-package-based-installation/defguard-apt-repository.md index ea962b1..2613bd0 100644 --- a/deployment-strategies/standalone-package-based-installation/defguard-apt-repository.md +++ b/deployment-strategies/standalone-package-based-installation/defguard-apt-repository.md @@ -57,7 +57,7 @@ Defguard Core: sudo apt install defguard ``` -Defguard Proxy: +Defguard Edge: ```sh sudo apt install defguard-proxy diff --git a/deployment-strategies/terraform.md b/deployment-strategies/terraform.md index 7962224..c6ad7be 100644 --- a/deployment-strategies/terraform.md +++ b/deployment-strategies/terraform.md @@ -1,9 +1,5 @@ # Terraform -{% hint style="info" %} -Terraform deployment works with Defguard Core version 1.3.2-alpha2 and later. -{% endhint %} - {% hint style="info" %} We've recently introduced this deployment method and are still actively improving it. If you encounter any issues or have suggestions, please open an issue in the [Defguard deployment repository](https://github.com/DefGuard/deployment/issues). {% endhint %} @@ -14,10 +10,10 @@ To deploy Defguard using Terraform on AWS, you can use the Terraform configurati The terraform configuration includes the necessary resources to setup all components of Defguard. -We recommend reading on the architecture of Defguard before proceeding with the deployment. You can find the documentation on the [Defguard architecture page](https://docs.defguard.net/in-depth/architecture). When configuring the networking, the most important thing is to keep in mind the following rules: +We recommend reading on the architecture of Defguard before proceeding with the deployment. You can find the documentation on the [Defguard architecture page](../in-depth/architecture/). When configuring the networking, the most important thing is to keep in mind the following rules: * Defguard Core web UI should be accessible only from the internal network or through a secure VPN connection. -* Defguard Proxy web UI should be publicly accessible, as it is used to securely pass messages to core from clients that are not connected to the VPN. +* Defguard Edge web UI should be publicly accessible, as it is used to securely pass messages to core from clients that are not connected to the VPN. * Defguard Gateway UDP port should be publicly accessible, as clients use it to connect to the VPN. * All gRPC traffic must stay internal. gRPC ports should only be available for the two parties that communicate with each other, e.g. core and proxy, or core and gateway. @@ -68,26 +64,26 @@ It accepts the following variables: * `cookie_insecure`: Set to `true` if you are using HTTP instead of HTTPS. This is not recommended for production environments. * `default_admin_password`: The default password for the admin user. This should be changed after the first login. * `proxy_grpc_port`: The gRPC port for Defguard Core to connect to the proxy. This must match the `grpc_port` variable in the proxy module. -* `proxy_url`: The URL at which Defguard Proxy will be accessible. This must match the `proxy_url` variable in the proxy module. This will be displayed to the user in the web UI when adding a new device. +* `proxy_url`: The URL at which Defguard Edge will be accessible. This must match the `proxy_url` variable in the proxy module. This will be displayed to the user in the web UI when adding a new device. * `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created. See the [VPN networks configuration](terraform.md#vpn-networks-configuration) section for more details on how to configure the VPN networks. * `db_details`: A map containing the database configuration. It must contain the following: * `name`: The name of the PostgreSQL database to be created for Defguard. * `username`: The username for the PostgreSQL database. * `password`: The password for the PostgreSQL database user. * `port`: The port on which the PostgreSQL database will listen. -* `proxy_address`: The IP address of the Defguard Proxy instance. Ideally this should be a private address, as it will be used for internal communication between the core and proxy components. +* `proxy_address`: The IP address of the Defguard Edge instance. Ideally this should be a private address, as it will be used for internal communication between the core and proxy components. * `gateway_secret`: The secret used to authenticate the gateways with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the gateway module. * `network_interface_id`: The ID of the network interface that should be attached to the Defguard Core instance. This is used to ensure that the core instance has a private IP address in the same VPC as the proxy and gateways. #### Proxy module -The proxy module is responsible for setting up the Defguard Proxy. +The proxy module is responsible for setting up the Defguard Edge. It accepts the following variables: -* `url`: The URL at which Defguard Proxy will be accessible. -* `grpc_port`: The gRPC port for Defguard Proxy to communicate with core. This is used only for internal communication. -* `http_port`: The HTTP port on which the Defguard Proxy web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default. +* `url`: The URL at which Defguard Edge will be accessible. +* `grpc_port`: The gRPC port for Defguard Edge to communicate with core. This is used only for internal communication. +* `http_port`: The HTTP port on which the Defguard Edge web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default. #### Gateway module @@ -197,7 +193,7 @@ The `basic` example can be directly downloaded using the following link: [basic/ The example is a basic configuration that sets up all the components and a network that allows them to communicate with each other. It includes the following: * Defguard Core instance -* Defguard Proxy instance +* Defguard Edge instance * Defguard Gateway instance * A database instance (RDS) for Defguard Core. * A single VPC for all components. diff --git a/deployment-strategies/updating-and-version-compatibility.md b/deployment-strategies/updating-and-version-compatibility.md index 89b121c..ed3f1e3 100644 --- a/deployment-strategies/updating-and-version-compatibility.md +++ b/deployment-strategies/updating-and-version-compatibility.md @@ -4,7 +4,7 @@ **Always back up your database before updating Core.** Core is the only component with persistent storage (PostgreSQL). See the [deployment overview](overview.md#backup) for backup instructions. {% endhint %} -Defguard is composed of multiple components (Core, Edge, Gateway) that communicate over gRPC. Each component can be updated independently, provided the components remain compatible. +Defguard is composed of multiple components (Core, Edge, Gateway) that communicate over gRPC. Each component can be updated independently, provided the components remain compatible. When components attempt to establish a connection, Defguard automatically performs a version check. If an incompatibility is detected, the connection is refused. @@ -33,14 +33,14 @@ Choose the guide that matches how you deployed Defguard: * [Docker / Docker Compose](docker-compose.md#upgrading) * [Standalone packages (DEB, RPM)](standalone-package-based-installation/#upgrading-packages) -* [OVA / Virtual Appliance](ova.md#managing-and-updating-containers) +* [OVA / Virtual Appliance](ova.md#upgrading) ### Official GitHub Releases Check the GitHub repositories for each service to find their newest releases and release notes: * [Defguard Core](https://github.com/DefGuard/defguard/releases) -* [Defguard Proxy](https://github.com/DefGuard/proxy/releases) +* [Defguard Edge](https://github.com/DefGuard/proxy/releases) * [Defguard Gateway](https://github.com/DefGuard/gateway/releases) * [Defguard YubiBridge](https://github.com/DefGuard/YubiKey-Provision/releases) diff --git a/deployment-strategies/upgrading.md b/deployment-strategies/upgrading.md index 952501f..a86f40b 100644 --- a/deployment-strategies/upgrading.md +++ b/deployment-strategies/upgrading.md @@ -8,6 +8,10 @@ description: Notes on upgrading Defguard and its components Before doing any updates please remember to **backup your database.** {% endhint %} +## 2.0.x -> 2.1.0 + +No migration steps are required. Back up your database, then update Core, Edge and Gateway together as described in [updating-and-version-compatibility.md](updating-and-version-compatibility.md "mention"). + ## 1.6.x -> 2.0.0 {% hint style="danger" %} @@ -19,9 +23,9 @@ The good news is that we have raised the limits for the free tier, and it now su {% hint style="warning" %} **Upgrading from 1.5.x?** -We recommend upgrading to the latest **1.6.x** release before migrating to **2.x**. +We recommend upgrading to the latest **1.6.x** release before migrating to **2.x**. -This ensures that all intermediate migrations and configuration changes are applied in the expected order, reducing the risk of upgrade-related issues. +This ensures that all intermediate migrations and configuration changes are applied in the expected order, reducing the risk of upgrade-related issues. Recommended upgrade path: **any → latest 1.6.x → 2.x.** {% endhint %} @@ -68,13 +72,13 @@ As mentioned in the Core migration section, this feature requires both Defguard #### Service locations -The [service-locations.md](../features/service-locations.md "mention") feature currently only works on the Windows Desktop Client. Locations in the service location mode won't be sent to clients that don't support them (either are older than 1.6.0 or are on a different platform than Windows). +When 1.6.0 was released, the [service-locations.md](../features/service-locations.md "mention") feature worked only on the Windows Desktop Client - see that page for the platforms supported today. Locations in the service location mode won't be sent to clients that don't support them (either are older than 1.6.0 or are on a platform without support). To work properly, this feature requires the Desktop Client to be in version 1.6. Service locations won't show up or work in older clients. #### Force all traffic -1.6 introduces the ability to "Force all traffic" as a [Client traffic policy](../features/wireguard/behavior-customization.md#client-traffic-policy-selection). However, this policy only works with desktop and mobile clients ≥ 1.6.0. Older clients (<1.6.0) will not respect the policy and will allow the users to select the "Predefined traffic" option. As an alternative, administrators can enforce all traffic by setting allowed ips: `0.0.0.0/0, ::/0`. +1.6 introduces the ability to "Force all traffic" as a [Client traffic policy](../features/wireguard/behavior-customization.md#client-traffic-rules). However, this policy only works with desktop and mobile clients ≥ 1.6.0. Older clients (<1.6.0) will not respect the policy and will allow the users to select the "Predefined traffic" option. As an alternative, administrators can enforce all traffic by setting allowed ips: `0.0.0.0/0, ::/0`. #### macOS Client changes @@ -109,7 +113,7 @@ To resolve this, before upgrading, we recommend first uninstalling the old Clien **Force all traffic** -1.6 introduces the ability to "Force all traffic" as a [Client traffic policy](https://app.gitbook.com/s/e86iamwJVSYnIRsyVEAV/features/wireguard/behavior-customization#client-traffic-policy-selection). However, this policy only works with desktop and mobile clients ≥ 1.6.0. Older clients (<1.6.0) will not respect the policy and will allow the users to select the "Predefined traffic" option. As an alternative, administrators can enforce all traffic by setting allowed ips: `0.0.0.0/0, ::/0`. +1.6 introduces the ability to "Force all traffic" as a [Client traffic policy](../features/wireguard/behavior-customization.md#client-traffic-rules). However, this policy only works with desktop and mobile clients ≥ 1.6.0. Older clients (<1.6.0) will not respect the policy and will allow the users to select the "Predefined traffic" option. As an alternative, administrators can enforce all traffic by setting allowed ips: `0.0.0.0/0, ::/0`. ## 1.4.x -> 1.5.0 @@ -240,7 +244,7 @@ You will need to change a duplicate email address before the upgrade by hand via ### Desktop Client Real Time Sync -From 1.0.0 we have introduced [Enterprise features](https://github.com/DefGuard/docs/blob/docs/deployment-strategies/broken-reference/README.md), and one of them is [automatic and real-time desktop client configuration synchronization](../features/remote-user-enrollment/automatic-real-time-desktop-client-configuration.md). +From 1.0.0 we have introduced [Enterprise features](../enterprise/license.md), and one of them is [automatic and real-time desktop client configuration synchronization](../features/remote-user-enrollment/automatic-real-time-desktop-client-configuration.md). To enable this on an **already configured desktop client,** one must perform one time instance update, which will generate necessary tokens on the client to perform from now on automatic updates. In details: @@ -264,14 +268,12 @@ This change requires a few changes if you are upgrading: 1. Remove `DEFGUARD_PROXY_UPSTREAM_GRPC_URL` variable - since Proxy does not connect to Defguard Core any more. 2. Proxy is now the server to which Defguard Core connects, so you may want to: 1. Optional: configure non-default Proxy gRPC port with `DEFGUARD_PROXY_GRPC_PORT -` default value is **50051** - 2. If you have a Proxy in a different network segment - eg. have a custom installation (not with one-line install/docker compose all on one server) - you may also consider exposing the gRPC port and reverse-proxy (nginx/treafik/...) the port with SSL/TLS. - 1. (Optional) If you want to use SSL with Proxy gRPC server without revers-proxy (nginx/etc) configure `DEFGUARD_PROXY_GRPC_CERT` and `DEFGUARD_PROXY_GRPC_KEY` following the [SSL setup guide](docker-compose.md#grpc-ssl-setup). + 2. If you have a Proxy in a different network segment - eg. have a custom installation (not with one-line install/docker compose all on one server) - you may also consider exposing the gRPC port and reverse-proxy (nginx/traefik/...) the port with SSL/TLS. 3. Also adjust your firewall config to open new Docker port mapping etc. Make sure Proxy gRPC server **can be reached from Core**. #### Core deployment configuration 1. Add `DEFGUARD_PROXY_URL` variable to point to your Proxy gRPC server endpoint, for example `http://proxy:50051` when using Docker Compose - or any gRPC URL you have configured with your reverse proxy. -2. (Optional) If using SSL configure `DEFGUARD_PROXY_GRPC_CA` #### Upgrade process diff --git a/deployment-strategies/using-a-userspace-wireguard-implementation.md b/deployment-strategies/using-a-userspace-wireguard-implementation.md index aae93f1..e82544e 100644 --- a/deployment-strategies/using-a-userspace-wireguard-implementation.md +++ b/deployment-strategies/using-a-userspace-wireguard-implementation.md @@ -4,7 +4,7 @@ Defguard Gateway supports a userspace WireGuard implementation based on BoringTu Using a userspace WireGuard implementation is useful on platforms where native kernel support is unavailable, limited, or impractical to use. It can also help in environments where running WireGuard entirely in user space better matches the operating model of the platform. -On platforms where native WireGuard support exists, such as Linux or FreeBSD, using the kernel implementation is generally recommended. The kernel implementation usually provides better performance, lower overhead, and behavior that is closer to the standard WireGuard deployment model. +On platforms where native WireGuard support exists, such as Linux or FreeBSD, using the kernel implementation is generally recommended. The kernel implementation usually provides better performance, lower overhead, and behaviour that is closer to the standard WireGuard deployment model. You can enable the userspace implementation in one of the following ways: diff --git a/enterprise/license.md b/enterprise/license.md index 78c58b0..5082f48 100644 --- a/enterprise/license.md +++ b/enterprise/license.md @@ -2,6 +2,26 @@ Defguard is available as an open-source solution with additional paid features. Some functionalities are available only with a valid license or are subject to usage limits, depending on the selected plan. Details about feature availability, limits, and pricing are provided on the [Pricing page](https://defguard.net/pricing/). +### Plans and limits + +Paid features are gated by two plan levels: + +* **Business** - unlocks the paid feature set, for example the REST API, LDAP and Active Directory integration, external OpenID providers, the firewall (ACL), activity log streaming and client behaviour customisation. +* **Enterprise** - everything from Business, plus features intended for larger deployments, such as Service Locations, device posture verification, generating Allowed IPs from firewall rules, and component high availability. + +Every feature page in this documentation states which plans include it, in an **Availability** note at the top. + +{% hint style="info" %} +Enterprise is a **higher** level than Business, so an Enterprise license also unlocks everything that a Business license unlocks. +{% endhint %} + +Your license also carries **usage limits** - the number of users and the number of VPN locations, and optionally device counts. +The current tier, expiry date, and how close you are to each limit are shown in **Settings → License**. + +{% hint style="success" %} +Small deployments can use a **free Business license**: [https://defguard.net/get-free-business/](https://defguard.net/get-free-business/). The exact limits of the free plan are listed on that page and on the [Pricing page](https://defguard.net/pricing/). +{% endhint %} + ### Purchasing the license If you would like to purchase a license, we offer two types of licenses: @@ -43,3 +63,13 @@ To configure Defguard with the received license, please go to **Settings** -> Li The license will be validated and detailed information about the license will be displayed.
+ +### License expiry + +A **subscription** license is renewed automatically, so under normal circumstances you do not need to do anything. If a renewal does not go through - for example because Core temporarily cannot reach our licensing server - the license keeps working for a grace period of **14 days** past its expiry date, which gives you time to resolve the problem without losing access to paid features. + +An **offline** license has no grace period: it stops being valid on its expiry date, because there is no licensing server to renew it against. + +{% hint style="warning" %} +If a license expires past the grace period paid features stop working. Your data, users, devices, and VPN locations are not removed. +{% endhint %} diff --git a/features/activity-log/README.md b/features/activity-log/README.md index c99cd80..353b72d 100644 --- a/features/activity-log/README.md +++ b/features/activity-log/README.md @@ -8,7 +8,7 @@ Activity log is available as a dedicated page in Defguard core Web UI that's use To access it, click the `Activity log` button in the navbar. -
+
### Overview @@ -27,12 +27,17 @@ Each entry in the list contains following fields: Events are grouped into modules based on the part of the system they are related to. -Currently, there are four modules: +Currently, there are following modules: -* **Defguard** - operations performed in the core Web UI (e.g. adding users, modifying devices, managing groups etc.) -* **Client** - actions performed by desktop client applications -* **Enrollment** - events related to the [user enrollment](../../using-defguard-for-end-users/enrollment/) process -* **VPN -** events related to VPN clients (e.g. client connecting to a location) +* **defguard** - operations performed in the core Web UI (e.g. adding users, modifying devices, managing groups etc.) +* **client** - actions performed by desktop client applications +* **enrollment** - events related to the [user enrollment](../../using-defguard-for-end-users/enrollment/) process +* **vpn -** events related to VPN clients (e.g. client connecting to a location) +* **posture** - managing [device posture checks](../device-posture-verification.md) and the result of every evaluation +* **active\_directory** and **ldap** - [LDAP and Active Directory](../ldap-and-active-directory-integration/) synchronization, in both directions +* **oidc\_directory\_sync** - [directory synchronization](../external-openid-providers/#directory-synchronization) with an external OpenID provider + +LDAP synchronization events land in **active\_directory** or **ldap** depending on the `LDAP server is Active Directory` setting. ### Search @@ -49,6 +54,14 @@ The search is case-insensitive and will match partial text. Note that filtering & searching are composable operations, so if you've already applied some filters the search will be performed only among those filtered events. +### Filtering by date + +The `Select range` control next to the `Search` input limits the list to a period of time. Set **Start** and **End**, then click **Apply**; **Reset** clears the range. + +
+ +Both ends of the range are inclusive. Timestamps are compared in UTC. + ## Permissions Access to the Activity log is controlled by user permissions. @@ -61,7 +74,7 @@ Additionally administrators can view events related to all users. At the moment following events are tracked in the Activity log: -* **Defguard** module +* **defguard** module * UserLogin * UserLoginFailed * UserLogout @@ -80,12 +93,15 @@ At the moment following events are tracked in the Activity log: * MfaSecurityKeyAdded * MfaSecurityKeyRemoved * UserAdded + * UserImportBlocked * UserRemoved * UserModified * UserGroupsModified - * UserDeviceAdded - * UserDeviceRemoved - * UserDeviceModified + * UserEnabled + * UserDisabled + * DeviceAdded + * DeviceRemoved + * DeviceModified * NetworkDeviceAdded * NetworkDeviceRemoved * NetworkDeviceModified @@ -107,6 +123,7 @@ At the moment following events are tracked in the Activity log: * SettingsUpdated * SettingsUpdatedPartial * SettingsDefaultBrandingRestored + * EnterpriseSettingsUpdated * GroupsBulkAssigned * GroupAdded * GroupModified @@ -122,23 +139,67 @@ At the moment following events are tracked in the Activity log: * AuthenticationKeyRemoved * AuthenticationKeyRenamed * ClientConfigurationTokenAdded + * EnrollmentTokenAdded * UserSnatBindingAdded * UserSnatBindingRemoved * UserSnatBindingModified -* **Enrollment** module + * GatewayModified + * GatewayDeleted + * GatewayConnected + * GatewayDisconnected + * ProxyModified + * ProxyDeleted + * ProxyConnected + * ProxyDisconnected +* **enrollment** module * EnrollmentStarted * EnrollmentDeviceAdded * EnrollmentCompleted * PasswordResetRequested * PasswordResetStarted * PasswordResetCompleted - * TokenAdded -* **VPN** module - * ConnectedToMfaLocation - * DisconnectedFromMfaLocation - * MfaFailed - * ConnectedToLocation - * DisconnectedFromLocation +* **vpn** module + * VpnClientConnected + * VpnClientDisconnected + * VpnClientMfaConnected + * VpnClientMfaDisconnected + * VpnClientMfaSuccess + * VpnClientMfaFailed + * VpnClientSessionSuperseded + * VpnClientMfaSessionSuperseded +* **posture** module + * DevicePostureCreated + * DevicePostureUpdated + * DevicePostureDeleted + * DevicePostureDuplicated + * DevicePostureLocationsAssigned + * LocationPosturesAssigned + * DevicePostureCheckPassed + * DevicePostureCheckFailed +* **active\_directory** and **ldap** modules + * LdapSyncUserCreated + * LdapSyncUserDeleted + * LdapSyncUserModified + * LdapSyncUserEnabled + * LdapSyncUserDisabled + * LdapSyncGroupCreated + * LdapSyncGroupMemberAdded + * LdapSyncGroupMemberRemoved + * LdapSyncOutboundUserCreated + * LdapSyncOutboundUserDeleted + * LdapSyncOutboundUserModified + * LdapSyncOutboundUserEnabled + * LdapSyncOutboundUserDisabled + * LdapSyncOutboundGroupMemberAdded + * LdapSyncOutboundGroupMemberRemoved +* **oidc\_directory\_sync** module + * OidcDirectorySyncUserCreated + * OidcDirectorySyncUserDeleted + * OidcDirectorySyncUserEnabled + * OidcDirectorySyncUserDisabled + * OidcDirectorySyncGroupCreated + * OidcDirectorySyncGroupMemberAdded + * OidcDirectorySyncGroupMemberRemoved ## Streaming to external SIEM systems diff --git a/features/activity-log/activity-log-streaming/README.md b/features/activity-log/activity-log-streaming/README.md index c165fa0..27cca83 100644 --- a/features/activity-log/activity-log-streaming/README.md +++ b/features/activity-log/activity-log-streaming/README.md @@ -1,7 +1,7 @@ --- description: >- This feature is designed to help teams centralize visibility into user - actions, security events, and system behavior by integrating with tools they + actions, security events, and system behaviour by integrating with tools they already use for monitoring and incident response. --- @@ -10,7 +10,7 @@ description: >- {% hint style="warning" %} **Availability** -This feature is available in all plans, with usage limits. See the [pricing page](https://defguard.net/pricing/) for details. +This feature is available in Business and Enterprise plans. See the [pricing page](https://defguard.net/pricing/) for details. {% endhint %} **Activity Log Streaming** allows you to forward real-time activity logs from your system to external SIEM (Security Information and Event Management) platforms. diff --git a/features/desktop-client-auto-provisioning/README.md b/features/desktop-client-auto-provisioning/README.md index 91be126..22b31fc 100644 --- a/features/desktop-client-auto-provisioning/README.md +++ b/features/desktop-client-auto-provisioning/README.md @@ -54,7 +54,7 @@ These values are analogous to those used in the standard user enrollment process 3. The user follows the standard enrollment process to finish setting up their account 4. Once enrollment is complete, the user can connect to VPN locations and access protected resources 5. If configured, the user receives a welcome email after completing enrollment.\ - This behavior is controlled by the **Send welcome email** option in the **Enrollment** settings page. + This behaviour is controlled by the **Send welcome email** option in the **Enrollment** settings page. ### Enrollment Settings diff --git a/features/desktop-client-auto-provisioning/auto-provisioning-in-windows-environments/entra-id-environments.md b/features/desktop-client-auto-provisioning/auto-provisioning-in-windows-environments/entra-id-environments.md index 4158295..140513e 100644 --- a/features/desktop-client-auto-provisioning/auto-provisioning-in-windows-environments/entra-id-environments.md +++ b/features/desktop-client-auto-provisioning/auto-provisioning-in-windows-environments/entra-id-environments.md @@ -61,12 +61,12 @@ It will present an interactive propmt for selecting a user account. If this fail 3. **Token Generation** * Generate enrollment tokens for users using the [helper script](entra-id-environments.md#generating-enrollment-tokens) 4. **Client Installation** - * Install the `defguard-client` application on user machines using the [MSI installer](../#msi-installer-integration) + * Install the `defguard-client` application on user machines using the [MSI installer](./#msi-installer-integration) * Pass the `PROVISIONING=1` argument to execute provisioning script during installation * Example command: `msiexec /i defguard-client.msi PROVISIONING=1 ADAttribute="description"` 5. **Automatic Configuration** - * During installation, the bundled script fetches [provisioning configuration](../#active-directory-configuration) from Entra ID - * The configuration is written to the client's [data directory](../../../using-defguard-for-end-users/desktop-client/#storage) as explained [here](../#configuration-file-creation) + * During installation, the bundled script fetches [provisioning configuration](./#entra-id-configuration) from Entra ID + * The configuration is written to the client's [data directory](../../../using-defguard-for-end-users/desktop-client/#storage) as explained [here](./#configuration-file-creation) 6. **User Enrollment** * When the user launches the client for the first time, they are guided through the enrollment process * The enrollment uses the pre-configured token and URL from the provisioning file diff --git a/features/desktop-client-auto-provisioning/auto-provisioning-in-windows-environments/on-premise-active-directory-environments.md b/features/desktop-client-auto-provisioning/auto-provisioning-in-windows-environments/on-premise-active-directory-environments.md index bfe9a9a..0f6acdc 100644 --- a/features/desktop-client-auto-provisioning/auto-provisioning-in-windows-environments/on-premise-active-directory-environments.md +++ b/features/desktop-client-auto-provisioning/auto-provisioning-in-windows-environments/on-premise-active-directory-environments.md @@ -53,12 +53,12 @@ Alternatively if you specify a username by the `ADUsername` parameter you'll be 3. **Token Generation** * Generate enrollment tokens for users using the [helper script](on-premise-active-directory-environments.md#generating-enrollment-tokens) 4. **Client Installation** - * Install the `defguard-client` application on user machines using the [MSI installer](../#msi-installer-integration) + * Install the `defguard-client` application on user machines using the [MSI installer](./#msi-installer-integration) * Pass the `PROVISIONING=1` argument to execute provisioning script during installation * Example command: `msiexec /i defguard-client.msi PROVISIONING=1 ADAttribute="description"` 5. **Automatic Configuration** - * During installation, the bundled script fetches [provisioning configuration](../#active-directory-configuration) from Active Directory - * The configuration is written to the client's [data directory](../../../using-defguard-for-end-users/desktop-client/#storage) as explained [here](../#configuration-file-creation) + * During installation, the bundled script fetches [provisioning configuration](./#active-directory-configuration) from Active Directory + * The configuration is written to the client's [data directory](../../../using-defguard-for-end-users/desktop-client/#storage) as explained [here](./#configuration-file-creation) 6. **User Enrollment** * When the user launches the client for the first time, they are guided through the enrollment process * The enrollment uses the pre-configured token and URL from the provisioning file diff --git a/features/device-posture-verification.md b/features/device-posture-verification.md index ae2d572..6ebc144 100644 --- a/features/device-posture-verification.md +++ b/features/device-posture-verification.md @@ -7,11 +7,12 @@ This feature requires an Enterprise plan. See the [pricing page](https://defguar {% endhint %} {% hint style="warning" %} -**Posture verification feature is available starting with Defguard Core v2.1 and Defguard Client v2.1.** +**Posture verification requires Defguard Core 2.1 and a client that supports it:** -Once posture checks are assigned to a location, that location does not appear in Defguard clients older than 2.1. +* **Desktop Client 2.1.0 or newer** on Windows, macOS and Linux +* **Mobile client 1.7.0 or newer** on iOS and Android -Older clients do not support posture verification and cannot access posture-protected locations. +Older clients do not receive the configuration for locations with posture checks assigned, so such a location does not appear in them. See [Desktop Client](../using-defguard-for-end-users/desktop-client/) for what changed in 2.1. {% endhint %} Posture checks let you verify the security state of a user’s device before allowing it to connect to a location. Instead of trusting only the user’s identity, Defguard can also evaluate device requirements such as: @@ -29,7 +30,7 @@ Posture checks let you verify the security state of a user’s device before all * Linux disk encryption status * iOS version * Android version -* Android device integrity status +* Android security patch level age If a posture check fails, the user is shown a list of the unmet requirements: @@ -37,7 +38,7 @@ If a posture check fails, the user is shown a list of the unmet requirements: ## Configuring posture checks -You can view, edit, create, and assign posture checks to locations in the "Posture Checks" section: +You can view, edit, create, and assign posture checks to locations in **Identity & Access → Posture Checks**:
@@ -47,9 +48,13 @@ The section displays a table of all posture checks defined in the system. Clicki ### Creating a new posture check -To create a new posture check, click the “Add new posture check” button above the posture checks table. This launches a wizard that guides you through the configuration step by step. +To create a new posture check, click the "Add new posture check" button above the posture checks table. -In the wizard, you can choose which operating systems the posture check applies to and define the requirements each device must meet. Depending on the selected platform, this can include minimum OS version, security update age, disk encryption, antivirus status, Active Directory membership, or device integrity. You can also set the minimum required Defguard client version and decide whether pre-release client versions are allowed. +#### Step 1: Operating systems + +Click a system to add it to the check. Each system gets its own card, where you set the minimum accepted version and the **Security conditions** available on that platform. + +On Windows and Android you can additionally require the last security update to be no older than 30, 60, 90 or 180 days. {% hint style="warning" %} If you do not configure requirements for a specific operating system, devices running that operating system will not be allowed to connect to locations protected by this posture check. @@ -59,9 +64,31 @@ For example, if a posture check only defines Windows and macOS requirements, Lin
-
+#### Step 2: Defguard client version + +Set the minimum accepted client version, separately for **Desktop** and **Mobile**. + +Enable **Allow users who run pre-release versions of the Defguard client to access the system** if you have users on non-stable builds. + +
+ +#### Step 3: Name and description + +Give the check a name and, optionally, a description. + +
+ +#### Step 4: Summary -Once the rules are configured, the posture check can be saved and [assigned to one or more locations](device-posture-verification.md#assigning-posture-check-to-locations). +Review the conditions the check will enforce, then click **Create posture check**. + +{% hint style="danger" %} +Before the check is created, Defguard asks you to confirm that at least one System Administrator will still meet all the required conditions. If none does, admin access through the protected location can be lost. +{% endhint %} + +
+ +Once the check is saved, [assign it to one or more locations](device-posture-verification.md#assigning-posture-check-to-locations). A check that is not assigned to any location does nothing. ### Editing an existing posture check @@ -73,23 +100,31 @@ To edit one of the existing posture checks, select the "Edit" menu item from the ### Assigning posture check to locations -Posture checks can be assigned to locations in 4 ways: +Posture checks can be assigned to locations in 5 ways: * "Assign to locations" action from the actions menu in the postures table * "Assign to locations" action from the "Actions" menu in the posture details drawer -* [Edit posture form](device-posture-verification.md#editing-an-existing-posture-check) * "Posture Checks" section in the Location edit form +* "Posture check" step of the wizard used when creating a new location
Once a posture check is assigned to a location, every client attempting to connect to that location is verified before access is granted. If multiple posture checks are assigned, the client must satisfy all requirements from all assigned posture checks. The connection is allowed only when every required check passes; if any requirement fails, the client is denied access. +A location cannot have posture checks and be a [service location](service-locations.md) at the same time. + +
+ ### Duplicating a posture check If you want to create a posture check that is similar to an existing one, you can duplicate the existing posture check instead of starting from scratch. This copies its configuration and lets you adjust only the parts that need to be different, saving time and reducing the risk of mistakes. To duplicate a posture check, use the “Duplicate” action from the posture checks table or from the action menu in the posture check details drawer. -
+
The posture check is duplicated and saved immediately, then opened in the edit form. You can modify any settings that should differ from the original and assign the duplicated posture check to the appropriate locations. Duplicated posture checks are not assigned to any locations by default. + +### How checks are evaluated + +Operating system and kernel versions are compared by major version only. A requirement that cannot be evaluated counts as failed. Failed checks are recorded in the [activity log](activity-log/). diff --git a/features/external-openid-providers/README.md b/features/external-openid-providers/README.md index 2eeb823..5684ef8 100644 --- a/features/external-openid-providers/README.md +++ b/features/external-openid-providers/README.md @@ -27,7 +27,7 @@ In order to configure this feature, the following information is needed to be ob * (for custom provider) Your provider's base URL * (for Microsoft as provider) Tenant ID -If you don't know where to find those values, go to the [Examples](./#examples) section, where you will find an example setup for the built-in providers. +If you don't know where to find those values, go to the [Examples](./#configuration-and-setup) section, where you will find an example setup for the built-in providers. ### Base URL @@ -55,7 +55,7 @@ For example, if your Defguard main dashboard is accessible at `https://defguard. * `https://enrollment.my-domain.net/openid/callback` * `https://enrollment.my-domain.net/openid/mfa/callback` -These URIs will need to be provided in your provider's configuration. See [#examples](./#examples "mention") to learn more. +These URIs will need to be provided in your provider's configuration. See [#configuration-and-setup](./#configuration-and-setup "mention") to learn more. ## Configuration and setup @@ -69,22 +69,22 @@ In order to configure the external OpenID provider login, go to the settings in For a configuration guide for given provider, check one of the dedicated articles: -* [Google](google.md#directory-synchronization) +* [Google](google.md) * [Microsoft](microsoft.md) -* [Okta](okta.md#directory-synchronization) -* [JumpCloud](jumpcloud.md#directory-synchronization) +* [Okta](okta.md) +* [JumpCloud](jumpcloud.md) * [Keycloak](keycloak.md) * [Zitadel](zitadel.md) * [Custom](custom.md) ### OpenID enrollment -When you configure your provider, the proxy will automatically allow enrolling users through it. See [with-external-sso-google-microsoft-custom.md](../../using-defguard-for-end-users/enrollment/with-external-sso-google-microsoft-custom.md "mention") for the process from the user's point of view. +When you configure your provider, Edge will automatically allow enrolling users through it. See [with-external-sso-google-microsoft-custom.md](../../using-defguard-for-end-users/enrollment/with-external-sso-google-microsoft-custom.md "mention") for the process from the user's point of view. For this to work, make sure you have the following two things set: -* Additional allowed redirect URI in your provider's configuration (see [#redirect-url](./#redirect-url "mention")) -* A `DEFGUARD_PROXY_URL` environment variable set correctly for your proxy (not core). This variable needs to be set for your proxy and should be equal to the URL where users perform the enrollment process. This should be set automatically if you are using the one-line deployment script version `1.2.1` or above. E.g. if your enrollment URL is `https://enrollment.my-domain.net`, set `DEFGUARD_PROXY_URL` to `https://enrollment.my-domain.net`. +* Additional allowed redirect URI in your provider's configuration (see [#redirect-uri](./#redirect-uri "mention")) +* The public Edge URL set correctly in **Settings → General → Instance settings**. It should be equal to the URL where users perform the enrollment process, for example `https://enrollment.my-domain.net`. #### Disabling automatic account creation @@ -100,19 +100,31 @@ Defguard matches users with external sources by email. In order for users to be If you choose not to enable this option, new users won't be able to automatically go through the enrollment. You will need to create their accounts by hand (with the same email address as the one they have set on your OIDC provider's side) and only then they will have an option to activate it by logging through the provider. -### Directory synchronization +#### Disabling password management -{% hint style="info" %} -This feature is available only in Defguard v1.2.0 and above +Next to the account creation option there is **Disable password management**. Enable it when your provider is the only place where passwords should live: users sourced from it cannot then reset their password through Defguard, and they complete enrollment without setting one. + +
+ +It only affects users who have **no Defguard password at all**. + +{% hint style="warning" %} +Such users can only sign in through the provider. If it becomes unavailable, an administrator has to set a password for them. {% endhint %} +### Directory synchronization + Defguard supports synchronizing users' and groups' states based on the state of the external provider directory. The following things can be synchronized: -* **User Groups**: Automatically create and assign user groups in Defguard to reflect them in Google Workspace. +* **User Groups**: Automatically create and assign user groups in Defguard to reflect the groups in your provider's directory. * **User Deletion**: Removing a user from the provider's directory can also remove them from Defguard. * **User Status**: Disabling users in the provider's directory will disable them in Defguard. -Defguard doesn't automatically create users based on the users in your provider's directory. They will have to manually log in to Defguard through your provider for their Defguard accounts to be created. Defguard is responsible only for synchronizing their later state. +By default, Defguard doesn't create users based on the users in your provider's directory. They will have to manually log in to Defguard through your provider for their Defguard accounts to be created, and Defguard is responsible only for synchronizing their later state. + +{% hint style="info" %} +Microsoft is the exception: enabling the **Import users from your Microsoft directory to Defguard** option creates the directory's users in Defguard during synchronization, without waiting for their first login. See [microsoft.md](microsoft.md "mention") for details. +{% endhint %} After completing first step in wizard, you will have option to configure "**Directory Synchronization**". @@ -127,11 +139,16 @@ The following configuration options are currently available in the directory syn * **Synchronization interval (600s by default):** How often to synchronize with your provider. Very low values may cause issues with the provider API. The user state is also synchronized on login. {% hint style="danger" %} -If you want to delete your users based on the state of your provider we recommend trying out the "disable" behavior first to make sure everything works as expected. Always back up your database regularly. +If you want to delete your users based on the state of your provider we recommend trying out the "disable" behaviour first to make sure everything works as expected. Always back up your database regularly. {% endhint %} * **User behaviour (Keep, Disable, Delete):** What to do with Defguard users who are absent from your provider's directory. * **Admin behaviour (Keep, Disable, Delete):** What to do with Defguard users with admin status (in Defguard) who are absent from your provider's directory. +* **Synchronize users only from specified groups:** Limits synchronization to the members of the listed directory groups, separated by commas. Leave it empty to synchronize everyone. A group name that does not exist in the directory is skipped with a warning in the Core log. + +{% hint style="warning" %} +Microsoft has a second, similar field, **Sync only matching memberships**, which limits which group memberships are mapped rather than which users are synchronized. If you use both, list the same groups in both, otherwise the members of the groups you filtered users by will not be recognised. +{% endhint %} ## Known issues @@ -181,7 +198,7 @@ docker container ls ``` CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -42986c3e772j postgres:15-alpine "docker-entrypoint.s…" 10 days ago Up 5 hours 0.0.0.0:5432->5432/tcp defguard-db-1 +42986c3e772j postgres:18-alpine "docker-entrypoint.s…" 10 days ago Up 5 hours 0.0.0.0:5432->5432/tcp defguard-db-1 c4000t32936a ghcr.io/defguard/defguard:main "./defguard" 4 weeks ago Up 19 minutes 0.0.0.0:8000->8000/tcp, 0.0.0.0:50055->50055/tcp defguard-core-1 ``` diff --git a/features/external-openid-providers/custom.md b/features/external-openid-providers/custom.md index 8717419..2c6b79a 100644 --- a/features/external-openid-providers/custom.md +++ b/features/external-openid-providers/custom.md @@ -6,7 +6,7 @@ Defguard supports custom providers that allow a **code** response type in the Op You can also configure a custom OpenID provider. The key thing here is setting up the **Base URL** correctly. This URL is used to discover all the endpoints required for the authorization flow. -The easiest way of obtaining the Base URL is to find out what is the OpenID `.well-known` URL of your provider. For example, for Google it's `https://accounts.google.com/.well-known/openid-configuration`, in this case, the Base URL would be `https://accounts.google.com` (note the lack of a trailing slash). The part starting with `/.well-known` is added automatically, so it should be omitted from the Base URL. This is explained in more detail in the [Base URL](custom.md#base-url) section. +The easiest way of obtaining the Base URL is to find out what is the OpenID `.well-known` URL of your provider. For example, for Google it's `https://accounts.google.com/.well-known/openid-configuration`, in this case, the Base URL would be `https://accounts.google.com` (note the lack of a trailing slash). The part starting with `/.well-known` is added automatically, so it should be omitted from the Base URL. This is explained in more detail in the [Base URL](./#base-url) section. In order to get the **Client ID** and **Client Secret** values, refer to the documentation of your custom provider of choice. diff --git a/features/external-openid-providers/external-oidc-secure-enrollment.md b/features/external-openid-providers/external-oidc-secure-enrollment.md index 7741eee..d581273 100644 --- a/features/external-openid-providers/external-oidc-secure-enrollment.md +++ b/features/external-openid-providers/external-oidc-secure-enrollment.md @@ -3,11 +3,13 @@ {% hint style="warning" %} **Availability** -This feature is available Business and Enterprise plan. +This feature is available in Business and Enterprise plans. See the [pricing page](https://defguard.net/pricing/) for details. {% endhint %} When [External OIDC is enabled,](./) users have the possibility to [securely enroll (automatically create a Defguard account) and very easily configure their desktop client](../../using-defguard-for-end-users/enrollment/with-external-sso-google-microsoft-custom.md) just by logging in with the SSO provider. +## Step-by-step guide + 1. Go to **Edge** site
@@ -19,3 +21,15 @@ When [External OIDC is enabled,](./) users have the possibility to [securely enr 3. Click "**Sign in with Google**" (in this example) For this to work, see [#openid-enrollment](./#openid-enrollment "mention"). + +## Troubleshooting + +### Sign in with External SSO section not visible after configuring the external SSO + +Make sure the External SSO is configured properly and reachable from the Defguard Core service. + +After clicking the **Launch enrollment** button check the Core service logs. Look for error messages similar to: + +``` +ERROR defguard_proxy_manager::handler: message=Failed to setup external OIDC provider client: Authorization error: Failed to discover provider metadata, make sure the URL is correct: http://example.com/realms/master. Error details: Request failed [2.1.0 Debian 13.0.0 x86_64] +``` diff --git a/features/external-openid-providers/google.md b/features/external-openid-providers/google.md index a3cb5f7..462da8d 100644 --- a/features/external-openid-providers/google.md +++ b/features/external-openid-providers/google.md @@ -38,7 +38,7 @@ Here is [full Google documentation](https://developers.google.com/identity/openi
- Make sure to select "Web application" as the application type. The other thing to note here is the redirect URI. It is the URI to which the user will be redirected from the external provider's authorization. This URI is in the form of `/auth/callback`. Replace `` with the URL under which your dashboard is accessible, e.g., `https://defguard.example.com`. If you'd like to use OpenID enrollment through proxy (and MFA, make sure to enter an additional URIs here in the form of `/openid/callback`, and if you use External MFA please add also: `/openid/mfa/callback` + Make sure to select "Web application" as the application type. The other thing to note here is the redirect URI. It is the URI to which the user will be redirected from the external provider's authorization. This URI is in the form of `/auth/callback`. Replace `` with the URL under which your dashboard is accessible, e.g., `https://defguard.example.com`. If you'd like to use OpenID enrollment through Edge (and MFA, make sure to enter an additional URIs here in the form of `/openid/callback`, and if you use External MFA please add also: `/openid/mfa/callback` 11. After you proceed further, you will be presented with a popup containing your `Client ID` and `Client Secret`, copy them as you will need them in Defguard ## Obtaining Directory Synchronization credentials @@ -96,6 +96,9 @@ This feature is currently technically limited to 10000 members or groups. High u * **Admin email:** The email of the Google Workspace admin user on whose behalf Defguard will call the Google API * **Service Account Key:** JSON file used to authenticate your application with Google APIs using a service account +* **Synchronize users only from specified groups:** Restricts synchronization to the members of the Google Workspace groups you list here, separated by commas. Leave it empty to allow all users. See [#directory-synchronization](./#directory-synchronization "mention") for details. + +
6. Click "**Continue"** diff --git a/features/external-openid-providers/jumpcloud.md b/features/external-openid-providers/jumpcloud.md index 86e1574..32b859a 100644 --- a/features/external-openid-providers/jumpcloud.md +++ b/features/external-openid-providers/jumpcloud.md @@ -32,7 +32,7 @@ If you already have them, please skip to [#configuring-jumpcloud-as-external-oid Make sure to set the correct Redirect URI and Login URL that will reflect your Defguard's setup.\ If you access your Defguard dashboard at e.g., `https://defguard.example.net` your redirect URI will be `https://defguard.example.net/auth/callback` and the login URL `https://defguard.example.net/auth/login`.\ - Additionally, if you are using a Defguard proxy to enroll users, you can also add another redirect URI in the form of `/openid/callback` and `/openid/mfa/callback` if you wish to use the [External MFA feature](../wireguard/multi-factor-authentication-mfa-2fa/#external-mfa) (`` is the address at which your Proxy enrollment page is accessible). + Additionally, if you are using Defguard Edge to enroll users, you can also add another redirect URI in the form of `/openid/callback` and `/openid/mfa/callback` if you wish to use the [External MFA feature](../wireguard/multi-factor-authentication-mfa-2fa/external-sso-based-mfa.md) (`` is the address at which your Edge enrollment page is accessible). 9. Next, select the profile scope and add an `email` user attribute mapping by hand, like so:
diff --git a/features/external-openid-providers/microsoft.md b/features/external-openid-providers/microsoft.md index 7c829a3..27643cd 100644 --- a/features/external-openid-providers/microsoft.md +++ b/features/external-openid-providers/microsoft.md @@ -46,10 +46,6 @@ Make sure the Redirect URL you insert here is correct. The full list of redirect ## Obtaining Directory Synchronization credentials -{% hint style="info" %} -This feature is available only in Defguard 1.2.1 and above -{% endhint %} - {% hint style="warning" %} This feature is currently technically limited to 10000 members or groups. High user or group counts may still trigger your provider API limits even below this threshold. If you have many users (200+), we recommend you test this feature first before you decide to turn on automatic user deletion. {% endhint %} diff --git a/features/external-openid-providers/okta.md b/features/external-openid-providers/okta.md index fe5de56..47a09e7 100644 --- a/features/external-openid-providers/okta.md +++ b/features/external-openid-providers/okta.md @@ -17,7 +17,7 @@ If you already have them, please skip to [#configuring-okta-as-external-oidc-in-
-3. On the next page, configure the application. Make sure to set the correct Sign-in URIs, those will take the form of `/auth/callback` (dashboard login) and `/openid/callback` (if you want to perform new user enrollment using Okta). Replace `` and `` with the URLs of your Defguard dashboard and enrollment page (proxy) accordingly. If you access your Defguard dashboard at e.g., `https://defguard.example.net` your redirect URI will be `https://defguard.example.net/auth/callback`. If you want to use Okta as the MFA provider, also add `/openid/mfa/callback` to the redirect URIs. +3. On the next page, configure the application. Make sure to set the correct Sign-in URIs, those will take the form of `/auth/callback` (dashboard login) and `/openid/callback` (if you want to perform new user enrollment using Okta). Replace `` and `` with the URLs of your Defguard dashboard and enrollment page (Edge) accordingly. If you access your Defguard dashboard at e.g., `https://defguard.example.net` your redirect URI will be `https://defguard.example.net/auth/callback`. If you want to use Okta as the MFA provider, also add `/openid/mfa/callback` to the redirect URIs.
diff --git a/features/external-openid-providers/zitadel.md b/features/external-openid-providers/zitadel.md index 9dbc836..9fd83b6 100644 --- a/features/external-openid-providers/zitadel.md +++ b/features/external-openid-providers/zitadel.md @@ -13,7 +13,7 @@ Refer to [Zitadel's documentation](https://zitadel.com/docs) on how to install i 5. Choose **Code** for authorization method.
-6. Enter a redirect URI for your Defguard instance. The URI is in the form `/auth/callback`, for example `https://defguard.example.com/auth/callback`. (If Defguard has been launched on the _localhost_, select **Development Mode** and enter `http://localhost:8000/auth/callback`). If you'd like to use OpenID enrollment through proxy, make sure to enter an additional URI here in the form of `/openid/callback`. +6. Enter a redirect URI for your Defguard instance. The URI is in the form `/auth/callback`, for example `https://defguard.example.com/auth/callback`. (If Defguard has been launched on the _localhost_, select **Development Mode** and enter `http://localhost:8000/auth/callback`). If you'd like to use OpenID enrollment through Edge, make sure to enter an additional URI here in the form of `/openid/callback`.
7. **Create** the application. diff --git a/features/firewall/README.md b/features/firewall/README.md index 85a78cf..3bea037 100644 --- a/features/firewall/README.md +++ b/features/firewall/README.md @@ -3,14 +3,12 @@ {% hint style="warning" %} **Availability** -This feature requires a Business or Enterprise plan. See the [pricing page](https://defguard.net/pricing/) for details. +This feature is available in Business and Enterprise plans. See the [pricing page](https://defguard.net/pricing/) for details. {% endhint %} {% hint style="warning" %} -Access Control List feature is available starting with Defguard Core v1.3.0 and Defguard Gateway v1.3.0. - -Defguard Gateway v1.3.0+ supports Linux machines with [NFTables](https://nftables.org/).\ -Defguard Gateway v1.4.0+ supports FreeBSD, NetBSD, and macOS machines with Packet Filter (PF). +Defguard Gateway supports Linux machines with [NFTables](https://nftables.org/).\ +On FreeBSD, NetBSD, and macOS machines, Defguard Gateway uses Packet Filter (PF). {% endhint %} {% embed url="https://www.youtube.com/watch?v=Go4C4LWcVS4" %} diff --git a/features/firewall/firewall-internals.md b/features/firewall/firewall-internals.md index e3802ec..dbad5f1 100644 --- a/features/firewall/firewall-internals.md +++ b/features/firewall/firewall-internals.md @@ -102,7 +102,7 @@ As a shortcut, Defguard Gateway offers the `--masquerade` flag (or the `DEFGUARD ``` {% hint style="warning" %} -The `--masquerade` option applies masquerading between **all** interfaces on the gateway, which may be more permissive than necessary in some environments. While convenient, this broad behavior might not align with more restrictive or segmented network designs. For greater control and tighter security, we recommend that administrators configure masquerading manually between only the interfaces that require it. +The `--masquerade` option applies masquerading between **all** interfaces on the gateway, which may be more permissive than necessary in some environments. While convenient, this broad behaviour might not align with more restrictive or segmented network designs. For greater control and tighter security, we recommend that administrators configure masquerading manually between only the interfaces that require it. {% endhint %} #### Forward chain priority @@ -125,7 +125,7 @@ If your hardware or environment is incompatible with Defguard's firewall managem ### Packet Filter (FreeBSD, NetBSD, macOS) {% hint style="info" %} -Defguard Gateway supports Packet Filter (PF) firewall since version 1.4.0. +Defguard Gateway supports the Packet Filter (PF) firewall. {% endhint %} Packet filter (PF) firewall, is a BSD-licensed stateful packet filtering software originally developed for OpenBSD and now ported to other BSD-based systems like FreeBSD, NetBSD, and macOS. diff --git a/features/firewall/troubleshooting.md b/features/firewall/troubleshooting.md index b415441..f43bcfc 100644 --- a/features/firewall/troubleshooting.md +++ b/features/firewall/troubleshooting.md @@ -66,7 +66,7 @@ Additionally, if multiple rules cover overlapping destinations, their combined f ### Connection issues with Docker installed -If you have Docker installed on the same machine as your Gateway (or if you deployed Defguard using the one-line installation script) the firewall may not work properly due to Docker firewall rules interfering with your ACL rules. +If you have Docker installed on the same machine as your Gateway (or if you deployed Defguard using the one-line installation script) the firewall may not work properly due to Docker firewall rules interfering with your ACL rules. To verify this, execute `nft list ruleset` (may require sudo) on the machine on which your Gateway is installed: @@ -84,7 +84,7 @@ table ip filter { If you have a FORWARD chain (managed by Docker) that has a default policy of drop and filter priority, this chain will interfere with Defguard rules (accept policy shouldn't be a problem). -To fix this, set the [Defguard firewall priority](https://docs.defguard.net/features/access-control-list/firewall-internals#forward-chain-priority) to -1. This will make Defguard rules run before Docker rules. +To fix this, set the [Defguard firewall priority](firewall-internals.md#forward-chain-priority) to -1. This will make Defguard rules run before Docker rules. Running `nft list ruleset` on the machine should then result in the following: diff --git a/features/forward-auth.md b/features/forward-auth.md index 95fd3e0..d0a07c6 100644 --- a/features/forward-auth.md +++ b/features/forward-auth.md @@ -7,7 +7,7 @@ In order for forward auth to work the services you are trying to protect must be For example if you are serving your Defguard UI at `id.yourdomain.com`, then your services must use other subdomains of `yourdomain.com`, e.g. ``app1.yourdomain.com, `service.yourdomain.com` etc``. -Additionally you have to update your [Defguard config](../deployment-strategies/configuration.md#auth-cookies-configuration) to set the cookies domain to `yourdomain.com`. +Additionally you have to update your [Defguard config](../deployment-strategies/configuration.md#core-deployment-parameters) to set the cookies domain to `yourdomain.com`. {% endhint %} ## Example configurations diff --git a/features/gateway.md b/features/gateway.md deleted file mode 100644 index a454792..0000000 --- a/features/gateway.md +++ /dev/null @@ -1,72 +0,0 @@ -# OPNSense Configuration - -[OPNsense®](https://opnsense.org/) is an open source, feature rich firewall and routing platform, offering cutting-edge network protection. - -## Installing OPNsense plugin - -To start Defguard Gateway as OPNsense plugin: - -1. On the [release page](https://github.com/DefGuard/gateway/releases) find and download OPNsense package which will be named:\ - `defguard-gateway_VERSION_x86_64-unknown-opnsense.pkg` – this package **includes both Defguard Gateway and OPNsense plugin.** -2. Install the package: - -```sh -pkg add defguard-gateway_VERSION_x86_64-unknown-opnsense.pkg -``` - -3. Refresh OPNsense user interface by running command below: - -```sh -opnsense-patch -``` - -4. In a web-browser, open OPNsense user interface and navigate to **VPN → Defguard Gateway**. - -
- -## Defguard Gateway Configuration - -This instruction helps configure Defguard Gateway in OPNsense. This is based on [WireGuard Road Warrior Setup](https://docs.opnsense.org/manual/how-tos/wireguard-client.html) from OPNsense documentation. - -### Configure Defguard Gateway plugin - -1. Go to **VPN → Defguard Gateway** -2. Fill out the appropriate values in the form. You can read more about the available configuration options here: [#gateway-configuration](../deployment-strategies/configuration.md#gateway-configuration "mention") -3. Eventually, **Start/Restart** the service. - -### Assign a network interface to Defguard - -1. Go to **Interfaces → Assignments** -2. Under **Assign a new interface**, select the Defguard Gateway network interface (e.g. _wg0_) -3. Add a description, for example _ParisOfficeVPN_ -4. Click **Add** - -
Interface Assignments
- -5. Select the newly create interface by clicking on its name (in this example _\[ParisOfficeVPN]_). -6. Select **Enable Interface** -7. Select **Prevent interface removal** -8. Click **Save**, and then **Apply changes** - -### Create an outbound NAT rule - -1. Go to **Firewall → NAT → Outbound** -2. Make sure the selected **Mode** is **Hybrid outbound NAT rule generation**; if it wasn't selected, click **Save** and then **Apply changes** -3. Under **Manual rules**, add a new rule by clicking **+**. -4. Select **Interface** – this should be either WAN or LAN, depending on the needs. -5. Select **TCP/IP version** – either IPv4 or IPv6. -6. Select **Source address** – this should be interface name assigned above plus _net_, e.g. _ParisOfficeVPN net_. -7. Click **Save**, and then **Apply changes** - -
Outbound NAT rule
- -### Add firewall rules to allow WireGuard traffic in - -1. Go to **Firewall → Rules → WAN** -2. Click **+** (plus) to add a new rule -3. The rule should _Pass_ the traffic _in_ with _quick_ option enabled -4. Select **WAN** interface -5. Choose **TCP/IP version** of your desire -6. Select **UDP** protocol. -7. Set **Destination** to **WAN address** and port to the port number provided in Defguard Core: _Location configuration → Gateway port_ -8. Click **Save**, and then **Apply changes** diff --git a/features/integrations/api-tokens.md b/features/integrations/api-tokens.md index 14e8870..4c1b386 100644 --- a/features/integrations/api-tokens.md +++ b/features/integrations/api-tokens.md @@ -3,14 +3,7 @@ {% hint style="warning" %} **Availability** -This feature is available in all plans, with usage limits. See the [pricing page](https://defguard.net/pricing/) for details. -{% endhint %} - -{% hint style="warning" %} -API functionality: - -1. requires Defguard version 1.2.4+ -2. is also **available without enterprise license**, if your instance does not exceed the limits [described here](../../enterprise/license.md#enterprise-is-free-up-to-certain-limits). +This feature is available in Business and Enterprise plans. See the [pricing page](https://defguard.net/pricing/) for details. {% endhint %} ## REST API documentation @@ -25,8 +18,6 @@ Tokens retain the same access permissions as their owner, so be careful when sha ## Generating API token -## Setup - Navigate to an user profile and open **API Tokens** tab, then click **Add new API token**.
diff --git a/features/integrations/webhooks.md b/features/integrations/webhooks.md index 92e30c4..8e80f71 100644 --- a/features/integrations/webhooks.md +++ b/features/integrations/webhooks.md @@ -16,14 +16,14 @@ On the form above, you'll see inputs like URL description token and triggers * **URL** is a URL on which data will be sent after certain triggers * **Description** short description of your webhook to remember its use case -* **Secret token** is a token sent with request in authorization header, **Note** if receiver didn't implement any token check it'll do nothing +* **Secret token** is a token sent with the request in the `Authorization` header, **Note** if receiver didn't implement any token check it'll do nothing * **Triggers** are events which will trigger the webhook ## Sample requests Below is a list of all triggering actions with their request header and sample JSON body which will be sent on URL given at webhook creation. -**Note** all requests are using `GET` method and sends data in body of request in JSON format. +**Note** all requests use the `POST` method and send data in the body of the request in JSON format. The secret token is sent as a bearer token, so the request carries `Authorization: Bearer ` next to the trigger header. ### New user created @@ -37,16 +37,27 @@ Body example: ```json { -"email":"janedoe@email.pl", +"id":5, +"username":"jdoe", "first_name":"jane", "last_name":"doe", +"name":"jane doe", +"email":"janedoe@email.pl", +"phone":"123456789", +"mfa_enabled":false, +"totp_enabled":false, +"email_mfa_enabled":false, +"mfa_method":"None", "groups":[], +"authorized_apps":[], +"devices":[], +"is_active":true, "is_admin":false, -"pgp_cert_id":"", -"pgp_key":"", -"phone":"123456789", -"ssh_key":"", -"username":"jdoe" +"enrolled":false, +"ldap_pass_requires_change":false, +"password_management_disabled":false, +"has_non_mfa_location_access":true, +"has_non_posture_location_access":true } ``` @@ -54,26 +65,35 @@ Body example: Triggered after modifying user -Webhook will be triggered on new user deletion sample request: - Header `X-Defguard-Event: user_modified` -Request body example: +The body has the same shape as for `user_created` and carries the state of the user after the change: ```json { -"email":"janedoe@email.pl", +"id":5, +"username":"jdoe", "first_name":"jane", "last_name":"doe", -"groups":["admin"], -"is_admin":false, -"pgp_cert_id":"", -"pgp_key":"", +"name":"jane doe", +"email":"janedoe@email.pl", "phone":"123456789", -"ssh_key":"", -"username":"jdoe" +"mfa_enabled":true, +"totp_enabled":true, +"email_mfa_enabled":false, +"mfa_method":"OneTimePassword", +"groups":["admin"], +"authorized_apps":[], +"devices":[], +"is_active":true, +"is_admin":true, +"enrolled":true, +"ldap_pass_requires_change":false, +"password_management_disabled":false, +"has_non_mfa_location_access":true, +"has_non_posture_location_access":true } ``` @@ -87,31 +107,28 @@ Header Request body example: -`{ username: "jdoe"}` +```json +{ +"username":"jdoe" +} +``` ### User YubiKey Provision -Triggered after successfully provisioning YubiKey +Triggered after successfully provisioning YubiKey. This is the only trigger with a different body: instead of the full user object it carries the provisioned keys. Header `X-Defguard-Event: user_keys` -request body example: +Request body example: ```json { +"username":"jdoe", "email":"janedoe@email.pl", -"first_name":"jane", -"last_name":"doe", -"groups":["admin"], -"is_admin":false, -"pgp_cert_id":"", -"pgp_key":"", -"phone":"123456789", -"ssh_key":"", -"username":"jdoe" +"ssh_key":"ssh-rsa AAAAB3NzaC1yc2E…", +"pgp_key":"-----BEGIN PGP PUBLIC KEY BLOCK-----…", +"serial":"12345678" } ``` - -**Note** diff --git a/features/ldap-and-active-directory-integration/README.md b/features/ldap-and-active-directory-integration/README.md index e0fc702..9ef94c8 100644 --- a/features/ldap-and-active-directory-integration/README.md +++ b/features/ldap-and-active-directory-integration/README.md @@ -3,7 +3,7 @@ {% hint style="warning" %} **Availability** -This feature is available in all plans, with usage limits. See the [pricing page](https://defguard.net/pricing/) for details. +This feature is available in Business and Enterprise plans. See the [pricing page](https://defguard.net/pricing/) for details. {% endhint %} {% embed url="https://youtu.be/8lf9UIAt9Rw" %} @@ -17,7 +17,7 @@ Depending on your setup, Defguard can be used in two main ways: * as an authentication layer that allows users to sign in with directory-backed credentials, * as a synchronization layer that exchanges user and group data between Defguard and your directory service. -You can start with a simple connection and one-way propagation from Defguard to LDAP, and then move to two-way synchronization if you need Defguard and the external directory to stay aligned over time. This makes it possible to adopt the integration gradually and validate the configuration before enabling more powerful synchronization behavior. +You can start with a simple connection and one-way propagation from Defguard to LDAP, and then move to two-way synchronization if you need Defguard and the external directory to stay aligned over time. This makes it possible to adopt the integration gradually and validate the configuration before enabling more powerful synchronization behaviour. This chapter covers all aspects of LDAP and AD integration, including: diff --git a/features/ldap-and-active-directory-integration/configuration.md b/features/ldap-and-active-directory-integration/configuration.md index 8fc5058..e01fd91 100644 --- a/features/ldap-and-active-directory-integration/configuration.md +++ b/features/ldap-and-active-directory-integration/configuration.md @@ -17,10 +17,6 @@ The LDAP and Active Directory settings in Defguard control how the application: Before you begin, make sure you know your server URL, bind credentials, user and group search bases, username attribute, and whether your environment requires `ldaps` or StartTLS. If you are configuring Active Directory and expect Defguard to create users or set passwords, verify that encrypted LDAP communication is available. -{% hint style="warning" %} -Active Directory support is available since Defguard version 1.3.0. -{% endhint %} - {% hint style="warning" %} If you are using the integration across multiple nested organizational units, please read the [Multiple Nested OUs](configuration.md#multiple-nested-ous) section. {% endhint %} @@ -40,7 +36,7 @@ This section defines how Defguard connects to your LDAP server and authenticates
LDAP Connection settings
* **Use StartTLS**: Enable this option for an encrypted connection to LDAP. StartTLS is an LDAP extended operation that begins with an unencrypted TCP connection on port 389, then sends a StartTLS request to initiate a TLS handshake without changing ports. -* **LDAP server is Active Directory**: Enable this option for an Active Directory server. Active Directory (AD) is Microsoft’s directory service for managing users, computers, and resources in Windows networks. See [#example-active-directory-configuration](configuration.md#example-active-directory-configuration "mention") for a working example. +* **LDAP server is Active Directory**: Enable this option for an Active Directory server. Active Directory (AD) is Microsoft’s directory service for managing users, computers, and resources in Windows networks. See [#example-active-directory-configuration](examples.md#example-active-directory-configuration "mention") for a working example. * **Verify TLS certificate**: Enable this option to validate the TLS certificate. For custom self-signed certificates, it may be reasonable to leave this option disabled. * **URL**: The LDAP server's URL. Use the `ldap:` schema for unencrypted connections or connections with StartTLS (this defaults to TCP port 389), or the `ldaps:` schema for SSL-encrypted connections (this defaults to TCP port 636). * **Bind username** and **Bind password**: These refer to the credentials used in an LDAP "bind" operation to authenticate a client to the directory server. The username field should contain a Distinguished Name (DN) for a service account that is able to manage LDAP entries. @@ -111,9 +107,7 @@ After enabling the LDAP integration, users will be able to log in to Defguard th ### Multiple nested OUs -Multiple nested organizational units are supported in Defguard 1.4.0 and above. - -If you are using an older version of Defguard, using the integration with multiple nested organizational units may lead to unexpected behavior. The following issues are known to occur: +If you are using an older version of Defguard, using the integration with multiple nested organizational units may lead to unexpected behaviour. The following issues are known to occur: * If you have duplicate user RDNs across multiple OUs, a database error may occur: `Duplicate key violates unique constraint 'unique_ldap_rdn'`, causing issues with two-way synchronization. This would happen in the following scenario: * `CN=user1,OU=ou1,OU=ou,DC=example` diff --git a/features/ldap-and-active-directory-integration/examples.md b/features/ldap-and-active-directory-integration/examples.md index 0a472f2..e2563ee 100644 --- a/features/ldap-and-active-directory-integration/examples.md +++ b/features/ldap-and-active-directory-integration/examples.md @@ -70,4 +70,4 @@ Use this example if your deployment is based on a more traditional LDAP schema a * Group member attribute: `uniqueMember` * Group search base: for example `cn=groups,dc=ldap,dc=server,dc=name` -After applying either example, save the settings and use the connection test in Defguard before enabling synchronization. A successful connection test confirms that Defguard can reach the directory and authenticate with the bind account, but you should still verify that user lookup, group lookup, and any intended synchronization behavior work as expected. +After applying either example, save the settings and use the connection test in Defguard before enabling synchronization. A successful connection test confirms that Defguard can reach the directory and authenticate with the bind account, but you should still verify that user lookup, group lookup, and any intended synchronization behaviour work as expected. diff --git a/features/ldap-and-active-directory-integration/settings-table.md b/features/ldap-and-active-directory-integration/settings-table.md index 646a8b7..7e7c76b 100644 --- a/features/ldap-and-active-directory-integration/settings-table.md +++ b/features/ldap-and-active-directory-integration/settings-table.md @@ -24,6 +24,9 @@ Ensure that the letter casing in your Defguard settings matches exactly with you | Group Search Base | Relative Distinguished Name (RDN) of your group entries. | ou=groups,dc=example,dc=org | | User RDN attribute | The attribute that is part of the user's DN (the leftmost component of the DN). | Empty, defaults to the username attribute | | Limit synchronization to these groups | Limits all LDAP actions only to users belonging to one of the specified groups, both ways. Values should be provided as a list separated by commas. | Empty | +| Disable password management | When enabled, users sourced from LDAP without a local password cannot change or reset their password through Defguard. See below. | Disabled | +| Synchronize account disabled status | Keeps the enabled/disabled state of an account in sync with Active Directory. Active Directory only. See below. | Disabled | +| Synchronization interval (sec) | How often Defguard pulls changes from the directory when two-way synchronization is enabled. | 300 | ## Settings in depth @@ -51,3 +54,5 @@ To use this feature, your LDAP user entries must possess the `memberOf` attribut * Changes in Defguard will be propagated to LDAP only if a user belongs to a given group in Defguard. * If the two-way synchronization is enabled, only the users belonging to the specified groups will be fetched from the LDAP server. * Adding a user to one of the synchronization groups in Defguard will automatically create that user in LDAP if they do not exist yet. If they already exist, their LDAP data, e.g. the email address, will be overwritten with the data from Defguard if only one-way synchronization (Defguard → LDAP) is enabled. Otherwise, if two-way synchronization is enabled, the selected authority source will be respected. +* `Disable password management`: Users sourced from LDAP cannot reset their password through Defguard and complete enrollment without setting one. Only affects users who have **no Defguard password**; administrators are never affected. External identity providers have an [equivalent option](../external-openid-providers/#disabling-password-management). +* `Synchronize account disabled status`: Maps the Active Directory `userAccountControl` flag onto the Defguard account state, in both directions. This option requires `LDAP server is Active Directory` to be enabled; on a plain LDAP server it has no effect. **With this option disabled, disabling a user in Defguard deletes their LDAP entry instead of flagging the account as disabled.** diff --git a/features/ldap-and-active-directory-integration/two-way-ldap-and-active-directory-synchronization.md b/features/ldap-and-active-directory-integration/two-way-ldap-and-active-directory-synchronization.md index 5744586..8b0297b 100644 --- a/features/ldap-and-active-directory-integration/two-way-ldap-and-active-directory-synchronization.md +++ b/features/ldap-and-active-directory-integration/two-way-ldap-and-active-directory-synchronization.md @@ -3,11 +3,7 @@ {% hint style="warning" %} **Availability** -This feature is available in all plans, with usage limits. See the [pricing page](https://defguard.net/pricing/) for details. -{% endhint %} - -{% hint style="warning" %} -This feature is available since Defguard version 1.3.0. +This feature is available in Business and Enterprise plans. See the [pricing page](https://defguard.net/pricing/) for details. {% endhint %} {% hint style="danger" %} @@ -146,7 +142,7 @@ Because some LDAP implementations require a password when a user is created, Def Defguard does not pull passwords from LDAP in any form. Instead, when a user tries to log in to Defguard and LDAP integration is enabled, a test login attempt is made against the LDAP server using the provided credentials. If the test login attempt succeeds, Defguard authenticates the user just as it would during a regular login. -## Known issues and other unexpected behavior +## Known issues and other unexpected behaviour ### General diff --git a/features/managing-defguard-via-cli.md b/features/managing-defguard-via-cli.md index 43cebbf..efab615 100644 --- a/features/managing-defguard-via-cli.md +++ b/features/managing-defguard-via-cli.md @@ -77,7 +77,7 @@ john | false peter | false ``` -### Check which group is admin +### Check which group is admin ```bash defguard manage list-groups diff --git a/features/notifications/gateway-notifications.md b/features/notifications/gateway-notifications.md index 5d1521b..af5c579 100644 --- a/features/notifications/gateway-notifications.md +++ b/features/notifications/gateway-notifications.md @@ -8,7 +8,7 @@ You can configure automatic e-mail notifications when one of your gateways disco ### Configuration -In order to configure the notifications, navigate **Settings → Notifications → Gateway notifications .** +In order to configure the notifications, navigate to **Settings → Notifications → Gateway notifications**.
@@ -16,4 +16,4 @@ The configuration options are as follows: * **Enable gateway disconnect notifications** - whether the notifications should be enabled * **Gateway inactivity time** - the time for which the gateway needs to stay disconnected in order to trigger the notification -* **Enable gateway reconnect notifications** - whether to send the notification when the gateway connects again after +* **Enable gateway reconnect notifications** - whether to send the notification when the gateway connects again after being disconnected diff --git a/features/notifications/setting-up-smtp-for-email-notifications.md b/features/notifications/setting-up-smtp-for-email-notifications.md index 24c9d48..230ad8f 100644 --- a/features/notifications/setting-up-smtp-for-email-notifications.md +++ b/features/notifications/setting-up-smtp-for-email-notifications.md @@ -1,9 +1,139 @@ # Email notifications -In **Settings → Notifications → SMTP Configuration** you can setup a connection to an SMTP server. +Defguard Core can send email notifications to users and admins for security events, enrollment flows, and account activity. For this feature to work, you must configure a connection to an SMTP (Simple Mail Transfer Protocol) server. + +## Notification kinds + +* **Welcome message after enrollment**: welcome message sent to the user after completing enrollment and activating the account +* **Support data**: diagnostic data sent manually by an admin to Defguard support +* **Desktop client configuration**: configuration link sent when an admin starts desktop client configuration for a user +* **User enrollment**: enrollment link and token sent to user when admin triggers it in Defguard +* **New device added to your account**: notification sent when a new device is added to the user's account +* **New device logged in to your account**: notification sent when logging in from a new, unrecognized device/browser +* **New login to OIDC application**: notification sent on the first login to an OpenID application +* **Multi-Factor Authentication activation**: activation code sent when the user starts email MFA configuration +* **Multi-Factor Authentication {method} has been activated**: confirmation that an MFA method has been activated +* **Multi-Factor Authentication code for login**: MFA code sent on request during login +* **Password reset**: password reset link sent when an admin initiates a reset or the user [requests one in Edge](../../using-defguard-for-end-users/changing-your-password.md) +* **Password reset success**: confirmation sent after a successful password reset +* **Password reset disabled**: sent when a reset was requested for an account that cannot use it, for example a user with [password management disabled](../external-openid-providers/#disabling-password-management) +* **User import blocked**: alert to admins when user import from LDAP/directory is blocked +* **User enrollment completed**: notification to an admin when a user completes enrollment +* **Gateway disconnected** and **Gateway reconnected**: alerts to admins about gateway connectivity, configured separately in [Gateway notifications](gateway-notifications.md) +* **Automatic Let's Encrypt certificate refresh failed**: alert to admins when the automatic Let's Encrypt certificate renewal fails +* **Certificate expiration**: warning to admins when a custom-uploaded HTTPS/TLS certificate (Core or Edge) is approaching expiration +* **Certificate has expired**: alert to admins when a custom-uploaded HTTPS/TLS certificate (Core or Edge) has already expired + +## Configuration + +To configure a connection to an SMTP server, go to **Settings → Notifications → SMTP Configuration**.
-This enables your Defguard instance to send **email notifications** to users and admins. +Then, select one of the configuration methods by clicking **Configure** on the right side of a panel: + +
+ +* **No Authentication**: use this option for an SMTP server that doesn't require any authentication. Usually, this kind of server is protected with firewall rules and is not accessible outside an internal network. +* **Username and password**: use this option for SMTP servers that require credentials to authenticate. +* **Google**: use this option to send email notifications through Gmail; it requires OAuth2 authentication. +* **Microsoft**: use this option to send email notifications through Microsoft 365 Exchange; it requires OAuth2 authentication. + +{% hint style="warning" %} +**Availability** + +The Google and Microsoft methods are available in Business and Enterprise plans. See the [pricing page](https://defguard.net/pricing/) for details. +{% endhint %} + +Only one method can be active at a time, so configuring a new one replaces the currently active configuration and Defguard asks you to confirm that. The active method is listed under **Active SMTP configuration** and marked **Applied**, the remaining ones under **Other configuration methods**. + +Below is the detailed information on how to configure each of the methods. + +### No Authentication + +This option requires the following: + +* **Server Address**: IP address or domain name of the SMTP server. +* **Server port**: port number of the SMTP server. Common values are `587` (message submission), `465` (message submission over TLS), or `25` (SMTP relay). +* **Sender email address**: email address that will appear as the sender. +* **Encryption**: choose from _None_, _Start TLS_, or _Implicit TLS_. Use _Implicit TLS_ (port `465`) or _Start TLS_ (port `587`) whenever your server supports it; plain _None_ should only be used on trusted internal networks. +* **Verify TLS certificate**: leave it enabled unless your server uses a self-signed certificate. + +Click **Submit** to confirm the settings. + +### Username and password + +This option requires the following: + +* **Server Address**: IP address or domain name of the SMTP server. +* **Server port**: port number of the SMTP server. Common values are `587` (message submission), `465` (message submission over TLS), or `25` (SMTP relay). +* **Sender email address**: email address that will appear as the sender. +* **Encryption**: choose from _None_, _Start TLS_, or _Implicit TLS_. +* **Verify TLS certificate**: leave it enabled unless your server uses a self-signed certificate. +* **Server username**: username used to authenticate with the SMTP server. +* **Server password**: password used to authenticate with the SMTP server. + +{% hint style="info" %} +If your mail provider uses two-factor authentication (e.g. a personal Gmail account), you may need to generate an app-specific password instead of using your regular account password. +{% endhint %} + +Click **Submit** to confirm the settings. + +### Google + +This option uses OAuth2 to send email through Gmail. Defguard sets the server address, port and encryption itself, so you only provide the sender address and the OAuth2 credentials. + +Before configuring it in Defguard, you need to create OAuth2 credentials in the Google Cloud Console: + +1. Go to [Google Cloud Console](https://console.cloud.google.com/) and open or create a project. +2. Navigate to **APIs & Services → OAuth consent screen** and configure the consent screen for your organisation. +3. Go to **APIs & Services → Credentials** and click **Create credentials → OAuth client ID**. +4. Select **Web application** as the application type, and give it a **Name**. +5. Add the Defguard callback URL, in the form of `https://mydefguard/smtp-oauth-callback`, to **Authorized redirect URIs**. +6. Click **Create** and copy the generated **Client ID** and **Client secret**. +7. Publish app **APIs & Services → OAuth consent screen → Audience → Publish app** + +
+ +Then fill in the following fields in Defguard: + +* **Sender email address**: Gmail address that will be used to send notifications. +* **Client ID**: the OAuth2 Client ID obtained from Google Cloud Console. +* **Client Secret**: the OAuth2 Client secret obtained from Google Cloud Console. + +Click **Submit** to confirm the settings. A pop-up window will appear asking you to sign in to your Google account and grant Defguard permission to send email on your behalf, so make sure your browser does not block pop-ups for the Defguard dashboard. + +### Microsoft + +This option uses OAuth2 to send email through Microsoft 365 Exchange. As with Google, Defguard sets the server address, port and encryption itself. + +Defguard authenticates as the application, not as a signed-in user, which is why the app registration needs an application permission and admin consent. Before configuring it in Defguard, register an application in Azure Active Directory: + +1. Go to [Entra portal](https://entra.microsoft.com/) and navigate to **Entra ID → App registrations**. +2. Click **New registration**, give the app a name, and click **Register**. +3. After registration, note the **Application (client) ID** and **Directory (tenant) ID** shown on the overview page. +4. Go to **Entra ID → App registrations → Certificates & secrets**, select **Client secrets** tab, and click **New client secret**. Copy the generated secret value immediately, it will not be shown again. +5. Go to **Entra ID → App registrations → API permissions**, select the new app, and add the **SMTP.SendAsApp** permission under **Office 365 Exchange Online**. +6. Go to **Entra ID → Enterprise apps**, select the new app, and then go to **Permissions**. Click on **grant admin consent for…**. + +Then fill in the following fields in Defguard: + +* **Sender email address**: Microsoft 365 email address that will be used to send notifications. +* **Tenant ID**: the Directory (tenant) ID of your Azure AD. +* **Client ID**: the Application (client) ID of the registered app. +* **Client Secret**: the client secret value generated in Azure AD. + +Click **Submit** to confirm the settings. + +## Testing + +After saving the configuration, you can verify it works by sending a test email. Click **...** next to the active configuration to expand the menu, then select **Send test email**. In the dialog that appears, enter the recipient's email address and click **Send email**. The same menu holds **Reset settings**, which clears the SMTP configuration and disables all email notifications. + +If the test email does not arrive, check the following: -After you fill in all the relevant fields you can use the **Send test email** form at the bottom to test if your configuration is correct. +* **Server address and port**: confirm the host is reachable from the machine running Defguard Core and that the port is not blocked by a firewall. +* **Encryption mismatch**: make sure the port and the encryption mode are consistent, for example port `465` requires _Implicit TLS_, while port `587` is used with _Start TLS_. Mixing these will cause the connection to fail or produce a TLS handshake error. +* **Credentials**: for the _Username and password_ method, double-check the username and password. If your provider requires an app-specific password, make sure you are using that instead of your regular account password. +* **OAuth2 token**: for the _Google_ and _Microsoft_ methods, the OAuth2 token may have expired or been revoked. Re-open the configuration panel and go through the authentication flow again to obtain a fresh token. +* **Spam folder**: the test email may have been delivered but filtered into the spam or junk folder. +* **Defguard Core logs**: check the application logs for SMTP-related error messages, which will give the most precise indication of what went wrong. diff --git a/features/openid-connect/README.md b/features/openid-connect/README.md index e3558df..6fd9d8f 100644 --- a/features/openid-connect/README.md +++ b/features/openid-connect/README.md @@ -111,7 +111,7 @@ client_id= // Generated by Defguard available on app detail page 1. `Client ID` and `Client Secret` are generated by Defguard after creating your app. 2. **Scope** must include `OpenID` -3. Available scopes are `Profile` (all available info from user profile) `Phone` and `Email` +3. Available scopes are `Profile` (all available info from user profile), `Phone`, `Email` and `Groups`. The `Groups` scope adds a `groups` claim with the names of the user's Defguard groups to the ID token, which applications can use to map roles. 4. Currently, only supported **response\_type** is **code**. 5. Redirect URI is URL to which the user will be redirected with and authorization code. It must exactly match the redirect URL registered during client creation, otherwise error will be returned. diff --git a/features/openid-connect/proxmox-1.md b/features/openid-connect/proxmox-1.md index 1997aef..26d3a7f 100644 --- a/features/openid-connect/proxmox-1.md +++ b/features/openid-connect/proxmox-1.md @@ -5,7 +5,7 @@ hidden: true # Matrix / Synapse {% hint style="warning" %} -For Synapse OIDC to work you'll have to run Defguard with [RSA signing key](../../deployment-strategies/docker-compose.md#openid-rsa-setup). +For Synapse OIDC to work you'll have to run Defguard with [RSA signing key](../../deployment-strategies/configuration.md#deprecated-core-deployment-parameters). {% endhint %} ## Add Synapse app to Defguard diff --git a/features/openid-connect/proxmox.md b/features/openid-connect/proxmox.md index 6df5b10..1cb863d 100644 --- a/features/openid-connect/proxmox.md +++ b/features/openid-connect/proxmox.md @@ -5,7 +5,7 @@ hidden: true # Proxmox {% hint style="warning" %} -For Proxmox OIDC to work you'll have to run Defguard with [RSA signing key](../../deployment-strategies/docker-compose.md#openid-rsa-setup). +For Proxmox OIDC to work you'll have to run Defguard with [RSA signing key](../../deployment-strategies/configuration.md#deprecated-core-deployment-parameters). {% endhint %} ## Add Proxmox app to Defguard diff --git a/features/remote-user-enrollment/README.md b/features/remote-user-enrollment/README.md index 149e119..92b5e4d 100644 --- a/features/remote-user-enrollment/README.md +++ b/features/remote-user-enrollment/README.md @@ -16,7 +16,7 @@ To avoid this issue you can deploy a **public** [Defguard Edge](https://github.c {% hint style="info" %} Edge is included when using the default [deployment instructions](../../deployment-strategies/overview.md). -Please also see the relevant configuration options for [core](../../deployment-strategies/configuration.md#enrollment-configuration) and the [edge itself](../../deployment-strategies/configuration.md#enrollment-service). +Please also see the relevant configuration options for [core](../../deployment-strategies/configuration.md#settings) and the [edge itself](../../deployment-strategies/configuration.md#edge-deployment-parameters). {% endhint %} ## How to initiate user secure enrollment diff --git a/features/remote-user-enrollment/automatic-real-time-desktop-client-configuration.md b/features/remote-user-enrollment/automatic-real-time-desktop-client-configuration.md index 6ad7f07..1a36eed 100644 --- a/features/remote-user-enrollment/automatic-real-time-desktop-client-configuration.md +++ b/features/remote-user-enrollment/automatic-real-time-desktop-client-configuration.md @@ -3,7 +3,7 @@ {% hint style="warning" %} **Availability** -This feature is available in all plans, with usage limits. See the [pricing page](https://defguard.net/pricing/) for details. +This feature is available in Business and Enterprise plans. See the [pricing page](https://defguard.net/pricing/) for details. {% endhint %} When initially configuring Defguard desktop client, all available locations for the user (with all location settings) are automatically configured (which is one of Defguard's unique functionalities). @@ -13,7 +13,7 @@ In the course of time: new locations can be added by administrators, existing on In order to reconfigure a user's desktop client, the administrator has two possibilities: 1. If using the **Open Source Open Core** - the administrator needs to send a new configuration token to each user affected, and the user needs to [update the instance](../../using-defguard-for-end-users/desktop-client/instance-configuration.md#updating-instance) in the desktop client with the new obtained token. -2. Obtain the **Enterprise License**, then each user desktop client (and all Locations) are **reconfigured automatically in real time** (propagation takes around 30 seconds to 1 minute) whenever any VPN Location is reconfigured or the user is assigned to a different group. +2. Obtain a **Business or Enterprise** license, then each user desktop client (and all Locations) are **reconfigured automatically in real time** (propagation takes around 30 seconds to 1 minute) whenever any VPN Location is reconfigured or the user is assigned to a different group. {% hint style="warning" %} If you have been using Defguard prior to version 1.0.0, upgraded and have Enterprise License, to take advantage of the real-time config sync on an already configured desktop client, [please refer to Upgrade notes documentation.](../../deployment-strategies/upgrading.md#desktop-client-real-time-sync) diff --git a/features/service-locations.md b/features/service-locations.md index ace066f..9791fc7 100644 --- a/features/service-locations.md +++ b/features/service-locations.md @@ -7,14 +7,16 @@ This feature is available in Enterprise plan. See the [pricing page](https://def {% endhint %} {% hint style="warning" %} -Service locations are currently only supported with Defguard Client for Windows. +Service locations are currently supported with Defguard Client for Windows and Linux. Windows supports both modes described below; Linux supports **Always on** only. {% endhint %} Service locations are a special kind of locations that allow establishing automatic VPN connections on system boot. +They are not operated by the user: a service location **never appears in the Defguard Client's location list**, and there is nothing for the user to connect to or disconnect from. The connection is established and maintained by a background service that runs independently of the Client, so an **Always on** location stays connected even when the Defguard Client has never been started or has been closed. + There are currently two modes of service locations: -* **Pre-logon**: the VPN connection to the location is established on system boot and is terminated when the user completes login to their system account. This may be used when your users need to authorize with some external identity provider (for example Active Directory) in order to successfully login and later don't require constant access to the VPN location. +* **Pre-logon** (Windows only): the VPN connection to the location is established on system boot and is terminated when the user completes login to their system account. This may be used when your users need to authorize with some external identity provider (for example Active Directory) in order to successfully login and later don't require constant access to the VPN location. * **Always on**: the VPN connection to the location is established on system boot and is never terminated, unless: * The network configuration of this location is changed (connection is re-established, to apply new changes) @@ -29,7 +31,7 @@ There are currently two modes of service locations:
-2. Select "**Service location (Windows only)**" +2. Select "**Service location (Windows, Linux)**"
@@ -50,30 +52,34 @@ If you want to edit your service location, click "**…**" and select "**Edit"**
-Scroll down, you will see "**Location type (Windows only)**" section +Scroll down, you will see the "**Location type**" section
Here you can change service location mode, and confirm with "**Save changes**" button. {% hint style="warning" %} -If your location is MFA protected, you won't be able to set is as a service location. The location must have MFA disabled in order to use service location mode. +A location cannot be set as a service location if it is MFA protected or has posture checks assigned. Disable MFA and remove the posture checks from the location first. {% endhint %} -After the configuration of the Defguard client is updated for your instance, the location will be hidden in the client's UI. The connection to the location will be established in the background without any user input. +After the configuration of the Defguard Client is updated for your instance, the location disappears from the Client's UI and stays hidden for as long as it is a service location. The connection is established in the background without any user input. ## Network configuration updates If you have enterprise features enabled, the Defguard Client periodically updates its network configuration if it's changed in Defguard Core. This also applies to service locations, but in order for the configuration update to happen for a service location, the Defguard Client must be open. This means that the configuration won't be updated when the user hasn't logged in yet, since the Client is not running at that point. In other words, **the user must first log in and start the Client for a configuration update to automatically happen**. +This applies to configuration updates only. The connection itself does not depend on the Client running - see the section below. + ## Service location connection management in depth {% hint style="info" %} -This section describes the current behavior of the Defguard Client on Windows. +This section describes the current behaviour of the Defguard Client on Windows. {% endhint %} Service locations are managed by a background service (`defguard-service`) responsible for managing VPN connections. The background service is running independently from the Desktop Client and is always active. The service is responsible for establishing the connection on system boot and terminating/restarting it under specific circumstances (e.g. when user logs in if using the pre-logon mode). +Because the connection belongs to the background service and not to the Desktop Client, it is neither visible nor controllable in the Client's UI, and closing or never opening the Client does not bring it down. + ### Pre-logon If you selected the pre-logon mode, the connection will be established on system boot. If the service detects a login event, the connection will be terminated. @@ -84,7 +90,7 @@ After login, the connection won't be established unless a system logoff event is If you selected the always-on mode, the connection will be established on system boot. -The connection won't be terminated or restarted unless the Desktop Client receives a network update or is uninstalled. +The connection won't be terminated or restarted unless the Desktop Client receives a network update or is uninstalled. It stays up across user logins and logoffs, and while the Desktop Client is closed. ## Troubleshooting diff --git a/features/user-management.md b/features/user-management.md new file mode 100644 index 0000000..72cd5ba --- /dev/null +++ b/features/user-management.md @@ -0,0 +1,33 @@ +# User management + +The **Users** page lists every account in your Defguard instance. Individual accounts are managed from the menu at the end of each row; this page covers the tools that act on the whole list. + +## Filtering by group + +The filter on the **Groups** column lists every group you have defined, plus an extra **No groups** entry matching accounts that belong to no group at all. + +
+ +Selecting several groups returns users who are in **any** of them, and adding **No groups** widens the result rather than narrowing it. + +## Bulk actions + +Select accounts with the checkboxes in the rows, then use the **Bulk actions** menu: + +* **Assign to a group** +* **Start self-enrollment** - begins [enrollment](remote-user-enrollment/) and sends each user an enrollment email +* **Disable** +* **Enable** +* **Delete** + +
+ +Each action asks for confirmation and states how many accounts it will affect. + +{% hint style="warning" %} +**Start self-enrollment** requires [SMTP to be configured](notifications/setting-up-smtp-for-email-notifications.md). +{% endhint %} + +{% hint style="danger" %} +Deleting accounts cannot be undone. +{% endhint %} diff --git a/features/user-snat-bindings.md b/features/user-snat-bindings.md index f89eb4d..8c9f21a 100644 --- a/features/user-snat-bindings.md +++ b/features/user-snat-bindings.md @@ -3,11 +3,7 @@ {% hint style="warning" %} **Availability** -This feature is available in all plans, with usage limits. See the [pricing page](https://defguard.net/pricing/) for details. -{% endhint %} - -{% hint style="info" %} -This feature is available starting from version 1.5 +This feature is available in Business and Enterprise plans. See the [pricing page](https://defguard.net/pricing/) for details. {% endhint %} **User SNAT bindings** allow administrators to assign specific public IP addresses to users for outbound traffic from Defguard VPN gateways in a given location. This provides fine-grained control over how user traffic appears to external networks. diff --git a/features/wireguard/behavior-customization.md b/features/wireguard/behavior-customization.md index 4f282a0..e890acc 100644 --- a/features/wireguard/behavior-customization.md +++ b/features/wireguard/behavior-customization.md @@ -3,10 +3,10 @@ {% hint style="warning" %} **Availability** -This feature is available from Business license. See the [pricing page](https://defguard.net/pricing/) for details. +This feature is available in Business and Enterprise plans. See the [pricing page](https://defguard.net/pricing/) for details. {% endhint %} -Navigate to **Settings → Client behaviour.** +Navigate to **Settings → General → Client behaviour.**
@@ -32,17 +32,33 @@ One of the unique features of Defguard desktop client is the ability for users t
-However, in some cases administrators may want to enforce a specific behavior - allowing access only to predefined traffic or requiring all traffic to pass through the VPN. +However, in some cases administrators may want to enforce a specific behaviour - allowing access only to predefined traffic or requiring all traffic to pass through the VPN.
\ -The **Client Traffic Policy** setting enables administrators to control this behavior as needed. The available options are: +The **Client Traffic Policy** setting enables administrators to control this behaviour as needed. The available options are: -* **None** - Users can freely choose between routing predefined traffic or all traffic through the VPN. +* **No limitation** - Users can freely choose between routing predefined traffic or all traffic through the VPN. * **Disable all traffic** - Only predefined traffic is allowed, the "All traffic" option is disabled for users. * **Force all traffic** - All traffic is routed through the VPN, the "All traffic" option is enforced and cannot be changed by users. {% hint style="warning" %} Please note that this option is only client-side enforced, meaning the user may manually modify Wireguard interface to force all traffic to go through the VPN. {% endhint %} + +### Group-based policies + +In addition to the global **Client traffic policy**, you can define traffic rules for selected groups. Groups listed in this section use their own traffic rules instead of the global policy; any group that is not listed uses the global policy. + +The available options are the same as for the global policy - **No limitations**, **Disable all traffic** and **Force all traffic** - but they apply only to users in the selected groups. Use the **Edit groups** button next to an option to choose which groups it applies to. + +
+ +A group can be assigned to only one option. The **Groups** page shows the assigned policy in the **Traffic policy** column, or `-` when the group follows the global policy. + +{% hint style="info" %} +Group-based policies are useful when most of your users should keep the default behaviour, while a specific group - for example contractors or a set of managed workstations - must have all traffic forced through the VPN. +{% endhint %} + +When a user belongs to several groups with different policies, **Disable all traffic** wins, then **Force all traffic**, then **No limitations**. diff --git a/features/wireguard/create-your-vpn-network/README.md b/features/wireguard/create-your-vpn-network/README.md index 78af262..1daf0d3 100644 --- a/features/wireguard/create-your-vpn-network/README.md +++ b/features/wireguard/create-your-vpn-network/README.md @@ -1,6 +1,6 @@ # Create/Manage VPN Location -A VPN location is a VPN network to which users can connect to. Every location has a [dedicated gateway](/broken/pages/1KLINb5EeNCxbdWVydt1) (or [multiple gateways if you deploy a high-availability solution](../../../deployment-strategies/high-availability-and-failover/#gateway-high-availability)). +A VPN location is a VPN network to which users can connect to. Every location has a [dedicated gateway](../../../deployment-strategies/standalone-package-based-installation/gateway.md) (or [multiple gateways if you deploy a high-availability solution](../../../deployment-strategies/high-availability-and-failover/#gateway-high-availability)). {% hint style="success" %} Defguard supports **multiple locations**, for each location to work you need to configure it and deploy a dedicated gateway. @@ -19,10 +19,10 @@ This is the default option that creates an typical VPN network. #### Service location {% hint style="info" %} -This feature is only for Windows platform. +This feature is supported on Windows and Linux. The **Pre-logon** mode is Windows-only. {% endhint %} -Service Location is a Windows-specific configuration that automates secure network connectivity for managed devices. It ensures that authorized clients establish a persistent VPN tunnel immediately upon system startup, rather than waiting for a user to log in. +Service Location automates secure network connectivity for managed devices. It ensures that authorized clients establish a persistent VPN tunnel immediately upon system startup, rather than waiting for a user to log in. The tunnel is handled by a background service, so the location is not shown in the Defguard Client and requires no action from the user. See [Service locations](../../service-locations.md) for details. ## VPN Location configuration @@ -82,7 +82,7 @@ It supports multiple networks separated with comma, e.g. 10.11.1.0/0, 192.168.1. {% hint style="danger" %} Right now Defguard only manages routing of Allowed IPs (adding to routing table the networks defined in Allowed IPs). -If you want the _All Traffic_ to work in the desktop client you need to also configure MASQUARED/NAT for the VPN interface. [Example of that here.](/broken/pages/MbleSplRWwmcWM2VEo3m#enabling-to-access-internet-through-your-vpn) +If you want the _All Traffic_ to work in the desktop client you need to also configure MASQUARED/NAT for the VPN interface. {% endhint %} {% hint style="info" %} @@ -96,7 +96,7 @@ To simplify this, you can use an **Allowed IPs calculator** to generate the corr #### Generate Allowed IPs from Firewall Rules {% hint style="info" %} -**Enterprise feature.** Requires an active Enterprise license. +**Enterprise feature.** Requires an active Enterprise license. {% endhint %} When enabled, IP addresses from [Firewall Rules](../../firewall/) that grant access to the given user are automatically added to the Allowed IPs list when a device config is generated. Manually entered Allowed IPs are always included. @@ -106,7 +106,7 @@ The Firewall must be **enabled** for the location for this option to have any ef {% endhint %} * **Sources included:** Addresses entered directly in Rule manual settings or Aliases and pre-defined Destinations attached to the rule. -* **Merge behavior:** Manual AllowedIPs are preserved. ACL-derived IPs are\ +* **Merge behaviour:** Manual AllowedIPs are preserved. ACL-derived IPs are\ appended, deduplicated, and sorted. * **Any Address destinations:** Destinations marked as "Any Address" in ACL\ rules are **not** added to Allowed IPs (the firewall still enforces them\ diff --git a/features/wireguard/multi-factor-authentication-mfa-2fa/README.md b/features/wireguard/multi-factor-authentication-mfa-2fa/README.md index cbae45d..6679626 100644 --- a/features/wireguard/multi-factor-authentication-mfa-2fa/README.md +++ b/features/wireguard/multi-factor-authentication-mfa-2fa/README.md @@ -45,7 +45,7 @@ User prerequisites (something a user has in terms of MFA terminology): * A private WireGuard® key corresponding to the public key configured during the Defguard enrollment session. * A mobile device successfully enrolled and added to the user profile (as a second VPN device). -* Private keys in the mobile device’s secure key store, generated during the mobile device enrollment process, which are accessible only via the device’s biometric authentication.\\ +* Private keys in the mobile device’s secure key store, generated during the mobile device enrollment process, which are accessible only via the device’s biometric authentication. Extended MFA flow using two devices: @@ -58,6 +58,3 @@ Extended MFA flow using two devices: The main purpose of MFA is to strengthen security by acting as a highly effective barrier against cyberattacks such as phishing or brute-force attacks. With an effective MFA implementation, even if an attacker gains access to a user’s basic credentials (in WireGuard®’s case, typically the private key stored on the device), they will still be unable to connect to the VPN without the additional factor(s). This prevents access to critical private network resources and applications, blocking further exploitation and greatly reducing the risk of unauthorized access. This means that relying on external SSO only for the initial device configuration is not sufficient to provide security in today’s environment. Even worse, marketing a VPN solution as providing MFA under these circumstances is highly misleading and potentially harmful to user security. - -\ -\\ diff --git a/features/wireguard/multi-factor-authentication-mfa-2fa/internal-sso-based-mfa.md b/features/wireguard/multi-factor-authentication-mfa-2fa/internal-sso-based-mfa.md index 71db7ce..00312f7 100644 --- a/features/wireguard/multi-factor-authentication-mfa-2fa/internal-sso-based-mfa.md +++ b/features/wireguard/multi-factor-authentication-mfa-2fa/internal-sso-based-mfa.md @@ -5,7 +5,7 @@ Enabling Internal MFA for a desired VPN Location is done by: 1. Going into Defguard to **VPN Overview** 2. Selecting the VPN Location from the dropdown list, and pressing the **Edit Location** button in the top right corner of the page 3. Check the "**Internal MFA**" checkbox under the **MFA requirement** section -4. Set **peer disconnect threshold**, we recommend it to be min. 300 (5 min) - see chapter [below](internal-sso-based-mfa.md#peer-disconnect-threshold). +4. Set **peer disconnect threshold**, we recommend it to be min. 300 (5 min) - see chapter [below](internal-sso-based-mfa.md#client-disconnect-threshold). 5. And **save changes**.
diff --git a/features/wireguard/network-overview.md b/features/wireguard/network-overview.md index 38927ff..8124516 100644 --- a/features/wireguard/network-overview.md +++ b/features/wireguard/network-overview.md @@ -1,10 +1,10 @@ # Network overview -Once your gateway service is up and users start connecting to the VPN, upload/download summary data is stored and can be displayed in "overview" tab of Defguard web application. See [architecture overview](../../in-depth/architecture/) for details of core-gateway interaction. +Once your gateway service is up and users start connecting to the VPN, upload/download summary data is stored and can be displayed on the **VPN Overview** page of the Defguard web application. See [architecture overview](../../in-depth/architecture/) for details of core-gateway interaction. -On the overview page, you'll see who is currently connected and how much data each connected user transferred. You'll also see overall network transfer charts. +On the **VPN Overview** page, you'll see who is currently connected and how much data each connected user transferred. You'll also see overall network transfer charts. -Since **version 1.4**, Defguard dashboard allows administrators to see: +The Defguard dashboard allows administrators to see: * Current amount of active users / network devices * Active users / network devices during time period diff --git a/features/wireguard/remote-desktop-activation.md b/features/wireguard/remote-desktop-activation.md index 108edfd..09803c0 100644 --- a/features/wireguard/remote-desktop-activation.md +++ b/features/wireguard/remote-desktop-activation.md @@ -26,7 +26,7 @@ You will be presented with a choice to send an activation token via email or you
-After receiving the token, the user will need to follow the activation process in the client. You can find out more about it in [#adding-instance](../../using-defguard-for-end-users/desktop-client/instance-configuration.md#adding-instance "mention"). +After receiving the token, the user will need to follow the activation process in the client. You can find out more about it in [#manually-adding-instance](../../using-defguard-for-end-users/desktop-client/instance-configuration.md#manually-adding-instance "mention"). This token also allows for updating information, read more about it in [#updating-instance](../../using-defguard-for-end-users/desktop-client/instance-configuration.md#updating-instance "mention"). diff --git a/getting-started/one-line-install.md b/getting-started/one-line-install.md index f9e3da8..603683b 100644 --- a/getting-started/one-line-install.md +++ b/getting-started/one-line-install.md @@ -77,7 +77,7 @@ The script does the following: * Starts the compose stack {% hint style="info" %} -By default, the script enables masquerade on the Gateway container. This allows all traffic coming through the VPN to leave the container and reach any destination accessible from the host system. To disable this behavior, use the relevant [configuration](one-line-install.md#cli-options) option or set up proper [ACL](../features/firewall/)/firewall rules. +By default, the script enables masquerade on the Gateway container. This allows all traffic coming through the VPN to leave the container and reach any destination accessible from the host system. To disable this behaviour, use the relevant [configuration](one-line-install.md#cli-options) option or set up proper [ACL](../features/firewall/)/firewall rules. {% endhint %} ### Prerequisites diff --git a/in-depth/architecture-decision-records/1.4.md b/in-depth/architecture-decision-records/1.4.md index 8de1ce1..da3a6d9 100644 --- a/in-depth/architecture-decision-records/1.4.md +++ b/in-depth/architecture-decision-records/1.4.md @@ -2,4 +2,4 @@ ## 2025-06-01 Assign all IP addresses to clients -Up to this point, only the first network IP address was assigned to devices, as described in \[ADR]\([https://docs.defguard.net/in-depth/architecture-decision-records/pre-1.3#id-2025-01-03-multiple-ip-addresses](https://docs.defguard.net/in-depth/architecture-decision-records/pre-1.3#id-2025-01-03-multiple-ip-addresses)). This was an artificial limitation, and many customers were interested in being able to assign multiple addresses (IPv4 and IPv6) to user devices. v1.4 introduces changes to user device model as well as desktop client code that allows assignment of all network IPs. +Up to this point, only the first network IP address was assigned to devices, as described in [ADR](pre-1.3.md#id-2025-01-03-multiple-ip-addresses). This was an artificial limitation, and many customers were interested in being able to assign multiple addresses (IPv4 and IPv6) to user devices. v1.4 introduces changes to user device model as well as desktop client code that allows assignment of all network IPs. diff --git a/in-depth/architecture-decision-records/1.6.md b/in-depth/architecture-decision-records/1.6.md index b5c8e0b..11f59eb 100644 --- a/in-depth/architecture-decision-records/1.6.md +++ b/in-depth/architecture-decision-records/1.6.md @@ -2,10 +2,10 @@ ## 2025-10-16 Desktop client auto-provisioning -In order to support client auto-provisioning of the desktop client we've introduced support for initializing the client from a provisioning file ([#627](https://github.com/DefGuard/client/pull/627)). If a client is "uninitialized" (has no instance configured) it can read required enrollment config from a file stored in app data directory. The process is explained further in the [docs](../../features/desktop-client-auto-provisioning/#client-side-implementation). +In order to support client auto-provisioning of the desktop client we've introduced support for initializing the client from a provisioning file ([#627](https://github.com/DefGuard/client/pull/627)). If a client is "uninitialized" (has no instance configured) it can read required enrollment config from a file stored in app data directory. The process is explained further in the [docs](../../features/desktop-client-auto-provisioning/#client-side-implementation-details). This file-based approach allows us to support provisioning on various platforms independent of the specific tooling used by system administrators. -Furthermore since the majority of users are on the Windows platform we also updated our MSI package to support provisioning scenarios in Active Directory and Entra ID environments as described [here](../../features/desktop-client-auto-provisioning/#windows-auto-provisioning). +Furthermore since the majority of users are on the Windows platform we also updated our MSI package to support provisioning scenarios in Active Directory and Entra ID environments as described [here](../../features/desktop-client-auto-provisioning/auto-provisioning-in-windows-environments/#windows-auto-provisioning). -To enable this functionality we also needed to introduce a change to the OpenID directory sync functionality - when using Microsoft provider it is now possible to [create users in Defguard during sync](../../features/external-openid-providers/microsoft.md#creating-defguard-user), without waiting for the first login. +To enable this functionality we also needed to introduce a change to the OpenID directory sync functionality - when using Microsoft provider it is now possible to create users in Defguard during sync, without waiting for the first login. diff --git a/in-depth/architecture-decision-records/2.0.md b/in-depth/architecture-decision-records/2.0.md index d7c3627..d616f13 100644 --- a/in-depth/architecture-decision-records/2.0.md +++ b/in-depth/architecture-decision-records/2.0.md @@ -109,7 +109,7 @@ Both Aliases and Destinations are still stored in the same underlying database m ### Explicit destination configuration -In previous Defguard versions, the ACL rule logic regarding destinations broadly reflected how most firewalls, such as `nftables` and `packetfilter`, work. As a result, some behaviors were implicit. +In previous Defguard versions, the ACL rule logic regarding destinations broadly reflected how most firewalls, such as `nftables` and `packetfilter`, work. As a result, some behaviours were implicit. In particular, rules and aliases could omit destination addresses, ports, or protocols, which implicitly meant "match any". This matched firewall semantics, but it introduced ambiguity in the data model and in the UI: @@ -117,7 +117,7 @@ In particular, rules and aliases could omit destination addresses, ports, or pro * The logic for generating firewall rules had to assume user intent, especially for rules using aliases. * Validation and editing logic had to handle a number of edge cases. -As ACL functionality evolved, this approach became harder to maintain consistently. Defguard 2.0 introduces a more explicit ACL model to reduce ambiguity while preserving the effective firewall behavior of existing rules. +As ACL functionality evolved, this approach became harder to maintain consistently. Defguard 2.0 introduces a more explicit ACL model to reduce ambiguity while preserving the effective firewall behaviour of existing rules. #### Database model changes @@ -136,11 +136,11 @@ In addition, rules now include **use\_manual\_destination\_settings**, which def The rule model also adds **allow\_all\_groups** and **deny\_all\_groups** to align group handling with the already explicit "all" flags used for other source types. -Overall, the 2.0 schema preserves the effective firewall behavior of existing ACL rules while making the model clearer, easier to validate, and less dependent on implicit assumptions. +Overall, the 2.0 schema preserves the effective firewall behaviour of existing ACL rules while making the model clearer, easier to validate, and less dependent on implicit assumptions. #### Backfill logic -The Defguard 2.0 database migration includes SQL backfill logic that converts legacy implicit ACL behavior into the new explicit model while preserving the meaning of existing rules. +The Defguard 2.0 database migration includes SQL backfill logic that converts legacy implicit ACL behaviour into the new explicit model while preserving the meaning of existing rules. For **Destinations** (previously destination aliases), the migration backfills the new `any_*` flags from the legacy fields: @@ -162,7 +162,7 @@ The migration sets **use\_manual\_destination\_settings** to **false** only when * no linked component alias contributed any destination fragments, * at least one linked destination alias existed. -In every other case, **use\_manual\_destination\_settings** remains **true**, preserving the previous behavior of rules that relied on direct destination settings or component aliases. +In every other case, **use\_manual\_destination\_settings** remains **true**, preserving the previous behaviour of rules that relied on direct destination settings or component aliases. As a result, legacy empty destination fields become explicit "match any" flags, rules based only on destination aliases become explicit Destination-based rules, and mixed or manual rules continue to behave as they did before migration. diff --git a/in-depth/architecture-decision-records/2.1.md b/in-depth/architecture-decision-records/2.1.md new file mode 100644 index 0000000..f1b4d9f --- /dev/null +++ b/in-depth/architecture-decision-records/2.1.md @@ -0,0 +1,7 @@ +# 2.1 + +{% hint style="info" %} +The Architecture Decision Records for the 2.1 release are being prepared and will be published here. + +In the meantime, see [2.0](2.0.md) for the decisions behind the current component architecture. +{% endhint %} diff --git a/in-depth/client-application-feature-compatibility.md b/in-depth/client-application-feature-compatibility.md index a083c3b..425583b 100644 --- a/in-depth/client-application-feature-compatibility.md +++ b/in-depth/client-application-feature-compatibility.md @@ -11,4 +11,4 @@ Use this page to quickly verify whether a given feature will work in your enviro ### Feature compatibility matrix -
FeatureIntroduced inMinimum Server versionMinimum Client version
Service Locations1.61.61.6
Setting MTU1.6Client-only feature1.6
Desktop Client Auto Provisioning1.61.61.6
Client Traffic Policy Selection1.61.61.6
+
FeatureIntroduced inMinimum Server versionMinimum Client version
Service Locations1.61.61.6
Setting MTU1.6Client-only feature1.6
Desktop Client Auto Provisioning1.61.61.6
Client Traffic Policy Selection1.61.61.6
diff --git a/in-depth/secure-by-design.md b/in-depth/secure-by-design.md index 08f0fe0..b127846 100644 --- a/in-depth/secure-by-design.md +++ b/in-depth/secure-by-design.md @@ -30,7 +30,7 @@ The choice of programming language and frameworks/libraries is fundamental, as i * Exposure to vulnerabilities * The likelihood of implementation errors -* System behavior under failure conditions +* System behaviour under failure conditions * The ability to detect and mitigate attacks Defguard is built in [Rust](https://rust-lang.org/) language, which is recommended by leading security organizations worldwide due to its strong memory safety guarantees and modern security model: diff --git a/support-1/how-to-submit-an-issue.md b/support-1/how-to-submit-an-issue.md index fa31512..5583110 100644 --- a/support-1/how-to-submit-an-issue.md +++ b/support-1/how-to-submit-an-issue.md @@ -5,7 +5,7 @@ To help us diagnose and resolve problems efficiently, please follow the process below when submitting an issue. {% hint style="info" %} -If you are using the OVA VM image, to access the VM and gather logs, please see this chapter: [https://docs.defguard.net/deployment-strategies/ova#accessing-the-vm](https://docs.defguard.net/deployment-strategies/ova#accessing-the-vm) +If you are using the OVA VM image, to access the VM and gather logs, please see this chapter: [Accessing the VM](../deployment-strategies/ova.md#accessing-the-vm) {% endhint %} ### 1. Enable debug logging @@ -34,7 +34,7 @@ The logs will automatically include: After reproducing the issue, gather logs from **all relevant components**.\ Make sure to include **all of them** in your report. -For UI components, also take screenshots if the issue affects layout, design, or visual behavior. +For UI components, also take screenshots if the issue affects layout, design, or visual behaviour. {% hint style="warning" %} Please include only the log entries captured around the time the issue occurred and make sure the logs contain the actual error message.\ @@ -47,8 +47,8 @@ In addition to logs, clearly describe how the issue can be reproduced. Include: * Description of your deployment strategy * Exact steps you took -* Expected behavior -* Actual behavior +* Expected behaviour +* Actual behaviour ### 5. Submit your report diff --git a/support-1/sending-support-information/README.md b/support-1/sending-support-information/README.md index 985df0c..6281572 100644 --- a/support-1/sending-support-information/README.md +++ b/support-1/sending-support-information/README.md @@ -1,2 +1,21 @@ # Sending support information +The following document describes how to obtain support information that you can attach when contacting our support team. + +Providing this information helps us diagnose issues more quickly, reducing the time required to identify the root cause and resolve the problem. + +Depending on the nature of the issue, you may need to provide support information from the server applications, the client applications, or both. + +See the relevant subpages for detailed instructions on how to retrieve the support information for each component. + +{% content-ref url="core.md" %} +[core.md](core.md) +{% endcontent-ref %} + +{% content-ref url="desktop-client.md" %} +[desktop-client.md](desktop-client.md) +{% endcontent-ref %} + +{% content-ref url="mobile-client.md" %} +[mobile-client.md](mobile-client.md) +{% endcontent-ref %} diff --git a/support-1/sending-support-information/core.md b/support-1/sending-support-information/core.md index 5c787c6..d537887 100644 --- a/support-1/sending-support-information/core.md +++ b/support-1/sending-support-information/core.md @@ -1,7 +1,31 @@ # Core -When contacting support you can send us **anonymous** support data by: +Defguard Core has a dedicated **Support** page that gathers everything you need when reporting a problem or contacting our team. It is available to administrators in the main menu, under the **Admin** group. -1. In **Settings → Support** tab you'll be able to generate and send support data that can be used when debugging your issues. -2. To download configuration and logs use appropriate buttons. You can attach them to bug report in our GitHub repository or send them in Matrix. -3. The "Send email" button is active only if you [configured the SMTP server](../../features/notifications/setting-up-smtp-for-email-notifications.md). +The page is divided into sections: + +### Documentation + +Before submitting an issue, check the documentation - most configuration problems are covered there. The **Go to documentation** button opens it in a new tab. + +### Report a bug + +The **Report on Github** button opens a new issue in our GitHub repository. To give us more context, use the **Download** button next to it and pick **Download support data**. This saves a JSON file named `defguard-support-data-.json`, which you can attach to the issue. + +The support data contains your instance settings, VPN locations, and device assignments, so that we can reproduce your configuration. Secrets are removed before the file is generated - the SMTP password and the LDAP bind password are stripped - and user records are reduced to anonymous diagnostic fields (identifier, MFA method, whether MFA is enabled, whether the account is active and enrolled). No usernames, e-mail addresses, or password hashes are included. + +{% hint style="info" %} +Core logs are **not** part of the support data file. If we ask you for logs, collect them from the machine or container running Core. If Core was started with `--log-file` / `DEFGUARD_LOG_FILE` (see [Core deployment parameters](../../deployment-strategies/configuration.md#core-deployment-parameters)), an administrator can also fetch that file from the API endpoint `GET /api/v1/support/logs`. +{% endhint %} + +### Request feature + +The **Submit on Github** button opens a feature request in our GitHub repository. + +### Contact us by email + +Shown for instances with a basic or direct support plan. It points you at `support@defguard.net`. + +### Need direct support? + +Shown only for instances with a direct support plan. **Open a support ticket** opens a ticket pre-filled with your customer identifier, and **Schedule a call with our support team** opens our booking page. diff --git a/support-1/troubleshooting-guides/README.md b/support-1/troubleshooting-guides/README.md index 334dd3f..299d192 100644 --- a/support-1/troubleshooting-guides/README.md +++ b/support-1/troubleshooting-guides/README.md @@ -16,6 +16,9 @@ Issues are grouped by component. Each linked page covers one specific problem. * [unable-to-sign-in-with-correct-credentials.md](core/unable-to-sign-in-with-correct-credentials.md "mention") * [user-lost-access-to-their-2fa-methods.md](core/user-lost-access-to-their-2fa-methods.md "mention") * [enrollment-url-changed.md](core/enrollment-url-changed.md "mention") +* [failed-to-parse-duration.md](core/failed-to-parse-duration.md "mention") +* [core-cannot-connect-to-gateway-or-edge-after-restart-on-single-host-deployments.md](core/core-cannot-connect-to-gateway-or-edge-after-restart-on-single-host-deployments.md "mention") +* [lost-access.md](core/lost-access.md "mention") ### [desktop-client](desktop-client/ "mention") @@ -33,6 +36,9 @@ Issues are grouped by component. Each linked page covers one specific problem. * [high-disk-usage.md](desktop-client/high-disk-usage.md "mention") * [mfa-location-disconnected-after-x-time.md](desktop-client/mfa-location-disconnected-after-x-time.md "mention") * [unix-socket-permission-error-on-connect-linux.md](desktop-client/unix-socket-permission-error-on-connect-linux.md "mention") +* [could-not-start-mfa-process.md](desktop-client/could-not-start-mfa-process.md "mention") +* [vpn-location-is-missing-from-client.md](desktop-client/vpn-location-is-missing-from-client.md "mention") +* [client-crashes-immediately-on-launch-with-error-71-protocol-error-dispatching-to-wayland-display.md](desktop-client/client-crashes-immediately-on-launch-with-error-71-protocol-error-dispatching-to-wayland-display.md "mention") ### [mobile-client](mobile-client/ "mention") @@ -52,3 +58,4 @@ Issues are grouped by component. Each linked page covers one specific problem. * [webauthn-security-keys.md](webauthn-security-keys.md "mention") * [can-access-vpn-but-not-local-network-or-internet.md](can-access-vpn-but-not-local-network-or-internet.md "mention") * [how-to-verify-the-vpn-is-working.md](how-to-verify-the-vpn-is-working.md "mention") +* [testing-vpn-speed.md](testing-vpn-speed.md "mention") diff --git a/support-1/troubleshooting-guides/can-access-vpn-but-not-local-network-or-internet.md b/support-1/troubleshooting-guides/can-access-vpn-but-not-local-network-or-internet.md index 8e18fc1..40c6bdf 100644 --- a/support-1/troubleshooting-guides/can-access-vpn-but-not-local-network-or-internet.md +++ b/support-1/troubleshooting-guides/can-access-vpn-but-not-local-network-or-internet.md @@ -25,5 +25,3 @@ echo 1 > /proc/sys/net/ipv4/ip_forward ``` To persist across reboots, add `net.ipv4.ip_forward = 1` to `/etc/sysctl.conf`. - -A full step-by-step example for enabling internet access through the VPN is available in the [deployment tutorial](https://docs.defguard.net/2.0/tutorials/step-by-step-setting-up-a-vpn-server#enabling-to-access-internet-through-your-vpn). diff --git a/support-1/troubleshooting-guides/core/unable-to-sign-in-with-correct-credentials.md b/support-1/troubleshooting-guides/core/unable-to-sign-in-with-correct-credentials.md index d34fdaf..db4803a 100644 --- a/support-1/troubleshooting-guides/core/unable-to-sign-in-with-correct-credentials.md +++ b/support-1/troubleshooting-guides/core/unable-to-sign-in-with-correct-credentials.md @@ -2,7 +2,7 @@ This error appears when the browser's session cookie cannot be set. The most common cause is a misconfigured `DEFGUARD_URL`. -### In version 2.0 +### Instance URL setting `DEFGUARD_URL` is deprecated. The instance URL is now configured through the web UI. Go to **Settings** in the Defguard interface and verify the **Instance URL** field. It must match the URL you are accessing Defguard from, including the correct scheme (`https://` vs `http://`). @@ -10,4 +10,4 @@ If the value is wrong, the server will set the session cookie with an incorrect ### HTTP (non-TLS) deployments -If you are accessing Defguard over plain `http://` (for example, in a local or development environment), you need to configure auth cookie settings to allow non-secure cookies. See the [Auth cookies configuration](https://docs.defguard.net/2.0/deployment-strategies/configuration#auth-cookies-configuration) documentation for the required settings. +If you are accessing Defguard over plain `http://` (for example, in a local or development environment), you need to configure auth cookie settings to allow non-secure cookies. See the [Core deployment parameters](../../../deployment-strategies/configuration.md#core-deployment-parameters) documentation for the required settings. diff --git a/support-1/troubleshooting-guides/desktop-client/high-disk-usage.md b/support-1/troubleshooting-guides/desktop-client/high-disk-usage.md index 11582e0..3d5b9f8 100644 --- a/support-1/troubleshooting-guides/desktop-client/high-disk-usage.md +++ b/support-1/troubleshooting-guides/desktop-client/high-disk-usage.md @@ -16,7 +16,7 @@ The fix for the original table-scan problem was introduced in **v1.5.2**. If the stats purge mechanism is not working correctly or heavy usage generates too much data, the database can grow very large. -**Location of the DB file: `C:\Users\AppData\Roaming\net.defguard\defguard.db`** +**Location of the DB file: `C:\Users\\AppData\Roaming\net.defguard\defguard.db`** **Typical sizes:** @@ -43,7 +43,7 @@ This immediately reduces the DB size and disk I/O. **Option B — Remove the Database Entirely (quickest, but requires re-enrollment)** 1. Close Defguard completely -2. Delete the database file: `C:\Users\AppData\Roaming\net.defguard\defguard.db` +2. Delete the database file: `C:\Users\\AppData\Roaming\net.defguard\defguard.db` 3. Re-enroll your device in Defguard (you will need your enrollment link or admin setup) This is the nuclear option but works reliably. diff --git a/support-1/troubleshooting-guides/desktop-client/vpn-location-is-missing-from-client.md b/support-1/troubleshooting-guides/desktop-client/vpn-location-is-missing-from-client.md index 092d7db..b3a2cee 100644 --- a/support-1/troubleshooting-guides/desktop-client/vpn-location-is-missing-from-client.md +++ b/support-1/troubleshooting-guides/desktop-client/vpn-location-is-missing-from-client.md @@ -8,9 +8,7 @@ Locations protected by posture checks require Defguard Client `2.1` or later. If your organization enabled posture checks on a location, that location does not appear in clients older than `2.1`. -The same applies to service locations. They are hidden when the client does not support them, for example on non-Windows platforms or in older clients. - -**Fix:** Update Defguard to the latest version, then reopen the app. If the missing location is a service location, use Defguard Client for Windows. +**Fix:** Update Defguard to the latest version, then reopen the app. ### Client configuration is outdated @@ -24,7 +22,7 @@ Update the instance configuration. See [Instance configuration](../../../using-d Refresh the instance screen manually or restart the app. -See [Mobile Client](../../../using-defguard-for-end-users/mobile-client/) for mobile client behavior. +See [Mobile Client](../../../using-defguard-for-end-users/mobile-client/) for mobile client behaviour. ### You do not have access to the location @@ -32,8 +30,10 @@ Administrators can restrict a location to specific users or groups. If other users can see the location but you cannot, contact your administrator. -### The location is hidden by design +### The location is a service location + +[Service locations](../../../features/service-locations.md) are never shown in the Defguard Client. They are established and maintained by a background service, so there is no entry in the location list and nothing for the user to connect to. An **Always on** service location is connected even when the Client is closed. -Some location types are not shown in the regular client list. +**Fix:** nothing to fix in the Client. To confirm the connection is up, check the network adapters on the machine or the client status in the Defguard Core web interface - see [Checking if connection is established](../../../features/service-locations.md#checking-if-connection-is-established). -For example, Windows service locations run in the background and are hidden in the UI after configuration is applied. +Service locations require Defguard Client for Windows or Linux; the **Pre-logon** mode is Windows-only. If a location was made a service location and the machine runs macOS or a mobile client, it will not be available there at all. diff --git a/support-1/troubleshooting-guides/gateway/README.md b/support-1/troubleshooting-guides/gateway/README.md index 342b3ae..3cae70a 100644 --- a/support-1/troubleshooting-guides/gateway/README.md +++ b/support-1/troubleshooting-guides/gateway/README.md @@ -1,2 +1,59 @@ # Gateway +### WireGuard network interface not configured + +* Make sure Defguard Gateway has been properly adopted. If not adopted, Gateway won't configure any + WireGuard network interfaces. After the adoption, there should be files in `/etc/defguard/certs`. + + ```sh + # ls -l /etc/defguard/certs + total 16 + -rw------- 1 root wheel 569 May 4 09:53 core_client_cert.pem + -rw------- 1 root wheel 602 May 4 09:53 gateway_grpc_cert.pem + -rw------- 1 root wheel 241 May 4 09:53 gateway_grpc_key.pem + -rw------- 1 root wheel 655 May 4 09:53 grpc_ca_cert.pem + ``` + +* Check if the correct interface name is set as `ifname` in `/etc/defguard/gateway.toml`, for + example: + + ```ini + ifname = "wg0" + ``` + +* Check if the required network interface has been configured: + + On Linux: + + ```sh + # ip a show dev wg0 + 8: wg0: mtu 1420 qdisc noqueue state UNKNOWN group default qlen 1000 + link/none + ``` + + On BSD/macOS: + + ```sh + # ifconfig wg0 + wg0: flags=10080c1 metric 0 mtu 1420 + options=80000 + inet 192.168.0.1 netmask 0xffffff00 + groups: wg + nd6 options=109 + ``` + +* Check if WireGuard peers are configured. This requires [wireguard-tools](https://github.com/WireGuard/wireguard-tools) package being installed. + + ```sh + # wg show wg0 + interface: wg0 + public key: VGFrZXMgb25lIERlZmd1YXJkIHRvIHJ1bGUgdGhlbSBhbGw= + private key: (hidden) + listening port: 51820 + + peer: TWF5IHRoZSBmb3JjZSBvZiBEZWZndWFyZCBiZSB3aXRoIHlvdQ== + preshared key: (hidden) + allowed ips: 192.168.0.2/32 + transfer: 0 B received, 90.48 KiB sent + persistent keepalive: every 25 seconds + ``` diff --git a/support-1/troubleshooting/README.md b/support-1/troubleshooting/README.md index 31978d3..3c9ac79 100644 --- a/support-1/troubleshooting/README.md +++ b/support-1/troubleshooting/README.md @@ -127,7 +127,7 @@ You are probably looking for `DEFGUARD_ENROLLMENT_URL` which is the URL needed t
-Please check [this article](../../deployment-strategies/configuration.md#enrollment-configuration). +Please check [this article](../../deployment-strategies/configuration.md#settings). ## Enrollment URL has changed @@ -139,7 +139,7 @@ If for any reason the Enrollment URL has changed (eg. the domain from: _enroll.c In order to do so: -* **The administrator** needs to send an update token to each person - [see this documentation page.](https://docs.defguard.net/features/remote-user-enrollment#restarting-enrollment-manually) +* **The administrator** needs to send an update token to each person - [see this documentation page.](../../features/remote-user-enrollment/#restarting-enrollment-manually) * **The user** needs to update manually the Enrollment URL providing also the received token - [see this documentation page](../../using-defguard-for-end-users/desktop-client/). ## How to check if the VPN is working / my VPN is not working @@ -152,7 +152,7 @@ After connecting to VPN you should be able to ping: 10.1.1.1. ### VPN Location settings changed -Check if the VPN location configuration has changed. If it did, and you do not have Enterprise license where real-time config sync is automatic, the user needs to [update their client configuration by updating that instance manually.](../../using-defguard-for-end-users/desktop-client/instance-configuration.md#updating-instance) +Check if the VPN location configuration has changed. If it did, and you do not have a Business or Enterprise plan where real-time config sync is automatic, the user needs to [update their client configuration by updating that instance manually.](../../using-defguard-for-end-users/desktop-client/instance-configuration.md#updating-instance) ### Conflicting networks @@ -199,15 +199,15 @@ Then when the client / user connects it actually establishes **a secure tunnel b From there, what happens to this traffic is the **administrator role.** The most common scenarios to do are: * add routing rules, so that the traffic from that interface/VPN IP network gets routed to your network - this approach gives the advantage that users VPN ip persists in the network and the user is visible with it's VPN ip in your local network -* Masquerade or NAT - a common use case is to masquerade or NAT the traffic - which is **actually required if you want users to access Internet from the VPN -** this process is [described in detailed in this tutorial](/broken/pages/MbleSplRWwmcWM2VEo3m#enabling-to-access-internet-through-your-vpn). +* Masquerade or NAT - a common use case is to masquerade or NAT the traffic - which is **actually required if you want users to access Internet from the VPN.** ## Unable to sign in to your Defguard instance with correct credentials The user tries to sign in to a Defguard instance but gets a 401 response with message "Session is required". -This issue is most likely caused by a misconfigured `DEFGUARD_URL` . Please have a look at the configuration options described in [General configuration](../../deployment-strategies/configuration.md#general-configuration) documentation. +This issue is most likely caused by a misconfigured `DEFGUARD_URL` . Please have a look at the configuration options described in [Core deployment parameters](../../deployment-strategies/configuration.md#core-deployment-parameters) documentation. -If you want to access your Defguard instance without TLS (using an `http://` URL), please also make sure you have everything configured according to [Auth cookies configuration](../../deployment-strategies/configuration.md#auth-cookies-configuration) documentation. +If you want to access your Defguard instance without TLS (using an `http://` URL), please also make sure you have everything configured according to [Core deployment parameters](../../deployment-strategies/configuration.md#core-deployment-parameters) documentation. ## User lost access to their 2FA methods diff --git a/using-defguard-for-end-users/cli-client.md b/using-defguard-for-end-users/cli-client.md index 28aa24c..18f8b4e 100644 --- a/using-defguard-for-end-users/cli-client.md +++ b/using-defguard-for-end-users/cli-client.md @@ -2,28 +2,26 @@ ### Downloading -Latest release page: [https://github.com/DefGuard/client/releases/tag/v1.2.0](https://github.com/DefGuard/client/releases/tag/v1.2.0) +Download the packages from the [latest release](https://github.com/DefGuard/client/releases/latest) page. The CLI Client ships as its own set of `dg-*` assets, next to the desktop client packages: #### Linux (AMD64) -Deb: [https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-x86\_64-v1.2.0-dg.deb](https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-x86_64-v1.2.0-dg.deb) - -RPM: [https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-x86\_64-v1.2.0-dg.rpm](https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-x86_64-v1.2.0-dg.rpm) - -Binary: [https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-x86\_64-v1.2.0-dg.tar.gz](https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-x86_64-v1.2.0-dg.tar.gz) +* Deb: `dg-linux-x86_64-v{x.x.x}.deb` +* RPM: `dg-linux-x86_64-v{x.x.x}.rpm`, or `dg-linux-x86_64-v{x.x.x}-el9.rpm` for Enterprise Linux 9 +* Binary: `dg-linux-x86_64-v{x.x.x}.tar.gz` +* Deb for Ubuntu 22.04 / Debian 12: `dg-linux-{x.x.x}_amd64_ubuntu-22-04-lts.deb` #### Linux (ARM64) -Deb: [https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-aarch64-v1.2.0-dg.deb](https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-aarch64-v1.2.0-dg.deb) - -RPM: [https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-aarch64-v1.2.0-dg.rpm](https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-aarch64-v1.2.0-dg.rpm) - -Binary: [https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-aarch64-v1.2.0-dg.tar.gz](https://github.com/DefGuard/client/releases/download/v1.2.0/dg-linux-aarch64-v1.2.0-dg.tar.gz) +* Deb: `dg-linux-aarch64-v{x.x.x}.deb` +* RPM: `dg-linux-aarch64-v{x.x.x}.rpm` +* Binary: `dg-linux-aarch64-v{x.x.x}.tar.gz` +* Deb for Ubuntu 22.04 / Debian 12: `dg-linux-{x.x.x}_arm64_ubuntu-22-04-lts.deb` ### Requirements * Root access on a given machine -* Defguard proxy running and accessible from the machine the CLI will be installed on +* Defguard Edge running and accessible from the machine the CLI will be installed on * `resolvconf` and `ip` commands available ### Installation @@ -33,13 +31,13 @@ Installation is straightforward. As a root, install it as any other package of a #### Deb archive ```sh -apt install ./dg-linux-x86_64-v1.5.0-dg.deb +apt install ./dg-linux-x86_64-v{x.x.x}.deb ``` #### DNF ```sh -dnf install ./dg-linux-x86_64-v1.5.0-dg.rpm +dnf install ./dg-linux-x86_64-v{x.x.x}.rpm ``` #### Post install @@ -68,7 +66,7 @@ Copy the command and proceed with [enrollment](cli-client.md#enrollment). #### Enrollment -Execute the command obtained in the previous step to configure Defguard CLI on the machine of your choice. The enrollment command will pull all the information required to establish a connection from your Defguard instance (through the Defguard proxy, so make sure it can be accessed) and will save it in a configuration file. Run the `enroll` command only when you need to retrieve your network configuration and apply it to the CLI Client. If you have access to the enterprise features, the CLI should automatically handle this when running. +Execute the command obtained in the previous step to configure Defguard CLI on the machine of your choice. The enrollment command will pull all the information required to establish a connection from your Defguard instance (through Defguard Edge, so make sure it can be accessed) and will save it in a configuration file. Run the `enroll` command only when you need to retrieve your network configuration and apply it to the CLI Client. If you have access to the enterprise features, the CLI should automatically handle this when running. #### Connecting diff --git a/using-defguard-for-end-users/desktop-client/README.md b/using-defguard-for-end-users/desktop-client/README.md index e8b83b3..6e5a6c7 100644 --- a/using-defguard-for-end-users/desktop-client/README.md +++ b/using-defguard-for-end-users/desktop-client/README.md @@ -10,7 +10,7 @@ Key capabilities: * **Multi-Factor Authentication** – supports internal MFA (Authenticator App, email) as well as external OIDC/SSO providers and mobile biometry. The desktop client is required for MFA, as standard WireGuard clients do not support it. * **Command-line control** – the [`defguard-cli`](command-line-defguard-cli.md) tool ships with the client for headless machines, remote sessions, and scripting. * **Automatic updates** – the client checks for new releases and notifies you when one is available (this can be disabled in settings). -* **Real-time configuration sync** – with an Enterprise License, instances and locations stay [synchronized automatically](../../features/remote-user-enrollment/automatic-real-time-desktop-client-configuration.md). +* **Real-time configuration sync** – with a Business or Enterprise plan, instances and locations stay [synchronized automatically](../../features/remote-user-enrollment/automatic-real-time-desktop-client-configuration.md). Download the latest release here: [https://defguard.net/download/](https://defguard.net/download/) @@ -23,6 +23,14 @@ Guides: * [MTU Setting](mtu-setting.md) * [Command-line (defguard-cli)](command-line-defguard-cli.md) +## Defguard Client 2.1 + +Version 2.1 brings a completely redesigned Desktop Client. It now lives in the system tray, where a **compact view** lets you connect to and disconnect from locations, while the **full window** remains available for configuration, logs and settings. + +Version 2.1.0 is also **required for [device posture verification](../../features/device-posture-verification.md)**. Locations with posture checks assigned are not sent to older clients and do not appear in them. + +
+ ## Windows Download the Windows installer from the [download page](https://defguard.net/download/) (or from [GitHub releases](https://github.com/DefGuard/client/releases)) and run it. The `defguard-cli` command-line tool is installed alongside the client. diff --git a/using-defguard-for-end-users/desktop-client/instance-configuration.md b/using-defguard-for-end-users/desktop-client/instance-configuration.md index b50b7dd..b132ece 100644 --- a/using-defguard-for-end-users/desktop-client/instance-configuration.md +++ b/using-defguard-for-end-users/desktop-client/instance-configuration.md @@ -26,7 +26,7 @@ If you are looking for how to generate tokens for your users as an Administrator 4. Select **Client Activation** and click **Next**.
-5. Afterwards, use **One-Click Configuration** or click **Show advanced configuration** and copy **URL** and **Token** manually. +5. Afterwards, use **One-Click Configuration** or click **Show advanced configuration** and copy **URL** and **Token** manually.
@@ -91,7 +91,7 @@ Your Instance will update immediately. Defguard Desktop stores all information locally and doesn't communicate with Defguard outside the registration process. This means that the information about an instance is a snapshot of the moment you registered it in the desktop client, and you might want to update it, for example when locations are added or removed. {% hint style="success" %} -If you have an Enterprise License, all desktop clients and all instances are [synchronized automatically and in real-time.](../../features/remote-user-enrollment/automatic-real-time-desktop-client-configuration.md) +If you have a Business or Enterprise plan, all desktop clients and all instances are [synchronized automatically and in real-time.](../../features/remote-user-enrollment/automatic-real-time-desktop-client-configuration.md) {% endhint %} ### Removing Instance diff --git a/using-defguard-for-end-users/desktop-client/using-multi-factor-authentication-mfa.md b/using-defguard-for-end-users/desktop-client/using-multi-factor-authentication-mfa.md index dff412d..6ff3526 100644 --- a/using-defguard-for-end-users/desktop-client/using-multi-factor-authentication-mfa.md +++ b/using-defguard-for-end-users/desktop-client/using-multi-factor-authentication-mfa.md @@ -1,7 +1,6 @@ # Using Multi-Factor Authentication (MFA) -* Up to version 1.4, only internal MFA was supported, and a user could only use the MFA methods configured in their profile. -* Since version 1.5 (currently in alpha), MFA can be configured per location, and administrators can choose whether a location will use internal MFA or an external OIDC/SSO provider. +MFA is configured per location, and administrators choose whether a location uses internal MFA or an external OIDC/SSO provider. Depending on location settings, you may use: @@ -41,7 +40,7 @@ If you don't know how to set up or use your **Authenticator App,** please check
{% hint style="info" %} -If you need a guide explaining how to use Mobile Client as your MFA method, please [scroll down.](using-multi-factor-authentication-mfa.md#authenticating-via-biometry) +If you need a guide explaining how to use Mobile Client as your MFA method, please [scroll down.](using-multi-factor-authentication-mfa.md#multi-factor-authentication-via-mobile-biometry) {% endhint %} 3. After entering code, click **Verify** @@ -71,6 +70,6 @@ Here is a video showcasing this process: {% embed url="https://www.youtube.com/watch?v=b-XC76k4KVU" %} -And here you can see the whole flow done with multiple steps including the user, desktop (and mobile) the Proxy and Defguard Core and gateway in the final step: +And here you can see the whole flow done with multiple steps including the user, desktop (and mobile) the Edge and Defguard Core and gateway in the final step:
diff --git a/using-defguard-for-end-users/mobile-client/README.md b/using-defguard-for-end-users/mobile-client/README.md index 1e22da0..1dc9667 100644 --- a/using-defguard-for-end-users/mobile-client/README.md +++ b/using-defguard-for-end-users/mobile-client/README.md @@ -8,7 +8,7 @@ Mobile applications are available in the official app stores for [Android](https These guides explain how to use the Defguard Mobile to connect securely to VPN locations within your Defguard instance. It covers the entire process, from installation, adding new instances, connecting to locations, to managing your VPN connection settings. -* [Instance adding guide](instance-adding.md#adding-instance-during-enrollment) +* [Instance adding guide](instance-adding.md#adding-new-instance) * [Connecting to Instance guide](instance-connect.md#connecting-to-instance) * [Managing Instance guide](instance-manage.md#managing-your-instance) diff --git a/using-defguard-for-end-users/mobile-client/instance-connect.md b/using-defguard-for-end-users/mobile-client/instance-connect.md index 476f9b2..8635020 100644 --- a/using-defguard-for-end-users/mobile-client/instance-connect.md +++ b/using-defguard-for-end-users/mobile-client/instance-connect.md @@ -1,6 +1,6 @@ # Connecting to Instance -In this guide, you will learn how to connect to location. If you haven't added an instance yet, follow [this guide](instance-adding.md#adding-instance-during-the-enrollment). +In this guide, you will learn how to connect to location. If you haven't added an instance yet, follow [this guide](instance-adding.md). ## Connecting to location without MFA diff --git a/using-defguard-for-end-users/resolving-posture-check-failures.md b/using-defguard-for-end-users/resolving-posture-check-failures.md index 6981f3d..b9e1c61 100644 --- a/using-defguard-for-end-users/resolving-posture-check-failures.md +++ b/using-defguard-for-end-users/resolving-posture-check-failures.md @@ -86,7 +86,7 @@ The posture check requires Windows Active Directory domain membership, but the d **Fix:** Join active directory. {% hint style="warning" %} -To join a Windows device to Active Directory you'll need Windows Pro, +To join a Windows device to Active Directory you'll need Windows Pro, Enterprise or Education. Windows Home cannot join an AD domain. {% endhint %} @@ -107,7 +107,7 @@ Enterprise or Education. Windows Home cannot join an AD domain. **Configure the domain** -* Settings -> System -> About -> Domain or workgroup +* Settings -> System -> About -> Domain or workgroup * Click "Change" next to "Rename this computer or change its domain or workgroup"
@@ -126,9 +126,7 @@ The Windows device has not received a security update within the maximum allowed ### `device integrity check failed` -Device integrity is required, but the device did not pass the integrity check. This applies to supported platforms such as macOS and Android. - -#### MacOS +Device integrity is required, but the device did not pass the integrity check. On macOS this means System Integrity Protection is disabled. {% embed url="https://developer.apple.com/documentation/security/disabling-and-enabling-system-integrity-protection#Enable-System-Integrity-Protection" %}