SSO Agent User Guide

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.

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.

You can configure the LDAP and Kerberos credentials for the SSO Agent through any of the following:

• The password in the ldap and Kerberos sections of the sso-agent.conf file.

• The ITRS_SSO_LDAP_PW and ITRS_SSO_KERBEROS_PW environment variables.

• The useKeyTab and keytab options in the ssoagent-server and the ldap-client sections of the login.conf file.

To use keytab authentication, you must omit the password from the sso-agent.conf file and edit the login.conf file. Below is an example of a login.conf file that is configured to use a keytab file:

ssoagent-server {
	com.sun.security.auth.module.Krb5LoginModule required
	storeKey=true
	isInitiator=false
	useKeyTab=true
	keyTab="conf/user.keytab";
};
							
ldap-client {
	com.sun.security.auth.module.Krb5LoginModule required client=TRUE
	useKeyTab=true
	keyTab="conf/user.keytab";
};

In this example, conf/user.keytab is the keytab file associated with the user for both pre-authentication and LDAP queries.

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.

You can also refine your LDAP query by using the following optional filters:

• users.query_filter — enables you to make specific LDAP searches using fields such as objectCategory and objectClass.

Note: By default, the SSO Agent identifies users by querying objectClass=user. You can change the name of the object class by setting users.class to a different value, or you can replace that part of the query by setting users.query_filter. For example, if you want to use objectCategory to identify a user rather than objectClass, set users.query_filter to objectCategory=user.

Note: In the LDAP query, the users.query_filter acts as a logical AND (&&) operator where all conditions contained within must be met. More information regarding LDAP syntax can be found by performing an internet search for Active Directory LDAP Syntax Filters.

• groups.token_filter — 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.

Enable SSO with Active Console

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

1. Open your Active Console.
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 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 Consolecacerts. For example:

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

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.

You can also configure an endpoint that provides the public key so you do not need to search for the file. See Enable the public key endpoint.

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

Enable SSO in the Gateway Setup Editor

Enable SSO in Gateway

To enable SSO authentication for a Gateway:

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:

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, see Webslinger Setup in Webslinger.

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:

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, see Enabling SSO in Web Dashboard.

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

Web Dashboard supports Basic and Kerberos authentication. When you are connecting to SSO Agent through Kerberos, Web Dashboard looks for the krb5.conf in /etc/ directory by default.

If you want to modify its location:

1. Open run/geneosws start-up scripts.
2. Edit the config under SSO_PROPERTIES:

-Djava.security.krb5.conf=/etc/krb5.conf

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:
     

     cd <JAVA_HOME>/jre/lib/security
     keytool -importcert -trustcacerts -alias ssokey -file ssokey.cer \
     -keystore cacerts -storepass <keystore password; default is changeit>