[Legacy] Using WebAuth with PaperCut

IMPORTANT: this article refers to a 3rd party SSO solution that will no longer be supported as of August 31, 2018.

For more information, please see the end-of-life announcement here: https://uit.stanford.edu/service/saml/webauth-announce .

For other SSO options, consider Windows Integrated Authentication. We have also since rolled out single sign-on for Google customers using our Print Enablement solutions, Print Deploy and Mobility Print.

This KB article applies to PaperCut version 13.1 and higher.

Single sign-on (SSO) is a feature of many authentication and directory services currently on the market. It allows users to sign-in once and be authenticated to multiple separate applications.

Many organizations provide SSO with WebAuth, which can be used with an Apache reverse proxy to provide a secure but transparent authentication system. Oxford University has worked alongside PaperCut to add support for this SSO configuration into PaperCut MF.

Note: The following configuration instructions should only be attempted by System Administrators with experience in both WebAuth’s SSO solution and Apache reverse proxy configuration. The Apache WebAuth module also requires that you run Apache on Linux.

WebAuth integration is a security related feature. It’s important that your team consider security during any implementation. The PaperCut software development team is happy to make themselves available to assist with planning, validation or to act as a sounding board for architecture and decisions. If you are implementing WebAuth, we’d recommend reaching out via ( http://support.papercut.com ) referencing this article so we can book in some time for a discussion.

How it works

1. Bob’s browser hits papercut.example.com, which is an Apache reverse proxy
2. The WebAuth extension for Apache inspects Bobs cookies for his session key.
3. If Bob is not authenticated, he will be redirected to the authentication server before being allowed to continue
4. If bob is authenticated the reverse proxy will send a request to the real PaperCut server (real-papercut.example.com) on Bobs behalf. This request looks like any normal HTTP request, but with an addition HTTP header that contains Bobs identity. In most cases this would be Bobs username, but could potentially be any other form of ID that your linked directory service accepts.
5. When the request reaches the PaperCut server, PaperCut will recognize that the request is coming from a designated SSO proxy and will attempt to look for the identifying HTTP header.
6. Upon finding the HTTP header contents, PaperCut will treat Bobs forwarded request as already authenticated. Bob will not need to reauthenticate to access PaperCut because the proxy will continue to package his identifier along with all the subsequent requests.

How to configure

You will need an Apache web server (running on Linux) set up on the public facing side of the request, papercut.example.com in the example above. The web server will need mod_proxy installed.

In your Apache site configuration add a new virtual host. This defines what server the proxy will forward requests to, as well as which HTTP header to put the user’s identity into.

<VirtualHost *:80>
        ServerName papercut.example.com
        SSLEngine on
        SSLProxyEngine on
        ProxyRequests off
    &lt;Location / &gt;
            AuthType WebAuth
            require valid-user
            ProxyPass https://real-papercut.example:9192/
            ProxyPassReverse https://real-papercut.example:9192/
            RequestHeader set "SSO-USER" "%{WEBAUTH_USER}e"
    &lt;/Location&gt;

</VirtualHost>

Once your Apache reverse proxy is configured, update the following config keys using PaperCut’s config editor (Options → Actions → Config Editor).

auth.web-login.sso-header

This should be the HTTP header key that you’ve configured the reverse proxy to use above. PaperCut uses this value to determine which user is authenticated. In the example above the header value would be SSO-USER.

auth.web-login.sso-ip-whitelist

Set this value to the ip address of the reverse proxy. PaperCut will only trust SSO connections coming from this IP address. If you have multiple reverse proxies, you need to separate the IP address’s with a comma.

auth.web-login.sso-logout-url (Optional)

By default SSO authenticated users who logout of PaperCut will be redirect back to the welcome screen. System Administrators may use this configuration option to make PaperCut redirect SSO authenticated users to a diferent URL.

Important: Do not override the Host header when setting up a proxy in front of PaperCut MF or PaperCut NG, as it will conflict with HTTP header origin checks (CSRF) security checks, rely on “X-Forwarded-Host” instead. For example, when using mod_proxy with Apache, do not use “mod_rewrite” to change the HOST header.

If you really have to rewrite the Host header, then the CSFR checks can be disabled using the “server.csrf-check.validate-request-origin” configuration in server.properties.