Skip to main content
Version: Next

Authentication in Salt.Box

User authentication algorithm​

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

Salt.Box user authentication diagram
Figure 1. Salt.Box user authentication diagram

User authentication 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