Auth Service

Service: auth-service (authapi) · Port: 8081 · Database schema: auth

auth-service is KubeOpera's identity provider. It signs people in, issues the tokens every other service trusts, manages users, roles and permissions, connects organizations' single sign-on, and stores sensitive credentials — AI provider keys, registry credentials and cloud credentials — encrypted.

Capabilities

Area	What it provides
Sign-in	Email and password with verification, password reset and TOTP multi-factor authentication.
Social login	Google and GitHub.
Single sign-on	Any OpenID Connect provider (Okta, Microsoft Entra ID, Keycloak, Auth0…) and SAML 2.0, configured per tenant.
Tokens	Signed access and refresh tokens, with key rotation.
Access tokens	Scoped, expiring personal access tokens for scripts and CI.
Service identities	OAuth2 client credentials for service-to-service calls and integrations.
RBAC	Roles, permissions and groups, at platform and tenant level.
Credential storage	AI provider keys, registry credentials and cloud credentials, encrypted at rest.
Audit	A record of every sign-in, permission change and credential change.

Tokens

A successful sign-in returns:

• an access token — a short-lived signed JWT carrying the user's ID, user_type, tenant_id and roles;
• a refresh token — used by the dashboard to get new access tokens silently.

Services validate access tokens locally using the shared signing key, so no service has to call auth-service on every request. auth-service accepts a list of signing keys, so you can rotate keys without signing anyone out: add the new key, switch signing to it, and remove the old key once its tokens have expired.

Callers that don't hold the signing key (such as the dashboard) can validate a token with GET /api/v1/auth/introspect.

Service identities

Every KubeOpera service has its own client identity. Services obtain short-lived tokens with the OAuth2 client-credentials grant, scoped to only what they need, and pass the acting tenant along when they work on a tenant's behalf. You can create service accounts for your own integrations the same way (Settings → Service Accounts).

Single sign-on

Tenant administrators configure SSO under Settings → Single Sign-On.

• OIDC — enter the issuer URL, client ID and secret. auth-service discovers the provider's configuration and verifies every ID token's signature against its published keys, along with the issuer, audience and expiry.
• SAML 2.0 — upload your identity provider's metadata; auth-service provides its own metadata to register in return.

Map your provider's groups to KubeOpera roles, and optionally require SSO for the organization. Users are created on first sign-in (just-in-time provisioning) with the roles their groups map to.

Rate limiting

Sign-in, registration and password-reset attempts are rate-limited per identifier and per client with a sliding window, stored in cache-service so limits apply across every replica and survive restarts.

AI provider credentials

Every AI feature in KubeOpera — agents, recommendations, the Optimizer, the App Advisor and the AI Chat — gets its Claude API key from auth-service. The policy is the same everywhere:

1. If the tenant has configured their own key, use it (unmetered by KubeOpera).
2. Otherwise, if the platform host key is configured and shared, use it, metered against the tenant's quota.
3. Otherwise, report clearly that no key is available.

This supports both common setups: an enterprise running KubeOpera for internal teams (one shared host key with per-team quotas) and a SaaS provider whose customers each bring their own key.

Method	Path	Description
GET · PUT · DELETE	/api/v1/ai-credentials	A tenant sets, checks or removes its own key.
GET · PUT	/api/v1/admin/ai-credentials/host	Platform administrators manage the host key, sharing and quotas.
GET	/internal/ai-credentials/resolve	Services resolve the key for a tenant (cached briefly).
POST	/internal/ai-credentials/usage	Services record usage against a tenant's quota.

Registry tokens

auth-service issues short-lived tokens for KubeOpera's built-in container registry using the standard Docker Registry v2 token protocol. The registry itself knows nothing about tenants — it trusts the signed token — and auth-service only ever grants a credential access to its own tenant's path (tenant-<id>/*), whatever the request asks for.

Method	Path	Description
GET	/v2/registry-token	Registry token endpoint, scoped to the requesting credential's tenant.
POST	/internal/registry-credentials/{tenantID}	Provision a tenant's push and pull credentials.

Cloud credentials

Platform administrators store cloud credentials for provisioning clusters:

• AWS access key — an access key ID and secret;
• AWS assume role — a role ARN (and optional external ID) that KubeOpera assumes for each provisioning run;
• GCP service account — a service-account key.

Credentials are encrypted with AES-256-GCM under the platform MASTER_KEY, and only ever decrypted for cluster-provisioner at the start of a provisioning run. The dashboard sees only a label and the last four characters.

Method	Path	Description
GET · POST	/api/v1/admin/cloud-credentials	List or store credentials.
DELETE	/api/v1/admin/cloud-credentials/{id}	Remove a credential.
GET	/internal/cloud-credentials/{id}/resolve	Resolve a credential for a provisioning run.

The first administrator

auth-service creates the first platform administrator through its admin CLI (kubeopera-admin create-super-admin), which Installation walks through. Cluster Management and the Helm chart call the same operation automatically when you give them an administrator email. It upserts by email, so it's also how you reset a lost administrator password.

REST API

Method	Path	Description
POST	/api/v1/auth/register	Create an account.
POST	/api/v1/auth/login	Sign in with email and password.
POST	/api/v1/auth/refresh	Refresh an access token.
POST	/api/v1/auth/logout	Sign out.
POST	/api/v1/auth/send-verification-email · /verify-email	Email verification.
POST	/api/v1/auth/forgot-password · /reset-password	Password reset.
POST	/api/v1/auth/mfa/enable · /disable · /verify	Multi-factor authentication.
GET	/api/v1/auth/introspect	Validate a token and return its claims.
GET · POST	/api/v1/tokens	List or create personal access tokens.
DELETE	/api/v1/tokens/{id}	Revoke a token.
GET · POST	/api/v1/service-accounts	List or create service accounts.
POST	/oauth/token	OAuth2 token endpoint (client credentials).
GET · POST · PUT · DELETE	/api/v1/users, /api/v1/roles, /api/v1/groups, /api/v1/permissions	User, role, group and permission management.
GET · PUT	/api/v1/sso	A tenant's SSO configuration.
GET	/oauth/{provider} · /oauth/{provider}/callback	Social and OIDC sign-in.
POST	/saml/{tenant}/acs	SAML assertion consumer service.
GET	/api/v1/audit	Audit log (?actor=&action=&from=&to=).
GET	/healthz	Health check.

Configuration

Variable	Default	Description
DATABASE_URL	—	PostgreSQL connection (required).
JWT_ACCESS_SECRETS	—	Signing keys, newest first (required).
JWT_REFRESH_SECRET	—	Refresh-token signing key (required).
ACCESS_TOKEN_TTL / REFRESH_TOKEN_TTL	15m / 7d	Token lifetimes.
MASTER_KEY	—	Encryption key for stored credentials (required).
CACHE_SERVICE_BASE_URL	http://cache-service:8080	Rate-limit storage.
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	—	Google sign-in.
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	—	GitHub sign-in.
PUBLIC_URL	—	auth-service's public address, for OAuth and SAML callbacks.
PORT	8081	HTTP port.