About Salt.Box

Purpose of the Salt.Box software suite

The Salt.Box software suite is designed to manage software configurations of workstations in order to ensure their operation in the required consistent state, deployment of system and application software on workstations, monitoring the state of workstations.

Tasks that can be automated with Salt.Box

• Inventarisation of software and hardware of workstations.
• Managing the software configuration of workstations in a hybrid IT infrastructure.
• Group policy management
• Transferring workstations to use operating systems of the GNU/Linux family and Linux-compatible application software.
• Configuring application software.

Main features of Salt.Box

• Multi-user mode with role-based access control.
• Obtaining detailed information about the enterprise's computing equipment fleet, and statistical information about software and hardware of workstations.
• Advanced tools for filtering and grouping workstations based on their hardware and software characteristics, software configuration status, and various monitored parameters.
• Asynchronous and parallel execution of software configuration management tasks on individual physical or virtual machines or on groups of machines.
• Event-driven launch of workstation software configuration management scripts.
• A single web interface for managing workstations, tasks and task templates, management scripts, and reports.
• Integration bus for connecting modules for expanding the program's functionality.

Architecture of the Salt.Box software suite

Figure 1. Architecture of the Salt.Box software suite

Table 1. Interactions between components, containers and subsystems of the Salt.Box software suite

№	Описание
1	User interaction with the web application via the http or https protocol
2	The web application works with the API gateway via a reverse proxy
3	The user's login and password are transferred to the KeyCloak to perform the authentication procedure
4	To store the user's registration data and the hash of their password, KeyCloak uses the PostgreSQL
5	Integration of KeyCloak with the corporate LDAP directory allows you to use existing user accounts. Using OpenID Connect provides single sign-on for all connected applications
7	KeyCloak issues JSON Web Token (JWT) for web application access to Salt.Box components
8	Passing JWT as part of any request made by the web application
9	API Gateway validates JWT received as part of any request against the KeyCloak
10	If JWT is valid, API Gateway queries OPA (Open Policy Agent) for the token owner's access policy to Salt.Box
11	Checking for updates, receiving, packing and saving changes in bundles
12	If the access policy allows the user to make the request, API Gateway forwards the request to the core of the Salt.Box
13	Service Core stores temporary data (pillars data, jobs, job execution results) in the key-value Redis store
14	Salt engines also have access to Redis store, get from it and save Job Returns and other data structures. The results of job execution are saved with a specified time to live (TTL)
15, 16	The Core service makes synchronous calls (RPC) and processes events (Events) via a message broker based on Redis Pub/Sub channels, managed by the FastStream framework
17	Static data (collections, minion and master server parameters, job schemes, task templates, Salt.Box settings) are stored in a DB managed by MongoDB
18	After processing the request and executing the corresponding jobs on the SaltStack minion side, the Core service returns a response to the API gateway
19	The API gateway passes the response to the web application to display the result to the user
20	The Core service launches long-running asynchronous tasks via Taskiq, using RabbitMQ as a message broker. Additionally, Taskiq provides a scheduler for executing tasks
21	The request to the Salt.Box extension module is executed in the same way as in item 12
22	The Salt.Box extension module launches long-running asynchronous tasks in the same way as in item 20
23	After processing the request and executing the corresponding jobs on the SaltStack minion side, the Salt.Box extension module returns a response to the API gateway
24	Salt Master publishes jobs, receives events created by the minion, generates its own events
25	The minion receives tasks jobs, receives events created by the master, generates its own events
26	Receiving data from the Salt Master's built-in file server
27	Data returned by the minion (Job returns)

Description of the authentication procedure

The authentication procedure is implemented using modern standards OAuth 2.0 and OpenID Connect:

1. The frontend initiates authentication process when web application is opened

2. The frontend generates a URL for redirection to the KeyCloak server with the following parameters:

   • client_id - client application ID in the KeyCloak
   • redirect_uri - return URL on successful authentication
   • response_type - code for flow authorization
   • scope - requested permissions (e.g. openid profile email)
   • state - random value to prevent CSRF attacks

3. The user enters credentials on the KeyCloak page

4. Upon successful authentication, the KeyCloak service does the following:

   • creates a user session
   • generates JWT tokens (access and refresh)
   • redirects the user to the specified redirect_uri with tokens

5. The frontend receives the JWT tokens and stores them in localStorage

6. All subsequent requests from the frontend to the API include the JWT access token in Authorization header

7. When the access token expires, the frontend automatically uses the refresh token to get a new access token without re-authenticating the user

Figure 2. Salt.Box user authentication diagram

Authentication of KeyCloak users via LDAP

KeyCloak integration with a corporate LDAP directory allows you to use existing user accounts.
To set up the integration, the KeyCloak administrator must do the following:

1. Create a new User Federation Provider of the LDAP type in the admin console

2. Configure connection parameters:

   • Connection URL: LDAP server address (e.g. ldap://ldap.example.com:389)
   • Bind DN и Bind Credential: credentials for connecting to LDAP
   • Users DN: base for searching users (Base DN)
   • Connection Pooling: enable connection pooling for performance

3. Configure synchronization strategy:

   • Edit Mode: edit mode (READ_ONLY, WRITABLE, UNSYNCED)
   • Sync Registrations: synchronization of new registrations
   • Batch Size: batch size when synchronizing a large number of users

4. Define mapping:

   • Атрибутов Username, Email, First Name, Last Name, etc. to attributes in KeyCloak
   • LDAP groups to groups in KeyCloak

5. Run primary synchronization to import existing users.
   The system then automatically authenticates users via LDAP when they log in to KeyCloak

Once configured, users can log in with their LDAP credentials, and KeyCloak provides single sign-on for all connected applications.

Open Policy Agent (OPA) and policy distribution

OPA is a tool for defining and enforcing uniform security policies across a microservice architecture:

1. Bundles: the main mechanism for distributing security policies:

   • packed archives with policies, rules, and data
   • usually include files in Rego format (OPA policy language)
   • may contain additional JSON data for context

2. Bundle lifecycle:

   • creating policies in Rego by security developers
   • packing policies into a bundle (archive) using CLI or API
   • publishing a bundle to a repository (HTTP server, S3, Git)
   • downloading a bundle by OPA agents through configured distribution points

3. Policy updates:

   • OPA periodically checks the source for updates
   • OPA downloads new versions of bundles automatically
   • OPA applies changes without restarting services

4. Versioning:

   • each bundle has a revision to track changes
   • OPA supports atomic policy updates