From 5e16a0c8496b9dfc375deeecc029f3fb09e9fac7 Mon Sep 17 00:00:00 2001 From: Jason G <52545545+gongjason@users.noreply.github.com> Date: Mon, 13 Jun 2022 11:38:10 -0400 Subject: [PATCH] Docs - OIDC instructions (#615) * 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 --- docs/docs/administer/upgrade.md | 40 ++++++++++ docs/docs/authenticate/azure-ad.md | 94 ++++++++++++++++++++++ docs/docs/authenticate/google-sso.md | 97 ---------------------- docs/docs/authenticate/google.md | 115 +++++++++++++++++++++++++++ docs/docs/authenticate/index.md | 80 ++++++++++++++++--- docs/docs/authenticate/okta-sso.md | 76 ------------------ docs/docs/authenticate/okta.md | 103 ++++++++++++++++++++++++ 7 files changed, 423 insertions(+), 182 deletions(-) create mode 100644 docs/docs/authenticate/azure-ad.md delete mode 100644 docs/docs/authenticate/google-sso.md create mode 100644 docs/docs/authenticate/google.md delete mode 100644 docs/docs/authenticate/okta-sso.md create mode 100644 docs/docs/authenticate/okta.md diff --git a/docs/docs/administer/upgrade.md b/docs/docs/administer/upgrade.md index f265f6b03..b33fc6fc2 100644 --- a/docs/docs/administer/upgrade.md +++ b/docs/docs/administer/upgrade.md @@ -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 diff --git a/docs/docs/authenticate/azure-ad.md b/docs/docs/authenticate/azure-ad.md new file mode 100644 index 000000000..eff1e82ce --- /dev/null +++ b/docs/docs/authenticate/azure-ad.md @@ -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//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//v2.0/.well-known/openid-configuration", + client_id: "", + 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. diff --git a/docs/docs/authenticate/google-sso.md b/docs/docs/authenticate/google-sso.md deleted file mode 100644 index 4e6fab6ef..000000000 --- a/docs/docs/authenticate/google-sso.md +++ /dev/null @@ -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. diff --git a/docs/docs/authenticate/google.md b/docs/docs/authenticate/google.md new file mode 100644 index 000000000..7233cef87 --- /dev/null +++ b/docs/docs/authenticate/google.md @@ -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//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_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. diff --git a/docs/docs/authenticate/index.md b/docs/docs/authenticate/index.md index 01f0c1242..7ac4e2337 100644 --- a/docs/docs/authenticate/index.md +++ b/docs/docs/authenticate/index.md @@ -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: "", + 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:///.well-known/openid-configuration", + client_id: "", + 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//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 diff --git a/docs/docs/authenticate/okta-sso.md b/docs/docs/authenticate/okta-sso.md deleted file mode 100644 index 75414b17e..000000000 --- a/docs/docs/authenticate/okta-sso.md +++ /dev/null @@ -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. diff --git a/docs/docs/authenticate/okta.md b/docs/docs/authenticate/okta.md new file mode 100644 index 000000000..a854fd8c3 --- /dev/null +++ b/docs/docs/authenticate/okta.md @@ -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//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:///.well-known/openid-configuration", + client_id: "", + 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"}