Auth Module - Kubernetes Dashboard

Overview

The Auth module is a lightweight Go application responsible for handling authentication to the Kubernetes API. It provides secure login endpoints and manages user sessions through token validation.

The Auth module acts as an authentication gateway, validating credentials before granting access to Dashboard features.

Module Architecture

Entry Point

The module starts in modules/auth/main.go:

func main() {
    klog.InfoS("Starting Kubernetes Dashboard Auth", "version", environment.Version)
    
    // Initialize Kubernetes client
    client.Init(
        client.WithUserAgent(environment.UserAgent()),
        client.WithKubeconfig(args.KubeconfigPath()),
        client.WithMasterUrl(args.ApiServerHost()),
        client.WithInsecureTLSSkipVerify(args.ApiServerSkipTLSVerify()),
        client.WithCaBundle(args.ApiServerCaBundle()),
    )
    
    // Start Gin router
    klog.V(1).InfoS("Listening and serving insecurely on", "address", args.Address())
    if err := router.Router().Run(args.Address()); err != nil {
        klog.ErrorS(err, "Router error")
        os.Exit(1)
    }
}

Reference: modules/auth/main.go:33-49

Package Structure

modules/auth/
├── api/
│   └── v1/
│       └── login.go        # Login API types
├── pkg/
│   ├── args/              # Command-line arguments
│   ├── environment/       # Version information
│   ├── router/            # Gin router setup
│   └── routes/            # Route handlers
│       ├── csrftoken/     # CSRF token generation
│       ├── login/         # Login handler
│       └── me/            # User info endpoint
└── main.go

Core Responsibilities

1. User Authentication

The Auth module validates user credentials against the Kubernetes API Server.

2. CSRF Token Generation

Provides CSRF tokens for state-changing operations:

// GET /api/v1/csrftoken/{action}
// Returns a one-time CSRF token

type CsrfTokenResponse struct {
    Token string `json:"token"`
}

Reference: modules/auth/pkg/routes/csrftoken/handler.go

3. User Information

Returns authenticated user details:

// GET /api/v1/me
// Returns current user information

type UserResponse struct {
    Username  string   `json:"username"`
    Groups    []string `json:"groups"`
    Namespace string   `json:"namespace"`
}

Reference: modules/auth/pkg/routes/me/handler.go

Authentication Methods

The Auth module supports multiple authentication strategies:

Token-Based Authentication

Users provide a Kubernetes service account token or user token:

{
  "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii...",
  "namespace": "default"
}

Token Validation Process

Receive token from login request
Create TokenReview request to Kubernetes API
Validate response from TokenReview API
Extract user info (username, UID, groups)
Generate session token or cookie
Return authentication response

Kubeconfig-Based Authentication

Users can upload kubeconfig files containing:

Client certificates
Bearer tokens
Username/password credentials

Kubeconfig authentication should only be used in trusted environments. Tokens are preferred for production.

API Routes

The Auth module exposes three primary endpoints: Authenticates a user and returns session information. Request:

{
  "token": "string",
  "namespace": "string"
}

Response:

{
  "jweToken": "string",
  "errors": []
}

Reference: modules/auth/pkg/routes/login/handler.go:27-48

GET /api/v1/csrftoken/

Generates a CSRF token for the specified action. Parameters:

action (path): Action name (e.g., “deploy”, “scale”)

Response:

{
  "token": "string"
}

GET /api/v1/me

Returns information about the currently authenticated user. Response:

{
  "username": "system:serviceaccount:default:dashboard",
  "groups": [
    "system:serviceaccounts",
    "system:authenticated"
  ]
}

Security Features

CSRF Protection

The Auth module generates CSRF tokens using a shared secret:

import "golang.org/x/net/xsrftoken"

func generateToken(action, userID string) string {
    return xsrftoken.Generate(
        csrfKey,      // Shared secret with API module
        userID,       // User identifier
        action,       // Action being protected
    )
}

The CSRF key is:

Shared between Auth and API modules via Kubernetes Secret
Base64-encoded 256-byte random string
Auto-generated if not provided in Helm values

Session Management

Authentication sessions are managed through:

JWE Tokens: Encrypted JSON Web Tokens
HTTP-only Cookies: Secure session cookies
Token Refresh: Automatic token refresh mechanism

TLS/HTTPS

The Auth module supports both HTTP and HTTPS:

// HTTP mode (behind Kong gateway)
router.Router().Run(args.Address())

// HTTPS mode (direct access)
router.Router().RunTLS(args.Address(), certPath, keyPath)

In typical deployments, the Auth module runs HTTP behind Kong Gateway, which handles TLS termination.

Request Flow

Token Review API

The Auth module uses Kubernetes TokenReview API:

apiVersion: authentication.k8s.io/v1
kind: TokenReview
spec:
  token: "<user-provided-token>"
status:
  authenticated: true
  user:
    username: "system:serviceaccount:default:dashboard"
    uid: "abc123"
    groups:
    - "system:serviceaccounts"
    - "system:authenticated"

Configuration Arguments

Key command-line arguments:

Argument	Description	Default
`--kubeconfig`	Path to kubeconfig file	In-cluster config
`--apiserver-host`	Kubernetes API server URL	Auto-detected
`--bind-address`	Bind address	`0.0.0.0:8000`
`--csrf-key`	CSRF token secret key	Auto-generated
`--token-ttl`	Session token TTL	`15m`

Reference: modules/auth/pkg/args/args.go

Router Setup

The Auth module uses Gin web framework:

func Router() *gin.Engine {
    router := gin.New()
    
    // Middleware
    router.Use(gin.Logger())
    router.Use(gin.Recovery())
    
    // CORS headers
    router.Use(corsMiddleware())
    
    // API v1 routes
    v1 := router.Group("/api/v1")
    
    return router
}

Reference: modules/auth/pkg/router/setup.go

Route Registration

Routes are registered via init() functions:

// modules/auth/main.go
import (
    _ "k8s.io/dashboard/auth/pkg/routes/csrftoken"
    _ "k8s.io/dashboard/auth/pkg/routes/login"
    _ "k8s.io/dashboard/auth/pkg/routes/me"
)

// modules/auth/pkg/routes/login/handler.go
func init() {
    router.V1().POST("/login", handleLogin)
}

Reference: modules/auth/main.go:27-31

Error Handling

Consistent error responses:

{
  "errors": [
    "Invalid authentication token"
  ]
}

HTTP status codes:

200 OK - Successful authentication
400 Bad Request - Malformed request
401 Unauthorized - Invalid credentials
500 Internal Server Error - Server error

Integration with Other Modules

With API Module

The API module validates CSRF tokens generated by Auth module:

// API module validates token
if !xsrftoken.Valid(token, csrfKey, userID, action) {
    return errors.New("invalid CSRF token")
}

With Kong Gateway

Kong routes authentication requests to Auth module:

routes:
  - name: auth-login
    paths:
      - /api/v1/login
    service: kubernetes-dashboard-auth

Deployment

Helm chart configuration:

auth:
  image:
    repository: kubernetesui/dashboard-auth
    tag: v1.0.0
  scaling:
    replicas: 1
  containers:
    args: []
    env:
      - name: CSRF_KEY
        valueFrom:
          secretKeyRef:
            name: kubernetes-dashboard-csrf
            key: csrf

Reference: charts/kubernetes-dashboard/templates/deployments/auth.yaml

Testing

Run Auth module tests:

cd modules/auth
go test ./...

Manual Testing

# Get service account token
TOKEN=$(kubectl get secret <secret-name> -o jsonpath='{.data.token}' | base64 -d)

# Test login endpoint
curl -X POST http://localhost:8000/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"token": "'$TOKEN'"}'

# Test CSRF endpoint
curl http://localhost:8000/api/v1/csrftoken/deploy

Logging

The Auth module uses structured logging:

import "k8s.io/klog/v2"

klog.InfoS("Starting Kubernetes Dashboard Auth", "version", environment.Version)
klog.ErrorS(err, "Could not log in")
klog.V(1).InfoS("Listening and serving on", "address", args.Address())

Log levels:

0 - Info and errors
1 - Verbose info
2+ - Debug information

Security Best Practices

Token Storage

Never log authentication tokens
Clear tokens from memory after use
Use secure session storage

CSRF Protection

Rotate CSRF keys regularly
Use different tokens for different actions
Validate token expiration

TLS Configuration

Always use HTTPS in production
Use strong cipher suites
Enable certificate validation

Rate Limiting

Implement login attempt limiting
Block suspicious IP addresses
Monitor failed authentication attempts

Troubleshooting

Common Issues

401 Unauthorized

Cause: Invalid or expired tokenSolution:

Verify token is valid: kubectl get secret
Check token hasn’t expired
Ensure service account exists

CSRF Token Mismatch

Cause: Auth and API modules using different CSRF keysSolution:

Check kubernetes-dashboard-csrf secret
Restart both Auth and API pods
Verify secret is mounted correctly

Cannot Connect to Kubernetes API

Cause: Invalid API server configurationSolution:

Check --apiserver-host argument
Verify RBAC permissions
Check network connectivity

API Module

How API module validates CSRF tokens

Security

Dashboard security documentation

RBAC Configuration

Setting up proper permissions

Kubernetes TokenReview

Kubernetes TokenReview API documentation

Get Started

User Guide

Architecture

Configuration

​Overview

​Module Architecture

​Entry Point

​Package Structure

​Core Responsibilities

​1. User Authentication

​Login Request Flow

​2. CSRF Token Generation

​3. User Information

​Authentication Methods

​Token-Based Authentication

​Token Validation Process

​Kubeconfig-Based Authentication

​API Routes

​POST /api/v1/login

​GET /api/v1/csrftoken/

​GET /api/v1/me

​Security Features

​CSRF Protection

​Session Management

​TLS/HTTPS

​Request Flow

​Login Flow

​Token Review API

​Configuration Arguments

​Router Setup

​Route Registration

​Error Handling

​Integration with Other Modules

​With API Module

​With Kong Gateway

​Deployment

​Testing

​Manual Testing

​Logging

​Security Best Practices

​Troubleshooting

​Common Issues

​Related Resources

API Module

Security

RBAC Configuration

Kubernetes TokenReview

Build docs developers (and LLMs) love

Overview

Module Architecture

Entry Point

Package Structure

Core Responsibilities

1. User Authentication

Login Request Flow

2. CSRF Token Generation

3. User Information

Authentication Methods

Token-Based Authentication

Token Validation Process

Kubeconfig-Based Authentication

API Routes

POST /api/v1/login

GET /api/v1/csrftoken/

GET /api/v1/me

Security Features

CSRF Protection

Session Management

TLS/HTTPS

Request Flow

Login Flow

Token Review API

Configuration Arguments

Router Setup

Route Registration

Error Handling

Integration with Other Modules

With API Module

With Kong Gateway

Deployment

Testing

Manual Testing

Logging

Security Best Practices

Troubleshooting

Common Issues

Related Resources