some file

Google Workspace SSO with NetBird Self-Hosted (Legacy)

Use Google accounts for authentication with NetBird. This supports both personal Google accounts and Google Workspace (formerly G Suite) organizations.

Standalone Setup (Advanced)

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 only recommended for experienced Google Workspace administrators who need full control over authentication and user management.

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.

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, go back up to the Management Setup (Recommended) section above.

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.