Gateway Hub ["Geneos"]
["Geneos > Gateway Hub"]["User Guide"]

LDAP configuration


You can configure Single Sign On (SSO) and role-based security in Geneos and Gateway Hub. You can configure either LDAP (including an integration with Active Directory) or SAML authentication. Once configured, you can access Geneos with their environment credentials without further password prompts.

You should enable and configure these security features; otherwise full access will be granted to everyone who accesses the API and Web Console. Certain Gateway features such as Gateway centralised configuration should only be used when SSO is enabled with Kerberos.

This document covers the configuration of SSO using LDAP.

For more information about SAML base SSO, see SAML configuration.


Before configuring SSO, you should acquire the following information from a system administrator within your organisation:

  • The credentials to connect to LDAP/Active Directory.
  • The LDAP query to determine the full name and LDAP groups of an authenticated user.
  • The LDAP groups to be assigned to the Administrator and Operator roles.
  • If using Active Directory, request the administrator register the SPN with the LDAP credentials above.
  • The correct Kerberos configuration details, these can be stored in a configuration file on the system such as /etc/krb5.conf.

Note: Registering the SPN that you want to use for Kerberos authentication requires Kerberos (often Windows Active Directory) administration access. This is likely to require a change request within your organisation. For detailed instructions, see Associate the SSO Agent's SPN with its username.

Secure LDAP

To use secure LDAP (LDAPS), you must ensure the CA certificate used by the LDAP service is included in the list of trusted certificates for the Java runtime environment on all Gateway Hub nodes. This list is located in a file called cacerts.

To add the LDAP CA certificate to cacerts:

  1. Acquire the LDAP CA certificate from your LDAP administrator.
  2. On each Gateway Hub node, run the following. You will be prompted for the key file password.
    keytool -importcert -alias MySecureLdap -keystore $JAVA_HOME/jre/lib/security/cacerts -file path_to_ldap_CA_cert.cer
  3. Restart the Gateway Hub apid service:
    /opt/hub/hub-<version>/tools/hub-admin/bin/hub-admin service restart -n apid

When importing the certificate, note the following:

  • The alias must be a unique name that does not already exist in the Java environments keystore.
  • You must run the keytool command as a user with write permission for cacerts.

LDAP status

If you configure LDAP SSO, an information bar is displayed at the top of this page providing the current status.

The LDAP page displays the following status:

  • SSO Working correctly — security is enabled.
  • Not configured — security is disabled.

LDAP Configuration

LDAP SSO is configured using the Web Console. This requires that all previous steps of the installation have been completed, see Install. Once the Web Console is accessible, navigate to the Security section to configure SSO.

Note: When SAML is enabled, you cannot enable Security in the LDAP Config page. You can only enable security from the SAML Config page.

Caution: Until security is configured, anyone with access to the REST API or Web Console has unrestricted access to all administrative functions.

LDAP server settings

The details for the LDAP servers to be connected to are entered in this section. There are two server types supported: Active Directory and Open LDAP. The details of the servers are:

Field Description
Type Specify if the connected system is Active Directory or Open LDAP.
Hosts Specify URLs for the active directory server in the form ldap://host[:port] . If more than one host is provided, a connection will be attempted with each one in order until a successful connection is made.
Query base

The base distinguished name used when querying LDAP. This allows the query to be restricted to a subset of the directory.

Example: DC = itrs

Query user

The LDAP user used to query LDAP. A dedicated user with highly restricted permissions is recommended here.

Example: qa\sso


The password for the LDAP user when querying LDAP.

Mandatory: Yes

Show detailed errors Specify if detailed errors should be returned when there is a problem.

Caution: Showing detailed errors can be helpful when configuring SSO, but is considered a security risk and should be disabled afterwards.

LDAP query

This section allows you to specify the correct LDAP queries for each field in Geneos. The default configuration should be sufficient for most installations.

Field Description

The LDAP database field containing usernames.

Default: sAMAccountName

Display Name

The LDAP database field containing the visible names for each user.

Default: displayname

Given Name

The LDAP database field containing the given name for each user. This field is provided for legacy reasons and will be depreciated.

Default: givenname


The LDAP database field containing the surname for each user. This field is provided for legacy reasons and will be depreciated.

Default: sn


The LDAP database field containing the email address for each user.

Default: mail


The LDAP database field containing the list of LDAP groups each user is a member of.

Default: memberOf


The LDAP query can also be refined using the following optional fields:

Field Description
Users: Class If a custom object is used in the place of Users, specify it here.
Users: Query Filter If a custom object is used in the place of Users, and a User Class isn’t available, a custom query filter to identify users can be specified here.
Groups: Class If a custom object is used in the place of Groups, specify it here.
Groups: Query Filter If a custom object is used in the place of Groups, and a Groups Class isn’t available, a custom query filter to identify groups can be specified here.
Allow group queries Specify if group queries are enabled or disabled. Active Console can provide lists of groups when assigning items, requiring the user to perform a LDAP group query. You may wish to disable this behaviour for security reasons.
Access group The LDAP group required to perform a group query
Token Filter A regular expression (regex) filter that reduces the number of groups the query returns. Only groups containing text that matches the regex will be added to the resulting token. This is useful when users belong to many groups but only a known subset is needed for authorisation.

Authentication protocol

Two authentication protocols are supported, Kerberos and Basic. In almost all circumstances, you should select Kerberos.

Using Basic authentication can be useful for simple tests and proofs of concept. However, Basic is generally not recommended as it is not supported by Gateway functions such as gateway centralised configuration.

Kerberos configuration

This section allows you to perform Kerberos configuration. However, the default configuration should be sufficient for most installations. There are two ways to configure Kerberos using Text or File.

Note: You must ensure all prerequisites are met before configuring Kerberos. If the SPN you want to use for authentication requests has not been associated with the correct LDAP credentials by your security administrators, then Kerberos will not function correctly.

To configure Kerberos by providing a config file:

Field Description
File location

The location of the krb5.conf file.

Default: /etc/krb5.conf

Kerberos user Optional Kerberos specific username.
Password Optional Kerberos specific password.
Reject realm mismatch Specify if Kerberos should reject users with a different realm to the SSO agent.

Note: When using an Active Directory the LDAP server user and password will be used to perform Kerberos configuration by default.

To configure Kerberos using the Web Console:

Field Description
Realm name The Kerberos realm name used by the SSO Agent.
Realm kdc The kdc address.
Config name and Value Specify key and value pairs to configure Kerberos.
Kerberos user Optional Kerberos specific username.
Password Optional Kerberos specific password.
Reject realm mismatch Specify if Kerberos should reject users with a different realm to the SSO agent.

LDAP token expiration

This section allows you to configure security tokens. You can set the token expiration of each field in the following format:

  • seconds
  • minutes
  • hours
  • days

Field Description
Check Origin

Specify if the origin IP of the token request should be compared against subsequent uses.

When the SAML is enabled, the Check Origin option becomes unavailable.

Code The duration for a short-lived code token. This is provided to the web browser when the user logs in to Web Dashboard or Webslinger. The web service uses this code token to obtain an access token for the user session.
Rest The duration for REST command tokens. As this token cannot be restricted to a single process, it is less secure and its lifetime should be limited.
Access The duration for OAuth 2.0 access tokens. A token is provided to any client component when it requests access to the REST API using SSO.
Refresh The duration for a refresh token. This is used to obtain a new Access token without requiring the users to re-authenticate themselves, as long as the Active Directory groups of the users have not changed since the refresh token was initially granted. When this token expires the user needs to re-authenticate, which is handled automatically by Active Console and the Web Console. The duration for this token can be longer-lived than the others.
Webslinger and Web Dashboard locations Specify the URLs for instances of Webslinger and Web Dashboard. This allows automatic redirects after authentication.

Rotating passwords

If you have an automatic process that rotates SSO account passwords, then you must also configure it to update the passwords that Gateway Hub uses.

Gateway Hub contains scripts to enable you to manage password changes. You can find the script in the <hub_home>/hub-current/services/apid-<version> directory. To update a password run: <new password>

If Gateway Hub's LDAP query user or Kerberos user becomes locked out you will not be able to sign into the Web Console.

To avoid this, you may want to temporarily disable security. To do this, use the script located in the same directory.