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.

Warning: The SAML support in Funnelback 15.12 is considered experimental.

Funnelback will not provide official support for SAML configurations in 15.12 and future versions of Funnelback may refine SAML configuration options in non-backwards compatible ways.

Configuration

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:

auth.publicui.saml.enabled

Set to 'true' if SAML should be enabled on Funnelback's search interface and 'false' otherwise.

auth.publicui.saml.identity-provider-metadata-url

Set to the IdP metadata Funnelback should use. If the metadata is stored as a file on the Funnelback server use something like file:///some/path/metadata and if the metadata is available as a URL use something like http://identity-provider.com/metadata. Please note that the SSL certificate of any HTTPS metadata source must be trusted (see the keystore details below).

auth.publicui.saml.logout-url

Set to the location where users should be redirected in order for them to be logged out of the IdP. If the IdP metadata that is provided in auth.publicui.saml.identity-provider-metadata-url defines a SingleLogoutService, then this url should not be set.

auth.publicui.saml.entity-id-prefix

Sets a prefix on the service provider entity IDs which Funnelback should expose itself as via SAML.

auth.publicui.saml.keystore-path

Set to the location of the java keystore which is used to store the private key Funnelback will use for SAML communications. For example '$SEARCH_HOME/conf/samlPublicUIKeystore.jks'.

http://docs.spring.io/spring-security-saml/docs/1.0.2.RELEASE/reference/html/security.html provides details on how this keystore can be created with java's 'keytool' utility. This documentation also covers the creation of the private key described below, and configuring trust of certificates presented by other systems for SAML usage.

auth.publicui.saml.keystore-password

Set to the main password of the keystore above.

If desired, the password may be obfuscated using the Jetty web server's password obfuscation tool. Please note that the checksum and crypt forms are not supported (since the original password must be accessible for Funnelback to open the keystore).

auth.publicui.saml.key-alias

Set to the alias of the specific key in the keystore above that Funnelback should use for SAML as a service provider.

auth.publicui.saml.key-password

Set to the key password for key with the alias above.

As with auth.publicui.saml.keystore-password, the password may be obfuscated if desired.

After these settings are configured in Funnelback's global.cfg file, Funnelback's jetty web server process must be restarted for them to take effect.

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.

auth.admin.saml.enabled

Set to 'true' if SAML should be enabled on Funnelback's admin interface and 'false' otherwise.

auth.admin.saml.identity-provider-metadata-url

Set to the IdP metadata Funnelback should use. If the metadata is stored as a file on the Funnelback server use something like file:///some/path/metadata and if the metadata is available as a URL use something like http://identity-provider.com/metadata. Please note that the SSL certificate of any HTTPS metadata source must be trusted (see the keystore details below).

auth.admin.saml.logout-url

Set to the location where users should be redirected in order for them to be logged out of the IdP. If the IdP metadata that is provided in auth.admin.saml.identity-provider-metadata-url defines a SingleLogoutService, then this url should not be set.

auth.admin.saml.entity-id-prefix

Sets a prefix on the service provider entity IDs which Funnelback should expose itself as via SAML.

auth.admin.saml.keystore-path

Set to the location of the java keystore which is used to store the private key Funnelback will use for SAML communications. For example '$SEARCH_HOME/conf/samlAdminKeystore.jks'.

http://docs.spring.io/spring-security-saml/docs/1.0.2.RELEASE/reference/html/security.html provides details on how this keystore can be created with java's 'keytool' utility. This documentation also covers the creation of the private key described below, and configuring trust of certificates presented by other systems for SAML usage.

auth.admin.saml.keystore-password

Set to the main password of the keystore above.

If desired, the password may be obfuscated using the Jetty web server's password obfuscation tool. Please note that the checksum and crypt forms are not supported (since the original password must be accessible for Funnelback to open the keystore).

auth.admin.saml.key-alias

Set to the alias of the specific key in the keystore above that Funnelback should use for SAML as a service provider.

auth.admin.saml.key-password

Set to the key password for key with the alias above.

As with auth.admin.saml.keystore-password, the password may be obfuscated if desired.

auth.admin.saml.groovy-permission-mapper

Sets the path to a groovy script implementing a mapping from SAML credentials provided by the identify provider to objects representing Funnelback Users.

The following example script provides a simple example in which the groovy script simply loads the 'admin.ini' file for all valid SAML users. In practice a script would likely interrogate the given SAMLCredential, and load or create a suitable user object which grants permissions appropriate for the user.

import com.funnelback.springmvc.api.config.security.saml.SamlFunnelbackUserMapper;
import org.springframework.security.saml.SAMLCredential;
import com.funnelback.springmvc.api.config.security.user.model.FunnelbackUser;
import com.funnelback.springmvc.api.config.security.user.service.FunnelbackUserDetailsService;

import java.io.File

import org.springframework.security.core.userdetails.UsernameNotFoundException;

public class ExampleGroovySamlFunnelbackUserMapper implements SamlFunnelbackUserMapper {
    public FunnelbackUser getSAMLDerivedUser(SAMLCredential credential, FunnelbackUserDetailsService funnelbackUserDetailsService, File searchHome) throws UsernameNotFoundException {
    	// Treat all valid SAML users as admins
		FunnelbackUser user = funnelbackUserDetailsService.loadUserByUsername("admin");

		// Ensure we don't let them try to change passwords etc.
		user = user.withIsLocallyAuthenticated(false);

		return user;
	}
}

The file containing the script can be located anywhere so long as it is readable by the Funnelback jetty web server. Further detail about the provided SAMLCredential object is available within the spring security SAML documentation.

After these settings are configured in Funnelback's global.cfg file, Funnelback's jetty web server process must be restarted for them to take effect.

Service provider metadata

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

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

top

Funnelback logo
v15.12.0