some file

Google Workspace SSO with NetBird Self-Hosted (Legacy)

Updated

Using Google directly as NetBird's identity provider is not recommended. Use the embedded IdP with Google as an external provider instead. If you already run this standalone setup, migrate with the External IdP to Embedded IdP migration guide.

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.

NetBird includes built-in local user management 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) section in the main Google Workspace documentation.

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 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 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) 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). 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, 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.

Prerequisites

  1. Navigate to OAuth consent
  2. Select Internal User Type and click Create

Consent screen type

  1. Fill in the form:
    • App name: Netbird
    • User support email: <administrator email>
    • Authorized domain: <your netbird domain>
    • Developer contact information: <developer email>
  2. Click SAVE AND CONTINUE
  3. Click ADD OR REMOVE SCOPES
  4. Select /auth/userinfo.email, /auth/userinfo.profile, and openid
  5. Click UPDATE

Consent screen scopes

  1. Click SAVE AND CONTINUE
  2. Review the summary and click BACK TO DASHBOARD

Consent screen summary

Step 2: Create OAuth 2.0 Credentials

  1. Navigate to API Credentials
  2. Click CREATE CREDENTIALS → OAuth client ID
  3. Fill in:
    • Application type: Web application
    • Name: netbird
    • Authorized JavaScript origins: https://<your domain> and http://localhost
    • Authorized redirect URIs:
      • https://<your domain>/auth
      • https://<your domain>/silent-auth
      • http://localhost:53000
  4. Click CREATE

OAuth client

  1. Note Client ID and Client Secret

OAuth client created

Step 3: Create Service Account

  1. Navigate to API Credentials
  2. Click CREATE CREDENTIALS → Service account
  3. Fill in:
    • Service account name: netbird
    • Service account ID: netbird
  4. Note the service account email address
  5. Click DONE

Create service account

Step 4: Create Service Account Keys

  1. Navigate to API Credentials
  2. Under Service Accounts, click netbird to edit

Edit service account

  1. Click the Keys tab
  2. Click Add key → Create new key
  3. Select JSON and click Create

The key file downloads automatically. Store it securely. Read about managing service account keys.

  1. Open the downloaded JSON file and note the client_id (Service Account Client ID)

Step 5: Grant User Management Admin Role

  1. Navigate to Admin Console
  2. Select Account → Admin Roles
  3. Click Create new role
  4. Fill in:
    • Name: User Management ReadOnly
    • Description: User Management ReadOnly
  5. Click CONTINUE

New role info

  1. Scroll to Admin API privileges and add:
    • Users: Read
  2. Click CONTINUE

Privileges review

  1. Click CREATE ROLE
  2. Click Assign service accounts
  3. Add the service account email address
  4. Click ADD then ASSIGN ROLE

Assign role

Service account privileges

  1. Navigate to Account Settings and note the Customer ID

Step 6: Encode Service Account Key

base64 -i <SERVICE_ACCOUNT_KEY_PATH>

Step 7: Configure NetBird

Set properties in the setup.env file:

NETBIRD_DOMAIN="<YOUR_DOMAIN>"
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://accounts.google.com/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_AUDIENCE="<OAUTH_CLIENT_ID>"
NETBIRD_AUTH_CLIENT_ID="<OAUTH_CLIENT_ID>"
NETBIRD_AUTH_CLIENT_SECRET="<OAUTH_CLIENT_SECRET>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
NETBIRD_TOKEN_SOURCE="idToken"

NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"

NETBIRD_MGMT_IDP="google"
NETBIRD_MGMT_IDP_SIGNKEY_REFRESH=true
NETBIRD_IDP_MGMT_EXTRA_SERVICE_ACCOUNT_KEY="<BASE64_SERVICE_ACCOUNT_KEY>"
NETBIRD_IDP_MGMT_EXTRA_CUSTOMER_ID="<GOOGLE_WORKSPACE_CUSTOMER_ID>"

Step 8: Continue with NetBird Setup

You've configured all required resources in Google Workspace. Continue with the NetBird Self-hosting Guide.

Troubleshooting

"Access blocked" error

  • Ensure OAuth consent screen is configured correctly
  • For external apps, you may need to submit for verification or add test users
  • Check that required scopes are added

"Invalid redirect URI" error

  • Verify the redirect URI exactly matches what's in Google Cloud Console
  • Check for trailing slashes or HTTP vs HTTPS mismatches
  • Google is case-sensitive for redirect URIs

Users from wrong domain signing in

  • For Workspace, use Internal user type in OAuth consent screen
  • Verify domain restrictions in consent screen settings

Service account not syncing users

  • Verify Admin SDK API is enabled
  • Check that the service account has the User Management ReadOnly role
  • Ensure the Customer ID is correct

NetBird includes built-in local user management 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) section in the main Google Workspace documentation.