SAML configuration

Overview Copied

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 Copied

Before configuring SAML-based SSO in the Web Console, you must add your SAML Identity Provider 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. Ensure that the SAML metadata file is a valid XML file before configuring Gateway Hub.

To add SAML metadata to Gateway Hub, follow these steps:

Note

During this process, it is recommended that you disable security for easier set up. If you prefer not to, then you need to get a token from the APID so you can add the service provider metadata using curl -H "Authorization: Bearer {token}".

  1. Set the Identity Provider metadata to the Web Console:

    hubctl config set --service-name webconsole --local-config-files saml_idp_metadata.xml installation-descriptor.yaml

  2. Download the service provider metadata XML from the Web Console:

    curl https://<host>:8443/saml/metadata -k

  3. Add the service provider metadata file to the APID:

    curl -k -X PUT -H 'Content-Type: application/xml' "https://<host>:8081/v0/security/saml/serviceprovider/metadata" -d @saml_sp_metadata.xml -v

  4. Set the Identity Provider metadata file to the APID:

    hubctl config set --service-name apid --local-config-files saml_idp_metadata.xml installation-descriptor.yaml

SAML status Copied

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:

Configure SAML Copied

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

For more information on LDAP-based SSO, see Configure single sign-on (SSO).

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 Copied

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 token expiration Copied

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

Field Description
Check Origin Specify if the origin IP of the token request should be compared against subsequent uses.
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 Active Directory 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.
Webslinger and Web Dashboard locations Specify the URLs for instances of Webslinger and Web Dashboard. This allows automatic redirects after authentication.
["Geneos"] ["Geneos > Gateway Hub"] ["Technical Reference"]

Was this topic helpful?