Syteca Application Credentials Broker (ACB)
NOT AVAILABLE IN SAAS
Table of Contents
1. Introduction
Syteca Application Credentials Broker (ACB) is a stand-alone component of Syteca that is used for integrating a customer’s IT system with Syteca via the Syteca ACB API.
This application is designed to allow customers to get Syteca secrets data via the ACB API, in order to use for their own business purposes.
The Syteca ACB API can also be used to rotate the password of the default "admin" user of Syteca via an external application.
2. System Requirements
First make sure that the following system requirements are met, and then download the latest version of the installation file.
• Windows Server 2022 or Windows Server 2019 [Recommended], Windows Server 2019 Core, Windows Server 2016, Windows Server 2012, or Windows 10. Both the x86 and x64 platforms are supported.
• IIS 7.5 or higher.
NOTE: Please refer to the Syteca Quick Start Deployment Guide to:
- Turn on Internet Information Services (IIS).
- Configure Internet Information Services (IIS).
• ASP.NET Core 8.0 Runtime (v8.0.12) - Windows Hosting Bundle or higher.
• Syteca Application Server 7.22 or higher when using ACB version 1.2 (or Syteca Application Server 6.41.1 if using a version prior to ACB 1.2).
3. Installation
The latest version of the installation file can be downloaded from the syteca.com website: https://download.syteca.com/Syteca_ACB.zip
Run this file to open the installation wizard, which will guide you through the installation process.
4. Adding an Application Account in the Management Tool
To use the Syteca ACB API, you need to first create a user account of any type (except an Active Directory user group) on the Users page, by clicking the Add User button (in the top right of the page).
Then while either editing/adding an Internal user or an Application Account user, or editing an Active Directory user, in the Application Account Settings section, you will get (and can copy) a Refresh Token, which is required for getting the Access Token that will be used for accessing the secrets' data.
Optionally, you can also specify the Authorization token lifetime (which defines how long the Access Token will be valid after receiving it) and an IP Address restriction to allow the application account to only be used from a specific IP address.
NOTE: The default value of the Authorization token lifetime is "600" seconds, and if you specify a value of "0", the Access Token will never expire.
5. Editing Secret Permissions for the Account
After the account has been created, it needs to be added to the Role Type permissions of the secret that you want to access.
For an existing secret, you can view (and copy) the Secret ID in the bottom right of the Automation tab (where the Secret ID is required to use the ACB API, for getting the secret's data).
6. The Syteca ACB API
After installing the Syteca ACB service on a web server machine (please also refer to Section 2. System Requirements above), you can start using the ACB API with any HTTP/HTTPS client.
Request URL: https://<hostname>/SytecaACB/<request_name>
NOTE: If ACB was updated from a version prior to 1.2, "SytecaACB" needs to be replaced by "EkranACB" in the Request URL above.
Request Name | Description | Type | Request Parameters in JSON Body | Response | |||
| Name | Required | Description | Name | Description | |||
get_access_token | Returns the Access Token. | POST | refreshToken | yes | The Refresh Token of the Application Account user. | Access Token | The Access Token with a limited lifetime to get the properties for available secrets. |
| get_secret_details | Returns the JSON data with the secret's properties. | POST | accessToken | yes | The Access Token, received via the get_access_token request. | Secret properties:
| The JSON data with the secret's properties. |
| secretId | yes | The identifier (number) of the secret, whose properties we need to receive. NOTE: It can be copied from the MT, in the Edit Secret pop-up window. | |||||
Examples of queries using the cURL utility:
curl -X POST "https://localhost/SytecaACB/get_access_token" -H "accept: */*" -H "Content-Type: application/json" -d "{\"refreshToken\":\"Vs7yGDEJGU8DLovudELezwMEZqFZ4nOcpjtrvNIlZbETWJCz5xH7FZOImYeFkeaW\"}"
curl -X POST "https://localhost/SytecaACB/get_secret_details" -H "accept: */*" -H "Content-Type: application/json" -d "{\"accessToken\":\"u)_MM*vCYn8GY;In|!@S%XvfWSi5-|@pC|PASoOA_b49N{j(V2htXIPlHK8v+YPJ\",\"secretId\":1}"
NOTE: If ACB was updated from a version prior to 1.2, "SytecaACB" needs to be replaced by "EkranACB" in the queries above.
ACB API queries return the following status codes:
Code | Name | Description |
|---|---|---|
| 200 | OK | Successful. |
| 400 | Bad Request | Bad input parameter, or some required parameter is missing. The response message indicates which one and why. |
401 | Unauthorized | Bad (invalid) input parameter. |
| 403 | Forbidden |
|
| 405 | Method Not Allowed | The application does not support the specified HTTP/HTTPS verb. |
429 | Too Many Requests | The rate limit is exceeded. |
| 500 | Internal Server Error | The ACB service is not working as expected. The request is probably valid, but needs to be requested again later. |
| 503 | Service Unavailable | Syteca Application Server is probably stopped or offline. |
7. Rate Limiting
Rate limiting is applied for all API requests as follows:
| API Endpoints | Max. No. of Requests | Period | Applied To |
|---|---|---|---|
POST get_access_token | 10 | 1 min. | IP address |
POST get_secret_details | 10 | 1 sec. | Access Token |
| * | 20 | 1 min | IP address |
Where:
• Each API response contain headers containing the rate limit status as follows:
- X-RateLimit-Limit: The maximum number of requests for the period.
- X-RateLimit-Remaining: The number of remaining requests.
- X-RateLimit-Reset: The time period (i.e. number of seconds) remaining or timestamp before the limit is reset.
• When an API response exceeds the rate limit, Syteca Application Server returns:
- The HTTPS status "429 Too Many Requests".
- A Retry-After header, indicating the time period (i.e. number of seconds) remaining before retrying.
8. The Syteca ACB CLI
After installing the Syteca ACB service, you can find a command line tool in the C:\Program Files (x86)\Ekran System\Ekran System Application Credentials Broker\Console folder (requires .NET Framework 4.8 or higher to run).
Run the following commands to identify the CLI (command line interface) parameters to make queries to the ACB API:
SytecaACBConsole.exe
SytecaACBConsole.exe get_access_token --help
SytecaACBConsole.exe get_secret_details --help
NOTE: If ACB was updated from a version prior to 1.2, "SytecaACB" needs to be replaced by "EkranACB" in the commands above.