github-personal/firezone
1
0
Fork 0
mirror of https://github.com/outbackdingo/firezone.git synced 2026-01-27 10:18:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Authentication documentation (Google, Okta) (#483)

Browse Source 
* add links to common configurations

* add Google auth doc

restructure auth section and add start to google sso draft

* Add Okta doc first draft

* update authentication index

* fix wording

* grammar

* suggested changes

- resolved comments
- images wider for visibility
- newline

* complete Google OAuth doc

* lint error + grammar

* complete Okta doc

* ordering + wording

* re-auth instructions

* fixes

* consistent references

* add reference to sso in add users doc

* fix small markdown error
This commit is contained in:
Jason G
2022-03-04 17:15:43 -08:00
committed by GitHub
parent 973d025b97
commit b54684a154
18 changed files with 298 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/_sass/color_schemes/fz.scss
View File

@@ -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;

2
docs/docs/administer/index.md
View File

@@ -1,5 +1,5 @@
---
nav_order: 3
nav_order: 4
layout: default
title: Administer
has_children: true

2
docs/docs/administer/security-considerations.md
View File

@@ -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. |

2
docs/docs/administer/troubleshoot.md
View File

@@ -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.

2
docs/docs/administer/upgrade.md
View File

@@ -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.

97
docs/docs/authenticate/google-sso.md Normal file
View File

@@ -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.

30
docs/docs/authenticate/index.md Normal file
View File

@@ -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"}

76
docs/docs/authenticate/okta-sso.md Normal file
View File

@@ -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.

18
docs/docs/authenticate/web-auth.md Normal file
View File

@@ -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"}

4
docs/docs/deploy/clients.md
View File

@@ -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}

2
docs/docs/reference/index.md
View File

@@ -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.

11
docs/docs/user-guides/add-devices.md
View File

@@ -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"}

11
docs/docs/user-guides/add-users.md
View File

@@ -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}

34
docs/docs/user-guides/authentication.md
View File

@@ -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.

46
docs/docs/user-guides/client-instructions.md
View File

@@ -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)

2
docs/docs/user-guides/index.md
View File

@@ -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.

2
docs/docs/user-guides/whitelist-vpn.md
View File

@@ -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}

9
docs/index.md
View File

@@ -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