Geneos ["Geneos"]
You are currently viewing an older version of the documentation. You can find the latest documentation here.

Gateway Hub SSO Agent


Gateway Hub includes built in SSO Agent functionality as part of the API daemon.

You can use the Gateway Hub SSO Agent as an alternative to the stand alone SSO Agent used in typical Geneos installations.

For more information about configuring any GeneosSSO Agent, see SSO Agent User Guide.

For more information about configuring SSO in Gateway Hub, see LDAP configuration and SAML configuration.

Note: SAML based SSO is only available when using the Gateway HubSSO Agent and is not possible with the standalone SSO Agent.

Intended audience

This document covers material relevant to two types of users:

  • Gateway Hub users setting up centralised configuration.

  • Geneos users adding Gateway Hub to their deployment.


You must have a working Gateway Hub installation. Some features depend on a specific version of Geneos or Gateway Hub, these are noted where relevant.

For guidance on installing and configuring Gateway Hub, see the Introduction to Gateway Hub and Installation guide.

Centralised Gateway configuration

Centralised configuration behaviour depends on the authentication method that is used.

For more information about centralised configuration, see Centralised Gateways User Guide.

Note: You cannot lock a centrally configured Gateway setup unless you are using the Gateway Hub SSO Agent. This is because Gateway Hub uses SSO tokens to identify the user creating the lock.

Gateway Hub SSO Agent

If Gateway Hub SSO security is enabled then, when using Centralised Configuration, a token provided by the user is required by Gateway Hub in order to see, validate, and change Gateway setups.

As a result, to change a Gateway setup you must configure Active Console and Gateway Setup Editor to log in using the Gateway Hub SSO Agent. For information on how to do this, see SSO in Geneos.

Alternative authentication

Beginning from Geneos 5.5.0 you can use Centralised Configuration without enabling Gateway Hub SSO security.

If Gateway Hub SSO security is not enabled, then the following alternate authentication methods are available:

  • No authentication (including Gateway Authentication disabled).

  • Password authentication.

  • System authentication.

  • External SSO provider.

Migration from standalone SSO Agent

When deploying Gateway Hub, you may want existing Gateways to use the Gateway HubSSO Agent.

To simplify this process, beginning from Gateway Hub 2.3.0 you can configure the API daemon to use the public and private key pair of the existing standalone SSO Agent. This ensures that existing Gateways do not need to be reconfigured.

For more information about the keys used by a stand alone SSO Agent, see Procedure in SSO Agent User Guide.

To configure the Gateway HubSSO Agent, you must provide the following files:

  • (public key)

  • id_rsa_hub_sso.key (private key)

To update the Gateway Hub configuration, run:

hubctl config set -n apid -l /tmp/ -l /tmp/id_rsa_hub_sso.key config.yaml

When you apply configuration, note the following behaviours:

  • If these files are non-empty, the API Daemon will load and use them.

  • Both keys must be configured at the same time, otherwise the API daemon will fail to start.

  • The keys must form a matching public and private key pair, otherwise the API Daemon will fail to start.

  • If the files are empty, the API daemon will use existing keys if there are any, otherwise it will generate new ones. In this case, Gateways configured to use known keys cannot use Gateway Hub for SSO.

  • If you are using the Capacity Planner application for Gateway Hub, then you will need to restart the application. For instructions on how to do this, see Restart Capacity Planner application in Troubleshooting.

Key format

The keys used for SSO services must have the following properties:

  • Must be base 64 encoded (PEM).

  • Must be in PCKS #8 syntax.

  • Must not be encrypted.

  • Must be generated using RSA.

A correct key file should look similar to the following:

RSA Private Key


RSA Public Key

-----END PUBLIC KEY-----

Extract keys from a stand alone SSO Agent

To extract the public and private keys used by an existing stand alone SSO Agent, you will need the following:

  • OpenSSL

  • Java keytool

Private key

To extract the private key:

  1. Convert the the JCEKS keystore into a standard PKCS12 keystore:

    keytool -importkeystore -srcstoretype JCEKS -srckeystore keystore.db -destkeystore keystore.p12 -deststoretype PKCS12
  2. Extract a key.pem file from the store:

    openssl pkcs12 -in keystore.p12 -nodes -nocerts -out key.pem
  3. Convert the private key to the expected format:

    openssl pkcs8 -in key.pem -nocrypt -out id_rsa_hub_sso.key

Only the id_rsa_hub_sso.key file is required, the intermediary files keystore.p12 and key.pem should be deleted.

Public key

To extract the public key:

  1. Convert the the JCEKS keystore into a standard PKCS12 keystore (this repeats the step in the extraction of the private key above, and does not need to be repeated if you have already performed this step):

    keytool -importkeystore -srcstoretype JCEKS -srckeystore keystore.db -destkeystore keystore.p12 -deststoretype PKCS12                          
  2. Extract a cert.pem file from the store:

    openssl pkcs12 -in keystore.p12 -nokeys -out cert.pem
  3. Convert the public key to the expected format:

    openssl x509 -pubkey -noout -in cert.pem >

Only the file is required, the intermediary files keystore.p12 and cert.pem should be deleted.

SSO in Geneos

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

The Geneos components that use ITRS SSO Agent are:

  • Active Console
  • Gateway
  • Web Dashboard
  • Webslinger

Role based authorisation

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.