view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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
    <http://tools.ietf.org/html/rfc7239> 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 <http://tools.ietf.org/html/rfc7239>
    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, then "tx->remote_address" is set to
        the first matching value.

    *   If the "by" parameter is found, then "tx->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, then "req->url->base->scheme" is
        set to the first matching value.

    *   If the "host" parameter is found, then "req->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.