open-how2 – Entdecke. Verstehe. Nutze.
Veröffentlicht am
• How2-Tipps

Was ist der `token_auth` bei Matomo?

Autor
Was ist der `token_auth` bei Matomo?

Der token_auth ist ein geheimer API-Schlüssel, den Matomo jedem Benutzer zuordnet. Er dient zur Authentifizierung bei automatisierten Anfragen an Matomo — z. B. beim Import von Logdateien, bei API-Abfragen oder beim automatischen Reporting.

Du kannst ihn dir vorstellen wie ein Passwort für die API-Schnittstelle. Jede Anfrage mit diesem Token gilt so, als würde der betreffende Benutzer in Matomo eingeloggt sein.

Wo finde ich den token_auth?

Variante 1: Direkt über die Matomo-Weboberfläche

  1. Melde dich in Matomo als Administrator oder als Benutzer mit Import-Rechten an.

  2. Klicke oben rechts auf dein Benutzer-Symbol → „Einstellungen“ (⚙️).

  3. Gehe zu „Sicherheit“ → „API-Authentifizierung“.

  4. Dort findest du einen Eintrag wie:

    Ihr Authentifizierungs-Token (token_auth):
9f8a1b2c3d4e5f6a7b8c9d0e12345678

    Diesen Wert kopieren und sicher aufbewahren — er gewährt vollen Zugriff im Namen deines Accounts!

  5. Wenn du möchtest, kannst du dort auch einen neuen Token regenerieren, z. B. wenn du glaubst, der alte wurde kompromittiert.

Warum brauche ich ihn für Log Analytics?

Das Log-Import-Skript (import_logs.py) kommuniziert über die Matomo HTTP API mit deiner Matomo-Installation. Es sendet für jede erkannte Logzeile ein Tracking-Event an Matomo — genau so, als hätte ein Browser das Tracking-Script ausgeführt.

Damit Matomo diese Requests akzeptiert, muss sich das Skript authentifizieren — und dafür braucht es den token_auth.

Ein Beispielbefehl:

python3 /pfad/zu/import_logs.py \
  --url=https://analytics.example.com/matomo \
  --idsite=1 \
  --token-auth=9f8a1b2c3d4e5f6a7b8c9d0e12345678 \
  /var/log/apache2/access.log

Ohne gültigen Token würde Matomo alle eingehenden Tracking-Requests vom Import-Skript ablehnen.

Warum „unsichere Verbindungen“ erwähnen?

Standardmäßig lehnt Matomo API-Zugriffe über unverschlüsselte HTTP-Verbindungen (also ohne HTTPS) ab. Das ist ein Sicherheitsfeature, um zu verhindern, dass Token im Klartext durchs Netz gehen.

Wenn du das Import-Skript auf demselben Server betreibst (z. B. localhost), ist das kein Problem — du kannst HTTPS oder HTTP verwenden. Wenn du das Skript auf einem anderen Server nutzt, musst du HTTPS verwenden, sonst riskierst du, dass der Token abgefangen wird.

Es gibt aber Ausnahmen:

  • In internen Netzwerken (z. B. 192.168.x.x oder 10.x.x.x) kann es vorkommen, dass HTTPS noch nicht eingerichtet ist.

  • Dann muss das Skript Matomo mitteilen, dass unsichere Verbindungen erlaubt sind — über den Parameter:

    --accept-invalid-ssl

    oder bei älteren Versionen mit:

    --no-ssl-check

Dieser Schalter deaktiviert die SSL-Zertifikatsprüfung. Das ist nützlich bei internen Tests oder selbstsignierten Zertifikaten – sollte aber niemals dauerhaft im Internetbetrieb verwendet werden.

Best Practices

  1. Immer HTTPS verwenden, auch intern (z. B. mit Let’s Encrypt oder selbstsignierten Zertifikaten).
  2. Token nur für den Import-Benutzer erstellen – kein Admin-Token verwenden!

  • Du kannst z. B. einen Benutzer „logimporter“ anlegen, der nur Rechte auf eine bestimmte Website (idsite) hat.

    1. Token niemals in Logs, Skripten oder öffentlich sichtbaren Cronjobs im Klartext speichern.

  • Besser: in einer separaten Konfigurationsdatei mit restriktiven Berechtigungen (chmod 600).

    1. Wenn du das Skript regelmäßig ausführst, prüfe, dass das Token aktuell ist (nicht nach einem Reset des Passworts abgelaufen).
    2. Wenn du in einem internen Netz arbeitest und HTTPS nicht verfügbar ist:

  • Verwende --accept-invalid-ssl, aber nur in einer geschützten Umgebung.

  • Stelle sicher, dass das Netz physisch oder per VPN abgesichert ist.

Beispiel mit Token und SSL-Schutz

Ein vollständiger, sicherer Import-Befehl sieht so aus:

/usr/bin/python3 /opt/matomo/misc/log-analytics/import_logs.py \
  --url=https://analytics.meinserver.de/matomo \
  --idsite=7 \
  --token-auth=$(cat /etc/matomo/token_auth) \
  --recorders=4 \
  --enable-http-errors \
  --enable-http-redirects \
  /var/log/nginx/access.log

Der Token liegt dabei in /etc/matomo/token_auth, die nur root lesen darf. Das Skript sendet die Daten sicher über HTTPS an Matomo und verwendet den Token für die Authentifizierung.

Ähnliche Beiträge