[Legacy] How to deploy PaperCut NG/MF Application Server with SAML Single Sign-On

This article needs a disclaimer. It was written a few years ago by a guest author, and effectively showcases how it can be possible to configure PaperCut to work with a SAML Single Sign-On system by using PaperCut’s WebAuth authentication in tandem with a 3rd party identity management system known as Shibboleth. However, updates come and go and the instructions in this article are no longer for current versions of Shibboleth. While we want to update these instructions to help our customers, we have to admit that this article is several paces outside of our realm of expertise so our ability to help in this area is limited.

We’ve kept this article in place as something of a time-capsule to show you what can be possible. If you are an expert in this area and you’d like to help us get this information updated please reach to us through our Support Portal and let us know.

As they say, “two tech walkthroughs are better than one” so feel free to look at Implementing Papercut SSO using a Shibboleth SP blog provided by the University of Kent, as this is another great resource to aid you in your SSO setup and configuration.

Background

This guide is applicable to both PaperCut NG and MF. For the sake of simplicity, the guide will only refer to PaperCut MF, but the exact same steps can be taken for PaperCut NG.

There are a number of places where PaperCut MF authenticates users, which occurs before the document is printed, at the time of printing and after printing.
Before printing:

• Administrate PaperCut MF or view reports through the admin web interface
• End users visit the user web interface to submit web print jobs, view statistics and top up their account for example.
• Identify the owner of a print job, whether they print from a managed, shared or self managed BYOD device

At the time of printing:

• Authenticate the user at the release station, through methods like username and password, card swipe, two factor authentication with card and pin or even biometric options.

Add accountability to the document forever:

• Optionally apply a watermark / digital signature to all pages, which adds an encrypted HMAC signature to the page which can be traced back to the user who printed the document.

When authenticating users, PaperCut MF interfaces directly with directory services like Active Directory or LDAP. Additionally, you can also configure single sign-on on the admin web interface and user web interface, where PaperCut MF will rely on an external SAML service for authentication.

This article covers how to configure SAML single sign-on with PaperCut NG and MF, using Active Directory Federation Services (ADFS), IIS and Shibboleth. Although, the same concept can be applied to similar services.

We would love to hear from you if you used different tools, especially if you can help others by providing a how-to guide which we can publish on our web site.

Special thank you to Jonathan at Selectec for providing this guide.

IIS Configuration (Shibboleth)

If you have not already done so install IIS onto either the PaperCut Application Server or a different server. If you install IIS onto the PaperCut Application Server make sure you have not configured PaperCut MF to use port 80 or 443 and make sure you don’t tell IIS to use any of the standard PaperCut ports (9191, 9192, 9193).

You will need to make sure that you have ISAPI Extensions and ISAPI Filters installed on IIS which can both be found under Add Server Roles > Web Server (IIS) > Web Server > App Development

You will also need the IIS 6 Management Compatibility options installed which can be found under Add Server Roles > Web Server (IIS) > Management Tools > IIS 6 Management Compatibility

ADFS Configuration

If you have not already installed ADFS on your Domain Controller take a few minutes to go and do that.

We found that the steps here were helpful when doing the install if you have never done it before.

Make sure you make a note of your Federation Service Name, as we will need this later.

Add Relying Party Trust

Select Claims Aware then click Next

Select Import Data about the relying party and enter the FQDN for your IIS Server followed by /Shibboleth.sso/Metadata (For iis.domain.vm the URL would be iis.domain.vm/Shibboleth.sso/Metadata)

Optionally edit the display name and add a note if you want to.

Set your access control policy. If you don’t want to lock down which users or groups can authenticate leave the default options set.

Double check the settings and make sure you are happy with them and click Next so it can finish.

Edit Claim Issuance Policy

Right click on your Party Trust and select Edit Claim Issuance Policy. For our rule template we are going to use Send LDAP Attributes as Claims

Now we are going to select the AD attribute we want to send back and what type of outgoing claim type to set it to. Give your claim a name and select Active Directory from the Attribute Store. Under LDAP Attribute select SAM-Account-Name and set the Outgoing type to Windows account name.

Click Finish

Shibboleth Installation & Configuration

Download the latest version of Shibboleth from https://shibboleth.net/downloads/service-provider/latest/ and install it using the default options. (at time of writing, this is valid for Shibboleth version 3.3)

All files are under [C:\opt\shibboleth-sp\etc\shibboleth]

Open shibboleth2.xml with a text editor.

Edit InProcess so we use the correct IIS Site

We need to change the site name. This will be the fully qualified domain name (FQDN) that your users connect to.

  <InProcess logger="native.logger">
    <ISAPI normalizeRequest="true" safeHeaderNames="true">
        <Site id="1" name="iis.domain.vm" scheme="https" port="443" />
    </ISAPI>
  </InProcess>

NOTE: If you are running Shibboleth V3 then an additional entry needs to be put into the code above. V3 requires the command useHeaders=“true”. Therefore, if you are implementing a Shibboleth V3 configuration, please use the code below, which has the useHeaders=“true” command added.

  <InProcess logger="native.logger">
    <ISAPI normalizeRequest="true" safeHeaderNames="true" useHeaders="true">
        <Site id="1" name="iis.domain.vm" scheme="https" port="443" />
    </ISAPI>
  </InProcess>

Update RequestMapper

The RequestMapper tells IIS which Paths for a certain host need to use Shibboleth for authentication. We are going to use “user” for ours so any user going to host/user will need to be logged in if not they will be taken to the login page. If you wanted to add /admin to this, you can just copy and paste the user line and replace user with admin.

  <RequestMapper type="Native">
       <RequestMap>
           <Host name="iis.domain.vm">
               <Path name="secure" authType="shibboleth" requireSession="true"/>
               <Path name="user" authType="shibboleth" requireSession="true"/>
           </Host>
       </RequestMap>
  </RequestMapper>

Update ApplicationDefaults

The ApplicationDefaults will set the remote_user variable which will contain the headers we want to set we will want to make sure we include ppcuser here as that is what we will use in the PaperCut MF configuration for Web Auth.

  <ApplicationDefaults entityID="https://iis.domain.vm/shibboleth"
    REMOTE_USER="eppn persistent-id targeted-id ppcuser"    
   cipherSuites="ECDHE+AESGCM:ECDHE:!aNULL:!eNULL:!LOW:!EXPORT:!RC4:!SHA:!SSLv2">

Update SSO

The SSO section contains the location of our Identity Provider which will be your Federation Service Name followed by /adfs/services/trust.

  <SSO entityID="http://fs.domain.vm/adfs/services/trust"
       discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">
       SAML2 SAML1
  </SSO>

Add automatic metadata fetching

There are 2 ways you can load the metadata for your identity provider the first is from a local file which you would need to manually update if you ever make changes to it and the other is by using a URL which will automatically grab the metadata as needed and will make life easier later. This URL is going to be your Federation Service Name followed by /federationmetadata/2007–06/federationmetadata.xml

  <MetadataProvider type="XML" url="https://fs.domain.vm/federationmetadata/2007-06/federationmetadata.xml"/>

Open attribute-map.xml

Now we need to tell Shibboleth where it can find the value we want to set to ppcuser, We used the Windows Account Name option in the claims issuance so that is what we will set here.

  <Attribute name="http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname" id="ppcuser"/>

Restart Shibboleth

You have 2 ways to do this, either load up Services Manager (services.msc) and find Shibboleth 2 Daemon and click restart or open a command prompt window and run:

net stop shibd_default
net start shibd_default

IIS Configuration (Proxy)

The only thing left to do now is to setup IIS to act as a proxy to do this we will the IIS ARR (Application Request Routing) module which can be found here: https://www.iis.net/downloads/microsoft/application-request-routing

Once installed we will need to enable the Proxy option, Open IIS Manager and select the local server from the tree on the left then find Application Request Routing Cache.

Now on the right select Server Proxy Settings

Check the Enable Proxy checkbox and click Apply on the right

Select your site on the left and click on URL Rewrite.

Click Add Rules on the right and pick Blank Rule from under Inbound rules.

The first rule to create is one to ignore any requests that come in to [FQDN]/Shibboleth.sso/ as we don’t want to block any of the Shibboleth functions.

1. Give your rule a name and set the Requested URL to Matches the Pattern and set Using to Regular Expression.
2. Set the Pattern to Shibboleth.sso/.*
3. Check the Ignore case” checkbox
4. Set the Action type at the bottom to None
5. Check Stop Processing of subsequent rules.

Our next rule will be to pass anything else off to PaperCut Application Server. Create a new blank rule and this time set the pattern to (.*)

Now for the action set the type to Rewrite and for the Rewrite URL use http://[papercut_ip_or_fqdn]:9191/{R:1} and check Append Query String. With a bit more work you can configure this internal route to use HTTPS if needed.

Now restart IIS by clicking restart on the right or by opening a command prompt window and running iisreset.

PaperCut MF Configuration

Everything should now be good to go so we can get PaperCut MF configured to use Web Auth for the SSO.

Login to the PaperCut admin portal and go to Options > Advanced. Look for Web Single Sign-On (SSO) and enable it.

From the dropdown you are going to want WebAuth, The HTTP Header Key will be ppcuser which will contain the username after a successful authentication attempt. The Allowed WebAuth IP addresses list will only need the IIS server’s IP in it but to play it safe also add the IPv4 and v6 localhost addresses (127.0.0.1 and 0:0:0:0:0:0:0:1) and the IP for the PaperCut Application Server.

Now select the pages you want to use SSO for. If you followed the steps above it will just be for the User login page but you can change it as needed. For the logout URL you can use https://[iis_fqdn_or_ip]/Shibboleth.sso/Logout?return=https://papercut.com with this option when the user logs out they will be redirected to the PaperCut website. You can change the return URL to anything you want.

Testing

Now for the fun bit, Open a browser and go to http://[IIS_HOST]/ you should see the ADFS login page and you will be able to login by using domain\username and your password which will then take you to the PaperCut MF User page like the gif below.

Troubleshooting

While the steps above should be enough to get you up and running every environment is a little bit different. If you do run into any issues the first thing to do is to check the URLs you used. Some of them will work if you enter them into a browser from the IIS host. The 3 to check are listed below.

• Shibboleth Status: https://localhost/Shibboleth.sso/Status
• Shibboleth Metadata: https://localhost/Shibboleth.sso/Metadata
• ADFS Metadata: https://[adfs_fqdn]/federationmetadata/2007-06/federationmetadata.xml

You can also find the Shibboleth log files under C:\opt\shibboleth-sp\var\log\shibboleth. While working on this I found shibd.log to be the most useful. You can do a quick search for “ERROR” or “FATAL” and find out where it went wrong.

If you manage to authenticate but PaperCut MF is still showing the login page, enable debug logging in the PaperCut Application Server then try again. Open the server.log under [install_path]/server/log and do a search for “WebSsoAuthenticationFilter”, this will give you a good understanding of what is going on. If you happen to find the error “Not using SSO because remote IP is not on the whitelist” in the log, but you’re scratching your head because you can see where you added the server’s IPv4 loopback address to Allowed WebAuth IP addresses, then try adding the IPv6 loopback address as well: 0:0:0:0:0:0:0:1.

If you are running PaperCut MF / NG 17.3.2 or later and run into a CSRF error after authenticating check the KB article here which will tell you how to resolve the issue.

If you have enabled SSO for the Admin and can’t login add /nosso to the end of the URL and it will skip the SSO option so that you can login and check your settings.