README
¶
Zitadel RBAC Mapper
Groups-to-grants mapping webhook for Zitadel Actions V2. Receives group claims from authenticated users and maps them to Zitadel project grants — enabling automated role assignment based on IdP group membership.
What it does
- Token enrichment (function manipulation): Zitadel calls this webhook during
preaccesstoken/preuserinfo. The mapper resolves the user's groups and returnsappend_claimswith role information. - Event-driven grant sync: Zitadel sends
user.human.addedorsession.addedevents. The mapper resolves groups and syncs UserGrants in Zitadel (add/update/remove).
Architecture
[User authenticates] → [Zitadel Actions V2] → [zitadel-rbac-mapper]
│
├─→ calls groups resolver (e.g., google-group-sync)
├─→ maps groups to roles via config rules
└─→ returns append_claims OR syncs UserGrants via Zitadel API
Configuration
# config.yaml
zitadel:
domain: auth.example.com
# token loaded from env or mounted secret
groupsResolver:
url: http://google-group-sync:8080/resolve # or Lambda function name
rules:
- group: platform-admins
grants:
- project: infra
roles: [admin]
- group: developers
grants:
- project: infra
roles: [viewer]
- project: monitoring
roles: [viewer]
Deployment
- Kubernetes: Helm chart (
oci://ghcr.io/truvity/charts/zitadel-rbac-mapper) - AWS Lambda: ZIP archive from GitHub Release (arm64, with Lambda Web Adapter)
- Pulumi example:
deploy/example/shows how to deploy to AWS Lambda from GitHub Release assets
Development
devbox shell # activates dev environment
just build # build binary
just test # run unit tests
just lint # run linter
just snapshot # build snapshot release locally
Related
- truvity/zitadel-operator — K8s operator that configures ActionTarget + ActionExecution pointing to this webhook
- truvity/google-group-sync — Google Workspace group membership resolver (used as groups source)
- truvity/zitadel-notify-relay — Zitadel notification delivery relay
License
MIT
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
zitadel-rbac-mapper
command
Package main is the entry point for zitadel-rbac-mapper.
|
Package main is the entry point for zitadel-rbac-mapper. |
|
zitadel-rbac-mapper-lambda
command
Package main is the Lambda entry point for zitadel-rbac-mapper.
|
Package main is the Lambda entry point for zitadel-rbac-mapper. |
|
pkg
|
|
|
app
Package app wires all components and runs the service.
|
Package app wires all components and runs the service. |
|
config
Package config provides environment-based configuration for zitadel-rbac-mapper.
|
Package config provides environment-based configuration for zitadel-rbac-mapper. |
|
grantsync
Package grantsync provides idempotent Zitadel UserGrant synchronization.
|
Package grantsync provides idempotent Zitadel UserGrant synchronization. |
|
mapper
Package mapper provides the rules engine that maps groups to desired Zitadel UserGrants.
|
Package mapper provides the rules engine that maps groups to desired Zitadel UserGrants. |
|
resolver
Package resolver provides an HTTP client for the groups resolver service (google-group-sync).
|
Package resolver provides an HTTP client for the groups resolver service (google-group-sync). |
|
server
Package server provides the HTTP server for zitadel-rbac-mapper.
|
Package server provides the HTTP server for zitadel-rbac-mapper. |
|
zitadeljwt
Package zitadeljwt provides payload verification for Zitadel Actions V2 webhooks.
|
Package zitadeljwt provides payload verification for Zitadel Actions V2 webhooks. |
Click to show internal directories.
Click to hide internal directories.