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:
Component | Recommended Setup |
---|---|
Operating System |
Linux |
CPU | Multicore Intel / AMD |
Memory | 4 GB |
Disk | 500 MB available space |
Network | 1 Network Interface Card |
Java (JRE) | Version 11 |
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:
- Download and unpack the files
- Generate a signing key for SSO Agent
- Configure SSO Agent to use the keystore
- Configure SSO Agent’s LDAP Settings
- Configure Kerberos authentication
- Start the SSO Agent
- Check that the SSO Agent is running
- Check that the SSO Agent can authenticate a user
- Enable SSO authentication in Geneos components
Download and unpack the files Copied
- Download the SSO Agent package
sso-agent-<version>-bin.zip
from the ITRS Downloads site. - 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 bessokey
.-keyalg
— algorithm used to generate the SSO key. Must beRSA
.-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, usekeystore.db
.-storetype
— keystore type. Must bejceks
.-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:
-
Move or copy the keystore file to the
conf
directory of the SSO Agent. -
Open your
sso-agent.conf
file. -
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 thesso-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:
-
Open your
sso-agent.conf
file. -
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 theldap
andKerberos
sections of thesso-agent.conf
file. -
The
ITRS_SSO_LDAP_PW
andITRS_SSO_KERBEROS_PW
environment variables. -
The
useKeyTab
andkeytab
options in thessoagent-server
and theldap-client
sections of thelogin.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 thesso-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:
-
Open your
sso-agent.conf
file. -
In the
ldap
section, update thebase
setting with the base distinguished name for LDAP queries. -
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.
-
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 asobjectCategory
andobjectClass
.Note
By default, the SSO Agent identifies users by queryingobjectClass=user
. You can change the name of the object class by settingusers.class
to a different value, or you can replace that part of the query by settingusers.query_filter
. For example, if you want to useobjectCategory
to identify a user rather thanobjectClass
, setusers.query_filter
toobjectCategory=user
.Note
In the LDAP query, theusers.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:
- Open your
krb5.conf
file, located in theconf/
directory. - Replace
domaincontroller.changeme.com
with the host name of your Key Distribution Center (KDC). - 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 whetherhttp://
orhttps://
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-agent
command 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:
- Open your
sso-agent.conf
file. - In the
server
section, changeport
to the desired value. - In the
server
section, changebind_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:
-
Enable the endpoint in your
sso-agent.conf
file.- Open your
sso-agent.conf
file. - In the
server
section, change the value ofshow_test_pages
totrue
. - Restart the SSO Agent.
- Open your
-
If you are using Linux, log in to Kerberos using
kinit
(or another Kerberos client) and check using theklist
command that you have a Kerberos token-granting-token. -
Configure your browser to trust the SSO Agent.
-
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
.
- On Linux, you can also use the curl command
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:
- Open your Active Console.
- Navigate to Tools > Settings > General.
- Add the URL location of the SSO Agent in the SSO Agent URL field.
- Click OK to close the Settings window.
- Test the SSO Login by pressing SSO Login on the menu bar.
- Navigate to Tools > Settings > Connections.
- 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:
- Open your
GatewaySetupEditor.gci
file. - Add the
-SSOAgentURL
flag to the file. - Add the SSO Agent URL after the flag.
- For example.
-SSOAgentURL http://server.example.itrs:8083
- For example.
- 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:
- Open the GSE.
- Navigate to Authentication > Single Sign On.
- (Optional) Add the URL location of the SSO Agent in the Sso agent box.
- Copy the SSO Agent’s public key in PEM format into the Public key box. Do not omit the header or footer lines.
- 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:
- Open your Webslinger setup file.
- Configure the following properties in the Webslinger setup file:
SSO_PROVIDER
SSO_PUBKEY
WEB_SERVICE_URL
For more information, see Webslinger Setup in Webslinger.
- 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:
-
Configure the following properties in
<web_dashboard_install_dir>/config/sso.properties
file: -sso.agent.url
-webdashboard.url
-sso.enabled
-sso.pubkey
For more information, see Enabling SSO in Web Dashboard. -
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:
- Run the
./bin/ssl_utils.sh export ssokey
command to export the SSO Agent’s certificate namedssokey
: - Copy the generated
ssokey.cer
to your Web Dashboard instance. - 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:
-
Open your
sso-agent.conf
file. -
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"]
.
- The possible options are:
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 beJCEKS
).-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:
- Open your
sso-agent.conf
file. - In the
server
section, change the value ofenable_ssl
totrue
. - In the
server
section, change the value ofssl_alias
to value of the alias used when storing the certificate in the keystore. - In the
server.trust_store
section, check the value oflocation
andpassword
. It is recommended that thekey_store
andtrust_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:
-
Open your
sso-agent.conf
file. -
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:
- Open your
sso-agent.conf
file. - 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:
Password Setting | Environment Variable |
---|---|
kerberos.password | ITRS_SSO_KERBEROS_PW |
ldap.password | ITRS_SSO_LDAP_PW |
server.key_store.password | ITRS_SSO_KEYSTORE_PW |
server.trust_store.password | ITRS_SSO_TRUSTSTORE_PW |
You can set environment variables to provide passwords by using the export
command prior to running the SSO Agent. For example:
export ITRS_SSO_KERBEROS_PW=[your password here]
export ITRS_SSO_LDAP_PW=[your password here]
export ITRS_SSO_KEYSTORE_PW=[your password here]
export ITRS_SSO_TRUSTSTORE_PW=[your password here]
./bin/sso-agent
Authentication errors can be investigated by using the SSO Agent log (logs/sso-agent.log
).
Run multiple instances of SSO Agent Copied
The SSO Agent is a stateless REST service. Therefore, you can run multiple instances of the service.
Before you do so, check that:
- The configuration (including certificates and keys) is the same across all instances.
- 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:
- Open your
sso-agent.conf
file. - In the
ldap
section, update thelocation
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.
- 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.
- 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:
- Open your
sso-agent.conf
file. - In
ldap.groups
section, change the value ofaccess_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:
- Open your
sso-agent.conf
file. - 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.
- In
ldap.groups
section, update thequery_filter
setting.- This filter enables you to make specific LDAP searches using fields such as
objectCategory
andobjectClass
.Note
By default, the SSO Agent identifies groups by queryingobjectClass=group
. You can change the name of the object class by settinggroups.class
to a different value, or you can replace that part of the query by settinggroups.query_filter
. For example, if you want to useobjectCategory
to identify a group rather thanobjectClass
, setgroups.query_filter
toobjectCategory=group
.Note
In the LDAP query, thegroups.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.
- This filter enables you to make specific LDAP searches using fields such as
If you want to disable the endpoint, perform the following:
- Open your
sso-agent.conf
file. - In
ldap.groups
section, change the value ofqueryable
tofalse
.
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:
- Open your
sso-agent.conf
file. - In
key_store
section, modify theexport_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:
- Open your
sso-agent.conf
file. - In
key_store
section, addenable_public_key_endpoint
and set totrue
.
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:
- Open your
sso-agent.conf
file. - In
kerberos
section, modify thekrb5_conf
andlogin_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:
-
Open your
sso-agent.conf
file. -
In
kerberos
section, modify theuser
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 yoursso-agent.conf
file should match the exact case of the username in the KDC. -
In
kerberos
section, modify thepassword
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 thesso-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:
- Open your
sso-agent.conf
file. - In
kerberos
section, change therealm_mismatch
toallow
.
Troubleshooting Copied
Scenario | Recommended action |
---|---|
Clients fail to authenticate in ITRS applications. |
|
Browser falls to authenticate using /testuser endpoint. |
|
Status page is not available. |
|
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
Scenario | Recommended action |
---|---|
SSO Agent log reports that client is attempting NTLM authentication. Error message in the form ERROR com.itrsgroup.ssoagent.authentication - Client request uses unsupported NTLM token. This is caused by a failed SPN lookup in the Windows domain controller. |
|
SSO Agent log reports that it cannot verify Kerberos credential because realm is not as expected. Warning message in the form WARNING com.itrsgroup.ssoagent.authentication - Cannot verify Kerberos credential: realm='xxx', expected='yyy' |
|
SSO Agent reports error reading Kerberos message. |
|