Einleitung
Dieser Webdienst ermöglicht den Zugriff auf entsprechend konfigurierte Icinga2-Instanzen über einen zentralen Server.
Durch den zentralen Server können bestimmte Anwendung leichter und andere überhaupt erst entwickelt werden. Ursprünglich wurde dieser Dienst für den Alexa Skill gebaut, der vom Endnutzer nicht konfiguriert werden kann. Lediglich eine "Account-Verknüpfung" ist möglich. Dieser Dienst kann aber problemlos auch von anderen Anwendungen genutzt werden und kann, falls es für andere Anwendung nötig ist, auch um Funktionen erweitert werden.
Fragen, Probleme und Anregungen zu diesem Dienst können per E-Mail an littlefox@lf-net.org mitgeteilt werden.
Authentifizierung
Nutzer der API können über 3 Wege authentifiziert werden: OAuth2, HTTP Basic-Auth und Loginformular+Cookie. Für Anwendungen stehen dabei aber nur die ersten beiden Möglichkeiten zur Verfügung, die dritte geht nur zum Testen über den Browser, in dem man eh schon eingeloggt ist.
Die Authentifizierung über OAuth2 ist zu bevorzugen, die HTTP Basic-Authentifizierung sollte nur in kleinen, selbst geschriebenen und nicht für die Öffentlichkeit gedachten Scripts verwendet werden.
Basic-Authentifizierung
Die HTTP-Basic-Authentifizierung ist eine sehr einfache und standardisierte Variante zur Authentifizierung von Benutzern. Hierbei werden die Zugangsdaten des Nutzers einfach entsprechend des HTTP Standards bei jedem Request mitgeschickt.
Der Nachteil dieser Authentifizierungsart ist, dass Anwendungsentwickler dabei zum einen die Zugangsdaten benötigen, die sie auch für andere Dinge verwenden könnten. Außerdem können einzelnen Anwendungen nicht die Zugriffsrechte entzogen werden, ohne das Passwort zu ändern. Die OAuth2-Authentifizierung behebt diese Probleme, ist aber etwas aufwendiger zu implementieren.
OAuth2-Authentifizierung
OAuth2 ist die bevorzugte Authentifizierungsart. Der Ablauf sieht dabei etwa wie folgt aus:
- Die Anwendung leitet den Nutzer zur Adresse https://icinga.lf-net.org/auth und gibt dabei die folgenden Parameter mit:
client_id
ID der Anwendung (wird beim Registrieren der Anwendung generiert)
state
kann von der Anwendung verwendet werden um Anfragen zu identifizieren, wird genau so wieder zurückgegeben
redirect_uri
Adresse zu der der Authentifizierungstoken ausgeliefert werden soll
- Weitere Argumente können übergeben werden, werden aber bisher ignoriert :o)
- Falls noch nicht eingeloggt: der Nutzer loggt sich mit seinen Zugangsdaten in den Webdienst ein
- Der Nutzer wird gefragt, ob die Anwendung Zugriff bekommen darf
- Stimmt der Nutzer dem zu, wird er zu der von der Anwendung übergebenen
redirect_uri
weitergeleitet, wobei die folgenden Argumente im Fragment-Teil der URL übergeben werden:state
Das von der Anwendung an den Webdienst übergebene
state
-Argumenttoken_type
Typ des übergebenen Authentifizierungstokens, immer
Bearer
access_token
Der Authentifizierungstoken zum Verwenden durch die Anwendung
Beispiele
Die Anwendung ruft die folgende Adresse auf:
https://icinga.lf-net.org/auth?client_id=421337&state=foobarbaz&redirect_uri=http://localhost:5000/auth_token_deliver?custom_var=23&illuminati=gr8
Bei erfolgreicher Authentifizierung wird dann die folgende Adresse aufgerufen:
http://localhost:5000/auth_token_deliver?custom_var=23&illuminati=gr8#state=foobarbaz&token_type=Bearer&access_token=asdlasdlkashdkasdhaskdasdkasd
Der so erhaltene Authentifizierungstoken muss dann bei jedem Request im Authorization
-Header mitgeschickt werden. Beispiel: Authorization: Bearer asdasdasdasdasdasd
.
Momentan gibt es für die Registrierung neuer Anwendungen noch keine Schnittstelle, deshalb bitte neue Anwendungen mit der Angabe der folgenden Informationen per Mail an littlefox@lf-net.org registrieren:
- Name der Anwendung
- Beschreibung der Anwendung
- Webseite mit mehr Informationen
- Liste der gültigen
redirect_uri
URLs für mehr Sicherheit
API
Es gibt nur 2 API-Endpunkte: Instanzen Auflisten und API-Gateway zu Icinga. Hier ist also recht wenig zu dokumentieren (und zu lesen).
Die Authentifizierung läuft immer wie im Kapitel Authentifizierung beschrieben.
Instanzen auflisten
GET /api
gibt eine JSON-Struktur im folgenden Format zurück:
{ "instances": [ { "id": 42, "base_href": "https://icinga.lf-net.org/api/42", "status_href": "https://icinga.lf-net.org/api/42/v1/status" } ] }Im
instances
-Array können dabei mehrere Objekte der gleichen Art enthalten sein - eins pro eingestellter Instanz des Nutzers.
Icinga API
Mit dem base_href
aus dem vorherigen Endpunkt können beliebige Icinga2 API Endpunkte angesprochen werden.
Als Beispiel wird für jede Instanz der Link zum Status-Endpunkt mit ausgeliefert, auch wenn der natürlich selber ermitelt
werden könnte.
Sämtliche Argumente, die an diesen Webdienst übermittelt werden, werden direkt an die Icinga2 API weitergeleitet, hier gibt es also keine Einschränkungen durch die Verwendung des Webdiestens.
Aktuell werden allerdings nur GET
-Anfragen unterstützt. Weitere werden implementiert, sobald Sie benötigt werden.