Configure LDAP configuration
Overview Copied
You can configure Single Sign On (SSO) and role-based security in Geneos and Gateway Hub using LDAP (including an integration with Active Directory) 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.
Alternatively, you can use SAML based SSO for Gateway Hub SSO. However, SAML based SSO is not supported by other Geneos components. For more information, see SAML configuration.
Prerequisites Copied
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 an SPN with a set of LDAP credentials is likely to require a change request within your organisation.
Secure LDAP Copied
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:
-
Acquire the LDAP CA certificate from your LDAP administrator.
-
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 -
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 Copied
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 Copied
LDAP SSO is configured using the Web Console. This requires that all previous steps of the installation have been completed, see . 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 Copied
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. If you are using Kerberos, note that the Kerberos Service Principal username may be case-sensitive. Therefore, the username specified here should match the exact case of the username in the KDC. Example: qa\sso |
| Password |
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 Copied
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 |
|---|---|
| User |
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 |
| Surname |
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 |
|
| Groups |
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 Copied
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 Copied
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.
To configure Kerberos by providing a config file:
| Field | Description |
|---|---|
| File location |
The location of the krb5.conf file. Default: |
| Kerberos user |
Optional Kerberos specific username. Note that the Kerberos Service Principal username may be case-sensitive. Therefore, the username specified here should match the exact case of the username in the KDC. |
| 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 Copied
This section allows you to configure security tokens. You can set the token expiration of each field in the following format:
secondsminuteshoursdays
| 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. |