Team Mapping

A team mapper puts people into Mission Control teams automatically when they sign in, based on their groups or roles in your login provider. It's a CEL expression that returns team names. You then bind Roles to those teams with RoleBindings. Your login provider decides who belongs to which team, and Mission Control decides what each team may do.

A team mapper never grants a Role.

Login	Setting	Input
Kratos, including single sign-on	The identityRoleMapper Helm values, or the --identity-role-mapper flag. The name predates teams: it now returns teams	identity, the person's Kratos identity: traits and metadata
Clerk (Mission Control SaaS)	--clerk-team-mapper flag	claims, the claims of the verified Clerk session token
External identity provider	spec.identity.teams.mapper	claims, the claims of the verified token

The flags take the expression inline, or a file path prefixed with file://. On a Helm install, set the Helm values instead of passing a flag.

Output

The expression returns a list of team names:

clerk-team-mapper
claims.org_role == "org:admin" ? ["clerk-admins"] : ["clerk-members"]

Kratos and Clerk mappers may also return {"teams": [...]}. An external identity provider's mapper must return a list.

An object result with any field other than teams, such as the role field older Kratos scripts returned, is logged as an error and changes nothing. Map those people into a team and bind the Role to the team instead:

identity-role-mapper
{
  "teams": "admins" in identity.traits.groups ? ["admins"] : ["viewers"]
}

Behavior

• When it runs. On a person's first request after they sign in, and again whenever the identity or claims it reads change. An external identity provider's mapper runs on every request.
• Kept in sync. The person's mapped teams become exactly what the mapper returns. They join new teams and leave mapped teams the mapper no longer returns. Teams an admin added them to directly are never touched.
• Existing teams only. A team that doesn't exist is skipped and logged. Create the team from Settings → Teams, and bind a Role to it, before a mapper returns it.
• Without a mapper, signing in to Kratos adds the person to no team.
• Invites. When you invite someone from Settings → Users, you choose their teams. They join those teams when they accept the invite.

warning

A mapper that reads attributes people can change themselves, such as Kratos traits the settings flow lets them edit, lets them choose their own teams. Map from attributes only admins or your identity provider can set, such as Kratos metadata_public or the Clerk organization role. The examples on this page read identity.traits.groups, which is only safe when your SSO claims mapper sets it on sign-in and people can't edit it in their Kratos profile settings.

Clerk default

When --clerk-team-mapper isn't set, Clerk uses this mapper. It puts organization admins in admins, guests in no team, and everyone else in viewers:

default-clerk-team-mapper
{
  "teams":
    (has(claims.role) && claims.role == "admin") ||
    (has(claims.org_role) && claims.org_role == "org:admin") ? ["admins"] :
    (has(claims.org_role) && claims.org_role == "org:guest") ? [] :
    ["viewers"]
}

admins is the shipped team bound to admin. viewers grants nothing until you create it and bind a Role to it, for example mission-control-builtin/viewer.