SSO Agent

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

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.

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
}                                

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.

You can use the following filters to make the LDAP query more specific:

• group_filter: This is a regular expression that reduces the number of groups the query returns. This is useful when users belong to many groups but only a known subset is needed for authorisation.
• query_filter: This filter allows you to make more specific LDAP searches using fields, such as objectCategory and objectClass. For example, "query_filter" : "(objectCategory=person)(objectClass=user)" searches only for users that are people. By default, the objectClass of a query is user.
  
  In the LDAP query, the 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.

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
	}
	# "group_filter": "^[A-Z]"         # Optional regex to filter groups that user is a member of
	# "query_filter" : ""              # Optional filter to specify fields like objectCategory		
}

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

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

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 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$"]

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"

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.

Note: SSO logon is not supported when the GSE is running as a standalone process.

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.