custom claim which holds the "teams" value

[schaefec]

We want to use a custom plugin to extract the teams value out of a custom claim field of our IDP issued access token. We're not able to update the configuration of the IDP to add the teams name into a claim called "teams" of the JWT token.
Is there a way to implement a plugin which hooks into a place BEFORE the teams claim gets extracted from the JWT token? E.g. in the resolve user hook, can I update the teams in the user_context to make this work?

[dkxmercury]

Short version: you probably don't need a plugin at all, and the hook you're aiming at wouldn't work anyway. The gateway never extracts a teams claim from an IdP-issued access token, so there is no "before" point to hook into.

Why the resolve-user hook approach won't work

Two things in the code rule it out:

• _resolve_plugin_authenticated_user_sync in mcpgateway/auth.py is what consumes whatever your http_auth_resolve_user plugin returns. It keys off email, looks the user up in the DB, and returns the DB record (falling back to a non-admin virtual user only when REQUIRE_USER_IN_DB=false). Teams are not read from the hook result at all, so there is nothing you can set there to influence team scoping.
• Even if a teams claim were present, it could only ever restrict, never grant. _narrow_by_jwt_teams (same file) intersects the claim with the DB-resolved memberships. Team membership always has to exist in the database first.

And for your specific case, build_external_identity in mcpgateway/utils/verify_credentials.py says it outright:

Team scoping uses SESSION semantics (DB authority) because an external access token carries no internal teams claim.

So the claim in your token is never consulted for team scoping. It goes through resolve_session_teams, which reads memberships from the DB.

What actually maps your custom claim to teams

The same function reuses the browser-SSO normalization and provisioning path, which is exactly where your custom claim can be picked up. Two provider fields do the work:

1. provider_metadata.groups_claim - this is the claim name the gateway reads groups from. It defaults to "groups" but it is configurable, so just point it at your custom claim. _normalize_user_info in mcpgateway/services/sso_service.py does groups_claim = metadata.get("groups_claim", "groups") and uses it for Keycloak, Entra, Okta, IBM Verify, ADFS and the generic OIDC branch. There are also env seeds for first bootstrap: SSO_GENERIC_GROUPS_CLAIM, SSO_KEYCLOAK_GROUPS_CLAIM, SSO_ENTRA_GROUPS_CLAIM.

2. team_mapping - a JSON dict on the provider mapping a group value to a team. _apply_team_mapping matches your claim values against its keys and grants membership, with values being either a team ID string or {"team_id": "...", "role": "..."}. Note that role only accepts "owner" or "member" - anything else is silently coerced to "member" by _resolve_team_mapping_target, so don't reach for RBAC role names like team_admin here, they'll quietly degrade rather than error.

Set both via the admin API:

PUT /auth/sso/admin/providers/{provider_id}
{
  "provider_metadata": { "groups_claim": "my_custom_claim" },
  "team_mapping": { "engineering": "team-uuid-1", "security": {"team_id": "team-uuid-2", "role": "owner"} }
}

After that the flow is: your token's my_custom_claim values → matched against team_mapping → memberships written to the DB with grant_source="sso" → resolve_session_teams picks them up. _apply_team_mapping also reconciles, so it revokes SSO-granted memberships when a group disappears from the claims.

Caveats worth knowing before you try it

• Top-level claims only. _extract_groups_and_roles does if groups_claim in user_data, a plain key lookup. There's no dotted/nested path support, so if your custom claim is nested inside another object this won't reach it. That's the one case where you'd genuinely need to do something custom.
• A top-level roles claim gets merged in too, on top of whatever groups_claim you configure. This applies to the Okta, Entra, IBM Verify, ADFS and generic OIDC branches, which go through _extract_groups_and_roles. Keycloak is the exception: it builds its group list itself from realm_access / resource_access (gated on map_realm_roles / map_client_roles) plus your groups_claim, and doesn't merge a top-level roles.
• On Keycloak, the claim must be a list. That branch only picks the claim up when the value isinstance(..., list), so a bare string claim is silently dropped. The other branches accept a string or a list. Worth checking which shape your IdP emits.
• Matching is case-insensitive - _apply_team_mapping lowercases both sides before comparing.
• Teams must already exist; team_mapping targets team IDs, it doesn't create them.
• Changing groups_claim via env won't take on an existing provider. The bootstrap does a smart merge where DB values win over env ones (so admin API changes survive restarts). Use the admin API, not just the env var, if the provider already exists.
• For the access-token path itself you'll need SSO_API_TOKEN_AUTH_ENABLED=true plus trusted_for_api_auth and a non-empty api_audience on the provider.

If your claim is nested rather than top-level, say so and that's a different (and more interesting) conversation.