some file

Google Workspace

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

Add Google as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments.

Prerequisites

Step 1: Create OAuth Credentials

  1. Go to Google Cloud Console
  2. Select or create a project
  3. Navigate to APIs & Services → Credentials
  4. Click Create Credentials → OAuth client ID
  5. If prompted, configure the OAuth consent screen first:
    • Choose Internal (for Workspace) or External (for any Google account)
    • Fill in required fields (app name, support email)
    • Add scopes: email, profile, openid
    • Save and continue
  6. Back in Credentials, create the OAuth client:
    • Application type: Web application
    • Name: NetBird
    • Leave redirect URIs empty for now
  7. Click Create
  8. Note the Client ID and Client Secret

Step 2: Add Connector in NetBird

  1. Log in to your NetBird Dashboard
  2. Navigate to Settings → Identity Providers
  3. Click Add Identity Provider
  4. Fill in the fields:
FieldValue
TypeGoogle
NameGoogle (or your preferred display name)
Client IDFrom Google Cloud Console
Client SecretFrom Google Cloud Console

Google connectors don't require an Issuer field—it's determined automatically.

  1. Click Save

Step 3: Configure Redirect URI

After saving, NetBird displays the Redirect URL. Copy this URL and add it to your Google OAuth client:

  1. Return to Google Cloud Console → Credentials
  2. Click on your OAuth client
  3. Under Authorized redirect URIs, click Add URI
  4. Paste the redirect URL from NetBird
  5. Click Save

Step 4: Test the Connection

  1. Log out of NetBird Dashboard
  2. On the login page, you should see a "Google" button
  3. Click it and sign in with your Google account
  4. You should be redirected back to NetBird and logged in

Restricting to Google Workspace Domains

To limit authentication to specific Google Workspace domains:

  1. Go to APIs & Services → OAuth consent screen
  2. Under User type, select Internal (Workspace only)
  3. For external apps, verify your domain to restrict access

Domain restrictions are configured in Google Cloud Console, not in NetBird.

Standalone Setup (Advanced)

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 Connector 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