Google Cloud Platform (GCP) | Entitle

1. In the GCP console, select the project for the Entitle service account, or the project where you plan to create it. Then go to IAM & Admin > Workload Identity Pools.

2. Create an identity pool. Click the Create Pool button and enter the following information:
   1. Name: entitle

      🚧

      Use entitle only. Never user special characters.

   2. Description: Enter a description to help you identify this identity pool later.
   3. Enabled pool: toggled on

3. Add a provider to the pool. Enter the following information:

   1. Select a provider: OpenID Connect (OIDC)

   2. Provider name: entitle

      🚧

      Use entitle only. Never user special characters.

   3. Issuer (URL): Enter the issuer URL provided for your Entitle agent environment.

      ℹ️

      • If your Entitle agent is hosted in the cloud within Entitle Europe (Ireland), use:
        https://oidc.eks.eu-west-1.amazonaws.com/id/7104B0E9ED58DCD19AE0DC0EC7D46D5D
      • If your Entitle agent is hosted in the cloud within Entitle USA use:
        https://oidc.eks.us-east-1.amazonaws.com/id/E1F031C91539B03EE726ED530E719F4C
      • If you are using an EKS-hosted agent running on your AWS account, run this command on your EKS cluster and use its output:

        aws eks describe-cluster --name <your eks cluster name> --query "cluster.identity.oidc.issuer" --output text --region <your eks cluster's region id>

   4. JWK file (JSON): Leave this field empty.

   5. Audiences: Allowed audiences

      • Audience 1: sts.amazonaws.com
      

4. Configure provider attributes. Enter the following information:
   1. Google 1: google.subject
   2. OIDC 1: assertion.sub
   3. Google 2: attribute.env
   4. OIDC 2: assertion.iss

5. Click Save.

5. Download the created JSON file on setup completion. You will use it later in this guide.

5. Open the GCP shell and execute:

# 1. Define the variables
export projectId=<your GCP project ID>
export poolId="entitle"
export providerId="entitle" 
export serviceAccountName="entitle-integrations-sa"  # The name of the service account Entitle's Google integrator scripts create
# 2. Run the commands
# 2.1 Identiy your GCP project number
export projectNumber=$(gcloud projects describe ${projectId} --format="value(projectNumber)")
echo $projectNumber
# 2.2 Allow Entitle to authenticate to the service account you created:
export issuerUrl=$(gcloud iam workload-identity-pools providers describe "${providerId}" \
    --workload-identity-pool="${poolId}" \
    --location="global" \
    --project="${projectId}" \
    --format="value(oidc.issuerUri)")

gcloud iam service-accounts add-iam-policy-binding \
    "${serviceAccountName}@${projectId}.iam.gserviceaccount.com" \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/${projectNumber}/locations/global/workloadIdentityPools/${poolId}/attribute.env/${issuerUrl}"
# 2.3 Identify your organization's universe domain value used in authentication
universeDomain=$(gcloud config get-value core/universe_domain)
echo $universeDomain
# 2.4 Grant yourself the serviceAccountTokenCreator role on the service account
export shellUser=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")
gcloud iam service-accounts add-iam-policy-binding \
    ${serviceAccountName}@${projectId}.iam.gserviceaccount.com \
    --member="user:${shellUser}" \
    --role="roles/iam.serviceAccountTokenCreator" \
    --project=${projectId}

# 2.5 Wait up to five minutes for the role granting to take affect.

# 2.6 Generate a temporary token for the integration onbaording
nonceValue=$(gcloud auth print-access-token \
    --impersonate-service-account="${serviceAccountName}@${projectId}.iam.gserviceaccount.com" \
    --lifetime=10m)
echo $nonceValue

1. Select Service Account Key if you created a service account key for the integration.

2. In the connection JSON, under the "service_account_key" field, paste the downloaded key JSON of your service account.

3. If you want to manage groups in your GCP integrations, provide "credential_subject" with the email address of an admin in your organization who has permission to view all users and groups. Otherwise, enter entitle-integrations-sa@<your project ID>.com.

4. If you want to limit the resource types managed by Entitle, add "resource_types_constraints": [] in an "options": {} object beneath "credential_subject": "", and specify the allowed resources types as a list of strings.

   Supported resource types

   projects
   folders
   datasets
   tables
   instances
   buckets
   sql_instances
   organizations
   secrets
   GKE clusters
   GKE namespaces
   groups
   functions
   service_accounts

   ✅

   Example

   …
     "credential_subject": "[email protected]",
     "options": {
       "resource_types_constraints": ["projects", "folders", "datasets"]
     }
   …

   ℹ️

   A non-existent field or an empty list means all Entitle-supported resource types, except tables and instances, can be managed.

5. If Domain-wide delegation for managing groups was set as .readonly for this integration, add "read_only": true to the "options" object.

   ✅

   Example

   …
     "credential_subject": "[email protected]",
     "options": {
       "read_only": true
     }
   …

6. If you want to audit when and how often Entitle grants permissions, enable this option to record the grant time and request number in the GCP IAM policy.

   In the options object, add "iam_policy_auditing": true.

   Limitations of the GCP IAM policy given by Google:

   • The policy cannot be larger than approximately 100kb.

     ℹ️

     Auditing significantly increases policy size. In environments with high usage, this can cause Entitle to reach the maximum policy size limit, preventing further access grants.

   • Maximum of 250 assignments in a binding (mapping between a role and users)

   • Maximum of 1500 assignments in a policy.

     

✅

Example configuration JSON

Entitle Configuration

{
  "service_account_key": {
		 // A dictionary from tthe downloaded JSON file
  },
  "credential_subject": "an email of an admin in your organization which has permission to view all users",
  "options": {
    "resource_types_constraints": ["buckets", "groups"],
    "read_only": false,
    "iam_policy_auditing": false
  }
}

Below is an example of how the options section should look. Make sure to add double quotations and commas in the appropriate places.

ℹ️

After access is granted, the user receives a message in Slack or the Entitle web app indicating that the user was added to the GCP IAM policy for the first time, not that a new user account was created.

1. Under the "workload_identity_federation" field, complete the relevant sub-fields:

   JSON

   {
     "workload_identity_federation": {
       "project_number": "<your GCP project number>",
       "pool_id": "entitle",
       "provider_id": "entitle",
       "service_account_email": "entitle-integrations-sa@<your project ID>.iam.gserviceaccount.com",
       "universe_domain": "<your GCP universe domain>",
       "nonce_value": "<the nonce value generated in the GCP shell>"
     },
     "credential_subject": "[email protected]"
   }

2. If you want to manage groups in your GCP integrations, provide "credential_subject" with the email address of an admin in your organization who has permission to view all users and groups. Otherwise, enter entitle-integrations-sa@<your project ID>.com.

3. If you want to limit the resource types managed by Entitle, add "resource_types_constraints": [] in an "options": {} object beneath "credential_subject": "", and specify the allowed resources types as a list of strings.

   Supported resource types

   projects
   folders
   datasets
   tables
   instances
   buckets
   sql_instances
   organizations
   secrets
   GKE clusters
   GKE namespaces
   groups
   functions
   service_accounts

   ✅

   Example

   …
     "credential_subject": "[email protected]",
     "options": {
       "resource_types_constraints": ["projects", "folders", "datasets"]
     }
   …

   ℹ️

   A non-existent field or an empty list means all Entitle-supported resource types, except tables and instances, can be managed.

4. If Domain-wide delegation for managing groups was set as .readonly for this integration, add "read_only": true to the "options" object.

   ✅

   Example

   …
     "credential_subject": "[email protected]",
     "options": {
       "read_only": true
     }
   …

5. If you want to audit when and how often Entitle grants permissions, enable this option to record the grant time and request number in the GCP IAM policy.

   In the options object, add "iam_policy_auditing": true.

   Limitations of the GCP IAM policy given by Google:

   • The policy cannot be larger than approximately 100kb.

     ℹ️

     Auditing significantly increases policy size. In environments with high usage, this can cause Entitle to reach the maximum policy size limit, preventing further access grants.

   • Maximum of 250 assignments in a binding (mapping between a role and users)

   • Maximum of 1500 assignments in a policy.

     

✅

Example configuration JSON

Entitle Configuration

{
  "workload_identity_federation": {
      "project_number": "1079892362871",
      "pool_id": "entitle",
      "provider_id": "entitle",
      "service_account_email": "[email protected]",
      "universe_domain": "googleapis.com",
      "nonce_value": "ya29.c.c0AZ1aNiXnE52LzJcIpo-FHo*****************"
    },
  "credential_subject": "[email protected]",
  "options": {
    "resource_types_constraints": [],
    "read_only": false,
    "iam_policy_auditing": false
  }
}

Below is an example of how the options section should look. Make sure to add double quotations and commas in the appropriate places.

ℹ️

After access is granted, the user receives a message in Slack or the Entitle web app indicating that the user was added to the GCP IAM policy for the first time, not that a new user account was created.

1. Select GKE Pod-based identity if you’re using the pre-configured Workload Identity service account of your GKE cluster.
2. Leave the connection JSON blank, and click Save.