Skip to main content
Version: main 🚧

Authentication and authorization

This guide explains the key security concepts in vCluster Platform and demonstrates how to set up a complete authentication system with role-based permissions.

Core security concepts​

The platform uses several objects to manage access and permissions:

ObjectDescription
UserA person with platform access. Users can have Management Roles assigned directly and can belong to Groups and Teams. API reference
SSO GroupA representation of a group from your configured SSO provider. These groups are imported during authentication and stored in User records.
TeamA collection of platform users. Users join teams either through explicit assignment or via SSO Group membership. Teams can have Management Roles. API reference
Management RoleDefines permissions granted to users or teams within specific scopes. API reference
ProjectAn organizational unit for resources such as virtual clusters. Projects help enforce access control and resource quotas.

Setting up authentication with Microsoft Entra ID​

This example shows how to implement a comprehensive security model using Microsoft Entra ID (formerly Azure AD).

Prerequisites​

  • Microsoft Entra ID tenant configured as your identity provider
  • vCluster Platform installed and running
  • Administrative access to vCluster Platform

Authentication setup​

  1. Configure Microsoft Entra ID as your SSO provider using either:

  2. Configure your Entra ID application to include group memberships in authentication tokens

  3. Configure vCluster Platform to accept specific groups for platform access

Define roles for different personas​

Create Management Roles aligned with your organization's needs. This example uses four distinct roles:

  1. Platform Operations - Full platform management permissions
  2. DevOps Engineers - Create and manage virtual clusters within projects
  3. Developers - Connect to and use virtual clusters
  4. Automation Service Account - Programmatic access for GitOps workflows

Team structure​

  1. Create Teams that correspond to your organizational structure:

    kubectl apply -f platform-ops-team.yaml
    kubectl apply -f app-team-devops.yaml
    kubectl apply -f app-team-developers.yaml
    kubectl apply -f gitops-automation-team.yaml

  2. Associate Teams with SSO Groups:

    apiVersion: management.loft.sh/v1
    kind: Team
    metadata:
      name: app-team-devops
    spec:
      displayName: "Application Team - DevOps"
      description: "DevOps engineers responsible for cluster provisioning"
      groups:
        - name: "app-team-devops@example.com"

  3. Assign appropriate Management Roles to each Team:

    apiVersion: management.loft.sh/v1
    kind: Team
    metadata:
      name: platform-ops-team
    spec:
      displayName: "Platform Operations"
      clusterRoles:
        - platform-admin

Project organization​

Create Projects for each application or team:

apiVersion: management.loft.sh/v1
kind: Project
metadata:
  name: app-team-project
spec:
  displayName: "Application Team Project"
  description: "Resources for the application team"
  allowedClusters:
    - name: "prod-cluster"
    - name: "dev-cluster"
  quotas:
    virtualClusters: 5

GitOps governance​

For organizations requiring additional governance:

  1. Manage Projects, Management Roles, and Teams using GitOps workflows
  2. Store configurations in a version-controlled repository
  3. Use your CI/CD system with the automation service account to apply changes

Management role example​

apiVersion: management.loft.sh/v1
kind: ClusterRoleTemplate
metadata:
  name: loft-management-project-admin-custom
  labels:
    loft.sh/project-role: 'true'
spec:
  displayName: Custom Project Admin
  description: >-
    Allows the user or team to manage the project. Gives full access to
    modifying the project and all objects inside it.
  management: true
  access:
    - verbs:
        - get
      users:
        - '*'
  clusterRoleTemplate:
    metadata:
      creationTimestamp: null
    rules:
      - verbs:
          - '*'
        apiGroups:
          - management.loft.sh
        resources:
          - virtualclusterinstances
          - virtualclusterinstances/log
          - virtualclusterinstances/kubeconfig
          - virtualclusterinstances/accesskey
          - virtualclusterinstances/restricted
          - projectsecrets
          - projects
          - projects/spec.*

Additional resources​