Authentisierungsprüfung via Cloud Server

Ab Vertec 6.6.0.10 bietet der Cloud Server die Möglichkeit, mithilfe von Vertec zu prüfen, ob Benutzername/Passwort dieses Benutzers in Vertec bekannt und korrekt sind.

Dafür gibt es zwei Endpunkte:

GET /authsettings

Für jeden Request gegen den Endpunkt wird eine eindeutige Nonce generiert. Diese kommt als JSON wie folgt zurück:

{
   "authnonce": "<randomly_generated_key>"
}

Diese Nonce wird im Header X-AUTH-NONCE an den /authcheck übergeben.

Antwortet /authsettings stattdessen mit einem HTTP Status Code 403 und dem Fehleroutput too many active login attempts, bedeutet das, dass aktuell zu viele Tokens aktiv sind. In diesem Fall muss die Anfrage später nochmal erfolgen.

POST /authcheck

Der Endpunkt erwartet als Input einen JSON Body mit folgenden Parametern:

{
    "loginname": "<loginname>",
    "password": "<password>",
    "twofactorCode": "<2facode>",
}

• loginname
• password
• twofactorCode: Bei Bedarf wird die 2FA Authentisierung ausgeführt. Der 2FA Code muss direkt im Input mitgeschickt werden, wenn 2FA für Vertec gefordert wird. Es ist Sache der Client App, zu entscheiden, ob sie einen 2FA Code vom Benutzer erfragt oder nicht.
  Wird 2FA nicht benötigt, kann der Parameter weggelassen oder ein Leerstring mitgeliefert werden.
• Im Header X-AUTH-NONCE wird eine aktuell gültige Nonce erwartet. Enthält der Request keine oder keine gültige Nonce, schlägt der Request sofort fehl.

Kann der Benutzer erfolgreich authentisiert werden, antwortet der Cloud Server mit HTTP Status Code 200 OK und leerem Body.

Ist Benutzername, Passwort, 2FA Code oder Nonce ungültig, antwortet der Cloud Server mit HTTP Status Code 403 FORBIDDEN. Der Body enthält eine kurze Beschreibung des Fehlers ('reason') als JSON:

{
    "reason": "<reason>",
    "message": "<message>" //bei reasons "banned" und "authentication server unavailable"
}

• Keine Nonce: reason = invalid nonce
• Ungültige/Abgelaufene Nonce: reason = invalid nonce
• Kein Benutzername angegeben (null oder empty): reason = invalid credentials
• Passwort falsch: reason = invalid credentials
• Vertec verlangt 2FA, Benutzer hat 2FA nicht eingerichtet: reason = missing 2fa setup
• Vertec verlangt 2FA, kein 2FA Code geliefert: reason = missing 2fa code
• Vertec verlangt 2FA, gelieferter Code falsch: reason = invalid credentials
• User ist gebannt: reason = banned, message = The user is still locked for ... minutes because too many login attempts failed.
• Zu viele Anfragen aktiv: reason = too many active login attempts

Bei aktiviertem OpenID Connect beantwortet der Cloud Server alle Requests an /authcheck mit 403 Forbidden mit der Reason authentication with credentials not allowed.

Ist der Authentisierungsserver nicht erreichbar (zum Beispiel bei Login mit LDAP), antwortet der Cloud Server mit einem HTTP Status Code 500 und dem Fehleroutput reason =authentication server unavailable, message = Vertec couldn't connect to the ... authentication server..

Die verwendete Nonce wird sofort invalidiert und ist nicht mehr für weitere Requests gültig. Jede Nonce kann nur für einen einzigen Request verwendet werden, unabhängig davon, ob die Authentisierung erfolgreich ist oder nicht.