Web Single Sign-on Problems and Diagnosis (Troubleshooting)

Web Single Sign-on Problems and Diagnosis

PaperCut’s Web SSO functionality (see SSO chapter in manual) is compelling and in the case of Windows Authentication, easy to implement.

But the technology underlying SSO is complex and there are many Windows policy and configuration variables that can occasionally cause things to go wrong.

Before implementing SSO it is very important to work through the planning section in the manual. Complete the post install tests before putting SSO in production.

 

Locked out of PaperCut after enabling SSO

If you find yourself locked out of PaperCut, you can bypass SSO to get PaperCut’s standard login screen by adding “/nosso” to the URL. For example:

 
   http://mypapercutserver:9191/admin/nosso
 

Users still prompted to login

If automatic Windows Authentication cannot proceed, the browser may ask for your credentials. If you provide incorrect credentials, or click Cancel, the request will fail as “Not Authorized”. There are several reasons why you may see this behavior:

  • You are not logged into Windows. Users accessing the site from a mobile device or a Mac or Linux computer can expect to see the authentication dialog.
  • Your browser does not support Integrated Windows Authentication or needs configuration. Firefox, for example, requires configuration as described here.
  • The PaperCut server is not configured to be in the “Intranet Zone”. This applies to Internet Explorer and Chrome browsers. Go to Control Panel → Internet Options → Security. Select Intranet Zone and ensure the PaperCut server is included. By default a URL containing a period ‘.’ will not belong to the Intranet Zone and may need to be manually added.
 

Windows SSO not working when PaperCut runs as a Domain User account

In this scenario, the URL for the PaperCut server is already in the Intranet Zone, but users are still being prompted for credentials to sign in when using Internet Explorer or Chrome. This was seen to happen when customers followed the instructions to set up their PaperCut Application Server service to run as a domain user or Service Account. The solution is to edit an advanced attribute on the account that PaperCut is running as, then specify the FQDN of your PaperCut server for the servicePrincipalName attribute. This issue was was fixed with the release of PaperCut 18.2.6.

Steps:

  1. Open Active Directory Users and Computers.
  2. Go to View and select Advanced Features.
  3. Find the service account PaperCut is running as, then right click and choose Properties.
  4. Find the Attribute Editor tab and look for servicePrincipalName, then enter the fully qualified domain name of your PaperCut Server, and click OK to apply.
  5. Then restart the PaperCut Service and test.

(Note that If you try browsing to the web interface again and seen an error code “0×20b5:- The name reference is invalid”, then try editing the servicePrincipalName with this syntax “http/fully qualified domain”. Also in some cases this has been case sensitive and the syntax are “HTTP/fully qualified domain”.)

 

White screen when attempting login

A white screen with no browser authentication prompt indicates a failure in the Windows Authentication process. For example, there may be a site or browser mis-configuration that makes the Windows Domain controller unreachable. You should ensure that the browser is accessing the PaperCut server directly and not via a proxy server.

Internet Explorer users may see this when they are actually getting a “HTTP 413” error (see below)

 

Error 413 “Full HEAD” when attempting login

If using Kerberos SSO the HTTP headers can be large, and can exceed the jetty default max size (4096 bytes). This can be fixed with a [app-path]/server/server.properties config option “server.request-header-size”. The default size is 10000 bytes. It seems that for kerberos SSO it needs to be higher. e.g. 32000. This can be set in the server.properties file by adding a brand new line with:
server.request-header-size=32000
The App Server will then need to be restarted.
Note that this will only work with PaperCut build 14.2 (28942) or later

 

Trying to log in as admin but redirected to user pages

If your Windows login does not have PaperCut admin rights, you will not be able to access the admin interface. Instead, you may be redirected to the PaperCut user interface. If you have been using the built-in “admin” account prior to using SSO, you may log in with that account using the http://mypapercutserver:9191/admin/nosso URL and grant your Windows account the necessary admin rights.

 

Diagnostics

Try to isolate the problem as much as possible. For example, log in to the Windows machine running the PaperCut application server and try to access PaperCut from localhost.

If you wish to report an SSO problem to PaperCut support, please collect the following diagnostic information:

  • Windows version on PaperCut server and client
  • Type of Browser
  • Server debug logs

To collect the server debug logs:

  1. Turn on debug logging (instructions here: https://www.papercut.com/kb/Main/HowToEnableDebugInNG)
  2. Turn on SSO. Take a screen shot of your SSO configuration.
  3. Attempt to log in (and note the date/time)
  4. Log in using /nosso and turn off SSO
  5. Turn off debug logging and set the logs to us along with the time of your SSO login attempt

 

Link to original article