Private Registry Authentifizierung: Credential Helper statt Klartext-Passwoerter

1. Wie docker login Zugangsdaten standardmaessig speichert

Nach einem docker login gegen eine private Registry legt Docker die Zugangsdaten in der Datei ~/.docker/config.json ab, in einem Abschnitt namens auths, gegliedert nach Registry-Hostname. Ohne weitere Konfiguration werden Benutzername und Passwort dort standardmaessig lediglich Base64-kodiert gespeichert, was auf den ersten Blick nach Verschluesselung aussieht, tatsaechlich aber trivial umkehrbar ist und keinerlei kryptografischen Schutz bietet. Jeder Prozess und jeder Nutzer mit Lesezugriff auf diese Datei kann die Zugangsdaten in Sekunden decodieren.

Besonders kritisch wird das bei geteilten Entwicklungsmaschinen, CI-Runnern mit mehreren parallelen Jobs oder Backup-Systemen, die das Home-Verzeichnis eines Nutzers sichern, denn die config.json landet dann potenziell in Backups, Snapshots oder wird von anderen Prozessen auf demselben System eingesehen. Auf einem persoenlichen Notebook mag das Risiko ueberschaubar sein, in einer produktiven CI/CD-Umgebung mit vielen Beteiligten und automatisierten Prozessen ist Base64-Kodierung als einziger Schutzmechanismus fuer Registry-Credentials klar unzureichend.

2. Wie Credential Helper das Problem loesen

Ein Credential Helper ist ein eigenstaendiges, ausfuehrbares Programm, das Docker anweist, Zugangsdaten nicht mehr direkt in der config.json zu speichern, sondern an einen sicheren, betriebssystemeigenen oder cloud-spezifischen Speicher zu delegieren, etwa den macOS Keychain, den Windows Credential Manager, den Linux Secret Service via libsecret, oder cloud-spezifische Mechanismen wie IAM-Rollen bei AWS. Docker kommuniziert dabei ueber ein simples, standardisiertes Stdin/Stdout-Protokoll mit dem Helper-Programm, das Befehle wie store, get und erase implementiert.

Konfiguriert wird ein Credential Helper ueber den Schluessel credsStore oder credHelpers in der ~/.docker/config.json. credsStore setzt einen globalen Helper fuer alle Registries, waehrend credHelpers eine feingranulare Zuordnung pro Registry-Hostname erlaubt, was etwa sinnvoll ist, wenn gleichzeitig eine AWS-ECR-Registry ueber IAM-Credentials und eine Docker-Hub-Anmeldung ueber den lokalen OS-Keystore authentifiziert werden sollen.

# Credential Helper Binary muss im PATH liegen, z.B. docker-credential-osxkeychain
which docker-credential-osxkeychain

# ~/.docker/config.json manuell oder per docker login konfigurieren
cat ~/.docker/config.json
# {
#   "credsStore": "osxkeychain"
# }

3. Cloud-spezifische Credential Helper einrichten

Fuer die grossen Cloud-Registries existieren dedizierte Credential Helper, die zusaetzlich temporaere, automatisch rotierende Zugangs-Tokens ausstellen koennen, statt eines dauerhaften Passworts. Fuer AWS ECR ist das docker-credential-ecr-login, das die vorhandene AWS-Konfiguration, etwa eine IAM-Rolle oder ein Profil aus ~/.aws/credentials, nutzt, um bei jedem docker pull oder docker push automatisch ein kurzlebiges Authentifizierungs-Token anzufordern, ohne dass jemals ein statisches Passwort in irgendeiner Konfigurationsdatei landet.

Aehnliche Helper existieren fuer Google Artifact Registry mit docker-credential-gcr sowie fuer Azure Container Registry mit docker-credential-acr, jeweils eng verzahnt mit der cloud-eigenen Identitaets- und Zugriffsverwaltung. Der grosse Vorteil gegenueber einem klassischen docker login mit Langzeit-Passwort ist, dass die eigentlichen Zugangsdaten niemals dauerhaft auf der Festplatte landen und bei kompromittierter Maschine automatisch mit dem naechsten Token-Refresh ablaufen, statt manuell rotiert werden zu muessen.

# ECR Credential Helper installieren und konfigurieren
brew install docker-credential-ecr-login   # oder ueber Paketmanager der Distribution

cat ~/.docker/config.json
# {
#   "credHelpers": {
#     "123456789012.dkr.ecr.eu-central-1.amazonaws.com": "ecr-login"
#   }
# }

# Kein docker login noetig, IAM-Rolle oder Profil authentifiziert automatisch
docker pull 123456789012.dkr.ecr.eu-central-1.amazonaws.com/mironsoft/app:latest

4. Credential Helper unter Linux ohne Desktop-Umgebung

Auf Linux-Servern und CI-Runnern ohne grafische Desktop-Umgebung steht der bequeme libsecret-basierte Helper oft nicht zur Verfuegung, da er auf einen laufenden Secret-Service-Daemon wie GNOME Keyring angewiesen ist. Als Alternative bietet sich docker-credential-pass an, das auf dem etablierten Unix-Tool pass basiert, welches Zugangsdaten GPG-verschluesselt in einem einfachen Dateisystem-Baum ablegt und damit auch auf headless Servern ohne grafische Oberflaeche funktioniert.

Die Einrichtung erfordert einen initialisierten GPG-Schluessel und einen initialisierten pass-Store, danach verhaelt sich docker-credential-pass wie jeder andere Credential Helper und wird ueber credsStore in der config.json aktiviert. Wichtig ist, dass der GPG-Schlussel selbst wiederum sicher verwahrt werden muss, etwa in einem Hardware-Token oder einem dedizierten Secrets-Management-System, da er letztlich den Wurzel-Schutz fuer alle gespeicherten Registry-Credentials darstellt.

# docker-credential-pass unter Linux einrichten
gpg --gen-key
pass init "docker-credential-key-id"

echo '{"credsStore": "pass"}' > ~/.docker/config.json
docker login registry.mironsoft.internal

5. Secrets sicher an docker login in CI-Umgebungen uebergeben

In CI-Pipelines ist ein interaktives docker login mit Passwort-Prompt nicht praktikabel, weshalb Zugangsdaten meist per --password-stdin uebergeben werden, um zu vermeiden, dass das Passwort als Klartext-Argument im Prozess-Listing oder in Shell-Historien sichtbar wird. Ein haeufiger Fehler ist die Verwendung des veralteten --password Flags mit direktem Wert, denn dieser landet dadurch potenziell in Job-Logs, im Bash-History-File des Runners oder ist ueber ps aux fuer andere Prozesse auf demselben System sichtbar.

Die CI-eigenen Secret-Mechanismen wie GitHub Actions Secrets oder GitLab CI/CD-Variablen sorgen dafuer, dass der Wert selbst maskiert im Log erscheint und nicht im Klartext im Workflow- oder Pipeline-File hinterlegt werden muss. In Kombination mit --password-stdin wird das Passwort so niemals als Kommandozeilenargument sichtbar, sondern ausschliesslich ueber eine sichere Pipe an docker login uebergeben.

# Sicheres Login in CI ueber Stdin statt Kommandozeilenargument
echo "$REGISTRY_PASSWORD" | docker login ghcr.io -u "$REGISTRY_USER" --password-stdin

# Niemals so (Passwort landet in Prozess-Listing und History):
# docker login ghcr.io -u user --password "$REGISTRY_PASSWORD"

6. Credential Helper in Compose- und Kubernetes-Umgebungen

docker compose nutzt beim Pullen von Images dieselbe ~/.docker/config.json wie die Docker CLI, sodass ein einmal konfigurierter Credential Helper automatisch auch fuer compose pull und compose build mit privaten Base-Images greift, ohne separate Konfiguration. In Kubernetes-Umgebungen hingegen kommt kein Credential Helper im eigentlichen Sinne zum Einsatz, sondern imagePullSecrets, die Zugangsdaten als Kubernetes-Secret vom Typ kubernetes.io/dockerconfigjson im Cluster hinterlegen und einem Pod oder Service Account zugeordnet werden.

In Cloud-Kubernetes-Angeboten wie EKS, GKE oder AKS uebernehmen jedoch haeufig Node-seitige Credential-Provider, etwa der ECR Credential Provider fuer EKS, aehnliche Aufgaben wie ein lokaler Credential Helper: Sie stellen automatisch kurzlebige Tokens fuer die jeweilige Cloud-Registry bereit, sodass kein statisches imagePullSecret gepflegt werden muss und Zugangsdaten analog zum lokalen ecr-login Helper regelmaessig automatisch rotieren.

7. Least-Privilege-Prinzip bei Registry-Zugangsdaten

Unabhaengig vom konkreten Speichermechanismus gilt fuer Registry-Zugangsdaten dasselbe Least-Privilege-Prinzip wie fuer jede andere Form von Credentials: Ein CI-Job, der nur Images pullen muss, sollte niemals mit einem Token ausgestattet werden, das auch Push- oder gar Loeschrechte besitzt. Viele Registries erlauben die Erstellung feingranularer Access-Tokens oder Service-Accounts mit auf einzelne Repositories und Operationen beschraenkten Berechtigungen, statt eines generischen Admin-Zugangs fuer alle automatisierten Prozesse.

Besonders bei geteilten CI-Umgebungen mit vielen Projekten empfiehlt es sich, pro Projekt oder sogar pro Pipeline-Stufe eigene, eng begrenzte Zugangsdaten zu vergeben, sodass ein kompromittiertes Token im schlimmsten Fall nur ein einzelnes Repository betrifft und nicht die gesamte Registry-Infrastruktur gefaehrdet. Diese Segmentierung erhoeht zwar den initialen Konfigurationsaufwand, reduziert aber den moeglichen Schaden im Falle eines Sicherheitsvorfalls erheblich.

8. Token-Rotation und Audit-Faehigkeit

Statische, langlebige Passwoerter, wie sie bei einem klassischen docker login ohne Credential Helper entstehen, muessen manuell rotiert werden, was in der Praxis haeufig vernachlaessigt wird, sobald ein Zugang einmal funktioniert. Cloud-Credential-Helper wie docker-credential-ecr-login umgehen dieses Problem strukturell, indem sie ohnehin nur kurzlebige Tokens ausstellen, typischerweise mit einer Gueltigkeit von wenigen Stunden, wodurch ein gestohlenes Token von selbst nutzlos wird, ohne dass ein Mensch aktiv eingreifen muss.

Zusaetzlich bieten viele Registries detaillierte Audit-Logs, die jeden Pull und Push mit dem verwendeten Zugangstoken protokollieren, was bei feingranularen, pro Projekt vergebenen Credentials eine praezise Nachvollziehbarkeit erlaubt, welcher Dienst oder welche Pipeline wann auf welches Image zugegriffen hat. Bei einem einzigen, geteilten Admin-Zugang fuer alle Systeme geht diese Nachvollziehbarkeit weitgehend verloren, da sich einzelne Aktionen nicht mehr eindeutig einer Quelle zuordnen lassen.

9. Best Practices und Methodenvergleich

Als praktikable Grundregel gilt: Auf Entwickler-Notebooks sollte immer ein betriebssystemeigener Credential Helper wie osxkeychain, wincred oder pass aktiviert sein, niemals die reine Base64-Speicherung in der config.json. In CI-Pipelines sollten, wo verfuegbar, cloud-native Credential Provider mit kurzlebigen Tokens den Vorzug vor statischen Passwoertern erhalten, und wo das nicht moeglich ist, zumindest --password-stdin in Kombination mit maskierten CI-Secrets verwendet werden.

Die folgende Tabelle vergleicht die vorgestellten Mechanismen hinsichtlich Sicherheit, Einsatzort und Wartungsaufwand, um die passende Wahl fuer die eigene Umgebung zu erleichtern.

10. Zusammenfassung

11. FAQ: Registry-Authentifizierung: Das Wichtigste auf einen Blick