Reverse Proxy Auth Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID reverse-proxy-auth-plugin Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies 		1.4.0 (archives)
May 27, 2014
1.532
ldap (version:1.8) 		Source Code
Issue Tracking
Pull Requests
Maintainer(s) 		GitHub
Open Issues
Pull Requests
Kohsuke Kawaguchi (id: kohsuke)
Wilder Rodrigues (id: wilderrodrigues)
Usage Installations 2014-May 581
2014-Jun 615
2014-Jul 642
2014-Aug 679
2014-Sep 737
2014-Oct 779
2014-Nov 774
2014-Dec 796
2015-Jan 806
2015-Feb 848
2015-Mar 919
2015-Apr 900

This plugin lets you delegate the authentication to the reverse proxy that you run in front of Jenkins. It also includes Authorisation, which is done via LDAP groups loaded from the HTTP header or LDAP search - based on the username.
This plugin is useful in an environment where you have a reverse proxy, such as Apache, already available and configured to perform necessary user authentication. This reverse proxy must pass the authenticated user name in an HTTP header of a fixed name. With this plugin, Jenkins that run behind it will simply look at this header and use its value as the user name. In the newest release, version 1.3, this plugin also offers Authorisation mechanism. The user can have Role Based Matrix Authorization configured, which will look up into LDAP groups that can be loaded into Jenkins either via HTTP header groups field or LDAP search.

The default values for the HTTP header fields are:

  1. Header User Name: X-Forwarded-User
  2. Header Groups Name: X-Forwarded-Groups
  3. Header Groups Delimiter: |## In case no LDAP server is informed the plugin will try to take the information from the HTTP header. When no header groups information can be retrieved, in case the user wants to do authentication only, and there is no LDAP server configured, the user retrieved from the header will have only Authenticated authority available.

Apache Configuration Example

    <Proxy http://localhost:8080/jenkins*>
        AuthName "Please sign in with your Apache user name and password"
        AuthType BASIC
        AuthUserFile /etc/apache2/passwd
        Require valid-user

        # prevent the client from setting this header
        RequestHeader unset X-Forwarded-User

        # Adds the X-Forwarded-User header that indicates the current user name.
        # this portion came from http://old.nabble.com/Forcing-a-proxied-host-to-generate-REMOTE_USER-td2911573.html#a2914465
        RewriteEngine On
        # see the Apache documentation on why this has to be lookahead
        RewriteCond %{LA-U:REMOTE_USER} (.+)
        # this actually doesn't rewrite anything. what we do here is to set RU to the match above
        # "NS" prevents flooding the error log
        RewriteRule .* - [E=RU:%1,NS]
        RequestHeader set X-Forwarded-User %{RU}e
        # strip the REALM of Kerberos Login
        # RequestHeader edit X-Forwarded-User "@REALM$" ""
    </Proxy>

Notes

  • Make sure that clients cannot bypass the reverse proxy. If they can send requests directly to Jenkins, then a malicious client can send in arbitrary header name with arbitrary value, thus compromising the security of Jenkins
  • Make sure you configure the reverse proxy to erase the header that you use to pass the authenticated user name. This prevents malicious client from setting the header name with arbitrary value, which would ruin the security.
  • If your authorization need is simple (for example, every valid user gets full access and everyone else gets no access), then you need not use this plugin, as you can do both authentication and authorization in the reverse proxy.
  • Hit http://yourserver/whoAmI to see the actual HTTP headers your Apache is sending to Jenkins. This is useful for trouble-shooting.

Jenkins says my reverse proxy setup is broken...

Since Jenkins 1.572 this message can also appear if you don't access Jenkins through a reverse proxy: Make sure the Jenkins URL configured in the System Configuration matches the URL you're using to access Jenkins.

If you see the error message "It appears that your reverse proxy set up is broken" in the "Manage Jenkins" page, here's what's happening.

For a reverse proxy to work correctly, it needs to rewrite both the request and the response. Request rewriting involves receiving an inbound HTTP call and then make a forwarding request to Jenkins (sometimes with some HTTP headers modified, sometimes not.) Failing to configure the request rewriting is easy to catch, because you just won't see any pages at all.

But proper reverse proxying also involves rewriting response. (Details: Hyperlinks in HTML) The primary place where this needs to happen is the "Location" header in the response, which is used during redirects. Jenkins would send back "Location: http://actual.server:8080/jenkins/foobar" and the reverse proxy needs to rewrite this to "Location: http://nice.name/jenkins/foobar". Unfortunately, failing to configure this correctly is harder to catch.

So Jenkins has a proactive monitoring to make sure this is configured correctly. It uses XmlHttpRequest to request a specific URL in Jenkins (via relative path, so this will always get through provided the request is properly rewritten), which will then redirect the user to another page in Jenkins (this works correctly only if you got the reponse rewriting configured correctly), which then returns 200.

This error message indicates that this test is failing. The most likely cause is that you got the response rewriting incorrectly done. See Running Jenkins behind Apache for additional tips about reverse proxy. While the page talks primarily about Apache, it has some information that applies to other reverse proxies.

Note. The reverse proxy tests were improved in release 1.552 so users with previously working proxy setups may start to receive proxy warnings. If using Apache check that nocanon is set on ProxyPass and that AllowEncodedSlashes is set as per the Apache link above. (AllowEncodedSlashes is not inherited in Apache configs, so this directive must be placed inside the VirtualHost definition.)

Also, make sure to set the X-Forwarded-Proto header if your reverse proxy is accessed via HTTPS, but Jenkins itself is not.

For further diagnosis, try using cURL:

curl -iL -e http://your.reverse.proxy/jenkins/manage http://your.reverse.proxy/jenkins/administrativeMonitor/hudson.diagnosis.ReverseProxySetupMonitor/test

(assuming your Jenkins should be visible at http://your.reverse.proxy/jenkins/)

Changelog

Version 1.4.0 (2014 May 27)

  • Fixed JENKINS-22402 - The authorities of each user are not required in the config.xml
  • Adding group membership filter setting
  • Adding Cache Update Interval so Jenkins can reload user's LDAP groups on the fly, no need to restart Jenkins if users are added to new groups.

Version 1.3.3 (2014 March 14)

  • The user retrieved from the HTTP header is needed when the plugin does not use the LDAP advanced options.

Version 1.3.2 (2014 March 5)

  • Fixed concurrent problem with instance variable that was not being used any more, although it could cause issues with users' rights visibility.

Version 1.3.1 (2014 January 8)

  • Fixed the load user by name method in the Reverse Proxy Security Realm when LDAP is activated.

Version 1.3 (2014 January 7)

  • Including Authorisation via both HTTP header groups field and LDAP search.

Version 1.2 (2013 December 20)

  • Including Authorisation via LDAP groups performing search based on user name. 

Version 1.0.1 (2013 May 7)

  • list all unprotected root actions (URLs) in the configuration, so the admin gets a hint which URLs should not be protected by the reverse proxy (supported with Jenkins core 1.495+)

Version 1.0 (2011 March 26)

  • Initial release

Labels

Edit
plugin-user plugin-user Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment