{"id":18363069,"url":"https://github.com/jenkinsci/reverse-proxy-auth-plugin","last_synced_at":"2025-08-08T05:31:08.889Z","repository":{"id":37269865,"uuid":"1531036","full_name":"jenkinsci/reverse-proxy-auth-plugin","owner":"jenkinsci","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-31T13:31:29.000Z","size":313,"stargazers_count":20,"open_issues_count":9,"forks_count":49,"subscribers_count":98,"default_branch":"master","last_synced_at":"2025-07-31T17:28:11.709Z","etag":null,"topics":["adopt-this-plugin","authentication"],"latest_commit_sha":null,"homepage":"https://plugins.jenkins.io/reverse-proxy-auth-plugin/","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2011-03-27T00:12:32.000Z","updated_at":"2025-07-31T12:35:41.000Z","dependencies_parsed_at":"2024-01-16T17:00:42.074Z","dependency_job_id":"eea17c87-c686-4fcc-b0ef-d16c7337dfa4","html_url":"https://github.com/jenkinsci/reverse-proxy-auth-plugin","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/jenkinsci/reverse-proxy-auth-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Freverse-proxy-auth-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Freverse-proxy-auth-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Freverse-proxy-auth-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Freverse-proxy-auth-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/reverse-proxy-auth-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Freverse-proxy-auth-plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269370971,"owners_count":24406224,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adopt-this-plugin","authentication"],"created_at":"2024-11-05T23:04:43.621Z","updated_at":"2025-08-08T05:31:08.781Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","readme":"# Jenkins Reverse Proxy Authentication and Authorisation Plugin\n\nThe Reverse proxy plugin providers developers the ability to have easy and simple authentication and authorisation using SSO techniques. The plugin authenticates the user in Jenkins via a HTTP header field.\n\nWhen it comes to authorisation, the offers two options to developers: HTTP header containing LDAP groups or LDAP discovery. When one of the mentioned options is used, the developer can have Jenkins configured to use role based matrix authorisation, that will read the groups that were configured in the Reverse Proxy plugin.\n\n## The default values for the HTTP header fields are:\n\n1. Header User Name: X-Forwarded-User\n2. Header User Mail: X-Forwarded-Mail\n3. Header User Display Name: X-Forwarded-DisplayName\n4. Header Groups Name: X-Forwarded-Groups\n5. Header Groups Delimiter: |\n\nThe LDAP options can be displayed via the Advanced... button, located on the right side of the security settings.\n\nIf no LDAP information is given, the default used will be the HEADER fields. However, if both are configured, the LDAP has priority over the HTTP header.\n\nIf the username is not forwarded to Jenkins, the user will be authenticated as ANONYMOUS. When LDAP groups are sent via the HTTP header, there is no check if the username exists in the LDAP directory, so protect your proxy in order to avoid HTTP Header injection. Once an username is informed, the user will be authenticated. If no groups are returned from the LDAP search, the user will still be authenticated, but no other grants will be given.\n\nHowever, once the LDAP is properly configured instead of groups on the HTTP header, there is guarantee that only the groups of a given user will be returned. There is no possibility to get groups injected via the header.\n\nSee the fields in [ReverseProxySecurityRealm.java](https://github.com/jenkinsci/reverse-proxy-auth-plugin/blob/master/src/main/java/org/jenkinsci/plugins/reverse_proxy_auth/ReverseProxySecurityRealm.java) for details about the available options.\n\n## Alternative authentication: API Token\nAn other possibility to authenticate is to the use an HTTP Basic authentication with the Jenkins API Token.\n\nIf both methods (header specific for this plugin and HTTP Basic authentication) are used, the plugin header takes precedence.\n\n# Documentation from wiki (please edit!)\n\nThis plugin lets you delegate the authentication to the reverse proxy\nthat you run in front of Jenkins. It also includes Authorisation, which\nis done via LDAP groups loaded from the HTTP header or LDAP search -\nbased on the username.This plugin is useful in an environment where you\nhave a reverse proxy, such as Apache, already available and configured\nto perform necessary user authentication. This reverse proxy must pass\nthe authenticated user name in an HTTP header of a fixed name. With this\nplugin, Jenkins that run behind it will simply look at this header and\nuse its value as the user name. In the newest release, version 1.3, this\nplugin also offers Authorisation mechanism. The user can have Role Based\nMatrix Authorization configured, which will look up into LDAP groups\nthat can be loaded into Jenkins either via HTTP header groups field or\nLDAP search.\n\nThe default values for the HTTP header fields are:\n\n1.  Header User Name: X-Forwarded-User\n2.  Header Groups Name: X-Forwarded-Groups\n3.  Header Groups Delimiter: \\|\\#\\# In case no LDAP server is informed\n    the plugin will try to take the information from the HTTP header.\n    When no header groups information can be retrieved, in case the user\n    wants to do authentication only, and there is no LDAP server\n    configured, the user retrieved from the header will have only\n    Authenticated authority available.\n\n## Apache Configuration Example\n\n    \u003cVirtualHost *:80\u003e\n      ProxyPreserveHost On\n      ProxyRequests     Off\n      AllowEncodedSlashes NoDecode\n      Timeout 5400\n      ProxyTimeout 5400\n\n      \u003cProxy \"*\"\u003e\n        Order deny,allow\n        Allow from all\n        Authtype BASIC\n        AuthName \"Please sign in with your Apache user name and password\"\n        # file created with htpasswd\n        AuthUserFile /usr/local/apache2/conf/passwd\n        Require valid-user\n\n        # Remove these header before to set the right value after, it prevent the client from setting this header\n        RequestHeader unset \"X-Forwarded-User\"\n        RequestHeader unset \"X-Forwarded-Groups\"\n        RequestHeader unset \"X-Forwarded-Mail\"\n        RequestHeader unset \"X-Forwarded-DisplayName\"\n        # Remove the basic authorization header to avoid to use it in Jenkins\n        RequestHeader unset \"Authorization\"\n\n        # Adds the X-Forwarded-User header that indicates the current user name.\n        # this portion came from http://old.nabble.com/Forcing-a-proxied-host-to-generate-REMOTE_USER-td2911573.html#a2914465\n        RewriteEngine On\n\n        # User to use to login in Jenkins\n        RequestHeader set \"X-Forwarded-User\" \"%{RU}e\"\n        # Groups are separated by |\n        RequestHeader set \"X-Forwarded-Groups\" \"%{RU}e|users\"\n        # Inject mail \u0026 display name\n        RequestHeader set \"X-Forwarded-Mail\" %{AUTHENTICATE_MAIL}e\n        RequestHeader set \"X-Forwarded-DisplayName\" %{AUTHENTICATE_DISPLAYNAME}e\n\n        # strip the REALM of Kerberos Login\n        # RequestHeader edit X-Forwarded-User \"@REALM$\" \"\"\n\n        # see the Apache documentation on why this has to be lookahead\n        RewriteCond %{LA-U:REMOTE_USER} (.+)\n        # this actually doesn't rewrite anything. what we do here is to set RU to the match above\n        # \"NS\" prevents flooding the error log\n        RewriteRule .* - [E=RU:%1,NS]\n      \u003c/Proxy\u003e\n\n      # send you to the Jenkins instance\n      ProxyPass \"/jenkins\" \"http://jenkins.example.com:8282/jenkins\" nocanon\n      ProxyPassReverse \"/jenkins\" \"http://jenkins.example.com:8282/jenkins\"\n    \u003c/virtualhost\u003e\n\n## Notes\n\n-   Make sure that clients cannot bypass the reverse proxy. If they can\n    send requests directly to Jenkins, then a malicious client can send\n    in arbitrary header name with arbitrary value, thus compromising the\n    security of Jenkins\n-   Make sure you configure the reverse proxy to erase the header that\n    you use to pass the authenticated user name. This prevents malicious\n    client from setting the header name with arbitrary value, which\n    would ruin the security.\n-   If your authorisation need is simple (for example, every valid user\n    gets full access and everyone else gets no access), then you need\n    not use this plugin, as you can do both authentication and\n    authorisation in the reverse proxy.\n-   Hit \u003chttp://yourserver/whoAmI\u003e to see the actual HTTP headers your\n    Apache is sending to Jenkins. This is useful for trouble-shooting.\n\n## Jenkins says my reverse proxy setup is broken...\n\nSince Jenkins 1.572 this message can also appear if you don't access\nJenkins through a reverse proxy: Make sure the Jenkins URL configured in\nthe System Configuration matches the URL you're using to access Jenkins.\n\n## Symptoms\n\nAn error message is displayed in the \"Manage Jenkins\" page - \"It appears\nthat your reverse proxy set up is broken\"\n\n## Background\n\nFor a reverse proxy to work correctly, it needs to rewrite both the\nrequest and the response. Request rewriting involves receiving an\ninbound HTTP call and then making a forwarding request to Jenkins\n(sometimes with some HTTP headers modified, sometimes not). Failing to\nconfigure the request rewriting is easy to catch, because you just won't\nsee any pages at all.\n\nBut correct reverse proxying also involves one of two options, EITHER\n\n-   rewriting the response (for more information see [Hyperlinks in\n    HTML](https://wiki.jenkins.io/display/JENKINS/Hyperlinks+in+HTML)).\n    The primary place where this needs to happen is the \"Location\"\n    header in the response, which is used during redirects. Jenkins will\n    send back \"Location: \u003chttp://actual.server:8080/jenkins/foobar\u003e\" and\n    the reverse proxy needs to rewrite this to \"Location:\n    \u003chttp://nice.name/jenkins/foobar\u003e\". Unfortunately, failing to\n    configure this correctly is harder to catch; OR\n-   Setting the `X-Forwarded-Host` (and perhaps `X-Forwarded-Port`)\n    header on the forwarded request. Jenkins will parse those headers\n    and generate all the redirects and other links on the basis of those\n    headers. Depending on your reverse proxy it may be easier to\n    set `X-Forwarded-Host` and `X-Forwarded-Port` to the hostname and\n    port in the original `Host` header respectively or it may be easier\n    to just pass the original `Host` header through\n    as  `X-Forwarded-Host` and delete the `X-Forwarded-Port` header from\n    the request. You will also need to set the `X-Forwarded-Proto`\n    header if your reverse proxy is changing from `https` to `http` or\n    vice-versa\n\nSo Jenkins has a proactive monitoring to make sure this is configured\ncorrectly. It uses XmlHttpRequest to request a specific URL in Jenkins\n(via relative path, so this will always get through provided the request\nis properly rewritten), which will then redirect the user to another\npage in Jenkins (this only works correctly if you configured the\nresponse rewriting correctly), which then returns 200.\n\nThis error message indicates that this test is failing - and the most\nlikely cause is that the response rewriting is misconfigured. See\nthe **Server Configuration Guides** (below) for additional tips about\nconfiguring a reverse proxy. \n\nNote. The reverse proxy tests were improved in release 1.552 so users\nwith previously working proxy setups may start to receive proxy\nwarnings. \n\nBe sure to set the `X-Forwarded-Proto` header if your reverse proxy is\naccessed via HTTPS and then Jenkins itself is accessed via HTTP i.e.\nproxying HTTPS to HTTP.\n\nChanging the context path of Jenkins with a reverse proxy is fraught\nwith danger. There are lots of URLs that you need to rewrite correctly,\nand even if you get the ones in HTML files you may miss some in\njavascript, CSS or XML resources.\n\nThe recommendation is to ensure that Jenkins is running at the context\npath that your reverse proxy is serving Jenkins at. You will have the\nleast pain if you keep to this principle.\n\nWhile it is technically possible to use rewrite rules to change the\ncontext path, you should be aware that it would be a lot of work to find\nand fix everything in your rewrite rules and the reverse proxy will\nspend most of its time rewriting responses from Jenkins. Much easier to\nchange Jenkins to run at the context path your reverse proxy is\nexpecting, e.g. if your reverse proxy is forwarding requests at\n\u003chttps://manchu.example.org/foobar/\u003e to Jenkins then you could just use\n`java -jar jenkins.war --prefix /foobar` to start jenkins using\n`/foobar` as the context path\n\n \n\n## Further Diagnosis\n\nFor further diagnosis, try using cURL:\n\n``` syntaxhighlighter-pre\ncurl -iL -e http://your.reverse.proxy/jenkins/manage \\\n   http://your.reverse.proxy/jenkins/administrativeMonitor/hudson.diagnosis.ReverseProxySetupMonitor/test\n```\n\n(assuming your Jenkins is located at\n\u003chttp://your.reverse.proxy/jenkins/\u003e - and is open to anonymous read\naccess)\n\n## Server Configuration Guides\n\nWhile the pages talk primarily about Apache / NGinX / HAProxy / Squid,\nthey also have information that applies to other reverse proxies.\n\n-   [Running Jenkins behind\n    Apache](https://www.jenkins.io/doc/book/system-administration/reverse-proxy-configuration-apache)\n-   [Running Jenkins behind\n    Nginx](https://www.jenkins.io/doc/book/system-administration/reverse-proxy-configuration-nginx)\n-   [Running Jenkins behind\n    HAProxy](https://www.jenkins.io/doc/book/system-administration/reverse-proxy-configuration-haproxy)\n-   [Running Jenkins behind\n    Squid](https://www.jenkins.io/doc/book/system-administration/reverse-proxy-configuration-squid)\n-   [Running Jenkins behind\n    IIS](https://www.jenkins.io/doc/book/system-administration/reverse-proxy-configuration-iis)\n\nIf using Apache check that *nocanon* is set on *ProxyPass* and\nthat *AllowEncodedSlashes* is set as per the Apache link above.\n\n*AllowEncodedSlashes* is not inherited in Apache configs, so this\ndirective must be placed inside the *VirtualHost* definition.\n\n# Changelog\n\n(TODO switch to Release Drafter)\n\n### Version 1.7.2 (2022-03-02)\n\nRelease failed due to Javadoc issues.\n### Version 1.7.1 (2020-11-05)\n\nDocumentation in GH. Should be no functional change.\n### Version 1.7.0 (2020-11-05)\n\nCompatibility with [JEP-227](https://jenkins.io/jep/227). Should be no functional change.\n\n### Version 1.6.3 (2018, Feb 07)\n\n-   [![(error)](https://wiki.jenkins.io/s/en_GB/8100/5084f018d64a97dc638ca9a178856f851ea353ff/_/images/icons/emoticons/error.svg)](https://issues.jenkins-ci.org/browse/JENKINS-49238) [JENKINS-49274](https://issues.jenkins-ci.org/browse/JENKINS-49274) -\n    Run reverse-proxy servlet filter only after the default filter so\n    that the authentication gets right authorities (regression in 1.6.0)\n\n### Version 1.6.2 (2018 January 30)\n\n-   [![(error)](https://wiki.jenkins.io/s/en_GB/8100/5084f018d64a97dc638ca9a178856f851ea353ff/_/images/icons/emoticons/error.svg) JENKINS-49238](https://issues.jenkins-ci.org/browse/JENKINS-49238) -\n    Prevent ClassCastException when processing authorities\n    in DefaultReverseProxyAuthenticator (regression in 1.3?)\n\n### Version 1.6.1 (2018 January 29)\n\n-   [![(error)](https://wiki.jenkins.io/s/en_GB/8100/5084f018d64a97dc638ca9a178856f851ea353ff/_/images/icons/emoticons/error.svg) JENKINS-49236](https://issues.jenkins-ci.org/browse/JENKINS-49236) -\n    Prevent NullPointerException when null authContext is passed to the\n    AuthoritiesPopulator (regression in 1.6.0)\n\n### Version 1.6.0 (2018 January 29)\n\n-   ![(error)](https://wiki.jenkins.io/s/en_GB/8100/5084f018d64a97dc638ca9a178856f851ea353ff/_/images/icons/emoticons/error.svg) [JENKINS-22402](https://issues.jenkins-ci.org/browse/JENKINS-22402)/[JENKINS-48970](https://issues.jenkins-ci.org/browse/JENKINS-48970) -\n    Stop storing authentication context and caches on the disk\n    -   The change also fixes compatibility with JEP-200 in Jenkins\n        2.102+\n    -   More info: [Plugins affected by fix for\n        JEP-200](https://wiki.jenkins.io/display/JENKINS/Plugins+affected+by+fix+for+JEP-200)\n-   ![(error)](https://wiki.jenkins.io/s/en_GB/8100/5084f018d64a97dc638ca9a178856f851ea353ff/_/images/icons/emoticons/error.svg) [JENKINS-31612](https://issues.jenkins-ci.org/browse/JENKINS-31612) -\n    Fix handling of UI filters in the plugin so that it does not cause\n    integration issues when using other ones\n-   ![(error)](https://wiki.jenkins.io/s/en_GB/8100/5084f018d64a97dc638ca9a178856f851ea353ff/_/images/icons/emoticons/error.svg) [JENKINS-32909](https://issues.jenkins-ci.org/browse/JENKINS-32909) -\n    Prevent NullPointerException when using BASIC auth and when the user\n    does not exist \n-   ![(plus)](https://wiki.jenkins.io/s/en_GB/8100/5084f018d64a97dc638ca9a178856f851ea353ff/_/images/icons/emoticons/add.svg) [PR\n    \\#24](https://github.com/jenkinsci/reverse-proxy-auth-plugin/pull/24)\n    - Add configuration option for groupNameAttribute to use fields\n    other than CN as group lookup\n\n-   [![(plus)](https://wiki.jenkins.io/s/en_GB/8100/5084f018d64a97dc638ca9a178856f851ea353ff/_/images/icons/emoticons/add.svg) PR\n    \\#25](https://github.com/jenkinsci/reverse-proxy-auth-plugin/pull/25) -\n    Add support of custom log output redirect\n\n-   [![(plus)](https://wiki.jenkins.io/s/en_GB/8100/5084f018d64a97dc638ca9a178856f851ea353ff/_/images/icons/emoticons/add.svg) PR\n    \\#26](https://github.com/jenkinsci/reverse-proxy-auth-plugin/pull/26) -\n    Add support of custom login URL\n\n-   [![(info)](https://wiki.jenkins.io/s/en_GB/8100/5084f018d64a97dc638ca9a178856f851ea353ff/_/images/icons/emoticons/information.svg) PR\n    \\#33](https://github.com/jenkinsci/reverse-proxy-auth-plugin/pull/33) -\n    Plugin now requires Jenkins core 1.625.3 or above\n\n### Version 1.5 (2016 January 22)\n\n-   Adding LDAP connection retries\n-   Adding robust handling of authorisation headers for API tokens\n-   Adding email and name attributes to LDAP configuration\n-   Fixed NPE when forwarded user was not present\n\nFor more details, please checked the closed pull requests on\nGithub: \u003chttps://github.com/jenkinsci/reverse-proxy-auth-plugin/pulls\u003e\n\n### Version 1.4.0 (2014 May 27)\n\n-   Fixed JENKINS-22402 - The authorities of each user are not required\n    in the config.xml\n-   Adding group membership filter setting\n-   Adding Cache Update Interval so Jenkins can reload user's LDAP\n    groups on the fly, no need to restart Jenkins if users are added to\n    new groups.\n\n### Version 1.3.3 (2014 March 14)\n\n-   The user retrieved from the HTTP header is needed when the plugin\n    does not use the LDAP advanced options.\n\n### Version 1.3.2 (2014 March 5)\n\n-   Fixed concurrent problem with instance variable that was not being\n    used any more, although it could cause issues with users' rights\n    visibility.\n\n### Version 1.3.1 (2014 January 8)\n\n-   Fixed the load user by name method in the Reverse Proxy Security\n    Realm when LDAP is activated.\n\n### Version 1.3 (2014 January 7)\n\n-   Including Authorisation via both HTTP header groups field and LDAP\n    search.\n\n### Version 1.2 (2013 December 20)\n\n-   Including Authorisation via LDAP groups performing search based on\n    user name. \n\n### Version 1.0.1 (2013 May 7)\n\n-   list all unprotected root actions (URLs) in the configuration, so\n    the admin gets a hint which URLs should not be protected by the\n    reverse proxy (supported with Jenkins core 1.495+)\n\n### Version 1.0 (2011 March 26)\n\n-   Initial release\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Freverse-proxy-auth-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Freverse-proxy-auth-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Freverse-proxy-auth-plugin/lists"}