Skip to content

Overview

This section provides comprehensive reference documentation for Kubauth's Kubernetes Custom Resource Definitions (CRDs).

Custom Resources

Kubauth stores all configuration and user data as native Kubernetes resources, providing a cloud-native, scalable solution without requiring an external database.

Core Resources

  • OidcClient - OIDC client application definitions
  • User - User account definitions with authentication credentials
  • Group - Group definitions with shared claims
  • GroupBinding - User-to-group associations

API Group and Version

All Kubauth resources use the following API group and version:

  • API Group: kubauth.kubotal.io
  • Version: v1alpha1

Resource Organization

Namespaces

Kubauth resources are namespaced and typically organized as follows:

Resource Type Default Namespace Configurable
OidcClient kubauth-oidc Yes
User kubauth-users Yes
Group kubauth-users Yes
GroupBinding kubauth-users Yes

Namespace configuration can be adjusted via Helm chart values during Kubauth deployment.

Common Patterns

Accessing Resources

Fully Qualified Names

Since some resource names (like User) are common and may conflict with other CRDs, use fully qualified names:

kubectl -n kubauth-users get users.kubauth.kubotal.io

Using Aliases

For convenience, Kubauth provides aliases:

# User alias
kubectl -n kubauth-users get kusers

Listing Resources

# List all OIDC clients
kubectl -n kubauth-oidc get oidcclients

# List all users
kubectl -n kubauth-users get users.kubauth.kubotal.io

# List all groups
kubectl -n kubauth-users get groups.kubauth.kubotal.io

# List all group bindings
kubectl -n kubauth-users get groupbindings

Describing Resources

# Describe an OIDC client
kubectl -n kubauth-oidc describe oidcclient myapp

# Describe a user
kubectl -n kubauth-users describe user john

# Describe a group
kubectl -n kubauth-users describe group developers

Security Considerations

Access Control

Use Kubernetes RBAC to control access to Kubauth resources:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kubauth-user-manager
  namespace: kubauth-users
rules:
- apiGroups: ["kubauth.kubotal.io"]
  resources: ["users", "groupbindings"]
  verbs: ["get", "list", "create", "update", "patch", "delete"]

Secret Management

  • User Passwords: Always stored as bcrypt hashes, never in plain text
  • Client Secrets: Stored as bcrypt hashes in OidcClient resources
  • Use kc hash command: Generate hashes for passwords and secrets

Best Practices

Resource Naming

  • Use descriptive, lowercase names with hyphens
  • Follow consistent naming conventions across your organization
  • For GroupBindings, use pattern: <username>-<groupname>

Examples Repository

Complete examples for all resources can be found throughout the documentation:

Additional Resources