Skip to main content
Version: main 🚧

What are Users and Teams

Users and teams are the core identities in vCluster Platform. A user represents an individual or service identity that can authenticate to the platform. A team represents a group of users that should receive the same access, ownership, and platform-level configuration.

They are used throughout the platform, not just during login. Users and teams can receive management roles, become project members, own resources, and consume quota. They also appear as Kubernetes subjects in reconciled role-based access control (RBAC) objects that Platform automatically creates and keeps up to date.

Users​

A user is the platform record for one authenticated identity that can be human or automated. Platform tracks the identifiers needed to recognize that identity, including a stable platform name, an SSO-matching subject, and the groups associated with it. Beyond identity, a user record can also grant management roles directly. It can also be disabled to block login without deleting the user or its resources.

Platform also computes each user's current effective team membership. Effective means the fully resolved result right now, not the raw configuration. This lets admins see which teams a user actually belongs to at this moment, not just which teams were configured to include them.

See the User resource reference for the full list of fields.

Create users →

Teams​

A team is the platform record for a shared identity boundary. Teams do not log in on their own. Instead, they become part of an authenticated user's effective identity when that user is a member.

Membership comes from two places. Some users are explicitly assigned to the team, and others belong because their groups match a token or SSO group name configured on the team. This lets you combine manual team assignment with identity-provider-driven membership. For example, you might add a break-glass admin user (an emergency-access account for when normal login isn't available) directly to a team. The rest of the team's membership can then come from an SSO group, such as OIDC, SAML, GitHub, GitLab, Google, Microsoft, LDAP, or Dex.

Like users, teams can be granted management roles directly. Those apply to whichever users are currently members of the team.

See the Team resource reference for the full list of fields.

Create teams →

User authentication resolves team membershipFor a user login or user access key, Platform adds team groups from direct assignment or matching SSO groups.Usermetadata.name: alicespec.groups: devsSSO tokensubject: alice@example.comgroups: devsTeammetadata.name: app-teamDirect membersspec.users: aliceGroup membersspec.groups: devsEffective identityuser: alice@example.comgroup: loft:user:alicegroup: loft:team:app-teamsyncs groupsadds team groupPlatform records the resolved team list on user status.
For a user login or user access key, Platform resolves team membership from explicit assignment and matching SSO groups.

SSO and account provisioning​

With SSO, Platform can create or update users from identity provider claims. The important design choice is usually where to manage group membership:

  • Manage membership in the identity provider when your organization already has authoritative groups.
  • Manage membership in Platform when teams are platform-specific or short-lived.
  • Use both when you need exceptions, such as manually adding a service user to a team whose human members come from SSO.

SSO configuration can also do more than manage membership. It can apply cluster account templates (predefined access configurations for connected clusters) to users when they first sign in. It can also keep those templates synchronized when tokens refresh. This is useful when users or teams should automatically receive access to particular connected clusters after authentication.

SSO configuration →

How effective identity works​

After a user authenticates, Platform builds a Kubernetes-compatible identity for that request. The resulting identity includes:

  • the user's subject as the Kubernetes user name;
  • the user's direct groups;
  • system:authenticated and loft:authenticated;
  • platform groups such as loft:user:<user-name>;
  • one loft:team:<team-name> group for every effective team membership;
  • exactly one scope group, loft:platform or loft:tenant:<tenant-name>. See Scope groups.

This is why teams are useful beyond the UI. Platform permissions, project membership, admission policies, and cluster access can all refer to users and teams as Kubernetes-style subjects and groups.

The subject is the name that role bindings and other Kubernetes-style checks see for the user. If the subject is empty or starts with a reserved prefix, Platform uses loft:user:<user-name> instead. Platform reserves the loft: and system: prefixes for its own identities, so a user's subject can't start with either one. See Reserved subject prefixes.

Scope groups​

Every identity built from a user or from a team's access key carries one scope group. The scope group names the scope the identity belongs to.

IdentityScope group
A user or team access key that belongs to no tenant, including a platform adminloft:platform
A user or team access key that belongs to a tenantloft:tenant:<tenant-name>

loft:authenticated stays on every identity, and the scope group sits next to it. This follows the Kubernetes pattern where a service account carries system:serviceaccounts:<namespace> next to system:authenticated.

Platform derives the scope group from the identity's tenant.vcluster.com/owner label each time it builds the identity. A connected cluster's agent derives it the same way for direct-endpoint tokens. The group is never stored, so it doesn't appear on the user or team object. To see it, read the groups list of the Self resource while connected as that identity.

kubectl create -o jsonpath='{range .status.groups[*]}{@}{"\n"}{end}' -f - <<EOF
apiVersion: management.loft.sh/v1
kind: Self
EOF

The output lists one group per line, including exactly one of loft:platform or loft:tenant:<tenant-name>. See Check which tenant you belong to for how to connect.

A project member named * binds the scope group of the project's own scope. That's what keeps a wildcard member from reaching across the tenant boundary in either direction.

Reserved group names​

Only the ownership label can give an identity a scope group, so Platform reserves these group names:

  • loft:platform, and every group that starts with loft:platform:
  • the exact shape loft:tenant:<name>, with no further colon

loft:tenant:<tenant-name>:<group> isn't reserved. That shape is free for a tenant's own identity provider groups.

A reserved group never takes effect from anywhere else:

  • Adding one to a user's or team's groups through the API returns 403 with group "<group-name>" is derived from the identity's scope and cannot be set.
  • SSO sync drops one that arrives from an identity provider.
  • A reserved group stored on an access key, or by an earlier Platform version, is ignored.

When Platform acts as an OIDC provider, the groups claim it issues leaves out every group that starts with loft: or system:, scope groups included. An application that signs users in through Platform can't use scope groups to tell tenants apart.

Authentication and authorization →

Permissions and roles​

Platform uses Kubernetes RBAC concepts to authorize users and teams. A management role defines allowed actions, and Platform applies that role to one or more users or teams through reconciled role bindings.

Grant roles to teams when many people should share the same access. Grant roles directly to users only for exceptions, such as platform administrators, automation users, or temporary troubleshooting access. Direct user roles and team-inherited roles are additive, so a user can receive permissions from several places at once.

Users and permissions overview →

Tenant membership​

A tenant user belongs to exactly one tenant and stays there. That binding scopes everything the user can see. It can't be changed after the user is created.

Platform records the binding as the tenant.vcluster.com/owner label on the user. That label alone determines a signed-in user's tenant. The hostname a request arrives on doesn't change it, and neither do the user's teams. A team access key takes its tenant from the team's own label.

Because a label holds one value, there's no list of memberships and nothing to switch between. A person who works in two tenants needs a separate user in each. Usernames, emails, and identity subjects are unique across the platform, so each user needs its own, including its own sign-in identity.

Team membership doesn't cross that line either, because a team carries permissions. A team can only add users from its own tenant, and a platform team can only add platform users. Platform refuses a write that adds a tenant user to a platform team, so a tenant user can't pick up operator-level rights.

Users on a platform with no tenants are unaffected, and belong to the platform. So do platform admins. A platform admin belongs to no tenant, and the tenant boundary doesn't narrow their session.

Understand tenants →

Check which tenant you belong to​

The Self resource reports the caller's tenant in status.user.tenant, or in status.team.tenant for a team access key.

Sign in with the credentials you want to check, then connect your kubeconfig to the platform management API.

vcluster platform connect management

Run this query with either a user or team access key.

kubectl create -o jsonpath='{.status.user.tenant}{.status.team.tenant}{"\n"}' -f - <<EOF
apiVersion: management.loft.sh/v1
kind: Self
EOF

The output is the tenant name. A blank line means the identity belongs to the platform rather than a tenant.

Switch to a tenant by impersonation​

Platform admins see a Switch to Tenant... menu at the top of the sidebar once a tenant exists. Select a tenant to open the Switch to Tenant dialog. Select one of its users and click .

This impersonates the selected user rather than changing the admin's tenant membership. The sidebar badge changes from Admin to Tenant until impersonation ends.

Tenant users never see this menu. They have one tenant and nothing to switch to.

Impersonate a user →

Roles inside a tenant​

A tenant admin grants roles the same way any admin does, through the users, teams, and projects in their tenant.

  • Management roles go on a user or a team. Inside a tenant, only a cluster role template with spec.management set to true can be bound. Examples include loft-users-admin, loft-teams-admin, and loft-impersonator.
  • Project roles go on a project member. The role template needs the loft.sh/project-role label set to "true", as on any platform.
  • Tenant admin rights come from the <tenant>--admins team. To make another tenant user a tenant admin, add them to it.

The tenant admin role is loft-management-admin, which carries full management rights. The tenant boundary is what confines it, not a narrower role.

Some roles can't be bound inside a tenant, whoever is asking. A role that isn't a management role, such as loft-cluster-admin, grants rights outside the tenant boundary, so Platform refuses it. The same rule applies when a platform admin edits a tenant's user or team. An operator can't grant a tenant user a role the tenant couldn't bind. The check applies only to roles a write adds, so a role already on the object stays.

Tenants can't write roles of their own. Cluster role templates are shared with every tenant for binding, and authoring one is reserved for platform admins. Cluster accesses are too, so direct access to a control plane cluster comes only from a platform admin. See Cluster access.

Project membership​

Projects are where users and teams usually become operational. A project's member list can include specific users, specific teams, or a wildcard member. Each member receives a project role that defines what they can do inside that project.

A wildcard member, that is a user or team named *, appears in the UI as Everybody for a user or All teams for a team. It covers every identity in the project's own scope, not every identity on the platform. On a tenant's project, that's the tenant's users and team access keys. On a project no tenant owns, that's the platform's users and team access keys. A * team member covers the same identities as a * user member, users who belong to no team included. Platform binds the project's scope group, so a user or team created later is covered from its first request, and a deleted one loses access with its credentials.

When a team is a project member, all current team members receive the team's project access. Platform's project members API resolves both the direct team entry and the users who belong to that team. This lets project views show the effective member set.

Project ownership is related but separate. A project can have spec.owner.user or spec.owner.team, and the owner is included in the resolved project members list. Owners and members are often the same organizational unit, but they answer different questions. Ownership says who the project belongs to. Membership says who can access it and with which role.

Project members and owners answer different questionsMembers define who can access the project. The owner identifies who the project belongs to.Project membersMany users and teamsUser alice: adminTeam devs: editTeam qa: viewProjectteam-alphaPolicy boundaryProject ownerOne user or teamTeam devsCommon patternOwner and member can be the same team,but they are separate fields.can accessbelongs to
Project membership grants access with roles; project ownership identifies the user or team the project belongs to.

Manage project members →

What are Projects →

Resource ownership​

Many platform resources can be owned by either a user or a team. Platform records that ownership through owner fields on the resource and through ownership labels applied to resources such as namespaces, space instances, cluster instances, and access keys.

Ownership affects how resources are displayed, who can manage them, how project quota is counted, and how sharing workflows behave. Use team ownership for shared environments and long-lived resources that should survive changes in individual staffing. Use user ownership for personal development environments, individual access keys, or short-lived work that should clearly belong to one person.

SSH keys →

Platform labels and annotations →

Quotas​

Project quotas can apply to the whole project or to each user or team inside the project. A project-wide quota caps the total resources that the project can consume across all members. A per-user/team quota caps the resources that a single user or team can consume.

Ownership determines which quota a resource's usage counts against. A team-owned resource counts against that team's quota, and a user-owned resource counts against that user's quota, even when the user also belongs to a team. Team and individual usage are tracked separately, so a team-owned resource never counts against a member's personal quota, and a member's personally owned resource never counts against the team's quota.

Configure project quotas →

Automation and service accounts​

As the Users section noted, a user or team doesn't need a human behind it. For GitOps, CI/CD, or external automation, create a dedicated user and issue an access key for that user. The access key authenticates as that user, and any access key scope can only narrow what the user is already allowed to do.

Access keys can also authenticate as a team. A team access key acts as the team identity, so it receives the team's roles and project memberships rather than a particular user's direct roles. Use this when automation should belong to a shared operational identity instead of an individual user.

Access keys →

GitOps end-to-end guide →

Access troubleshooting​

When troubleshooting access, check the actor first. Is the request using a normal user login, a user access key, or a team access key? Then review the user's teams, direct roles, team roles, project memberships, resource ownership, and any access key scope that might be narrowing the request.

Access starts with an actor, then roles and scopes applyAccess keys authenticate as a user or team. Optional key scope can narrow access, but does not add permissions.User actorlogin or user keyaliceTeam actorteam access keyapp-teamAuthenticated actorPlatform resolves the requestto a user or team identityAdditive grantsDirect user rolesTeam rolesProject membershipAccess key scope narrowsResultCan manageCan accessCan ownevaluateallowsnarrows
When changing someone's access, check which actor is authenticated, then review roles, project membership, ownership, and any access key scope.

Access modeling​

For most installations, start with teams as the primary unit of access. Create teams that match how work is owned, such as platform administrators, application teams, customer accounts, environments, or automation roles. Add those teams to projects, grant project roles to teams, and use direct user permissions only where the exception is intentional.

Use user-owned resources for personal workspaces and use team-owned resources for shared services. This keeps access, ownership, and quota behavior predictable as people join, leave, or move between teams.