Configure single sign-on (SSO)

Overview

You can configure Single Sign On (SSO) and role-based security in Geneos and Gateway Hub using LDAP, including an integration with Active Directory. Once configured, users 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 are only available when SSO is enabled with Kerberos.

Prerequisites

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.

Configuration

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.

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

Password The password for the LDAP user when querying LDAP
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.

Role mappings

Map the Geneos roles used to manage permissions in Gateway Hub to LDAP users and groups. Mapping LDAP users directly to Geneos roles is supported but not recommended except for testing and proofs of concept. You can assign LDAP groups and users to have either Administrator or Operator roles in Geneos.

Caution: SSO cannot be enabled unless the configuring user will be an Administrator after the configuration has taken effect. It is important that the Administrator role is bound correctly.

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

Email

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 2 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.

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.

Token configuration

This section allows you to configure security tokens.

Field Description
Check Origin Specify if the origin IP of the token request should be compared against subsequent uses.
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 Gateway access tokens. A token is provided to each Geneos client component when it logs in to SSO and a separate token is provided for each user connection to a Geneos Gateway.
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 2 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.

Enabling SSO

Once you complete the SSO configuration process, the Test and Save function is available to ensure that the configuration behaves as expected before you save it. If the configuration is correct, it will be saved and security will be activated. If it is incorrect, the configuration will not be activated. This prevents you from being locked out of the system.

You can only save the SSO configuration if you were assigned Administrator access according to the role mappings you specified. If you do not have Administrator access, the test will fail and Security will remain inactive.

Once the SSO configuration is active, if you make changes to the configuration Gateway Hub will deactivate security temporarily. This ensures that you will not be locked out if you provide incorrect logic. If the updated configuration tests successfully, security will be re-enabled automatically.