SSO Agent User Guide

Overview

The ITRS SSO Agent is a Java application that acts on behalf of Geneos components to authenticate users against the Windows Active Directory.

If a user is logged into Windows on a computer in the same domain as the SSO Agent, the Active Console 2 can present their credentials to the SSO Agent without prompting them for a user name or password. Web browsers running on Windows or Linux can also be redirected to the SSO Agent by Webslinger or Web Dashboard to authenticate a logged-in user without prompting for their user name or password. To do this, SSO Agent uses the Kerberos protocol. As a fallback, it can also use HTTP Basic authentication, in which case the user is prompted for their credentials.

In each case, the SSO Agent generates SSO tokens that are used by the Geneos components to determine the user’s Geneos permissions. User authentication (checking identity) is handled by the SSO Agent, while user authorisation (checking permissions) is based on the LDAP groups the user belongs to and used to identify Geneos roles set up in the Gateway configuration. Once Geneos roles have been set up and associated with LDAP group names, administrators can add, modify, or remove users using only Active Directory tools.

The Geneos components that use ITRS SSO Agent are:

  • Active Console 2
  • Gateway
  • Web Dashboard
  • Webslinger

Intended audience

This guide is directed towards Geneos administrators who want to set up single sign-on (SSO) on their organisation's Geneos implementation.

Prerequisites

System requirements

The SSO Agent is a 64-bit Java application. It has the following requirements:

Component Recommended Setup
Operating System

Windows

Linux

CPU Multicore Intel / AMD
Memory 4 GB
Disk 500 MB available space
Network 1 Network Interface Card
Java (JRE) Version 8 (tested with java version 1.8.0_144)

See the Geneos Compatibility Matrix for the list of supported platforms and web browsers.

Active Directory requirements

Before setting up the SSO Agent, you need to acquire the following information from a system administrator within your organisation:

You also need to arrange for the Kerberos administrator in your organisation to associate the SSO Agent's Service Principal Name (SPN) with its username. See Associate the SSO Agent's SPN with its username.

SSO Agent introduction

SSO Agent authentication methods

The SSO Agent supports two authentication methods:

  • Kerberos/SPNEGO (Negotiate)
  • HTTP Basic authentication (BASIC)

Most client applications try to authenticate using Negotiate first and fall back to Basic authentication if Negotiate fails.

Note: An SSO Agent binary that supports NTLM (NT LAN Manager v2) as an additional authentication method is available on request. This SSO Agent binary can only run on Windows. Please contact ITRS Support for more information.

SSO Agent configuration

The configuration of the SSO Agent is contained in the file sso-agent.conf, which is located in the conf directory of the SSO Agent package. This file uses Human-Optimized Config Object Notation (HOCON), which is based on JSON but with a more editor-friendly syntax.

Download and unpack the files

  1. Download the SSO Agent package sso-agent-<version>-bin.zip from the ITRS Downloads site.
  2. Note: An SSO Agent binary that supports NTLM (NT LAN Manager v2) as an additional authentication method is available on request. This SSO Agent binary can only run on Windows. Please contact ITRS Support for more information.

  3. Unpack the files to the desired directory.

Generate a signing key for SSO Agent

Before running the SSO Agent, a public/private key pair must be produced and stored in a Java keystore.

The key is used to sign the SSO tokens that the SSO Agent produces. It can be generated using the keytool program that is distributed as part of Java.

Make a key with the Java keytool

A detailed explanation of the keytool program can be found in the online Java documentation.

You can use the following template command to generate a key and store it in a Java keystore file named keystore.db.

The following keytool parameters are used:

  • -genkeypair — tells keytool to generate a key pair.
  • -alias — name of the key that the SSO Agent uses when searching the key store. Must be ssokey.
  • -keyalg — algorithm used to generate the SSO key. Must be RSA.
  • -dname — Distinguished Name (DN). It contains the server identity, called the Common Name (CN), as well as other relevant information about your organisational Unit (OU), organisation(O), Locality (L), State (S) and Country (C). This should reflect the usage of the SSO Agent in your organisation.
  • -keystore — name of the keystore in which to store the Key pair. If the keystore does not exist then it is created. As a default, use keystore.db.
  • -storepass — password used to access the key store.
  • -keypass — password used to access the key in the key store. Must be the same as the keystore password.
  • -validity — number of days that the key will be valid for. When this period expires, SSO tokens signed with this key will no longer be accepted by Geneos Gateways.
  • -ext SAN — Subject Alternative Name (SAN) that specifies the additional host names to be protected by the certificate. It is sufficient to provide either the SSO Agent’s IP address or DNS name, but both can be defined.

Use the following command replacing the terms in <> with your information using the terms above:

  • On Windows:

    keytool.exe -genkeypair -alias ssokey -keyalg RSA ^ 
    -dname <"CN=SSOAgent,OU=Geneos,O=ITRS"> ^ -keystore keystore.db -storepass <password> -keypass <password> ^ -validity <180> -ext SAN=ip:<SSO Agent IP>
  • On Linux:

    keytool -genkeypair -alias ssokey -keyalg RSA \
    -dname <"CN=SSOAgent,OU=Geneos,O=ITRS"> \ -keystore keystore.db -storepass <password> -keypass <password> \ -validity 180 -ext SAN=ip:<SSO Agent IP>

Note: The commands above must be run from a command prompt with administrator privileges.

Configure SSO Agent to use the keystore

After making a public/private key pair, you must configure the SSO Agent to use the keystore:

  1. Move or copy the keystore file to the conf directory of the SSO Agent.
  2. Open your sso-agent.conf file.
  3. In the server.keystore section, modify the following settings:
    • location — the location of your keystore file.
    • password — the password for your keystore.

Note: As an alternative to having passwords appear in the sso-agent.conf file, they can instead be provided via environment variables. See Use environment variables to provide passwords.

Configure SSO Agent's LDAP Settings

The tokens issued by the SSO Agent provide information about the users that they are issued to. This information is obtained by querying an LDAP server, usually the Microsoft Active Directory server that handles their Windows login.

To query this LDAP server, the SSO Agent must:

  • Have its own credentials.
  • Be configured to use the correct LDAP fields to acquire the required information.

Acquire and add LDAP credentials for the SSO Agent

You must first acquire LDAP credentials for the SSO Agent. It is best to set up a new account for the SSO Agent, because its capabilities should be limited to querying Geneos users and their groups.

Follow these steps to add the requisite Active Directory requirements:

  1. Open your sso-agent.conf file.
  2. In the ldap section, modify the following settings:
    • location — URL for the Active Directory server (host and port). This can also be a space-separated list of URLs. If you provide a list of URLs, the SSO Agent attempts to connect to each URL in order until it makes a successful connection.
    • user — Username used by SSO Agent to login to query LDAP.
    • password — Password used by SSO Agent to login to query LDAP.

The SSO Agent can also be configured to connect to a secure LDAP server. See Configure SSO Agent to use secure LDAP.

Note: As an alternative to having passwords appear in the sso-agent.conf file, they can instead be provided via environment variables. See Use environment variables to provide passwords.

Configure the parameters for querying LDAP

When the SSO Agent builds a token for a user, it needs to look up their entry in LDAP to populate the token. The LDAP field names that the SSO Agent uses can vary between installations. Therefore, it needs to be configured with the correct field names for these items.

The SSO Agent also must specify a base distinguished name when it issues an LDAP query. This is used to restrict the query to the appropriate sub-tree of the directory. You must alter the default value of this setting to reflect the usage of the SSO Agent in your organisation.

To configure the parameters for LDAP, follow these steps:

  1. Open your sso-agent.conf file.
  2. In the ldap section, update the base setting with the base distinguished name for LDAP queries.
  3. In the ldap.fields section, update the following settings:
    • user — username of the account. This is used to parameterise the LDAP query.
    • displayname — display name that Geneos can use to describe the user.
    • email — email address of the user.
    • groups — list of Common Names (CN) of the LDAP groups that the user is a member of. These LDAP group names act as role properties to identify the Geneos roles which apply to a user authenticated via SSO.

    Note: The default values provided are applicable to many LDAP configurations.

Configure Kerberos authentication

Note: If you want to use NTLM or basic authentication, see Change authentication methods and then skip ahead to Start the SSO Agent.

To use Kerberos authentication with the SSO Agent, you must:

If you are experience problems with Kerberos authentication, see Kerberos Troubleshooting.

Add Kerberos details to SSO Agent configuration

The SSO Agent uses the Java Authentication and Authorisation Service (JAAS) framework. There are two configuration files included in the package directory:

  • krb5.conf
  • login.conf

You must add the details of your Key Distribution Center (KDC) and Kerberos realm to the krb5.conf file. If you use Microsoft Active Directory, the KDC is usually the Active Directory server, and the first part of the Kerberos realm matches the Active Directory domain. As a general example, if your KDC host is kdc.example.com, then your Kerberos realm is likely to be EXAMPLE.COM.

Perform the following steps:

  1. Open your krb5.conf file, located in the conf/ directory.
  2. Replace domaincontroller.changeme.com with the host name of your Key Distribution Center (KDC).
  3. Replace all instances of CHANGEME.COM with your Kerberos realm.

For more information on Kerberos configuration, see Optional Kerberos settings .

Associate the SSO Agent's SPN with its username

By default, the SSO Agent uses the same username and password to pre-authenticate with Kerberos and to connect to the LDAP server. If you want to use separate credentials to authenticate with Kerberos, see Use different credentials for Kerberos.

Your Kerberos administrator must associate the SSO Agent’s SPN with the username the SSO Agent uses to connect to Kerberos. Clients using Kerberos authentication from the SSO Agent request a service ticket from the KDC using the SSO Agent's SPN.

Identify your SSO Agent's SPN

The SSO Agent's SPN consists of two parts:

  • The first part is HTTP/. This is irrespective of whether http:// or https:// protocol is used. It is in upper case, has no colon, and only one slash.
  • The second part is the canonical name of the host where the SSO Agent is running. This is usually the hostname part of the SSO Agent’s URL, omitting the port.

For example, if the SSO Agent's location is http://mwserver.emea.itrs:8083, then its SPN is HTTP/mwserver.emea.itrs. However, if the hostname part of the URL is a name which is mapped to the actual host name of the SSO Agent by a CNAME (“canonical name lookup”) DNS record, then the SPN contains the actual host name, not the name that appears in the URL.

Link the SPN with the username

If the Kerberos service is provided by Active Directory, use the setspn command to associate the SSO Agent's SPN with its username.

Use the following command, replacing <SPN> with the SSO Agent's SPN, and <username> with the SSO Agent's username:

setspn -S <SPN> <username>

For example, if the SSO Agent's SPN is HTTP/mwserver.emea.itrs, and its username is itrs_sso, then the command would be:

setspn -S HTTP/mwserver.emea.itrs itrs_sso

The -S option shown ensures that no other username has been associated with the SPN. Note that the port is not used. It is not possible to associate the HTTP service(s) provided by a single host with more than one SPN.

If the client applications use more than one hostname to refer to the SSO Agent, ensure that all the corresponding SPNs are associated with the username used by the SSO Agent.

Note:For additional information regarding setting up the SSO Agent with Kerberos authentication, see Setting up Kerberos Authentication with ITRS SSO Agent..

Start the SSO Agent

Run the applicable command to start the SSO Agent:

  • On Windows, run .\bin\sso-agent.bat.
  • On Linux, run ./bin/sso-agent.

Note: Neither script takes parameters because they are intended to be run from the package base directory.

If the host machine has multiple network adapters, or if you want to run the SSO Agent on a TCP port other than the default, do the following:

  1. Open your sso-agent.conf file.
  2. In the server section, change port to the desired value.
  3. In the server section, change bind_address to the desired value.

Check that the SSO Agent is running

Use the /status endpoint to check the SSO Agent is running and can be reached by browsers running on the client machines.

To access the endpoint, query http://agent.example.com:80/status, replacing agent.example.com:80 with the correct host and port of the SSO Agent.

If successful, it returns 200 OK. The status page shows the SSO Agent and Java versions, start time of the SSO Agent, and configured authentication methods.

If you query the endpoint and it is disabled, it returns 404 Not Found.

This endpoint can also be used as a keep-alive endpoint by Load Balancers to maintain a list of active nodes in the cluster.

Check that the SSO Agent can authenticate a user

Use the /testuser endpoint to check that the agent can authenticate a user. To do this:

  1. Enable the endpoint in your sso-agent.conf file.
    1. Open your sso-agent.conf file.
    2. In the server section, change the value of show_test_pages to true.
    3. Restart the SSO Agent.
  2. If you are using Linux, log in to Kerberos using kinit (or another Kerberos client) and check using the klist command that you have a Kerberos token-granting-token.
  3. Configure your browser to trust the SSO Agent.
  4. Query http://agent.example.com:80/testuser, replacing agent.example.com:80 with the host and port of the SSO Agent.
    • On Linux, you can also use the curl command curl --negotiate -u : http://agent.example.com:80/testuser.

If successful, the results page shows the user details extracted from ldap using the fields configured in sso-agent.conf.

If you query the endpoint and it is disabled, it returns 404 Not Found.

Enable SSO authentication in Geneos components

Enable SSO with Active Console 2

To use SSO authentication with Active Console 2, follow these steps:

  1. Open your Active Console 2.
  2. Navigate to Tools > Settings > Advanced.
  3. Add the URL location of the SSO Agent in the SSO Agent URL box.
  4. Click OK to close the Settings window.
  5. Test the SSO Login by pressing SSO Login on the menu bar.
  6. Navigate to Tools > Settings > Connections.
  7. In the Connections box, change the Logon method of the desired Gateways to SSO.

The Active Console 2 rejects the connection as untrusted if the SSO Agent is configured to use SSL/TLS and the certificate that it uses is not in the CA chain. You must add the local root certificate or the self-signed certificate to the Active Console 2 cacerts. For example:

.\JRE\bin\keytool.exe -keystore .\lib\security\cacerts ^
-import -alias ssl_cert -file C:\dump\p-eu-geneos.cer

See the Active Console 2 Reference Guide for more details.

Acquire the SSO Agent's public key

Before enabling SSO authentication in Geneos components, you need to acquire the SSO Agent's public key. Geneos components require the public key to use SSO authentication.

By default, the public key is exported to the file pub.pem when the SSO Agent starts. To change the target file, see Change the file the key is exported to.

The key is provided in PEM format, which is the format required by Geneos components. Below is an example of the key:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5I8Q2j3tVvXvz5vo5iN2
cv1DdXMRlIRi3jlukitapvUZ50nWPI2TnGEHiTlAYIN8rYErdMI1qfJcK0ImDls7
zfEgrQK1viEoc+S/DBEmJFbZxlQMyqgPlynDNmcy7ZWtS9ofWeJ4cVdqTAEJldJx
APzmp6ZB9R1zcnysbZA9q8ZDxonwLymKIimKt4gDfi+DlZSu+uB2CJGHmKkr2i/N
GTh2FXtjuzvgq3cbAmircHycQ7TWjCh137E6MOYz/PYDGnjLAnkYE524Y8N9Uzhp
xS6hGXkelrtzg348XI3i5gr6Df7HO11jxogdE0SQFo/QGnscjkB16Gyv0g40FOBB
zwIDAQAB
-----END PUBLIC KEY-----

Use SSO with Gateway Setup Editor

To use SSO authentication with Gateway Setup Editor, you must launch the GSE from within the Active Console 2. SSO logon is not supported when the GSE is running as a stand-alone process.

Enable SSO with Gateway

To enable SSO authentication for a Gateway, follow these steps:

  1. Open the GSE.
  2. Navigate to Authentication > Single Sign On.
  3. (Optional) Add the URL location of the SSO Agent in the Sso agent box.
  4. Copy the SSO Agent's public key in PEM format into the Public key box. Do not omit the header or footer lines.
  5. Set up the Gateway user roles with role properties that match LDAP groups to which the Geneos users belong.

Enable SSO with Webslinger

To use SSO authentication with Webslinger, follow these steps:

  1. Open your Webslinger setup file.
  2. Configure the following properties in the Webslinger setup file:
    • SSO_PROVIDER
    • SSO_PUBKEY
    • WEB_SERVICE_URL

    For more information on setting up Webslinger, see Webslinger Setup .

  3. Ensure the SSO Agent's public key is in PEM format in the file you have specified in SSO_PUBKEY.

Enable SSO with Web Dashboard

To use SSO authentication with Web Dashboard, follow these steps:

  1. Configure the following properties in <web_dashboard_install_dir>/config/sso.properties file:
    • sso.agent.url
    • webdashboard.url
    • sso.enabled
    • sso.pubkey

    For more information on setting up the Web Dashboard, see Enabling SSO.

  2. Ensure the SSO Agent's public key is in PEM format in the file you have specified in sso.pubkey.
Configuration using SSO Agent with HTTPS

There are additional configuration steps with Web Dashboard when using the SSO Agent in HTTPS. To learn how to enable HTTPS, see Enable HTTPS.

With HTTPS enabled, perform the following steps:

  1. Run one of the following commands, depending on your operating system, to export the SSO Agent's certificate named ssokey:
    • On Windows, run .\bin\ssl_utils.bat export ssokey.
    • On Linux, run ./bin/ssl_utils.sh export ssokey.
  2. Copy the generated ssokey.cer to your Web Dashboard instance.
  3. Import ssokey.cer to your Web Dashboard’s JRE, using the steps below:
    • If using a Web Dashboard with JRE, use these commands:
      cd <web_dashboard_install_dir>/JRE/lib/security
      keytool -importcert -trustcacerts -alias ssokey -file ssokey.cer \
      -keystore cacerts -storepass <keystore password; default is changeit>
    • If using a Web Dashboard without JRE:
      • Use these commands using a JDK:
        cd <JAVA_HOME>/jre/lib/security
        keytool -importcert -trustcacerts -alias ssokey -file ssokey.cer \
        -keystore cacerts -storepass <keystore password; default is changeit>
      • Use these commands using a JRE:
        cd <JAVA_HOME>/lib/security
        keytool -importcert -trustcacerts -alias ssokey -file ssokey.cer \
        -keystore cacerts -storepass <keystore password; default is changeit>

Additional configuration settings

Change authentication methods

By default, the SSO Agent is configured to use Negotiate and Basic authentication. Most client applications try to authenticate using Negotiate first and, if this fails, use Basic authentication.

To change this:

  1. Open your sso-agent.conf file.
  2. Modify the list in the authentication setting.
    • The three possible options are Negotiate,BASIC, and NTLM.
    • For example, to disable HTTP Basic authentication, change "authentication": ["Negotiate","BASIC"] to "authentication": ["Negotiate"].
    • For example, to enable NTLM authentication, change "authentication": ["Negotiate","BASIC"] to "authentication": ["NTLM","Basic"].

Note: An SSO Agent binary that supports NTLM (NT LAN Manager v2) as an additional authentication method is available on request. This SSO Agent binary can only run on Windows. Please contact ITRS Support for more information.

Enable HTTPS

Using HTTPS gives a layer of encryption to your user data.We recommended that you enable HTTPS on the SSO Agent.

To enable HTTPS, you must provide an SSL certificate and store it in the Java keystore used by the SSO Agent. You must use the same keystore to store both the HTTPS SSL certificate and the signing key for the SSO tokens. If you have not done this yet, see Generate a signing key for SSO Agent.

There are two ways to configure an SSL certificate for the SSO Agent:

  • Generate a new self-signed certificate.
  • Import an existing SSL certificate issued by a Certificate Authority (CA) trusted by your users’ web browsers.

Generate and import a new self-signed certificate

You can generate a new self-signed certificate for the SSO Agent.

You can use the scripts ssl_utils.bat or ssl_utils.sh provided in the bin directory to help generate and import a certificate into a Java keystore. When you do this, ensure you update the scripts with the Distinguished Name of your server and the password for your private key.

To generate a new self-signed certificate, run the following command, specifying the certificate alias. This generates the certificate and adds it to a keystore.

  • On Windows:

    cd <sso_agent_install_dir>
    .\bin\ssl_utils.bat add <certificate_alias>
  • On Linux:

    cd <sso_agent_install_dir>
    ./bin/ssl_utils.sh add <certificate_alias>

Note: If the SSO Agent uses a self-signed certificate, web browsers warn users connecting to the Geneos web services that the certificate is not trusted. As long as it is not necessary to authenticate the SSO Agent to the client applications, it is reasonable to advise users to add an exclusion rule (or to accept the warning).

Import an existing certificate for your domain name

If the server running SSO Agent has an existing SSL certificate issued by a Certificate Authority (CA), you can import that certificate and its private key into the server’s keystore. To import the certificate and its private key into the keystore, it must be transformed into a PKCS12 server certificate. This can be done using openssl:

openssl pkcs12 -export -inkey input_cert.key -in input_cert.crt \
-out output_cert.pfx

The openssl pkcs12 parameters are:

  • -export — tells openssl to output a pkcs12 certificate to a file.
  • -inkey — file containing the private key of the certificate to be converted.
  • -in — file containing the certificate to be converted.
  • -out — output file to be populated with the PKCS12 server certificate.

Once you have a PKCS12 server certificate, it can be imported using keytool:

  • On Windows:

    keytool.exe -importkeystore -srckeystore output_cert.pfx -srcstoretype PKCS12 ^
    -destkeystore keystore.db -deststoretype JCEKS ^
    -deststorepass CHANGE-ME -destkeypass CHANGE-ME ^
    -alias itrs.geneos.sso
  • On Linux:

    keytool -importkeystore -srckeystore output_cert.pfx -srcstoretype PKCS12 \
    -destkeystore keystore.db -deststoretype JCEKS \
    -deststorepass CHANGE-ME -destkeypass CHANGE-ME \
    -alias itrs.geneos.sso

The following are the parameters for the above command:

  • -importkeystore — openssl to generate a pkcs12 certificate.
  • -srckeystore output_cert.pfx — file containing the private key of the certificate to be converted
  • -srcstoretype PKCS12 — format of the certificate to be imported (PKCS12)
  • -destkeystore keystore.db — name of the keystore to be used by SSO Agent
  • -deststoretype JCEKS — format of the keystore (This must be JCEKS).
  • -deststorepass CHANGE-ME — password used to access the key store.
  • -destkeypass CHANGE-ME — password used to access the key in the key store. Must be identical to the keystore password.
  • -alias <certificate_alias> — name of the alias used when storing the certificate in the keystore.

Configure SSO Agent to use SSL

Once the SSL certificate has been added to the keystore:

  1. Open your sso-agent.conf file.
  2. In the server section, change the value of enable_ssl to true.
  3. In the server section, change the value of ssl_alias to value of the alias used when storing the certificate in the keystore.
  4. In the server.trust_store section, check the value of location and password. It is recommended that the key_store and trust_store is the same store.
"server": {
	"enable_ssl": true
	"ssl_alias": "CHANGE-ME",
	"key_store": {
		"location": "conf/keystore.db"
		"password": "CHANGE-ME"	
	},
"trust_store": {
	"location": "conf/keystore.db",
	"password": "CHANGE-ME"
	}
}                                

Tokens and token lifetimes

The SSO Agent provides tokens used to authorise the users to access Geneos components. All the tokens provided by the SSO Agent have a limited duration, after which the token is no longer valid. Geneos components request a new token before each token expires, so that user sessions are not interrupted.

The following token types are supported by SSO Agent:

  • Code — short-lived token, provided to the web browser when the user logs in to Web Dashboard or Webslinger. The web service uses this code to obtain an access token for the user session.
  • REST token — token is provided to allow access to Geneos REST commands. As this token cannot be restricted to a single process, it is less secure and its lifetime should be limited.
  • Access token — token provides access to Geneos components. 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 token — long-lived token, used to obtain new Access tokens without requiring the user 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 need to re-authenticate (handled automatically by Active Console 2).

Change token lifetimes

The duration of a token is given in seconds. To change the durations for the various types of token:

  1. Open your sso-agent.conf file.
  2. In token _duration section, modify the value of the following settings to the desired number of seconds:
    • code — code token duration. Default value is 60.
    • rest — REST token duration. Default value is 300.
    • access — access token duration. Default value is 3600.
    • refresh — refresh token duration. Default value is 86400.

Web service support

Web services access the SSO Agent by redirecting the web browser to the SSO Agent. Once the user has been authenticated, the SSO Agent redirects the browser back to the Web service. The SSO Agent only does this for services with known URIs.

These URIs are listed in the redirect_uri setting. For example:

redirect_uri: [
"http://dev-webdashboard.itrsgroup.com",
"http://uat-webdashboard.itrsgroup.com",
"http://webslinger.itrsgroup.com"]

Use environment variables to provide passwords

Passwords can be provided to the SSO Agent as environment variables.

Password settings in the sso-agent.conf file take precedence over its equivalent environment variable. If the password setting is absent in the sso-agent.conf file, then it is instead read from the corresponding environment variable:

Password Setting Environment Variable
kerberos.password ITRS_SSO_KERBEROS_PW
ldap.password ITRS_SSO_LDAP_PW
server.key_store.password ITRS_SSO_KEYSTORE_PW
server.trust_store.password ITRS_SSO_TRUSTSTORE_PW

You can set environment variables to provide passwords by using the export command prior to running the SSO Agent. For example:

export ITRS_SSO_KERBEROS_PW=[your password here]
export ITRS_SSO_LDAP_PW=[your password here]
export ITRS_SSO_KEYSTORE_PW=[your password here]
export ITRS_SSO_TRUSTSTORE_PW=[your password here]
./bin/sso-agent

Authentication errors can be investigated by using the SSO Agent log (logs/sso-agent.log).

Run multiple instances of SSO Agent

The SSO Agent is a stateless REST service. Therefore, you can run multiple instances of the service.

Before you do so, check that:

  1. The configuration (including certificates and keys) is the same across all instances.
  2. The SSO Agent’s DNS A record points to the IP addresses of all the machines running the SSO Agent.

Run SSO Agent as a Windows service

The SSO Agent comes with a service wrapper that allows the SSO Agent to run as a Windows service. The Windows service wrapper used is winsw.

To install the SSO Agent as a Windows service:

  1. Check that you can run the SSO Agent in the foreground. You must check this with your current directory set to the parent of the .bin directory, so that you run the agent as .\bin\sso-agent.bat.
  2. Run .\bin\sso-service.exe install as Administrator.

The service can now be started and stopped using the Windows Services Manager. The service is listed as Geneos SSO Agent.

To remove the service, run the following command as Administrator:

.\bin\sso-service stop
.\bin\sso-service uninstall

Configure SSO Agent to use secure LDAP

The SSO Agent can be configured to connect to a secure LDAP server. To do this, follow these steps:

  1. Open your sso-agent.conf file.
  2. In the ldap section, update the location setting from "ldap:<insecure_ldap>" to "ldaps:<secure_ldap>".
    • Make sure that the location points to the secure LDAP port on your LDAP server rather than the insecure one.
  3. Obtain the LDAP certificate for your LDAP service from your Active Directory.
    • The SSO service needs to access your LDAP certificate so it can trust your LDAP service.
  4. Add the LDAP certificate to the cacerts in your Java distribution. Use the keytool command below with the following flags, and replacing the terms in <> with your information:
    • -keystore — absolute path to your keystore.
    • -import — instructs keytool to import the certificate provided.
    • -alias — unique name for your certificate, which must not already exist in the keystore. A unique name is required, but is not used by the SSO Agent: when the LDAP service presents a certificate, the Java security framework checks it against all the certificates in the trust store.
    • -file — absolute path to the certificate you want to import.
      • On Windows:

        keytool.exe -keystore cacerts -import ^
        -alias <ldap_certificate> -file <ldap_certificate_file>
      • On Linux:

        keytool -keystore cacerts -import \
        -alias <ldap_certificate> -file <ldap_certificate_file>

Export the SSO Agent's public key

Change the file the key is exported to

When the SSO Agent is started, it exports the public key part of its key pair to a file. The default file is called pub.pem.

To change the name of the file from the default:

  1. Open your sso-agent.conf file.
  2. In key_store section, modify the export_public_key_file setting.

Optional Kerberos settings

The kerberos section of the sso-agent.conf file can be modified to:

Change the location of the configuration files

By default, the configuration files that the SSO Agent uses for Kerberos authentication are located in the conf directory. To change the location:

  1. Open your sso-agent.conf file.
  2. In kerberos section, modify the krb5_conf and login_conf settings to the directory.

Use different credentials for Kerberos

By default, SSO Agent uses the same username and password to pre-authenticate with Kerberos that it uses to connect to the LDAP server.

If you want to use a Kerberos-specific username and password:

  1. Open your sso-agent.conf file.
  2. In kerberos section, modify the user setting to the username you want to use.
  3. In kerberos section, modify the password setting to the password you want to use.

Note: As an alternative to having passwords appear in the sso-agent.conf file, they can instead be provided via environment variables. See Use environment variables to provide passwords.

Disable the realm-checking feature

By default, the SSO Agent rejects the authorisation of users who are authenticated with realms different from the one the SSO Agent is authenticated with.

You may want to allow the SSO Agent to accept authorisation of user from different realms if your organisation has multiple Kerberos realms with a trust relationship between them (a user connecting to a service in REALM.X can be authenticated by REALM.Y). In this case, there are two possible scenarios that could occur in your organisation:

  • If two users with identical names exist in the different realms in your organisation, there is no way for the SSO Agent to differentiate which roles are allowed for each user. Keep the setting as reject to authorise in this instance.
  • If usernames are globally unique across your organisation, and the allowed roles for each user are available to the SSO Agent, you can configure it to allow the realm mismatch.

To allow realm mismatch, perform the following:

  1. Open your sso-agent.conf file.
  2. In kerberos section, change the realm_mismatch to allow.

Troubleshooting

Scenario Recommended action
Clients fail to authenticate in ITRS applications.
  • Check application logs.
  • Check whether /testuser endpoint works.
  • If /testuser endpoint works, check that the user has the LDAP groups expected by applications.
Browser falls to authenticate using /testuser endpoint.
  • Check that /status page is available.
  • Check SSO Agent console output and log.
Status page is not available.
  • Check the SSO Agent is running.
  • Check firewall.

Kerberos Troubleshooting

To authenticate via Kerberos, the client (Active Console 2 or a web browser) sends a request to the Key Distribution Centre (KDC) for a ticket for the SSO Agent service. To do this, the client requires a Service Principal Name (SPN) for the service. The name it uses is made up of a prefix, "HTTP/", and the host name that the client connects to. If the initial DNS lookup for this host finds a DNS alias (CNAME), the client uses the result of that lookup to construct the SPN. If the initial DNS lookup finds an A record, it uses the host name it started with.

If the resultant SPN is not registered to exactly one service principal, the client does not attempt to use Kerberos. Most Windows clients (including Active Console 2) resort to attempting NTLM authentication, and this will fail. If the SPN is registered to a service principal, but this name is different to the one with which SSO Agent authenticates to Kerberos, then the client attempts to use Kerberos but the authentication will fail.

Note: If the SSO Agent detects a request containing an NTLM header where a Kerberos header is expected, it logs an explicit error message and does not attempt Kerberos authentication.

General points

  • Do not include the port number in the SPN registered for the SSO Agent.
  • Ensure that each SPN is registered to only one service principal.
  • If a DNS alias (CNAME) record exists for the hostname used by the client, ensure that the name that the alias resolves to is registered as an SPN for the SSO Agent.

Common errors

Scenario Recommended action
SSO Agent reports error reading Kerberos message
  • Check that the SSO Agent is using correct credentials to connect to Kerberos.
SSO Agent log reports that client is attempting NTLM authentication. Error message in the form ERROR com.itrsgroup.ssoagent.authentication - Client is attempting NTLM authentication. There is a configuration issue.
  • Check that the SSO Agent's SPN is set up correctly.
  • Check that CNAME records do not cause host name in SPN to be different from URL.
SSO Agent log reports that it cannot verify Kerberos credential because realm is not as expected. Warning message in the form WARNING com.itrsgroup.ssoagent.authentication - Cannot verify Kerberos credential: realm='xxx', expected='yyy'