Erste Schritte mit der OnDMARC API

Die OnDMARC API ist ideal für die Durchführung von Massen- oder Wiederholungsaufgaben, die schnell, häufig und fehlerfrei ausgeführt werden müssen – und Sie müssen dafür kein Entwickler sein oder überhaupt programmieren können. In diesem Beitrag zeige ich Ihnen, wie Sie die häufige Aufgabe der Aktualisierung der Subdomain-Richtlinie von Domains, die sich bereits in „Reject“ befinden, mithilfe von Red Sifts Dynamic DMARC, der OnDMARC API und Make (früher bekannt als Integromat) durchführen können. In diesem Beispiel verwenden wir Make, aber Sie könnten genauso gut jedes andere No-Code-Automatisierungstool wie Zapier oder Retool verwenden.

Wenn OnDMARC erstmals einen DMARC-Eintrag für eine Domain einrichtet, die zuvor keinen Eintrag hatte, wird immer eine Richtlinie mit p=„none“ (nur DMARC-Reporting) und sp=none erstellt. Das bedeutet, dass auch die Subdomain-Richtlinie nur auf Reporting eingestellt ist. Das heißt, wenn eine E-Mail von der Domain oder einer ihrer Subdomains, die keine eigene Richtlinie hat, DMARC nicht besteht, sollte der Empfänger keine (blockierende) Maßnahme ergreifen. Die E-Mail sollte normal zugestellt und ein DMARC-Bericht zur Analyse an uns zurückgesendet werden. Es sei denn, die Subdomain hat eine eigene DMARC-Richtlinie – mehr dazu in unserem hilfreichen DMARC-Leitfaden hier.

Diese passive Richtlinie ist großartig, während eine Domain und ihre Versandquellen konfiguriert werden. Sobald dies jedoch abgeschlossen ist oder wenn die Domain und ihre Subdomains keine E-Mails versenden, sollte die Richtlinie zügig auf p=reject geändert werden. Dabei werden E-Mails, die DMARC nicht bestehen, vom Empfänger abgelehnt und Spoofing-Versuche blockiert.

In unserem Beispiel haben wir 4 Domains in einem OnDMARC-Konto. Wir haben gewissenhaft 3 Domains auf p=reject umgestellt, aber vergessen, die Subdomain-Richtlinie zu aktualisieren, die weiterhin auf sp=none steht. Eine verbleibende Domain befindet sich noch bei p=none, da wir noch daran arbeiten. Wir müssen also zurückgehen und die Subdomain-Richtlinie für 3 der 4 Domains auf sp=reject aktualisieren. Mit der OnDMARC-Benutzeroberfläche und Dynamic DMARC ist das eigentlich recht einfach und würde etwa 12 Klicks erfordern. Aber was, wenn es statt 3 von 4 Domains 36 von 73 wären? Das wäre deutlich weniger unterhaltsam. Hier kommt die OnDMARC API ins Spiel.

Zunächst benötigen wir einen API-Schlüssel für OnDMARC. Gehen Sie zu „Administration“ im Benutzer- und Kontobereich, indem Sie auf das Profilsymbol oben rechts auf dem Bildschirm klicken.

Klicken Sie dann auf den Tab OnDMARC und stellen Sie sicher, dass Sie die richtige Instanz über die Instanzauswahl auswählen. Wenn Sie nur Zugriff auf eine OnDMARC-Instanz haben, müssen Sie sich darüber keine Gedanken machen.

Scrollen Sie nach unten zur API-Schlüsseltabelle am Ende des Bildschirms und klicken Sie auf „Hinzufügen“. Achten Sie darauf, diesem Schlüssel während des Vorgangs die Rolle Super Admin zuzuweisen. Kopieren Sie den API-Schlüssel an einen sicheren Ort. Ihre Übersicht der API-Schlüssel sollte nun so aussehen:

Klicken Sie auf dem Bildschirm „Meine Domains“ auf die unten hervorgehobene Export-Schaltfläche und laden Sie Ihre Domain-Liste als CSV herunter.

Öffnen Sie dann Google Sheets (oder Microsoft Office 365) und laden Sie die Datei in ein neues Blatt hoch. Entfernen Sie alle Spalten außer der Domain-Spalte, damit wir uns darauf konzentrieren können. Es sollte nun etwa so aussehen:

Hinweis: Wir hätten die Domain-Liste anstatt über die CSV-Methode auch über die API mithilfe des GET /domains API-Endpunkts abrufen können.

Nachdem unser Kontrollblatt eingerichtet ist, gehen wir zu Make, um unser Automatisierungsszenario einzurichten. Falls Sie noch kein Konto haben, können Sie hier eines einrichten.

Gehen Sie nun zu Szenarien und klicken Sie auf „Neues Szenario erstellen“. Fügen Sie das erste Modul hinzu und wählen Sie das Google Sheets-Modul „Bereichswerte abrufen“ aus. Wenn Sie dies zum ersten Mal tun, fordert Make Sie auf, sich zuvor bei Google Sheets zu authentifizieren.

Anschließend richten wir das Modul so ein, dass es den richtigen Zeilenbereich aus unserer spezifischen Google Sheets-Datei und dem entsprechenden Tab abruft. Es sollte so aussehen:

Wir können dies testen, indem wir mit der rechten Maustaste auf das Modul klicken und „Nur dieses Modul ausführen“ auswählen, um die Ausgabe zu überprüfen.

Wie erwartet, erhalten wir ein Bündel pro Zeile, das jeweils eine Domain enthält. Dies ermöglicht es uns, in den nachfolgenden Schritten jede Domain der Liste zu durchlaufen.

Als Nächstes senden wir eine Anfrage an die OnDMARC API, zunächst um die aktuellen Dynamic DMARC-Einstellungen zu überprüfen, und dann, um sie bei Bedarf zu aktualisieren. Wir überprüfen die aktuellen Einstellungen, bevor wir sie aktualisieren, weil wir die Subdomain-Richtlinie nur für Domains auf „Reject“ setzen möchten, deren übergeordnete Richtlinie bereits auf „Reject“ steht.

Um die vorhandenen Dynamic DMARC-Richtlinieneinstellungen abzurufen, verwenden wir den GET domainDMARC-Endpunkt. Dieser ruft die aktuellen Dynamic DMARC-Einstellungen einer bestimmten Domain in der OnDMARC-Instanz ab.

Erstellen Sie ein neues Modul, verknüpfen Sie es mit dem ersten Google Sheets-Modul und wählen Sie die HTTP-App sowie die Aktion „Basic-Auth-Anfrage stellen“ wie unten gezeigt aus:

Geben Sie im URL-Feld die Basis-API-URL für Ihre Region ein, gefolgt von der Erweiterung „/domain/{domain}/dmarc“. Die richtige Basis-URL finden Sie oben in der API-Dokumentation; sie variiert je nach Standort Ihrer Instanz (EU, UK oder US). Für die UK-Instanz sähe das so aus: https://api.ondmarc.com/domain/{domain}/dmarc

Ersetzen Sie nun {domain} durch eine Referenz auf die Domain-Spalte im Google Sheet aus dem vorherigen Modul, so wie hier:

Stellen Sie sicher, dass die Methode auf GET gesetzt ist, und fahren Sie dann mit dem nächsten Schritt zur Einrichtung dieses API-Aufrufs fort: der Autorisierung. Damit der API-Aufruf funktioniert, muss er mit Ihrem API-Schlüssel autorisiert werden. Dazu müssen wir einen Autorisierungsheader hinzufügen.

Geben Sie Element 1 im Bereich „Headers“ den Namen „Authorization“ und tragen Sie im Wertfeld „Api-Key“ ein, gefolgt von einem Leerzeichen und dem API-Schlüssel, den Sie in Schritt 1 gespeichert haben. Achten Sie darauf, diese Schritte genau wie angegeben auszuführen, da sie groß-/kleinschreibungssensitiv sind. Das Endergebnis sollte wie im obigen Screenshot aussehen.

Setzen Sie als letzten Schritt den Body-Typ auf „Raw“, den Content-Typ auf JSON (application/json) und „Parse response“ auf „Ja“, und klicken Sie anschließend auf OK, um zu speichern.

Lassen Sie uns nun das gesamte Szenario ausführen, um es zu testen.

Großer Erfolg. Bei der Analyse der Ausgabe gibt die API ein Datenobjekt zurück, das ein Array namens „entries“ enthält. Das erste Element (Element 1) enthält die übergeordnete Richtlinie, und das dritte Element (Element 3) enthält die Subdomain-Richtlinie. Um uns die Array-Manipulation zu ersparen, gehen wir sicher davon aus, dass die Elemente immer in dieser Reihenfolge übermittelt werden, und erstellen einfache Zuordnungen für unsere Filter.

Zurück in unserem Google Sheet: Geben Sie in der Kopfzeile von Spalte B „p=“ ein, in Spalte C „previous sp=“, in D fügen wir „Update status code“ hinzu und in E „new sp=“. Das Ergebnis sollte so aussehen:

Erstellen wir nun unseren ersten Rückschreibvorgang (Writeback) zu Google Sheets, um die aktuellen Einstellungen zur Bestätigung in unser Blatt zurückzuschreiben. Fügen Sie ein Google Sheets-Modul „Zeile aktualisieren“ hinzu und richten Sie es wie folgt ein:

Beachten Sie die Referenz der Zeilennummer auf das erste Modul; dadurch wird sichergestellt, dass die Ergebnisse an die richtige Zeile angehängt werden. Und in den Spalten B und C beziehen wir uns auf die Werte der Elemente 1 und 3 des „Entries“-Arrays, das von der OnDMARC API zurückgegeben wurde. Wenn wir das Szenario jetzt ausführen, sollten die Ergebnisse so aussehen:

Wir können nun deutlich erkennen, dass bei den Domains in den Zeilen 2, 4 und 5 die Subdomain-Richtlinie auf „Reject“ angepasst werden muss, bei der Domain in Zeile 3 jedoch nicht. Fahren wir mit dem nächsten Schritt fort.

Erstellen wir nun ein Router-Modul, um zwei mögliche Pfade für unser Szenario zu schaffen. Klicken Sie auf das +-Zeichen neben dem letzten Modul im Szenario und suchen Sie nach „Router“. Im ersten Pfad filtern wir so, dass nur Zeilen durchgelassen werden, bei denen die p=-Richtlinie den Wert „reject“ hat, und im zweiten Pfad alle übrigen Ergebnisse.

Richten wir den ersten Filter ein, indem wir auf den 1. Pfad nach dem Router klicken. Benennen Sie den Filter und richten Sie ihn wie folgt ein:

Das bedeutet, dass nur Elemente, bei denen die Richtlinie p=reject lautet, diesen Pfad durchlaufen. Beim zweiten Pfad richten wir den umgekehrten Filter ein:

Beachten Sie den Operator „Nicht gleich“.

Richten wir zunächst den zweiten Pfad ein, da dieser am einfachsten ist. Hier müssen wir die Richtlinie nicht aktualisieren; wir schreiben lediglich in die Zeile zurück, dass keine Aktualisierung erforderlich war. Klonen Sie das Modul „Zeile aktualisieren“ und ziehen Sie es auf den zweiten Pfad, dann bearbeiten Sie es wie folgt:

Denken Sie daran, dass Spalte D unser Feld „Update status code“ ist.

Wenden wir uns nun dem ersten Pfad zu, in dem wir einen Update-Aufruf an die OnDMARC API durchführen. Anstatt ein neues HTTP-Modul von Grund auf einzurichten, klonen und benennen Sie das erste Modul um und ziehen Sie es dann auf den Pfad. Die Pfade sollten so aussehen:

Nun müssen wir den API-Aufruf ändern, da wir nicht mehr die aktuellen Einstellungen abrufen, sondern neue Einstellungen übermitteln möchten. Wir verwenden denselben API-Endpunkt, aber anstelle eines GET-Aufrufs verwenden wir einen PATCH-Aufruf mit einigen zusätzlichen Informationen im Body, um die gewünschten geänderten Einstellungen anzugeben. Richten Sie es wie folgt ein:

Denken Sie daran, die Methode auf PATCH zu ändern, dieselben Autorisierungsheader zu behalten und Folgendes im Anfrageninhalt bzw. Body einzuschließen:

Dadurch wird die Subdomain-Richtlinie der betreffenden Domain aktualisiert, während alles andere unverändert bleibt.

Fügen wir nun ein abschließendes Bestätigungs-Writeback zu Google Sheets hinzu. Klonen, benennen und ziehen Sie das Google Sheets-Modul „Zeile aktualisieren“ aus dem unteren Pfad und richten Sie es wie folgt ein:

Dadurch wird der Antwortstatuscode in Spalte D zurückgeschrieben, und wenn der Status erfolgreich ist (Code 200), wird der aktualisierte Wert („reject“) in Spalte E eingetragen, andernfalls bleibt sie leer.

Das vollständige Szenario sollte so aussehen:

Lassen Sie es uns ausführen!

Wenn alles korrekt eingerichtet ist, sollten die Domains in „Reject“ Route 1 durchlaufen, während die anderen über Route 2 geleitet werden. Und hier ist das Ergebnis in Google Sheets, perfekt:

Dies ist ein großartiges Beispiel für einen realen Anwendungsfall der OnDMARC API. Wir haben gesehen, wie jeder sie mithilfe von Tabellenkalkulationssoftware wie Google Sheets oder Microsoft Office 365 als Kontrollblatt und Make oder Zapier als Automatisierungstool nutzen kann, um die API-Aufrufe durchzuführen. In diesem Beispiel haben wir die API verwendet, um die Dynamic DMARC-Einstellungen für eine Reihe von Domains bedingt zu aktualisieren, aber jede andere Aktion ist ebenfalls möglich. Um einige Ideen zu erhalten, können Sie die OnDMARC API-Dokumentation durchsehen oder sich einfach daran erinnern, dass Sie für alles, was Sie manuell in der Benutzeroberfläche tun können, wahrscheinlich auch einen passenden API-Endpunkt finden, mit dem Sie es automatisch orchestrieren können.