Authenticate

Benötigt für den Start einer VSA-API-Webdienstsitzung. Die zurückgegebene Sitzungs-ID muss mit jeder in der Sitzung aufgerufenen Methode übertragen werden. Die Sitzungs-ID ist nur gültig, wenn sie von dem gleichen Rechner erhalten wird, auf dem auch die Authentifizierung stattfand.

Es wird ein einzelner Datensatz der folgenden Felder zurückgegeben.

Automatische Anmeldung während der Authentifizierung

Wenn Sie sich über die API authentifizieren, werden Sie automatisch beim VSA angemeldet. Falls Sie zum Zeitpunkt der Authentifizierung bereits beim VSA angemeldet sind, werden die beiden Sitzungen synchronisiert.  Das Ergebnis ist in beiden Fällen das gleiche – es werden an beiden Ausgangspunkten gültige Sitzungen eingerichtet.

Der VSA sucht in der Abfragezeichenfolge jeder VSA-Seite nach der 26-stelligen Sitzungs-ID der API. Falls die Anwendung den Benutzer also auf eine VSA-Seite umleitet, wird sie geöffnet, ohne dass sich der Benutzer erneut anmelden muss. Die Syntax lautet:

URL?apiLogonGuid=12345678901234567890123456

Zum Beispiel:

http://someServer:123/Systemtab/SomePage?apiLogonGuid=12345678901234567890123456&SomeVar=SomeValue

Die API-Aktivität sorgt dafür, dass die VSA-Sitzung aktiv bleibt. Da der VSA jedoch nicht davon ausgeht, dass stets Bedarf für eine API-Sitzung besteht, hält die VSA-Aktivität die API-Sitzung umgekehrt nicht aktiv.

Die API verwendet den gleichen Timeout-Wert wie der VSA, der auf die Seite "System > Anmelderichtlinie des VSA festgelegt wird. Der Standardwert beträgt 30 Minuten.

Hash-Algorithmus

Ab Version 6.2 implementiert K2 für sichere Authentifizierungen den Hash-Algorithmus SHA-256. Der bisherige Standard war SHA-1. Eine allgemeine Beschreibung dieser Verbesserung finden Sie im Thema Passwörter externer Anwendungen ändern der Online-Hilfe zum System.

• Neu erstellte oder zurückgesetzte Passwörter werden mit SHA-256 gehasht.
• Für nicht zurückgesetzte Legacy-Passwörter ist SHA-1 weiterhin erforderlich.
• Der Parameter HashingAlgorithm in Authenticate wird standardmäßig auf SHA-1 gesetzt, wenn er nicht eigens angegeben wird.
• Die API-Beispielanwendung für C# und die API-Beispielseite für ASP bieten eine Option zum Wechseln zwischen SHA1 und SHA-256.
• VSA-Passwörter können nur in der VSA-Anwendung zurückgesetzt werden, nicht über die API.

  Warnung: Jegliche Änderung des Passworts einer externen Legacy-Anwendung führt zu einer Unterbrechung der Integration, bis entweder die externe Anwendung zur Nutzung des erforderlichen SHA-256-Hash-Algorithmus aktualisiert wurde oder neue SHA-1-Anmeldedaten erstellt und angewendet wurden. Stellen Sie also sicher, dass keine Passwörter externer Anwendungen geändert werden, bevor die Aktualisierung vorgenommen wurde. Siehe Neue SHA-1-Anmeldedaten für externe Legacy-Anwendungen erstellen unten.

Best Practices

Für eine nahtlose Migration zwischen früheren Versionen und der aktuellen Version empfiehlt Kaseya, den Clientcode der API-Webdienste so zu programmieren bzw. umzuprogrammieren, damit zunächst die Authentifizierung mit SHA-256 versucht und erst anschließend SHA-1 verwendet wird. Dadurch stellen Sie sicher, dass der Clientcode mit Passwörtern aus früheren Versionen und der aktuellen Version von VSA kompatibel ist.

1. Setzen Sie den Parameter HashingAlgorithm in der Anfrage Authenticate auf SHA-256. Vergewissern Sie sich, dass das Passwort mit SHA-256 gehasht wird. Geben Sie die Anfrage Authenticate aus. Prüfen Sie, dass eine gültige Sitzungs-ID zurückgegeben wird.
   • Die Authentifizierung war erfolgreich, wenn der Parameter SessionID einen anderen Wert als Null zurückgibt und der Parameter ErrorMessage leer ist.
   • Die Authentifizierung war nicht erfolgreich, wenn der Parameter SessionID den Wert Null zurückgibt. Führen Sie Schritt 2 aus.
2. Setzen Sie den Parameter HashingAlgorithm auf SHA-1. Hashen Sie das Passwort erneut, diesmal mit SHA-1. Geben Sie die Anfrage Authenticate erneut aus. Prüfen Sie, dass eine gültige Sitzungs-ID zurückgegeben wird.

Neue SHA-1-Anmeldedaten für externe Legacy-Anwendungen erstellen

Wenn Sie in VSA v6.2 oder höher einen kompatiblen Satz aus SHA-1-Benutzernamen und -Passwort für eine externe Legacy-Anwendung anlegen müssen, die noch nicht auf Kompatibilität mit v6.2-Passwörtern aufgerüstet wurde, gehen Sie wie folgt vor: Erstellen Sie entweder einen neuen Master-Benutzer mit zugehörigem Passwort oder setzen Sie das Passwort des bestehenden Master-Benutzers zurück.

Hinweis: Sie müssen über Administratorberechtigungen auf dem Kaseya Server verfügen. Aus Sicherheitsgründen können Sie das folgende Verfahren nicht remote ausführen.

Neues Master-Benutzerkonto erstellen

1. Melden Sie sich auf dem Rechner an, auf dem der Kaseya Server ausgeführt wird.
2. Rufen Sie diese Webseite auf:
   http://localhost/localAuth/setAccountV61.asp.
3. Geben Sie einen neuen Kontonamen in das Feld Master-Benutzername ein.
4. Geben Sie ein Passwort in das Feld Passwort eingeben ein und bestätigen Sie es, indem Sie es erneut in das Feld Passwort bestätigen eingeben.
5. Geben Sie im Feld E-Mail-Adresse eine E-Mail-Adresse ein.
6. Klicken Sie auf Erstellen.

Die externe Anwendung kann nun aktualisiert werden, um sich über das neue Benutzerkonto und SHA-1-Passwort mit dem VSA zu verbinden.

Passwort eines bestehenden Master-Benutzers zurücksetzen

Hinweis: Das Master-Benutzerkonto kann nicht deaktiviert werden.

1. Melden Sie sich auf dem Rechner an, auf dem der Kaseya Server ausgeführt wird.
2. Rufen Sie diese Webseite auf:
   http://localhost/localAuth/setAccountV61.asp.
3. Geben Sie den Namen eines bestehenden aktiven Master-Benutzerkontos in das Feld Master-Benutzername ein.
4. Geben Sie ein Passwort in das Feld Passwort eingeben ein und bestätigen Sie es, indem Sie es erneut in das Feld Passwort bestätigen eingeben.
5. Überspringen Sie die E-Mail-Adresse. Auf dieser Webseite kann die E-Mail-Adresse eines bestehenden Benutzers nicht zurückgesetzt werden.
6. Klicken Sie auf Erstellen.

Die externe Anwendung kann nun aktualisiert werden, um sich über das neue SHA-1-Passwort mit dem VSA zu verbinden.