Skip to main content

​
What this gives you

With IAM Federation enabled, Hoop stops sharing a single Google service-account key with every user. Instead, each user’s activity against GCP is attributed to their own principal — so a bq query Alice runs through Hoop shows up in Cloud Logging as Alice, not as a shared admin service account. This buys you:
  • Per-user attribution — every GCP operation is tied to the individual who ran it
  • No shared keys — users never hold a long-lived service-account key; Hoop mints short-lived tokens at session time
  • A clean audit trail — GCP’s delegation chain records both who ran each query and through whom (the Hoop admin service account)

​
How It Works

When a user runs hoop connect my-bq, the gateway:
1

Reads the federation policy

The connection’s federation policy defines the identity template, project id, and fallback rules that map the Hoop user to a GCP principal.
2

Mints a token as the user's principal

The gateway asks Google’s iamcredentials API to mint a short-lived OAuth access token as the user’s target principal, using the admin service account stored for your organization.
3

Hands the token to the agent

The agent uses that short-lived token for the session. Every subsequent operation is attributed to the user’s principal — not the shared admin account.
For this to work, two things must be true on the GCP side:
  • The admin service account must be allowed to impersonate each user’s target principal (the roles/iam.serviceAccountTokenCreator grant).
  • Each target principal must have whatever data-plane roles it needs (e.g. roles/bigquery.user for BigQuery).

​
The Audit Trail

Federation’s payoff is the delegation chain GCP records on every operation. A BigQuery job run through Hoop carries a serviceAccountDelegationInfo chain showing who ran the query (the user’s principal) and through whom (the Hoop admin service account): 
protoPayload.authenticationInfo.principalEmail: alice@my-proj.iam.gserviceaccount.com
protoPayload.authenticationInfo.serviceAccountDelegationInfo:
  - firstPartyPrincipal:
      principalEmail: hoop-admin@my-proj.iam.gserviceaccount.com
That chain is the audit story IAM Federation buys you: you can prove every query in a project went through Hoop, and flag any that bypassed it. Enabling, querying, and sinking these logs is covered in the configuration guide.
Ready to set it up? The IAM Federation for GCP configuration guide walks through the GCP IAM setup (admin service account, Token Creator grants, verification), wiring the policy onto a connection, and enabling the audit logs.

​
Next Steps

Configuration Guide

Grant Token Creator and wire federation onto a connection

CLI Reference

hoop admin federation set and test flag reference

Connect to BigQuery

Create the connection federation attaches to

Session Recording

Audit every federated session inside Hoop