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

Docs - OIDC instructions (#615)

Browse Source 
* add azure ad docs

* re-add idp instructions

* update azure AD doc

* edit google auth doc for oidc

* update okta documentation for oidc

* update azure gif

* fix lint errors

* title case

* update for review notes

* changing references of base URL to external URL

* make notes consistent to discourage basic OAuth vs OIDC

* add offline_access scope for azure

* wip upgrade docs

* update azure doc and upgrade instructions

* update Okta doc

* trailing whitespace

* add docs for offline access

* consistent code placeholder formatting

* update upgrade docs

* update image title
This commit is contained in:
Jason G
2022-06-13 11:38:10 -04:00
committed by GitHub
parent f7c1a545ea
commit 5e16a0c849
7 changed files with 423 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -25,6 +25,46 @@ To upgrade Firezone, follow these steps:
Occasionally problems arise. If you hit any, please let us know by [filing an
issue](https://github.com/firezone/firezone/issues/new/choose).
## Upgrading from 0.3.x to >= 0.3.16
Follow the instructions below based on your current version and setup:
### I have an existing OIDC integration
Upgrading to >= 0.3.16 requires the `offline_access` scope for some OIDC providers
to obtain a refresh token.
This ensures Firezone syncs with the identity provider and VPN access is terminated
once the user is removed. Previous versions of Firezone do not have this capability.
Users who are removed from your identity provider will still have active VPN sessions
in some cases.
For OIDC providers that support the `offline_access` scope, you will need to add
`offline_access` to the `scope` parameter of your OIDC config. The
Firezone configuration file can be found at `/etc/firezone/firezone.rb` and requires
running `firezone-ctl reconfigure` to pick up the changes.
If Firezone is able to successfully retrieve the refresh token, you will see
the **OIDC Connections** heading in the user details page of the web UI for
users authenticated through your OIDC provider.
![OIDC Connections](https://user-images.githubusercontent.com/52545545/173169922-b0e5f2f1-74d5-4313-b839-6a001041c07e.png)
If this does not work, you will need to delete your existing OAuth app
and repeat the OIDC setup steps to
[create a new app integration]({%link docs/authenticate/index.md%}).
### I have an existing OAuth integration
Prior to 0.3.11, Firezone used pre-configured OAuth2 providers. Follow the
instructions [here]({%link docs/authenticate/index.md%}) to migrate
to OIDC.
### I have not integrated an identity provider
No action needed. You can follow the instructions
[here]({%link docs/authenticate/index.md%})
to enable SSO through an OIDC provider.
## Upgrading from 0.3.1 to >= 0.3.2
The configuration option `default['firezone']['fqdn']` has been removed in favor

94
docs/docs/authenticate/azure-ad.md Normal file
View File

@@ -0,0 +1,94 @@
---
layout: default
title: Azure Active Directory
nav_order: 3
parent: Authenticate
description: >
This page contains instructions on integrating Azure AD as
an identity provider for Firezone
---
---
Firezone supports Single Sign-On (SSO) using Azure Active Directory through the generic
OIDC connector. This guide will walk you through how to obtain the following
config settings required for the integration:
1. `discovery_document_uri`: This URL returns a JSON with information to
construct a request to the OpenID server.
1. `client_id`: The client ID of the application.
1. `client_secret`: The client secret of the application.
1. `redirect_uri`: Instructs OIDC provider where to redirect after authentication.
This should be your Firezone `EXTERNAL_URL + /auth/oidc/<provider_key>/callback/`
(e.g. `https://firezone.example.com/auth/oidc/azure/callback/`).
1. `response_type`: Set to `code`.
1. `scope`: [OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to `openid email profile offline_access`
to provide Firezone with the user's email in the returned claims.
1. `label`: The button label text that shows up on your Firezone login screen.
![Azure SSO](https://user-images.githubusercontent.com/52545545/168922621-1f0f4dea-adfc-4e15-a140-a2f213676103.gif){:width="600"}
## Obtain Config Settings
_This guide is adapted from the [Azure Active Directory documentation](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/auth-oidc)._
Navigate to the Azure Active Directory page on the Azure portal.
Select the App registrations link under the Manage menu, click
`New Registration`, and register after entering the following:
1. `Name`: `Firezone`
1. `Supported account types`: `(Default Directory only - Single tenant)`
1. `Redirect URI`: This should be your firezone `EXTERNAL_URL + /auth/oidc/azure/callback/`
(e.g. `https://firezone.example.com/auth/oidc/azure/callback/`).
Make sure you include the trailing slash.
**This will be the `redirect_uri` value**.
![App Registration](https://user-images.githubusercontent.com/52545545/168722092-716c8448-4dc4-4d7a-a25c-1af701a57744.png){:width="800"}
After registering, open the details view of the application and copy the
`Application (client) ID`. **This will be the `client_id` value**. Next, open
the endpoints menu to retrieve the `OpenID Connect metadata document`.
**This will be the `discovery_document_uri` value**.
![Azure Client ID](https://user-images.githubusercontent.com/52545545/168724099-100e4a9a-0bf6-42f6-b0ee-13a4c9a8da23.png){:width="800"}
Next, select the Certificates & secrets link under the Manage menu and
create a new client secret. Copy the client secret - **this will be the
`client_secret` value**.
![Add a client secret](https://user-images.githubusercontent.com/52545545/168720697-1a28d2c1-4108-459c-9915-4397a4108818.png){:width="800"}
Lastly, select the API permissions link under the Manage menu,
click `Add a permission`, and select `Microsoft Graph`. Add `email`, `openid`,
`offline_access` and `profile` to the required permissions.
![Permissions](https://user-images.githubusercontent.com/52545545/171556138-26de489b-7de5-4b53-91dc-dc8058f0f901.png){:width="800"}
## Integrate With Firezone
Edit `/etc/firezone/firezone.rb` to include the options below.
```ruby
# Using Azure Active Directory as the SSO identity provider
default['firezone']['authentication']['oidc'] = {
azure: {
discovery_document_uri: "https://login.microsoftonline.com/<TENANT_ID>/v2.0/.well-known/openid-configuration",
client_id: "<CLIENT_ID>",
client_secret: "<CLIENT_SECRET>",
redirect_uri: "https://firezone.example.com/auth/oidc/azure/callback",
response_type: "code",
scope: "openid email profile offline_access",
label: "Azure"
}
}
```
Run `firezone-ctl reconfigure`and `firezone-ctl restart` to update the application.
You should now see a `Sign in with Azure` button at the root Firezone URL.
## Restricting Access to Certain Members
Azure AD allows admins to restrict app access to a subset of users within your
organization. See Microsoft's
[documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-restrict-your-app-to-a-set-of-users)
for more information on how to do this.

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

@@ -1,97 +0,0 @@
---
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']['enabled'] = 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.

115
docs/docs/authenticate/google.md Normal file
View File

@@ -0,0 +1,115 @@
---
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) using Google Workspace and Cloud Identity
through the generic OIDC connector. This guide will walk you through how to
obtain the following config settings required for the integration:
1. `discovery_document_uri`: This URL returns a JSON with information to
construct a request to the OpenID server.
1. `client_id`: The client ID of the application.
1. `client_secret`: The client secret of the application.
1. `redirect_uri`: Instructs OIDC provider where to redirect after authentication.
This should be your Firezone `EXTERNAL_URL + /auth/oidc/<provider_key>/callback/`
(e.g. `https://firezone.example.com/auth/oidc/google/callback/`).
1. `response_type`: Set to `code`.
1. `scope`: [OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to `openid email profile`
to provide Firezone with the user's email in the returned claims.
1. `label`: The button label text that shows up on your Firezone login screen.
![Firezone Google SSO Login](https://user-images.githubusercontent.com/52545545/156853456-1ab3f041-1002-4c79-a266-82acb5802890.gif){:width="600"}
Note: Previously, Firezone used pre-configured Oauth2 providers. We've moved to
OIDC based authentication, which allows for any OpenID Connect provider
(Google, Okta, Dex) to be used for authentication.
We strongly recommend transitioning your existing Google or Okta-based SSO
configuration to the generic OIDC-based configuration format described here.
We'll be removing the Google-specific and Okta-specific SSO functionality
in a future release.
To set up SSO, follow the steps below:
## Obtain Config Settings
### Step 1 - OAuth Config 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 following scopes:
![OAuth Consent Scopes](https://user-images.githubusercontent.com/52545545/168910904-57e86d71-b8ae-4b11-8b9c-bf8a19127065.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 your Firezone `EXTERNAL_URL + /auth/oidc/google/callback/`
(e.g. `https://firezone.example.com/auth/oidc/google/callback/`) as an entry to
Authorized redirect URIs.
![Create OAuth client ID](https://user-images.githubusercontent.com/52545545/168910923-819300d3-b0c2-49a6-81ee-884dce471362.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 in the next step.
![Copy Client ID and Secret](https://user-images.githubusercontent.com/52545545/168913326-10e694d2-cda0-4ed3-b401-2406b36af7c0.png){:width="800"}
## Integrate With Firezone
Edit `/etc/firezone/firezone.rb` to include the options below.
```ruby
# Using Google as the SSO identity provider
default['firezone']['authentication']['oidc'] = {
google: {
discovery_document_uri: "https://accounts.google.com/.well-known/openid-configuration",
client_id: "<CLIENT_ID>",
client_secret: "<CLIENT_SECRET>",
redirect_uri: "https://firezone.example.com/auth/oidc/google/callback",
response_type: "code",
scope: "openid email profile",
label: "Google"
}
}
```
Run `firezone-ctl reconfigure`and `firezone-ctl restart` to update the application.
You should now see a `Sign in with Google` button at the root Firezone URL.

80
docs/docs/authenticate/index.md
View File

@@ -5,21 +5,83 @@ nav_order: 3
has_children: true
has_toc: false
description: >
This page contains all the authentication methods that Firezone supports.
This page documents 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:
Firezone can be configured to require authentication before users can generate
or download device configuration files. Optionally,
[periodic re-authentication](#enforce-periodic-re-authentication)
can also be required for users to maintain their VPN session.
* [Google]({%link docs/authenticate/google-sso.md%})
* [Okta]({%link docs/authenticate/okta-sso.md%})
![Azure SSO](https://user-images.githubusercontent.com/52545545/168922621-1f0f4dea-adfc-4e15-a140-a2f213676103.gif){:width="600"}
By default, Firezone uses local email/password authentication, but can also
support integration with any generic OpenID Connect
(OIDC) identity provider. This allows users to sign in to Firezone using
their credentials from Okta, Google, Azure AD, or your own custom identity provider.
## Integrating A Generic OIDC Provider
The example below details the config settings required by Firezone to enable SSO
through an OIDC provider. The configuration file can be found at
`/etc/firezone/firezone.rb`. To pick up changes, run `firezone-ctl reconfigure`
and `firezone-ctl restart` to update the application.
```ruby
# This is an example using Google and Okta as an SSO identity provider.
# Multiple OIDC configs can be added to the same Firezone instance.
default['firezone']['authentication']['oidc'] = {
google: {
discovery_document_uri: "https://accounts.google.com/.well-known/openid-configuration",
client_id: "<GOOGLE_CLIENT_ID>",
client_secret: "<GOOGLE_CLIENT_SECRET>",
redirect_uri: "https://firezone.example.com/auth/oidc/google/callback",
response_type: "code",
scope: "openid email profile",
label: "Google"
},
okta: {
discovery_document_uri: "https://<OKTA_DOMAIN>/.well-known/openid-configuration",
client_id: "<OKTA_CLIENT_ID>",
client_secret: "<OKTA_CLIENT_SECRET>",
redirect_uri: "https://firezone.example.com/auth/oidc/okta/callback",
response_type: "code",
scope: "openid email profile offline_access",
label: "Okta"
}
}
```
1. `discovery_document_uri`: This URL returns a JSON with information to
construct a request to the OpenID server.
1. `client_id`: The client ID of the application.
1. `client_secret`: The client secret of the application.
1. `redirect_uri`: Instructs OIDC provider where to redirect after authentication.
This should be your Firezone `EXTERNAL_URL + /auth/oidc/<provider_key>/callback/`
(e.g. `https://firezone.example.com/auth/oidc/google/callback/`).
1. `response_type`: Set to `code`.
1. `scope`: [OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to `openid email profile`
or `openid email profile offline_access` depending on the provider.
1. `label`: The button label text that shows up on your Firezone login screen.
We've included instructions on how to set up Firezone with several popular
identity providers:
* [Azure AD]({%link docs/authenticate/azure-ad.md%})
* [Google]({%link docs/authenticate/google.md%})
* [Okta]({%link docs/authenticate/okta.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).
If your identity provider is not listed above, but has a generic OIDC
connector, please consult their documentation to find instructions on obtaining
the config settings required.
Join our [Slack](https://www.firezone.dev/slack) to request additional help or
open a [Github Issue](https://github.com/firezone/firezone/issues) to request
additional documentation for your provider.
## Enforce Periodic Re-authentication

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

@@ -1,76 +0,0 @@
---
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.

103
docs/docs/authenticate/okta.md Normal file
View File

@@ -0,0 +1,103 @@
---
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) using Okta
through the generic OIDC connector. This guide will walk you through how to
obtain the following config settings required for the integration:
1. `discovery_document_uri`: This URL returns a JSON with information to
construct a request to the OpenID server.
1. `client_id`: The client ID of the application.
1. `client_secret`: The client secret of the application.
1. `redirect_uri`: Instructs OIDC provider where to redirect after authentication.
This should be your Firezone `EXTERNAL_URL + /auth/oidc/<provider_key>/callback/`
(e.g. `https://firezone.example.com/auth/oidc/okta/callback/`).
1. `response_type`: Set to `code`.
1. `scope`: [OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)
to obtain from your OIDC provider. This should be set to `openid email profile offline_access`
to provide Firezone with the user's email in the returned claims.
1. `label`: The button label text that shows up on your Firezone login screen.
![Firezone Okta SSO Login](https://user-images.githubusercontent.com/52545545/156855886-5a4a0da7-065c-4ec1-af33-583dff4dbb72.gif){:width="600"}
**Note:** Previously, Firezone used pre-configured Oauth2 providers. We've moved
to OIDC based authentication, which allows for any OpenID Connect provider
(Google, Okta, Dex) to be integrated.
We strongly recommend transitioning your existing Google or Okta-based SSO
configuration to the generic OIDC-based configuration format described here.
We'll be removing the Google-specific and Okta-specific SSO functionality
in a future release.
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 Options](https://user-images.githubusercontent.com/52545545/168918378-0dd9f705-2544-412d-bbbe-4a7cd9253907.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. **Grant Type**: Check the **Refresh Token** box. This ensures Firezone syncs
with the identity provider and VPN access is terminated once the user is removed.
1. **Sign-in redirect URIs**: Add your Firezone `EXTERNAL_URL + /auth/oidc/okta/callback/`
(e.g. `https://firezone.example.com/auth/oidc/okta/callback/`) as an entry to
Authorized redirect URIs.
1. **Assignments**:
Limit to the groups you wish to provide access to your Firezone instance.
![Okta Settings](https://user-images.githubusercontent.com/52545545/172768478-e8be516d-aa0a-4882-b017-adc938bbd10b.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/172768856-8a373d56-1362-4fc3-a747-3c84f0e76dae.png){:width="800"}
## Integrate With Firezone
Edit `/etc/firezone/firezone.rb` to include the options below. Your `discovery_document_url`
will be `/.well-known/openid-configuration` appended to the end of your `okta_domain`.
```ruby
# Using Okta as the SSO identity provider
default['firezone']['authentication']['oidc'] = {
okta: {
discovery_document_uri: "https://<OKTA_DOMAIN>/.well-known/openid-configuration",
client_id: "<CLIENT_ID>",
client_secret: "<CLIENT_SECRET>",
redirect_uri: "https://firezone.example.com/auth/oidc/okta/callback",
response_type: "code",
scope: "openid email profile offline_access",
label: "Okta"
}
}
```
Run `firezone-ctl reconfigure`and `firezone-ctl restart` to update the application.
You should now see a **Sign in with Okta** button at the root Firezone URL.
## Restricting Access to Certain Users
Okta can limit the users with access to the Firezone app. To do this,
go to the Assignments tab of the Firezone App Integration in your Okta
Admin Console.
![Okta Assignments](https://user-images.githubusercontent.com/52545545/172766608-b95e20e2-eb58-4085-b532-84386de1ea23.png){:width="800"}