Admin Overview

The administration tab is divided into multiple sections covering a variety of administrative actions, as detailed below.

Account Information

This section is to view installation metadata to help customers work with Heimdall Support in enrolling for complimentary support. Account ID is an GUID of the installation, while Registered ID is provided from Customer Support to verify enrollment. Enrollment can be confirmed by a checkmark next to the field (as well as the removal of the UNSUPPORTED banner) see below:

License Configuration

In this section, a new license file can be uploaded when provided by Heimdall, and the current settings and license use can be observed. In Demo mode, up to 4 LB servers can be used, and up to four VDBs with rules (optimizations) can be enabled for 30 days. The used count is only based on VDBs that have received traffic in the last 30 seconds, so will dynamically account for activity. If the used values surpass the allowed values, then a warning will be displayed on the console, but no restriction in features will be enforced. License handling is strictly advisory, i.e. while the system may complain about a license being invalid, it will not restrict what is done, to insure no outages occur as a result of licensing.

Note: When using an AWS paid-for instance, the proxy use on the instance will not count toward license use. Additionally, added paid-for instances can be reconfigured to be a pure proxy instance and will also not count to license use on another management server.

Log Management

Log Files Management

This section is provided to assist in managing log files and configuring data source used for logging. Core dumps are files that are generated by the operating system when a program terminates abnormally, such as by crashing or encountering an error. Heap dumps are files that contain a snapshot of the Java Virtual Machine (JVM) heap at a specific point in time. This functionality is removing all core files from /var/lib/systemd/coredump folder and also core files and heap dumps files from the project directory.

Log Database Management

By default, an embedded database supplied with Heimdall is used to store logs and statistics, however there is an option to select user configured data source (MySQL, PostgreSQL, Oracle and SQL Server supported). If Heimdall is unable to establish connection to selected source at any point it will fall back to using embedded one. User configured in selected data source has to have database root privileges.

S3 Log Bucket Configuration

In this section, we can configure log uploads to S3. There is an option to specify the S3 bucket where the logs should be saved.

Security Tags

This section allows for the management of security tags, which can be applicable in the database browser section of Source tab. Each resource (i.e. databases, schemas, tables, views, columns) in the database browser can be tagged with one or more tags. The admin can select a specific tag from the dropdown and filter out the tagged resources.

Warnings:

1. If you delete a resource in your database that had assigned security tags and later decide to recreate it, it will inherit those tags.
2. If you change the name of a given resource in your database, the security tags assigned to it will be lost.

Software Management

This section allows for management of the software. In the first dropdown, you can select a version of code to update to. Release is the normal release train of code, test versions are generally just before a new release, and development are the often daily updates that have completed regression testing. Customers will often be asked to update to the development build if they have encountered a problem and want to apply the fix for it. To apply a particular version, select the version in the dropdown, then click "Update via Repository". Please note, if you have independent proxies running (vla NLB or as a service), you will need to restart them independently as well. To check the version of code each proxy is running, please refer to the status tab.

Note: Any build pushed as a development build have passed all regression testing that any previous version has passed. What may not yet be complete are regression tests for the new changes, which often are developed in parallel with customer testing of the changes. This can result in frequent development builds, but allows for rapid test/fix/deploy cycles during customer POC processes. Once a POC is completed, we will work with customers to schedule a full release build for use in production that has completed full and updated regression testing.

You can also update the version of Heimdall by providing the url link to the zip file, complete this action using Update via URL button.

In the event that you want to update to a particular version of Heimdall that was provided to you as a zip file, you can use the third section for a manual update. Simply select the heimdall zip file, then update via File.

The next option is the Shutdown/Restart Heimdall button, which will not explicitly trigger a restart, but will rely on any restart mechanisms on the server to trigger the actual execution of the server after it terminates.

In the event you need to download the Heimdall driver (say to use as a jdbc driver) the next option "Download Heimdall Driver" can be used.

If you need to roll back to a previous version of the system, the quickest way is to use the "Rollback Version" button. Heimdall stores two versions of the system - the current and the previous - and you can swiftly switch between them.

Following is the release notes link, for the most current release notes.

Note, for command line manual update, please do the following:

1) copy the file into the install directory as heimdall-new.zip 2) cd to install directory 3) execute the following commands:

* sed -i "s/\s*\"modules\/.*\",*//g" config/heimdall.conf
* unzip -j heimdall-new.zip

4) kill and restart the heimdallserver.jar process: ps auxw | grep heimdallserver.jar root 4198 0.0 0.0 6100 624 pts/0 S+ 18:03 0:00 grep --color=auto heimdallserver.jar root 26005 30.8 4.0 9679444 638504 ? Sl 17:58 1:25 java -server -XX:+ExitOnOutOfMemoryError -jar /opt/heimdall/heimdallserver.jar

kill 26005

The next option is the Migration button, which initiates the download and execution of the 'heimdall-migration.sh' script. The script carries out all necessary actions to meet the requirements for the upcoming release.

Current migration steps:

1. Install Java 17 and set it default

2. Update heimdall-entrypoint.sh script

If there will be an issue with download file, you will receive an error with link to the script:

If you encounter this issue, proceed to download the migration script manually here. Before executing the script, ensure it has the necessary execute permissions:

chmod +x heimdall-migration.sh

To manually run the migration script on the Heimdall Manager host, use the following command:

bash heimdall-migration.sh

If an error occurs during migration with retrieving the latest file heimdall-entrypoint.sh, it should be downloaded from here, placed on the host where migration is being conducted, and the path to it should be provided as an argument to the script:

For example: bash heimdall-migration.sh /tmp/heimdall-entrypoint.sh

Alerts

This section provides a list of any alerts that have been dismissed with the check. Any alerts in this list will not be shown in the top of the GUI until cleared.

Sending alerts via notification: If this option is checked, every alert which message doesn't match any added pattern, will be sent via notification. If no pattern is added, all alerts will be sent via notification.

Notifications

This section provides the capability to create group notifications. Users can choose from three supported protocols: AWS SNS, LDAP, or SMTP. Additionally, there is an option to view the list of emails associated with a particular entry by clicking the envelope icon. This will display a popup showing the email addresses.

System notification: This option allows to choose which notification config is used as system notification and will be used to send various system messages, such as alerts by default.

When choosing AWS SNS for email (and potential SMS) notifications, it will require Heimdall to be hosted on the AWS platform, having appropriate AWS IAM roles and permissions configured to interact with AWS SNS.

When choosing SMTP, user will be able to define his mailing list (from existing Heimdall defined users in Users tab). Also, please remember to configure SMTP client in the Admin tab -> Smtp Configuration.

Additionally, it's possible to create a "none" type notification, meaning without specifying any group or recipients. This is used in portal mode, where it can be assigned to a Role Config that should be auto-approved. Such empty notifications without recipients can only be created with the SMTP protocol.

After making any changes, they must be submitted using the Commit button.

Portal

The "Portal Basic" section is generally used to configure settings related to the portal. Within it, we can define the LDAP configuration, from which portal users will be sourced, the data source where portal data will be stored, and several checkboxes.

• Portal data source - Data source where portal data will be stored.
• Portal Host - Indicates the portal host and is included in portal notifications to facilitate quick access to the correct URL. If the field is empty, this information will not be included in emails.
• Show approvers emails - If selected, it will be possible for all users to view approvers' emails for a specific role. Admins can always see these emails, even without the checkbox being checked.
• Send audit logs to CloudWatch - Indicates whether the audit trail logs should also be saved in the AWS CloudWatch.
• CloudWatch namespace - The namespace specified in this field will be used as the log group name in the AWS CloudWatch. If left empty, audit logs will be sent to the default namespace: HEIMDALL-mgmt, provided that logging is enabled in Server Properties.
• Synchronize Portal Users - Indicates that if the LDAP Group Filter matches, Heimdall (GUI) users will be created automatically.
• Require specific justification format - If selected, there is an option to specify the regex that the justification must match when requesting a session.
  • Regex pattern - Specifies the regex that must be matched in the justification field.
  • Invalid justification message - Specifies the message to appear when requesting a session if the justification content does not match the configured regex.

To simplify portal configuration, three additional sections are available below: one for Notifications, the second for Data Source, where you can configure Group Mapping and Roles Management, and the third (Users) for setting portal users and manually assigning them groups.

For more complex configurations, it is recommended to configure them in the dedicated tabs intended for each specific setting.

SMTP Configuration

This section provides the functionality to establish SMTP configurations for email dispatch. Users can adjust the configuration to their preferences, by incorporating relevant properties in the SMTP Properties section (available properties can be found here: https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html ). The Heimdall team recommends users set the ssl protocol to TLSv1.2 or TLSv1.3, otherwise TLSv1 might be used. The Email Tester component, allows users to validate configuration before committing changes by sending a test email. If changes will are not committed, all entered configuration will be lost. While using e.g. Google smtp, user should consider using application password rather than their personal password - especially if the account has 2fa enabled, then without app password functionality might have problem to operate. The password can be stored in a secret and this secret must contain at least password, email is not required. An email from a secret has higher priority than email from GUI config.

Login History

This provides the login times, account ID and source IP of the recently recorded GUI logins.

Unchecking 'Exclude proxy logins' will result with adding proxy logins to the list.

Cache Drivers

This section allows a cache driver (specifically Hazelcast) to be uploaded for use by Heimdall instead of the built-in driver. This allows the driver to match what may exist in a customer's environment if our version causes a conflict.

Server Properties

These are properties that can control overall Management server behavior, and will be added to over time. Current properties supported.

• Disable Cert Validation: Disable TLS certificate validation for software downloads (Boolean)
• Enable Portal Mode: Value that indicates if after successful login central manager or portal mode will be used (Boolean)
• Minimum free disk space %: configured how much space needs to be free for any configuration saves to occur. Defaults to 1 for 1%. This helps prevent configuration loss if not enough space is available to successfully save the full configuration. (Double)
• Log Events To Console: For debugging or container use, log ALL events to the stdout console of management server (Boolean)
• Max Log Age: Sets the maximum age in days of log files and log records (Integer)
• Enables password validation: Validate new users password along with provided rules (Boolean)
• Proxy Host: If a proxy is needed to access the Internet for code update notifications and downloads, the host to use for this (String)
• Proxy Password: Proxy password for proxy authentication, no default (String)
• Proxy Port: The port defaults is 3128 (Integer)
• Proxy User: Proxy user for proxy authentication, no default (String)
• Redirect Config Fetches: Value that indicates if server should redirect all HTTP config requests to HTTPS Tomcat port (Boolean)
• Reserved Disk Space: Sets the amount of FREE memory to maintain on the log filesystem (Double)
• Verbose Debug Mode: On the server, enable verbose debug mode (Boolean)
• Session Timeout: Controls HttpSession idle-timeout expiration (default value is 30 minutes) for GUI users
• Log Rotation Interval: A period between log rotation (in minutes)
• Enable Manager CloudWatch Logging: Value that indicates if manager logs should be sent to AWS CloudWatch. May incur additional AWS charges (Boolean)
• Max Config Backups: Value that indicates how many backups of configuration to keep. Default value is 10 (Integer)

Modules

Allows modules to be added or removed as needed. The fewer the modules, the faster a Heimdall node can startup. In particular cache modules that are unused should be deleted as some can add significant load time.

Password Policies

This section allows user to set up requirements that specific user password must meet to be created/updated. Current rules supported:

• minimum/maximum of characters - minimum/maximum number of characters that password must contain (with minimum/maximum parameter tht defines the limit).
• digits requirement - rule defining that password must contain at least one digit
• special marks requirement - rule defining that password must contain at least one special mark
• uppercase character requirement - rule defining that password must contain at least one uppercase character
• custom regex matching - rule that provides a pattern parameter with the regular expression to which password must match

The Password Policies apply to GUI Heimdall users but do not extend to users with external passwords, such as those using LDAP, Kerberos, or Secrets Manager.

Config Management

This section allows editing startup /etc/heimdall.conf configuration file, which can be used to populate environmental variables or cloud environments. More details in Heimdall Environmental Variables.

When hdRole is set to proxy, the secrets can be used for the proxy authentication.

AWS Endpoints

This section allow to configure alternate endpoints for AWS services. If alternate secrets manager endpoint is passed, secrets will be used even if cloud option is not set to AWS.

Identity Providers

Heimdall supports a variety of identity providers to authenticate users for various situations. This includes:

• Secrets Managers (AWS Secrets Manager, Cyberark Conjure and Hashicorp Vault)
• Kerberos Domains
• LDAP (AD, Jumpcloud, Okta, Redhat ID Manager, OpenLDAP, and others)
• SAML (AWS Identity Center, Okta, and others)

To begin to configure any of these, in the admin tab, please go to proper tab and follow the steps in the instruction.

Secrets Manager Configuration

This section allows to configure Secrets Manager that will be used across Heimdall services.

Remember that if you want to use the secrets manager, it has to be enabled.

Currently supported settings:

Default

By default, 0 Secrets Managers are configured. Secret options will be disabled.

AWS Secrets Manager

When running in AWS environment it will be added by default. Does not require additional configuration.

Currently, it is possible to have only one secrets manager of this type.

CyberArk Conjur

Following properties are available for CyberArk's Conjur connection configuration:

• Appliance URL: The URL of the Conjur instance you are connecting to. When connecting to Conjur Enterprise configured for high availability, this should be the URL of the master load balancer (if performing read and write operations) or the URL of a follower load balancer (if performing read-only operations).
• Account: Conjur account that you are connecting to. This value is set during Conjur deployment.
• Authn Login: User/host identity.
• Authn API Key: User/host API key (or password).
• Authn URL: (optional) Alternate authentication endpoint. By default, the client uses the standard <applianceUrl>/authn for generic username and API key login flow.

Currently, it is possible to have only one secrets manager of this type.

Hashicorp Vault

Following properties are available for Hashicorp Vault server connection configuration:

• Vault URL: The URL of the Hashicorp Vault instance.
• Token: Token used for authentication. It should have permissions appropriate to access deserved secret values.
• Engine Version: The version of Secrets Engine. If you are using only one KV engine choose the correct version (by default it is 2). If you are using both KV engines, set it as 1 and remember the about /data part in the secrets API path. For others, engines set it as 1.

Some parts in the secret path will be automatically put into our requests. If the full secret API path is /v1/kv/data/test/secret then: * kv is the name of the Secret Engine. * test/secret is the name of the secret.

v1 and data parts will be automatically injected into the final request url. In such case the secret path that You should put into our GUI is kv/test/secret.

It is possible to have multiple secrets managers of this type.

Testing secret manager

Before clicking the "Test secret retrieval" button, please make sure that you click the "Commit" button to test the newest configuration.

Kerberos Configuration

This authentiation type allows configuring Kerberos to authenticate users in the Heimdall Manager.

Option Name	Default Value	Description
Enable Kerberos Authentication	---	Enable Kerberos Authentication for Heimdall Manager
Service Principal	HTTP/localhost	Identity for a service instance in Kerberos
Keytab Location	/etc/krb5.keytab	File path to the file that stores pairs of Kerberos principals and their corresponding encrypted keys
Enable LDAP Groups Extraction	---	Perform LDAP groups extraction on successful authentication
LDAP Configuration	---	LDAP Configuration used for groups extraction

LDAP Configuration (Proxy & Central Manager)

LDAP Authentication provides authentication with using of LDAP server. LDAP Authentication provides two modes of authentication:

• Bind + Search Mode - authentication is made by binding to server as admin and searching information about authenticated user;
• Simple Mode - authentication is made by binding to server as authenticated user.

Bind + Search Mode

To configure Bind + Search Mode, below options can be set.

LDAP option	Required?	Description	Example value
LDAP(S) URL	yes	Specifies URL of LDAP server. Instead of just one URL, you can also supply a space-separated list of URLs. In this case, the LDAP provider will attempt to use each URL in turn until it is able to create a successful connection.	ldap://server.example.com:389
Server Type	yes	Specifies the type of LDAP Server	RedHat IDM (FreeIPA)
LDAP Security Principal	yes	Specifies name of user used to search for authenticated user	CN=ro-admin,CN=Users,DC=example,DC=com
LDAP Sec. Security Principal	no	Specifies name of user used to search for authenticated user in case the primary search with LDAP Security Principal fails.	CN=admin2,CN=Users,DC=example,DC=com
LDAP Search User Password	yes	Specifies password for LDAP Security Principal user used to search for authenticated user	examplepassword123
LDAP Sec. Search User Password	no	Specifies password for LDAP Sec. Security Principal.	examplepassword321
LDAP Search Domain	yes	Specifies LDAP search domain, the domain in which authenticated user's groups will be searched.	DC=example,DC=com
LDAP User Search Base	yes	Specified LDAP user search base in which authenticated user will be searched.	CN=Users,DC=example,DC=com
LDAP Name Attribute	yes	Specifies name attribute by which authenticated user	sAMAccountName
LDAP Group Name Attribute	no	Optional, specifies group's name attribute which should be read during extracting authenticated user's groups. If not provided, LDAP Name Attribute will be used instead.	CN
LDAP Group Filter	no	Optional, option used during searching for authenticated user. Setting this option limits the number of groups to search user into them, only to particular group inside server. Setting this option makes it required to extract at least one group to authenticate the user.	(DistinguishedName=CN=group1,CN=Users,DC=example,DC=com)
Use nested groups filter	-	Specifies if parent groups should be included, when searching for user's groups.	-
Ignore LDAP Cert	-	Specifies if TLS validation of LDAP server certificate should be performed	-
LDAP Healthcheck	no	Performs LDAP Healthcheck automatically every minute. An appropriate alert will be shown if the server goes down (Similarly, once the server is back online). Moreover, the account expiration date of the LDAP Security Principal will be checked once every 24 hours.	-
Management privileges	no	Determines whether it entitles a user to use admin/read only privileges by requiring membership in a specific group.	-
Admin privilege group	no	To be authorized to use the Management Privilege: Admin, the user must be a member of the selected group.	-
Read Only privilege group	no	To be authorized to use the Management Privilege: Read Only, the user must be a member of the selected group.	-

By choosing option Simple LDAP Mode, you can switch to Simple Mode.

Advanced group filter

LDAP group filter is used to limit number of groups for look up for authenticated user. Example value describes filter limiting number of groups to only one particular group, but this option value is added as written, what enables writing more complex filters. Please look on below example.

Let's assume that we want our user be from groups group1 or group2. By knowing the syntax of search filter used in LDAP server we can set LDAP Group Filter as:

(|(DistinguishedName=CN=group1,CN=Users,DC=example,DC=com)(DistinguishedName=CN=group2,CN=Users,DC=example,DC=com))

Important: If there is an LDAP Group Filter specified at least one group has to be extracted to authenticate the user.

LDAP Healthcheck

If enabled, performs in the background automatically every minute and may result in two alerts: once the server is down, and once the server is back online.

Nevertheless, it can be performed on demand by using the button with hearth - if used, the JSON with the details of LDAP Healthcheck result will be opened in the new tab.

Important: LDAP Healthcheck on demand will be performed on ALL configurations with LDAP Healthcheck checkbox enabled.

Secrets Manager for LDAP Security Principal

When there is Secrets Manager configured there is additional option available represented as a checkbox located beside both Security Principal inputs. When enabled, instead of Search Password, Secret Name can be typed. After commiting the changes the credentials for Security Principal will be automatically fetched and cached on both manager and proxy instances. This configuration supports rotating passwords, which means that in case of connection failure (due to credential rotation most likely) the system will silently pull the newest values and try to establish the connection again.

For those utilizing a custom secrets manager, it is imperative to adhere to the structure outlined in AWS RDS secrets manager. For instance, the JSON format should resemble the following: {"username":"test","password":"test"}.

Simple Mode

Simple Mode is simpler mode than Bind + Search mode, because uses only one request (which is binding request) to LDAP server.
Simple Mode can be turned on by choosing Active Directory (LDAP) Auth Enabled checkbox, and then choosing Simple LDAP Mode checkbox. Simple Mode requires to set below options to work properly.

LDAP option	Required?	Description	Example value
LDAP(S) URL	yes	Specifies URL of LDAP server. Instead of just one URL, you can also supply a space-separated list of URLs. In this case, the LDAP provider will attempt to use each URL in turn until it is able to create a successful connection.	ldap://server.example.com:389
LDAP Prefix	yes	Specifies prefix used in during bind authenticated user to LDAP server	CN=
LDAP Suffix	yes	Specifies suffix used in during bind authenticated user to LDAP server	,CN=Users, DC=example, DC=com

To understand working of this mode, should be known that send request is binding composed of three parts: prefix + username + suffix. For given example values and user exampleuser, binding request would look like CN=exampleuser,CN=Users, DC=example, DC=com.

Central Manager Information

If you want to authenticate CM user, in the Users tab you should create new user(-s) with the same name as in your active directory. During creating new user don't forget to mark the "Authenticate By LDAP" option.

LDAP Configuration Wizard

The LDAP Configuration Wizard is provided to simplify configuration process as much as possible. It's a walk-through tool preventing from going forward if provided configuration is not valid. It can be accessed by clicking the "LDAP Wizard" button in the LDAP Configuration section.

Bind + Search Mode

There is the list of information necessary to finalize the Wizard Configuration:

• LDAP(S) URL - Specifies URL of LDAP server.
• Ignore LDAP Cert - Specifies if TLS validation of LDAP server certificate should be performed.
• LDAP Security Principal - Specifies name of user used to search for authenticated user.
• LDAP Sec. Security Principal - Specifies name of user used to search for authenticated user if the primary search fails.
• LDAP Search User Password - Specifies password for LDAP Security Principal user used to search for authenticated user.
• LDAP Sec. Search User Password - Specifies password for LDAP Sec. Security Principal user used to search for authenticated user.
• LDAP Security Principal Secret Name - Specifies the name of a Secret containing the credentials (user/username and password) of the LDAP Security Principal. Available only if 'Secret' is enabled.
• LDAP Sec. Security Principal Secret Name - Specifies the name of a Secret containing the credentials (user/username and password) of the LDAP Sec. Security Principal. Available only if 'Secret' is enabled.
• LDAP Search Domain - Specifies the domain in which authenticated user's groups will be searched.
• LDAP User Search Base - Specifies user search base in which authenticated user will be searched.
• LDAP Name Attribute - Specifies attribute which should be used to identify a user.
• LDAP Group Name Attribute - Specifies attribute, which should be used to extract information about a group (Optional).
• LDAP Group Filter - Specifies group filter, which will be added during a search for a user's groups (Optional).
• Use nested groups filter - Specifies if parent groups should be included, when searching for user's groups.
• LDAP Healthcheck - Performs LDAP Healthcheck automatically every minute. An appropriate alert will be shown if the server goes down (Similarly, once the server is back online).
• Cache groups' emails - Specifies whether emails for LDAP groups should be cached (applies only if LDAP configuration is linked to the portal configuration).
• Cache time - Specifies the interval at which emails in the cache should be updated.
• Management privileges - Determines whether it entitles a user to use admin/read only privileges by requiring membership in a specific group.
• Admin privilege group - To be authorized to use the Management Privilege: Admin, the user must be a member of the selected group.
• Read Only privilege group - To be authorized to use the Management Privilege: Read Only, the user must be a member of the selected group.

Service Account Validation

At the very beginning, the absolute basis of the correct and valid configuration:

• The fields above are required as the authentication is made by binding to server as admin and searching information about authenticated user.
• The grayed-out "Verify" button will remain gray until all required fields are filled in.
• When all the required fields are filled in, the button will turn green and when pressed, the connection to AD will be attempted.
• If it fails, a corresponding message with the reason for the error will be displayed.
• if it succeeds, the next Wizard stage will be unlocked.

If one of available Secrets Managers is configured in Admin -> Secrets Manager Configuration, then it can be used to provide credentials for LDAP (Sec.) Security Principal.

In such case it is obligatory to provide either '${username}' or '${user}' placeholder where the actual username (retrieved from Secrets Manager, based on LDAP (Sec.) Security Principal Secret Name) has to be injected in the distinguished name (DN).

Wrong way: Good way:

Users & Groups Search Details

The next step is necessary to properly look for information about the user being authenticated and the groups he belongs to + set whether nested groups should be searched for.

• In order to simplify configuration some of the fields can be filled using dropdowns (LDAP Search Domain and LDAP Search Base contains all possible options straight from LDAP Server).
• LDAP (Group) Name Attribute contains all attributes which are actually used among all configured users / groups with additional counter of how many users / groups actually contain particular attribute.
• Additional "Example users found" row will be shown after LDAP Name Attribute selection. This row is just a preview and has no affect on the final configuration, but what is important - these values will be treated as logins for users to authenticate.
• Caching emails for LDAP groups is enabled by default, with a cache update time of 1 hour. This can be customized to fit your needs or disabled altogether. However, the minimum update time must be at least 5 minutes.
• All of these fields can be customized after checking suitable checkbox on the right.
• When all the fields are filled in, the button will turn green and when pressed, the attempt to find Groups configured on the server will be performed.

LDAP Group Filter Creation

The almost last step of the Wizard is to select Groups of interest for the DB i.e. Groups which will be relevant to database roles. Based on the selected Group the LDAP Group Filter will be generated when you click "Generate Filter" button. If no group is selected then no filter will be provided and this is ok - LDAP Group Filter is optional.

Management Privileges

As an option, Management Privileges can be enabled to enhance security. When activated, only members of the specified groups will have access to the assigned in the Users tab Admin or Read-Only privileges.

Authentication Checker

Provided configuration can be verified with the last part of the LDAP Configuration Wizard - Authentication Checker. In case of successful authentication extracted groups will be listed, as long as LDAP Group Filter is specified.

Simple Mode

In Simple Mode, unlike Bind + Search Mode, only the url suffice to start the configuration. Nevertheless what is important, the LDAP Configuration Wizard does not work with Active Directory, as this one has a strong security authentication and requires a successful bind before any data can be retrieved. Regardless of the success of the scan the next part of the Wizard wll be unlocked.

After successful scan all possible LDAP Prefixes and LDAP Suffixes will be available in a drop-down list. After failed scan drop-down lists will be empty, nevertheless both these fields can be customized after checking suitable checkbox on the right.

At this point your Simple LDAP Configuration is complete and after saving it can be found under "LDAP Configuration".

SAML 2.0 Configuration Guide

Heimdall supports Single Sign-On (SSO) through SAML 2.0, allowing authentication via external Identity Providers (IdPs) such as AWS IAM Identity Center, Okta, and others.

---

🔧 Required Configuration Parameters

Parameter	Description
SAML Configuration Name	A user-friendly name for the SAML configuration.
IdP Metadata URL	The URL pointing to the Identity Provider’s metadata.

---

🚀 Setting Up SAML with AWS IAM Identity Center

This guide explains how to configure SAML authentication with AWS IAM Identity Center using SAML 2.0 to enable Single Sign-On (SSO).

Create a New Application in AWS

1. Go to IAM Identity Center → Applications
2. Choose: Customer managed → Add application
3. Select:
   • Setup preference: I have an application I want to set up
   • Application type: SAML 2.0
4. Fill in the Display Name and Description
5. Application properties are optional and may be left unspecified.

Obtain Metadata URL

On the IAM Identity Center metadata section, AWS will provide a SAML metadata file URL.
This will be used in Heimdall during the SAML setup.

---

⚙️ Configure Application Metadata in AWS

You have two options to configure metadata in AWS:

---

Option 1: Manually type your metadata values

Application ACS URL:
(Replace <heimdall_hostname> with your actual hostname) http://<heimdall_hostname>:8087/login/saml2/sso/heimdall https://<heimdall_hostname>:8443/login/saml2/sso/heimdall

Application SAML Audience: (Replace <heimdall_hostname> with your actual hostname) http://<heimdall_hostname>:8087/saml2/service-provider-metadata/heimdall https://<heimdall_hostname>:8443/saml2/service-provider-metadata/heimdall

⚠️ Important:
These URL paths (/login/saml2/sso/heimdall and /saml2/service-provider-metadata/heimdall) must not be changed.
Altering them may result in SAML not working properly.

---

Option 2: Upload application SAML metadata file

1. In Heimdall Central Manager:

   • Log in with admin privileges
   • Navigate to: Admin → SAML Configuration
   • Fill in:
     • SAML Configuration Name
     • IdP Metadata URL (e.g.
       https://portal.sso.us-east-1.amazonaws.com/saml/metadata/<random_string>)
   • Click Commit
   • Restart Heimdall Central Manager

   

2. After the restart, download the metadata file from heimdall endpoints:

   • http://<heimdall_hostname>:8087/saml2/metadata
   • https://<heimdall_hostname>:8443/saml2/metadata

   ℹ️ Note:
   The SAML configuration XML is retrieved from a metadata URL (/saml2/metadata endpoint) via HTTP or HTTPS. The retrieved XML contains URLs that reflect the same protocol used during retrieval. AWS will subsequently use the same protocol (HTTP or HTTPS) found within the retrieved XML for communication. Users should therefore be mindful of the protocol used when accessing the metadata URL, as this will dictate the protocol AWS employs.

3. In AWS IAM Identity Center:

   • Choose: Upload application SAML metadata file
   • Upload the file downloaded from Heimdall

AWS will auto-fill the ACS URL and Audience based on the uploaded file. The values should look like that:

---

✅ Assign Users to the Application

Don't forget to assign users to the SAML application in AWS IAM Identity Center.
Without this step, users will not be able to authenticate via SAML.

To configure the attribute mappings in AWS Identity Center, navigate to the application settings and select "Edit attributes mappings".

The Subject attribute must be mapped correctly, into ${user:subject}. Additional attribute mappings are optional and can be configured as needed to meet specific application requirements (aws docs: https://docs.aws.amazon.com/singlesignon/latest/userguide/attributemappingsconcept.html#supportedssoattributes). After adjusting, click Save changes.

👤 Enabling SAML Authentication for Heimdall Users

1. In Heimdall, go to the Users tab
2. Click Create New User
3. Check: Authenticate By SAML2
4. Save the user

Now, when the user clicks Login with SAML (!use proper protocol of HTTP/HTTPS as configured on the aws), they will be redirected to AWS for authentication and then back to Heimdall as a logged-in user.

Upon successful authentication, the user will be automatically redirected to the Heimdall application as an authenticated user. For successful SAML2 authentication via AWS, the username used must exactly match a pre-existing username within the Heimdall user directory.

🔒 Important Notes:

• Logging out of Heimdall does not automatically log the user out of AWS IAM Identity Center.
• All SAML-authenticated users must be explicitly assigned to the application within AWS Identity Center under the Assigned users and groups tab.
• Mixing HTTP and HTTPS flow is not allowed! AWS configurations using HTTPS require a consistent HTTPS authentication flow. Users accessing the Heimdall login page must do so via HTTPS (e.g. https://<heimdall_host>:8443/#/login). Inconsistent use of HTTP within an HTTPS configured environment may lead to authentication failures and prevent successful login.
• If you encounter issues during login, try using your browser's Incognito/Private Mode. This helps eliminate the chance of lingering sessions or cached credentials interfering with the SAML login flow.

---

🚀 Setting Up SAML with Okta

Heimdall Central Manager & Portal Integration with Okta

This guide explains how to configure SAML authentication with Okta using SAML 2.0 to enable Single Sign-On (SSO).

---

Create a New Application in Okta

1. Create or log in to your Okta developer account.
2. Navigate to Applications → Create App Integration.
3. Select SAML 2.0 and click Next.
4. Name your application and click Next.

Configure SAML Settings

Use the following configuration:

• Single sign on URL:
  (Use either HTTP or HTTPS consistently across the entire setup and future logins) http://<heimdall_hostname>:8087/login/saml2/sso/heimdall https://<heimdall_hostname>:8443/login/saml2/sso/heimdall

• ✅ Use this for Recipient URL and Destination URL (default)

• Audience URI:
  http://<heimdall_hostname>:8087/saml2/service-provider-metadata/heimdall https://<heimdall_hostname>:8443/saml2/service-provider-metadata/heimdall

Finalize App Setup

Click Next, then select: - I’m an Okta customer adding an internal app - This is an internal app that we have created

Click Finish.

Retrieve Metadata URL

On the Sign On tab, copy the Metadata URL, e.g.: https://dev-82243426.okta.com/app/<random-characters>/sso/saml/metadata

Step 5: Assign Users or Groups

Go to the Assignments tab in your Okta app and assign access to users or groups.

---

🛠️ Configure SAML in Heimdall

1. Log in to Heimdall Central Manager with admin privileges.
2. Navigate to: Admin → SAML Configuration
3. Fill in the following:
4. SAML Configuration Name
5. IdP Metadata URL, e.g.:
   https://dev-82243426.okta.com/app/<random_string>/sso/saml/metadata
6. Click Commit
7. Restart Heimdall Central Manager

---

👤 Enable SAML Authentication for Heimdall Users

1. Go to the Users tab in Heimdall.
2. Click Create New User
3. For Okta users, enter the user's email address instead of a username (as Heimdall will authenticate based on the data returned by Okta —i.e., email).
4. Check the box: Authenticate By SAML2
5. Click Save

---

🔑 Logging In via SAML (Okta)

Once configured:

• Users can click Login with SAML on the Heimdall login page (!use proper protocol of HTTP/HTTPS as configured on okta).
• They will be redirected to Okta for authentication.

• Upon successful login, they will be returned to Heimdall as authenticated users.

---

🔒 Important Notes:

• Logging out of Heimdall does not automatically log the user out of Okta.
• All SAML-authenticated users must be explicitly assigned to the application within Okta under the Assignments tab.
• Mixing HTTP and HTTPS flow is not allowed! Okta configurations using HTTPS require a consistent HTTPS authentication flow. Users accessing the Heimdall login page must do so via HTTPS (e.g. https://<heimdall_host>:8443/#/login). Inconsistent use of HTTP within an HTTPS configured environment may lead to authentication failures and prevent successful login.
• If you encounter issues during login, try using your browser's Incognito/Private Mode. This helps eliminate the chance of lingering sessions or cached credentials interfering with the SAML login flow.

TCP

This allows checking if given port is available. Host is optional, if it isn't provided, it is set to "localhost".