diff --git a/src/pages/selfhosted/identity-providers/managed/advanced/google-workspace.mdx b/src/pages/selfhosted/identity-providers/managed/advanced/google-workspace.mdx index a9bb0bc1..b8832d03 100644 --- a/src/pages/selfhosted/identity-providers/managed/advanced/google-workspace.mdx +++ b/src/pages/selfhosted/identity-providers/managed/advanced/google-workspace.mdx @@ -3,26 +3,30 @@ import {Note, Warning} from "@/components/mdx"; # Google Workspace SSO with NetBird Self-Hosted (Legacy) -The client secret has been removed from the authentication flow. The secret was originally included to support providers like Google Workspace that don't offer a proper PKCE flow, but this is no longer necessary with the embedded IdP. +**Using Google directly as NetBird's identity provider is not recommended.** Use the [embedded IdP with Google as an external provider](/selfhosted/identity-providers/managed/google-workspace#management-setup-recommended) instead. If you already run this standalone setup, migrate with the [External IdP to Embedded IdP migration guide](/selfhosted/migration/external-to-embedded-idp). -If you are using this standalone Google Workspace setup, we strongly recommend migrating to the [embedded IdP setup with Google as an external provider](/selfhosted/identity-providers/managed/google-workspace#management-setup-recommended). The embedded IdP approach is simpler, fully supported, and does not rely on the deprecated client secret. +Google requires a client secret to issue tokens, even with PKCE, so this setup relies on the Management service sending the client secret to every NetBird client. Sending the client secret to clients is deprecated and will be removed in a future release. With the embedded IdP, clients authenticate against NetBird's own IdP, which brokers the login to Google and keeps the client secret on the server. Use Google accounts for authentication with NetBird. This supports both personal Google accounts and Google Workspace (formerly G Suite) organizations. -## Standalone Setup (Advanced) +## Standalone Setup (Not Recommended) NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options. We highly recommend using the simpler setup that adds Google as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/managed/google-workspace#management-setup-recommended) section in the main Google Workspace documentation. -The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced Google Workspace administrators who need full control over authentication and user management. +The standalone setup below replaces your embedded IdP entirely and is not recommended for new or existing deployments. -Use Google Workspace as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Google Workspace administrators as it also requires additional setup and ongoing maintenance. +Use Google Workspace as your primary identity provider instead of NetBird's embedded IdP. This option requires additional setup and ongoing maintenance, depends on the deprecated client secret delivery described above, and has the limitations listed below. -For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above. +For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, see the [Management Setup (Recommended)](/selfhosted/identity-providers/managed/google-workspace#management-setup-recommended) section in the main Google Workspace documentation. + +### Limitation: No Device Authorization Flow + +Google's device flow requires a client secret when polling for the token, and NetBird clients do not send one, so this setup disables the device flow (`NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"` in [Step 7](#step-7-configure-net-bird)). Linux and FreeBSD peers without a graphical session, such as servers or SSH sessions, use only the device flow, so they cannot log in with SSO (`netbird login`, `netbird up`) or authenticate with `netbird ssh`. Register those peers with [setup keys](/manage/peers/register-machines-using-setup-keys), or migrate to the embedded IdP, which supports the device flow. Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP manager no longer requires the custom admin role called `User and Schema Management`. We now use a read-only role for user information. diff --git a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx index 8c0445e5..1f5b13ba 100644 --- a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx +++ b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx @@ -1,4 +1,4 @@ -import {Note} from "@/components/mdx"; +import {Note, Warning} from "@/components/mdx"; # Google Workspace SSO with NetBird Self-Hosted @@ -138,13 +138,15 @@ Domain restrictions are configured in Google Cloud Console, not in NetBird. --- -## Standalone Setup (Advanced) +## Standalone Setup (Not Recommended) -Use Google Workspace as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Google Workspace administrators as it also requires additional setup and ongoing maintenance. + +Using Google directly as NetBird's identity provider, instead of the embedded IdP, is not recommended. It relies on the Management service sending the client secret to every NetBird client, which is deprecated and will be removed in a future release, and it does not support the device authorization flow used by headless Linux and FreeBSD peers. Use the [Management Setup (Recommended)](#management-setup-recommended) above instead. -For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above. +If you already run this standalone setup, migrate to the embedded IdP with the [External IdP to Embedded IdP migration guide](/selfhosted/migration/external-to-embedded-idp). Existing users keep signing in with their Google accounts. + -For detailed instructions on the standalone setup, see the [Google Workspace SSO with NetBird Self-Hosted (Legacy)](/selfhosted/identity-providers/managed/advanced/google-workspace) documentation. +For reference, the standalone setup instructions are kept in the [Google Workspace SSO with NetBird Self-Hosted (Legacy)](/selfhosted/identity-providers/managed/advanced/google-workspace) documentation. If you prefer to have full control over authentication, consider self-hosted alternatives like [PocketID](/selfhosted/identity-providers/pocketid). diff --git a/src/pages/selfhosted/migration/external-to-embedded-idp.mdx b/src/pages/selfhosted/migration/external-to-embedded-idp.mdx index f8e223c3..e74b9206 100644 --- a/src/pages/selfhosted/migration/external-to-embedded-idp.mdx +++ b/src/pages/selfhosted/migration/external-to-embedded-idp.mdx @@ -149,6 +149,22 @@ Using Zitadel as an example, the JSON should have the following values: - "clientID" and "clientSecret": are the values you copy when creating the OAuth app + +For Google, use the `google` connector type, which needs no issuer. It uses the same Google account ID as the standalone Google setup, so existing users keep their NetBird accounts: +```json +{ + "type": "google", + "name": "Google", + "id": "google", + "config": { + "clientID": "my-client-id", + "clientSecret": "my-client-secret" + } +} +``` +In the Google Cloud Console, add `https:///oauth2/callback` to the OAuth client's **Authorized redirect URIs**. + + 2. Encode and store it in the `NETBIRD_IDP_SEED_INFO` environment variable: diff --git a/src/pages/selfhosted/selfhosted-guide.mdx b/src/pages/selfhosted/selfhosted-guide.mdx index ffca268a..4486418a 100644 --- a/src/pages/selfhosted/selfhosted-guide.mdx +++ b/src/pages/selfhosted/selfhosted-guide.mdx @@ -139,7 +139,7 @@ NetBird supports generic OpenID (OIDC) protocol allowing integration with any ID NetBird's management service integrates with some of the most popular IDP APIs, allowing the service to cache and display user names and email addresses without storing sensitive data. -Pick the one that suits your needs, follow the **Standalone Setup (Advanced)** section in each guide, and continue with this guide: +Pick the one that suits your needs, follow the **Standalone Setup (Advanced)** section in each guide (except Google, see the note below), and continue with this guide: **Self-hosted options** - [Zitadel](/selfhosted/identity-providers/zitadel) - Previously used in the quickstart script @@ -149,13 +149,15 @@ Pick the one that suits your needs, follow the **Standalone Setup (Advanced)** s **Managed options** - [Microsoft Entra ID](/selfhosted/identity-providers/managed/microsoft-entra-id) - Azure AD / Microsoft 365 -- [Google Workspace](/selfhosted/identity-providers/managed/google-workspace) - Google accounts +- [Google Workspace](/selfhosted/identity-providers/managed/google-workspace#management-setup-recommended) - Google accounts. Not recommended as a standalone IdP; use the Management Setup (Recommended) instead - [Okta](/selfhosted/identity-providers/managed/okta) - Enterprise SSO - [Auth0](/selfhosted/identity-providers/managed/auth0) - Flexible auth platform - [JumpCloud](/selfhosted/identity-providers/managed/jumpcloud) - Cloud directory Each provider page includes both "Management Setup (Recommended)" (for use with the embedded IdP) and "Standalone Setup (Advanced)" sections. For this guide, follow the **Standalone Setup (Advanced)** section. + +Google is the exception: its standalone setup is not recommended. Deploy with the [Quickstart guide](/selfhosted/selfhosted-quickstart), which uses the embedded IdP, and add Google with the [Management Setup (Recommended)](/selfhosted/identity-providers/managed/google-workspace#management-setup-recommended) section instead of continuing with this guide. ### Step 4: Disable single account mode (optional)