Syteca ACB API Endpoints for Rotation of the Default Admin Password

Syteca provides enhanced security capabilities by offering seamless integration for integrating a customer’s IT system with Syteca via the Syteca ACB API. This integration enables external applications to be used to rotate, and verify the password of the built-in default "admin" user account of the Syteca Management Tool automatically and securely.

Table of Contents

1. Prerequisites

To integrate Syteca ACB API with an external application so as to execute API requests, the following preconditions first need to be met:

• Syteca Application Credentials Broker (ACB) version 1.2 must be installed and configured, as well as Syteca version 7.22 or higher.

• All the API requests (below) are sent via the HTTPS protocol.

• The password generated by an external application must not violate Syteca's password requirements for the default "admin" user, which must (when Adding Users):

- Be at least 8 characters long.

- Contain at least one lowercase letter, one uppercase letter, one numeric character, and one special character.

- Not contain more than 3 consecutive identical characters, or contain the user login name.

NOTE: The password can optionally be an email address.

2. Enabling a User Account to be Used by External Applications

In order to be able to use Syteca ACB ASP, a user needs to be configured who will be able to rotate (and verify) the password of the default "admin" user, as follows:

1. On the Users page, either edit/add an Internal user or edit an Active Directory user that has the administrative User Management permission.

2. On the User Details tab, in the Application Account Settings section, move the Allow this user account to be used by external applications toggle to the right to enable this functionality:

3. After enabling the Allow this user account to be used by external applications toggle, the Refresh Token, Authorization token lifetime (sec) and IP Address restriction fields are then displayed and a Refresh Token is generated.

NOTE: After disabling the "Allow this user account to be used by external applications" toggle, the "Refresh Token", "Authorization token lifetime (sec)" and "IP Address restriction" fields are hidden again (and no longer function), and the Refresh Token expires.

NOTE: The fields in the Application Account Settings section are the same as in an Application Account (as otherwise used for ACB) and function in the same way, but an Application Account cannot be used to rotate the password of the default "admin" user (since this type of user cannot have the administrative User Management permission). 

3. Security and Authentication

A Refresh Token and an Access Token provide for security and authentication as follows:

• Authentication is performed by means of a short-lived Access Token obtained via the Refresh Token.

• The Access Token is refreshed by using the Refresh Token.

• The Access Token has a limited lifetime (see the Authorization token lifetime (sec) field in the screenshots above), and cannot be used after it expires.

• Access to Syteca’s ACB REST API for operation of the "admin" password is authorized by using a short-lived Access Token obtained via the Refresh Token.

• The Refresh Token is renewable and is securely stored in the vault of the external application.

4. Rate Limiting

Rate limiting is applied for all API requests as follows:

Where:

• The POST /auth/verify endpoint may have higher limits than other endpoints (if used frequently by an automated client of the external application).

• Failed login attempts performed via the Password Verification API (POST /auth/verify) increment the login failure counter (see Locking Users on Multiple Failed Login Attempts), where:

-  The user who performed unsuccessful API requests is locked for the amount of time specified in the EkranServer.Settings.config file (on the computer where Syteca Application Server is installed).

-  A locked user cannot log in to the Management Tool.

5. New Syteca ACB API endpoints

The new endpoints (described in the tables below), which were added in ACB version 1.2 use an Authorization header (instead of an Access Token), and are therefore handled differently to the old endpoints (described on the Syteca Application Credentials Broker (ACB) page).

The following new endpoints are available when using ACB:

6. API Status Codes

The Syteca ACB API has the following status codes:

7. Other Information

Other information, that may be useful to know:

• It is also possible to rotate the password of the default "admin" user with a сustom name (if this user name was changed) via the external application.

• After password rotation via the external application:

- The default "admin" user still has access to the Management Tool.

- Installing Syteca Application Server in Load Balancing (i.e. High Availability) mode is only possible by using the new password of the default "admin" user.

- The default "admin" user has access to all nodes (in Load Balancing mode), only using the new password of the default "admin" user.

- Installing Syteca API Data Connector is only possible using the new password of the default "admin" user.

- Logging in to the Syteca Tray Notifications Application is only possible by using the new password of the default "admin" user.