Plesk-Connector: Korrekturen aus dem Live-Test (Plesk 18.0.81)

- Health: server/get mit gen_info vor stat (Plesk lehnte die Reihenfolge ab)
- Panel-Login: Plesk bindet die Sitzung an user_ip; die API übergibt jetzt
  die IP des Browsers (SDK loginUrl(ctx, ref, { userIp }), clientIp(req)),
  ohne IP gibt es eine klare Fehlermeldung statt eines toten Links
- Unterobjekte: leeres Ergebnis ohne id bei Datenbanken/FTP wird ausgefiltert
- Nachbau verhält sich jetzt wie das echte Plesk (Reihenfolge, IP-Bindung,
  leere Ergebnisse); Live-Prüfung in docs/connector-plesk.md dokumentiert

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kundencenter 2026-10-05 21:13:13 +02:00
parent 2aa793ed05
commit 612ab5fc53
6 changed files with 39 additions and 23 deletions

View file

@ -272,7 +272,7 @@ export const resourcesModule: KcModule = {
if (!r || !access(a, r)) throw notFound();
if (!canLogin(r, a)) throw forbidden('Der Panel-Login ist für diese Ressource nicht möglich', 'LOGIN_FORBIDDEN');
let out: { url: string; validForSec: number };
try { const { connector, ctx } = await loadInstance(r.instance_id, req.correlationId); out = await connector.loginUrl!(ctx, r.external_ref); } catch (e) { return providerError(e); }
try { const { connector, ctx } = await loadInstance(r.instance_id, req.correlationId); out = await connector.loginUrl!(ctx, r.external_ref, { userIp: clientIp(req) }); } catch (e) { return providerError(e); }
await audit({ actorType: 'user', actorId: a.user.id, orgId: r.org_id, action: 'resource.login', resourceType: 'resource', resourceId: id, connector: r.connector_key, correlationId: req.correlationId, ip: clientIp(req) });
reply.header('cache-control', 'no-store'); return out;
});

View file

@ -1,7 +1,7 @@
# Plesk-Connector
## Umsetzungsstand (05.10.2026)
Paket `packages/connector-plesk`, gebaut nach der Plesk-Dokumentation (XML-API, Plesk Obsidian 18) und getestet gegen einen Nachbau (`test/fake.ts`), **nicht gegen eine echte Instanz** (kein Testzugang). Zugang: Plesk-Adresse mit Port (meist `https://host:8443`) + **Secret Key**.
Paket `packages/connector-plesk`, gebaut nach der Plesk-Dokumentation (XML-API, Plesk Obsidian 18), getestet gegen einen Nachbau (`test/fake.ts`) **und am 05.10.2026 live gegen Plesk Obsidian 18.0.81** (Debian 13, Testserver) vom Kundencenter-Server aus. Zugang: Plesk-Adresse mit Port (meist `https://host:8443`) + **Secret Key**.
### Einrichtung
1. Auf dem Plesk-Server als root: `plesk bin secret_key -c -ip-address <IP des Kundencenter-Servers> -description Kundencenter` → Schlüssel kopieren. Er ist an diese IP gebunden und hat **Administratorrechte** (verschlüsselt gespeichert, nur Superadmins).
@ -29,17 +29,24 @@ Paket `packages/connector-plesk`, gebaut nach der Plesk-Dokumentation (XML-API,
- Alle Werte werden in XML maskiert (keine Element-Injektion); Antworten mit DOCTYPE/ENTITY werden abgelehnt (kein XXE).
- Der Secret Key steht nur im Header `KEY`, nie im Paket. Lesende Pakete werden bei 5xx/Netzfehler wiederholt, schreibende nie automatisch.
### Annahmen, die an einer echten Instanz zu prüfen sind
1. Secret Key wird von der XML-API im Header `KEY` akzeptiert (alternativ wären `HTTP_AUTH_LOGIN`/`HTTP_AUTH_PASSWD` möglich).
2. Leerer `<filter/>` liefert alle Objekte; „nicht gefunden“ kommt als Fehler 1013 je Ergebnis.
3. Elementreihenfolge bei `customer/add` (`cname, pname, login, passwd, status, email, description`) und `webspace/add` (`gen_setup, hosting, plan-name`) entspricht dem Schema.
4. `webspace/get` mit `<subscriptions/>` liefert die `plan-guid`; `limits` enthält die effektiven Limits inkl. `expiration` (Unix-Zeit, -1 = nie).
5. `real_size` und Traffic in **Byte**; `cr_date` als `YYYY-MM-DD`.
6. `server/create_session` mit `user_ip` (Base64) und leerem `source_server` liefert eine Sitzung, die vom Browser des Kunden (andere IP) genutzt werden kann; Gültigkeit ~5 Min. angenommen.
7. `site/get` mit `parent-id` liefert weitere Domains/Subdomains des Abonnements; `mail/get_info` mit `site-id` die Postfächer.
### Live-Prüfung (Plesk 18.0.81, 05.10.2026)
| Punkt | Ergebnis |
|---|---|
| Secret Key im Header `KEY`, Zertifikat per Fingerabdruck | ✅ bestätigt |
| Leerer `<filter/>` liefert alles, 1013 = nicht gefunden | ✅ bestätigt |
| Elementreihenfolge `customer/add`, `webspace/add` | ✅ bestätigt (Bereitstellung + Wiederholung ohne Doppelanlage) |
| `subscriptions/plan-guid`, effektive `limits`, `expiration` | ✅ bestätigt |
| Größen in Byte, `cr_date` als Datum | ✅ bestätigt |
| `server/get`: Reihenfolge | ❌ war `stat, gen_info` → Plesk verlangt **`gen_info` vor `stat`** (behoben) |
| Panel-Login (`create_session`) | ❌ Sitzung ist an `user_ip` gebunden; mit 127.0.0.1 landet der Kunde auf der Anmeldeseite → **IP des Browsers wird übergeben** (SDK: `loginUrl(ctx, ref, { userIp })`, API: `clientIp(req)`), danach ✅ |
| `site/get`, `mail/get_info`, `database/get-db`, `ftp-user/get` | ✅ bestätigt; bei 0 Treffern liefert Plesk ein leeres `<result>` ohne `id` → wird ausgefiltert (behoben) |
| Sperren/Entsperren, Planwechsel, Passwort, Löschen | ✅ bestätigt (Zielzustand, Wiederholung unschädlich) |
| Mandantentrennung bei Unterobjekten | ✅ bestätigt |
Hinweis: Mit der kostenlosen Edition „Web Admin SE“ sind höchstens 3 Kunden/3 Domains möglich; für echten Betrieb ist eine Plesk-Lizenz mit Kundenverwaltung (z. B. Web Pro/Web Host) nötig.
### Noch nicht umgesetzt
Neue Service-Pläne aus dem Kundencenter anlegen, Ändern von Domains/Postfächern/Datenbanken/FTP, SSL-Zertifikate, DNS, Reseller, mehrere Abonnements je Bestellung.
### Testen ohne eigenen Server
Plesk bietet ein offizielles Docker-Image (`plesk/plesk`) und eine kostenlose Testlizenz (14 Tage). Damit lassen sich die Annahmen oben in kurzer Zeit gegen eine echte Instanz prüfen.
Plesk bietet ein offizielles Docker-Image (`plesk/plesk`) und eine kostenlose Testlizenz (14 Tage). Das Skript für den Live-Test liegt nicht im Repo (nutzt echte Zugangsdaten); Ablauf: read → provision → actions → sso → children → cleanup.

View file

@ -214,11 +214,12 @@ export function createPleskConnector(deps: PleskDeps = {}): Connector {
}
if (kind === 'database') {
const op = await packet(ctx, xs('database', xs('get-db', x('filter', { 'webspace-id': w.id }))), false);
return results(op, 'get-db', true).filter((r) => (txt(r, 'webspace-id') ?? w.id) === w.id).map((r) => ({ id: txt(r, 'id') ?? '', kind, name: txt(r, 'name') ?? '', state: 'active', details: { type: txt(r, 'type') } }));
// Ein leeres Ergebnis ohne id bedeutet „keine Datenbanken“ (an Plesk 18.0.81 beobachtet)
return results(op, 'get-db', true).filter((r) => txt(r, 'id') && (txt(r, 'webspace-id') ?? w.id) === w.id).map((r) => ({ id: txt(r, 'id') ?? '', kind, name: txt(r, 'name') ?? '', state: 'active', details: { type: txt(r, 'type') } }));
}
if (kind === 'ftp') {
const op = await packet(ctx, xs('ftp-user', xs('get', x('filter', { 'webspace-id': w.id }))), false);
return results(op, 'get', true).filter((r) => (txt(r, 'webspace-id') ?? w.id) === w.id).map((r) => ({ id: txt(r, 'id') ?? '', kind, name: txt(r, 'name') ?? '', state: 'active', details: { home: txt(r, 'home') } }));
return results(op, 'get', true).filter((r) => txt(r, 'id') && (txt(r, 'webspace-id') ?? w.id) === w.id).map((r) => ({ id: txt(r, 'id') ?? '', kind, name: txt(r, 'name') ?? '', state: 'active', details: { home: txt(r, 'home') } }));
}
throw new ConnectorError('UNSUPPORTED', `${kind as ChildKind} wird bei Plesk noch nicht gelesen`);
},
@ -241,7 +242,8 @@ export function createPleskConnector(deps: PleskDeps = {}): Connector {
async healthCheck(ctx) {
const t0 = Date.now();
try {
const op = await packet(ctx, xs('server', xs('get', x('stat'), x('gen_info'))), false); const r = one(results(op, 'get'));
// Reihenfolge laut Schema: gen_info vor stat (Plesk lehnt sonst mit 1014 ab)
const op = await packet(ctx, xs('server', xs('get', x('gen_info'), x('stat'))), false); const r = one(results(op, 'get'));
const v = txt(path(r, 'stat', 'version'), 'plesk_version'); const host = txt(kid(r, 'gen_info'), 'server_name');
return { ok: true, latencyMs: Date.now() - t0, version: v ? `Plesk ${v}${host ? ` (${host})` : ''}` : undefined };
} catch (e) { return { ok: false, latencyMs: Date.now() - t0, message: e instanceof ConnectorError ? e.message : 'Unbekannter Fehler' }; }
@ -332,9 +334,11 @@ export function createPleskConnector(deps: PleskDeps = {}): Connector {
throw new ConnectorError('UNSUPPORTED', 'Diese Aktion gibt es bei Plesk nicht');
},
/** Einmal-Sitzung für den Besitzer des Abonnements (server/create_session); der Link wird nie gespeichert. */
async loginUrl(ctx, ref) {
async loginUrl(ctx, ref, opts) {
const { owner } = await ownerOf(ctx, ref);
const op = await packet(ctx, xs('server', xs('create_session', x('login', owner.login), x('data', { user_ip: Buffer.from('127.0.0.1').toString('base64'), source_server: '' }))), true);
// Plesk bindet die Sitzung an diese IP: es muss die des Browsers sein, der den Link öffnet (an Plesk 18.0.81 geprüft).
const ip = opts?.userIp?.replace(/^::ffff:/, '') ?? ''; if (!IPV4_RE.test(ip) && !/^[0-9a-f:]{2,39}$/i.test(ip)) throw new ConnectorError('BAD_CONFIG', 'Für den Plesk-Login wird die IP-Adresse des Browsers benötigt');
const op = await packet(ctx, xs('server', xs('create_session', x('login', owner.login), x('data', { user_ip: Buffer.from(ip).toString('base64'), source_server: '' }))), true);
const sid = txt(one(results(op, 'create_session')), 'id'); if (!sid || !/^[\w-]{8,200}$/.test(sid)) throw new ConnectorError('INVALID_RESPONSE', 'keine Sitzungs-ID');
return { url: `${base(ctx)}/enterprise/rsession_init.php?PLESKSESSID=${encodeURIComponent(sid)}`, validForSec: 300 };
},

View file

@ -56,10 +56,11 @@ export function createFake(secret = 'test-secret'): Fake {
function handle(pk: XNode): string {
const opNode = pk.children[0]!; const operation = opNode.children[0]!; const o = opNode.name; const n = operation.name;
const wrap = (inner: string) => `<${o}><${n}>${inner}</${n}></${o}>`;
if (o === 'server' && n === 'get') { const order = operation.children.map((c) => c.name); if (order.indexOf('stat') >= 0 && order.indexOf('gen_info') > order.indexOf('stat')) return `<${o}><${n}>${errR('1014', "Parser error: Element 'gen_info': This element is not expected.")}</${n}></${o}>`; }
if (o === 'server' && n === 'get') return wrap(ok(`<gen_info><server_name>plesk.fake.test</server_name></gen_info><stat><version><plesk_version>18.0.62</plesk_version><plesk_os>Debian</plesk_os></version></stat>`));
if (o === 'server' && n === 'create_session') {
const login = txt(operation, 'login'); if (!state.customers.some((c) => c.login === login)) return wrap(errR('1013', 'Client does not exist'));
const sid = `sess${++seq}abcdef`; state.sessions.push(`${login}:${sid}`); return wrap(ok(v('id', sid)));
const ip = Buffer.from(txt(path(operation, 'data'), 'user_ip') ?? '', 'base64').toString(); const sid = `sess${++seq}abcdef`; state.sessions.push(`${login}:${ip}:${sid}`); return wrap(ok(v('id', sid)));
}
if (o === 'service-plan' && n === 'get') return wrap(state.plans.map((p) => ok(`${v('id', p.id)}${v('name', p.name)}${v('guid', p.guid)}<limits><overuse>block</overuse>${Object.entries(p.limits).map(([k, val]) => `<limit><name>${k}</name><value>${val}</value></limit>`).join('')}</limits><permissions>${Object.entries(p.perms).map(([k, val]) => `<permission><name>${k}</name><value>${val}</value></permission>`).join('')}</permissions>`)).join(''));
if (o === 'customer' && n === 'get') {
@ -104,8 +105,9 @@ export function createFake(secret = 'test-secret'): Fake {
const f = filt(operation); const list = state.mail.filter((m) => String(m.site) === f.site);
return wrap(ok(`${v('filter-id', f.site)}${list.map((m) => `<mailname>${v('id', m.id)}${v('name', m.name)}<mailbox>${v('enabled', m.enabled)}${v('quota', m.quota)}</mailbox></mailname>`).join('')}`));
}
if (o === 'database' && n === 'get-db') { const f = filt(operation); return wrap(state.dbs.filter((d) => String(d.ws) === f.ws).map((d) => ok(`${v('id', d.id)}${v('name', d.name)}${v('type', d.type)}${v('webspace-id', d.ws)}`)).join('')); }
if (o === 'ftp-user' && n === 'get') { const f = filt(operation); return wrap(state.ftp.filter((u) => String(u.ws) === f.ws).map((u) => ok(`${v('id', u.id)}${v('name', u.name)}${v('home', u.home)}${v('webspace-id', u.ws)}`)).join('')); }
// Echtes Plesk liefert bei 0 Treffern ein leeres <result><status>ok</status></result> (an 18.0.81 beobachtet)
if (o === 'database' && n === 'get-db') { const f = filt(operation); const l = state.dbs.filter((d) => String(d.ws) === f.ws); return wrap(l.length ? l.map((d) => ok(`${v('id', d.id)}${v('name', d.name)}${v('type', d.type)}${v('webspace-id', d.ws)}`)).join('') : ok('')); }
if (o === 'ftp-user' && n === 'get') { const f = filt(operation); const l = state.ftp.filter((u) => String(u.ws) === f.ws); return wrap(l.length ? l.map((u) => ok(`${v('id', u.id)}${v('name', u.name)}${v('home', u.home)}${v('webspace-id', u.ws)}`)).join('') : ok('')); }
return wrap(errR('1014', `unbekannte Operation ${o}/${n}`));
}

View file

@ -102,9 +102,10 @@ describe('Plesk-Connector: Bereitstellung und Aktionen', () => {
expect(await code(c.execute!(ctx(), { action: 'reset_password', externalRef: '23', secrets: { password: 'kurz' }, idempotencyKey: 'p' }))).toBe('INVALID_INPUT');
});
it('Panel-Login als Einmal-Sitzung des Besitzers', async () => {
const f = createFake(); const r = await mk(f).loginUrl!(ctx(), '22');
expect(r.url).toMatch(/^https:\/\/plesk\.test:8443\/enterprise\/rsession_init\.php\?PLESKSESSID=sess\d+abcdef$/); expect(f.state.sessions[0]).toMatch(/^alpha:/);
expect(await code(mk(f).loginUrl!(ctx(), '24'))).toBe('UNSUPPORTED');
const f = createFake(); const r = await mk(f).loginUrl!(ctx(), '22', { userIp: '::ffff:198.51.100.7' });
expect(r.url).toMatch(/^https:\/\/plesk\.test:8443\/enterprise\/rsession_init\.php\?PLESKSESSID=sess\d+abcdef$/); expect(f.state.sessions[0]).toMatch(/^alpha:198\.51\.100\.7:/); // Sitzung an die Browser-IP gebunden
expect(await code(mk(f).loginUrl!(ctx(), '24', { userIp: '198.51.100.7' }))).toBe('UNSUPPORTED');
expect(await code(mk(f).loginUrl!(ctx(), '22'))).toBe('BAD_CONFIG'); // ohne Browser-IP funktioniert der Plesk-Login nicht
});
});
@ -118,6 +119,7 @@ describe('Plesk-Connector: Unterobjekte (nur lesen, nur eigenes Abonnement)', ()
const all = JSON.stringify(await c.children!.list(ctx(), '23', 'email')); expect(all).toMatch(/bernd@beta\.test/); expect(all).not.toMatch(/alpha|GEHEIM/);
expect(await code(c.children!.act(ctx(), { parentRef: '21', kind: 'email', op: 'create', data: {}, idempotencyKey: 'x' }))).toBe('UNSUPPORTED');
expect(await code(c.children!.list(ctx(), '../21', 'domain'))).toBe('NOT_FOUND');
expect(await c.children!.list(ctx(), '22', 'database')).toEqual([]); expect(await c.children!.list(ctx(), '22', 'ftp')).toEqual([]); // leeres Ergebnis = keine Einträge
});
});

View file

@ -112,7 +112,8 @@ export interface Connector {
* Die Werte werden nie gespeichert oder protokolliert (Capability `secret.reveal`).
*/
/** Kurzlebiger Login-Link ins Kundenpanel (Capability `sso.login`). Wird nie gespeichert. */
loginUrl?(ctx: ConnectorContext, externalRef: string): Promise<{ url: string; validForSec: number }>;
/** `userIp`: IP-Adresse des Browsers, der den Link öffnet (manche Panels binden die Sitzung daran, z. B. Plesk). */
loginUrl?(ctx: ConnectorContext, externalRef: string, opts?: { userIp?: string }): Promise<{ url: string; validForSec: number }>;
/** Unterobjekte eines Objekts (Capability `children.read`/`children.write`). */
children?: ChildAccess;
reveal?(ctx: ConnectorContext, externalRef: string): Promise<{ label: string; value: string }[]>;