Einleitung

Überblick

Die Schnittstelle WebAPI bietet IT-Betreuern am KIT die Möglichkeit, eigene, speziell zugeschnittene Anwendungsprogramme für die Pflege ihrer netzwerk-spezifischen Anwendungsdaten (wie z.B. DNS) aufzubauen.

Die Schnittstelle setzt auf der Netzdatenbank des SCC (NetDB) auf und ist für eine vollautomatisierte Nutzung auf Basis des heutzutage üblichen textbasierten Datenaustauschformates JSON (JavaScript Object Notation) vorgesehen (s.a. http://de.wikipedia.org/wiki/JavaScript_Object_Notation).

Sie ist über HTTPS erreichbar und kann dadurch mit jeder beliebigen HTTP-Programmbibliothek benutzt werden. Im Rahmen der implementierten Systeme (Anwendungsbereiche), Objekttypen und Funktionen lassen sich sämtliche Daten durch entsprechende Dienstanforderungen (Requests) sowohl ausgeben bzw. abfragen als auch manipulieren (im Standardfall Eintragen, Ändern, Löschen). Die konkreten, jeweils versionsspezifischen Informationen und Parameter zu diesen Systemen, Objekttypen und Funktionen sind nicht Bestandteil dieser Dokumentation, sondern über selbstdokumentierende Indexabfragen der WebAPI erreichbar.

Alle nachfolgenden Beispielangaben zu Requests sind auf die Verwendung des Programms ‘curl’ bezogen; zusätzlich sind auch Codevorlagen in der Programmiersprache Python vorhanden. Eine einfache Formatierung der JSON-Ausgabe mit Zeilenumbrüchen und Einrückungen erreicht man z.B. mit ‘curl … | python -m json.tool’.

Authentifizierung / Registrierung

Das WebAPI ist nur über HTTPS erreichbar. Diese Ebene übernimmt auch die Identifizierung und Authentifizierung: akzeptiert werden gültige (d.h. nicht abgelaufende und nicht gesperrte) SSL-Client-Zertifikate für Benutzer, die

  • von der KIT-CA ausgestellt wurden und
  • mit einem NetDB-Benutzerkonto (in der NetDB bereits registrierter KIT-Account) verknüpft sind.

Diese Verknüpfung (Registrierung) ist über die dafür vorgesehene Webseite https://www-net.scc.kit.edu/api/cert/ vom Inhaber des KIT-Accounts einzurichten. Hierzu ist das im Browser installierte Zertifikat (bitte Hinweis beachten) sowie eine erneute, einmalige Authentifizierung des KIT-Accounts durch Passwort-Eingabe erforderlich. Ein und dasselbe Benutzerkonto kann grundsätzlich mit mehreren Zertifikaten verknüpft werden. Pro Vorgang kann allerdings nur ein Zertifikat eingetragen werden. Die Verknüpfung basiert auf dem Subject-DN (Distinguished Name) des zu registrierenden Zertifikats. Deshalb ist bei Ablauf bzw. Ungültigkeit des Zertifikats eine erneute Registrierung nur dann erforderlich, wenn der Subject-DN des alten nicht mit dem Subject-DN des neuen Zertifikats übereinstimmt. Auf diese Weise wird ein nahtloser Übergang bei Zertifikatserneuerungen ermöglicht.

Generelles

  • Basis-URI: https://www-net.scc.kit.edu
  • Alle Funktionen sind über ‘HTTP GET’ und ‘HTTP POST’ erreichbar.
  • Begriffskonventionen zu JSON:
    • Dict-Objekt: Objekt bzw. assoziatives Array, beginnt mit { und endet mit }.
    • List-Objekt: Liste oder Array: beginnt mit [ und endet mit ].
    • Bezeichner: Schlüssel eines Dict-Objektes
  • Das Antwortformat eines Requests ist grundsätzlich JSON; die JSON-Struktur hängt von den Request-Parametern (System, Objekttyp, Funktion) ab.
  • Der HTTP Request Body wird ebenfalls in JSON erwartet; auch hier hängt die Struktur von der Art des Requests ab.
  • Jeder WebAPI-Request für eine Datenmanipulation ist transaktional, d.h. entspricht einer separaten NetDB-Transaktion.
  • Beim ersten Fehler, der bei der Ausführung eines WebAPI-Requests auftritt, wird dieser abgebrochen und alle in diesem Request bis dahin erfolgten Datenmanipulationen werden rückgängig gemacht (rollback).

Hinweise zur Zertifikatsbenutzung bzw. Registrierung

Wir empfehlen Ihnen aus Sicherheitsgründen (Schadensminimierung im Mißbrauchsfall), hierfür nicht dasselbe Zertifikat einzusetzen, das Sie regulär für Ihre E-Mail-Kommunikation benutzen, sondern ein dediziertes Zertifikat (Personen- oder Gruppenzertifikat) zu verwenden (und ggf. neu zu beantragen). Die Unterscheidung liegt im “Distinguished Name” (DN, dh. der Name, auf den das Zertifikat ausgestellt wurde), welcher sich durch ein vorangestelltes “PN:” und den Hinweis auf “NET-WebAPI” vom DN Ihres E-Mail-Zertifikats unterscheidet. Im Einzelnen:

  • Benutzerzertifikat (Personen- oder Gruppenzertifikat) bei der KIT-CA beantragen. Dort als Name “PN: vorname nachname / NET-WebAPI” angeben. Weitere Infos: KIT-CA
  • Man bekommt als Bestätigung eine E-Mail von der KIT-CA und importiert das Zertifikat durch Klicken auf einen (in dieser Mail angegebenen) Link in den Browser. Die weiteren Schritte basieren auf diesem, im Browser importierten Zertifikat.
  • Zertifikat inklusive Key aus dem Browser im p12-Format exportieren: cert.p12
  • .key-Datei aus der .p12-Datei erstellen (Bsp. für Unix/Linux-Systeme): openssl pkcs12 -in cert.p12 -out net-webapi.key -clcerts -nodes
  • net-webapi.key ist die für alle WebAPI-Zugriffe zu nutzende Zertifikatsdatei. Da in dieser Datei der eigene Schlüssel enthalten ist, sollten Sie die Zugriffsberechtigungen so ändern, daß sie nur von Ihnen bzw. vom Zertifikatsinhaber benutzt werden kann.
  • Zertifikat an den eigenen KIT-Benutzeraccount in der NETDB binden: https://www-net.scc.kit.edu/api/cert/