Syteca Application Credentials Broker (ACB)

NOT AVAILABLE IN SAAS

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.

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 5.0 Runtime (v5.0.4) - Windows Hosting Bundle or higher.

• Syteca Application Server 6.41.1 or higher.

3. Installation

The latest version of the installation file can be downloaded from the syteca.com website: https://download.syteca.com/EkranSystem_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

Before using the Syteca ACB API, you need to create an application account on the Users page, by clicking the Add User button (in the top right of the page), and then clicking the Add Application Account button on the Adding New User page by (you must have the administrative Management Tool Access and User Management permissions to do this).

On the Adding New User page 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 list for allowing the application account only to be used from specific IP addresses.

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 Application Account

After the application 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 client.

Request URL: https://<hostname>/EkranACB/<request_name>

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: ID Name Type Description Last rotation date/time Rotations count Computer name (for Windows account secrets, SSH secrets, and MS SQL secrets) Domain (for AD secrets) URL (for web secrets) Login Password SSH key (for SSH secrets with an SSH key)	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/EkranACB/get_access_token" -H "accept: */*" -H "Content-Type: application/json" -d "{\"refreshToken\":\"Vs7yGDEJGU8DLovudELezwMEZqFZ4nOcpjtrvNIlZbETWJCz5xH7FZOImYeFkeaW\"}"

curl -X POST "https://localhost/EkranACB/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}"

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.
403	Forbidden	The Refresh Token is invalid. The Access Token has expired, or is invalid. The IP address of the client that sends the request is not permitted. The application account does not have access to the secret. The Secret ID is invalid.
405	Method Not Allowed	The application does not support the specified HTTP verb.
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	The Syteca Application Server is probably stopped or offline.

7. The Syteca ACB CLI

After installing the Syteca ACB service, your can find a command line tool in the C:\Program Files (x86)\Ekran System\Ekran System Application Credentials Broker\Console folder (requires .NET 4.8 or higher to run).

Run the following commands to identify CLI (command line interface) parameters to make queries to the ACB API:

EkranACBConsole.exe

EkranACBConsole.exe get_access_token --help

EkranACBConsole.exe get_secret_details --help

Table of Contents