SSO Agent User Guide

Overview Copied

The ITRS SSO Agent is a Java application that acts on behalf of Geneos components to authenticate users against the Windows Active Directory, Oracle Unified Directory, or Gateway Hub permissions.

If a user is logged into Windows on a computer in the same domain as the SSO Agent, the Active Console 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.

The SSO Agent generates SSO tokens that are used by Geneos components to determine the user’s permissions.

The components that use ITRS are:

• Active Console
• Gateway
• Web Dashboard
• Webslinger

Role based authorisation Copied

User authentication (checking identity) is handled by the SSO Agent, while user authorisation (checking permissions) is based on which LDAP groups or Gateway Hub roles the user belongs to. Gateway checks each user’s LDAP groups or Gateway Hub roles against its list of Gateway role properties. A user is assigned a Gateway role if any of the user’s LDAP groups or Gateway Hub roles match that Gateway role’s properties.

A user can have multiple Gateway roles. For more information about configuring Gateway roles and role properties, see Roles in Gateway Authentication.

Once Gateway roles have been set up and associated with group names, administrators can add, modify, or remove users using only Active Directory or Gateway Hub tools.

Intended audience Copied

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

Prerequisites Copied

System requirements Copied

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

When Security-Enhanced Linux (SELinux) is running in Enforcing mode, it may deny certain functions of Geneos depending on the implemented configurations and policies.

To see which functions SELinux denies, check the audit log. The log is typically located in /var/log/audit.log, where the log type entry is AVC. The audit log provides the details of any denied access. For example, denied connection to the TCP port.

If you experience issues related to this mode, you may opt to disable SELinux, or create policy modules to grant the required access. Please contact your administrator or security team for assistance.

Java requirements Copied

Version installed Copied

You must have Java installed on the machine running the SSO Agent. For more information on supported Java versions, see Java support in Geneos Compatibility Matrix.

Java location Copied

Once you have Java installed, check that the SSO Agent start script (bin/sso-agent) can locate your Java directory.

The JAVA_HOME variable is preconfigured in the script. However, if the SSO Agent fails to locate the directory, then add the line export JAVA_HOME=<Java directory> after this comment:

 # OS specific support. $var _must_ be set to either true or false:

The output would look like this on the start script:

# OS specific support.  $var _must_ be set to either true or false.
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

For guidance in setting the Java directory for JAVA_HOME, see Java support.

Active Directory requirements Copied

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

• The credentials that the SSO Agent will use to connect to Active Directory. See Acquire and add LDAP credentials for the SSO Agent.
• The LDAP query that the SSO Agent will use to determine the full name and LDAP groups of an authenticated user. See Configure the parameters for querying LDAP.

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 Copied

SSO Agent authentication methods Copied

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.

SSO Agent configuration Copied

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.

Procedure Copied

To start using the SSO Agent with Geneos, the following steps are required:

1. Download and unpack the files
2. Generate a signing key for SSO Agent
3. Configure SSO Agent to use the keystore
4. Configure SSO Agent’s LDAP Settings
5. Configure Kerberos authentication
6. Start the SSO Agent
7. Check that the SSO Agent is running
8. Check that the SSO Agent can authenticate a user
9. Enable SSO authentication in Geneos components

Download and unpack the files Copied

1. Download the SSO Agent package sso-agent-<version>-bin.zip from the ITRS Downloads site.
2. Unpack the files to the desired directory.

Generate a signing key for SSO Agent Copied

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 Copied

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.
• -storetype — keystore type. Must be jceks.
• -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:

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

Configure SSO Agent to use the keystore Copied

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 Copied

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.

Note

To view the list of LDAP-supported servers, see LDAP-supported servers for SSO.

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 Copied

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 Copied

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 parametrize 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.
   • loginname — name that can be used to look up a user instead of a specific field. This is used if there are multiple values for the field.

     Note

     The default values provided are applicable to many LDAP configurations.

4. If the LDAP system does not provide a field that contains the Common Name (CN) of each group that the user is a member of, and instead, the Distinguished Names (DN) of the users are listed as part of the groups then you need to set ldap.groups.memberfield to be the name of the field that stores the Distinguished Names (DN) of the users in the group record.

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.

Configure Kerberos authentication Copied

Note

If you want to use 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:

• Add Kerberos details to SSO Agent configuration.
• Instruct your Kerberos administrator to Associate the SSO Agent’s SPN with its username.

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

Add Kerberos details to SSO Agent configuration Copied

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 Copied

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.

The Kerberos Service Principal username may be case-sensitive. Therefore, the username specified in both the LDAP and Kerberos sections of your sso-agent.conf file should match the exact case of the username in the KDC.

Identify your SSO Agent’s SPN Copied

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://server.example.itrs:8083, then its SPN is HTTP/server.example.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 Copied

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/server.example.itrs, and its username is itrs_sso, then the command would be:

setspn -S HTTP/server.example.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 Copied

Run the ./bin/sso-agentcommand to start the 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 Copied

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 Copied

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.

   • Open your sso-agent.conf file.
   • In the server section, change the value of show_test_pages to true.
   • 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 Copied

Enable SSO with Active Console Copied

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

1. Open your Active Console.
2. Navigate to Tools > Settings > General.
3. Add the URL location of the SSO Agent in the SSO Agent URL field.
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 Copied

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 Copied

No additional configuration is required to use SSO authentication with Gateway Setup Editor if it is launched from an Active Console configured to use SSO. This also applies if the GSE is launched as an external process from the Active Console. See Enable SSO with Active Console.

To enable SSO authentication with a stand-alone GSE:

1. Open your GatewaySetupEditor.gci file.
2. Add the -SSOAgentURL flag to the file.
3. Add the SSO Agent URL after the flag.
   • For example. -SSOAgentURL http://server.example.itrs:8083
4. Save the .gci file.

The Active Console passes connection information to the GSE when launched from the Active Console. This connection information overrides the -SSOAgentURL flag in the GatewaySetupEditor.gci file (if present).

Enable SSO in Gateway Copied

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 Copied

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

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

Configuration using SSO Agent with HTTPS Copied

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 the ./bin/ssl_utils.sh export ssokey command to export the SSO Agent’s certificate named 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>

Additional configuration settings Copied

Change authentication methods Copied

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 possible options are: Negotiate,BASIC.
   • For example, to disable HTTP Basic authentication, change "authentication": ["Negotiate","BASIC"] to "authentication": ["Negotiate"].

Enable HTTPS Copied

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 Copied

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.

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 Copied

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:

Note

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org).

openssl pkcs12 -export -inkey input_cert.key -in input_cert.crt \
-name itrs.geneos.sso -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.
• -name — ‘friendly’ name for the certificate and private key.
• -out — output file to be populated with the PKCS12 server certificate.

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

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 Copied

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 Copied

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

Change token lifetimes Copied

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.

Check token origin Copied

When the SSO Agent issues any token, it records the source address of the requesting host.

By default, when the SSO Agent receives a request that includes a token it performs an origin check. The SSO Agent does this by checking the source address of the request against the source address recorded when issuing the included token.

However, in situations where the SSO Agent is accessed through a proxy this origin check will not work correctly. This is because the source address of any host making requests through the proxy will appear to be the proxy address. Additionally, if a load balancer is also used, the proxy source address may vary between requests, this causes valid requests to be rejected.

To disable the check origin function:

1. Open your sso-agent.conf file.
2. In the top level section, change the value of check_origin to false.

# Whether to restrict SSO tokens to the host issuing the request. This is more secure, since it makes it hard to
# re-use an intercepted token, but will not work if SSO Agent is behind a load-balanced proxy.
"check_origin": false      # Set to false to disable checks based on the apparent origin of the request; default is true

Web service support Copied

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.

The URIs can be regular expressions. Regular expression pattern matching is performed for URIs prefixed with ^. The SSO Agent is a Java application and uses the standard Java RegEx library.

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",
"^https:\/\/web-dashboard[0-9]\.itrsgroup\.com$"]

Use environment variables to provide passwords Copied

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:

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 Copied

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.

Configure SSO Agent to use secure LDAP Copied

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.

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

Configure REST endpoint to return assignable users Copied

The SSO Agent has a configurable endpoint that can be used by SSO-enabled Gateways to obtain a list of assignable users. This list is presented by the Active Console and Web Dashboard when running User Assignment commands.

By default, the endpoint is enabled. The SSO Agent restricts access to the this endpoint to users that are in the group denoted by the value of ldap.groups.access_group in the sso-agent.conf file.

Ensure that the endpoint is accessible by following these steps:

1. Open your sso-agent.conf file.
2. Inldap.groups section, change the value of access_group to the name of the group that you want to allow access to the endpoint.

Set up the LDAP fields to ensure that the SSO agent retrieves the correct fields:

1. Open your sso-agent.conf file.
2. In ldap.fields section, update the following settings:
   • givenname — Field that holds the first name of a user.
   • surname — Field that holds the last name of a user.
3. In ldap.groups section, update the query_filter setting.
   • This filter enables you to make specific LDAP searches using fields such as objectCategory and objectClass.

     Note

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

     Note

     In the LDAP query, the groups.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.

If you want to disable the endpoint, perform the following:

1. Open your sso-agent.conf file.
2. In ldap.groups section, change the value of queryable to false.

Export the SSO Agent’s public key Copied

Change the file the key is exported to Copied

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.

Enable the public key endpoint Copied

You can configure the SSO Agent to provide a public endpoint that displays its public key.

To enable the endpoint:

1. Open your sso-agent.conf file.
2. In key_store section, add enable_public_key_endpoint and set to true.

For example:

# Web server settings
"server": {
 "key_store": {                  # Keystore used to store private keys
 "location": "..\\conf\keystore.db",
 "password": "CHANGE-ME"     # [CHANGE THIS] Password for keystore
 "export_public_key_file": "pub.pem",    # File public key is exported to
 "enable_public_key_endpoint": "true"  } # Add this to enable endpoint
}

This configures the SSO Agent to create the public (or unauthenticated) /public_key endpoint. The enable_public_key_endpoint is a boolean, and defaults to false if absent.

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

If successful, the endpoint returns the agent’s public key.

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

Cross-Origin Resource Sharing (CORS) settings Copied

Cross-Origin Resource Sharing (CORS) is a mechanism that allows restricted resources on a web page running on one domain to be requested from another domain. CORS is enabled with the SSO Agent by default.

The CORS settings for SSO Agent are located in the server.cors section of the sso-agent.conf file. There are two settings:

• allowedOrigins — list of allowed origins when making a CORS request. Setting to * allows access from any origin. Requests that do not match are filtered. If this is not set, or set to *, the filter applies for all requests. Default is ["*"].
• allow_methods — list of methods that can be used when making a CORS request. Default is ["GET","POST", "HEAD", "OPTIONS"] .

Optional Kerberos settings Copied

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

• Change the location of the configuration files.
• Use different credentials for Kerberos.
• Disable the realm-checking feature.

Change the location of the configuration files Copied

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 Copied

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.

   Caution

   The Kerberos Service Principal username may be case-sensitive. Therefore, the username specified in both the LDAP and Kerberos sections of your sso-agent.conf file should match the exact case of the username in the KDC.

3. In kerberos section, modify the password setting to the password you want to use.

You can also use a keytab file to authenticate. To do this, refer to the following example of a login.conf that is configured to use keytab files for both pre-authentication and LDAP queries. In this case, neither the LDAP password nor the Kerberos password is configured in sso-agent.conf or in the corresponding environment variables.

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

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

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

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 Copied

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 Copied

Kerberos Troubleshooting Copied

To authenticate via Kerberos, the client (Active Console 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. 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 Copied

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