Security Architecture

Security Overview

Rancher implements comprehensive security controls including authentication, authorization, TLS encryption, audit logging, and security hardening features.

Security is a shared responsibility. While Rancher provides security features, proper configuration and maintenance are essential.

Authentication Mechanisms

Rancher’s authentication system is pluggable and supports multiple identity providers simultaneously.

Authentication Architecture

Auth Server

// From pkg/auth/server.go:55
func NewServer(ctx context.Context, wContext *wrangler.Context, 
    scaledContext *config.ScaledContext, 
    authenticator requests.Authenticator) (*Server, error) {
    // Creates authentication middleware
    // Configures auth provider handlers
    // Sets up token management
}

Supported Authentication Providers

Local
SAML
OIDC
LDAP/AD
OAuth2

Local AuthenticationBuilt-in username/password authentication with:

PBKDF2 Password Hashing: Industry-standard key derivation
Secure Storage: Passwords stored in Kubernetes secrets
Bootstrap Admin: First-time admin user creation
Password Policies: Configurable complexity requirements

Local User Storage

# Namespace: cattle-local-user-passwords  
# Secrets contain hashed passwords using PBKDF2
apiVersion: v1
kind: Secret
metadata:
  name: user-<username>
  namespace: cattle-local-user-passwords
data:
  password: <pbkdf2-hash>

Bootstrap password can be set via Helm: --set bootstrapPassword=<password>

SAML 2.0 AuthenticationLocation: pkg/auth/providers/samlFeatures:

Multiple SAML IdP support
Metadata import/export
Group membership synchronization
Attribute mapping
Sign-on URL customization

Endpoints:

/v1-saml/login         # Initiate login
/v1-saml/acs           # Assertion Consumer Service
/v1-saml/metadata      # Service Provider metadata
/v1-saml/idp-metadata  # IdP metadata

Supported IdPs:

Active Directory Federation Services (ADFS)
Okta
Ping Identity
Shibboleth
KeyCloak

OpenID Connect (OIDC)Location: pkg/oidc/ and pkg/auth/providers/Features:

Authorization Code flow
PKCE support
Token refresh
UserInfo endpoint
Multiple OIDC providers

OIDC Configuration

type OIDCConfig struct {
    ClientID     string
    ClientSecret string  
    IssuerURL    string
    RedirectURL  string
    Scopes       []string
}

Supported Providers:

Keycloak
Azure AD
Google
Okta
Generic OIDC

LDAP and Active DirectoryLocation: pkg/auth/providers/Implementations:

ActiveDirectory
OpenLDAP
FreeIPA

Features:

User authentication
Group membership sync
Nested groups
Connection pooling
TLS/StartTLS
Search filters

AD Configuration

servers:
  - ldaps://ad.example.com:636
serviceAccountDN: cn=rancher,ou=service,dc=example,dc=com
userSearchBase: ou=users,dc=example,dc=com
groupSearchBase: ou=groups,dc=example,dc=com

Authentication Flow

User Login

User initiates login via UI or API with credentials

Provider Authentication

Rancher redirects to configured authentication provider (SAML/OIDC) or validates credentials (Local/LDAP)

User Creation

On first login, Rancher creates a User resource in Kubernetes

Token Generation

Rancher generates an API token stored as a Kubernetes secret

Token Return

Token is returned to the client for subsequent requests

Token Management

Location: pkg/auth/tokens/

Token Types

// User API Tokens
- TTL: Configurable (default: no expiration)
- Scope: User identity and permissions
- Storage: Kubernetes Secret in cattle-system

// Kubeconfig Tokens  
- TTL: Short-lived (renewable)
- Scope: kubectl access to specific cluster
- Format: Bearer token

// Cluster Registration Tokens
- TTL: Configurable
- Scope: Agent registration only
- One-time use or reusable

Token Cleanup:

Token Purge Daemon

// From pkg/auth/tokens/
tokens.StartPurgeDaemon(ctx, management)

// Automatically removes:
// - Expired tokens
// - Tokens for deleted users
// - Revoked tokens

API tokens can be managed via UI (User → API Keys) or directly via the /v3/tokens API.

RBAC Model

Rancher implements a hierarchical RBAC system with global, cluster, and project scopes.

RBAC Architecture

Location: pkg/rbac/

RBAC Components

// From pkg/rbac/
- access_control.go      // Permission evaluation
- common.go              // RBAC helpers
- user_based.go          // User-centric checks
- context_access_control.go  // Request context evaluation

Permission Hierarchy

Global Permissions

Scope: Entire Rancher installationBuilt-in roles:

admin: Full administrative access
restricted-admin: Admin without user management
user: Standard user access
user-base: Basic authenticated user

Capabilities:

Manage authentication
Create clusters
Manage users
Configure global settings
Manage catalogs

Global Role Binding

apiVersion: management.cattle.io/v3
kind: GlobalRoleBinding
metadata:
  name: user-admin
globalRoleName: admin
userName: user-abc123

Cluster Permissions

Scope: Specific Kubernetes clusterBuilt-in roles:

cluster-owner: Full cluster access
cluster-member: Read/write access
cluster-viewer: Read-only access

Capabilities:

Manage workloads
Configure cluster settings
Manage node pools
Access kubectl
View resources

Cluster Role Template Binding

apiVersion: management.cattle.io/v3
kind: ClusterRoleTemplateBinding 
metadata:
  name: user-cluster-owner
  namespace: c-m-abcdefgh
clusterName: c-m-abcdefgh
roleTemplateName: cluster-owner
userName: user-abc123

Project Permissions

Scope: Project within a cluster (namespace group)Built-in roles:

project-owner: Full project access
project-member: Create and edit resources
read-only: View-only access

Capabilities:

Deploy applications
Manage namespaces in project
Configure project resources
Set resource quotas
Manage certificates and secrets

Project Role Template Binding

apiVersion: management.cattle.io/v3
kind: ProjectRoleTemplateBinding
metadata:
  name: user-project-owner
  namespace: p-abcde  
projectName: c-m-abcdefgh:p-abcde
roleTemplateName: project-owner
userName: user-abc123

Role Templates

Rancher uses RoleTemplates to define permissions:

Role Template Structure

apiVersion: management.cattle.io/v3
kind: RoleTemplate
metadata:
  name: custom-role
context: cluster  # or project
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["deployments"]  
    verbs: ["*"]
inherited: true    # Available to projects
builtin: false     # Custom role

Role templates can inherit from other role templates and aggregate permissions.

Access Control Evaluation

TLS and Certificate Management

Location: pkg/tls/

TLS Configuration

Rancher supports multiple TLS termination modes:

Rancher-Generated
Let's Encrypt
Custom Certificate
External TLS

Rancher-Generated Certificates

Helm Configuration

ingress:
  tls:
    source: rancher
    secretName: tls-rancher-ingress

Self-signed CA generated by Rancher
Automatic certificate rotation
Suitable for development/testing
Not trusted by browsers (requires CA import)

Let’s Encrypt (ACME)

Helm Configuration

ingress:
  tls:
    source: letsEncrypt
letsEncrypt:
  email: [email protected]
  environment: production
  ingress:
    class: nginx

Automatic certificate provisioning
Auto-renewal
Requires public DNS and open port 80
Production-ready certificates

Custom/Existing Certificate

Helm Configuration

ingress:
  tls:
    source: secret
    secretName: my-tls-secret

Create secret:

kubectl -n cattle-system create secret tls my-tls-secret \
  --cert=tls.crt \
  --key=tls.key

Use existing certificates
Manual renewal
Full control over certificate properties

External TLS Termination

Helm Configuration

tls: external

TLS terminated at load balancer/proxy
Rancher receives plain HTTP
Requires X-Forwarded-Proto header
Common in enterprise environments

Agent TLS Mode

Location: pkg/settings/

TLS Validation Modes

# From chart/values.yaml:54
agentTLSMode: "strict"  # or "system-store"

# strict (default for 2.9+):
# - Validates against provided CA certificate
# - Rejects invalid/self-signed certs
# - Most secure option

# system-store:
# - Uses OS certificate store  
# - More permissive
# - Legacy compatibility

Using system-store may allow man-in-the-middle attacks. Use strict mode in production.

Private CA Support

Private CA Configuration

# Helm values
privateCA: true
additionalTrustedCAs: true

# Create CA bundle secret
kubectl -n cattle-system create secret generic tls-ca \
  --from-file=cacerts.pem=./ca-bundle.crt

# Additional CAs (for auth providers, registries)
kubectl -n cattle-system create secret generic tls-ca-additional \
  --from-file=ca-additional.pem=./additional-ca.crt

Audit Logging

Location: pkg/auth/audit/ Rancher provides comprehensive audit logging for compliance and security monitoring.

Audit Log Configuration

Helm Configuration

auditLog:
  enabled: true
  level: 1  # 0-3
  destination: sidecar  # or hostpath
  maxAge: 10      # days
  maxBackup: 10   # files
  maxSize: 100    # MB

Audit Levels

Level 0: Metadata

Logs request metadata:

User identity
Request path and method
Timestamp
Response code
Source IP

Level 1: Metadata + Headers

Level 0 plus:

Request headers
Response headers

Level 2: + Request Body

Level 1 plus:

Request body content
Useful for create/update operations

Level 3: Full Logging

Level 2 plus:

Response body content
Complete request/response capture
Highest verbosity

Audit Log Format

Sample Audit Log Entry

{
  "auditID": "req-abc123",
  "requestURI": "/v1/management.cattle.io.clusters/c-m-abc",
  "verb": "update",
  "user": {
    "username": "user-abc123",
    "groups": ["system:authenticated"]
  },
  "sourceIPs": ["192.168.1.100"],
  "userAgent": "kubectl/v1.28.0",
  "objectRef": {
    "resource": "clusters",
    "namespace": "",
    "name": "c-m-abc",
    "apiGroup": "management.cattle.io",
    "apiVersion": "v3"
  },
  "responseStatus": {
    "code": 200
  },
  "requestReceivedTimestamp": "2024-01-15T10:30:00.000Z",
  "stageTimestamp": "2024-01-15T10:30:00.123Z"
}

Audit Policies

Location: pkg/controllers/auditlog/auditpolicy/ Custom audit policies can be configured:

Audit Policy CRD

apiVersion: auditlog.cattle.io/v1
kind: AuditPolicy  
metadata:
  name: custom-policy
spec:
  rules:
  - level: RequestResponse
    users: ["admin"]
  - level: Metadata
    resources:
    - group: "management.cattle.io"
      resources: ["clusters"]
  - level: None
    resources:
    - group: ""
      resources: ["configmaps"]

Security Hardening

Pod Security

Rancher supports Pod Security Standards and Pod Security Policies:

Pod Security Configuration

# PSS enforcement via namespace labels
apiVersion: v1
kind: Namespace
metadata:
  name: my-namespace
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/warn: restricted

Security Context Constraints (OpenShift)

Location: pkg/scc/ For OpenShift deployments:

SCC Support

# Rancher can register custom SCCs
# Managed via RancherSCCRegistrationExtension feature
features:
  RancherSCCRegistrationExtension: true

Network Policies

Rancher can deploy network policies:

Network Policy Example

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: rancher-ingress
  namespace: cattle-system
spec:
  podSelector:
    matchLabels:
      app: rancher
  policyTypes:
  - Ingress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: ingress-nginx
    ports:
    - protocol: TCP
      port: 80
    - protocol: TCP  
      port: 443

Secret Encryption

Kubernetes secrets are encrypted at rest when etcd encryption is enabled:

Encryption Configuration

# RKE2/K3s clusters support encryption config
# Managed via EncryptionConfiguration
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
  - resources:
    - secrets
    providers:
    - aescbc:
        keys:
        - name: key1
          secret: <base64-encoded-secret>
    - identity: {}

User and Token Security

User Retention

Location: pkg/auth/userretention/

User Cleanup Policies

// Automatic cleanup of:
// - Inactive users
// - Disabled users
// - Expired tokens

// Configurable retention periods
// Preserves audit trail

Session Management

Session Configuration

# Session timeout settings
auth-user-session-ttl-minutes: 960  # 16 hours default
auth-user-session-max-ttl-minutes: 960

# Token settings
auth-token-max-ttl-minutes: 0  # No expiration default

Password Policies

For local authentication:

Password Requirements

// Minimum length
// Complexity requirements
// Password history
// Lockout policies
// Configured via auth settings

Webhook Authentication

Location: pkg/auth/webhook/ Kubernetes webhook token authenticator integration:

Webhook Config

# Rancher can act as auth webhook for downstream clusters
# Validates Rancher tokens
# Provides user impersonation

Security Best Practices

Authentication

Use external authentication providers (SAML/OIDC/LDAP)

Enable MFA at the identity provider

Regularly rotate API tokens

Use short-lived kubeconfig tokens

Disable unused authentication providers

Authorization

Follow principle of least privilege

Use projects to isolate teams

Create custom roles for specific needs

Regular RBAC audits

Avoid cluster-admin except when necessary

Network Security

Enable TLS for all communications

Use strict agent TLS mode

Implement network policies

Restrict ingress access

Use private networks where possible

Audit and Monitoring

Enable audit logging

Ship logs to SIEM

Monitor authentication failures

Alert on privilege escalation

Regular security reviews

Secrets Management

Enable etcd encryption

Use external secret stores (Vault)

Rotate secrets regularly

Limit secret access via RBAC

Never commit secrets to git

Security Resources

CIS Benchmark

Rancher provides CIS scanning for Kubernetes clusters

Security Advisories

Check Rancher Security for CVEs

Hardening Guide

Follow official hardening guides for production

Compliance

NIST, PCI-DSS, HIPAA considerations

Architecture

Overall architecture

Components

Server components

API Security

API authentication

Getting Started

Architecture

​Security Overview

​Authentication Mechanisms

​Authentication Architecture

​Supported Authentication Providers

​Authentication Flow

​Token Management

​RBAC Model

​RBAC Architecture

​Permission Hierarchy

​Role Templates

​Access Control Evaluation

​TLS and Certificate Management

​TLS Configuration

​Agent TLS Mode

​Private CA Support

​Audit Logging

​Audit Log Configuration

​Audit Levels

​Audit Log Format

​Audit Policies

​Security Hardening

​Pod Security

​Security Context Constraints (OpenShift)

​Network Policies

​Secret Encryption

​User and Token Security

​User Retention

​Session Management

​Password Policies

​Webhook Authentication

​Security Best Practices

​Security Resources

CIS Benchmark

Security Advisories

Hardening Guide

Compliance

​Related Documentation

Architecture

Components

API Security

Build docs developers (and LLMs) love

Security Overview

Authentication Mechanisms

Authentication Architecture

Supported Authentication Providers

Authentication Flow

Token Management

RBAC Model

RBAC Architecture

Permission Hierarchy

Role Templates

Access Control Evaluation

TLS and Certificate Management

TLS Configuration

Agent TLS Mode

Private CA Support

Audit Logging

Audit Log Configuration

Audit Levels

Audit Log Format

Audit Policies

Security Hardening

Pod Security

Security Context Constraints (OpenShift)

Network Policies

Secret Encryption

User and Token Security

User Retention

Session Management

Password Policies

Webhook Authentication

Security Best Practices

Security Resources

Related Documentation