Using WebAuth with PaperCut

KB Home   |   Using WebAuth with PaperCut

Main.WebAuthAndPaperCut History

Hide minor edits - Show changes to output

June 28, 2018, at 09:28 PM by Aaron Pouliot - Added Category SSO
Changed line 62 from:
''Categories:'' [[!Implementation]]
to:
''Categories:'' [[Category.SSO|+]], [[!Implementation]]
September 15, 2017, at 02:34 AM by 139.130.165.134 -
Added lines 57-59:
'''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.
September 16, 2013, at 02:46 AM by Alec - Fixed typo
Changed lines 7-8 from:
Many organizations provide SSO with [[http://webauth.stanford.edu/|WebAuth]], which can be used with an Apache reverse proxy to provide a secure but transparent authentication system. Oxford University has worked alongside PaperCut add support for this SSO configuration into PaperCut MF.
to:
Many organizations provide SSO with [[http://webauth.stanford.edu/|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.
Changed lines 9-10 from:
'''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.
to:
'''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.
June 20, 2013, at 02:48 AM by matt - Mention linux as requirement.
Changed lines 9-10 from:
'''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.
to:
'''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.
Changed lines 22-23 from:
You will need an Apache web server 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.
to:
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.
Changed line 38 from:
               RequestHeader set "SSO-USER" "%{WEBAUTH_USER}%"
to:
               RequestHeader set "SSO-USER" "%{WEBAUTH_USER}e"
February 25, 2013, at 11:28 AM by RossM - Apon -> Upon
Changed lines 19-20 from:
# Apon 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.
to:
# 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.
Added lines 11-12:
[-`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 to support@papercut.com referencing this article so we can book in some time for a discussion.-]
Changed line 12 from:
# Bobs browser hits papercut.example.com, which is an Apache reverse proxy
to:
# Bob's browser hits papercut.example.com, which is an Apache reverse proxy
Changed line 59 from:
[-Keywords: sso, webauth, single sign-on, login, proxy, apache, mod_proxy-]
to:
[-Keywords: sso, webauth, single sign-on, login, proxy, apache, mod_proxy, signon, login, browser authentication -]
Changed lines 45-46 from:
->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.
to:
->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@@.
Changed line 31 from:
       <Location />
to:
       <Location / >
Changed lines 49-51 from:
->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.
to:
->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.
Changed lines 45-46 from:
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.
to:
->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.
Changed line 49 from:
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
to:
->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
Changed lines 52-58 from:
''Optional''

@@auth.web-login.sso-logout-url@@

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.

to:
@@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.

Changed lines 29-30 from:
       ProxyRequests Off
to:
       ProxyRequests off
February 25, 2013, at 12:14 AM by Chris - Added version.
Changed lines 3-4 from:
''This KB article applies to PaperCut version 13.1 and higher.''
to:
''This KB article applies to PaperCut version '''13.1''' and higher.''
Added lines 3-4:
''This KB article applies to PaperCut version 13.1 and higher.''
Changed lines 9-10 from:
'''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.
to:
'''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.
Changed line 13 from:
# The Webauth extension for Apache inspects Bobs cookies for his session key.
to:
# The `WebAuth extension for Apache inspects Bobs cookies for his session key.
February 24, 2013, at 11:22 PM by will - Adding categories and keywords.
Changed line 58 from:
''Categories:'' []
to:
''Categories:'' [[!Implementation]]
Changed line 60 from:
[-Keywords: TODO keywords here if needed-]
to:
[-Keywords: sso, webauth, single sign-on, login, proxy, apache, mod_proxy-]
Changed lines 5-6 from:
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 add support for this SSO configuration into PaperCut MF.
to:
Many organizations provide SSO with [[http://webauth.stanford.edu/|WebAuth]], which can be used with an Apache reverse proxy to provide a secure but transparent authentication system. Oxford University has worked alongside PaperCut add support for this SSO configuration into PaperCut MF.
Changed lines 21-23 from:
@@

<VirtualHost *:80>
to:

[@
  <VirtualHost *:80>
Changed lines 36-41 from:
</VirtualHost>

@@

Once your Apache reverse proxy is configured, update the following config keys using PaperCutís config editor.
to:
  </VirtualHost>
@]

Once your Apache reverse proxy is configured, update the following config keys using PaperCutís config editor (Options -> Actions -> Config Editor).
Changed lines 3-18 from:
Note: This documentation is incomplete and refers to an unreleased version of PaperCut

PaperCut versions 13.1 or higher allow system administrators to use WebAuth to authenticate users to PaperCut's web interface. This allows the implementation of single sign on (SSO) for PaperCut. Users will be able to access PaperCut without having to reauthenticate themselves.

-- TODO: REVERSE PROXY CONFIGURATION --

Once your Apache reverse proxy is configured, update the following config keys using PaperCut's 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.

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.


Optional:
auth.web-login.sso-logout-url=
to:
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 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.

!!!How it works
# Bobs browser hits papercut.example.com, which is an Apache reverse proxy
# The Webauth extension for Apache inspects Bobs cookies for his session key.
# If Bob is not authenticated, he will be redirected to the authentication server before being allowed to continue
# 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.
# 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.
# Apon 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 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

        <Location />
                AuthType WebAuth
                require valid-user
                ProxyPass https://real-papercut.example:9192/
                ProxyPassReverse https://real-papercut.example:9192/
                RequestHeader set "SSO-USER" "%{WEBAUTH_USER}%"
        </Location>
</VirtualHost>

@@

Once your Apache reverse proxy is configured, update the following config keys using PaperCutís 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.

@@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.

''Optional''

@@auth.web-login.sso-logout-url@@

February 17, 2013, at 10:16 PM by will - First draft of sso doc
Added lines 1-25:
(:title Using WebAuth with PaperCut:)

Note: This documentation is incomplete and refers to an unreleased version of PaperCut

PaperCut versions 13.1 or higher allow system administrators to use WebAuth to authenticate users to PaperCut's web interface. This allows the implementation of single sign on (SSO) for PaperCut. Users will be able to access PaperCut without having to reauthenticate themselves.

-- TODO: REVERSE PROXY CONFIGURATION --

Once your Apache reverse proxy is configured, update the following config keys using PaperCut's 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.

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.


Optional:
auth.web-login.sso-logout-url=
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.


----
''Categories:'' []
----
[-Keywords: TODO keywords here if needed-]

Comments

Share your findings and experience with other PaperCut users. Feel free to add comments and suggestions about this Knowledge Base article. Please don't use this for support requests.

Article last modified on June 28, 2018, at 09:28 PM
Printable View   |   Article History   |   Edit Article