How to map Entra ID groups to ZITADEL roles on first login?
š¬Self-hostedš¬Roles & PermissionsāUnsolvedāQuestionšActions
Hi! We're self-hosting ZITADEL with federated login through Microsoft Entra ID. We need to map Entra ID group memberships to ZITADEL roles and have the mapped roles appear in the token on first login.
TL;DR: Actions v1 can read upstream Entra claims, but Actions v2
Current approach:
1. Actions v1 External Authentication / Post Authentication reads Entra group IDs and stores them as user metadata, e.g.
2. Actions v2
- reads the stored group IDs
- maps Entra groups to ZITADEL roles
- updates the user's ZITADEL grant via the Management API
- returns
This works, but
Questions:
1. Is there any supported way to merge into or override the built-in ZITADEL role claim from Actions v2?
2. Will Actions v2 get a trigger during external authentication where upstream IDP token claims are available?
3. Given v1 removal in v5, what is the recommended future-proof approach?
4. Is our v1 metadata ā v2
Any feedback would be appreciated.
TL;DR: Actions v1 can read upstream Entra claims, but Actions v2
preaccesstokenpreaccesstoken seems to only read ZITADEL user/user_grants/metadata. Our workaround is: v1 stores Entra group IDs in metadata, then v2 maps them and appends custom role claims. Is this the recommended/future-proof pattern given v1 removal in v5?Current approach:
1. Actions v1 External Authentication / Post Authentication reads Entra group IDs and stores them as user metadata, e.g.
entraid_groupsentraid_groups.2. Actions v2
function.preaccesstokenfunction.preaccesstoken calls our group-mapper service. The service:- reads the stored group IDs
- maps Entra groups to ZITADEL roles
- updates the user's ZITADEL grant via the Management API
- returns
append_claimsappend_claims with the mapped rolesThis works, but
append_claimsappend_claims appears unable to set urn:zitadel:iam:*urn:zitadel:iam:* claims or override existing claims, so we use a custom claim like org:project:{projectId}:rolesorg:project:{projectId}:roles. We also stopped requesting the built-in ZITADEL roles scope to avoid stale/duplicate role claims.Questions:
1. Is there any supported way to merge into or override the built-in ZITADEL role claim from Actions v2?
2. Will Actions v2 get a trigger during external authentication where upstream IDP token claims are available?
3. Given v1 removal in v5, what is the recommended future-proof approach?
4. Is our v1 metadata ā v2
preaccesstokenpreaccesstoken approach reasonable, or is there a better pattern?Any feedback would be appreciated.
