sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-21 09:56:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

DEX Docs Overall Updates

Browse Source
This commit is contained in:
Brandon Hopkins
2026-01-05 13:28:12 -08:00
parent ec76ca2524
commit 5d31b84c22
22 changed files with 4756 additions and 910 deletions
Download Patch File Download Diff File Expand all files Collapse all files

349
src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
View File

@@ -1,127 +1,237 @@
import {Note} from "@/components/mdx";
# Google Workspace with NetBird Self-Hosted
# Google Workspace
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate
**self-hosted** NetBird with [Google Workspace](https://workspace.google.com/).
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>
Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP manager no longer requires the creation of a custom admin role called `User and Schema Management`.
Instead, we are transitioning towards a more tailored role explicitly designed for managing read-only user information.
Consequently, you have the option to remove the previously established custom admin role and refer to the documentation to configure the admin role scope for read-only access correctly.
Google connectors don't require an Issuer field—it's determined automatically.
</Note>
Before you start creating and configuring an Google Workspace application, ensure that you have the following:
- An Google Workspace account: To create an Google Work application, you must have an Google Workspace. If you don't have one, sign up at https://workspace.google.com/business/signup/welcome.
- User account with admin permissions: You must have an Google Workspace user account with the admin permissions to create and manage Google Workspace applications. If you don't have the required permissions, ask your workspace administrator to grant them to you.
- Create new `Netbird` project in Google cloud console https://console.cloud.google.com.
- Enable `Admin SDK API` for `Netbird` project at https://console.cloud.google.com/apis/library/admin.googleapis.com.
5. Click **Save**
## Step 1: Configure OAuth consent screen
- Navigate to [OAuth consent](https://console.cloud.google.com/apis/credentials/consent) page
- 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="high-level-dia" className="imagewrapper-big"/>
</p>
### Step 3: Configure Redirect URI
- Fill in the form with the following values and click `SAVE AND CONTINUE`
- App name: `Netbird`
- User support email: `<administrator email address>`
- Authorized domain: `<your netbird domain>`
- Developer contact information: `<developer email address>`
- Click `ADD OR REMOVE SCOPES`
- Select `/auth/userinfo.email`, `/auth/userinfo.profile` and `openid` scopes and then click `UPDATE`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-scopes.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
- Click `SAVE AND CONTINUE`
- Verify the summary of the OAuth consent screen to ensure that everything is properly configured, and then click `BACK TO DASHBOARD`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-summary.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Google OAuth client:
## Step 2: Create OAuth 2.0 credentials
- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page
- Click `CREATE CREDENTIALS` at the top and select `OAuth client ID`
- Fill in the form with the following values and click `CREATE`
- Application type: `Web application`
- Name: `netbird`
- Authorized JavaScript origins: `https://<your netbird domain>` and `http://localhost`
- Authorized redirect URIs: `https://<your netbird domain>/auth`, `https://<your netbird domain>/silent-auth` and `http://localhost:53000`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
- Take note of `Client ID` and `Client Secret` and click `OK`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client-created.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
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 3: Create service account
- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page
- Click `CREATE CREDENTIALS` at the top and select `Service account`
- Fill in the form with the following values and click `CREATE`
- Service account name: `netbird`
- Service account ID: `netbird`
- Take note of service account email address, we will use it later
- Click `DONE`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-create.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### Step 4: Test the Connection
## Step 4: Create service account keys
- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page
- Under `Service Accounts` click the `netbird` to edit the service account
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-edit-service-account.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
- Click the `Keys` tab
- Click the `Add key` drop-down menu, then select `Create new key`
- Select `JSON` as the Key type and click `Create`
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>
When you create a service account key by using the Google Cloud console, most browsers immediately download the new key and save it in a download folder on your computer.
Read how to manage and secure your service keys [here](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#temp-locations)
Domain restrictions are configured in Google Cloud Console, not in NetBird.
</Note>
- Open downloaded json file and take note of `client_id` will be used later as `Service Account Client ID`
---
## 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**
## Step 5: Grant user management admin role to service account
- Navigate to [Admin Console](https://admin.google.com/ac/home) page
- Select `Account` on the left menu and then click `Admin Roles`
- Click `Create new role`
- Fill in the form with the following values and click `CREATE`
- name: `User Management ReadOnly`
- description: `User Management ReadOnly`
- Click `CONTINUE`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-new-role-info.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-type.png" alt="Consent screen type" className="imagewrapper-big"/>
</p>
- Scroll down to `Admin API privileges` and add the following privileges
- Users: `Read`
- Click `CONTINUE`
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-privileges-review.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
- Verify preview of assigned Admin API privileges to ensure that everything is properly configured, and then click `CREATE ROLE`
- Click `Assign service accounts`, add service account email address and then click `ADD`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-assign-role.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
- Click `ASSIGN ROLE` to assign service account to `User Management ReadOnly` role
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-privileges.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-scopes.png" alt="Consent screen scopes" className="imagewrapper-big"/>
</p>
- Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile?hl=en_US) page and take note of `Customer ID`
8. Click **SAVE AND CONTINUE**
9. Review the summary and click **BACK TO DASHBOARD**
- Encode service account json key into base64 format
```sh
base64 -i <SERVICE_ACCOUNT_KEY_PATH>
```
<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>
- Set properties in the `setup.env` file:
```json
### 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
@@ -141,5 +251,42 @@ NETBIRD_IDP_MGMT_EXTRA_SERVICE_ACCOUNT_KEY="<BASE64_SERVICE_ACCOUNT_KEY>"
NETBIRD_IDP_MGMT_EXTRA_CUSTOMER_ID="<GOOGLE_WORKSPACE_CUSTOMER_ID>"
```
## Step 6: Continue with the NetBird Self-hosting Guide
You've configured all required resources in Google Workspace. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
### 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)