Recommended Reads

SSO Agent

Introduction

ITRS SSO Agent is a Java application which acts on behalf of Geneos components to authenticate users against Windows Active Directory. If a user is logged in to Windows on a computer in the same domain as the SSO Agent, then ActiveConsole can present their credentials to SSO Agent (using the Kerberos or NTLM protocol) 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 pasword. As a fallback, the SSO Agent also supports HTTP Basic authentication; in this 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. That is, 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, which are 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 which use ITRS SSO Agent are:

  • Active Console 2
  • Web Dashboard
  • Webslinger
  • Gateway 2

System Requirements

SSO Agent is a 64-bit Java application that runs on Windows, with the following requirements:

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

Note: When running on Linux, the SSO Agent can authenticate against a Windows domain, but can only use Kerberos and/or Basic authentication.

Please refer to the Geneos Compatibility Matrix for the list of supported platforms and web browsers.

Next steps

Once SSO Agent is running, you may also want to consider the following:

  • Enable secure (HTTPS) connections to SSO Agent
  • Configure SSO token lifetimes

Generating a signing key for SSO Agent

Before running the SSO Agent, a public/private key pair needs to be produced and stored in a Java keystore. This 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.

Using the Java keytool

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

The following example generates a key and stores it in a Java keystore called ‘keystore.db. 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 command above must be run from a command prompt with administrator privileges. You will encounter keytool error: java.io.FileNotFoundException: keystore.db (Access is denied) if the command is run without administrator privileges.

The keytool parameters that should be used are as follows:

  • -genkeypair: This tells keytool to generate a key pair. This parameter is required.
  • -alias: This is the name of the key that the SSO Agent uses when searching the key store. It MUST be ‘ssokey’.
  • -keyalg: This is the algorthim used to generate the SSO key. This MUST be ‘RSA’.
  • -dname: This is the 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: This is the name of the keystore in which to store the Key pair. If the keystore does not exist then it will be created.
  • -storepass: This is the password used to access the key store.
  • -keypass: This is the password used to access the key in the key store. This MUST be the same as the keystore password.
  • -validity: This is the number of days for which the key will be valid. When this period expires, SSO tokens signed with this key will no longer be accepted by the Geneos gateways.
  • -ext SAN: This is the 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. This parameter is required.

Configuring SSO Agent to use the key

The keystore file created in the previous step should be copied or moved to the configuration directory of the SSO Agent. (This is the directory containing the agent’s configuration file, sso-agent.conf)

The sso-agent.conf file should then be updated to point at the keystore file and provide the password:

# 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"   }
}                                

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

Exporting the public key for use by Geneos components

When the SSO Agent is started, it will export the public key part of the key pair generated above to the file specified by the export_public_key_file setting.

This file is in the format required by the Geneos components that need to trust the tokens issued by the SSO Agent:

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

See Enabling SSO in Geneos components for information about how to use this file.

LDAP Settings

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

The SSO agent needs to have its own credentials so that it can query the LDAP server and it needs to be configured to use the correct LDAP fields to obtain the information needed.

Credentials for connecting to LDAP

The SSO Agent can use the credentials of an existing account, or a new account can be set up for it to use. The capabilities of this account should be limited to querying Geneos users and their groups.

The details of the LDAP server and the credentials to use need to be set up in the sso-agent.conf file:

"ldap": {
"location": "ldap://10.0.0.1:389" # [CHANGE THIS] URL for the Active Directory server (host and port)
"user": "ITRS\\geneos"            # [CHANGE THIS] Username used by SSO Agent to login to query LDAP
"password": "ChangeMe"            # [CHANGE THIS] Password used by SSO Agent to login to query LDAP
}                                

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

You can supply a space-separated list of URLs for the location setting. In this case, the SSO Agent will attempt to use each URL in turn until it is able to create a successful connection.

Parameters for querying LDAP

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

  • Username: The username of the account. This is used to parameterise the LDAP query.
  • Display name: A display name that Geneos can use to describe the user.
  • Email Address: The email address of the user.
  • LDAP groups: A 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.

Default values are provided which are applicable to many LDAP configurations.

In addition, the SSO Agent needs to specify a ‘base distinguished name’ when it issues an LDAP query. This is used to restrict the query to the appropriate subtree of the directory. The default value for this setting will need to be altered to reflect the usage of the SSO Agent in your organisation.

LDAP query parameters are configured in the ‘ldap’ section of the sso-agent.conf file:

"ldap": {
	"base": "OU=Global,DC=ldn,DC=itrs" # [CHANGE THIS] Base distinguished name for LDAP queries
	"fields": {
		"user": "sAMAccountName"       # LDAP field used to look up a user by name
		"displayname": "displayname"   # LDAP field that holds the display name for a user 
		"mail": "mail"                 # LDAP field that holds the email address of a user
		"groups": "memberOf"           # LDAP field that holds the groups a user is a member of
	}		
}

Secure LDAP

The SSO Agent can connect to a secure LDAP server. In order to do this the location of the service needs to be updated from ‘ldap:...’ to ‘ldaps:...’. Make sure that the location points to the secure LDAP port on your LDAP server rather than the insecure one.

"ldap": {
	"location": "ldaps://10.0.0.1:636"
	"user": "ITRS\\geneos"
    "password": "ChangeMe"
}                           

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

As well as updating the SSO Agent configuration, the SSO service needs to be able to trust your LDAP service. For this it needs access to the LDAP certificate. This needs to be added to the cacerts in your java distribution. Get the certificate from your Active Directory and import it into the cacerts. Use the following on Windows:

keytool.exe -keystore cacerts -import ^
-alias ldap_certificate -file ldap_certificate_file

Alternatively, use the following on Linux:

keytool -keystore cacerts -import \
-alias ldap_certificate -file ldap_certificate_file
  • -keystore: Absolute path to your keystore.
  • -import: This instructs keytool to import the certificate provided
  • -alias: A name for your certificate, which must not already exist in the keystore. (A unique name is needed, but is not used by the SSO Agent: when the LDAP service presents a certificate, the Java security framework will check it against all the certificates in the trust store.)
  • -file: Absolute path to the certificate you want to import

Enabling Kerberos authentication

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

Registering an SPN

The SSO Agent will by default use the same username and password to pre-authenticate with Kerberos that it uses to connect to the LDAP server. Separate credentials to the LDAP username and password can be used to authenticate with Kerberos, but these must be added to the 'kerberos' configuration section in the sso-agent.conf file (see below).

The Kerberos administrator needs to associate the Agent’s username with the Kerberos SPN (Service Principal Name) to which clients will request access. Since the clients will use the SPNEGO (“Negotiate”) mechanism, the SPN will be HTTP/hostname where hostname is the host name specified by the clients. If the clients will use more than one host name to refer to the SSO Agent, all the corresponding SPNs need to be associated with the username used by the agent.

For example, suppose that clients will connect to http://sso-agent.example.com:8080 and http://sso-agent:8080, that the username for the agent is geneos and that Kerberos authentication is provided by Windows Active Directory. In that case, the following commands need to be run as Administrator on a machine that has the Support Tools installed:

setspn.exe -A HTTP/sso-agent.example.com geneos
setspn.exe -A HTTP/sso-agent geneos

Notice that the port number is not used. It is not possible to associate the HTTP service(s) provided by a single host with more than one SPN.

Kerberos configuration

The SSO Agent uses the JAAS authentication framework. This requires two configuration files: krb5.conf and login.conf. They are located in the conf directory alongside the sso-agent.conf file. Their location can be changed by editing the 'kerberos.krb5_conf' and 'kerberos.login_conf' settings in the sso-agent.conf file.

Editing the krb5.conf file

The krb5.conf file needs to be edited to refer to your Kerberos realm and KDC (Key Distribution Center) host. If you use Microsoft Active Directory, the KDC will usually be the Active Directory server and the first part of the Kerberos realm will match the Active Directory domain. In general, if your KDC host is kdc.example.com, then your Kerberos realm is likely to be EXAMPLE.COM.

Edit the krb5.conf file, replacing all occurrences of CHANGEME.COM with your Kerberos realm and replacing domaincontroller.changeme.com with the host name of your KDC.

Kerberos configuration settings

The ‘kerberos’ section of the sso-agent.conf file can be modified to change the location of the krb5.conf and login.conf files, add Kerberos-specific username and password, and disable the realm-checking feature of the SSO Agent.

The Kerberos-specific username ('kerberos.user') and password ('kerberos.password') should be added to these settings if you wish to use different credentials to LDAP. If they are absent, the SSO Agent defaults to LDAP credentials.

The "kerberos.realm_mismatch"option determines whether the SSO Agent allows authorisation of users authenticated with realms different from the one which the SSO Agent is authenticated with. This has two settings: 'reject' (default) and 'allow'. This option may be relevant for organisations that have 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:

  • If two users with identical names exist in the different realms, there is no way for the SSO Agent to differentiate which roles are allowed for each user - therefore the Agent should reject to authorise.
  • If usernames are globally unique across the organisation, and the allowed roles for each user are available to the SSO Agent, then it can allow the realm mismatch.
"kerberos": {
	"krb5_conf": "conf/krb5.conf"  # Location of Kerberos configuration information
	"login_conf": "conf/login.conf" # Location of login.conf required by JAAS
	"realm_mismatch": "reject" # Other option is 'allow'
	# "user": "ITRS geneos"  # (Optional) User name to authenticate with Kerberos KDC
	# "password": "ChangeMe" # (Optional) Password to authenticate with Kerberos KDC
}

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

Note: If the SSO Agent detects a request containing an NTLM header where a Kerberos header is expected, it will log an explicit error message and will not attempt Kerberos authentication. (No configuration needed.)

Kerberos troubleshooting

To authenticate via Kerberos, the client (Active Console 2 or a web browser) sends a request to the KDC for a ticket for the SSO Agent service. To do so, it 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.

The following points are of particular importance:

  • Do not include the port number in the SPN(s) 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(s), ensure that the name the alias resolves to is registered as an SPN for the SSO Agent.

Enabling NTLM authentication

By default the example configuration has Negotiate enabled. To enable NTLM change Negotiate to NTLM in the authentication section of the agent configuration:

authentication: ["NTLM","BASIC"]

Running SSO Agent

In order to run SSO Agent both a Windows batch file and a Linux bash script are provided in the bin directory of the package. Neither script takes parameters; both are intended to be run from the package base directory. Thus you would run either:

./bin/sso-agent

or

.\bin\sso-agent.bat

If Kerberos authentication (“Negotiate” protocol) is used, SSO Agent can be run on either a Linux or a Windows machine. On Linux, the sso-agent script in the bin directory can be used to start the Agent.

If NTLM authentication is required, SSO Agent needs to be run on a Windows machine using additional DLLs. A variant of SSO Agent which supports this is available by request to ITRS Support.

If the host machine has multiple network adapters, or if you want to run the agent on a TCP port other than the default, you should update the server settings in the sso-agent.conf file:

"server": {
   "port": 80                 # Port that the web server will listen on
   "bind_address": "0.0.0.0"  # Bind address that the service will use
}                        

Logging is configured via the logback.xml file in the conf directory of the SSO Agent package.

The other essential configuration settings have been covered above (Generate a signing key and LDAP settings)

Using environment variables to provide passwords

If passwords are stored in the sso-agent.conf file, its file permissions should be set so that it can only be read by users authorised to know the passwords. Alternatively, the passwords can be provided to the SSO Agent as environment variables. The kerberos.password,ldap.password, server.key_store.password, and server.trust_store.password can be set using environment variables. If the password setting is absent in the sso-agent.conf file it will instead be 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.key_store.password ITRS_SSO_KEYSTORE_PW
server.trust_store.password ITRS_SSO_TRUSTSTORE_PW

Be aware that any setting present in the sso-agent.conf file will override the corresponding environment variable.

Environment variables can be used 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).

Using a web browser to check that the agent is running

You can check that the agent is running by visiting the status endpoint. This can be reached by visiting the URL http://agent.example.com:80/status (replacing agent.example.com:80 with the correct host and port of the SSO Agent).

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

The return code for the status endpoint is always 200 OK. The status page shows the SSO Agent and Java versions, start time of the SSO Agent, and configured authentication methods.

Using a web browser to check that the agent can authenticate a user

You can check that the agent can authenticate a user by visiting the testuser endpoint. In order to do this you must set the value of ‘show_test_pages’ in the ‘server’ section of the config to ‘true’ and then restart the SSO Agent.

You can check that the agent is working correctly by visiting one of its token endpoints using a web browser:

  • Visit the URL http://agent.example.com:80/testuser (replacing agent.example.com:80 with the correct host and port of the SSO Agent).
  • If your browser is configured to trust the SSO Agent using NTLM or Kerberos then you should see the results page, otherwise you will be asked for your login details.
  • If you are connecting from a Linux host, you will first need to log in to Kerberos (using kinit or another Kerberos client).
  • The results page will show the user details extracted from ldap using the fields configured in sso-agent.conf.

High Availablity

The SSO Agent is a stateless REST service. As such it is possible to run multiple instances of the service. So long as the configuration (including certificates and keys) are the same, and the SSO Agent’s DNS A record points to the IP addresses of all the machines running the SSO Agent, then this will provide a high availabilty solution.

Running as a Windows Service

The SSO Agent comes with a service wrapper that will allow the SSO Agent to run as a Windows service.

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

Then run sso-service.exe as Administrator:

.\bin\sso-service.exe install

This will install the service. The service can then be started and stopped using the Windows Services Manager The service is listed as “Geneos SSO Agent”.

To remove the service, run as Administrator:

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

The windows service wrapper used is winsw.

Enabling HTTPS

The tokens issued by the SSO Agent contain potentially confidential information about users. Furthermore, if the Basic authentication method is used, the authentication request from the Geneos client contains the username and password typed by the user. Therefore, it is highly recomended that HTTPS is enabled on the SSO Agent.

To enable HTTPS, an SSL certificate needs to be provided and stored in the Java keystore used by the SSO Agent.

The same keystore is used to store both the HTTPS SSL certificate and the signing key for the SSO tokens. (see Generating SSO Agent’s Key)

A script ‘ssl_utils.bat’ is provided in the package bin directory that can help generate and import a certificate into a Java keystore.

The scripts need to be updated first, following the instructions given as comments in the script itself before running it or following the other steps below.

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

  • Generate a new self-signed certificate: This provides confidentiality, but does not authenticate the SSO Agent to browser clients. This may be an issue if Basic authentication is used.
  • Import an existing SSL certificate issued by a Certificate Authority (CA) trusted by your users’ Web browsers.

To generate a new self-signed certificate

Run .\ssl_utils.bat and specify the host name or IP address of the box. This will generate the certificate and add it to a keystore.

cd <sso_agent_install_dir>
.\bin\ssl_utils.bat add <certificate_alias>

or

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

Note that, if the SSO Agent uses a self-signed certificate, web browsers will 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).

To 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. In order 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 that should be used are as follows:

  • -export: This 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 that will be populated with the PKCS12 server certificate.

Once you have a PKCS12 server certificate then 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: This tells openssl to generate a pkcs12 certificate.
  • -srckeystore output_cert.pfx: File containing the private key of the certificate to be converted
  • -srcstoretype PKCS12: The 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: This is the password used to access the key store.
  • -destkeypass CHANGE-ME: This is the password used to access the key in the key store. This MUST be the same as the keystore password.
  • -alias <certificate_alias>: The name of the alias used when storing the certificate in the keystore.

Configuring SSO Agent to use the key

Once the SSL certificate has been added to the keystore, the enable_ssl field in the server section of the sso-agent.conf file needs to be changed to true, the ssl_alias field in the server section of the sso-agent.conf file needs to be changed the value of the alias used when storing the certificate in the keystore. Finally, the values in the trust store section need to be checked. (It has been assumed above that the trust store and key store use the same file and password.)

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

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

Configuring SSO Agent

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.

Each configuration option is documented by a comment in the config file. Most of the important options have been described in the previous sections of this document; the remainder are described below.

Selecting authentication methods

The SSO Agent supports three authentication methods:

  • HTTP Basic authentication (BASIC)
  • NT LAN Manager v2 (NTLM)
  • Kerberos/SPNEGO (Negotiate)

Normally, SSO Agent is set up to offer Negotiate and Basic authentication; most client applications will try to authenticate via Negotiate first and, if this fails, to use Basic authentication. This can be changed using the authentication setting, which takes the form of a list of authentication methods.

authentication: ["NTLM","BASIC"]

For example, to disable Basic authentication, change this to:

authentication: ["Negotiate"]

A Note on Passwordless Login

ITRS Single Sign On capability supports both NTLM and Kerberos technologies for passwordless login. You can download the SSO Agent binary enabled for Kerberos technology from our downloads site, while the SSO Agent binary enabled for NTLM technology is only available on request. Please contact ITRS Support for more information.

Token Lifetimes

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

The following token types are supported by SSO Agent:

  • Access Token: This 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.
  • Code: This token is a 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: This 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.
  • Refresh Token: This is a long lived token, which is 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 will need to re-authenticate (this is handled automatically by Active Console 2).

The expiry time of a token is set to a number of seconds (its ‘duration’) after it is granted. The durations for the various types of token are set in the ‘token_duration’ section of the configuration.

token_duration: {
code: 60
rest: 300
access: 3600
refresh: 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 will redirect the browser back to the Web service. The SSOAgent will only do this for services with known URIs. These URIs are listed in the ‘redirect_uri’ setting:

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

Issuer name

The tokens issued by the SSO Agent include the "iss" field specified by the JWT standard. There is generally no need to change the setting which specifies its content:

"issuer": "ITRS SSO Agent"

Enabling SSO in Geneos components

Active Console 2

To use SSO authentication with ActiveConsole 2, you need to:

  • Set up the SSO Agent URL Advanced property so that Active Console 2 can connect to the SSO Agent.
  • Set up one or more Gateway connections to use the SSO Logon method.

If the SSO Agent is set up to use SSL/TLS and the certificate that it uses is not in the CA chain, then Active Console 2 rejects the connection as untrusted.

You must add the local root certificate or the self-signed certificate to the Active Console 2 cacerts:

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

Gateway 2

To enable SSO authentication for a Gateway, use the Gateway Setup Editor to complete the settings on the Single Sign On tab in the Authentication section of the Gateway configuration.

The contents of the PEM file generated by the SSO agent (see Exporting the public key) should be copied verbatim into the “Public key” setting on that tab. Do not omit the header or footer lines.

Gateway user roles should also be set up with role properties that match LDAP groups to which the Geneos users belong.

See the Gateway Authentication - Technical Reference for more details.

Web Dashboard

To use SSO authentication with Web Dashboard, you need to:

  • Set up the following properties in <web_dashboard_install_dir>/config/sso.properties file: sso.agent.url, webdashboard.url, sso.enabled
  • The contents of the PEM file generated by the SSO agent (see Exporting the public key) should be copied to the file specified in the sso.pubkey property in <web_dashboard_install_dir>/config/sso.properties file

When using the SSO Agent in HTTPS:

Run ./bin/ssl_utils.sh or .\bin\ssl_utils.bat and export the SSO Agent’s certificate named ssokey.

cd <sso_agent_install_dir>
./bin/ssl_utils.sh export ssokey

or

cd <sso_agent_install_dir>
.\bin\ssl_utils.bat export ssokey

Copy the generated ssokey.cer to your Web Dashboard instance and import it to your Web Dashboard’s JRE, using the steps below:

Web Dashboard with JRE

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

Web Dashboard without JRE

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>

Using a JRE

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

See the Web Dashboard Reference Guide for more details.

Webslinger

To use SSO authentication with Webslinger, you need to:

  • Set up the following properties in the Webslinger setup file: SSO_PROVIDER, SSO_PUBKEY, WEB_SERVICE_URL.
  • The contents of the PEM file generated by the SSO agent see Exporting the public key should be copied to the file specified in the SSO_PUBKEY section of the webslinger setup.

See the Webslinger Reference Guide for more details.