diff --git a/elixir/apps/web/lib/web/components/core_components.ex b/elixir/apps/web/lib/web/components/core_components.ex index 558ed176b..c1ffd12a3 100644 --- a/elixir/apps/web/lib/web/components/core_components.ex +++ b/elixir/apps/web/lib/web/components/core_components.ex @@ -1100,4 +1100,39 @@ defmodule Web.CoreComponents do def translate_errors(errors, field) when is_list(errors) do for {^field, {msg, opts}} <- errors, do: translate_error({msg, opts}) end + + @doc """ + This component is meant to be used for step by step instructions + + ex. + <.step> + <:title>Step 1. Do Something + <:content> + Here are instructions for step 1... + + + + <.step> + <:title>Step 2. Do Another Thing + <:content> + Here are instructions for step 2... + + + + """ + slot :title, required: true + slot :content, required: true + + def step(assigns) do + ~H""" +
+

+ <%= render_slot(@title) %> +

+
+ <%= render_slot(@content) %> +
+
+ """ + end end diff --git a/elixir/apps/web/lib/web/components/layouts/root.html.heex b/elixir/apps/web/lib/web/components/layouts/root.html.heex index 6a9568c62..4044a3f58 100644 --- a/elixir/apps/web/lib/web/components/layouts/root.html.heex +++ b/elixir/apps/web/lib/web/components/layouts/root.html.heex @@ -32,7 +32,7 @@ > - + <%= @inner_content %> diff --git a/elixir/apps/web/lib/web/components/page_components.ex b/elixir/apps/web/lib/web/components/page_components.ex index 2a0df75f7..baf762c5e 100644 --- a/elixir/apps/web/lib/web/components/page_components.ex +++ b/elixir/apps/web/lib/web/components/page_components.ex @@ -14,7 +14,7 @@ defmodule Web.PageComponents do def section(assigns) do ~H""" -
+
<.header> <:title> <%= render_slot(@title) %> diff --git a/elixir/apps/web/lib/web/controllers/home_html.ex b/elixir/apps/web/lib/web/controllers/home_html.ex index 52b5db4a0..378037d59 100644 --- a/elixir/apps/web/lib/web/controllers/home_html.ex +++ b/elixir/apps/web/lib/web/controllers/home_html.ex @@ -3,7 +3,7 @@ defmodule Web.HomeHTML do def home(assigns) do ~H""" -
+
<.logo /> diff --git a/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/components.ex b/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/components.ex index a1f6900ca..6fa6ef8b5 100644 --- a/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/components.ex +++ b/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/components.ex @@ -3,117 +3,227 @@ defmodule Web.Settings.IdentityProviders.GoogleWorkspace.Components do def provider_form(assigns) do ~H""" -
+
<.form for={@form} phx-change={:change} phx-submit={:submit}> -
-

- Step 1. Enable Admin SDK API -

- Visit the following link to enable the Admin SDK API for your Google Workspace account: - - https://console.cloud.google.com/apis/library/admin.googleapis.com - -
+ <.step> + <:title>Step 1. Create a new project in Google Cloud + <:content> + Visit the following link to create a new project to use for this integration: + + https://console.cloud.google.com/projectcreate + + + -
-

- Step 2. Configure OAuth consent screen -

-

- Ensure the following scopes are added to the OAuth client: -

- <.code_block - :for={ - {name, scope} <- [ - openid: "openid", - email: "email", - profile: "profile", - orgunit: "https://www.googleapis.com/auth/admin.directory.orgunit.readonly", - group: "https://www.googleapis.com/auth/admin.directory.group.readonly", - user: "https://www.googleapis.com/auth/admin.directory.user.readonly" - ] - } - id={"scope-#{name}"} - class="w-full mb-4 whitespace-nowrap rounded" - phx-no-format - ><%= scope %> -
+ <.step> + <:title>Step 2. Enable Admin SDK API + <:content> + Visit the following link to enable the Admin SDK API for the project you just created: + + https://console.cloud.google.com/apis/library/admin.googleapis.com + + + -
-

- Step 3: Create OAuth client -

-

- Ensure the OAuth client has following redirect URLs configured: -

- <.code_block - :for={ - {type, redirect_url} <- [ - sign_in: url(~p"/#{@account.id}/sign_in/providers/#{@id}/handle_callback"), - connect: - url( - ~p"/#{@account.id}/settings/identity_providers/google_workspace/#{@id}/handle_callback" - ) - ] - } - id={"redirect_url-#{type}"} - class="w-full mb-4 whitespace-nowrap rounded" - phx-no-format - ><%= redirect_url %> -
+ <.step> + <:title>Step 3. Configure OAuth consent screen + <:content> +

+ Visit the following link to configure the OAuth consent screen: + + https://console.cloud.google.com/apis/credentials/consent + +

+

+ Select Internal for the user type and click CREATE. +

+

+ On the next page, use the following values: +

+
    +
  • + App name: Firezone +
    • +
  • + User support email: Your email address +
    • +
  • + App logo: + <.link + href="https://www.firezone.dev/images/gco-oauth-screen-logo.png" + class={link_style()} + > + Download here + +
    • +
  • + Application home page: + <.link href="https://www.firezone.dev" class={link_style()}> + https://www.firezone.dev + +
    • +
  • + Application privacy policy link: + <.link href="https://www.firezone.dev/privacy-policy" class={link_style()}> + https://www.firezone.dev/privacy-policy + +
    • +
  • + Application terms of service link: + <.link href="https://www.firezone.dev/terms" class={link_style()}> + https://www.firezone.dev/terms + +
    • +
  • + Authorized domains: + firezone.dev +
    • +
+

+ Click SAVE AND CONTINUE. +

+ + -
-

- Step 4. Configure client -

+ <.step> + <:title>Step 4. Configure scopes + <:content> +

+ Click ADD OR REMOVE SCOPES and ensure the following scopes are added: +

+ <.code_block + id="oauth-scopes" + class="w-full text-xs mb-4 whitespace-pre-line rounded" + phx-no-format + ><%= scopes() %> +

+ Then click UPDATE. +

+ + - <.base_error form={@form} field={:base} /> + <.step> + <:title>Step 5: Create client credentials + <:content> +

+ Go to the client credentials section and click CREATE CREDENTIALS + to create new OAuth credentials. +

+

+ Select OAuth client ID + and then select Web application. +

+

+ Use the following values on the next screen: +

+
    +
  • + Name: Firezone OAuth Client +
    • +
  • + Authorized redirect URIs: +

    + <.code_block + :for={ + {type, redirect_url} <- [ + sign_in: url(~p"/#{@account.id}/sign_in/providers/#{@id}/handle_callback"), + connect: + url( + ~p"/#{@account.id}/settings/identity_providers/google_workspace/#{@id}/handle_callback" + ) + ] + } + id={"redirect_url-#{type}"} + class="w-full mb-4 text-xs whitespace-nowrap rounded" + phx-no-format + ><%= redirect_url %> +

    +
    • +
+

+ Click CREATE. Copy the Client ID + and Client secret + values from the next screen. +

+ + -
-
- <.input - label="Name" - autocomplete="off" - field={@form[:name]} - placeholder="Name this identity provider" - required - /> -

- A friendly name for this identity provider. This will be displayed to end-users. -

+ <.step> + <:title>Step 6. Configure Firezone + <:content> + <.base_error form={@form} field={:base} /> + +
+
+ <.input + label="Name" + autocomplete="off" + field={@form[:name]} + placeholder="Name this identity provider" + required + /> +

+ A friendly name for this identity provider. This will be displayed to end-users. +

+
+ + <.inputs_for :let={adapter_config_form} field={@form[:adapter_config]}> +
+ <.input + label="Client ID" + autocomplete="off" + field={adapter_config_form[:client_id]} + required + /> +

+ The Client ID from the previous step. +

+
+ +
+ <.input + label="Client secret" + autocomplete="off" + field={adapter_config_form[:client_secret]} + required + /> +

+ The Client secret from the previous step. +

+
+
- <.inputs_for :let={adapter_config_form} field={@form[:adapter_config]}> -
- <.input - label="Client ID" - autocomplete="off" - field={adapter_config_form[:client_id]} - required - /> -
- -
- <.input - label="Client secret" - autocomplete="off" - field={adapter_config_form[:client_secret]} - required - /> -
- -
- - <.submit_button> - Connect Identity Provider - -
+ <.submit_button> + Connect Identity Provider + + +
""" end + + def scopes do + """ + 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 + """ + end end diff --git a/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/new.ex b/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/new.ex index 000e75d76..2208f36e3 100644 --- a/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/new.ex +++ b/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/new.ex @@ -39,6 +39,11 @@ defmodule Web.Settings.IdentityProviders.GoogleWorkspace.New do <:title> Add a new Google Workspace Identity Provider + <:help> + For a more detailed guide on setting up Firezone with Google Workspace, please <.link class={ + link_style() + }>refer to our documentation. + <:content> <.provider_form account={@account} id={@id} form={@form} /> diff --git a/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/show.ex b/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/show.ex index 764856ec2..c671e87ce 100644 --- a/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/show.ex +++ b/elixir/apps/web/lib/web/live/settings/identity_providers/google_workspace/show.ex @@ -48,13 +48,6 @@ defmodule Web.Settings.IdentityProviders.GoogleWorkspace.Show do > Enable Identity Provider - <.button - :if={is_nil(@provider.disabled_at)} - phx-click="disable" - data-confirm="Are you sure want to disable this provider? All authorizations will be revoked and actors won't be able to use it to access Firezone." - > - Disable Identity Provider - <% end %> <:action :if={is_nil(@provider.deleted_at)}> @@ -104,6 +97,15 @@ defmodule Web.Settings.IdentityProviders.GoogleWorkspace.Show do <.danger_zone :if={is_nil(@provider.deleted_at)}> <:action> + <.button + :if={is_nil(@provider.disabled_at)} + style="warning" + phx-click="disable" + icon="hero-no-symbol" + data-confirm="Are you sure want to disable this provider? Users will no longer be able to sign in with this provider and user / group sync will be paused." + > + Disable Identity Provider + <.delete_button data-confirm="Are you sure want to delete this provider along with all related data?" phx-click="delete" diff --git a/elixir/apps/web/lib/web/live/settings/identity_providers/openid_connect/components.ex b/elixir/apps/web/lib/web/live/settings/identity_providers/openid_connect/components.ex index a6e2946db..4379f89d1 100644 --- a/elixir/apps/web/lib/web/live/settings/identity_providers/openid_connect/components.ex +++ b/elixir/apps/web/lib/web/live/settings/identity_providers/openid_connect/components.ex @@ -3,116 +3,115 @@ defmodule Web.Settings.IdentityProviders.OpenIDConnect.Components do def provider_form(assigns) do ~H""" -
+
<.form for={@form} phx-change={:change} phx-submit={:submit}> -
-

- Step 1. Create OAuth app in your identity provider -

- Please make sure that following scopes are added to the OAuth application: <.code_block - :for={scope <- [:openid, :email, :profile]} - id={"scope-#{scope}"} - class="w-full mb-4 whitespace-nowrap rounded" - phx-no-format - ><%= scope %> Please make sure that OAuth client has following redirect URL's whitelisted: <.code_block - :for={ - {type, redirect_url} <- [ - sign_in: url(~p"/#{@account.id}/sign_in/providers/#{@id}/handle_callback"), - connect: - url( - ~p"/#{@account.id}/settings/identity_providers/openid_connect/#{@id}/handle_callback" - ) - ] - } - id={"redirect_url-#{type}"} - class="w-full mb-4 whitespace-nowrap rounded" - phx-no-format - ><%= redirect_url %> -
+ <.step> + <:title>Step 1. Create OAuth app in your identity provider + <:content> + Please make sure that following scopes are added to the OAuth application: <.code_block + :for={scope <- [:openid, :email, :profile]} + id={"scope-#{scope}"} + class="w-full mb-4 whitespace-nowrap rounded" + phx-no-format + ><%= scope %> Please make sure that OAuth client has following redirect URL's whitelisted: <.code_block + :for={ + {type, redirect_url} <- [ + sign_in: url(~p"/#{@account.id}/sign_in/providers/#{@id}/handle_callback"), + connect: + url( + ~p"/#{@account.id}/settings/identity_providers/openid_connect/#{@id}/handle_callback" + ) + ] + } + id={"redirect_url-#{type}"} + class="w-full mb-4 whitespace-nowrap rounded" + phx-no-format + ><%= redirect_url %> + + -
-

- 2. Configure client -

+ <.step> + <:title>Step 2. Configure client + <:content> + <.base_error form={@form} field={:base} /> - <.base_error form={@form} field={:base} /> +
+
+ <.input + label="Name" + autocomplete="off" + field={@form[:name]} + placeholder="Name this identity provider" + required + /> +

+ A friendly name for this identity provider. This will be displayed to end-users. +

+
-
-
- <.input - label="Name" - autocomplete="off" - field={@form[:name]} - placeholder="Name this identity provider" - required - /> -

- A friendly name for this identity provider. This will be displayed to end-users. -

+ <.inputs_for :let={adapter_config_form} field={@form[:adapter_config]}> +
+ <.input + label="Response Type" + field={adapter_config_form[:response_type]} + placeholder="code" + value="code" + disabled + /> +

+ Firezone currently only supports code flows. +

+
+ +
+ <.input + label="Scopes" + autocomplete="off" + field={adapter_config_form[:scope]} + placeholder="OpenID Connect scopes to request" + required + /> +

+ A space-delimited list of scopes to request from your identity provider. In most cases you shouldn't need to change this. +

+
+ +
+ <.input + label="Client ID" + autocomplete="off" + field={adapter_config_form[:client_id]} + placeholder="Client ID from your IdP" + required + /> +
+ +
+ <.input + label="Client secret" + autocomplete="off" + field={adapter_config_form[:client_secret]} + placeholder="Client Secret from your IdP" + required + /> +
+ +
+ <.input + label="Discovery URL" + field={adapter_config_form[:discovery_document_uri]} + placeholder=".well-known URL for your IdP" + required + /> +
+
- <.inputs_for :let={adapter_config_form} field={@form[:adapter_config]}> -
- <.input - label="Response Type" - field={adapter_config_form[:response_type]} - placeholder="code" - value="code" - disabled - /> -

- Firezone currently only supports code flows. -

-
- -
- <.input - label="Scopes" - autocomplete="off" - field={adapter_config_form[:scope]} - placeholder="OpenID Connect scopes to request" - required - /> -

- A space-delimited list of scopes to request from your identity provider. In most cases you shouldn't need to change this. -

-
- -
- <.input - label="Client ID" - autocomplete="off" - field={adapter_config_form[:client_id]} - placeholder="Client ID from your IdP" - required - /> -
- -
- <.input - label="Client secret" - autocomplete="off" - field={adapter_config_form[:client_secret]} - placeholder="Client Secret from your IdP" - required - /> -
- -
- <.input - label="Discovery URL" - field={adapter_config_form[:discovery_document_uri]} - placeholder=".well-known URL for your IdP" - required - /> -
- -
- - <.submit_button> - Connect Identity Provider - -
+ <.submit_button> + Connect Identity Provider + + +
""" diff --git a/elixir/apps/web/lib/web/live/sign_in.ex b/elixir/apps/web/lib/web/live/sign_in.ex index ce4c255eb..4904c0d16 100644 --- a/elixir/apps/web/lib/web/live/sign_in.ex +++ b/elixir/apps/web/lib/web/live/sign_in.ex @@ -40,7 +40,7 @@ defmodule Web.SignIn do def render(assigns) do ~H""" -
+
<.logo /> diff --git a/elixir/apps/web/lib/web/live/sign_in/email.ex b/elixir/apps/web/lib/web/live/sign_in/email.ex index 592cb291d..e41dd3ec3 100644 --- a/elixir/apps/web/lib/web/live/sign_in/email.ex +++ b/elixir/apps/web/lib/web/live/sign_in/email.ex @@ -31,7 +31,7 @@ defmodule Web.SignIn.Email do def render(assigns) do ~H""" -
+
<.logo /> diff --git a/elixir/apps/web/lib/web/live/sign_up.ex b/elixir/apps/web/lib/web/live/sign_up.ex index f4a25c757..24caf4785 100644 --- a/elixir/apps/web/lib/web/live/sign_up.ex +++ b/elixir/apps/web/lib/web/live/sign_up.ex @@ -63,7 +63,7 @@ defmodule Web.SignUp do def render(assigns) do ~H""" -
+
<.logo /> diff --git a/elixir/apps/web/lib/web/live/sites/new_token.ex b/elixir/apps/web/lib/web/live/sites/new_token.ex index aa7262dc8..cc8db3cb3 100644 --- a/elixir/apps/web/lib/web/live/sites/new_token.ex +++ b/elixir/apps/web/lib/web/live/sites/new_token.ex @@ -43,6 +43,19 @@ defmodule Web.Sites.NewToken do <:title> Deploy a new Gateway + <:help> + Gateways require outbound access to api.firezone.dev:443 only. No inbound firewall rules + are required or recommended. + + <:help> + <.link + href="http://www.firezone.dev/kb/deploy/gateways?utm_source=product" + class="text-accent-500 hover:underline" + >Read the gateway deployment guide for more detailed instructions. + <:content>
diff --git a/website/public/images/gcp-allow.png b/website/public/images/gcp-allow.png new file mode 100644 index 000000000..c331da9fb Binary files /dev/null and b/website/public/images/gcp-allow.png differ diff --git a/website/public/images/gcp-create-credentials.png b/website/public/images/gcp-create-credentials.png new file mode 100644 index 000000000..b2dc9f577 Binary files /dev/null and b/website/public/images/gcp-create-credentials.png differ diff --git a/website/public/images/gcp-create-project.png b/website/public/images/gcp-create-project.png new file mode 100644 index 000000000..e801a054d Binary files /dev/null and b/website/public/images/gcp-create-project.png differ diff --git a/website/public/images/gcp-creds-web.png b/website/public/images/gcp-creds-web.png new file mode 100644 index 000000000..dacccd2e5 Binary files /dev/null and b/website/public/images/gcp-creds-web.png differ diff --git a/website/public/images/gcp-enable-admin-api.png b/website/public/images/gcp-enable-admin-api.png new file mode 100644 index 000000000..1a1c8128b Binary files /dev/null and b/website/public/images/gcp-enable-admin-api.png differ diff --git a/website/public/images/gcp-oauth-consent-screen.png b/website/public/images/gcp-oauth-consent-screen.png new file mode 100644 index 000000000..4e6a7a746 Binary files /dev/null and b/website/public/images/gcp-oauth-consent-screen.png differ diff --git a/website/public/images/gcp-oauth-credentials.png b/website/public/images/gcp-oauth-credentials.png new file mode 100644 index 000000000..17d0567c1 Binary files /dev/null and b/website/public/images/gcp-oauth-credentials.png differ diff --git a/website/public/images/gcp-oauth-screen-2.png b/website/public/images/gcp-oauth-screen-2.png new file mode 100644 index 000000000..387d641e4 Binary files /dev/null and b/website/public/images/gcp-oauth-screen-2.png differ diff --git a/website/public/images/gcp-oauth-screen-logo.png b/website/public/images/gcp-oauth-screen-logo.png new file mode 100644 index 000000000..4d2e099a1 Binary files /dev/null and b/website/public/images/gcp-oauth-screen-logo.png differ diff --git a/website/public/images/gcp-oauth-summary.png b/website/public/images/gcp-oauth-summary.png new file mode 100644 index 000000000..8cb9fd647 Binary files /dev/null and b/website/public/images/gcp-oauth-summary.png differ diff --git a/website/public/images/gcp-scopes-continue.png b/website/public/images/gcp-scopes-continue.png new file mode 100644 index 000000000..0f2c0a88b Binary files /dev/null and b/website/public/images/gcp-scopes-continue.png differ diff --git a/website/public/images/gcp-update-scopes-2.png b/website/public/images/gcp-update-scopes-2.png new file mode 100644 index 000000000..2f69538c0 Binary files /dev/null and b/website/public/images/gcp-update-scopes-2.png differ diff --git a/website/public/images/gcp-update-scopes.png b/website/public/images/gcp-update-scopes.png new file mode 100644 index 000000000..518f6e742 Binary files /dev/null and b/website/public/images/gcp-update-scopes.png differ diff --git a/website/src/app/kb/administer/upgrading/readme.mdx b/website/src/app/kb/administer/upgrading/readme.mdx index 09117dcfe..e3747f89c 100644 --- a/website/src/app/kb/administer/upgrading/readme.mdx +++ b/website/src/app/kb/administer/upgrading/readme.mdx @@ -10,14 +10,17 @@ high-availability deployments. ## How versioning works in Firezone -Firezone uses a semantic versioning scheme in the standard -`MAJOR`.`MINOR`.`PATCH` format with the following structure: +Firezone uses a simple versioning scheme with the following structure: -| Version type | Example | Explanation | -| ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `MAJOR` | `1` | Marketing version. Updates to this version generally constitute a new architecture or product. Updated every few years on average. | -| `MINOR` | `20231001` | API version. Clients and gateways **must** be the same API version to function together. The Firezone admin portal supports the latest **two** API versions at the same time. Updated every 6 months on average. | -| `PATCH` | `11` | Patch version. Represents backwards-compatible bug fixes and updates that are generally recommended for all users. Updated on average every week. | +`MARKETING`.`API_DATE`.`PATCH` + +Each of these fields is described below. + +| Version field | Example | Explanation | +| ------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `MARKETING` | `1` | Marketing version. Updates to this version generally constitute a new architecture or product. Updated every few years on average. | +| `API_DATE` | `20231001` | API version. Clients and gateways **must** be the same API version to function together. The Firezone admin portal supports the latest **two** API versions at the same time. Updated every 6 months on average. | +| `PATCH` | `11` | Patch version. Represents backwards-compatible bug fixes and updates that are generally recommended for all users. Updated on average every week. | All Firezone components follow the structure above, so it is trivial to determine which clients work with which gateways and for how long. @@ -51,7 +54,7 @@ Gateways deployed in the same site will automatically one-by-one, clients connected to the gateway being upgraded will automatically reconnect to an available gateway. -Currently the failover timeout is maximum 120 seconds, so upgrades should be +Currently the failover timeout is maximum 25 seconds, so upgrades should be performed during a scheduled maintenance window to ensure minimal disruption. Other than a possible short-term connection interruption to in-use resources, users won't be impacted by upgrading high-availability gateways. diff --git a/website/src/app/kb/authenticate/google/_page.tsx b/website/src/app/kb/authenticate/google/_page.tsx new file mode 100644 index 000000000..8f8abd30f --- /dev/null +++ b/website/src/app/kb/authenticate/google/_page.tsx @@ -0,0 +1,6 @@ +"use client"; +import Content from "./readme.mdx"; + +export default function _Page() { + return ; +} diff --git a/website/src/app/kb/authenticate/google/page.tsx b/website/src/app/kb/authenticate/google/page.tsx index e84fde61d..62a05340d 100644 --- a/website/src/app/kb/authenticate/google/page.tsx +++ b/website/src/app/kb/authenticate/google/page.tsx @@ -1,4 +1,4 @@ -import Content from "./readme.mdx"; +import _Page from "./_page"; import { Metadata } from "next"; export const metadata: Metadata = { @@ -7,5 +7,5 @@ export const metadata: Metadata = { }; export default function Page() { - return ; + return <_Page />; } diff --git a/website/src/app/kb/authenticate/google/readme.mdx b/website/src/app/kb/authenticate/google/readme.mdx index 3e0ba851f..e81171ea2 100644 --- a/website/src/app/kb/authenticate/google/readme.mdx +++ b/website/src/app/kb/authenticate/google/readme.mdx @@ -1,5 +1,7 @@ import Alert from "@/components/DocsAlert"; +import SupportOptions from "@/components/SupportOptions"; import PlanBadge from "@/components/PlanBadge"; +import Image from "next/image"; @@ -24,7 +26,7 @@ Google Workspace for your Firezone Enterprise account. ## Overview The Firezone Google Workspace connector integrates with Google's identity APIs -to support user authentication and automatic user/group sync. +to support user authentication and user / group 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 @@ -33,10 +35,224 @@ your Google Workspace account. ## Setup -To set up the Google workspace connector, go to `Settings` -> -`Identity Providers` -> `Add Identity Provider` and follow the prompts from -there. - 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 scopes needed to enable user/group sync. + +To setup the Google Workspace connector, follow the steps below. + +### Step 1: Create a new project in Google Cloud + + + Step 2 if you already have a GCP project you'd like to use with Firezone. + `} +/> + +[Go here to create a new project](https://console.cloud.google.com/projectcreate) +in your Google Cloud account and fill in the following fields: + +- **Project name**: `Firezone Connector` +- **Organization**: Select the appropriate organization that contains the users + and groups you wish to integrate with Firezone. +- **Location**: Select the appropriate organization to place this project under. + +Click **CREATE** after you've filled in the fields above. + +Create project in GCP + +### Step 2: Enable the Admin SDK API + +[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. + +**Important**: Ensure the **Firezone Connector** project you created in Step 1 +is selected before clicking the "ENABLE" button. + +Enable Admin SDK API + +### Step 3: Configure the OAuth consent screen + +[Click here](https://console.cloud.google.com/apis/credentials/consent) to +configure the OAuth consent screen for the project you created in Step 1. + +**Important**: Select "Internal" for User type. Select "External" may allow +external users to login to your Firezone account. + +Enable Admin SDK API + +Click **CREATE**. + +On the next page, enter the following information: + +- **App name**: `Firezone` +- **User support email**: Your or your company's IT support email address. +- **App logo** (optional): + [Download the Firezone logo here](/images/gcp-oauth-screen-logo.png) to use + for this consent screen. +- **Application home page**: `https://www.firezone.dev` +- **Application privacy policy link**: `https://www.firezone.dev/privacy-policy` +- **Application terms of service link**: `https://www.firezone.dev/terms` +- **Authorized domains**: Click "ADD DOMAIN" and enter `firezone.dev` +- **Developer contact information**: Enter the same email you used above, e.g. + `it-support@company.com` + +Add app info + +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: + +- `openid`: Reserved scope required by all OpenID Connect integrations. +- `profile`: Provides information such as the user's username, given name, + surname, and so forth. +- `email`: The user's email address. +- `https://www.googleapis.com/auth/admin.directory.orgunit.readonly`: Required + to sync Organization Units. +- `https://www.googleapis.com/auth/admin.directory.group.readonly`: Required to + 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. + +Update scopes + +Then click **UPDATE** to make sure they're applied. + +Update scopes + +Scopes continue + +Ensure your Scopes configuration looks like the screenshot above, then click +**SAVE AND CONTINUE**. + +Scopes continue + +Your OAuth app summary should look similar to the screenshot above. + +### Step 5: Create client credentials + +Next, you'll need to add OAuth credentials to allow Firezone to connect to your +Google Workspace account. + +Head to +[the Credentials section](https://console.cloud.google.com/apis/credentials) and +click **CREATE CREDENTIALS** to create new OAuth credentials. Be sure to select +"OAuth client ID" in the dropdown menu. + +Create OAuth credentials + +On the next screen, select **Web application**, then use the following +information for the remain fields: + +- **Name**: `Firezone OAuth Client` +- **Authorized redirect URIs**: Click **ADD URI**, and enter the two redirect + URIs shown on the Google Workspace identity provider setup screen in your + Firezone admin dashboard + (`Settings -> Identity Providers -> Add Identity Provider -> Google Workspace -> Configure`). + +Web application credentials + +Click **CREATE**. + +Web application credentials + +**Important**: Make sure to save the `Client ID` and `Client secret` fields in a +safe place as they won't be shown again. + +### Step 6: Enter `Client ID` and `Client secret` in Firezone + +Go back to the Firezone admin dashboard, and enter the `Client ID` and +`Client secret` you copied from the previous step in the appropriate fields in +"Create Identity Provider" form. + +Finally, click **Connect Identity Provider** and click **Allow** when Google +prompts you. + +Allow admin access + +If you get successfully redirected back to your Firezone admin dashboard, you're +done! Your Google Workspace connector is now successfully configured. Users in +your organization can now authenticate to Firezone using this connector and user +/ group sync will occur every few minutes. + + diff --git a/website/src/app/kb/deploy/gateways/readme.mdx b/website/src/app/kb/deploy/gateways/readme.mdx index 1e6da1b6d..f2c344d0c 100644 --- a/website/src/app/kb/deploy/gateways/readme.mdx +++ b/website/src/app/kb/deploy/gateways/readme.mdx @@ -61,10 +61,10 @@ Two or more Gateways deployed in the same site will automatically fail over and load balance for each other. When the portal detects a particular gateway is unhealthy, it will stop using it -for new connection requests to resources in the site. Fail over takes around 60 -to 120 seconds for clients to time out their existing gateway connections and -fail over to a healthy one. During this time, connection to resources will be -interrupted, so it's important to plan gateway downtime appropriately. +for new connection requests to resources in the site. Fail over takes up to 25 +seconds for clients to time out their existing gateway connections and fail over +to a healthy one. During this time, connection to resources will be interrupted, +so it's important to plan gateway downtime appropriately. ## Load balancing diff --git a/website/src/app/kb/quickstart/readme.mdx b/website/src/app/kb/quickstart/readme.mdx index 231c80a98..83db4c3ad 100644 --- a/website/src/app/kb/quickstart/readme.mdx +++ b/website/src/app/kb/quickstart/readme.mdx @@ -58,9 +58,20 @@ enter it in to the form on the sign-in page. When you log in to the admin portal, you'll land on the Sites page. The first step will be to create a Site by clicking the 'Add Site' button. We'll auto-generate a name for the site, but you should consider renaming it something -relevant like `Production`, `US-West`, or `Chicago-office`. After the site is -created, you'll be forwarded to the Site Details page where you can continue the -setup process. +relevant like `Production`, `US-West`, or `Chicago-office`. + +When creating a Site, you're presented with the option to select the routing +policy. Firezone uses industry-standard techniques to automatically holepunch +direct, peer-to-peer connections between clients and gateways. In nearly all +cases, this works fine, but in certain hostile network environments, a Relay +must be used to ensure connectivity. Select `Firezone-managed Relays` to allow +encrypted packets to traverse Firezone's managed global relay network, or select +`Direct only` to force all packets to flow peer-to-peer _only_. Keep in mind +`Direct only` can prevent connections in some rare circumstances based on the +NAT topology of your gateway environment. + +After the site is created, you'll be forwarded to the Site Details page where +you can continue the setup process. ### Deploy a Gateway