diff --git a/docs/_sass/color_schemes/fz.scss b/docs/_sass/color_schemes/fz.scss index 152288485..a1db0e327 100644 --- a/docs/_sass/color_schemes/fz.scss +++ b/docs/_sass/color_schemes/fz.scss @@ -33,6 +33,11 @@ h1, h2, h3, h4, h5, h6 { margin: 1rem; } +strong { + font-weight: 900 !important; + color: $fz-grey-dk-300 !important; +} + // Borders $border-color: $fz-grey-lt-200; diff --git a/docs/docs/administer/index.md b/docs/docs/administer/index.md index cbcb82c6e..b6bf5db82 100644 --- a/docs/docs/administer/index.md +++ b/docs/docs/administer/index.md @@ -1,5 +1,5 @@ --- -nav_order: 3 +nav_order: 4 layout: default title: Administer has_children: true diff --git a/docs/docs/administer/security-considerations.md b/docs/docs/administer/security-considerations.md index c764ac584..75cfd72ed 100644 --- a/docs/docs/administer/security-considerations.md +++ b/docs/docs/administer/security-considerations.md @@ -21,7 +21,7 @@ Shown below is a table of ports used by Firezone services. | Service | Default port | Listen address | Description | | Nginx | `80` `443` | `all` | Public HTTP(S) port for administering Firezone and facilitating authentication. | -| WireGuard | `51820` | `all` | Public WireGuard port used for VPN connections. | +| WireGuard | `51820` | `all` | Public WireGuard port used for VPN sessions. | | Postgresql | `15432` | `127.0.0.1` | Local-only port used for bundled Postgresql server. | | Phoenix | `13000` | `127.0.0.1` | Local-only port used by upstream elixir app server. | diff --git a/docs/docs/administer/troubleshoot.md b/docs/docs/administer/troubleshoot.md index 303866500..bf0058508 100644 --- a/docs/docs/administer/troubleshoot.md +++ b/docs/docs/administer/troubleshoot.md @@ -22,7 +22,7 @@ active, you'll need to ensure these don't conflict with the Firezone rules. ### Internet Connectivity Drops when Tunnel is Active If your Internet connectivity drops whenever you activate your WireGuard -connection, you should make sure that the `FORWARD` chain allows packets +tunnel, you should make sure that the `FORWARD` chain allows packets from your WireGuard clients to the destinations you want to allow through Firezone. diff --git a/docs/docs/administer/upgrade.md b/docs/docs/administer/upgrade.md index c15e14cef..697e61016 100644 --- a/docs/docs/administer/upgrade.md +++ b/docs/docs/administer/upgrade.md @@ -9,7 +9,7 @@ description: > --- --- -Upgrading Firezone will disconnect all VPN connections and require shutting +Upgrading Firezone will disconnect all VPN sessions and require shutting down the Web UI. We recommend a maintenance window of about an hour in case anything goes wrong during the upgrade. diff --git a/docs/docs/authenticate/google-sso.md b/docs/docs/authenticate/google-sso.md new file mode 100644 index 000000000..bb8d69c96 --- /dev/null +++ b/docs/docs/authenticate/google-sso.md @@ -0,0 +1,97 @@ +--- +layout: default +title: Google +nav_order: 1 +parent: Authenticate +description: > + This page contains instructions on setting up Google + as the SSO provider for Firezone. +--- +--- + +Firezone supports Single Sign-On (SSO) through Google Workspace and Cloud Identity. +After successfully configuring SSO with Firezone, users will be prompted to sign +in with their Google credentials in the Firezone portal to authenticate VPN +sessions, and download device configuration files. + +![Firezone Google SSO Login](https://user-images.githubusercontent.com/52545545/156853456-1ab3f041-1002-4c79-a266-82acb5802890.gif){:width="600"} + +To set up SSO, follow the steps below: + +## Step 1 - Configure OAuth Consent Screen + +If this is the first time you are creating a new OAuth client ID, you will +be asked to configure a consent screen. + +**IMPORTANT**: Select `Internal` for user type. This ensures only accounts +belonging to users in your Google Workspace Organization can create device configs. +DO NOT select `External` unless you want to enable anyone with a valid Google Account +to create device configs. + +![OAuth Consent Internal](https://user-images.githubusercontent.com/52545545/156853731-1e4ad1d4-c761-4a28-84db-cd880e3c46a3.png){:width="800"} + +On the App information screen: + +1. **App name**: `Firezone` +1. **App logo**: [Firezone logo](https://user-images.githubusercontent.com/52545545/156854754-da66a9e1-33d5-47f5-877f-eff8b330ab2b.png) +(save link as). +1. **Application home page**: the URL of your Firezone instance. +1. **Authorized domains**: the top level domain of your Firezone instance. + +![OAuth Consent App Info](https://user-images.githubusercontent.com/52545545/156853737-211ab7de-4c8f-4104-b3e8-5586c7a2ce6e.png){:width="800"} + +On the next step add the `.../auth/userinfo.email` scope. + +![OAuth Consent Scopes](https://user-images.githubusercontent.com/52545545/156853748-aed49198-989d-4b48-9e9a-108142bb4f8b.png){:width="800"} + +## Step 2 - Create OAuth Client IDs + +_This section is based off Google's own documentation on +[setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849)._ + +Visit the Google Cloud Console +[Credentials page](https://console.cloud.google.com/apis/credentials) +page, click `+ Create Credentials` and select `OAuth client ID`. + +![Create OAuth Client ID](https://user-images.githubusercontent.com/52545545/155904211-c36095b9-4bbd-44c1-95f8-bb165e314af3.png){:width="800"} + +On the OAuth client ID creation screen: + +1. Set `Application Type` to `Web application` +1. Add an entry to Authorized redirect URIs that consists of appending +`/auth/google/callback` to your Firezone base URL. For example, if your Firezone +instance is available at `https://firezone.example.com`, then you would enter +`https://firezone.example.com/auth/google/callback` here. The redirect URI is +where Google will redirect the user's browser after successful authentication. +Firezone will receive this callback, initiate the user's session, and redirect +the user's browser to the appropriate page depending on the user's role. + +![Create OAuth client ID](https://user-images.githubusercontent.com/52545545/155904581-9a82fc9f-26ce-4fdf-8143-060cbad0a207.png){:width="800"} + +After creating the OAuth client ID, you will be given a Client ID and Client Secret. +These will be used together with the redirect URI entered above to configure +Firezone SSO in Step 3. + +![Copy Client ID and Secret](https://user-images.githubusercontent.com/52545545/155906344-aa3673e1-903a-482f-86fb-75f12fd17f4f.png){:width="800"} + +## Step 3 - Configure Firezone + +Using the client ID, secret, and redirect URI from above, edit the `/etc/firezone/firezone.rb` +configuration file to include the following options: + +```ruby +# set the following variables to the values obtained in step 2 +default['firezone']['authentication']['google']['enabeld'] = true +default['firezone']['authentication']['google']['client_id'] = 'GOOGLE_CLIENT_ID' +default['firezone']['authentication']['google']['client_secret'] = 'GOOGLE_CLIENT_SECRET' +default['firezone']['authentication']['google']['redirect_uri'] = 'GOOGLE_REDIRECT_URI' +``` + +Run the following commands to apply the changes: + +```text +firezone-ctl reconfigure +firezone-ctl restart +``` + +You should now see a `Sign in with Google` button at the root Firezone URL. diff --git a/docs/docs/authenticate/index.md b/docs/docs/authenticate/index.md new file mode 100644 index 000000000..184aef6e3 --- /dev/null +++ b/docs/docs/authenticate/index.md @@ -0,0 +1,30 @@ +--- +layout: default +title: Authenticate +nav_order: 3 +has_children: true +has_toc: false +description: > + This page contains all the authentication methods that Firezone supports. +--- +--- + +Firezone provides the ability to require authentication to download device +configuration files. Firezone supports the following single sign on (SSO) +providers and authentication methods: + +* [Google]({%link docs/authenticate/google-sso.md%}) +* [Okta]({%link docs/authenticate/okta-sso.md%}) +* [Local email/password authentication (default)]({%link docs/authenticate/web-auth.md%}) + +If you wish to use an OAuth provider that is not listed above, +please open a +[GitHub issue](https://github.com/firezone/firezone/issues). + +Periodic re-authentication can be enforced by changing the setting in `settings/security`. +To re-authenticate a VPN session, a user will need to turn off their +VPN session and log in to the Firezone portal (URL specified during +[deployment]({%link docs/deploy/prerequisites.md%}) +). + +![re-authenticate](https://user-images.githubusercontent.com/52545545/155812962-9b8688c1-00af-41e4-96c3-8fb52f840aed.gif){:width="600"} diff --git a/docs/docs/authenticate/okta-sso.md b/docs/docs/authenticate/okta-sso.md new file mode 100644 index 000000000..75414b17e --- /dev/null +++ b/docs/docs/authenticate/okta-sso.md @@ -0,0 +1,76 @@ +--- +layout: default +title: Okta +nav_order: 2 +parent: Authenticate +description: > + This page contains instructions on setting up Okta + as the SSO provider for Firezone. +--- +--- + +Firezone supports Single Sign-On (SSO) through Okta. +After successfully configuring SSO with Firezone, users will be prompted to sign +in with their Okta credentials in the Firezone portal to authenticate VPN +sessions and download device configuration files. + +![Firezone Okta SSO Login](https://user-images.githubusercontent.com/52545545/156855886-5a4a0da7-065c-4ec1-af33-583dff4dbb72.gif){:width="600"} + +To set up SSO, follow the steps below: + +## Step 1 - Create Okta App Integration + +_This section of the guide is based on +[Okta's documentation](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm)._ + +In the Admin Console, go to `Applications > Applications` and click `Create App Integration`. +Set `Sign-in method` to `OICD - OpenID Connect` and `Application type` to `Web application`. + +![Okta Create App Integration](https://user-images.githubusercontent.com/52545545/155907051-64a74d0b-bdcd-4a22-bfca-542dacc8ad20.png){:width="800"} + +![Okta Create Options](https://user-images.githubusercontent.com/52545545/155909125-25d6ddd4-7d0b-4be4-8fbc-dc673bb1f61f.png){:width="800"} + +On the following screen, configure the following settings: + +1. **App Name**: `Firezone` +1. **App logo**: +[Firezone logo](https://user-images.githubusercontent.com/52545545/155907625-a4f6c8c2-3952-488d-b244-3c37400846cf.png) +(save link as). +1. **Sign-in redirect URIs**: Append `/auth/okta/callback` to your Firezone base +URL. For example, if your Firezone instance is available at +`https://firezone.example.com`, then you would enter +`https://firezone.example.com/auth/okta/callback` here. The redirect URI is +where Okta will redirect the user's browser after successful authentication. +Firezone will receive this callback, initiate the user's session, and redirect +the user's browser to the appropriate page depending on the user's role. +1. **Assignments**: +Limit to the groups you wish to provide access to your Firezone instance. + +![Okta Settings](https://user-images.githubusercontent.com/52545545/155907987-caa3318e-4871-488d-b1d4-deb397a17f19.png){:width="800"} + +Once settings are saved, you will be given a Client ID, Client Secret, and Okta Domain. +These 3 values will be used in Step 2 to configure Firezone. + +![Okta credentials](https://user-images.githubusercontent.com/52545545/156463942-7130b4bb-372a-4e27-ae06-7d3405214ec7.png){:width="800"} + +## Step 2 - Configure Firezone + +Using the client ID, secret, and redirect URI from above, edit the `/etc/firezone/firezone.rb` +configuration file to include the following options: + +```ruby +# set the following variables to the values obtained in step 2 +default['firezone']['authentication']['okta']['enabled'] = true +default['firezone']['authentication']['okta']['client_id'] = 'OKTA_CLIENT_ID' +default['firezone']['authentication']['okta']['client_secret'] = 'OKTA_CLIENT_SECRET' +default['firezone']['authentication']['okta']['site'] = 'OKTA_SITE' +``` + +Run the following commands to apply the changes: + +```text +firezone-ctl reconfigure +firezone-ctl restart +``` + +You should now see a `Sign in with Okta` button at the root Firezone URL. diff --git a/docs/docs/authenticate/web-auth.md b/docs/docs/authenticate/web-auth.md new file mode 100644 index 000000000..39a63d133 --- /dev/null +++ b/docs/docs/authenticate/web-auth.md @@ -0,0 +1,18 @@ +--- +layout: default +title: Local Email / Password +nav_order: 10 +parent: Authenticate +description: > + This page contains instructions on setting up local + email and password authentication for Firezone. +--- +--- + +Firezone will use the user's email address and password +to authenticate their VPN session. +You can set the session length to a minimum of 1 hour and maximum of 90 days. +Setting this to Never disables this setting, allowing VPN sessions indefinitely. +This is the default. + +![Add Web Auth](https://user-images.githubusercontent.com/52545545/153466175-0e1c3ec8-aa3a-42a9-a915-748c9432a10c.png){:width="600"} diff --git a/docs/docs/deploy/clients.md b/docs/docs/deploy/clients.md index aced260a1..a3403703b 100644 --- a/docs/docs/deploy/clients.md +++ b/docs/docs/deploy/clients.md @@ -13,11 +13,11 @@ connect to the VPN server: * [Add Users]({%link docs/user-guides/add-users.md%}): Add users to grant them access to your network. * [Client Instructions]({%link docs/user-guides/client-instructions.md%}): -Send these instructions to the user attempting to establish a connection. +Send these instructions to the user attempting to establish a VPN session. See [User Guides]({%link docs/user-guides/index.md%}) for additional information on common tasks. \ [Previous: Install Server]({%link docs/deploy/server.md%}){:.btn.mr-2} -[Related: Troubleshooting]({%link docs/administer/troubleshoot.md%}){:.btn.btn-purple} +[Related: Authenticate]({%link docs/authenticate/index.md%}){:.btn.btn-purple} diff --git a/docs/docs/reference/index.md b/docs/docs/reference/index.md index d2da8238d..a09203e34 100644 --- a/docs/docs/reference/index.md +++ b/docs/docs/reference/index.md @@ -1,7 +1,7 @@ --- layout: default title: Reference -nav_order: 5 +nav_order: 99 has_children: true description: > This section contains comprehensive references for different aspects of using Firezone. diff --git a/docs/docs/user-guides/add-devices.md b/docs/docs/user-guides/add-devices.md index 3cbaf3ded..ab1079bd1 100644 --- a/docs/docs/user-guides/add-devices.md +++ b/docs/docs/user-guides/add-devices.md @@ -8,8 +8,15 @@ description: > --- --- -Add a device through the Web UI by clicking the "Add Device" button under -`/devices` or `/users`. +**We recommend asking users to generate their own device configs so the private +key is only exposed to them.** Users can follow instructions on the +[Client Instructions]({%link docs/user-guides/client-instructions.md%}) +page to generate their own device configs. + +## Admin device config generation + +Firezone admins can generate device configs for all users. This can be done by +clicking the "Add Device" button under `/devices` or `/users`. ![add device under devices](https://user-images.githubusercontent.com/52545545/153468000-06b2ea64-30b3-4f62-a2f4-043e5f231cb4.png){:width="600"} diff --git a/docs/docs/user-guides/add-users.md b/docs/docs/user-guides/add-users.md index ff64f8712..f00d03a60 100644 --- a/docs/docs/user-guides/add-users.md +++ b/docs/docs/user-guides/add-users.md @@ -14,10 +14,15 @@ them access to your network. This is done through the Web UI. ## Web UI Add a user by clicking the "Add User" button under `/users`. You will be asked -to specify an email and a password for the user. These credentials will be used -to authenticate the user so they are able to establish the connection. +to specify an email and a password for the user. Firezone also offers other ways +to grant access to users in your organization. See +[Authenticate]({%link docs/authenticate/index.md%}) +for more information. + +These credentials will be used +to authenticate the user so they are able to establish the tunnel. ![add user](https://user-images.githubusercontent.com/52545545/153469244-c007c305-bfb0-4da7-a40c-6f41fa458c76.png){:width="600"} \ -[Next: Add Devices]({%link docs/user-guides/add-devices.md%}){:.btn.btn-purple} +[Related: Authenticate]({%link docs/authenticate/index.md%}){:.btn.btn-purple} diff --git a/docs/docs/user-guides/authentication.md b/docs/docs/user-guides/authentication.md deleted file mode 100644 index d489a9fdc..000000000 --- a/docs/docs/user-guides/authentication.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -layout: default -title: Authentication -nav_order: 4 -parent: User Guides -description: > - This page contains all the authentication methods that Firezone supports. ---- ---- - -Firezone provides the ability to require authentication to establish VPN connections. - -**Note**: To re-authenticate a VPN session, a user will need to turn off their -VPN connection and log in to the Firezone portal (URL specified during -[deployment]({%link docs/deploy/prerequisites.md%}) -). - -![re-authenticate](https://user-images.githubusercontent.com/52545545/155812962-9b8688c1-00af-41e4-96c3-8fb52f840aed.gif){:width="600"} - -## Web Authentication (default) - -Firezone will use the user's email address and password -to authenticate their VPN session. -You can set the session length to a minimum of 1 hour and maximum of 90 days. -Setting this to Never disables this setting, allowing VPN sessions indefinitely. -This is the default. - -![Add Web Auth](https://user-images.githubusercontent.com/52545545/153466175-0e1c3ec8-aa3a-42a9-a915-748c9432a10c.png){:width="600"} - -## Single Sign On (coming soon) - -Single Sign-On is currently under development! -[Contact us](https://e04kusl9oz5.typeform.com/to/Ls4rbMSR#source=docs) -to share your requirements and be notified when it's available. diff --git a/docs/docs/user-guides/client-instructions.md b/docs/docs/user-guides/client-instructions.md index 4ac9188c1..90273472c 100644 --- a/docs/docs/user-guides/client-instructions.md +++ b/docs/docs/user-guides/client-instructions.md @@ -5,8 +5,16 @@ nav_order: 5 parent: User Guides description: > Install the WireGuard client and import the configuration - file sent by the administrator to establish a connection. + file sent by the administrator to establish a VPN session. --- + +## Table of contents + +{: .no_toc} + +1. TOC +{:toc} + --- _This is written for the end user who will be connecting @@ -14,8 +22,8 @@ to the Firezone VPN server._ ## Install and Setup -Follow this guide to establish a connection to the -VPN server through the WireGuard native client. +Follow this guide to establish a VPN session +through the WireGuard native client. ### Step 1 - Install the native WireGuard client @@ -29,20 +37,27 @@ Firezone is compatible with the official WireGuard clients found here: For operating systems not listed above see the Official WireGuard site: [ https://www.wireguard.com/install/](https://www.wireguard.com/install/). -### Step 2 - Download the connection config file +### Step 2 - Download the device config file -This will end in `.conf` and be sent to you by the Firezone administrator. +The device config file can either be obtained from your Firezone administrator +or self-generated via the Firezone portal. + +To self generate a device config file, visit the domain provided by your Firezone +administrator. This URL will be specific to your company +(in this example it is `https://firezone.example.com`) + +![Firezone Okta SSO Login](https://user-images.githubusercontent.com/52545545/156855886-5a4a0da7-065c-4ec1-af33-583dff4dbb72.gif){:width="600"} ### Step 3 - Add the config to the client Open the WireGuard client and import the `.conf` file. -Turn on the VPN connection by toggling the `Activate` switch. +Activate the VPN session by toggling the `Activate` switch. -![Client Instructions]({{site.asset_urls.client_instructions}}){:width="600"} +![Activate Tunnel](https://user-images.githubusercontent.com/52545545/156859686-41755bf7-a9ad-42ec-af5e-9f0734d962db.gif) -## Authenticating your connection +## Re-authenticating your session -If your network admin has required periodic authentication to maintain your VPN connection, +If your network admin has required periodic authentication to maintain your VPN session, follow the steps below. You will need: * **URL of the Firezone portal**: Ask your Network Admin for the link. @@ -50,4 +65,17 @@ follow the steps below. You will need: Admin. If your company is using a Single Sign On provider (like Google or Okta), the Firezone portal will prompt you to authenticate via that provider. +### Step 1 - Deactivate VPN session + +![WireGuard Deactivate](https://user-images.githubusercontent.com/52545545/156859259-a3d386ce-b304-4caa-96e6-a8e7ca96d098.png) + +### Step 2 - Re-authenticate + +Visit the URL of your Firezone portal and log in using credentials provided by your +network admin. + ![re-authenticate](https://user-images.githubusercontent.com/52545545/155812962-9b8688c1-00af-41e4-96c3-8fb52f840aed.gif){:width="600"} + +### Step 3 - Activate VPN session + +![Activate Session](https://user-images.githubusercontent.com/52545545/156859636-fde95fc5-5b9c-4697-9108-2f277ed3fbef.png) diff --git a/docs/docs/user-guides/index.md b/docs/docs/user-guides/index.md index ba9519f3c..d27d98fbd 100644 --- a/docs/docs/user-guides/index.md +++ b/docs/docs/user-guides/index.md @@ -1,7 +1,7 @@ --- layout: default title: User Guides -nav_order: 4 +nav_order: 5 has_children: true description: > This section contains guides for common tasks. diff --git a/docs/docs/user-guides/whitelist-vpn.md b/docs/docs/user-guides/whitelist-vpn.md index 72d0117bf..ec8527816 100644 --- a/docs/docs/user-guides/whitelist-vpn.md +++ b/docs/docs/user-guides/whitelist-vpn.md @@ -64,4 +64,4 @@ has been enabled, configuration may be required to ensure the destination IP of the protected resource is included in the `Allowed IPs`. \ -[Related: Authentication]({%link docs/user-guides/authentication.md%}){:.btn.btn-purple} +[Related: Authenticate]({%link docs/authenticate/index.md%}){:.btn.btn-purple} diff --git a/docs/index.md b/docs/index.md index bfd9e8a79..b89d2b39c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,6 +25,15 @@ These docs explain how to deploy, configure, and use Firezone. learn how to use Firezone and troubleshoot common issues. Consult this section after you successfully deploy the Firezone server. +## Common Configuration Guides + +1. [Split Tunneling]({% link docs/user-guides/split-tunnel.md %}): +Only route traffic to certain IP ranges through the VPN. +1. [Whitelisting with VPN]({% link docs/user-guides/whitelist-vpn.md %}): +Configure a VPN server with a static IP address. +1. [Reverse Tunnels]({% link docs/user-guides/reverse-tunnel.md %}): +Establish tunnels between multiple peers. + ## Get Help If you're looking for help installing, configuring, or using Firezone, we're