Ekran System Application Credentials Broker (ACB)

NOT AVAILABLE IN SAAS

1. Introduction

Ekran System Application Credentials Broker (ACB) is a stand-alone component of Ekran System that is used for integrating a customer’s IT system with Ekran System via the Ekran System ACB API.

This application is designed to allow customers to get Ekran System 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 Ekran System 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.

• Ekran System Application Server 6.41.1 or higher.

3. Installation

The latest version of the installation file can be downloaded from the ekransystem.com website: https://download.ekransystem.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 Ekran System ACB API, you need to create an application account on the Adding New User page by clicking the Add Application Account button (you must have the administrative Management Tool Access and User Management permissions to do this).

On the Adding New User page you will get 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 permissions of the secret that you want to access.

For an existing secret, you can see the Secret ID at the bottom of the Secret Properties tab (this ID is required to use the ACB API, for getting the secret's data).

6. The Ekran System ACB API

After installing the Ekran System 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 Ekran System Application Server is probably stopped or offline.

7. The Ekran System ACB CLI

After installing the Ekran System 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