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

# Google Workspace with NetBird Self-Hosted

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

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

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

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

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

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

<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 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"/>
</p>

- Scroll down to `Admin API privileges` and add the following privileges
    - Users: `Read`
- Click `CONTINUE`
<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"/>
</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="<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 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).