Advanced configuration of services and components

This section describes the advanced technical configuration of the various services and components that make up Anjana Data Platform. It is intended for administrators and technical teams responsible for maintaining and operating the environment once the platform has been installed via Ansible or Kubernetes.

The purpose of this guide is to provide the necessary guidelines to adjust the behavior of Anjana's microservices and modules, covering aspects such as:

• Activation of specific profiles and configurations (spring.profiles.active).

• Management of secrets and credentials in Vaults and cloud Secret Managers (AWS, Azure, GCP).

• Log, performance, and load balancing configuration.

• Integration with external systems (authentication, notifications, licensing).

• Management of TOT plugins and Horus parameters.

Use of profiles

Any of Anjana's services can be started using different profiles. This practice is especially useful when a specific configuration needs to run at certain times, such as changes to log profiling or adjustments to variables that impact performance. The next section explains how to enable different profiles across various technologies; for now, we will focus on how to use those profiles.

By default, Anjana Data is configured to run the 'default' profile, which includes the default values provided by Anjana. These values are generally sufficient unless specific connection configurations are required. This configuration can be seen in the service descriptor of any of the artifacts, where the argument --spring.profiles.active=default is included.

It is possible to modify this profile or combine it with others, using a comma to separate them, as in --spring.profiles.active=default,profile1,profile2. Profiles that complement each other can also be run together. It is important to note that the order of the configured profiles affects the result: the last profile specified "wins". If there are properties with different values in each profile, the value from the last profile that sets them will be applied.

Configuration distribution

Anjana can be configured in different ways, and each service can even be configured differently due to its microservices architecture, although for practicality it is recommended to use the same mechanism for all of them.

It can be configured through:

• Horus as a centralized configuration repository that can read configurations from different sources such as a Git repository, a database (app_configuration table in the portuno database schema), HashiCorp's Vault, AWS Secret Manager, or the file system where Horus is hosted. (This is the recommended, default option).

• Another configuration method is to use a Vault key repository in each service (AWS Secret Manager, GCP Secret Manager, or Azure Key Vault).

• The last configuration method uses a YAML file accessible directly from the service to be configured; this method enables the use of environment variables on the same machine.

The methods described above can be used in combination, for example using Vault for credential configuration, the app_configuration table for Anjana configuration, and a yaml file to configure the log level.

📝Note:

• If Vault is used with Horus, it must be done through Horus.

⚠️Recommendation:

Given that most of the technical configuration relates to connections and credentials, it is recommended, for security reasons, to prioritize the use of Vault repositories.

Direct YAML

For a service to use a YAML file directly, the service descriptor must be configured to include the following argument:

--spring.config.additional-location=<path to properties file directory>

This argument accepts specific files or directories. If a specific file is chosen, it will overwrite all default values, leaving unset any configuration not included in that file; for this reason, it is recommended to use a directory, ending the chosen path with /.

The name of the file or files must follow this format: application-<profile>.yaml. The use of profiles is explained in the previous section.

Horus as a centralized repository

Horus is the only service that cannot use another Horus to provide configuration, so for this service you must choose one of the other two options, or both.

As mentioned, Horus accepts several types of repositories to provide configuration, and it also supports configuring several at the same time. To do so, an order must be set using the spring.cloud.config.server.<repository>.order property, assigning a numeric order to each one.

Every service that is going to use Horus must have the following argument configured in its service descriptor: --spring.config.import=optional:configserver:http://<Horus host>:9999/config

The following describes how to configure each repository.

Filesystem Repository

You only need to set the folder where the Anjana microservices' configuration files are located; this is Horus's native profile.

spring:
  profiles:
    active: native
  cloud:
    config:
      server:
        native:
         search-locations:
         - file:/opt/data/config
         - file:/opt/data/config/{application}
         - file:/opt/data/config/{application}/{profile}

Git Repository

You can specify which branch to use in default-label; the rest of the properties are generic Git repository connection properties

spring:
  cloud:
    config:
      server:
        git:
          uri: <user>@<server>/<repository>.git
          default-label: <branch>
          skipSslValidation: true
          timeout: 10
          clone-on-start: true
          force-pull: true
          searchPaths: '{application}'
          ignoreLocalSshSettings: true
          privateKey: |
            -----BEGIN RSA PRIVATE KEY-----
                       .......
            -----END RSA PRIVATE KEY-----

Vault Repository

The use of Vault repositories is supported via the HashiCorp's Vault tool

spring:
  profiles:
    active: vault
  cloud:
    config:
      server:
         vault:
            token: ******
            kv-version: 2
            host: <vault host>
            port: 8200
            authentication: TOKEN

For the complete configuration of HashiCorp Vault as a Horus backend (obtaining credentials, the meaning of each property, and environment-specific details) see the Vaults page.

Database

Anjana has native communication with the app_configuration table in the Portuno database schema. This table is made up of the following columns:

• Key for the property to configure

• Value for the value to configure

• Label to use as the property description

• Application to define which service the property is configured for (a NULL value identifies the property for all services)

• Profile to define the profile associated with the property (see what a profile is)

AWS Secret Manager

AWS Secret Manager can be used to store credentials and other configuration.

spring:
  # 1. BOOTSTRAP: Horus loads ITS OWN configuration.
  config:
    import: "optional:aws-secretsmanager:{HORUS_SM_PREFIX}/application_default/}" # EX: /secret/dev
  cloud:
    # 2. Connection to Secret Manager
    aws:
      region:
        static: {HORUS_SM_REGION}
      secretsmanager:
        enabled: true

    # 3. Prefix configuration for applications using horus as the configuration center
    config:
      server:
        aws-secretsmanager:
          order: 20
          prefix: {HORUS_SM_PREFIX} # EX: /secret/dev
          profile-separator: {APP_PREFIX} # EX: _

Encrypted Vault

Direct Vault configuration is only available for Tot Plugins, since they might not be on Anjana's core network and therefore cannot access Vault through Horus. This option is disabled by default; to enable any of the Cloud Vaults, the service descriptor must be edited by adding the property that enables the Vault, as defined below. To find out how to configure this property, follow the format explained in the previous section, "Use of profiles".

The complete configuration for each provider (required credentials, YAML, and specifics) is centralized in the Vaults page, to avoid keeping it duplicated in two places.

AWS Secrets Manager

Allows storing the plugin's sensitive configuration parameters in AWS Secret Manager and retrieving them via API call. Detailed configuration (IAM credentials or EC2 role, required YAML, and secret naming convention) is in the "AWS Secret Manager Configuration" section of Vaults.

Azure Key Vault

Allows storing the plugin's sensitive configuration properties in Azure Key Vault and retrieving them via API call. Detailed configuration (Azure AD app registration, required YAML, and secret naming restrictions) is in the "Azure Key Vault Configuration" section of Vaults.

GCP Secret Management

Allows storing the plugin's sensitive configuration in GCP Secret Manager and retrieving it via API call. Detailed configuration (GCP project, service account credentials, and required YAML) is in the "GCP Secret Manager Configuration" section of Vaults.

Other ways to secure credentials

Environment variables

Environment variables can be used to hide sensitive information in configuration yaml files, for example.

Create a folder with the service name /etc/systemd/system/xxxxx.service.d and inside it an env.conf-type file (owned by root with 600 permissions); this way only the microservice has access to that env.conf file.

[Service]
Environment=<KEY>=<VALUE>
Environment=<KEY2>=<VALUE2>

In the microservice's configuration yaml, it can be set in braces preceded by a dollar sign ${KEY}

spring:
  datasource:
    username: anjana
    password: ${BBDD_PASSWORD}
...

Generic utility and performance configurations

All Anjana microservices have an HTTP header size of 2KB by default; this value can be changed by modifying this property in the properties file.

server:
  max-http-header-size: 20000

It is possible to enable Hibernate statistics to view the information it provides with the following configuration.

It is important to note that generating statistics can affect performance, so it should only be enabled temporarily.

jpa:
  properties:
    hibernate:
      generate_statistics: true

Garbage collector: All services using jdk17 must use the G1 garbage collector to manage memory more efficiently:

-XX:+UseG1GC -XX:+UseStringDeduplication

Log configuration

The microservices are configured by default to output to standard console so that logs can be managed by the system's logging utility; typically in virtual machine environments, syslog, rsyslog, and journalctl will be used to consume or configure their handling.

All of them can be configured via each one's yaml file, following standard Spring Boot practices.

Example of common uses:

logging:
  pattern:
  console: "%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} [HERMES] %clr(${LOG_LEVEL_PATTERN:%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:%wEx}"
  level:
    root: INFO
    com.anjana: DEBUG

Load balancing

Load balancing and Horus high availability (the HORUS_REPLICAS variable, registering multiple Eureka and Config Server URLs) are documented on the Horus page, section "Horus high availability", to avoid keeping the same content duplicated in two places.

Authentication

Everything is configured in Zeus. The example YAML available in Nexus shows the configuration in detail, and you can copy, edit, and paste what you need, including field descriptions.

Additionally, authentication integrations are detailed in specific documents at Integrations/Authentication:

• SSO OKTA/AUTH0 (Deprecated)

• SSO AWS (Deprecated)

• SSO GCP (Deprecated)

• SSO Azure (Deprecated)

• Login LDAP/WAD

• SSO OICD

• SSO SAML 2.0

Email notifications

Anjana Data Platform allows automatic email notifications to be sent (for example, validation notices, status changes, adherences, etc.).
To enable them, the SMTP connection must be configured in the Hermes service, which is the component responsible for managing notification sending.

The configuration is done via Hermes's parameters file (YAML). Nexus has an example YAML with comments that can be used as a base to copy and adapt for each organization.

Required information (what to request from your organization)

Before configuring Hermes, request the following information from the team responsible for corporate email or the SMTP provider:

1. SMTP server (host)
   Address of the corporate SMTP server or provider (for example, smtp.empresa.com).

2. Port
   Enabled SMTP sending port. The most common are:

   • 587 (TLS STARTTLS)

   • 465 (SMTPS / implicit TLS)

   • 25 (unencrypted or internal relay, not recommended except in controlled environments)

3. Sender account (from)
   Email address from which notifications will be sent
   (for example, anjanadata@empresa.com).
   This account must be authorized to send emails from the domain.

4. Authentication credentials (username / password)
   Username and password of the mailbox or the SMTP technical account.

5. Security requirements

   • Whether the server requires SMTP authentication (auth = true).

   • Whether it requires TLS/STARTTLS (starttls.enable = true).

   • Whether there are IP, proxy, or firewall restrictions that need to be opened for Hermes.

Preliminary verification of the SMTP service from the command line

Before configuring Hermes, or whenever there is any doubt during troubleshooting, it is recommended to independently verify that the SMTP server and credentials work correctly. This makes it possible to isolate connectivity or authentication issues from possible functional errors in the platform.

Example SMTP test from the terminal (SMTPS – port 465)

swaks \
  --server smtp.empresa.com \
  --port 465 \
  --tls-on-connect \
  --auth LOGIN --auth-user 'user'--auth-password 'password' \
  --from 'anjanadata_platform@empresa.com' --to 'recipient@empresa.com' \
  --header "Subject: Test SMTPS 465" \
  --body "SMTP send test from the command line"

If the email is received successfully, this confirms that:

• the SMTP server is accessible from the environment,

• the credentials are valid,

• and there are no network or firewall blocks.

SMTP configuration in Hermes based on the port used

The Hermes configuration varies depending on the SMTP port and the type of encryption supported by the server. It is important not to combine SSL and STARTTLS simultaneously, since they are mutually exclusive mechanisms.

Port 587 – SMTP with STARTTLS (recommended in most environments)

Within Hermes's configuration YAML, enable the mail block and fill in the values provided by your organization.

######################
### SMTP connection properties
######################
  mail:
    # the host of the SMTP server
    host: smtp.example.com
    # the port to establish a connection with the SMTP server
    port: 587
    # the email address of the account you want to use as the sender of the emails
    from: anjanadata@anjanadata.com
    # the credentials for the SMTP server
    username: <userName>
    password: <password>
    properties:
      mail:
        smtp:
        # to enable SMTP authentication. When set to true, it indicates that the SMTP server requires authentication before sending email
          auth: true
        # to enable the use of TLS when connecting to the SMTP server. When set to true, it ensures that the connection is secured using TLS encryption
          starttls:
            enable: true
            required: true
          ssl:
            enable: false

Typical use: modern corporate servers, authenticated relays, cloud providers.

Port 465 – SMTPS (implicit TLS)

######################
### SMTP connection properties
######################
  mail:
    # the host of the SMTP server
    host: smtp.example.com
    # the port to establish a connection with the SMTP server
    port: 465
    # the email address of the account you want to use as the sender of the emails
    from: anjanadata@anjanadata.com
    # the credentials for the SMTP server
    username: <userName>
    password: <password>
    properties:
      mail:
        smtp:
        # to enable SMTP authentication. When set to true, it indicates that the SMTP server requires authentication before sending email
          auth: true
          ssl:
            enable: true
        # to enable the use of TLS when connecting to the SMTP server. When set to true, it ensures that the connection is secured using TLS encryption
          starttls:
            enable: true
            required: true

Typical use: servers that require an encrypted connection from the start.

Port 25 – SMTP without encryption (not recommended)

This should only be used in internal, controlled environments.

######################
### SMTP connection properties
######################
  mail:
    # the host of the SMTP server
    host: smtp.interno.local
    # the port to establish a connection with the SMTP server
    port: 25
    # the email address of the account you want to use as the sender of the emails
    from: anjanadata@anjanadata.com
    properties:
      mail:
        smtp:
          auth: false
        # to enable the use of TLS when connecting to the SMTP server. When set to true, it ensures that the connection is secured using TLS encryption
          starttls:
            enable: false

Functional validation of notification sending

Once SMTP connectivity has been verified from the command line and the configuration in Hermes has been deployed or updated, it is necessary to validate notification sending from Anjana Data Platform.

Validation steps

1. Restart the Hermes microservice
   For the new SMTP configuration to take effect, restart the Hermes microservice after any change to its configuration YAML.

2. Generate a notification from the platform
   Perform an action that triggers an email to be sent, for example:

   • sending an object for validation,

   • approving or rejecting a validation,

   • requesting or approving adherence to a DSA.

3. Verify the result
   Check that:

   • the email is received correctly in the recipient user's mailbox,

   • the sender matches the value configured in from,

   • the message is not blocked by corporate anti-spam policies.

Troubleshooting

If the email is not received, check the following points in this order:

1. SMTP connectivity

   • Confirm that Hermes can reach the configured host and port.

   • Check firewall rules, proxy settings, or IP allowlists.

2. Credentials and configuration

   • Verify the username, password, and port.

   • Check that the TLS/STARTTLS or SSL configuration is consistent with the port used.

3. SMTP relay policies

   • Check whether the server requires:

     • explicit authorization of the sender (from),

     • a validated domain,

     • the Hermes service's IP included in an allowlist.

4. Hermes logs

   • Analyze the logs to identify errors occurring before or after the send attempt.

   • Keep in mind that certain errors (for example, HTTP 400) can occur before the email send is even attempted, and may not be directly related to SMTP.

Encryption keys for Drittesta-Veltesta licensing

NIST recommends using keys of at least 2048 bits, which are the ones Anjana provides. Even so, if the customer wishes, they can generate a new RSA key pair to increase encryption security up to 4096 bits by creating the keys manually; this way, the customer becomes the creator and validator of the keys' security and uniqueness. Once generated, the public key must be provided to Anjana to configure its installation. The private key will be set in the Drittesta project using the new yaml property anjana.privateKey, taking into account that:

• It represents the customer's private key for communication between the licensing services.

• It will be a mandatory property.

• It can be generated by the customer as follows:

  • Using the endpoint enabled in Drittesta for this purpose (2048-bit key):

Where {{host}} is the machine's address and {{port}} is the Drittesta port. The response is a json with the following format:

Or,

In a UNIX console, run the following commands:

• ssh-keygen -m PKCS8 -t rsa -b 4096

• openssl rsa -in nombreClave -pubout

The first command generates the keys in a local directory. Description of the parameters:

• -m indicates the algorithm type, which must be PKCS8

• -t indicates the key type, which must be RSA.

• -b indicates the key size. The customer can configure whatever size they want. The most common sizes are 1024, 2048, 3072, or 4096 bits, with 4096 being the maximum size.

The second command returns the public key in the correct format for use in Anjana. The "nombreClave" parameter will be the key name given in the previous step.

Tot plugins

Each plugin has configuration to allow it to register with multiple Tots and use it as a proxy to register with eureka.

totplugin.server.urls: List of URLs of the Tots the plugin would register with.

Each plugin can register several connections under the same instance. The example YAML available in Nexus shows the configuration in detail, and you can copy, edit, and paste what you need, including field descriptions.

In addition to the common configuration, each plugin has a document for deployment and configuration (with configuration examples).