docs: Make it more clear that synced users have User role (#5934)

Fixes #5906
2026-01-27 10:18:54 +00:00 · 2024-07-24 10:21:46 -07:00
parent 5068425017
commit bfa410f7df
12 changed files with 117 additions and 37 deletions
--- a/elixir/apps/web/lib/web/auth.ex
+++ b/elixir/apps/web/lib/web/auth.ex
@@ -108,7 +108,7 @@ defmodule Web.Auth do
      conn
      |> Phoenix.Controller.put_flash(
        :error,
-        "Please use a client application to access Firezone."
+        "You must have the admin role in Firezone to sign in to the admin portal."
      )
      |> Phoenix.Controller.redirect(to: ~p"/#{conn.path_params["account_id_or_slug"]}")
      |> Plug.Conn.halt()
@@ -153,7 +153,10 @@ defmodule Web.Auth do
         _params
       ) do
    conn
-    |> Phoenix.Controller.put_flash(:error, "Please use a client application to access Firezone.")
+    |> Phoenix.Controller.put_flash(
+      :error,
+      "You must have the admin role in Firezone to sign in to the admin portal."
+    )
    |> Phoenix.Controller.redirect(to: ~p"/#{conn.path_params["account_id_or_slug"]}")
    |> Plug.Conn.halt()
  end
--- 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
@@ -84,12 +84,16 @@ defmodule Web.Settings.IdentityProviders.GoogleWorkspace.Show do
        </.button>
      </:action>
      <:help>
-        Directory sync is enabled for this provider. Users, groups, and organizational units will
-        be synced every 10 minutes on average, but could take longer for very large organizations.
-        <.website_link path="/kb/authenticate/directory-sync">
-          Read more
-        </.website_link>
-        about directory sync.
+        <p>
+          Directory sync is enabled for this provider. Users, groups, and organizational units will
+          be synced every few minutes on average, but could take longer for very large organizations.
+        </p>
+        <p>
+          <.website_link path="/kb/authenticate/directory-sync">
+            Read more
+          </.website_link>
+          about directory sync.
+        </p>
      </:help>
      <:content>
        <.header>
--- a/elixir/apps/web/lib/web/live/settings/identity_providers/jumpcloud/show.ex
+++ b/elixir/apps/web/lib/web/live/settings/identity_providers/jumpcloud/show.ex
@@ -85,12 +85,16 @@ defmodule Web.Settings.IdentityProviders.JumpCloud.Show do
        </.button>
      </:action>
      <:help>
-        Directory sync is enabled for this provider. Users and groups will be synced every 10
-        minutes on average, but could take longer for very large organizations.
-        <.website_link path="/kb/authenticate/directory-sync">
-          Read more
-        </.website_link>
-        about directory sync.
+        <p>
+          Directory sync is enabled for this provider. Users and groups will be synced every few
+          minutes on average, but could take longer for very large organizations.
+        </p>
+        <p>
+          <.website_link path="/kb/authenticate/directory-sync">
+            Read more
+          </.website_link>
+          about directory sync.
+        </p>
      </:help>
      <:content>
        <.header>
--- a/elixir/apps/web/lib/web/live/settings/identity_providers/microsoft_entra/show.ex
+++ b/elixir/apps/web/lib/web/live/settings/identity_providers/microsoft_entra/show.ex
@@ -84,12 +84,16 @@ defmodule Web.Settings.IdentityProviders.MicrosoftEntra.Show do
        </.button>
      </:action>
      <:help>
-        Directory sync is enabled for this provider. Users and groups will be synced every 10
-        minutes on average, but could take longer for very large organizations.
-        <.website_link path="/kb/authenticate/directory-sync">
-          Read more
-        </.website_link>
-        about directory sync.
+        <p>
+          Directory sync is enabled for this provider. Users and groups will be synced every few
+          minutes on average, but could take longer for very large organizations.
+        </p>
+        <p>
+          <.website_link path="/kb/authenticate/directory-sync">
+            Read more
+          </.website_link>
+          about directory sync.
+        </p>
      </:help>
      <:content>
        <.header>
--- a/elixir/apps/web/lib/web/live/settings/identity_providers/okta/show.ex
+++ b/elixir/apps/web/lib/web/live/settings/identity_providers/okta/show.ex
@@ -82,12 +82,16 @@ defmodule Web.Settings.IdentityProviders.Okta.Show do
        </.button>
      </:action>
      <:help>
-        Directory sync is enabled for this provider. Users and groups will be synced every 10
-        minutes on average, but could take longer for very large organizations.
-        <.website_link path="/kb/authenticate/directory-sync">
-          Read more
-        </.website_link>
-        about directory sync.
+        <p>
+          Directory sync is enabled for this provider. Users and groups will be synced every few
+          minutes on average, but could take longer for very large organizations.
+        </p>
+        <p>
+          <.website_link path="/kb/authenticate/directory-sync">
+            Read more
+          </.website_link>
+          about directory sync.
+        </p>
      </:help>
      <:content>
        <.header>
--- a/elixir/apps/web/test/web/acceptance/auth/userpass_test.exs
+++ b/elixir/apps/web/test/web/acceptance/auth/userpass_test.exs
@@ -135,7 +135,9 @@ defmodule Web.Acceptance.Auth.UserPassTest do
    session
    |> password_login_flow(account, identity.provider_identifier, password)
    |> assert_path(~p"/#{account}")
-    |> assert_error_flash("Please use a client application to access Firezone.")
+    |> assert_error_flash(
+      "You must have the admin role in Firezone to sign in to the admin portal."
+    )
  end

  feature "redirects to client deep link after successful sign in as account_admin_user", %{
--- a/elixir/apps/web/test/web/auth_test.exs
+++ b/elixir/apps/web/test/web/auth_test.exs
@@ -226,7 +226,9 @@ defmodule Web.AuthTest do
        |> signed_in(provider, user_identity, context, user_encoded_fragment, %{})

      assert redirected_to(conn) == ~p"/#{account}"
-      assert conn.assigns.flash["error"] == "Please use a client application to access Firezone."
+
+      assert conn.assigns.flash["error"] ==
+               "You must have the admin role in Firezone to sign in to the admin portal."

      conn =
        %{init_conn | path_params: %{"account_id_or_slug" => account.slug}}
@@ -237,7 +239,9 @@ defmodule Web.AuthTest do
        })

      assert redirected_to(conn) == ~p"/#{account}"
-      assert conn.assigns.flash["error"] == "Please use a client application to access Firezone."
+
+      assert conn.assigns.flash["error"] ==
+               "You must have the admin role in Firezone to sign in to the admin portal."

      conn =
        %{init_conn | path_params: %{"account_id_or_slug" => account.slug}}
@@ -248,7 +252,9 @@ defmodule Web.AuthTest do
        })

      assert redirected_to(conn) == ~p"/#{account}"
-      assert conn.assigns.flash["error"] == "Please use a client application to access Firezone."
+
+      assert conn.assigns.flash["error"] ==
+               "You must have the admin role in Firezone to sign in to the admin portal."
    end

    test "redirects non-admin users to the sign in success page for client contexts", %{
@@ -344,7 +350,9 @@ defmodule Web.AuthTest do
        |> signed_in(provider, identity, context, encoded_fragment, %{})

      assert redirected_to(conn) == ~p"/#{account}"
-      assert conn.assigns.flash["error"] == "Please use a client application to access Firezone."
+
+      assert conn.assigns.flash["error"] ==
+               "You must have the admin role in Firezone to sign in to the admin portal."
    end

    test "redirects admin user to the return path path for browser contexts", %{
--- a/website/src/app/kb/authenticate/directory-sync/readme.mdx
+++ b/website/src/app/kb/authenticate/directory-sync/readme.mdx
@@ -17,6 +17,19 @@ setup step is required after creating the connector to activate JumpCloud's SCIM
 API. Once the connector is activated, users, groups, and organizational units
 will be synced from your identity provider every few minutes.

+## Role mapping
+
+All synced users are assigned the unprivileged `User` role by default. This role
+is allowed to sign in from the Firezone Client, but has no access to the admin
+portal. If you need to grant a synced user access to the admin portal, you can
+manually assign the user the `Admin` role by going to
+`Actors -> <actor name> -> Edit User` and updating their role appropriately.
+
+Automatic role mapping is not currently supported. If this is a feature you
+would like to see, please let us know by
+[leaving a comment](https://github.com/firezone/firezone/issues/5931) on our
+GitHub issue tracker.
+
 ## How Firezone treats deleted entities

 When you delete a user or group in your identity provider, Firezone soft-deletes
--- a/website/src/app/kb/authenticate/entra/readme.mdx
+++ b/website/src/app/kb/authenticate/entra/readme.mdx
@@ -425,12 +425,14 @@ Go back to the setup page in the Firezone admin portal, ensure all fields are
 filled out, and click **Connect Identity Provider**.

 <Alert color="warning">
-  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)
-  for more information.
+
+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)
+for more information.
+
 </Alert>

 If you get successfully redirected back to your Firezone admin portal, you're
@@ -438,4 +440,13 @@ 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.

+<Alert color="info">
+
+Synced users will be assigned the `User` role by default, allowing them access
+to sign in from the Firezone Client only. If you need to grant access to the
+admin portal, you need to manually promote the user to the `Admin` role by
+visiting `Actors -> <actor name> -> Edit User` and updating their role.
+
+</Alert>
+
 <SupportOptions />
--- a/website/src/app/kb/authenticate/google/readme.mdx
+++ b/website/src/app/kb/authenticate/google/readme.mdx
@@ -338,4 +338,13 @@ 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.

+<Alert color="info">
+
+Synced users will be assigned the `User` role by default, allowing them access
+to sign in from the Firezone Client only. If you need to grant access to the
+admin portal, you need to manually promote the user to the `Admin` role by
+visiting `Actors -> <actor name> -> Edit User` and updating their role.
+
+</Alert>
+
 <SupportOptions />
--- a/website/src/app/kb/authenticate/jumpcloud/readme.mdx
+++ b/website/src/app/kb/authenticate/jumpcloud/readme.mdx
@@ -214,4 +214,13 @@ Once directory sync is enabled, users and groups will be synced every few
 minutes to ensure that your Firezone account remains up-to-date with the latest
 identity data from JumpCloud.

+<Alert color="info">
+
+Synced users will be assigned the `User` role by default, allowing them access
+to sign in from the Firezone Client only. If you need to grant access to the
+admin portal, you need to manually promote the user to the `Admin` role by
+visiting `Actors -> <actor name> -> Edit User` and updating their role.
+
+</Alert>
+
 <SupportOptions />
--- a/website/src/app/kb/authenticate/okta/readme.mdx
+++ b/website/src/app/kb/authenticate/okta/readme.mdx
@@ -274,4 +274,13 @@ done! Your Okta 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 Okta accounts.

+<Alert color="info">
+
+Synced users will be assigned the `User` role by default, allowing them access
+to sign in from the Firezone Client only. If you need to grant access to the
+admin portal, you need to manually promote the user to the `Admin` role by
+visiting `Actors -> <actor name> -> Edit User` and updating their role.
+
+</Alert>
+
 <SupportOptions />