Getting Started

Overview

This guide walks you through connecting a GCP organization to Britive and granting your first just-in-time IAM role assignment — no standing permissions, full audit trail on every checkout.

What you’ll accomplish:

Create a Britive service account in GCP with the required IAM roles
Onboard the GCP application in the Britive console
Create an access profile for a GCP IAM role
Check out and verify JIT access end-to-end

How It Works

Britive uses a dedicated GCP service account to manage IAM policy bindings via the Cloud Resource Manager API. At checkout, Britive adds a scoped IAM binding for the user on the target project or resource. At checkin (or on expiry), the binding is removed — no standing access remains.

User → Britive Console → Cloud Resource Manager API → Project IAM binding (timed) → Removed on checkin

Before You Begin

Britive tenant with administrator access
GCP Organization Admin or Project IAM Admin access to create service accounts and IAM bindings
A GCP project to host the Britive service account
gcloud CLI installed and authenticated (gcloud auth application-default login)

Never hardcode credentials. Use environment variables, your secret manager, or the Britive Secrets Store.

Step 1 — Create Britive Integration Resources in GCP

Britive needs a service account with a custom IAM role that allows it to enumerate and manage IAM bindings across your organization.

Terraform

The templates are in the britive/onboarding repository. A single deploy.sh script provisions the GCP resources, pauses for you to configure Domain Wide Delegation manually, then provisions the Google Workspace resources.

Clone and configure variables

git clone https://github.com/britive/onboarding.git
cd onboarding/terraform/google-cloud

Create a variables.tfvars file with your values (the variables are declared in main.tf):

terraform/google-cloud/variables.tfvars

organization_id       = "123456789012"
common_resource_name  = "BritiveIntegration"
workspace_customer_id = "C0xxxxxxx"
workspace_domain      = "yourcompany.com"

Run the deploy script

bash deploy.sh

deploy.sh runs gcloud auth application-default login, applies the GCP Terraform (a new project, a custom IAM role at the organization level, the BritiveIntegration service account, and its key written to keys/key.json), then prints the service account client ID and the OAuth scopes you need for Domain Wide Delegation.

Domain Wide Delegation must be configured manually in the Google Workspace Admin console — the script pauses and waits for you. This step cannot be automated.

When prompted, open admin.google.com → Security → Access and data control → API controls → Manage Domain Wide Delegation → Add new, enter the client ID and OAuth scopes shown by the script, then press ENTER to continue. The script applies the Workspace Terraform, retrying every 10 seconds until the delegation has propagated.

Python Automation

The setup_gcp.py script creates the service account and custom role using application-default credentials. It is idempotent — safe to re-run.

git clone https://github.com/britive/onboarding.git
cd onboarding
pip3 install -r requirements.txt

Authenticate with GCP:

gcloud auth application-default login

Run the setup script:

python python/google-cloud/setup_gcp.py \
  --project_id your-project-id \
  --role_id BritiveIntegrationRole \
  --service_account_name sa-britive-service \
  --service_account_display_name "Britive Service Account"

The script pauses briefly after creating the custom role to allow IAM propagation before binding the role to the service account.

Manual Setup

Create a GCP service account

In the GCP console, go to IAM & Admin → Service Accounts → Create Service Account. Name it britive-integration.

Grant required IAM roles

At the organization level, grant the service account these roles. The Terraform and Python paths instead create a custom role with the exact permissions ( iam.serviceAccounts.*, iam.serviceAccountKeys.*, iam.roles.get/list, and resourcemanager.*.get/list/getIamPolicy/setIamPolicy ); these predefined roles approximate that set:

roles/iam.securityAdmin — read/set IAM policies
roles/iam.serviceAccountAdmin — create/manage service accounts
roles/iam.serviceAccountKeyAdmin — create/manage service account keys
roles/iam.roleViewer — read role definitions
roles/resourcemanager.organizationViewer — enumerate the org and projects

Download the service account key

Under the service account, go to Keys → Add Key → JSON. Download and save the key file.

Step 2 — Register GCP in Britive

After the service account is created, connect GCP to your Britive tenant.

Add the application

In the Britive console, go to Applications → Add Application → GCP. Upload the service account JSON key and enter your GCP organization ID.

Wait for the initial scan

Britive scans your organization to import projects and available IAM roles. This takes 1–3 minutes. The application status changes to Connected when the scan completes.

For detailed onboarding reference, see the Britive documentation and the britive/onboarding repository.

Create Your First Access Profile

An access profile defines which GCP IAM roles a group of users can check out, for how long, and under what conditions.

Using the Britive Console

Open the GCP application

Navigate to Applications → select your GCP application → Profiles → Add Profile.

Configure the profile

Field	Value
Name	A descriptive name (e.g., `DevOps-StorageAdmin`)
Environment	Select the GCP project
Expiration	Max session duration (e.g., `1h0m0s`)

Add permissions

Under Permissions, add the GCP IAM roles to grant on checkout.

Add a policy

Under Policies, click Add Policy. Assign members (users or tags) and set any approval or time-of-access conditions.

Save and activate

Click Save. The profile appears in My Access for assigned members.

Using Terraform

data "britive_application" "gcp" {
  name = "GCP"
}

resource "britive_profile" "devops" {
  app_container_id    = data.britive_application.gcp.id
  name                = "DevOps-StorageAdmin"
  expiration_duration = "1h0m0s"

  associations {
    type  = "Environment"
    value = "my-project-id"
  }
}

resource "britive_profile_permission" "storage_admin" {
  profile_id      = britive_profile.devops.id
  permission_name = "roles/storage.admin"
  permission_type = "role"
}

resource "britive_profile_additional_settings" "devops" {
  profile_id          = britive_profile.devops.id
  console_access      = true
  programmatic_access = true
}

resource "britive_profile_policy" "devops" {
  profile_id  = britive_profile.devops.id
  policy_name = "DevOps-Access-Policy"

  members = jsonencode({
    tags  = [{ name = "devops-team" }]
    users = []
  })

  access_type = "Allow"
  consumer    = "papservice"
  is_active   = true
  is_draft    = false
}

Verify

Check out the profile

Navigate to My Access → find your profile → click Check Out.

Confirm the IAM binding in GCP

gcloud projects get-iam-policy your-project-id \
  --flatten="bindings[].members" \
  --filter="bindings.members:user:your-email@yourcompany.com"

You should see a binding for roles/storage.admin (or whichever role you added to the profile).

Check in

Return to My Access → click Check In. Re-run the gcloud command above — the binding should no longer appear.

Troubleshoot

Symptom	Likely cause	Fix
Application shows “Disconnected”	Service account key expired or revoked	Rotate the key and update it in the Britive application settings
Projects not visible after scan	Service account lacks Organization Viewer role	Grant `roles/resourcemanager.organizationViewer` at the organization level
Checkout fails with permission error	Service account lacks Security Admin role	Grant `roles/iam.securityAdmin` at the organization or project level
Domain Wide Delegation error / `deploy.sh` keeps retrying	DWD not yet configured or still propagating	Complete the Add new step in the Google Workspace Admin console with the client ID and scopes the script printed; it retries every 10 seconds until it succeeds
Custom role not found after creation	IAM propagation delay	The Python script adds a built-in delay; for manual setup, wait 60 seconds before binding

Next Steps

Britive documentation — complete GCP onboarding reference
britive/onboarding on GitHub — Terraform templates and Python scripts

Last updated on July 8, 2026