Cluster Authentication Methods

KubeOrch supports 5 authentication methods for connecting to Kubernetes clusters. Each method has different use cases, security characteristics, and setup requirements.

Overview

Method	Best For	Cluster-Side Setup
Bearer Token	Quick setup, service accounts	None
Client Certificate	Strong mutual TLS auth	None
KubeConfig	Existing kubectl users	None
Service Account	Automated/programmatic access	None
OIDC	Enterprise SSO, team access	Required

Bearer Token

Uses a Kubernetes bearer token (e.g., from a ServiceAccount) to authenticate API requests.

Required Fields

• Token: A valid Kubernetes bearer token
• CA Certificate (optional): The cluster’s CA certificate in PEM format
• Insecure: Skip TLS verification (not recommended for production)

How to Get a Token

# Create a service account
kubectl create serviceaccount kubeorch-admin -n kube-system

# Bind cluster-admin role
kubectl create clusterrolebinding kubeorch-admin-binding \
  --clusterrole=cluster-admin \
  --serviceaccount=kube-system:kubeorch-admin

# Generate a token (with 90-day expiry)
kubectl create token kubeorch-admin -n kube-system --duration=2160h

Notes

• Tokens have an expiry — you’ll need to rotate them before they expire
• For long-lived access, consider using a Service Account with a bound token

---

Client Certificate

Uses X.509 client certificates for mutual TLS authentication. The Kubernetes API server verifies the client certificate against its CA.

Required Fields

• Client Certificate: X.509 certificate in PEM format
• Client Key: Private key in PEM format
• CA Certificate (optional): The cluster’s CA certificate in PEM format

How to Get Certificates

For minikube:

# Client certificate
cat ~/.minikube/profiles/minikube/client.crt

# Client key
cat ~/.minikube/profiles/minikube/client.key

# CA certificate
cat ~/.minikube/ca.crt

For other clusters, certificates are typically generated by the cluster administrator using kubeadm or a PKI tool.

Notes

• Certificates are base64-encoded before being sent to the API for security
• Certificate-based auth provides strong identity without token expiry concerns
• The certificate’s Common Name (CN) and Organization (O) fields determine the Kubernetes username and groups

---

KubeConfig

Uses a standard Kubernetes kubeconfig YAML file. This is the same format used by kubectl.

Required Fields

• KubeConfig: A complete, self-contained kubeconfig YAML
• Namespace (optional): Default namespace for operations

How to Get a KubeConfig

# Export your current kubeconfig with embedded credentials (no file paths)
kubectl config view --flatten --minify

Important

The kubeconfig must be self-contained — it must use embedded data fields, not file paths:

# Correct - embedded data
clusters:
- cluster:
    certificate-authority-data: LS0tLS1CRUdJTi...  # base64 encoded
    server: https://your-cluster:6443

# Incorrect - file paths (won't work)
clusters:
- cluster:
    certificate-authority: /path/to/ca.crt  # file path won't work
    server: https://your-cluster:6443

Use kubectl config view --flatten to convert file paths to embedded data.

---

Service Account

Similar to Bearer Token but specifically designed for Kubernetes Service Account tokens. These tokens are namespace-scoped and tied to a specific ServiceAccount identity.

Required Fields

• Token: A ServiceAccount token
• Namespace: The namespace where the ServiceAccount exists
• CA Certificate (optional): The cluster’s CA certificate in PEM format
• Insecure: Skip TLS verification

How to Set Up

# Create a service account in your target namespace
kubectl create serviceaccount kubeorch-sa -n kube-system

# Grant appropriate permissions
kubectl create clusterrolebinding kubeorch-sa-binding \
  --clusterrole=cluster-admin \
  --serviceaccount=kube-system:kubeorch-sa

# Generate a token
kubectl create token kubeorch-sa -n kube-system --duration=2160h

Difference from Bearer Token

While both use tokens, Service Account auth includes namespace context and is mapped to a Kubernetes ServiceAccount identity. This provides better auditability in Kubernetes RBAC logs.

---

OIDC (OpenID Connect)

Uses an external identity provider (Google, Azure AD, Okta, etc.) for authentication. This is the recommended method for enterprise environments with SSO.

Required Fields

• OIDC Issuer URL: The identity provider’s issuer URL (e.g., https://accounts.google.com)
• Client ID: OAuth client ID from your identity provider
• Client Secret: OAuth client secret
• Refresh Token: An OAuth refresh token for obtaining new ID tokens

Cluster-Side Setup Required

Unlike other auth methods, OIDC requires the Kubernetes API server to be configured to trust the identity provider. This is a one-time setup done by the cluster administrator.

Minikube

minikube start \
  --extra-config=apiserver.oidc-issuer-url=https://accounts.google.com \
  --extra-config=apiserver.oidc-client-id=YOUR_CLIENT_ID

kubeadm / Self-Managed

Add these flags to the API server manifest (/etc/kubernetes/manifests/kube-apiserver.yaml):

spec:
  containers:
  - command:
    - kube-apiserver
    - --oidc-issuer-url=https://accounts.google.com
    - --oidc-client-id=YOUR_CLIENT_ID
    - --oidc-username-claim=email
    - --oidc-groups-claim=groups

Managed Kubernetes

Provider	How to Enable
GKE	Google OIDC works automatically for Google identity
EKS	aws eks associate-identity-provider-config
AKS	Azure AD integration is built-in via az aks update --enable-aad

How to Get OIDC Credentials (Google Example)

1. Go to Google Cloud Console > APIs & Services > Credentials
2. Create an OAuth 2.0 Client ID (type: Web application)
3. Set the redirect URI (e.g., http://localhost:8080/api/v1/auth/callback)
4. Get the Client ID and Client Secret
5. Obtain a Refresh Token via the OAuth consent flow:

# Step 1: Open in browser to authorize
# https://accounts.google.com/o/oauth2/auth?client_id=YOUR_CLIENT_ID&response_type=code&scope=openid%20email&access_type=offline&prompt=consent&redirect_uri=YOUR_REDIRECT_URI

# Step 2: Exchange the auth code for tokens
curl -s -X POST 'https://oauth2.googleapis.com/token' \
  --data-urlencode 'code=AUTH_CODE_FROM_REDIRECT' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'redirect_uri=YOUR_REDIRECT_URI' \
  --data-urlencode 'grant_type=authorization_code'

The response contains the refresh_token needed for KubeOrch.

Notes

• OIDC is the only auth method that requires cluster-side configuration
• KubeOrch automatically refreshes the ID token using the refresh token
• The cluster API server validates the ID token against the issuer’s public keys

---

Security Considerations

• All credentials are encrypted at rest using AES-256-GCM before being stored in the database
• Credentials are never returned in API responses after creation
• When editing a cluster, existing credentials are preserved if no new values are provided
• Use the Insecure option (skip TLS) only for development/testing environments
• For production, always provide a CA certificate or use a cluster with a publicly trusted certificate