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.

Britive authenticates as that service account in one of two ways, which correspond to two application types in the Britive console:

	GCP WIF (recommended)	GCP (key)
How Britive signs in	Presents an OpenID Connect token from your tenant to a workload identity pool and impersonates the service account. No secret is stored anywhere	Uploads a long-lived service account key
Google Workspace	Not used	A Workspace admin user with domain-wide delegation
Blocked by `iam.disableServiceAccountKeyCreation`	No	Yes

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 stack in britive/onboarding creates a project for the Britive service account, enables the APIs, creates the organisation custom role Britive Integration Role and the service account, grants the role at organisation, folder or project scope, and — depending on integration_type — a workload identity pool and OIDC provider (wif) or a service account key (key). Optionally it creates the Britive application too.

Clone and configure variables

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

terraform/google-cloud/terraform.tfvars

organization_id    = "123456789012"
project_id         = "britive-integration"        # new project, or create_project = false for an existing one
britive_tenant_url = "https://your-tenant.britive-app.com"
integration_type   = "wif"                        # or "key"
access_scope       = "organization"               # or "folder" / "project" with scope_id

Key mode also needs ../google-workspace/terraform.tfvars (Workspace customer ID, domain, a super administrator to act as).

Run the deploy script

# optional: also create the Britive application
export BRITIVE_TENANT=https://your-tenant.britive-app.com
export BRITIVE_TOKEN=<API token>

./deploy.sh

deploy.sh signs you in to Google if Application Default Credentials are missing, applies this directory, and then:

key mode only: prints the service account client ID and the OAuth scopes, waits for you to add them under admin.google.com → Security → Access and data control → API controls → Manage Domain Wide Delegation → Add new, then applies ../google-workspace, retrying the plan for up to 10 minutes while delegation takes effect;
applies britive-app/ if BRITIVE_TENANT and BRITIVE_TOKEN are set, otherwise prints the values to enter in the console (terraform output britive_application_values).

Organisation policies can block this: iam.disableServiceAccountKeyCreation refuses the key in key mode, iam.allowedPolicyMemberDomains refuses the pool members in wif mode. The directory README lists the exceptions to grant.

Python Automation

setup_gcp.py creates a service account and the 19-permission projects only custom role, bound on one project — what the GCP Standalone application type needs. For an organisation-level or WIF application use the Terraform stack instead. The script is idempotent: an existing service account is kept, an existing role has its permissions refreshed.

git clone https://github.com/britive/onboarding.git
cd onboarding/python/google-cloud
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Authenticate with GCP as someone who can create service accounts and roles on the project:

gcloud auth application-default login

Run the setup script, then create the key to upload when creating the application:

python3 setup_gcp.py --project-id your-project-id
# options: --service-account-name britive-service --role-id BritiveIntegrationRole --credentials key.json

gcloud iam service-accounts keys create britive-key.json \
  --iam-account britive-service@your-project-id.iam.gserviceaccount.com

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 Britive documents (organization, projects only); 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 System Administration → Tenant Applications → Create Application and pick the type that matches how you set up Google Cloud:

Application type	What to enter
GCP WIF	Organization ID, project ID for creating service accounts, workload identity pool and provider IDs, the connected service account email and its project number — all Terraform outputs (`terraform output britive_application_values`)
GCP (key)	Organization ID, the service account JSON key, and the Workspace admin user (Custom user email) and customer ID from `../google-workspace`
GCP Standalone	The service account JSON key from `setup_gcp.py`; scope is one project

The display name may contain only letters, digits and spaces. If your Britive users and Google identities use different email domains, set Replace domain.

Save, test and scan

Click Save and Test, then Scan. Britive imports the folders and projects the scan discovers and their IAM roles; this takes 1–3 minutes. Profiles can only be associated with what the scan found.

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
Workspace plan keeps failing with `unauthorized_client` (key mode)	Delegation not saved, wrong client ID or scopes, or not yet in effect	Compare with what `deploy.sh` printed; changes can take several minutes. The script retries for up to 10 minutes
`Key creation is not allowed on this service account`	`iam.disableServiceAccountKeyCreation` is enforced	Use `wif`, or grant an exception on the project
Save and Test fails for a GCP WIF application	Issuer URL or pool/provider IDs differ from what Britive expects	Compare `britive_issuer_url` with the application’s Settings → Britive Issuer URL
`API ... has not been used in project ... or it is disabled` on the first apply	The APIs were just enabled	Apply again; the stack already waits 60 seconds

Next Steps

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

Last updated on October 8, 2026