view release on metacpan or  search on metacpan

lib/Mojolicious/Plugin/TrustedProxy.pm  view on Meta::CPAN

1;
__END__

=pod

=head1 NAME

Mojolicious::Plugin::TrustedProxy - Mojolicious plugin to set the remote
address, connection scheme, and more from trusted upstream proxies

=head1 VERSION

Version 0.04

=head1 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;

=head1 DESCRIPTION

L<Mojolicious::Plugin::TrustedProxy> modifies every L<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
C<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 L<RFC 7239|http://tools.ietf.org/html/rfc7239>
compliant C<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 C<Forwarded>
headers are only partially supported. More information is available in L</BUGS>.

Debug logging can be enabled by setting the C<MOJO_TRUSTEDPROXY_DEBUG>
environment variable. This plugin also adds a C<remote_proxy_address>
attribute into C<Mojo::Transaction>. If a remote IP address override header is
matched from a trusted upstream proxy, then C<< tx->remote_proxy_address >>
will be set to the IP address of that proxy.

=head1 CONFIG

=head2 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 C<['x-forwarded-for', 'x-real-ip']>.

If a header is matched in the request, then C<< tx->remote_address >> is set to
the value, and C<< tx->remote_proxy_address >> is set to the IP address of the
upstream source.

=head2 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 C<['x-forwarded-proto', 'x-ssl']>.

This tests that the header value is "truthy" but does not contain the literal
barewords C<http>, C<off>, or C<false>. If the header contains any other
"truthy" value, then C<< req->url->base->scheme >> is set to C<https>.

=head2 https_values

List of values to consider as "truthy" when evaluating the headers in
L</scheme_headers>. Default is
C<['https', 'on', '1', 'true', 'enable', 'enabled']>.

=head2 parse_rfc7239, parse_forwarded

Enable support for parsing L<RFC 7239|http://tools.ietf.org/html/rfc7239>
compliant C<Forwarded> HTTP headers. Default is C<1> (enabled).

If a C<Forwarded> header is matched, the following actions occur with the first
semicolon-delimited group of parameters found in the header value:

=over

=item

If the C<for> parameter is found, then C<< tx->remote_address >> is set to the
first matching value.

=item

If the C<by> parameter is found, then C<< tx->remote_proxy_address >> is set
to the first matching value, otherwise it is set to the IP address of the
upstream source.