import {Note} from "@/components/mdx";

# Google Workspace

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

## Connector Setup (Recommended)

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

### Prerequisites

- NetBird self-hosted with embedded IdP enabled
- Access to [Google Cloud Console](https://console.cloud.google.com/)

### Step 1: Create OAuth Credentials

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
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:

| Field | Value |
|-------|-------|
| Type | Google |
| Name | Google (or your preferred display name) |
| Client ID | From Google Cloud Console |
| Client Secret | From Google Cloud Console |

<Note>
Google connectors don't require an Issuer field—it's determined automatically.
</Note>

5. 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

<Note>
Domain restrictions are configured in Google Cloud Console, not in NetBird.
</Note>

---

## Standalone Setup (Advanced)

Use Google Workspace as your primary identity provider instead of the embedded IdP. This enables full user management integration with Google Workspace.

<Note>
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.
</Note>

### Prerequisites

- A Google Workspace account (not just personal Google)
- Admin permissions in Google Workspace
- A project in [Google Cloud Console](https://console.cloud.google.com)
- Enable **Admin SDK API** for your project at https://console.cloud.google.com/apis/library/admin.googleapis.com

### Step 1: Configure OAuth Consent Screen

1. Navigate to [OAuth consent](https://console.cloud.google.com/apis/credentials/consent)
2. Select **Internal** User Type and click **Create**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-type.png" alt="Consent screen type" className="imagewrapper-big"/>
</p>

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

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-scopes.png" alt="Consent screen scopes" className="imagewrapper-big"/>
</p>

8. Click **SAVE AND CONTINUE**
9. Review the summary and click **BACK TO DASHBOARD**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-summary.png" alt="Consent screen summary" className="imagewrapper-big"/>
</p>

### Step 2: Create OAuth 2.0 Credentials

1. Navigate to [API Credentials](https://console.cloud.google.com/apis/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**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client.png" alt="OAuth client" className="imagewrapper-big"/>
</p>

5. Note **Client ID** and **Client Secret**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client-created.png" alt="OAuth client created" className="imagewrapper-big"/>
</p>

### Step 3: Create Service Account

1. Navigate to [API Credentials](https://console.cloud.google.com/apis/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**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-create.png" alt="Create service account" className="imagewrapper-big"/>
</p>

### Step 4: Create Service Account Keys

1. Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials)
2. Under **Service Accounts**, click **netbird** to edit

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-edit-service-account.png" alt="Edit service account" className="imagewrapper-big"/>
</p>

3. Click the **Keys** tab
4. Click **Add key** → **Create new key**
5. Select **JSON** and click **Create**

<Note>
The key file downloads automatically. Store it securely. Read about [managing service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#temp-locations).
</Note>

6. 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](https://admin.google.com/ac/home)
2. Select **Account** → **Admin Roles**
3. Click **Create new role**
4. Fill in:
   - **Name**: `User Management ReadOnly`
   - **Description**: `User Management ReadOnly`
5. Click **CONTINUE**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-new-role-info.png" alt="New role info" className="imagewrapper-big"/>
</p>

6. Scroll to **Admin API privileges** and add:
   - **Users**: `Read`
7. Click **CONTINUE**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-privileges-review.png" alt="Privileges review" className="imagewrapper-big"/>
</p>

8. Click **CREATE ROLE**
9. Click **Assign service accounts**
10. Add the service account email address
11. Click **ADD** then **ASSIGN ROLE**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-assign-role.png" alt="Assign role" className="imagewrapper-big"/>
</p>

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-privileges.png" alt="Service account privileges" className="imagewrapper-big"/>
</p>

12. Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile) and note the **Customer ID**

### Step 6: Encode Service Account Key

```bash
base64 -i <SERVICE_ACCOUNT_KEY_PATH>
```

### Step 7: Configure NetBird

Set properties in the `setup.env` file:

```shell
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](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).

---

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

---

## Related Resources

- [Google Cloud Console](https://console.cloud.google.com/)
- [Google OAuth 2.0 Documentation](https://developers.google.com/identity/protocols/oauth2)
- [Google Workspace Admin Console](https://admin.google.com/)
- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)