ssh2_auth_agent — Funktion · PHP-Referenz

Signatur

ssh2_auth_agent(resource $session, string $username): bool

Beschreibung

ssh2_auth_agent() ermöglicht die Authentifizierung gegenüber einem SSH-Server, indem der lokal laufende SSH-Agent genutzt wird. Der SSH-Agent verwaltet private Schlüssel im Speicher und stellt sie für Authentifizierungsvorgänge bereit, ohne dass das PHP-Skript direkt Zugang zu den privaten Schlüsseldateien benötigt.

Diese Methode ist besonders nützreich in Umgebungen, in denen private Schlüssel nicht direkt im Dateisystem verfügbar sein sollen oder wenn ein Forwarding-Szenario (Agent Forwarding) eingesetzt wird. Voraussetzung ist, dass die PHP-Erweiterung libssh2 mit Agent-Unterstützung kompiliert wurde und auf dem System ein SSH-Agent läuft (erkennbar an der Umgebungsvariablen SSH_AUTH_SOCK).

Die Funktion gehört zur ssh2-PECL-Erweiterung. Sie gibt true zurück, wenn die Authentifizierung erfolgreich war, andernfalls false. Im Fehlerfall kann ein E_WARNING ausgelöst werden.

Erfordert eine aktive SSH-Verbindung (erstellt mit ssh2_connect()).
Der SSH-Agent muss laufen und den passenden Schlüssel zum Ziel-Server enthalten.
Auf Windows-Systemen ist diese Funktion in der Regel nicht verfügbar.

Parameter

Name	Typ	Default	Beschreibung
$session Pflicht	resource		Eine SSH-Verbindungs-Ressource, wie sie von `ssh2_connect()` zurückgegeben wird.
$username Pflicht	string		Der Benutzername, mit dem die Authentifizierung auf dem SSH-Server durchgeführt werden soll.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Authentifizierung über den SSH-Agenten erfolgreich war, andernfalls false. Bei einem Fehler kann zusätzlich eine E_WARNING-Meldung ausgelöst werden.

Beispiele

Einfache SSH-Verbindung mit Agent-Authentifizierung

<?php
// Verbindung zum SSH-Server herstellen
$session = ssh2_connect('example.com', 22);

if ($session === false) {
    die('Verbindung zum SSH-Server fehlgeschlagen.');
}

// Authentifizierung über den lokalen SSH-Agenten
if (!ssh2_auth_agent($session, 'deploy')) {
    die('Agent-Authentifizierung fehlgeschlagen.');
}

echo 'Erfolgreich authentifiziert via SSH-Agent!' . PHP_EOL;

// Beispiel: Befehl ausführen
$stream = ssh2_exec($session, 'uptime');
stream_set_blocking($stream, true);
echo stream_get_contents($stream);
fclose($stream);

Erfolgreich authentifiziert via SSH-Agent! 14:32:01 up 10 days, 3:14, 1 user, load average: 0.01, 0.05, 0.09

Fallback auf Passwort-Authentifizierung bei fehlschlagendem Agenten

<?php
$host = 'example.com';
$user = 'admin';
$password = 'geheimes_passwort';

$session = ssh2_connect($host, 22);
if ($session === false) {
    die('SSH-Verbindung fehlgeschlagen.');
}

// Zunächst Agent-Authentifizierung versuchen
if (@ssh2_auth_agent($session, $user)) {
    echo 'Agent-Authentifizierung erfolgreich.' . PHP_EOL;
} elseif (ssh2_auth_password($session, $user, $password)) {
    echo 'Passwort-Authentifizierung als Fallback erfolgreich.' . PHP_EOL;
} else {
    die('Alle Authentifizierungsmethoden fehlgeschlagen.');
}

Agent-Authentifizierung erfolgreich.

// Wichtig · Fallstricke

Verfügbarkeit: ssh2_auth_agent() ist nur verfügbar, wenn die libssh2-Bibliothek mit Agent-Unterstützung kompiliert wurde. Auf Windows-Systemen ist diese Funktion meist nicht nutzbar, da ssh-agent dort nicht nativ unterstützt wird.

SSH_AUTH_SOCK: Die Funktion erfordert, dass die Umgebungsvariable SSH_AUTH_SOCK gesetzt ist und auf den Unix-Socket des laufenden SSH-Agenten zeigt. Wird PHP über einen Webserver (z. B. Apache oder Nginx) ausgeführt, ist diese Variable häufig nicht verfügbar, da der Webserver-Prozess sie nicht erbt.

Sicherheit: Die Agent-Authentifizierung ist sicherer als Passwort-Authentifizierung, da der private Schlüssel den Arbeitsspeicher des Agenten nie verlässt. Achten Sie dennoch auf Agent-Forwarding: Wird es über nicht vertrauenswürdige Server aktiviert, können diese den Agenten für eigene Verbindungen missbrauchen.

Siehe auch

ssh2_connect ssh2_auth_password ssh2_auth_pubkey_file ssh2_auth_none ssh2_exec