x509 client certificate authentication

In certain environments, it may be desirable to secure Funnelback's search interface such that only certain other systems can access it. Commonly this technique may be used when Funnelback results are consumed by some other system and that other system implements some security model after results are returned.

This kind of restriction can normally be achieved with firewall restrictions however x.509 client certificate authentication provides an option where IP based restrictions are undesirable.

Limitations

Please note that once x.509 client certificate authentication is enabled all search users, including users searching from within Funnelback's administration interface, will require trusted client certificates to access the search interface.

Please also note that many administration features, including accessibility auditor and content auditor, rely on permission to use the search interface, and will not function correctly if an administration user's browser does not present a trusted client certificate.

Configuration

Funnelback's x.509 client certificate authentication mode can be enabled by setting

auth.publicui.require-x509=true

in Funnelback's conf/global.cfg file and restarting Funnelback's web server.

After doing so, the following URLs (assuming default ports) will require the client (be it a web browser or client program) to present a trusted x.509 client certificate with each request.

• https://funnelback-server/s/*
• https://funnelback-server:8443/s/*

Note that http://funnelback-server/s/* will no longer be available to any user because the http protocol does not provide any way to present a client certificate. It may be good practice to prevent access to port 80 to avoid confusion in this case.

Creating a client certificate

Note - This documentation does not aim to teach the reader how to use keytool and configure client certificates, the following steps may be a useful prompt.

# Create a client key in the client's keystore
keytool -genkey -dname "CN=(username), OU=(user department), O=(user company), L=(user city), ST=(user state), C=(2 letter user country code)" -alias "client-alias" -keyalg RSA -validity 3650 -keypass (password) -storepass (password) -keystore client-keystore.jks

# Export the client's certificate
keytool -exportcert -alias "client-alias" -storepass (password) -keypass (password) -keystore client-keystore.jks > client-certificate.p12

# Import the client's certificate into the server's truststore
keytool -import -trustcacerts -alias "client-alias" -file client-certificate.p12 -noprompt -keypass (password) -storepass (funnelbacks_jetty.ssl.truststore-password_password) -keystore (funnelbacks_jetty.ssl.truststore-path)

Testing client certificate authentication

Once configured, you may wish to test the x.509 client certificate authentication. Doing so with non-java clients will likely require exporting the client certificate and private key with a command such as:

# Export the client certiciate to PKCS12 format suitable for curl (on Mac OS), Firefox or other clients
keytool -importkeystore -srckeystore client-keystore.jks -srcalias "client-alias" -srcstorepass (password) -destkeystore client-keystore-for-curl.pfx -deststoretype PKCS12 -deststorepass (password) -destkeypass (password)

On platforms where curl supports PKCS12 keystores, the connection can then be tested with a command such as:

curl "https://funnelback-server/s/search.html?collection=coll&query=test" --cert client-keystore-for-curl.pfx:(password)