Gateway Hub SSO Agent

Overview Copied

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 Copied

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 Copied

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 Copied

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 Copied

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

Alternative authentication Copied

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 Copied

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:

• id_rsa_hub_sso.pub (public key)
• id_rsa_hub_sso.key (private key)

To update the Gateway Hub configuration, run:

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

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

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

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 Copied

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 Copied

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 Copied

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

SSO in Geneos Copied

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.