Ekran System Application Credentials Broker (ACB)


Table of Contents


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.


Prerequisites


First make sure that the following system requirements are met, and then download the latest version of the installation file.


System Requirements

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.


Installation


The latest version of the installation file can be downloaded from the ekransystem.com website: https://www.ekransystem.com/sites/default/files/ekransystem/EkranSystem_ACB.zip

Run this file to open the installation wizard, which will guide you through the installation process.


Adding an Application Account by Using 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 receive 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.


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).


The Ekran System ACB API


After installing the Ekran System ACB service on a web server machine (see System Requirements), 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

NameRequiredDescriptionNameDescription

get_access_token

Returns the Access Token.


POSTrefreshTokenyesThe Refresh Token of the application account user.Access TokenThe Access Token with a limited lifetime to get the properties for available secrets.
get_secret_detailsReturns the JSON data with the secret's properties.POSTaccessToken
yesThe 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.


secretIdyes

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|[email protected]%XvfWSi5-|@pC|PASoOA_b49N{j(V2htXIPlHK8v+YPJ\",\"secretId\":1}"


ACB API queries return the following status codes:

Code

Name

Description

200OKSuccessful.
400Bad requestBad input parameter, or some required parameter is missing. The response message indicates which one and why.
403Forbidden
  • 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.
405Method Not AllowedThe application does not support the specified HTTP verb.
500Internal Server Error

The ACB service is not working as expected. The request is probably valid, but needs to be requested again later.

503Service UnavailableThe Ekran System Application Server is probably stopped or offline.


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