# Google Cloud Platform Integration Setup

### Getting Started <a href="#h_01hq18ccm0ztv1ems1ex1fq8r6" id="h_01hq18ccm0ztv1ems1ex1fq8r6"></a>

BalkanID recommends creating a separate service account for the purposes of this integration, instead of using personal or employee named accounts.

#### Requirements: <a href="#h_01hq2tq8q255x9410dphf9ktse" id="h_01hq2tq8q255x9410dphf9ktse"></a>

* **Key:** This refers to the **Service Account Key (in JSON format)** that you will generate for the dedicated GCP service account. This key is used by BalkanID to securely authenticate and access your GCP resources programmatically.
* **Delegated:** The email address of a user in your Google Workspace domain that has been granted **domain-wide delegation**. BalkanID, through the service account, will impersonate this delegated user to access **Google Workspace directory data** (users, groups, and admin roles).
* **Domain:** This is the **primary domain name associated with your Google Workspace organization** (e.g., `yourcompany.com`). It's crucial for identifying the correct Google Workspace directory from which BalkanID will retrieve user identities, email addresses, and group access information.
* **Project:** The GCP **project ID or name** under which the dedicated service account is created.\
  Although the service account resides in a project, its permissions will be **granted at the organization level** (explained below).

**Who performs this task**

1. An *identity administrator* responsible for assigning role-based access to individuals or groups within your organisation. This individual needs to be a Super Administrator for Cloud Identity or Workspace.
2. A *domain administrator* with access to the company's domain host, to see and edit domain settings such as DNS configurations.

#### Getting access permissions <a href="#h_01hq18fmjv5a86yd2c64n9mwgs" id="h_01hq18fmjv5a86yd2c64n9mwgs"></a>

**You will be required to perform the below steps:**

1. Enable required APIs
2. Create a custom role (at organization level)
3. Create a service account
4. Add domain delegation scopes to the service account

#### **Enabling required APIs**

1. Go to *Google Cloud* → *APIs and service* → *Enabled APIs and services*, search for the required APIs and enable it.

<figure><img src="/files/xUQaKFl8AYdkAorafDJw" alt=""><figcaption></figcaption></figure>

2. **Search and enable the following APIs**

```
Cloud Asset API
Identity and Access Management (IAM) API
Cloud Resource Manager API
Admin SDK API
Cloud Identity API
```

In addition to the APIs listed above, the below APIs must be enabled to ensure  discovery of GCP [Credentials](/getting-started/entitlement-data-discovery/credentials-discovery/google-cloud-platform-credentials.md).

```
Cloud Storage API
Compute Engine API
Certificate Manager API
Policy Analyzer API
API Keys API
```

#### Create a Custom Role (at the Organization Level)

> **Important:**\
> The custom role must be created **at the organization level** (not project level).\
> This is required because BalkanID needs to pull **inherited IAM information** from both folders and the organization.\
> Without org-level scope, inherited roles and access relationships would not be visible.

**Creating a custom role and assigning permissions**

1. Go to *IAM* and *Admin* → *Roles.*
2. Click on **+ CREATE ROLE** to proceed with creating a custom role.<br>

   <figure><img src="/files/C654zqQTtIVTZQX267Aq" alt=""><figcaption></figcaption></figure>
3. Fill in the required fields for creating the role.

   <figure><img src="/files/JmSnL7ticZwDDnXho3sk" alt="" width="563"><figcaption></figcaption></figure>
4. Click on **Add Permissions** to add new permissions to the role.

   <figure><img src="/files/c8qOuEhMTgrNH6UwQmAc" alt="" width="375"><figcaption></figcaption></figure>
5. Search for the following permissions and add them

   ```markup
   cloudasset.assets.searchAllIamPolicies
   cloudasset.assets.searchAllResources
   cloudasset.assets.analyzeIamPolicy
   iam.roles.get
   iam.roles.list
   iam.serviceAccounts.get
   iam.serviceAccounts.list
   resourcemanager.folders.get
   resourcemanager.organizations.get
   resourcemanager.projects.get
   ```
6. Click on **CREATE** to create the role.

#### **Creating a service account**

1. Go to *IAM* and *Admin* → *Service Accounts.*
2. Click on **Create service account** button on the top to proceed.<br>

   <figure><img src="/files/t7VW12AflwxLtXcSEK67" alt="" width="375"><figcaption></figcaption></figure>
3. When you are in the second step, select the necessary permissions for its operation, in this case the new Custom Role. For more information - [Creating an account.](https://developers.google.com/identity/protocols/oauth2/service-account#creatinganaccount)
4. Click on the service account you just created and select the **KEYS** tab from the top.<br>

   <figure><img src="/files/5kOtxo0iEa8JwrglOj8k" alt=""><figcaption></figcaption></figure>
5. Click on **ADD KEY → Create new key.**<br>

   <figure><img src="/files/tNcqqVoK7TZJrlWHpOF0" alt="" width="375"><figcaption></figcaption></figure>
6. Select **JSON** and click on the **CREATE** button, the wizard will create a JSON file to download with the necessary key for later use.
7. Go to **IAM and Admin** → IAM. You can view the service account and permissions granted in the IAM.<br>

   <figure><img src="/files/gJlePur5wnVsQuhQO415" alt=""><figcaption></figcaption></figure>

### Creating a Custom Admin Role in Google Workspace (GWS)

#### Why This Is Needed

The delegated user that service account impersonates needs permission to **read directory information** (users, groups, and customer details) through the **Admin SDK API**.\
This role does *not* need **Super Admin privileges** only the specific **read** permissions required for API access. Creating a custom “Read-Only Role” helps you follow the principle of least privilege.

* Steps to Create a Custom Admin Role
  * Go to <https://admin.google.com>
  * Log in using an account with **Super Admin** privileges.
* **Navigate to Admin Roles**

  * In the left-hand menu, go to **Directory → Roles and administrators** (or simply **Admin roles**).
  * Click on **Create new role**.

  <figure><img src="/files/RMcOGxY208XEgx9ExVgO" alt=""><figcaption></figcaption></figure>
* **Configure Basic Role Details**
  * **Name**: `Read-Only Role` (or any preferred name)
  * **Description**: `Provides read-only access to users, groups, and customer organization details for BalkanID integration.`\
    Click **Continue**.
* **Assign the Required Privileges**

  Under **Admin API privileges**, enable only the following:

  **Users**

  * ✅ Read\
    \&#xNAN;*(Allows viewing user profiles, emails, and metadata)*

  **Groups**

  * ✅ Read\
    \&#xNAN;*(Allows viewing group memberships and details)*

  **Customer**

  * ✅ Read customer\
    \&#xNAN;*(Allows viewing organization/customer profile, contact, and settings data)*
* **Save the Role**

  Click **Create Role** to save the configuration.
* **Assign the Role to the Delegated User**

  Once the role is created:

  * Go back to **Admin roles**.
  * Select the new **Read-Only Role**.
  * Click **Assign users** and choose the **delegated email** (the same email used in the GCP setup).
  * Click **Assign Role**.

#### Delegate Configuration

Please ensure the **same delegated email** exists in **both GCP and GWS**:

* In **GCP**:

  * Assign the **custom org-level role** to the delegated email **at the organization level (not at the project level)**.

  > This is required because the integration needs to pull **inherited IAM information** from folders and the organization project-level roles only allow access within a single project and won’t include inherited permissions.
* In **Google Workspace (GWS)**:
  * The same email should have [**Custom (Read Only Role)**](#creating-a-custom-admin-role-in-google-workspace-gws)
  * This allows the service account to access user and group data by impersonating an authorized administrator through domain-wide delegation.

#### Add Domain-Wide Delegation Scopes

1. You need to add domain delegation scopes to the service account, first get the OAuth2 client ID from the Service account.
2. Go to *IAM* and *Admin* → *Service Accounts* and copy the OAuth 2 Client ID of the service account you just created.<br>

   <figure><img src="/files/hJzMROLQd9r29wf8Pfn5" alt=""><figcaption></figcaption></figure>
3. Go to [*Security* -> *API Controls* -> *Domain-wide delegation*](https://admin.google.com/u/1/ac/owl/domainwidedelegation) of your [Google Workspace](https://admin.google.com/).
4. Find the domain-wide delegation section and click on **MANAGE**.<br>

   <figure><img src="/files/uZdLdpo6syzyNo3BfsTn" alt="" width="563"><figcaption></figcaption></figure>
5. Enter the copied client ID and add the following OAuth scopes.

   ```
   https://www.googleapis.com/auth/admin.directory.user.readonly,
   https://www.googleapis.com/auth/admin.directory.user,
   https://www.googleapis.com/auth/admin.directory.group,
   https://www.googleapis.com/auth/admin.directory.customer.readonly,
   https://www.googleapis.com/auth/cloud-identity.groups.readonly,
   https://www.googleapis.com/auth/cloud-identity.groups,
   https://www.googleapis.com/auth/cloud-platform,
   https://www.googleapis.com/auth/cloudfunctions,
   https://www.googleapis.com/auth/compute
   ```

   <br>

   <figure><img src="/files/3A95UwAv7ldaxUVt9QJK" alt="" width="375"><figcaption></figcaption></figure>
6. For more info please refer: <https://developers.google.com/identity/protocols/OAuth2ServiceAccount#delegatingauthority>

### Configuring Google Cloud Platform in your BalkanID tenant <a href="#h_01hawnf26kmntar1ewsgkx56ee" id="h_01hawnf26kmntar1ewsgkx56ee"></a>

1. Login to the BalkanID application and switch to the tenant you would like to add your integration to.
2. Head to *Integrations* > **Add Integration**, select **Google Cloud Platform.**<br>

   <figure><img src="/files/3q2C00J9PMgDDtIEyGrx" alt=""><figcaption></figcaption></figure>

   <figure><img src="/files/k1VzBMBiY0T8rYy3adTm" alt=""><figcaption></figcaption></figure>
3. Set up the *Primary Application owner (mandatory)* and the *Description*, if any. Set up Secondary Application Owner(s), if any. <br>

   Select the Extraction Type. From here, you can configure your application using one of the following methods:

   1. **Direct integration** - Provide your Service Account Key(in JSON), Email of delegate, Domain and Project ID obtained above to set up a direct connection with BalkanID.
   2. **SCIM integration** - Provide SCIM server credentials to set up a SCIM connection with BalkanID.&#x20;
   3. **Manual file upload** - Upload Entity and Entity Relations through a .CSV file upload. Contact the team for assistance with this. &#x20;
   4. **Automated upload using API -** You can upload data using our [Bulk APIs](https://developer.balkan.id/) with the help of an API key which will be provided to you. Please refer to the [entity](https://developer.balkan.id/bulk-entities-upload-api-early-access-12828095e0) and [entity relation](https://developer.balkan.id/bulk-entity-relations-upload-api-early-access-12828102e0) upload docs for specific instructions on uploading your data through the API. \
      \
      **Note:** Use the **KEY JSON** downloaded in the 3rd step to fill in the key. Add a user’s email **with access to domain-wide delegation** in the delegated field. Fill in the domain name and the project’s ID as well.

   <figure><img src="/files/m0XBIzRu9chdzimk9wo2" alt="" width="563"><figcaption></figcaption></figure>
4. Click on next to move onto *Optional Configuration.*
5. Fill **Optional configuration,** if required.  <br>

   <figure><img src="/files/n3fAOw97aIUGKB2l30BK" alt="" width="563"><figcaption></figcaption></figure>
6. Once you filled in the information, click **Save**. Your integration is now configured and you will see the status of the integration displayed alongside other integrations on the *Integrations* page. When data is available, the integration Status will read **Connected** and the integration Message will read **Data available**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/google-cloud-platform-integration-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.