Identity & sign-in
Everything you do with kubehz (the dashboard, the API, and kubectl on a hosted cluster) sits behind one sign-in. This page explains how that login works and how it reaches your clusters.
One identity provider
kubehz runs its own single sign-on identity provider (built on ZITADEL). You sign in once at kubehz and that identity is used everywhere. There is no separate cluster password to manage.
You can sign in with:
- Email and password, protected by two-factor authentication;
- GitHub;
- Google;
- your own SSO (owner or admin, in the dashboard; we help if federation is not enabled for your org yet): federate an external OIDC provider (Okta, Entra, Google Workspace, …) so your team uses your existing corporate identity. See Sign-in & your own identity provider and Access & roles.
Your team is isolated
Each team gets its own identity organization. Your members, their roles, and any SSO you federate live inside your organization and nowhere else: one team can never see or affect another team’s people or access. This isolation is the foundation of how cluster access stays separated between customers.
How sign-in becomes cluster access
For a hosted cluster, you never manage a separate set of Kubernetes users. It works like this:
- You sign in to kubehz. Your tier and custom roles are attached to your token as group claims, tagged with your team’s organization.
- Your hosted cluster’s API server trusts kubehz as its OIDC identity provider.
- When you run
kubectlwith the OIDC kubeconfig, the API server reads those groups and maps them to Kubernetes RBAC, but only the bindings for your team’s organization match, so a token from one team can never gain access on another team’s cluster.
The result: add someone to your team with a role, and they can use kubectl immediately; remove them, and their access ends: no cluster-side user management, and no way for access to cross between teams.
Self-hosted clusters
Everything above describes a hosted cluster. For a self-hosted one the answer is shorter, and it is the important one: your cluster’s API server does not trust kubehz.
- kubehz is not an identity provider for your cluster. Your own kubeconfig, your own RBAC and your own users are untouched, and signing in to kubehz grants nobody any access inside your cluster.
- What a kubehz sign-in controls is the dashboard and the API: who in your team can see the clusters you registered, and who can change your team’s settings.
- The platform never connects into a self-hosted cluster at all; the in-cluster agent is outbound-only. See Registration.
You do not need a kubehz account to run a cluster. lo works without one.
Step-up for sensitive actions
Actions that grant or widen access (inviting a member, enabling the long-lived admin kubeconfig) ask for a fresh two-factor sign-in at the moment you do them, even if you are already logged in. This keeps a stolen or forgotten session from being enough to hand out access.
Next steps
- Access & roles: tiers, custom roles and SSO.
- Connecting with kubectl: the OIDC kubeconfig in practice.
- How it works: the hosting × access model and the trust boundary.
Doc status
| Aspect | Detail |
|---|---|
| Last reviewed | 14 July 2026 |