SAML 2.0 Authentication Configuration Properties

Advanced configuration properties for SAML 2.0 SSO

The properties listed here are only applicable if SAML 2.0 authentication is being used. Support for SAML 2.0 authentication is installed using the kcm-guacamole-auth-saml package or enabled with the Docker installation. If using the keeper/guacamole Docker image, support for SAML 2.0 authentication is configured using environment variables.

SAML 2.0 Configuration Properties

Property name	Description
saml-idp-metadata-url	The URI of the XML metadata file that from the SAML Identity Provider that contains all of the information the SAML extension needs in order to know how to authenticate with the IdP. This URI can either be a remote server (e.g. https://) or a local file on the filesystem (e.g. file://). Often the metadata file contains most of the required properties for SAML authentication and the other parameters are not required.
saml-idp-url	The base URL of the SAML IdP. This is the URL that the SAML authentication extension will use to redirect when requesting SAML authentication. If the saml-idp-metadata-url property is provided, this parameter will be ignored. If the metadata file is not provided this property is required.
saml-entity-id	The entity ID of the Keeper Connection Manager SAML client, which is generally the URL of the Keeper Connection Manager server, but is not required to be so. This property is required if either the saml-idp-metadata-url property is not specified, or if the provided metadata file does not contain the SAML SP Entity ID for the Keeper Connection Manager Client.
saml-callback-url	The URL that the IdP will use once authentication has succeeded to return to the Keeper Connection Manager web application and provide the authentication details to the SAML extension. The SAML extension currently only supports callback as a POST operation to this callback URL. This property is required.
saml-strict	Require strict security checks during SAML logins. This will insure that valid certificates are present for all interactions with SAML servers and fail SAML authentication if security restrictions are violated. This property is optional, and will default to true, requiring strict security checks. This property should only be set to false in non-production environments during testing of SAML authentication.
saml-debug	Enable additional logging within the supporting SAML library that can assist in tracking down issues during SAML logins. This property is optional, and will default to false (no debugging).
saml-compress-request	Enable compression of the HTTP requests sent to the SAML IdP. This property is optional and will default to true (compression enabled).
saml-compress-response	Request that the SAML response returned by the IdP be compressed. This property is optional and will default to "true" (compression will be requested).
saml-group-attribute	The name of the attribute provided by the SAML IdP that contains group membership of the user. These groups will be parsed and used to map group membership of the user logging in, which can be used for permissions management within the Keeper Connection Manager Client, particularly when layered with other authentication modules. This property is optional, and defaults to “groups”.
saml-private-key-path	Path to a private key for use with connecting to an ID Provider which is configured to expect signed requests
saml-x509-cert-path	Path to a certificate used to authenticate to an ID Provider which is configured to expect signed requests

Controlling Login Behavior

Keeper Connection Manager loads authentication extensions in order of priority, and evaluates authentication attempts in this same order. This has implications for how the login process behaves when an SSO extension is present:

If the SSO extension has priority:

Users that are not yet authenticated will be immediately redirected to the configured identity provider. They will not see a Keeper Connection Manager login screen.

If a non-SSO extension has priority:

Users that are not yet authenticated will be presented with a Keeper Connection Manager login screen. Additionally, links to the configured identity provider(s) will be available for users that wish to log in using SSO.

The default priority of extensions is dictated by their filenames, with extensions that sort earlier alphabetically having higher priority than others. This can be overridden by setting the extension-priority property within guacamole.properties.

Automatically redirecting all unauthenticated users

To ensure users are redirected to the SAML identity provider immediately (without a Keeper Connection Manager login screen), ensure the SAML extension has priority over all others:

extension-priority: saml

Presenting unauthenticated users with a login screen

To ensure users are given a normal Keeper Connection Manager login screen and have the option to log in with traditional credentials or with SAML, ensure the SAML extension does not have priority:

extension-priority: *, saml