google-group-sync

README

Google Group Sync

Google Workspace group membership resolver via HTTP API. Fetches group memberships using the Google Admin SDK Directory API. Provides a RESTful API for querying groups by user, by group email, or listing all groups with members.

What it does

Exposes HTTP endpoints that resolve Google Workspace group memberships. Designed to be called by other services (e.g., zitadel-rbac-mapper) that need group information for access control decisions.

This service has no knowledge of Zitadel — it's a pure Google Workspace utility.

API

GET /users/{email}/groups — Get groups for a user

{"email": "user@example.com", "groups": ["admins@example.com", "developers@example.com"]}

GET /groups — List all groups with members

[
  {"email": "admins@example.com", "members": ["user1@example.com", "user2@example.com"]},
  {"email": "developers@example.com", "members": ["user1@example.com"]}
]

GET /groups/{email} — Get a single group's members

GET /health — Health check

Architecture

[Any caller] → GET /users/{email}/groups → [google-group-sync] → [Google Admin SDK] → [Google Workspace]
                                                    │
                                                    └─ domain-wide delegation (service account + impersonation)

Cache Interface

The resolver uses a Cache interface (pkg/cache/Cache) for group membership caching:

type Cache interface {
    Get(key string) ([]string, bool)
    Set(key string, groups []string)
}

Current implementation: MemoryCache — in-memory LRU with TTL (hashicorp/golang-lru). Suitable for single-process deployments.

Future implementation (not yet built): DynamoDBCache — shared cache for Lambda-at-scale deployments where multiple concurrent Lambda instances benefit from a warm shared cache. Uses a DynamoDB table with TTL attribute for automatic expiration.

Cache selection happens in the platform main; default is MemoryCache.

Deployment Modes

google-group-sync ships three binaries for three deployment scenarios:

Mode	Binary	Entry point	Use case
Standalone	google-group-sync	cmd/google-group-sync/	K8s Deployment, local dev
Lambda	bootstrap	cmd/google-group-sync-lambda/	Standalone AWS Lambda with LWA layer
Extension	google-group-sync	cmd/google-group-sync-extension/	Lambda Extension sidecar for other Lambdas

All three modes wire through app.RunWithOptions — no divergent assembly. The difference is lifecycle management, configuration prefix, and secret loading.

Helm Chart (K8s)

helm install google-group-sync oci://ghcr.io/truvity/charts/google-group-sync \
  --set env.GOOGLE_ADMIN_EMAIL=admin@example.com \
  --set secrets.saKeySecretName=google-sa-key

The chart creates a Deployment (replicaCount: 2 default), Service (ClusterIP), ServiceAccount, and PodDisruptionBudget (enabled when replicas ≥ 2). It's on the login hot path as a separate failure domain.

Optional templates (default off, values-gated):

• CiliumNetworkPolicy — ingress only from rbac-mapper Deployment + CronJob pods
• RBAC — ServiceAccount + Role/RoleBinding
• HTTPRoute — Envoy Gateway (internal-only, rarely needed)

Chart Values

Key	Default	Description
replicaCount	2	Deployment replicas
env.GOOGLE_ADMIN_EMAIL	—	Admin email for domain-wide delegation
env.PORT	8080	HTTP server port
env.HEALTH_PORT	7070	Health probe port
env.CACHE_TTL	5m	Group membership cache TTL
env.CACHE_MAX_SIZE	10000	Max cache entries (LRU)
secrets.saKeySecretName	—	K8s Secret with SA key JSON
podDisruptionBudget.enabled	true	PDB (auto-disabled when replicas < 2)
ciliumNetworkPolicy.enabled	false	CiliumNetworkPolicy
rbac.enabled	false	Role + RoleBinding
httpRoute.enabled	false	HTTPRoute (Envoy Gateway)

Configuration

Env var	Required	Default	Description
GOOGLE_ADMIN_EMAIL	Yes	—	Admin email for domain-wide delegation
GOOGLE_SA_KEY_JSON	Mutual excl.	—	Raw SA key JSON
GOOGLE_SA_KEY_FILE	Mutual excl.	—	Path to SA key file
SA_KEY_SECRET_NAME	No	—	AWS Secrets Manager secret name (Lambda only)
PORT	No	8080	HTTP server port
HEALTH_PORT	No	7070	Health probe port
CACHE_TTL	No	5m	Cache TTL (Go duration)
CACHE_MAX_SIZE	No	10000	Max cache entries
LOG_LEVEL	No	info	Log level
LOG_FORMAT	No	json	Log format

Extension mode uses GGS_ prefix (e.g., GGS_GOOGLE_ADMIN_EMAIL).

Development

devbox shell          # activate dev environment
just build            # build binary
just test             # run unit tests
just lint             # run linter
just check            # build + test + lint + vuln

Related

• truvity/zitadel-rbac-mapper — consumes this service for group-based RBAC
• truvity/zitadel-operator — K8s operator for Zitadel resources

License

MIT