NAME
Mojolicious::Plugin::TrustedProxy - Mojolicious plugin to set the remote address, connection scheme, and more from trusted upstream proxies
VERSION
Version 0.04
SYNOPSIS
use Mojolicious::Lite;
plugin 'TrustedProxy' => {
ip_headers => ['x-forwarded-for', 'x-real-ip'],
scheme_headers => ['x-forwarded-proto', 'x-ssl'],
https_values => ['https', 'on', '1', 'true', 'enable', 'enabled'],
parse_rfc7239 => 1,
trusted_sources => ['127.0.0.0/8', '10.0.0.0/8'],
hide_headers => 0,
};
# Example of how you could verify expected functionality
get '/test' => sub {
my $c = shift;
$c->render(json => {
'tx.remote_address' => $c->tx->remote_address,
'tx.remote_proxy_address' => $c->tx->remote_proxy_address,
'req.url.base.scheme' => $c->req->url->base->scheme,
'req.url.base.host' => $c->req->url->base->host,
'is_trusted_source' => $c->is_trusted_source,
'is_trusted_source("1.1.1.1")' => $c->is_trusted_source('1.1.1.1'),
});
};
app->start;
DESCRIPTION
Mojolicious::Plugin::TrustedProxy modifies every Mojolicious request transaction to override connecting user agent values only when the request comes from trusted upstream sources. You can specify multiple request headers where trusted upstream sources define the real user agent IP address or the real connection scheme, or disable either, and can hide the headers from the rest of the application if needed.
This plugin provides much of the same functionality as setting MOJO_REVERSE_PROXY=1
, but with more granular control over what headers to use and what upstream sources can send them. This is especially useful if your Mojolicious app is directly exposed to the internet, or if it sits behind multiple upstream proxies. You should therefore ensure your application does not enable the default Mojolicious reverse proxy handler when using this plugin.
This plugin supports parsing RFC 7239 compliant Forwarded
headers, validates all IP addresses, and will automatically convert RFC-4291 IPv4-to-IPv6 mapped values (useful for when your Mojolicious listens on both IP versions). Please be aware that Forwarded
headers are only partially supported. More information is available in "BUGS".
Debug logging can be enabled by setting the MOJO_TRUSTEDPROXY_DEBUG
environment variable. This plugin also adds a remote_proxy_address
attribute into Mojo::Transaction
. If a remote IP address override header is matched from a trusted upstream proxy, then tx->remote_proxy_address
will be set to the IP address of that proxy.
CONFIG
ip_headers
List of zero, one, or many HTTP headers where the real user agent IP address will be defined by the trusted upstream sources. The first matched header is used. An empty value will disable this and keep the original scheme value. Default is ['x-forwarded-for', 'x-real-ip']
.
If a header is matched in the request, then tx->remote_address
is set to the value, and tx->remote_proxy_address
is set to the IP address of the upstream source.
scheme_headers
List of zero, one, or many HTTP headers where the real user agent connection scheme will be defined by the trusted upstream sources. The first matched header is used. An empty value will disable this and keep the original remote address value. Default is ['x-forwarded-proto', 'x-ssl']
.
This tests that the header value is "truthy" but does not contain the literal barewords http
, off
, or false
. If the header contains any other "truthy" value, then req->url->base->scheme
is set to https
.
https_values
List of values to consider as "truthy" when evaluating the headers in "scheme_headers". Default is ['https', 'on', '1', 'true', 'enable', 'enabled']
.
parse_rfc7239, parse_forwarded
Enable support for parsing RFC 7239 compliant Forwarded
HTTP headers. Default is 1
(enabled).
If a Forwarded
header is matched, the following actions occur with the first semicolon-delimited group of parameters found in the header value:
If the
for
parameter is found, thentx->remote_address
is set to the first matching value.If the
by
parameter is found, thentx->remote_proxy_address
is set to the first matching value, otherwise it is set to the IP address of the upstream source.If the
proto
parameter is found, thenreq->url->base->scheme
is set to the first matching value.If the
host
parameter is found, thenreq->url->base->host
is set to the first matching value.
Note! If enabled, the headers defined in "ip_headers" and "scheme_headers" will be overridden by any corresponding values found in the Forwarded
header.
trusted_sources
List of one or more IP addresses or CIDR classes that are trusted upstream sources. (Warning! An empty value will trust from all IPv4 sources!) Default is ['127.0.0.0/8', '10.0.0.0/8']
.
Supports all IP, CIDR, and range definition types from Net::CIDR::Lite.
hide_headers
Hide all headers defined in "ip_headers", "scheme_headers", and Forwarded
from the rest of the application when coming from trusted upstream sources. Default is 0
(disabled).
HELPERS
is_trusted_source
# From Controller context
sub get_page {
my $c = shift;
if ($c->is_trusted_source || $c->is_trusted_source('1.2.3.4')) {
...
}
}
Validate if an IP address is in the "trusted_sources" list. If no argument is provided, then this helper will first check tx->remote_proxy_address
then tx->remote_address
. Returns 1
if in the "trusted_sources" list, 0
if not, or undef
if the IP address is invalid.
CDN AND CLOUD SUPPORT
Mojolicious::Plugin::TrustedProxy is compatible with assumedly all third-party content delivery networks and cloud providers. Below is an incomplete list of some of the most well-known providers and the recommended config values to use for them.
Akamai
- ip_headers
-
Set "ip_headers" to
['true-client-ip']
(unless you set this to a different value) and enable True Client IP in the origin server behavior for your site property. Akamai also supports['x-forwarded-for']
, which is enabled by default in Mojolicious::Plugin::TrustedProxy. - scheme_headers
-
There is no known way to pass this by default with Akamai. It may be possible to pass a custom header via a combination of a Site Property variable and a custom behavior that injects an outgoing request header based on that variable, but this has not been tested or confirmed.
- trusted_sources
-
This is only possible if you have the Site Shield product from Akamai. If so, set "trusted_sources" to the complete list of IPs provided in your Site Shield map.
AWS
- ip_headers
-
The AWS Elastic Load Balancer uses
['x-forwarded-for']
, which is enabled by default in Mojolicious::Plugin::TrustedProxy. - scheme_headers
-
The AWS Elastic Load Balancer uses
['x-forwarded-proto']
, which is enabled by default in Mojolicious::Plugin::TrustedProxy. - trusted_sources
-
Depending on your setup, this could be one of the
172.x.x.x
IP addresses or ranges within your Virtual Private Cloud, the IP address(es) of your Elastic or Application Load Balancer, or could be the public IP ranges for your AWS region. Go to https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html for an updated list of AWS's IPv4 and IPv6 CIDR ranges.
Cloudflare
- ip_headers
-
Set "ip_headers" to
['cf-connecting-ip']
, or['true-client-ip']
if using an enterprise plan. Cloudflare also supports['x-forwarded-for']
, which is enabled by default in Mojolicious::Plugin::TrustedProxy. - scheme_headers
-
Cloudflare uses the
x-forwarded-proto
header, which is enabled by default in Mojolicious::Plugin::TrustedProxy. - trusted_sources
-
Go to https://www.cloudflare.com/ips/ for an updated list of Cloudflare's IPv4 and IPv6 CIDR ranges.
SECURITY
Caution should be taken that you set only the "CONFIG" values necessary for your application in a most-common-first order, and that your upstream proxies remove any headers you do not want passed through to your application.
For example, if you use Cloudflare and set "ip_headers" to ['x-real-ip', 'cf-connecting-ip']
and did not configure Cloudflare to remove x-real-ip
headers from requests, an attacker could use this trick your application into using whatever IP he or she defines due to being passed through your trusted proxy and the x-real-ip
header being the first to be evaluated.
AUTHOR
Kage <kage AT kage DOT wtf>
BUGS
Please report any bugs or feature requests on Github: https://github.com/Kage/Mojolicious-Plugin-TrustedProxy
- Hostnames not supported
-
Excluding the
host
parameter of RFC 7239, this plugin does not currently support hostnames or hostname resolution and there are no plans to implement this. If you have a use case that requires this, please feel free to submit a pull request. - HTTP 'Forwarded' only partially supported
-
Only partial support for RFC 7239 is currently implemented, but this should work with most common use cases. The full specification allows for complex structures and quoting that is difficult to implement safely. Full RFC support is expected to be implemented soon.
SEE ALSO
Mojolicious::Plugin::RemoteAddr, Mojolicious::Plugin::ClientIP::Pluggable, Mojolicious, Mojolicious::Guides, http://mojolicio.us.
COPYRIGHT
MIT License
Copyright (c) 2019 Kage
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.