How to deploy PaperCut Application Server with SAML single sign-on
on 13 August 2020 02:35 PM
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.
At the time of printing:
Add accountability to the document forever:
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.
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
You will also need the IIS 6 Management Compatibility options installed which can be found under
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
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.
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>
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>
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">
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"/>
Now we need to tell Shibboleth where it can find the value we want to set to ppcuser, We used the
<Attribute name="http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname" id="ppcuser"/>
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:
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
Now on the right select
Check the Enable Proxy checkbox and click Apply on the right
Select your site on the left and click on
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.
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
Now restart IIS by clicking restart on the right or by opening a command prompt window and running
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
From the dropdown you are going to want
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.
Now for the fun bit, Open a browser and go to
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.
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
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