Gateway Hub ["Geneos"]
["Geneos > Gateway Hub"]["User Guide"]

SAML configuration

Overview

You can configure Single sign-on (SSO) and role-based security in Gateway Hub using SAML authentication. Once configured, users can access with their Gateway Hub environment credentials without further password prompts.

Security Assertion Markup Language (SAML) is an open standard that allows an identity provider (IdP) to pass authentication credentials to service providers (SP). You can configure Gateway Hub to act as a SP and connect to your IdP for SSO. Gateway Hub will map SAML credentials to its internally configured roles. This process uses the industry-standard OAuth 2.0 protocol.

Note: SAML based SSO for Gateway Hub is only available when using the integrated Gateway Hub SSO Agent and is not possible with the standalone SSO Agent. Other Geneos components, such as Gateways and the Active Console, do not support SAML.

For more information about LDAP based SSO, see LDAP configuration.

Prerequisites

Before configuring SAML-based SSO in the Web Console, you must add your SAML Identity Provider's metadata to Gateway Hub. Typically, a REST API endpoint exists to automatically generate Identity Provider metadata. Otherwise, contact your systems administrator.

SAML metadata is configured using the hubctl tool. Check that the SAML metadata file is a valid XML file before configuring Gateway Hub.

To add SAML metadata to Gateway Hub:

  1. Add the SAML metadata file to the REST API configuration:
    hubctl config set --service-name apid --local-config-files saml_idp_metadata.xml installation-descriptor.yaml
  2. Add the SAML metadata file to the Web Console configuration:
    hubctl config set --service-name webconsole --local-config-files saml_idp_metadata.xml installation-descriptor.yaml

SAML status

If you configure SAML SSO, an information bar is displayed at the top of this page providing the current status.

The SAML screen displays the following status:

  • SAML working correctly — both the SAML endpoint and Gateway Hub security are enabled.
  • SAML disabled — when the endpoint is disabled, the SAML Config page disappears from the Web Console sidebar, but the LDAP Config page remains accessible.
  • Not configuredSAML endpoint is enabled, but Gateway Hub security is disabled. When the endpoint is enabled, both the LDAP Config and SAML Config are displayed in the Web Console sidebar.
  • Critical error — when the endpoints of the Gateway Hub return a timeout error or the request is blocked.

Configure SAML

By default, SAML is disabled. You can enable only one of SAML or LDAP-based SSO.

For more information on LDAP-based SSO, see LDAP configuration.

Note: When SAML is enabled, you cannot enable Security in the LDAP Config page. You can only enable security from the SAML Config page.

Field mappings

The Field mappings define the mapping between Gateway Hub user attributes and SAML 2.0 user attributes. These attributes are extracted from the SAML 2.0 Assertion and are used to derive the user's Gateway Hub security roles.

Field Description
First name SAML user's first name.
Surname SAML user's surname.
Groups

SAML user's group.

Mandatory: Yes

   

SAML role mappings

You must map the Geneos roles used to manage permissions in Gateway Hub to SSO groups and their members.

You can assign SSO groups and users to have either Administrator or Operator roles in Geneos. Mapping users directly to Geneos roles is supported but not recommended except for testing and proofs of concept.

Administrator

Field Description
Groups List of SSO groups that Gateway Hub will grant administrator permissions.
User List of SSO users that Gateway Hub will grant administrator permissions.
   

Click Add new row to add new elements to the list.

Operator

Field Description
Groups List of SSO groups that Gateway Hub will grant operator permissions.
User List of SSO users that Gateway Hub will grant operator permissions.
   

Click Add new row to add new elements to the list.

Caution: Ensure that you give the configuring user administrator permissions, either as a user or as part of a group. Otherwise, SSO will not be enabled. It is important that the administrator role is mapped correctly.

SAML token expiration

This section allows you to configure security tokens. You can set the token expiration of each field in the following format:

  • seconds
  • minutes
  • hours
  • days

Field Description
Code The duration for a short-lived code token. This is provided to the web browser when the user logs in to Web Dashboard or Webslinger. The web service uses this code token to obtain an access token for the user session.
Rest The duration for REST command tokens. As this token cannot be restricted to a single process, it is less secure and its lifetime should be limited.
Access The duration for OAuth 2.0 access tokens. A token is provided to any client component when it requests access to the REST API using SSO.
Refresh The duration for a refresh token. This is used to obtain a new access token without requiring the users to re-authenticate themselves, as long as the SSO groups of the users have not changed since the refresh token was initially granted. When this token expires the user needs to re-authenticate, which is handled automatically by Active Console and the Web Console. The duration for this token can be longer-lived than the others.