fair4DNS-API

SOAP-API einrichten und verbinden

Über die SOAP-API stehen Ihnen die Funktionen des Domainmanagers für eigene Programme zur Verfügung – etwa um Domains zu registrieren, DNS-Einträge aus einer Anwendung heraus zu pflegen oder Zonen für viele Domains anzulegen.

Voraussetzung: IP-Freigabe

Die SOAP-API nimmt nur Anfragen von IP-Adressen an, die Sie vorher freigegeben haben. Diese Sicherheitsmaßnahme lässt sich nicht umgehen.

1. Melden Sie sich im fair4DNS-Domainmanager an.
2. Öffnen Sie Start › Account › IP-Freigaben API und klicken Sie auf Erstellen.
3. Tragen Sie die öffentliche IP-Adresse des Rechners ein, auf dem Ihr Skript läuft – IPv4 oder IPv6. Sie können mehrere Adressen hinterlegen, z. B. Ihren Server und Ihren Arbeitsplatz für Tests.

Verbindung und Login in PHP

Die Schnittstelle ist per WSDL beschrieben:

https://www.fair4dns.de/soap_server.php?WSDL

In PHP nutzen Sie die eingebaute Klasse SoapClient; dafür muss die PHP-Erweiterung SOAP aktiv sein (prüfen Sie das z. B. mit php -m). Nach dem Verbindungsaufbau melden Sie sich mit login() an. Das folgende Grundgerüst verwenden auch alle weiteren Beispiele:

<?php
// Zugangsdaten aus einer Datei außerhalb des Web-Verzeichnisses laden (siehe unten)
$zugang = require '/PFAD/ZU/private/fair4dns-zugang.php';

$wsdl = 'https://www.fair4dns.de/soap_server.php?WSDL';

try {
    $client = new SoapClient($wsdl, array(
        'keep_alive'         => false,
        'connection_timeout' => 20,
    ));
    $client->login($zugang['benutzer'], $zugang['passwort']);

    // Hier folgen Ihre Aufrufe, z. B.:
    $result = $client->process('domain,list,domain', null, array('domain' => '*'));
    print_r($result);
} catch (SoapFault $e) {
    // Verbindungs- oder API-Fehler protokollieren – ohne Zugangsdaten auszugeben
    error_log('fair4DNS-API: ' . $e->getMessage());
    exit(1);
}

Fehler, die als SoapFault gemeldet werden – etwa wenn die Verbindung nicht zustande kommt –, fangen Sie mit try { … } catch (SoapFault $e) { … } ab. Wie die Rückgabe einer Aktion im Einzelnen aufgebaut ist, auch im Fehlerfall, beschreibt die API-Dokumentation. Zum Ausprobieren eignet sich print_r($result).

Eine Funktion für alles: process()

Nach dem Login rufen Sie jede Aktion über dieselbe Methode auf:

$result = $client->process($action, $object, $values);

Zugangsdaten sicher ablegen

Schreiben Sie Benutzername und Passwort nicht direkt in Ihr Skript, sondern in eine eigene Datei:

<?php
// fair4dns-zugang.php – außerhalb des Web-Verzeichnisses speichern
return array(
    'benutzer' => 'IHR-BENUTZERNAME',
    'passwort' => 'IHR-PASSWORT',
);

DNS-Challenge-API einrichten und aufrufen

Die DNS-Challenge-API ist für die automatische Ausstellung von Zertifikaten per ACME-DNS-01-Challenge gedacht. Diese Prüfmethode ist z. B. für Let’s-Encrypt-Wildcard-Zertifikate (*.beispiel.de) vorgeschrieben und funktioniert auch für Server, die von außen nicht per HTTP erreichbar sind. Statt mit Benutzername und Passwort melden Sie sich mit einem Access-Token an, der nur für die Zonen gilt, denen Sie ihn zugeordnet haben.

Access-Token anlegen und der Zone zuordnen

1. Melden Sie sich im fair4DNS-Domainmanager an und öffnen Sie im Bereich SSL-Zertifikate die Automation-API-Verwaltung.
2. Klicken Sie auf API-Zugang anlegen. Kopieren Sie den Access-Token und bewahren Sie ihn sicher auf.
3. Öffnen Sie die Zone der Domain unter DNS / Nameserver › Zonen mit Zone bearbeiten.
4. Wählen Sie auf dem Reiter DNS-01-Challenge den Access-Token aus und speichern Sie.
5. Wiederholen Sie die Schritte 3 und 4 für jede weitere Domain, für die der Token Zertifikate anfordern soll.

Anfrageformat

• Methode POST
• Header Content-Type: application/json
• Header X-API-TOKEN: IHR-ACCESS-TOKEN
• Im Body ein JSON-Objekt mit der Aktion (action) und ihren Parametern

Die API ist zustandslos: Jede Anfrage steht für sich, es gibt keinen Login und keine Sitzung. Ein vollständiger Anfrage-Body sieht so aus:

{"action":"addChallengeRecord","domain":"beispiel.de","subdomain":"www","challenge_token":"abcde123xyz"}

Parameter

Andere Parameter sind nicht zulässig und führen zu einem Fehler.

Die drei Aktionen mit curl

Für die Beispiele legen Sie den Access-Token in der Umgebungsvariable F4DNS_TOKEN ab. Mit read -rs wird er nicht angezeigt und landet nicht in der Shell-History:

read -rs F4DNS_TOKEN && export F4DNS_TOKEN

addChallengeRecord legt einen Challenge-Eintrag an:

curl -sS -X POST 'https://API-ENDPUNKT' \
  -H 'Content-Type: application/json' \
  -H "X-API-TOKEN: $F4DNS_TOKEN" \
  -d '{"action":"addChallengeRecord","domain":"beispiel.de","subdomain":"www","challenge_token":"abcde123xyz"}'

removeChallengeRecord entfernt ihn wieder – mit denselben Parametern:

curl -sS -X POST 'https://API-ENDPUNKT' \
  -H 'Content-Type: application/json' \
  -H "X-API-TOKEN: $F4DNS_TOKEN" \
  -d '{"action":"removeChallengeRecord","domain":"beispiel.de","subdomain":"www","challenge_token":"abcde123xyz"}'

listChallengeRecords listet die vorhandenen Challenge-Einträge auf – optional nur für eine Subdomain, aber immer ohne challenge_token:

curl -sS -X POST 'https://API-ENDPUNKT' \
  -H 'Content-Type: application/json' \
  -H "X-API-TOKEN: $F4DNS_TOKEN" \
  -d '{"action":"listChallengeRecords","domain":"beispiel.de"}'

Die Antwort ist JSON; das Ergebnis steht im Feld data.result_code. Mit dem Hilfsprogramm jq lesen Sie es z. B. so aus: … | jq '.data.result_code'.

Mit einem ACME-Client nutzen

Bei der DNS-01-Challenge gibt die Zertifizierungsstelle (z. B. Let’s Encrypt) einen Prüfwert vor, der als TXT-Eintrag unter _acme-challenge. plus Domainname veröffentlicht werden muss. Ein Hook-Skript übernimmt das automatisch: Vor der Prüfung legt es den Eintrag per addChallengeRecord an, danach entfernt es ihn per removeChallengeRecord.

Das Beispiel nutzt den ACME-Client certbot auf einem Linux-Server mit Root-Rechten. Andere ACME-Clients mit Hook-Unterstützung binden die API nach demselben Prinzip ein.

Ablauf

1. Legen Sie einen Access-Token an und ordnen Sie ihn der Zone zu (siehe oben).
2. Speichern Sie den Access-Token in einer Datei, die nur root lesen kann.
3. Legen Sie das Hook-Skript an und tragen Sie den Endpunkt und Ihre Zone ein.
4. Testen Sie die Ausstellung mit --dry-run und fordern Sie danach das Zertifikat an.

Access-Token sicher ablegen

Schreiben Sie den Access-Token nicht in das Skript selbst – vor allem nicht, wenn es in einer Versionsverwaltung liegt. Legen Sie ihn in einer Datei ab, die nur root lesen kann (alternativ in einer Umgebungsvariable):

sudo touch /root/.fair4dns-token
sudo chmod 600 /root/.fair4dns-token
sudo nano /root/.fair4dns-token      # Access-Token einfügen und speichern

Hook-Skript für certbot

certbot übergibt dem Skript die Domain in $CERTBOT_DOMAIN und den Prüfwert in $CERTBOT_VALIDATION. Speichern Sie das Skript z. B. als /usr/local/bin/fair4dns-hook.sh und machen Sie es mit sudo chmod 700 /usr/local/bin/fair4dns-hook.sh ausführbar:

#!/bin/bash
# fair4dns-hook.sh – DNS-01-Challenge über die fair4DNS-DNS-Challenge-API
# Aufruf durch certbot: "fair4dns-hook.sh add" (vor der Prüfung)
#                       "fair4dns-hook.sh remove" (nach der Prüfung)
set -euo pipefail

API_URL='https://API-ENDPUNKT'        # Endpunkt laut DNS-Challenge-API-Dokumentation
ZONE='beispiel.de'                    # Zone, der der Access-Token zugeordnet ist
API_TOKEN=$(tr -d '[:space:]' < /root/.fair4dns-token)

case "${1:-}" in
  add)    ACTION='addChallengeRecord' ;;
  remove) ACTION='removeChallengeRecord' ;;
  *)      echo "Aufruf: $0 add|remove" >&2; exit 1 ;;
esac

# Subdomain relativ zur Zone bestimmen (bei der Domain selbst entfällt sie)
case "$CERTBOT_DOMAIN" in
  "$ZONE")   SUB='' ;;
  *."$ZONE") SUB="${CERTBOT_DOMAIN%.$ZONE}" ;;
  *)         echo "$CERTBOT_DOMAIN gehört nicht zur Zone $ZONE" >&2; exit 1 ;;
esac

# Wichtig: Prüfen Sie mit listChallengeRecords, unter welchem Namen der Eintrag
# angelegt wird, und passen Sie SUB bei Bedarf an (siehe Hinweis unten).
if [ -n "$SUB" ]; then
  JSON=$(printf '{"action":"%s","domain":"%s","subdomain":"%s","challenge_token":"%s"}' \
    "$ACTION" "$ZONE" "$SUB" "$CERTBOT_VALIDATION")
else
  # Ohne Subdomain den Parameter weglassen statt leer übergeben
  JSON=$(printf '{"action":"%s","domain":"%s","challenge_token":"%s"}' \
    "$ACTION" "$ZONE" "$CERTBOT_VALIDATION")
fi

curl -sS --fail -X POST "$API_URL" \
  -H 'Content-Type: application/json' \
  -H "X-API-TOKEN: $API_TOKEN" \
  -d "$JSON"
echo

# Nach dem Anlegen warten, bis der Eintrag auf den Nameservern sichtbar ist
if [ "$ACTION" = 'addChallengeRecord' ]; then
  sleep 30
fi

Die Pause von 30 Sekunden gibt den Nameservern Zeit, den neuen Eintrag auszuliefern. Schlägt die Prüfung fehl, weil der Eintrag noch nicht sichtbar war, erhöhen Sie den Wert.

Ob der Eintrag auf unseren Nameservern abrufbar ist, prüfen Sie z. B. mit dig:

dig +short TXT _acme-challenge.beispiel.de @ns1.fair4dns.de

Zertifikat anfordern

Ein Wildcard-Zertifikat für *.beispiel.de wird über die Domain selbst validiert: certbot übergibt dem Skript in $CERTBOT_DOMAIN den Namen beispiel.de (ohne *.), das Skript lässt subdomain deshalb weg. Testen Sie den Ablauf zuerst mit --dry-run gegen die Testumgebung von Let’s Encrypt:

sudo certbot certonly --manual --preferred-challenges dns \
  --manual-auth-hook '/usr/local/bin/fair4dns-hook.sh add' \
  --manual-cleanup-hook '/usr/local/bin/fair4dns-hook.sh remove' \
  -d beispiel.de -d '*.beispiel.de' \
  --dry-run

Läuft der Test fehlerfrei, wiederholen Sie den Befehl ohne --dry-run. certbot speichert die Hook-Befehle und verwendet sie bei der Verlängerung mit certbot renew automatisch wieder.