docs auth

2026-03-16 11:14:12 +01:00
parent d02da33700
commit ae075bbc48
4 changed files with 847 additions and 36 deletions
--- a/docs/REFERENCE.md
+++ b/docs/REFERENCE.md
@@ -299,19 +299,27 @@ ingress:
    clusterIssuer: letsencrypt-prod

 auth:
-  enabled: false
-  type: token                   # Options: "token", "oidc"
-  oidc:
-    authority: ""
-    clientId: ""
-    scopes: ""
-    callbackPath: /auth/callback
-  tokens: []
-  # - token1
-  # - token2
+  enabled: false                 # Enable authentication sidecar injection
+  type: token                    # Authentication mode: "token" or "oidc"

-configmap: []
+  # Token-based authentication configuration
+  tokens: []                     # List of valid bearer tokens (hex strings, 32+ bytes recommended)
+  # - d4f88f6d9292c10cc3e21c4aad56d2be485db532b54fe961d738e1137d247823
+  # - 8803f621acc3898df1d7a8f514bc3602551a0681a8f747bd4e43c3c5849d57a7
+
+  # OIDC authentication configuration
+  oidc:
+    authority: ""                # OIDC provider URL (e.g., https://auth.example.com/realms/master)
+    clientId: ""                 # OIDC client ID registered with provider
+    scopes: "openid,profile,email"  # OAuth scopes (comma-separated)
+    callbackPath: /auth/callback    # OAuth callback path (default: /auth/callback)
+    # Note: Client secret must be in 'auth-oidc' Secret (client-secret key)
+    #       Cookie secret must be in 'auth-oidc' Secret (cookie-secret key)
+
+configmap: []                    # Application ConfigMap key-value pairs
 # KEY: value
+# DB_HOST: postgres
+# DB_PORT: "5432"
 ```

 ---
@@ -818,35 +826,235 @@ spec:

 **File**: `cluster-resources/policies/auth-sidecar-injector.yaml`

-**Purpose**: Inject authentication sidecar based on pod annotations
+**Purpose**: Automatically inject authentication sidecar into pods with authentication enabled
+
+**Rules**: 5 rules in the policy
+1. `generate-auth-tokens-secret` - Creates Secret for token mode
+2. `generate-auth-oidc-secret` - Creates Secret for OIDC mode
+3. `inject-sidecar-token` - Injects auth sidecar for token mode
+4. `inject-sidecar-oidc` - Injects auth sidecar for OIDC mode
+5. `generate-auth-network-policy` - Creates NetworkPolicy to restrict ingress
+
+#### Trigger Annotation

 ```yaml
-apiVersion: kyverno.io/v1
-kind: ClusterPolicy
-metadata:
-  name: inject-auth-sidecar
-spec:
-  rules:
-  - name: inject-sidecar
-    match:
-      any:
-      - resources:
-          kinds:
-          - Pod
-    preconditions:
-      all:
-      - key: "{{ request.object.metadata.annotations.\"policies.forteapps.io/auth\" || '' }}"
-        operator: Equals
-        value: "true"
-    mutate:
-      patchStrategicMerge:
-        spec:
-          containers:
-          - name: auth-proxy
-            image: oauth2-proxy/oauth2-proxy:latest
-            # ... additional configuration
+policies.forteapps.io/auth: "true"
 ```

+#### Authentication Modes
+
+**Token Mode** (default):
+```yaml
+# Annotations
+policies.forteapps.io/auth: "true"
+policies.forteapps.io/auth-type: "token"
+policies.forteapps.io/auth-token-secret-name: "auth-tokens"
+policies.forteapps.io/auth-upstream-url: "http://localhost:3000"
+
+# Optional customization
+policies.forteapps.io/auth-image: "ghcr.io/snothub/stunning-memory"
+policies.forteapps.io/auth-image-version: "latest"
+```
+
+**OIDC Mode**:
+```yaml
+# Annotations (required)
+policies.forteapps.io/auth: "true"
+policies.forteapps.io/auth-type: "oidc"
+policies.forteapps.io/auth-oidc-authority: "https://auth.example.com/realms/master"
+policies.forteapps.io/auth-oidc-client-id: "myapp"
+
+# Optional annotations
+policies.forteapps.io/auth-oidc-callback-path: "/auth/callback"
+policies.forteapps.io/auth-oidc-scopes: "openid,profile,email"
+policies.forteapps.io/auth-upstream-url: "http://localhost:3000"
+policies.forteapps.io/auth-image: "ghcr.io/snothub/stunning-memory"
+policies.forteapps.io/auth-image-version: "latest"
+```
+
+#### Sidecar Container Specification
+
+**Token Mode**:
+```yaml
+name: authn
+image: ghcr.io/snothub/stunning-memory:latest
+ports:
+- containerPort: 8080
+  name: auth
+  protocol: TCP
+env:
+- name: AUTH_MODE
+  value: "token"
+- name: AUTH_LISTEN_ADDR
+  value: ":8080"
+- name: AUTH_UPSTREAM_URL
+  value: "http://localhost:3000"
+- name: AUTH_TOKEN_FILE
+  value: "/etc/auth/tokens"
+volumeMounts:
+- name: auth-tokens
+  mountPath: /etc/auth
+  readOnly: true
+resources:
+  requests:
+    cpu: 10m
+    memory: 32Mi
+  limits:
+    cpu: 50m
+    memory: 64Mi
+securityContext:
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities:
+    drop: [ALL]
+```
+
+**OIDC Mode**:
+```yaml
+name: authn
+image: ghcr.io/snothub/stunning-memory:latest
+ports:
+- containerPort: 8080
+  name: auth
+  protocol: TCP
+env:
+- name: AUTH_MODE
+  value: "oidc"
+- name: AUTH_LISTEN_ADDR
+  value: ":8080"
+- name: AUTH_UPSTREAM_URL
+  value: "http://localhost:3000"
+- name: AUTH_OIDC_AUTHORITY
+  value: "https://auth.example.com/realms/master"
+- name: AUTH_OIDC_CLIENT_ID
+  value: "myapp"
+- name: AUTH_OIDC_CALLBACK_PATH
+  value: "/auth/callback"
+- name: AUTH_OIDC_SCOPES
+  value: "openid,profile,email"
+- name: AUTH_OIDC_COOKIE_SECRET
+  valueFrom:
+    secretKeyRef:
+      name: auth-oidc
+      key: cookie-secret
+- name: AUTH_OIDC_CLIENT_SECRET
+  valueFrom:
+    secretKeyRef:
+      name: auth-oidc
+      key: client-secret
+resources:
+  requests:
+    cpu: 10m
+    memory: 32Mi
+  limits:
+    cpu: 50m
+    memory: 64Mi
+securityContext:
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities:
+    drop: [ALL]
+```
+
+#### Generated Resources
+
+**Secret (Token Mode)**:
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: auth-tokens
+  namespace: <app-namespace>
+  labels:
+    app.kubernetes.io/managed-by: kyverno
+    app.kubernetes.io/created-by: inject-auth-sidecar
+type: Opaque
+data: {}  # Populated by Helm chart
+```
+
+**Secret (OIDC Mode)**:
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: auth-oidc
+  namespace: <app-namespace>
+  labels:
+    app.kubernetes.io/managed-by: kyverno
+    app.kubernetes.io/created-by: inject-auth-sidecar
+type: Opaque
+data:
+  client-secret: <base64>
+  cookie-secret: <base64>
+```
+
+**NetworkPolicy**:
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: <pod-name>-auth-ingress
+  namespace: <app-namespace>
+  labels:
+    app.kubernetes.io/managed-by: kyverno
+    app.kubernetes.io/created-by: inject-auth-sidecar
+spec:
+  podSelector:
+    matchLabels: <pod-labels>
+  policyTypes:
+  - Ingress
+  ingress:
+  - ports:
+    - port: 8080
+      protocol: TCP
+```
+
+#### Excluded Namespaces
+
+The policy does NOT apply to:
+- `kube-system`
+- `kyverno`
+- `argocd`
+- `cert-manager`
+- `monitoring`
+
+#### Health Checks
+
+```yaml
+readinessProbe:
+  httpGet:
+    path: /healthz
+    port: 8080
+  initialDelaySeconds: 2
+  periodSeconds: 5
+
+livenessProbe:
+  httpGet:
+    path: /healthz
+    port: 8080
+  initialDelaySeconds: 5
+  periodSeconds: 10
+```
+
+#### Request Flow
+
+```
+External Request → Traefik
+    ↓
+Service (port 8080)
+    ↓
+Pod: Auth Sidecar (port 8080)
+    ├─ Validate credentials
+    │  • Token mode: Check Bearer token
+    │  • OIDC mode: Validate session or redirect to IdP
+    ↓
+Forward to Application (localhost:3000)
+    ↓
+Application processes request
+```
+
+**See**: [Developer Guide - Enabling Authentication](DEVELOPER-GUIDE.md#enabling-authentication-for-applications) for usage examples.
+
 ---

 ## Configuration Reference