Skip to content

SAML authentication

Funnelback provides support for the integration of search and administration functions with a remote SAML identity provider (IdP). This enables Funnelback to utilise an existing SAML authentication mechanism to provide single sign-on access to both the search results and the administration interface.

Configuration - Funnelback side

Funnelback's SAML authentication can apply separately to the search interface and the administration interface, and these may be configured independently.

Search configuration

By default, Funnelback's search interface does not require any authentication. Enabling SAML authentication on Funnelback's search interface will force all users to authenticate through the configured SAML IdP before they are permitted to perform any search request.

Please note that Funnelback does not currently provide any support for making authorisation decisions for search access based on the search user's SAML credentials, so it is assumed that any user who is authenticated by the IdP is permitted to query Funnelback. Of course, document level security may subsequently adjust what specific results the user in question can be shown.

The following global.cfg settings are used by Funnelback to control the configuration of SAML authentication for the search interface:

Option Description
auth.publicui.saml.enabled Enable SAML authentication.
auth.publicui.saml.identity-provider-metadata-url Specify the SAML identity provider's metadata URL (file:// or http://).
auth.publicui.saml.logout-url Specify the URL to log users out of the IdP (Public search)
auth.publicui.saml.entity-id-prefix Specify the prefix for the SAML entity ID.
auth.publicui.saml.keystore-path Specify the location of the SAML keystore.
auth.publicui.saml.keystore-password Specify the password for SAML keystore.
auth.publicui.saml.key-alias Specify the alias of private key to use in SAML keystore.
auth.publicui.saml.key-password Specify the password for private key in SAML keystore.
auth.publicui.saml.default-login-redirect-url Specify where to send users after an IdP initiated login

Administration configuration

Funnelback normally authenticates all requests to administration endpoints (including search via the admin port) through either HTTP Basic or a custom header/cookie login mechanism. By enabling SAML authentication for Funnelback administration, SAML authentication will be used in preference to these mechanisms (though please note that the normal mechanisms will continue to function for any locally created users who do exist on the Funnelback server.

The following global.cfg settings are used by Funnelback to control the configuration of SAML authentication for the administration interface. The majority of the settings correspond to those for the search interface above.

Option Description
auth.admin.saml.enabled Enable SAML authentication.
auth.admin.saml.identity-provider-metadata-url Specify the SAML identity provider's metadata URL (file:// or http://).
auth.admin.saml.logout-url Specify the URL to log users out of the IdP.
auth.admin.saml.entity-id-prefix Specify the prefix for the SAML entity ID.
auth.admin.saml.keystore-path Specify the location of the SAML keystore.
auth.admin.saml.keystore-password Specify the password for SAML keystore.
auth.admin.saml.key-alias Specify the alias of private key to use in SAML keystore.
auth.admin.saml.key-password Specify the password for private key in SAML keystore.
auth.admin.saml.groovy-permission-mapper Specify the location of the Groovy class which maps SAML users to their permissions.
auth.admin.saml.default-login-redirect-url Specify where to send users after an IdP initiated login

Shared configuration

Option Description
auth.saml.algorithm Control the hash algorithm used within SAML in both admin and search.

Configuration - Identity provider side (ADFS)

Specific configuration is required when using ADFS as an identity provider.

Secure hash algorithm

Funnelback supports signing SAML messages with either the SHA-1 or the SHA-256 algorithm.

ADFS by default supports only SHA-256 and so the global config option auth.saml.algorithm must be used to configure Funnelback to use this algorithm.

If necessary, ADFS may be configured in the service provider advanced properties to accept the backwards-compatibility default of SHA-1 as follows:

SHA-1 secure hash algorithm configuration

Name ID mapping

The "Name ID" attribute must be passed to Funnelback on login. To achieve this configure a transform claim rule:

Add Transform Claim Rule

Then select which claim you would like to send as the Name ID. Sending the UPN is recommended. Make sure "Name ID" is spelled with a space:

SAML Name ID

Note that spring-security-saml describes an alternate approach for claims which might also be relevant/appropriate in some configurations.

Sending the user group memberships

It's usually useful to send the group membership information to Funnelback so that permissions within Funnelback can be configured accordingly. For example users belonging to the AD group "IT" may gain full permissions, whereas users of the "Marketing" group will only get access to the Marketing Dashboard.

To do so configure a group membership as a claim:

Configure group membership as claim

Group membership

Service provider metadata to register in the IdP

When configured with SAML, Funnelback exposes itself as a set of SAML service providers. In configuring your identity provider for Funnelback, you may need to export Funnelback's service provider metadata and provide it as part of the identify provider configuration.

The following URLs on your Funnelback server (after SAML configuration and assuming the default port configuration is used) will provide the required service provider metadata for each component:

Administration service providers

  • Administration interface - https://funnelback-server.example.com:8443/search/admin/saml/metadata
  • Admin-API - https://funnelback-server.example.com:8443/admin-api/saml/metadata
  • Mediator - https://funnelback-server.example.com:8443/search/admin/mediator/saml/metadata
  • Push-API - https://funnelback-server.example.com:8443/push-api/saml/metadata
  • Search (on the administration port) - https://funnelback-server.example.com:8443/s/saml/metadata

Search service providers

  • http://funnelback-server.example.com/s/saml/metadata or https://funnelback-server.example.com/s/saml/metadata

Limitations

Funnelback will load identity-provider metadata only during startup. If SAML is enabled and the identity provider metadata is unavailable at startup Funnelback will fail to start (and errors will be logged).

Please note that Funnelback does not currently support the configuration of multiple identity providers for search or administration (though search and administration may themselves use different identify providers).

Funnelback does not currently support SAML authentication to the WebDAV service used for replicating indexes and configuration between servers.

If a custom task picker is used to delay long running tasks, then additional restrictions will apply to the management of these tasks when SAML is enabled. Users will not be able to delete any task unless they are given the sec.queue.delete-other-users-tasks permission.

top

Funnelback logo
v15.24.0