Geneos ["Geneos"]

Gateway Hub SSO Agent

Overview

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 the stand alone SSO Agent, see SSO Agent User Guide.

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.

Prerequisites

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 Geneos configuration.

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.

Geneos configuration

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.

Enable SSO with Active Console

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

  1. Open your Active Console.
  2. Navigate to Tools > Settings > Advanced.
  3. Add the URL location of the SSO Agent in the SSO Agent URL box.
  4. Click OK to close the Settings window.
  5. Test the SSO Login by pressing SSO Login on the menu bar.
  6. Navigate to Tools > Settings > Connections.
  7. In the Connections box, change the Logon method of the desired Gateways to SSO.

The Active Console rejects the connection as untrusted if the SSO Agent is configured to use SSL/TLS and the certificate that it uses is not in the CA chain. You must add the local root certificate or the self-signed certificate to the Active Consolecacerts. For example:

                .\JRE\bin\keytool.exe -keystore .\lib\security\cacerts ^
-import -alias ssl_cert -file C:\dump\p-eu-geneos.cer

Enable SSO in Gateway

To enable SSO authentication for a Gateway:

  1. Open the GSE.
  2. Navigate to Authentication > Single Sign On.
  3. (Optional) Add the URL location of the SSO Agent in the Sso agent box.
  4. Copy the SSO Agent's public key in PEM format into the Public key box. Do not omit the header or footer lines.
  5. Set up the Gateway user roles with role properties that match LDAP groups to which the Geneos users belong.

Enable SSO with Web Dashboard

To use SSO authentication with Web Dashboard:

  1. Configure the following properties in <web_dashboard_install_dir>/config/sso.properties file:
    • sso.agent.url
    • webdashboard.url
    • sso.enabled
    • sso.pubkey

    For more information, see Enabling SSO in Web Dashboard.

  2. Ensure the SSO Agent's public key is in PEM format in the file you have specified in sso.pubkey.

Web Dashboard supports Basic and Kerberos authentication. When you are connecting to SSO Agent through Kerberos, Web Dashboard looks for the krb5.conf in /etc/ directory by default.

If you want to modify its location:

  1. Open run/geneosws start-up scripts.
  2. Edit the config under SSO_PROPERTIES:
  3. -Djava.security.krb5.conf=/etc/krb5.conf

Configuration using SSO Agent with HTTPS

There are additional configuration steps with Web Dashboard when using the SSO Agent in HTTPS. To learn how to enable HTTPS, see Gateway Hub SSO Agent .

With HTTPS enabled, perform the following steps:

  1. Run one of the following commands, depending on your operating system, to export the SSO Agent's certificate named ssokey:
    • On Windows, run .\bin\ssl_utils.bat export ssokey.
    • On Linux, run ./bin/ssl_utils.sh export ssokey.
  2. Copy the generated ssokey.cer to your Web Dashboard instance.
  3. Import ssokey.cer to your Web Dashboard’s JRE, using the steps below:
    • If using a Web Dashboard with JRE, use these commands:
      cd <web_dashboard_install_dir>/JRE/lib/security
      keytool -importcert -trustcacerts -alias ssokey -file ssokey.cer \
      -keystore cacerts -storepass <keystore password; default is changeit>
    • If using a Web Dashboard without JRE, use these commands:

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

Enable SSO with Webslinger

To use SSO authentication with Webslinger:

  1. Open your Webslinger setup file.
  2. Configure the following properties in the Webslinger setup file:
    • SSO_PROVIDER
    • SSO_PUBKEY
    • WEB_SERVICE_URL

    For more information, see Webslinger Setup in Webslinger.

  3. Ensure the SSO Agent's public key is in PEM format in the file you have specified in SSO_PUBKEY.
Caution: When you connect to Webslinger using an SSO-enabled Gateway, an error may occur:

ERROR: Authentication with Gateway 192.168.101.42:36039 failed: No login credentials for connection

Webslinger only supports password and SSL authentication.

Migration from standalone SSO Agent

When deploying Gateway Hub, you may want existing Gateways to use the Gateway Hub SSO 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 Hub SSO Agent, you must provide the following files:

  • id_rsa_hub_sso.pub (public key)

  • id_rsa_hub_sso.key (private key)

To update the Gateway Hub configuration, run:

Copy
hubctl config set -n apid -l /tmp/id_rsa_hub_sso.pub /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:

Copy

RSA Private Key

-----BEGIN PRIVATE KEY-----
MIIBVgIBADANBgkqhkiG9w0BAQEFAASCAUAwggE8AgEAAkEAq7BFUpkGp3+LQmlQ
Yx2eqzDV+xeG8kx/sQFV18S5JhzGeIJNA72wSeukEPojtqUyX2J0CciPBh7eqclQ
2zpAswIDAQABAkAgisq4+zRdrzkwH1ITV1vpytnkO/NiHcnePQiOW0VUybPyHoGM
/jf75C5xET7ZQpBe5kx5VHsPZj0CBb3b+wSRAiEA2mPWCBytosIU/ODRfq6EiV04
lt6waE7I2uSPqIC20LcCIQDJQYIHQII+3YaPqyhGgqMexuuuGx+lDKD6/Fu/JwPb
5QIhAKthiYcYKlL9h8bjDsQhZDUACPasjzdsDEdq8inDyLOFAiEAmCr/tZwA3qeA
ZoBzI10DGPIuoKXBd3nk/eBxPkaxlEECIQCNymjsoI7GldtujVnr1qT+3yedLfHK
srDVjIT3LsvTqw==
-----END PRIVATE KEY-----

 

Copy

RSA Public Key

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA61BjmfXGEvWmegnBGSuS
+rU9soUg2FnODva32D1AqhwdziwHINFaD1MVlcrYG6XRKfkcxnaXGfFDWHLEvNBS
EVCgJjtHAGZIm5GL/KA86KDp/CwDFMSwluowcXwDwoyinmeOY9eKyh6aY72xJh7n
oLBBq1N0bWi1e2i+83txOCg4yV2oVXhBo8pYEJ8LT3el6Smxol3C1oFMVdwPgc0v
Tl25XucMcG/ALE/KNY6pqC2AQ6R2ERlVgPiUWOPatVkt7+Bs3h5Ramxh7XjBOXeu
lmCpGSynXNcpZ/06+vofGi/2MlpQZNhHAo8eayMp6FcvNucIpUndo1X8dKMv3Y26
ZQIDAQAB
-----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:

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

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

    Copy
    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:

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

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

    Copy
    openssl x509 -pubkey -noout -in cert.pem -out id_rsa_hub_sso.pub

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