IIS Administration API

Es gibt einige Möglichkeiten einen IIS-Server zu verwalten: Über das GUI-Verwaltungstool IIS-Manager, das klassische CMD-Tool appcmd.exe oder Powershell. Seit dem IIS 10 steht für Powershell sogar ein neues Modul zur Verfügung (“IISAdministration”), das schneller und flexibler sein soll – das bisherige Modul “WebAdministration” gibt es aber weiterhin. Jede dieser Möglichkeiten hat seine Vorzüge, aber auch Nachteile. Was es aber bisher nicht gab, ist eine offene und standardisierte Schnittstelle, die über eine Vielzahl an möglichen Technologien angesprochen werden kann – am Besten von jedem Client aus (und nicht nur auf Windows-Systeme beschränkt). Genau so eine Schnittstelle hat nun Microsoft in Form einer REST-API unter dem Namen “IIS Administration API” zur Verfügung gestellt.

Die “IIS Administration API” bietet damit neue Möglichkeiten einer Remote-Verwaltung von IIS-Servern. Sie läuft als Microservice auf dem Ziel-Server und kann letztendlich über alle Sprachen/Technologien, die HTTP-Verbindungen ermöglichen, ansprechen:

  • Powershell
  • JavaScript
  • .NET
  • PHP
  • Java
  • Python
  • Native Mobile-Apps (Windows, Android, iOS)
  • ect.

Darüber hinaus steht unter https://manage.iis.net der “Microsoft IIS Web Manager” zur Verfügung - eine webbasierte IIS-Admin-Oberfläche. Hierüber lassen sich die eigenen Webserver nicht nur verwalten, sondern auch monitoren. Es muss nur die API auf den Servern installiert sein!

IIS API 01IIS API 02

Installation

Die IIS Administration API kann ab Windows 7 bzw. Windows Server 2008R2 installiert werden (auch der Nano-Server wird unterstützt) und setzt die Runtime von Microsoft .NET Core voraus. Es sollte jedoch zuerst der IIS, dann .NET Core installiert werden.

Nach dem Download der IIS Administration API installiert man diese.

Konfiguration

Alle Konfigurationsmöglichkeiten der API sind in der Datei appsettings.json zu finden. Diese liegt unter:

%SystemDrive%\Program Files\IIS Administration\<version>\Microsoft.IIS.Administration\config\appsettings.json


Die gesamte Datei hat eine JSON-Struktur. Allerdings sind anfangs die NTFS-Berechtigungen dieser Datei so gesetzt, dass Administratoren nur Leseberechtigung haben. Schreib- bzw. Vollzugriff hat nur das System. Wenn man Änderungen oder Ergänzungen vornehmen möchte, muss man zuvor als Administrator den Besitz übernehmen und sich entsprechende Schreibberechtigungen geben.

Wichtig: Alle Änderungen an der Datei erfordern einen Neustart des Dienstes “Microsoft IIS Administration”, damit die Änderungen wirksam werden!

IIS API 04

Die wichtigsten Konfigurations-Punkte im Überblick:

Security: “require_windows_authentication”
Über true/false gibt man an, ob für jeden API-Request die Windows Authentifizierung verwendet werden soll. Diese Option ist standardmäßig aktiviert.

Security: “users”
Es gibt innerhalb der API 2 Benutzergruppen: “Administrators” und “Owners”. Jeder dieser API-Gruppen kann man Windows-Benutzer zuweisen (lokale oder AD-Benutzer), die dann Mitglied werden.

Security: access_policy
Es gibt insgesamt 3 Zugriffsregeln, über die man bestimmten Usern Berechtigungen geben kann.

  1. api: Wer bekommt Zugriff auf die API
  2. api_keys: Wer darf die API-Keys verwalten
  3. system: Wer darf API Aktionen ausführen, die höhere Berechtigungen benötigen (z.B. das Ändern der Identität eines Application Pools)

Innerhalb jeder Regel können insgesamt 4 Attribute konfiguriert werden:

  1. users: Angabe, für wen die Regel gelten soll. Anzugeben ist entweder eine API-Gruppe (siehe oben) oder “Everyone” (um jedem Zugriff zu ermöglichen).
  2. access_key: Steuert, ob für Requests ein Access Token notwendig ist.
  3. read_only: Erzwingt einen Nur-Lese-Modus. Dadurch können nur Anfragen über die HTTP-Methode “GET” geschickt werden.
  4. forbitten: Blockiert den gesamten Zugriff

CORS
Die sog. CORS-Richtlinien steuern welche Browser-basierten Anwendungen Requests an die API schicken dürfen. Standardmäßig ist nur https://manage.iis.net eingetragen. Wenn man eine eigene Web-Anwendung hat, die auf die API zugreifen soll, dann muss man für diese eine neue Regel anlegen.

Hinweis: Die Angabe keiner Regel führt nicht dazu, dass allen Web-Anwendungen Zugriff gewährt wird!

Zugriff auf die API

Standardmäßig kann auf die API via http bzw. https über den Port 55539 zugegriffen werden.

API-Explorer
Die einzelnen IIS-Komponenten, die man einsehen, hinzufügen, ändern oder löschen möchte, spricht man über URLs an. Um einen Gesamtüberblick über die einzelnen Komponenten und deren URLs zu bekommen, stellt Microsoft den API-Explorer zur Verfügung. Diesen erreicht man unter https://localhost:55539. Für den Zugriff ist ein Access-Token notwendig (siehe unten).

Microsoft IIS Web Manager
Hierbei handelt es sich um eine Web-Oberfläche, um einen IIS-Server via GUI zu verwalten. Stellt damit eine Alternative zum klassischen IIS Manager dar. Das Web Management Portal hat jedoch den Vorteil, dass dieses in jedem Browser auf jedem Endgerät (Dank Responsive Design auch auf mobilen Endgeräten) ausgeführt werden kann. Für den Zugriff ist ein Access-Token notwendig (siehe unten).

Access-Token
Egal, ob man via API-Explorer, IIS Web Manager oder Programmier-/Scriptsprache auf die API zugreifen möchte, man benötigt hierfür einen Access-Token. Um sich solch einen generieren zu lassen, öffnet man den API-Explorer (https://localhost:55539) oder IIS Web Manager (https://manage.iis.net) und klickt auf “Get Access-Token” oder geht direkt zu https://localhost:55539/security/tokens.

Dort gib man zu erst den Zweck des Access-Token an. Das ist ein frei wählbarer Name, der auch nur optional angegeben werden muss – macht später die Verwaltung mehrerer Token jedoch einfacher. Als nächstes wählt man die Gültigkeitsdauer aus (1 Tag, 1 Monat, 3 Monate, 1 Jahr, unendlich). Der Access-Token, der dann generiert und angezeigt wird, sollte man gut abspeichern, da man sich diesen im Nachhinein nicht noch einmal anzeigen lassen kann!

IIS API 03

Programm-/Scriptsprachen
Über diveres Programmier- oder Scriptsprachen kann ohne großen Aufwand auf die API zugegriffen werden. Voraussetzung ist nur, dass mit der Sprache eine HTTP-Verbindung aufgebaut werden kann. Damit können gängige Sprachen wie Powershell, JavaScript, C# (.NET) oder PHP verwendet werden.

Beispiel Powershell

Mit diesem Code-Beispiel kann man mit Powershell alle Webseiten eines IIS-Servers inkl. Status ausgeben lassen:

$token = "1-4b1BmGw00a6bjLDCkqJDHaszFM-lNNY1Zdz7ligTV0-F1t_9Jy6g"
$headers = @{ "Access-Token" = "Bearer $token"; "Accept" = "application/hal+json" }
$response = Invoke-RestMethod "https://localhost:55539/api/webserver/websites" -UseDefaultCredentials -Headers $headers
$response.websites

Für den Zugriff auf die API benötigt man auch hier einen Access-Token (siehen oben), den man als Header dem HTTP-Request mitgeben muss (dieser muss im Quellcode natürlich entsprechend ausgetauscht werden).

IIS API 05


Beispiel JavaScript

Mit JavaScript ist es auch nicht wesentlich komplizierter die Webseiten ausgeben zu lassen. Hier kommt für die HTTP-Verbindung ein AJAX-Request zum Einsatz. Für mehr Komfort bzw. weniger Schreibarbeit habe ich hierfür jQuery eingesetzt.

Zu erst einmal ein simples HTML-Dokument für den Script-Aufruf und die Ausgabe:

IIS API 06

Bei der Einbindung der JavaScript-Datei (api.js) das Attribut “defer” beachten – damit spare ich mir im JS-Code das jQuery-Event “ready”!

Und nun der JavaScript-Code:

$.ajax({
    method: "GET",
    url: "https://localhost:55539/api/webserver/websites",
    headers: {
        "Access-Token": "Bearer 8RFvwFK6KTeegT_WJVKJzu5xjSRdOKItbE8QaJXANmm2WD2v8qQOHg"
    },
    xhrFields:{
        withCredentials: true
    },
    complete: function(data)
    {
        var htmlString = "";

        data.responseJSON.websites.forEach(function(site)
        {
            htmlString += "<h3>"+  site.name +"</h3>";
            htmlString += "ID: " + site.id + "<br>";
            htmlString += "Status: " + site.status + "<br>";
        });

        $("#output").html(htmlString);
    }
});

 
Auch hier nicht vergessen den Access-Token gegen den Eigenen auszutauschen.

Für weitere Informationen und Beispiele empfehle ich die offizielle Dokumentation der Microsoft IIS Administration API.

Kommentare sind geschlossen