Authentication check via Cloud Server

Starting with Vertec 6.6.0.10, the Cloud Server offers the possibility to use Vertec to verify that this user’s username/password is known and correct in Vertec.

There are two endpoints:

GET /authsettings

For each request against the endpoint, a unique nonce is generated. This is returned as JSON as follows:

{
   "authnonce": "<randomly_generated_key>"
}

This nonce is passed to /authcheck in the X-AUTH-NONCE header.

Replies /authsettings with a HTTP Status Code 403 and the error output too many active login attempts, this means that there are up to date too many tokens active. In this case, the request will have to be made again later.

POST /authcheck

The endpoint expects as input a JSON body with the following parameters:

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

• login name
• password
• twofactorCode: If necessary, the 2FA authentication is executed. The 2FA code must be sent directly in the input when 2FA is requested for Vertec. It is up to the client app to decide whether to request a 2FA code from the user or not.
  If 2FA is not required, the parameter can be omitted or an empty string can be supplied.
• a up to date valid nonce is expected in the X-AUTH-NONCE header. If the request contains no or no valid nonce, the request immediately fails.

If the user can be successfully authenticated, the Cloud Server responds with HTTP Status Code 200 OK and empty body.

If the user name, password, 2FA code or nonce is invalid, the Cloud Server responds with HTTP Status Code 403 FORBIDDEN. The body contains a short description of the error ('reason’) as JSON:

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

• Nononce: reason = invalid nonce
• Invalid/Expired Nonce: reason = invalid nonce
• No username specified (null or empty):reason = invalid credentials
• Password incorrect: reason = invalid credentials
• Vertec requires 2FA, user has not set up 2FA: reason = missing 2fa setup
• Vertec requires 2FA, no 2FA code supplied: reason = missing 2fa code
• Vertec requires 2FA, delivered code wrong: reason = invalid credentials
• User is banned: reason = banned, message = The user is still locked for ... minutes because too many login attempts failed.
• Too many requests active: reason = too many active login attempts

When activated Openid connect the Cloud Server answers all requests to /authcheck with 403 Forbidden with Reason authentication with credentials not allowed.

If the authentication server is not reachable (for example, when logging in with LDAP), the Cloud Server responds with a HTTP Status Code 500 and the error output reason = authentication server unavailable, message = Vertec couldn't connect to the ... authentication server..

The nonce used is immediately invalidated and is no longer valid for further requests. Each nonce can only be used for a single request, regardless of whether the authentication succeeds or fails.