diff --git a/website/src/app/kb/authenticate/email/readme.mdx b/website/src/app/kb/authenticate/email/readme.mdx index 299933887..f951395c0 100644 --- a/website/src/app/kb/authenticate/email/readme.mdx +++ b/website/src/app/kb/authenticate/email/readme.mdx @@ -4,7 +4,7 @@ import SupportOptions from "@/components/SupportOptions"; -# Email (OTP) authentication +# Email (OTP) Authentication @@ -32,8 +32,17 @@ short-lived and can only be used to authenticate once. The email authentication connector can be **disabled completely** for your account, forcing all users and admins to authenticate with another connector. -However, this can lead to issues signing in if one of your other authentication -connectors stops working. For that reason, you may want to leave the email -authentication connector enabled with at least one admin for recovery purposes. +This can increase security by reducing the number of potential entrypoints into +your Firezone account. + +To do so, navigate to `Settings -> Identity providers`, select the Email +provider in the list, and then click `Disable` in the upper-right. + + + Disabling the email provider can lead to issues signing in if all of your + other connectors stop working. For that reason, you may want to leave the + email authentication connector enabled with at least one admin assigned for + recovery purposes. + diff --git a/website/src/app/kb/authenticate/entra/readme.mdx b/website/src/app/kb/authenticate/entra/readme.mdx index fc9e65dc3..245060415 100644 --- a/website/src/app/kb/authenticate/entra/readme.mdx +++ b/website/src/app/kb/authenticate/entra/readme.mdx @@ -3,9 +3,9 @@ import PlanBadge from "@/components/PlanBadge"; import Image from "next/image"; import Link from "next/link"; - + -# SSO + Sync with Microsoft Entra ID +# SSO with Microsoft Entra ID @@ -13,13 +13,11 @@ Firezone integrates with [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) using a custom connector that supports both authentication and directory sync. Use this guide if you're looking to setup SSO with Microsoft Entra ID for your -Firezone Enterprise account and want to automatically sync users and groups from -Microsoft Entra ID to Firezone. +Firezone account and optionally sync users and groups from Microsoft Entra ID to +Firezone. - If you're just looking to authenticate users against Microsoft Entra ID - **without** automatic directory sync, use our [universal OIDC - connector](/kb/authenticate/oidc) instead, available on all plans. + Directory sync is supported for the **Enterprise** plan only. ## Overview @@ -27,9 +25,9 @@ Microsoft Entra ID to Firezone. The Firezone Microsoft Entra ID connector integrates with Microsoft's identity APIs to support user authentication and directory sync. -Users and groups are synced every few minutes to ensure that your Firezone -account remains up-to-date with the latest identity data from Entra ID. -[Read more](/kb/authenticate/directory-sync) about how sync works. +On Enterprise plans, users and groups are synced every few minutes to ensure +that your Firezone account remains up-to-date with the latest identity data from +Entra ID. [Read more](/kb/authenticate/directory-sync) about how sync works. ## Setup @@ -268,7 +266,14 @@ In the next screen, ensure the following OpenId permissions are selected: /> -Next, make sure the following Group and User permissions are selected: + + +#### Directory sync permissions + + + +For Enterprise plans, make sure the following additional Group and User +permissions are selected: - `Group.Read.All` - `GroupMember.Read.All` @@ -419,8 +424,8 @@ Go back to the setup page in the Firezone admin portal, ensure all fields are filled out, and click **Connect Identity Provider**. - All users and groups are synced by default. You can limit which users and - groups are synced in the [Enteprise + If directory sync is enabled, all users and groups are synced by default. You + can limit which users and groups are synced in the [Enteprise Applications](https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview) section of the Azure portal. See the [Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-restrict-your-app-to-a-set-of-users) @@ -428,6 +433,6 @@ filled out, and click **Connect Identity Provider**. If you get successfully redirected back to your Firezone admin dashboard, you're -done! Your Entra ID provider is now successfully configured. The first sync will -occur within about 10 minutes. After that, users will be able to authenticate to -Firezone using their Entra ID accounts. +done! Your Entra ID provider is now successfully configured. If directory sync +is enabled, the first sync will occur within about 10 minutes. After that, users +will be able to authenticate to Firezone using their Entra ID accounts. diff --git a/website/src/app/kb/authenticate/google/readme.mdx b/website/src/app/kb/authenticate/google/readme.mdx index 90f20ff58..6e8a7c04e 100644 --- a/website/src/app/kb/authenticate/google/readme.mdx +++ b/website/src/app/kb/authenticate/google/readme.mdx @@ -3,39 +3,37 @@ import PlanBadge from "@/components/PlanBadge"; import Image from "next/image"; import Link from "next/link"; - + -# SSO + Sync with Google Workspace +# SSO with Google Workspace Firezone integrates with [Google Workspace](https://workspace.google.com) using a custom connector that supports both authentication and directory sync. Use this guide if you're looking to setup SSO with Google Workspace for your -Firezone Enterprise account and want to automatically sync users, groups, and -organizational units from Google Workspace to Firezone. +Firezone account and optionally sync users, groups, and organizational units +from Google Workspace to Firezone. - If you're just looking to authenticate users against Google Workspace - **without** automatic directory sync, use our [universal OIDC - connector](/kb/authenticate/oidc) instead, available on all plans. + Directory sync is supported for the **Enterprise** plan only. ## Overview -The Firezone Google Workspace connector integrates with Google's identity APIs -to support user authentication and directory sync. +The Firezone Google Workspace connector integrates with Google's OAuth and +identity APIs to support user authentication and directory sync. -Users, groups, and organizational units are synced every few minutes to ensure -that your Firezone account remains up-to-date with the latest identity data from -Google Workspace. [Read more](/kb/authenticate/directory-sync) about how sync -works. +On Enteprise plans, users, groups, and organizational units are synced every few +minutes to ensure that your Firezone account remains up-to-date with the latest +identity data from Google Workspace. +[Read more](/kb/authenticate/directory-sync) about how sync works. ## Setup Setting up the Google Workspace connector is similar to the process of setting -up a universal OIDC connector. The main difference is the addition of a few -extra read-only scopes needed to enable sync. +up a universal OIDC connector for any other provider. The main difference is the +addition of a few extra read-only scopes needed to enable sync. Follow the steps below to setup the Google Workspace connector. @@ -69,11 +67,21 @@ Click **CREATE** after you've filled in the fields above. /> -### Step 2: Enable the Admin SDK API + -[Visit this link](https://console.cloud.google.com/apis/library/admin.googleapis.com) +### Step 2 (optional): Enable the Admin SDK API + + + +If you're on the Enterprise plan, +[visit this link](https://console.cloud.google.com/apis/library/admin.googleapis.com) to enable the Admin SDK API for the project you just created in Step 1. +If not, skip ahead to [Step 3](#step-3-configure-the-oauth-consent-screen). + +This is used to allow Firezone to read users, groups and organizational units +from your Google Workspace account. + **Important**: Ensure the **Firezone Connector** project you created in Step 1 is selected before clicking the "ENABLE" button. @@ -142,31 +150,25 @@ Click **SAVE AND CONTINUE**. ### Step 4: Configure scopes OAuth scopes determine what information the Firezone connector is allowed to -receive when a user authenticates. Firezone requires the following scopes to -authenticate users and sync users and groups with your Google Workspace account: +receive when a user authenticates. + +Firezone requires the following scopes to authenticate users on **all** plan +levels: - `openid`: Reserved scope required by all OpenID Connect integrations. - `profile`: Provides information such as the user's username, given name, - surname, and so forth. + surname, etc. - `email`: The user's email address. + +If you're on the Enterprise plan, you'll need to add the following additional +scopes to sync users, groups, and organizational units: + - `https://www.googleapis.com/auth/admin.directory.orgunit.readonly`: Required - to sync Organization Units. + to sync organizational units. - `https://www.googleapis.com/auth/admin.directory.group.readonly`: Required to - sync Groups. + sync groups. - `https://www.googleapis.com/auth/admin.directory.user.readonly`: Required to - sync Users. - -```text -openid -profile -email -https://www.googleapis.com/auth/admin.directory.orgunit.readonly -https://www.googleapis.com/auth/admin.directory.group.readonly -https://www.googleapis.com/auth/admin.directory.user.readonly -``` - -Click **ADD OR REMOVE SCOPES** and copy-paste the above scopes into the -**Manually add scopes** field. + sync users. +Click **ADD OR REMOVE SCOPES** and copy-paste the scopes below depending on your +plan level into the **Manually add scopes** field. + + + +##### Starter and Team plans + + + +``` +openid +profile +email +``` + + + +##### Enterprise plan scopes + + + +``` +openid +profile +email +https://www.googleapis.com/auth/admin.directory.orgunit.readonly +https://www.googleapis.com/auth/admin.directory.group.readonly +https://www.googleapis.com/auth/admin.directory.user.readonly +``` + Then click **UPDATE** to make sure they're applied. If you get successfully redirected back to your Firezone admin dashboard, you're -done! Your Google Workspace connector is now successfully configured. The first -sync will occur within about 10 minutes. After that, users will be able to -authenticate to Firezone using their Google Workspace accounts. +done! Your Google Workspace connector is now successfully configured. If +directory sync is enabled, the first sync will occur within about 10 minutes. +After that, users will be able to authenticate to Firezone using their Google +Workspace accounts. diff --git a/website/src/app/kb/authenticate/okta/readme.mdx b/website/src/app/kb/authenticate/okta/readme.mdx index bf13ff84e..1810bb2f4 100644 --- a/website/src/app/kb/authenticate/okta/readme.mdx +++ b/website/src/app/kb/authenticate/okta/readme.mdx @@ -3,31 +3,28 @@ import PlanBadge from "@/components/PlanBadge"; import Image from "next/image"; import Link from "next/link"; - + -# SSO + Sync with Okta +# SSO with Okta Firezone integrates with Okta using a custom connector that supports both authentication and directory sync. Use this guide if you're looking to setup SSO -with Okta for your Firezone Enterprise account and want to automatically sync -users and groups from Okta to Firezone. +with Okta for your Firezone account and optionally sync users and groups from +Okta to Firezone. - If you're just looking to authenticate users against Okta **without** - automatic directory sync, use our [universal OIDC - connector](/kb/authenticate/oidc) instead, available on all plans. + Directory sync is supported for the **Enterprise** plan only. - ## Overview The Firezone Okta connector integrates with Okta's APIs to support user authentication and directory sync. -Users and groups are synced every few minutes to ensure that your Firezone -account remains up-to-date with the latest identity data from Okta. -[Read more](/kb/authenticate/directory-sync) about how sync works. +On Enterprise plans, users and groups are synced every few minutes to ensure +that your Firezone account remains up-to-date with the latest identity data from +Okta. [Read more](/kb/authenticate/directory-sync) about how sync works. ## Setup @@ -208,7 +205,14 @@ In the app integration settings in Okta, click **Assignments** and then the /> -Ensure the `okta.groups.read` and `okta.users.read` scopes are granted. + + +#### Add directory sync scopes + + + +For Enterprise plans, ensure the `okta.groups.read` and `okta.users.read` scopes +are granted. Disabling the email provider can lock you out of your account in the event @@ -28,18 +31,35 @@ applied to them. assistance. +## Multi-factor authentication (MFA) + +Firezone intentionally does not support multi-factor authentication (MFA) +directly. Instead, we recommend setting any required MFA steps in your identity +provider so you can apply a consistent MFA strategy for all of your +SSO-connected applications, not just Firezone. + +Here are links to MFA setup guides for some popular identity providers: + +- [Google Workspace](https://support.google.com/a/answer/184711) +- [Microsoft Entra ID](https://docs.microsoft.com/en-us/azure/active-directory/authentication/howto-mfa-userstates) +- [Okta](https://help.okta.com/en/prod/Content/Topics/Security/MFA.htm) + ## Session lifetime -The table below summarizes the session lifetimes for various components. +Firezone uses a separate authentication session token for each component that +authenticates to either the Admin portal and the API. See the table below for +the session lifetimes of these tokens: | Component | Auth Provider | Lifetime | | ------------------- | --------------------------------- | --------------------------------------------------------------------------- | | Admin portal web UI | Email authentication | **10 hours** | | Admin portal web UI | OIDC and other identity providers | Copied from the OIDC access token lifetime, up to a maximum of **10 hours** | -| Client applications | All identity providers | **1 week** | +| Client applications | All identity providers | **2 weeks** | | Service accounts | N/A | **365 days** by default, configurable per token | | Gateways | N/A | **Indefinitely**. Tokens must be explicitly revoked in the portal UI. | When a session token expires or is revoked, the affected component is disconnected immediately and must reauthenticate to regain access to Resources. This includes web UI sessions for admins. + + diff --git a/website/src/components/KbSidebar/Item.tsx b/website/src/components/KbSidebar/Item.tsx index ff409a7db..6c0630349 100644 --- a/website/src/components/KbSidebar/Item.tsx +++ b/website/src/components/KbSidebar/Item.tsx @@ -4,15 +4,15 @@ import { usePathname } from "next/navigation"; import { HiMinus } from "react-icons/hi2"; export default function Item({ + children, topLevel, nested, href, - label, }: { + children: React.ReactNode; topLevel?: boolean; nested?: boolean; href: Route; - label: string; }) { function active(path: string) { return usePathname() == path; @@ -23,7 +23,7 @@ export default function Item({ href={href} className={ (active(href) ? "bg-neutral-200 " : "") + - "pb-0.5 flex " + + "pb-0.5 flex w-full " + ((!topLevel && "border-l") || "") + " border-0.5 border-neutral-500 items-center text-left text-base font-medium text-neutral-700 hover:bg-neutral-100" } @@ -34,11 +34,11 @@ export default function Item({ className={ (nested ? "ml-5 " : "") + (active(href) ? "text-neutral-800 " : "") + - "ml-2" + + "ml-2 w-full" + ((topLevel && " pl-0.5") || "") } > - {label} + {children} ); diff --git a/website/src/components/KbSidebar/index.tsx b/website/src/components/KbSidebar/index.tsx index edf4a891f..7b40612e6 100644 --- a/website/src/components/KbSidebar/index.tsx +++ b/website/src/components/KbSidebar/index.tsx @@ -25,10 +25,14 @@ export default function KbSidebar() {
  • - + + Overview +
  • - + + Quickstart +
  • Get started @@ -36,31 +40,31 @@ export default function KbSidebar() {
  • - + Overview
  • - + Sites
  • - + Gateways
  • - + Resources
  • - + Groups
  • - + Users
  • - + Policies
  • - + Clients
  • - + Configure DNS
    • @@ -70,49 +74,41 @@ export default function KbSidebar() { label="Authenticate" >
  • - + Overview
  • - + Email (OTP)
  • - + + SSO with Google Workspace +
  • - + SSO with Entra ID
  • - + SSO with Okta
  • - + + SSO with Universal OIDC +
  • - + + FusionAuth +
  • - + + Directory sync +
  • - + + Service accounts +
    • @@ -125,28 +121,23 @@ export default function KbSidebar() { label="Administer" >
  • - + Overview
  • - + Upgrading Gateways
  • - + + Backup & restore +
  • - + Viewing logs
  • - + + Troubleshooting +
    • @@ -156,38 +147,32 @@ export default function KbSidebar() { label="End-user guides" >
  • - + Install Clients
  • - + + macOS +
  • - + + iOS +
  • - + + Windows +
  • - + + Android & ChromeOS +
  • - + + Linux +
    • @@ -197,55 +182,45 @@ export default function KbSidebar() { label="Use cases" >
  • - + Overview
  • - + Block malicious DNS
  • - + + Scale access to a VPC +
  • - + + Route through a public IP +
  • - + + Access a Postgres DB +
  • - + + Manage access to a SaaS app +
  • - + + Access a remote host +
  • - + + Access a private network +
  • - + + Access a private web app +
    • @@ -258,28 +233,25 @@ export default function KbSidebar() { label="Architecture" >
  • - + Overview
  • - + + Core components +
  • - + Tech stack
  • - + + Critical sequences +
  • - + + Security controls +
    • @@ -289,10 +261,10 @@ export default function KbSidebar() { label="Reference" >
  • - + FAQ
  • - + Glossary