Create users
Proper user configuration is important for effective access control and authentication on the platform. Each user account represents an individual who interacts with the platform.
Create a user account​
To create a new user in the platform:
Go to Platform > Users & Roles.
Click the button.
In the configuration sheet that opens, give your new user a name by replacing the 'my-user' placeholder name, or by updating the manifest YAML 'metadata.name' field.
[Optional] Update the user with any additional desired configuration options.
The Details tab contains user settings. The username is used to login and optionally you can also set the default password in this tab. The email address needs to be unique across users and can also be used to login instead of using the username. The subject is used to map a user to an SSO provider. It can't start with
loft:orsystem:. See Reserved subject prefixes.The Team Memberships tab contains settings that govern which teams the user is part of. The Teams selector allows you to make user part of the selected teams.
Advanced Options allow for configuring cluster roles that apply directly to this user.
Access allows you to define which users and teams have access to modify the team you are currently creating.
Click the button.
User configuration options​
When creating a user, you can configure several important settings organized in tabs:
User details​
The Details tab contains essential user identification information:
- Username: The primary identifier used for login authentication. Choose something memorable but specific to the user.
- Password: Optionally set an initial password. For enhanced security, consider leaving this blank and using the password reset workflow instead.
- Subject (SSO User ID in the UI): A unique identifier used to map this user to an external SSO provider. This field enables identity federation with authentication systems. The subject can't start with
loft:orsystem:.
Team memberships​
The Team Memberships tab manages which teams this user belongs to:
- Use the Teams selector to add the user to one or more teams
- Team membership automatically grants the user all permissions associated with those teams
- Changes to team membership take effect immediately across all resources
Advanced options​
The Advanced Options section controls low-level permissions and access:
- Cluster Roles: Define specific Kubernetes cluster roles that apply directly to this user
The cluster roles defined here are combined with any roles inherited from team memberships, giving you fine-grained permission control.
Access controls​
The Access section determines who can manage this user account:
- Specify which users and teams have permission to modify this user's settings
- This meta-permission layer is crucial for delegated administration in larger organizations
Reserved subject prefixes​
Platform reserves the loft: and system: prefixes for its own identities, so a user's subject can't start with either one. The rule applies to every user, not only users in a tenant.
Platform refuses the following requests with a 422 error:
- Creating a user with a reserved subject, through the UI or the API.
- Changing an existing user's subject to a reserved one. An update that keeps the user's current subject is allowed.
The error includes:
subject must not start with "loft:" or "system:", which are reserved for platform identities
To fix it, choose a subject without a reserved prefix. In the UI, the subject is the SSO User ID field on the Details tab.
SSO applies the same check when it creates a user. If the identity provider's user ID starts with a reserved prefix, Platform doesn't create the user and the SSO login fails.
Users with a stored reserved subject​
A user who already has a reserved subject stored, for example from before an upgrade to Platform v5.0, can still log in. Platform ignores the stored subject and uses loft:user:<user-name> as the user's name in the session instead. Here <user-name> is the user's metadata.name, not its username.
Role bindings that name the stored subject no longer apply to that user. To keep the access, do one of the following:
- Bind
loft:user:<user-name>instead of the stored subject. Every user also has a group with that name, so the binding works whether it names a user or a group. - Give the user a subject without a reserved prefix, and bind that subject.
Don't change the subject of a user who signs in through SSO with an identity provider user ID that starts with loft: or system:. SSO matches users by subject, so that user could no longer sign in. Bind loft:user:<user-name> for that user instead.
To list the users with a reserved subject, connect to the platform management API and run:
kubectl get users.management.loft.sh -o json \
| jq -r '.items[] | select((.spec.subject // "") | test("^(loft|system):")) | .metadata.name'
User management best practices​
For effective management of users in vCluster:
- Use descriptive usernames: Choose usernames that clearly identify the individual user
- Leverage SSO where possible: For organizations with existing identity providers, configure SSO integration rather than managing separate credentials
- Prefer team-based permissions: Assign permissions to teams rather than individual users when possible
- Regularly audit user accounts: Periodically review user accounts to ensure they remain necessary and properly configured
Integration​
User accounts in the platform map to Kubernetes subjects in the underlying RBAC system:
- Each user is represented as a subject in Kubernetes role bindings
- Permissions granted to the user apply across all clusters managed by the platform
- Authentication tokens and credentials are securely managed by the platform