Skip to main content
Version: 2.0

Security Guide

This guide explains KubeOpera's security model — how people and services prove who they are, how every request is authorized, and how tenants are kept apart — and gives you a checklist for hardening your own installation.

Authentication​

Users​

auth-service is KubeOpera's identity provider. Users can sign in with:

  • Email and password, with optional time-based one-time passwords (TOTP) for multi-factor authentication;
  • Google or GitHub;
  • Your organization's single sign-on — any OpenID Connect provider (Okta, Microsoft Entra ID, Keycloak, Auth0…) or SAML 2.0.

OIDC sign-ins are verified properly: auth-service validates the provider's ID token signature against its published keys, and checks the issuer, audience and expiry.

A successful sign-in returns a short-lived access token (a signed JWT) and a refresh token. The token carries the user's ID, user_type and tenant_id, and the dashboard refreshes it automatically.

Single sign-on for your organization​

Tenant administrators can connect their organization's identity provider under Settings → Single Sign-On:

  1. Choose OIDC or SAML 2.0.
  2. Enter your provider's details (issuer URL and client credentials, or SAML metadata).
  3. Map your provider's groups to KubeOpera roles.
  4. Optionally require SSO so members can't sign in with a password.

Access tokens​

For scripts and CI pipelines, users create personal access tokens in Settings → Access Tokens. Each token has scopes (for example read, deploy or actions) and an expiry, acts with the permissions of the user who created it, and can be revoked at any time.

Services​

Services authenticate to each other with the OAuth2 client-credentials flow: each service has its own identity in auth-service, obtains short-lived tokens with only the scopes it needs, and presents them on every call. When a service acts on behalf of a user or tenant — for example, agent-runtime running an agent for a tenant — the token carries that tenant, so every downstream check applies.

Inside the cluster, traffic between services is encrypted with mutual TLS, using certificates issued by an internal cert-manager CA and rotated automatically.

Authorization​

Every KubeOpera API requires authentication, and every request is authorized — no endpoint is reachable anonymously except health checks and the sign-in flow itself.

Role-based access control​

Permissions are grouped into roles and assigned to users and groups:

Built-in roleScopeCan…
Super AdminPlatformEverything, across all tenants.
Platform OperatorPlatformOperate clusters and node pools and view all tenants, without changing platform settings.
Tenant AdminTenantManage the tenant's members, CloudSpaces and settings.
DeveloperTenantDeploy and manage apps, pipelines and CloudSpaces.
ViewerTenantRead-only access to the tenant's resources.

Create custom roles in Settings → Permissions by combining individual permissions — for example, a Responder role that can approve actions and manage incidents but not deploy.

Write actions — approving actions, rolling back, draining nodes, approving scaling decisions — require explicit permissions. AI agents and access tokens act as a user and can never exceed that user's permissions.

Tenant isolation​

Tenant data is isolated at every layer:

  • Storage — tenant-owned records carry a tenant_id, and every query filters on the tenant from the caller's verified token, never on a value supplied by the client.
  • Kubernetes — each tenant's workloads run in their own vCluster (see Multi-Tenancy).
  • AI — tools re-check that each requested resource belongs to the caller's tenant, and each tenant has its own App Advisor.

Protecting the platform​

The dashboard's API gateway​

The dashboard's server-side proxy only forwards requests to known service hostnames — an allowlist that prevents server-side request forgery — and never exposes backend URLs or credentials to the browser.

Rate limiting​

Sign-in, registration and password-reset attempts are rate-limited per account and per client, and every API enforces per-endpoint limits to protect against abuse and runaway clients.

Webhooks and integrations​

Incoming webhooks are verified by signature (see Webhooks), and integration credentials are scoped to a single pipeline or integration.

Audit log​

Every sign-in, permission change, configuration change and write action — including those taken by AI agents — is recorded in the audit log (Settings → Audit Log) with who did it, when and from where. Export it to your SIEM with the audit webhook.

Secrets​

Sensitive configuration is stored as Sealed Secrets in Git, and user-managed credentials are encrypted at rest by auth-service. See Configuration: where secrets live.

Hardening checklist​

  • Change the first administrator's password and enable MFA.
  • Connect your identity provider and require SSO for your organization.
  • Give people the least-privileged role that works; use custom roles for specialist duties.
  • Review which decisions run automatically before enabling automation in production.
  • Set expiries on access tokens and rotate CI tokens regularly.
  • Rotate sealed secrets (database, signing keys) on a schedule.
  • Route critical alerts to your on-call tool (see Monitoring).
  • Forward the audit log to your SIEM.
  • Keep KubeOpera up to date — upgrades are a commit away.

Next steps​