Add google workspace setup docs (#65)

* configure google OAuth conset screen * Create google OAuth 2.0 credentials * add user and schema management admin role to service account * grant service account permission to access org data * configure setup.env for google workspace * add step to enable admin sdk api * refactoring * add step to encode service account json key
2026-04-18 00:16:36 +00:00 · 2023-06-20 22:59:59 +03:00
parent 23d55bc297
commit 67091b4f79
14 changed files with 158 additions and 1 deletions
--- a/src/pages/selfhosted/identity-providers.mdx
+++ b/src/pages/selfhosted/identity-providers.mdx
@@ -960,7 +960,164 @@ NETBIRD_AUTH_DEVICE_AUTH_SCOPE="openid email"
 NETBIRD_AUTH_DEVICE_AUTH_USE_ID_TOKEN=true

 NETBIRD_MGMT_IDP="okta"
-NETBIRD_IDP_MGMT_EXRA_API_TOKEN="<api_token>"
+NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="<api_token>"
+```
+
+- You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-5-run-configuration-script).
+
+- Modify the value of the `AUTH_SUPPORTED_SCOPES` environment variable for the dashboard service in the docker-compose.yml file to `openid profile email`.
+
+## Google Workspace
+
+This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate 
+**self-hosted** NetBird with [Google Workspace](https://workspace.google.com/).
+
+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.
+
+### 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/integrations/identity-providers/self-hosted/google-consent-screen-type.png" alt="high-level-dia" class="imagewrapper"/>
+</p>
+
+- 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/integrations/identity-providers/self-hosted/google-consent-screen-scopes.png" alt="high-level-dia" class="imagewrapper"/>
+</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/integrations/identity-providers/self-hosted/google-consent-screen-summary.png" alt="high-level-dia" class="imagewrapper"/>
+</p>
+
+### 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>`
+    - Authorized redirect URIs: `https://<your netbird domain>/auth` and `https://<your netbird domain>/silent-auth`
+<p>
+    <img src="/docs-static/img/integrations/identity-providers/self-hosted/google-oauth-client.png" alt="high-level-dia" class="imagewrapper"/>
+</p>
+- Take note of `Client ID` and `Client Secret` and click `OK`
+<p>
+    <img src="/docs-static/img/integrations/identity-providers/self-hosted/google-oauth-client-created.png" alt="high-level-dia" class="imagewrapper"/>
+</p>
+
+### 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/integrations/identity-providers/self-hosted/google-service-account-create.png" alt="high-level-dia" class="imagewrapper"/>
+</p>
+
+### 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/integrations/identity-providers/self-hosted/google-edit-service-account.png" alt="high-level-dia" class="imagewrapper"/>
+</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`
+
+<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)
+</Note>
+
+- Open downloaded json file and take note of `client_id` will be used later as `Service Account Client ID`
+
+### Step 5: Grant user and schema 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 and Schema Management Admin`
+    - description: `User and Schema Management Admin`
+- Click `CONTINUE`
+<p>
+    <img src="/docs-static/img/integrations/identity-providers/self-hosted/google-new-role-info.png" alt="high-level-dia" class="imagewrapper"/>
+</p>
+
+- Scroll down to `Admin API privileges` and add the following provileges
+    - Users: `Create`, `Read` and  `Update Custom Attributes`
+    - Schema Management: `Schema Management` and `Schema Read`
+- Click `CONTINUE`
+<p>
+    <img src="/docs-static/img/integrations/identity-providers/self-hosted/google-privileges-review.png" alt="high-level-dia" class="imagewrapper"/>
+</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/integrations/identity-providers/self-hosted/google-assign-role.png" alt="high-level-dia" class="imagewrapper"/>
+</p>
+- Click `ASSIGN ROLE` to assign service account to `User and Schema Management Admin` role
+<p>
+    <img src="/docs-static/img/integrations/identity-providers/self-hosted/google-service-account-privileges.png" alt="high-level-dia" class="imagewrapper"/>
+</p>
+
+### Step 6: Granting service account access to organization data
+- Navigate to [Admin Console](https://admin.google.com/ac/home) page
+- Select `Security` > `Access and data control` > `API controls` and then click `MANAGE DOMAIN WIDE DELEGATION`
+- Click `Add new`
+- Fill in the form with the following values
+    - Client ID: `<Service Account Client ID>`
+    - OAuth scopes: `https://www.googleapis.com/auth/admin.directory.user`, `https://www.googleapis.com/auth/admin.directory.userschema`
+<p>
+    <img src="/docs-static/img/integrations/identity-providers/self-hosted/google-new-domain-delegation.png" alt="high-level-dia" class="imagewrapper"/>
+</p>
+- Click `AUTHORIZE`
+<p>
+    <img src="/docs-static/img/integrations/identity-providers/self-hosted/google-domain-delegation-added.png" alt="high-level-dia" class="imagewrapper"/>
+</p>
+
+- Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile?hl=en_US) page and take note of `Customer ID`
+
+- Encode service account json key into base64 format
+    ```sh 
+    base64 -i <SERVICE_ACCOUNT_KEY_PATH>
+    ```
+
+- Set properties in the `setup.env` file:
+```json
+NETBIRD_DOMAIN="<YOUR_DOMAIN>"
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://accounts.google.com/.well-known/openid-configuration"
+NETBIRD_USE_AUTH0=false
+NETBIRD_AUTH_AUDIENCE="<CLIENT_ID>"
+NETBIRD_AUTH_CLIENT_ID="<CLIENT_ID>"
+NETBIRD_AUTH_CLIENT_SECRET="<CLIENT_SECRET>"
+NETBIRD_AUTH_REDIRECT_URI="/auth"
+NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
+NETBIRD_TOKEN_SOURCE="idToken"
+
+NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="hosted"
+NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<CLIENT_ID>"
+NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<CLIENT_ID>"
+NETBIRD_AUTH_DEVICE_AUTH_SCOPE="openid email"
+NETBIRD_AUTH_DEVICE_AUTH_USE_ID_TOKEN=true
+
+NETBIRD_MGMT_IDP="google"
+NETBIRD_IDP_MGMT_EXTRA_SERVICE_ACCOUNT_KEY="<BASE64_SERVICE_ACCOUNT_KEY>"
+NETBIRD_IDP_MGMT_EXTRA_CUSTOMER_ID="<GOOGLE_WORKSPACE_CUSTOMER_ID>"
 ```

 - You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-5-run-configuration-script).