Web-ssh

Installer WebSSH avec reverse proxy Apache

Cette page décrit comment installer WebSSH dans un environnement isolé, le lancer en tant que service systemd, et le rendre accessible via Apache en HTTPS avec prise en charge des WebSocket.

1. Installation dans un environnement virtuel

EN général je travaille avec un user dédié, ici ce serait webssh ou un user d'administration admin. Dans la suite on considère admin.

Créer un environnement Python dédié :

python3 -m venv ~/sources/webssh-env
source ~/sources/webssh-env/bin/activate
pip install webssh

2. Script de lancement

Créer un script start-webssh.sh :

#!/bin/bash
source /home/admin/sources/webssh-env/bin/activate
exec wssh --address=127.0.0.1 --port=8888

Rendre le script exécutable :

chmod +x ~/sources/webssh-env/start-webssh.sh

3. Lancer WebSSH en tant que service

Voir créer un service systemd personnalisé pour créer un fichier webssh.service et activer le démarrage automatique.

4. Configuration Apache en reverse proxy

Dans la section HTTPS du VirtualHost :

Define WebSshURL "/webssh/"

<Location ${WebSshURL}>
    ProxyPreserveHost On
    ProxyPass http://localhost:8888/
    ProxyPassReverse http://localhost:8888/
</Location>

# Support WebSocket
ProxyPassMatch ^/webssh/ws$ ws://localhost:8888/ws

# Support WebSocket via mod_rewrite
RewriteEngine On
RewriteCond %{REQUEST_URI} ^/webssh/ws$
RewriteCond %{QUERY_STRING} (.*)
RewriteRule ^/webssh/ws$ ws://localhost:8888/ws?%1 [P,L]

Modules requis :

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_wstunnel

Redémarrer Apache :

sudo systemctl restart apache2

5. Accès sécurisé

L’interface WebSSH est maintenant accessible via https://monserveur/webssh/. L’authentification SSH reste gérée par WebSSH. Une protection Apache (BasicAuth, IP, etc.) peut être ajoutée en amont si nécessaire.

Configuration OTP sur WebSSH

Objectif

Configurer une authentification TOTP (Time-based One-Time Password) sur WebSSH, par couple hôte/utilisateur, avec provisioning via QR code et vérification côté serveur.

Prérequis

• WebSSH installé et fonctionnel
• Python 3.11+ avec les modules pyotp, qrcode, argparse
• Accès au fichier totp_secrets.json dans le bon répertoire
• Serveur SSH distant accessible et configuré avec shell interactif

Provisioning OTP

Script de génération

Utiliser un script Python nommé build-otp-key.py :

#!/home/admin/sources/webssh-env/bin/python3
import pyotp
import qrcode
import argparse

# Parse command-line arguments
parser = argparse.ArgumentParser(description="Provision TOTP key for WebSSH")
parser.add_argument("--host", required=True, help="Hostname of the target SSH server")
parser.add_argument("--user", required=True, help="SSH username to provision")
args = parser.parse_args()

host = args.host
user = args.user

print("Provisioning TOTP for {}@{}".format(user, host))
input("Press Enter to continue or Ctrl+C to abort...")

# Generate TOTP secret
secret = pyotp.random_base32()
print("\nSecret: {}".format(secret))

# Create provisioning URI
label = "{}@{}".format(user, host)
uri = pyotp.totp.TOTP(secret).provisioning_uri(name=label, issuer_name="WebSSH")
print("URI: {}".format(uri))

# Display QR code in ASCII
qr = qrcode.QRCode()
qr.add_data(uri)
qr.make()
qr.print_ascii(invert=True)

# Output JSON block to insert
print("\nJSON to insert into totp_secrets.json:\n")
print('  "{}": {{\n    "{}": "{}"\n  }}'.format(host, user, secret))

• Génère une clé TOTP unique
• Affiche le QR code dans le terminal (ce QR code sera utile pour initialiser l'application sur le téléphone de type google authentification)
• Enregistre la clé dans un fichier JSON structuré par hôte/utilisateur

Exemple d’appel :

python3 build-otp-key.py --host main-host --user admin --write

Format du fichier JSON

{
  "host1": {
    "web-admin": "JBSWY3DPEHPK3PXP"
  },
  "host2": {
    "admin": "KRSW4ZDFEHPK3ABC"
  }
}

Intégration dans WebSSH

Chemin du fichier secret

Corriger le chemin dans handler.py :

with open('/home/admin/sources/webssh-env/totp_secrets.json') as f:

Vérification TOTP dans post()

Déballer les arguments :

hostname, port, username, password, pkey = self.get_args()

Récupérer le code :

totp_code = self.get_argument('totp', default=None)

Vérifier :

host_secrets = secrets.get(hostname, {})
user_secret = host_secrets.get(username)

if user_secret:
    if not pyotp.TOTP(user_secret).verify(totp_code):
        raise tornado.web.HTTPError(403, "Invalid TOTP code")

Débogage

Logs utiles

• journalctl -u webssh -n 50
• Activer logging.DEBUG dans main.py