Kube AuthKit - Kubernetes Authentication Toolkit

A lightweight Python library that provides unified authentication for OpenShift and Kubernetes clusters. This library simplifies authentication by supporting multiple methods through a single, consistent interface.

Features

• Universal Authentication Support

  • Standard Kubernetes KubeConfig (~/.kube/config)
  • In-Cluster Service Account (for Pods and Notebooks)
  • OIDC (OpenID Connect) with multiple flows
  • OpenShift OAuth

• Auto-Detection: Automatically detects and uses the best authentication method for your environment

• Multiple OIDC Flows

  • Authorization Code Flow with PKCE (for interactive apps)
  • Device Code Flow (for CLI tools and headless environments)
  • Client Credentials Flow (for service-to-service authentication)

• Token Management

  • Automatic token refresh
  • Optional persistent storage via system keyring
  • Secure in-memory storage by default

• Security First

  • TLS verification enabled by default
  • No sensitive data in logs
  • Minimal dependencies

Installation

pip install kube-authkit

For optional keyring support (persistent token storage):

pip install kube-authkit[keyring]

Quick Start

Automatic Authentication (Recommended)

The library automatically detects your environment and chooses the appropriate authentication method:

from kube_authkit import get_k8s_client
from kubernetes import client

# Auto-detect environment and authenticate
api_client = get_k8s_client()

# Use with standard Kubernetes client
v1 = client.CoreV1Api(api_client)
pods = v1.list_pod_for_all_namespaces()
print(f"Found {len(pods.items)} pods")

This works seamlessly whether you're running:

• Locally with ~/.kube/config
• Inside a Kubernetes Pod or OpenShift Notebook (using Service Account)
• With OIDC credentials in environment variables

Explicit OIDC Authentication

For CLI tools or when you need explicit control:

from kube_authkit import get_k8s_client, AuthConfig

config = AuthConfig(
    method="oidc",
    oidc_issuer="https://keycloak.example.com/auth/realms/myrealm",
    client_id="my-cli-tool",
    use_device_flow=True  # Good for headless/CLI environments
)

# This will print: "Visit https://... and enter code: ABCD-EFGH"
api_client = get_k8s_client(config)

Interactive Browser-Based Authentication

For notebooks or interactive applications:

from kube_authkit import get_k8s_client, AuthConfig

config = AuthConfig(
    method="oidc",
    oidc_issuer="https://keycloak.example.com/auth/realms/myrealm",
    client_id="my-app",
    use_device_flow=False  # Use Authorization Code Flow (opens browser)
)

# Browser will open for authentication
api_client = get_k8s_client(config)

Persistent Token Storage

Store refresh tokens securely in your system keyring:

from kube_authkit import get_k8s_client, AuthConfig

config = AuthConfig(
    method="oidc",
    oidc_issuer="https://keycloak.example.com/auth/realms/myrealm",
    client_id="my-app",
    use_keyring=True  # Store tokens in system keyring
)

# First run: Interactive authentication
# Subsequent runs: Uses stored refresh token automatically
api_client = get_k8s_client(config)

Advanced: Customize Client Configuration

For advanced use cases where you need to customize the Kubernetes client configuration before creating the client:

from kube_authkit import get_k8s_config
from kubernetes import client

# Get just the configuration (without creating ApiClient yet)
k8s_config = get_k8s_config()

# Customize configuration as needed
k8s_config.debug = True        # Enable debug logging
k8s_config.verify_ssl = False  # Disable SSL verification (dev only)

# Create client with customized configuration
api_client = client.ApiClient(k8s_config)
v1 = client.CoreV1Api(api_client)

This is useful when you need:

• Custom debug settings
• SSL/TLS configuration
• Multiple clients with the same authentication but different settings
• To inspect the configuration before using it

Configuration

AuthConfig Options

Parameter	Type	Default	Description
method	str	"auto"	Authentication method: "auto", "kubeconfig", "incluster", "oidc", "openshift"
k8s_api_host	str	None	Kubernetes API server URL (auto-detected if not provided)
oidc_issuer	str	None	OIDC issuer URL (required for OIDC)
client_id	str	None	OIDC client ID (required for OIDC)
client_secret	str	None	OIDC client secret (for confidential clients)
scopes	list	["openid"]	OIDC scopes to request
use_device_flow	bool	False	Use Device Code Flow instead of Authorization Code Flow
use_keyring	bool	False	Store refresh tokens in system keyring
ca_cert	str	None	Path to custom CA certificate bundle
verify_ssl	bool	True	Verify SSL certificates (disable only for development)

Environment Variables

The library respects these environment variables:

• KUBECONFIG: Path to kubeconfig file
• KUBERNETES_SERVICE_HOST: Auto-detected in-cluster (set by Kubernetes)
• AUTHKIT_OIDC_ISSUER: OIDC issuer URL
• AUTHKIT_CLIENT_ID: OIDC client ID
• AUTHKIT_CLIENT_SECRET: OIDC client secret
• AUTHKIT_TOKEN: Bearer token for authentication
• AUTHKIT_API_HOST: Kubernetes API server URL
• OPENSHIFT_TOKEN: Legacy OpenShift OAuth token (use AUTHKIT_TOKEN instead)

Architecture

This library uses the Strategy Pattern to provide a unified interface across different authentication methods:

AuthFactory (auto-detection)
    ├── KubeConfigStrategy (~/.kube/config)
    ├── InClusterStrategy (Service Account)
    ├── OIDCStrategy (OpenID Connect)
    └── OpenShiftOAuthStrategy (OpenShift OAuth)

Each strategy implements the same interface, making it easy to add new authentication methods in the future.

Security Considerations

1. TLS Verification: Enabled by default. Only disable for development/testing.
2. Token Storage: In-memory by default. Use keyring for persistence across sessions.
3. Logging: No sensitive data (tokens, secrets) is ever logged.
4. Dependencies: Minimal dependency footprint to reduce supply chain risk.

Development

Setup Development Environment

# Clone repository
git clone https://github.com/openshift/kube-authkit.git
cd kube-authkit

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests with coverage
pytest

# Run specific test file
pytest tests/test_config.py

# Run with verbose output
pytest -v

# Type checking
mypy src/kube_authkit

# Code formatting
black src/ tests/
ruff check src/ tests/

# Security scanning
bandit -r src/

Examples

See the examples/ directory for complete examples:

• auto_auth.py - Simple auto-detection
• oidc_device_flow.py - CLI tool with device flow
• oidc_auth_code.py - Interactive browser-based auth
• notebook_usage.py - Jupyter notebook example
• explicit_config.py - All configuration options
• custom_ca.py - Custom CA certificate

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

Apache License 2.0 - see LICENSE for details.

Support

• Issues: https://github.com/openshift/kube-authkit/issues
• Documentation: https://github.com/openshift/kube-authkit#readme

Acknowledgments

This library wraps and extends the official Kubernetes Python Client to provide simplified authentication workflows for OpenShift AI and Kubernetes environments.