Sonderzeichen im Datenbank-Passwort

Warum @, :, / oder # im Passwort die DATABASE_URL zerbrechen und wie Sie das Passwort richtig kodieren – für Symfony, Laravel, Doctrine und Docker.

Viele Frameworks erwarten die Zugangsdaten zur Datenbank als eine einzige Zeichenkette, etwa in DATABASE_URL. Das ist praktisch, solange das Passwort nur aus Buchstaben und Ziffern besteht. Sobald ein @, :, / oder # darin vorkommt, liest der Parser die URL anders, als Sie es gemeint haben – und die Fehlermeldung verrät selten, dass das Passwort schuld ist.

Die Lösung ist einfach: Das Passwort wird URL-kodiert, bevor es in die Adresse kommt. Diese Anleitung zeigt, welche Zeichen betroffen sind, welche Kodierung die richtige ist und worauf Sie in Symfony, Laravel und Docker Compose zusätzlich achten müssen.

So ist eine Verbindungs-URL aufgebaut

Eine Verbindungs-URL folgt demselben Schema wie jede andere URL:

schema://benutzer:passwort@host:port/datenbank?parameter=wert

mysql://app:[email protected]:3306/shop?serverVersion=8.0&charset=utf8mb4
postgresql://app:geheim@db:5432/shop?serverVersion=16&charset=utf8

Der Teil vor dem @ heißt in der URL-Spezifikation RFC 3986 „userinfo“. Der Parser erkennt die einzelnen Bestandteile nur an ihren Trennzeichen: :// beendet das Schema, : trennt Benutzer und Passwort, @ trennt die Zugangsdaten vom Host, / leitet den Datenbanknamen ein, ? die Parameter und # ein Fragment. Steht eines dieser Zeichen im Passwort, verschiebt sich die Zerlegung.

Welche Zeichen Probleme machen

Nach RFC 3986 dürfen in der userinfo nur Buchstaben, Ziffern, - . _ ~, einige weitere Sonderzeichen und %-Folgen unkodiert stehen. Besonders kritisch sind:

  • @ – trennt die Zugangsdaten vom Host. PHPs parse_url() nimmt das letzte @, andere Parser das erste. Verlassen sollten Sie sich auf keines von beiden.
  • /, ? und # – beenden den Host-Teil vorzeitig. Bei mysql://app:ab/cd@db/shop liefert parse_url() nur noch false, Doctrine meldet dann Malformed parameter "url".
  • : – trennt Benutzername und Passwort und, nach dem Host, den Port.
  • % – leitet eine Kodierung ein. Ein Passwort wie 50%Rabatt wird beim Dekodieren verfälscht oder als ungültig abgelehnt.
  • Leerzeichen, Anführungszeichen, $ und \ – sind für die URL selbst nicht das Hauptproblem, wohl aber für die .env-Datei oder die Shell, in der die URL steht.

Typische Symptome sind „Access denied“, obwohl das Passwort stimmt, ein unbekannter Host, ein falscher Port oder eine Meldung, die URL sei fehlerhaft.

Richtig kodieren: rawurlencode statt urlencode

Beim Kodieren wird jedes problematische Zeichen durch % und seinen Byte-Wert in Hexadezimal ersetzt, aus @ wird %40. Am sichersten ist es, alles außer Buchstaben, Ziffern und - . _ ~ zu kodieren. Genau das macht PHPs rawurlencode(). Den Benutzernamen kodieren Sie auf dieselbe Weise, falls er Sonderzeichen enthält.

Passwortrawurlencode (richtig)urlencode
p@ss:w/rd#1p%40ss%3Aw%2Frd%231p%40ss%3Aw%2Frd%231
my pass+wordmy%20pass%2Bwordmy+pass%2Bword
50%Rabatt!50%25Rabatt%2150%25Rabatt%21
S3cr3t$KeyS3cr3t%24KeyS3cr3t%24Key
GrüßeGr%C3%BC%C3%9FeGr%C3%BC%C3%9Fe

Der Unterschied liegt beim Leerzeichen: urlencode() stammt aus der Welt der Formulardaten und macht daraus ein +. Doctrine und Laravel dekodieren die Bestandteile der URL aber mit rawurldecode(), und das lässt ein + unverändert. Aus my+pass%2Bword wird dann my+pass+word – ein falsches Passwort.

Sie können die Kodierung auf der Kommandozeile prüfen. Die einfachen Anführungszeichen verhindern, dass die Shell $ oder # selbst auswertet:

php -r 'echo rawurlencode($argv[1]), "\n";' 'p@ss:w/rd#1'
p%40ss%3Aw%2Frd%231

Ohne Kommandozeile geht es mit dem URL-Encoder & Decoder: Der Modus „Kodieren“ arbeitet standardmäßig wie rawurlencode(), und im Reiter „Verbindungs-URL“ setzen Sie Benutzer, Passwort, Host, Port und Datenbank zu einer fertigen DATABASE_URL zusammen. Die Eingaben verlassen dabei Ihren Browser nicht. JavaScripts encodeURIComponent() lässt einige Zeichen wie ! oder * unkodiert, die in der userinfo zwar erlaubt sind, bei weiterer Verarbeitung aber stören können.

Noch einfacher: Passwörter ohne Stolperfallen

Wenn Sie das Passwort selbst festlegen, können Sie das Problem von vornherein vermeiden. Lange Passwörter aus Buchstaben und Ziffern sind genauso sicher wie kürzere mit Sonderzeichen: 32 zufällige Zeichen aus Groß- und Kleinbuchstaben und Ziffern ergeben rund 190 Bit. Der Passwort-Generator erzeugt solche Passwörter, wenn Sie die Sonderzeichen abschalten. So entfallen Kodierung, Anführungszeichen und verdoppelte Dollarzeichen – und die URL bleibt lesbar.

Gibt ein Hoster das Passwort vor, ist die Kodierung der verlässliche Weg.

Symfony und Doctrine

In Symfony steht die Adresse in der Regel in .env oder, für lokale Zugangsdaten, in .env.local. Doctrine zerlegt die URL und dekodiert jeden Bestandteil, Sie tragen also die kodierte Form ein:

DATABASE_URL='mysql://app:p%40ss%3Aw%2Frd%[email protected]:3306/shop?serverVersion=8.0&charset=utf8mb4'

Zwei Stellen verdienen Aufmerksamkeit:

  • Anführungszeichen in der .env: Ohne Anführungszeichen und in doppelten Anführungszeichen ersetzt Symfony $NAME und ${NAME} durch Umgebungsvariablen. Aus "mysql://app:S3cr3t$Key@…" wird stillschweigend mysql://app:S3cr3t@…, weil es keine Variable Key gibt. Einfache Anführungszeichen übernehmen den Wert wörtlich. Eine vollständig kodierte URL enthält ohnehin kein $ mehr, weil daraus %24 wird.
  • Der Prozessor resolve:: In vielen Projekten steht in config/packages/doctrine.yaml die Zeile url: '%env(resolve:DATABASE_URL)%'. resolve: ersetzt %name% durch Container-Parameter. In p%40ss%3Aw… sieht Symfony dann einen Parameter 40ss und bricht mit „You have requested a non-existent parameter“ ab. Brauchen Sie resolve: nicht, entfernen Sie es. Andernfalls schreiben Sie jedes % in der .env doppelt, also p%%40ss%%3Aw….

Alternativ lassen Sie das Passwort ganz aus der URL heraus und übergeben es getrennt. Doctrine ergänzt die Werte aus der URL um die übrigen Optionen, sodass keine Kodierung nötig ist:

# .env.local
DATABASE_URL='mysql://[email protected]:3306/shop?serverVersion=8.0&charset=utf8mb4'
DATABASE_PASSWORD='p@ss:w/rd#1'

# config/packages/doctrine.yaml
doctrine:
    dbal:
        url: '%env(resolve:DATABASE_URL)%'
        password: '%env(DATABASE_PASSWORD)%'

Wichtig: Enthält die URL doch ein Passwort, hat dieses Vorrang vor password.

Laravel

Laravel kennt beide Wege. Üblich sind einzelne Variablen wie DB_HOST, DB_USERNAME und DB_PASSWORD. Dort wird nichts URL-kodiert, das Passwort steht im Klartext:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=shop
DB_USERNAME=app
DB_PASSWORD='p@ss:w/rd#1'

Setzen Sie das Passwort in einfache Anführungszeichen, sobald es Leerzeichen, #, $ oder Anführungszeichen enthält. In doppelten Anführungszeichen ersetzt die .env-Bibliothek von Laravel Ausdrücke wie ${NAME}.

Daneben gibt es die Variable DB_URL (in älteren Versionen DATABASE_URL). Ist sie gesetzt, zerlegt Laravel sie, dekodiert die %-Folgen und lässt ihre Bestandteile Vorrang vor den einzelnen Variablen haben. Für sie gelten dieselben Regeln wie oben: Passwort mit rawurlencode() kodieren. Nach einer Änderung an der .env löschen Sie einen eventuell vorhandenen Konfigurations-Cache mit php artisan config:clear, sonst arbeitet die Anwendung weiter mit den alten Werten.

Docker und Docker Compose

Docker Compose wertet in compose.yaml selbst $ aus, um Variablen einzusetzen. Ein wörtliches Dollarzeichen schreiben Sie dort als $$. Das betrifft vor allem Passwörter, die unkodiert übergeben werden, etwa an das Datenbank-Image:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: "S3cr3t$$Key"
      POSTGRES_DB: shop
  app:
    environment:
      DATABASE_URL: "postgresql://app:S3cr3t%24Key@db:5432/shop?serverVersion=16&charset=utf8"

Der Datenbank-Container erhält das Passwort im Klartext (S3cr3t$Key), die Anwendung dieselbe Zeichenfolge in kodierter Form. Beide müssen zum selben Passwort führen. Halten Sie die Werte in einer .env-Datei neben der compose.yaml, werden Werte in einfachen Anführungszeichen dort nicht interpoliert. Beachten Sie außerdem: Die Datenbank-Images übernehmen POSTGRES_PASSWORD und Co. nur beim ersten Start mit leerem Datenverzeichnis. Ein später geändertes Passwort ändern Sie in der Datenbank selbst.

Kurz zusammengefasst

  • Passwort (und gegebenenfalls Benutzernamen) mit rawurlencode() kodieren, nicht mit urlencode().
  • In .env-Dateien einfache Anführungszeichen verwenden, damit $ nicht interpoliert wird.
  • In Symfony bei %env(resolve:…)% jedes % verdoppeln oder resolve: weglassen.
  • In compose.yaml ein wörtliches $ als $$ schreiben.
  • Wo möglich: Passwort als eigene Variable statt in der URL – oder gleich ein langes Passwort ohne Sonderzeichen.

Tools zum Thema

Weitere Anleitungen