Group Mappings

Group mappings connect identity provider (IdP) groups to Shoehorn teams. When a user logs in and belongs to an IdP group, they are automatically added to the mapped Shoehorn team.

How It Works

1. Configure your IdP to send group claims in the JWT token
2. Map IdP groups to Shoehorn teams
3. When users authenticate, their group memberships are synced

Creating a Mapping

Via the UI

1. Navigate to Organization > Teams
2. Select a team
3. Go to the Group Mappings tab
4. Click Add Mapping
5. Enter the IdP group name
6. Click Save

Via the API

curl -X POST https://shoehorn.example.com/api/v1/admin/teams/<team-id>/group-mappings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "engineering-platform",
    "idp_provider": "zitadel"
  }'

Viewing Mappings

curl https://shoehorn.example.com/api/v1/admin/teams/<team-id>/group-mappings \
  -H "Authorization: Bearer <token>"

Removing a Mapping

curl -X DELETE https://shoehorn.example.com/api/v1/admin/teams/<team-id>/group-mappings/<group-id> \
  -H "Authorization: Bearer <token>"

Supported Identity Providers

Provider	Group Claim	Notes
Zitadel	groups	Groups managed in Zitadel organizations
Okta	groups	Okta group names sent via OIDC
Microsoft Entra ID	groups	Azure AD security groups
Keycloak	groups	Keycloak realm groups

Mapping Rules

• Each IdP group maps to exactly one Shoehorn team
• A team can have multiple group mappings
• Mappings are one-way: IdP group -> Shoehorn team
• Changes to IdP group membership are reflected on next login
• All mapping changes are recorded in the team audit log

Tenant Configuration

The tenant ID strategy determines how Shoehorn extracts the tenant from JWT claims. This is configured via environment variables:

Strategy	Env Var	Description
provider_claim	TENANT_ID_CLAIM_KEY=azp	Use a specific JWT claim
urn_claim	TENANT_ID_CLAIM_KEY=urn:zitadel:iam:org:id	Extract from URN claim
group_prefix	TENANT_GROUP_PREFIX=tenant:	Extract from group prefix
env_var	DEFAULT_TENANT_ID=default	Use environment variable