Icinga Cloud

Documentation

  1. Einleitung
  2. Authentifizierung
    1. Basic-Authentifizierung
    2. OAuth2 Authentifizierung
  3. API Endpunkte
    1. Instanzen auflisten
    2. Icinga2 API Zugriff

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-Argument

    • token_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:

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.