gitops/apps/argocd-config/OIDC_SECRET_SETUP.md

ArgoCD OIDC Secret Setup - Best Practices & Troubleshooting

Problem

ArgoCD Secret-Referenzen in oidc.config funktionieren nicht zuverlässig. Dies ist ein bekanntes Problem (siehe GitHub Issue #18576).

Warum funktionieren Secret-Referenzen nicht?

1. Timing-Problem: ArgoCD liest die ConfigMap beim Start. Wenn das Secret noch nicht existiert oder noch nicht bereit ist, cached ArgoCD die "Key does not exist" Warnung.

2. Secret-Name-Konvention: ArgoCD erwartet standardmäßig Keys im Secret argocd-secret (nicht argocd-oidc-secret).

3. Key-Namen-Format: Keys sollten mit Punkten formatiert sein (z.B. oidc.authentik.clientID), nicht mit Unterstrichen oder Bindestrichen.

4. Label-Requirement: Das Secret benötigt das Label app.kubernetes.io/part-of: argocd, damit ArgoCD es findet.

Lösungsoptionen

Option 1: Nutzung des Haupt-Secrets argocd-secret (Empfohlen)

Vorteile:

• ArgoCD erwartet dies standardmäßig
• Keine Probleme mit Secret-Namen
• Bewährte Praxis

Nachteile:

• Erfordert Zugriff auf das bestehende argocd-secret
• Könnte Konflikte mit bestehenden Keys geben

Implementierung:

# ExternalSecret: Keys ins argocd-secret schreiben
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: argocd-oidc-secret-source
  namespace: argocd
spec:
  refreshInterval: 1m
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: argocd-secret  # <-- Haupt-Secret verwenden
    creationPolicy: Merge  # <-- Merge, nicht Owner!
  data:
    - secretKey: oidc.authentik.clientID
      remoteRef:
        key: secret/apps/argocd
        property: oidc_client_id
    - secretKey: oidc.authentik.clientSecret
      remoteRef:
        key: secret/apps/argocd
        property: oidc_client_secret

# ConfigMap: Referenz ohne Secret-Name
oidc.config: |
  name: Authentik
  issuer: https://auth.apps.k3s.stabify.de/application/o/argo-cd/
  clientID: $oidc.authentik.clientID
  clientSecret: $oidc.authentik.clientSecret
  requestedScopes: ["openid", "profile", "email", "groups"]

Option 2: Separates Secret mit korrekten Labels

Vorteile:

• Saubere Trennung
• Keine Konflikte mit Haupt-Secret

Nachteile:

• Erfordert korrekte Labelung
• Timing-Probleme können weiterhin auftreten

Implementierung:

# ExternalSecret: Labels setzen
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: argocd-oidc-secret-source
  namespace: argocd
spec:
  refreshInterval: 1m
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: argocd-oidc-secret
    creationPolicy: Owner
    template:
      metadata:
        labels:
          app.kubernetes.io/part-of: argocd  # <-- Wichtig!
      type: Opaque
  data:
    - secretKey: clientID
      remoteRef:
        key: secret/apps/argocd
        property: oidc_client_id
    - secretKey: clientSecret
      remoteRef:
        key: secret/apps/argocd
        property: oidc_client_secret

Option 3: Init-Container oder Helm Pre-Hook (Erweitert)

Vorteile:

• Garantiert, dass Secret vor ArgoCD Start existiert
• Volle Kontrolle

Nachteile:

• Komplexer
• Erfordert zusätzliche Ressourcen

Aktuelle Lösung (Temporary)

Bis das Secret-Referenz-Problem gelöst ist, nutzen wir hardcoded Credentials:

⚠️ WICHTIG: Dies ist NICHT sicher für Production! Nur als Workaround!

Die hardcodierten Werte sollten:

1. Nur in Git Commits mit verschlüsselten Secrets gespeichert werden
2. Oder via Sealed Secrets / SOPS verschlüsselt werden
3. Oder komplett aus Git entfernt werden (nur via CI/CD gesetzt)

Option 4: Dex verwenden (Empfohlen für ArgoCD!)

Vorteile:

• Dex ist der "native" Weg für ArgoCD
• Secret-Referenzen funktionieren zuverlässiger
• Dex nutzt standardmäßig argocd-secret mit Keys wie dex.authentik.clientID
• Authentik empfiehlt Dex für ArgoCD-Integration
• Mehr Flexibilität (mehrere Connectors möglich)

Nachteile:

• Zusätzliche Layer (Dex als Middleware)
• Etwas komplexere Konfiguration

Implementierung:

# ExternalSecret: Keys ins argocd-secret schreiben (Dex-Format)
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: argocd-dex-secret-source
  namespace: argocd
spec:
  refreshInterval: 1m
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: argocd-secret  # <-- Haupt-Secret
    creationPolicy: Merge  # <-- Merge, nicht Owner!
  data:
    - secretKey: dex.authentik.clientID
      remoteRef:
        key: secret/apps/argocd
        property: oidc_client_id
    - secretKey: dex.authentik.clientSecret
      remoteRef:
        key: secret/apps/argocd
        property: oidc_client_secret

# ConfigMap: Dex-Config statt oidc.config
dex.config: |
  connectors:
  - type: oidc
    id: authentik
    name: Authentik
    config:
      issuer: https://auth.apps.k3s.stabify.de/application/o/argo-cd/
      clientID: $dex.authentik.clientID
      clientSecret: $dex.authentik.clientSecret
      scopes:
        - openid
        - profile
        - email
        - groups
      # Optional: Claim-Mapping
      claimMapping:
        groups: groups
        email: email
        name: name

Wichtig: Bei Dex wird der clientID im Secret auch referenziert (nicht hardcoded), da Dex Secret-Referenzen besser unterstützt!

Nächste Schritte

1. ⭐ Option 4 testen: Dex-Konfiguration (empfohlen!)
2. Falls Option 4 nicht funktioniert: Option 1 (Nutze argocd-secret mit Merge Policy für oidc.config)
3. Falls Option 1 nicht funktioniert: Option 2 mit korrekten Labels
4. Falls beides nicht funktioniert: Option 3 (Init-Container)
5. Langfristig: Warte auf Fix in ArgoCD oder verwende Sealed Secrets

Referenzen

• GitHub Issue #18576
• ArgoCD User Management Docs
• External Secrets Operator Docs