Google Cloud Platform Integration Setup

Getting Started

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

Requirements:

• 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

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.

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

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.

   
3. Fill in the required fields for creating the role.

   
4. Click on Add Permissions to add new permissions to the role.

   
5. Search for the following permissions and add them

   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.

   
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.

4. Click on the service account you just created and select the KEYS tab from the top.

   
5. Click on ADD KEY → Create new key.

   
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.

   

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.

  
• 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 (Allows viewing user profiles, emails, and metadata)

  Groups

  • ✅ Read (Allows viewing group memberships and details)

  Customer

  • ✅ Read customer (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)

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

   
3. Go to Security -> API Controls -> Domain-wide delegation of your Google Workspace.

4. Find the domain-wide delegation section and click on MANAGE.

   
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

   
6. For more info please refer: https://developers.google.com/identity/protocols/OAuth2ServiceAccount#delegatingauthority

Configuring Google Cloud Platform in your BalkanID tenant

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.

   

   
3. Set up the Primary Application owner (mandatory) and the Description, if any. Set up Secondary Application Owner(s), if any.

   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.

   3. Manual file upload - Upload Entity and Entity Relations through a .CSV file upload. Contact the team for assistance with this.

   4. Automated upload using API - You can upload data using our Bulk APIs with the help of an API key which will be provided to you. Please refer to the entity and entity relation 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.

   
4. Click on next to move onto Optional Configuration.

5. Fill Optional configuration, if required.

   
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.