yiisoft / proxy-middleware
Yii Proxy Middleware
Fund package maintenance!
Opencollective
yiisoft
Requires
- php: ^8.0
- ext-filter: *
- psr/http-message: ^1.0|^2.0
- psr/http-server-handler: ^1.0
- psr/http-server-middleware: ^1.0
- yiisoft/http: ^1.2
- yiisoft/network-utilities: ^1.1
Requires (Dev)
- httpsoft/http-message: ^1.0
- maglnet/composer-require-checker: ^4.4
- phpunit/phpunit: ^9.5
- rector/rector: ^0.16.0
- roave/infection-static-analysis-plugin: ^1.16
- spatie/phpunit-watcher: ^1.23
- vimeo/psalm: ^4.30|^5.24
- yiisoft/test-support: ^3.0
This package is auto-updated.
Last update: 2024-11-06 12:36:03 UTC
README
Yii Proxy Middleware
The package provides proxy related middleware classes that implement PSR-15:
For other miscellaneous middleware, there is a separate package - Yii Middleware.
For more information on how to use middleware in the Yii Framework, see the Yii middleware guide.
Requirements
- PHP 8.0 or higher.
Installation
The package could be installed with Composer:
composer require yiisoft/proxy-middleware
General usage
TrustedHeaderProtocolResolver
Trusted header protocol resolver sets a server request protocol based on special header you trust
such as X-Forwarded-Proto
.
You can use it if your server is behind a trusted load balancer or a proxy that's always setting the special header itself discarding any header values provided by user.
use Yiisoft\Yii\Middleware\TrustedHeaderProtocolResolver; /** * @var Psr\Http\Message\ServerRequestInterface $request * @var Psr\Http\Server\RequestHandlerInterface $handler */ $middleware = new TrustedHeaderProtocolResolver(); $middleware = $middleware->withAddedProtocolHeader('x-forwarded-proto', [ 'http' => ['http'], 'https' => ['https', 'on'], ]); // Disable earlier settings: $middleware = $middleware->withoutProtocolHeader('x-forwarded-proto'); $response = $middleware->process($request, $handler);
TrustedHostsNetworkResolver
Scans the entire connection chain and resolves the data from forwarded headers taking into account trusted IPs. Additionally, all items' structure is thoroughly validated because headers' data can't be trusted. The following data is resolved:
- IP.
- Protocol
- Host.
- Port.
- IP identifier - unknown or
obfuscated. Used with
Forwarded
RFC header.
The typical use case is having an application behind a load balancer.
Trusted IPs
A list of trusted IPs from connection chain.
Proxies' IPs including the one in $_SERVER['REMOTE_ADDR']
must be specified here. For example, for
$_SERVER['REMOTE_ADDR']
with value 18.18.18.18
and 2 other proxies - 2.2.2.2
and 8.8.8.8
, the configuration will
be:
use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; /** @var TrustedHostsNetworkResolver $middleware */ $middleware = $middleware->withTrustedIps([['8.8.8.8', '2.2.2.2', '18.18.18.18']]);
The order of IPs is not important.
Forwarded header groups
Header groups to parse the data from. By including headers in this list, they are trusted automatically.
The default is:
use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; /** @var TrustedHostsNetworkResolver $middleware */ $middleware = $middleware->withForwardedHeaderGroups([ TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC, TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_X_PREFIX, ]);
which is an alternative/shorter way of writing this:
use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; /** @var TrustedHostsNetworkResolver $middleware */ $middleware = $middleware->withForwardedHeaderGroups([ 'forwarded', [ 'ip' => 'x-forwarded-for', 'protocol' => 'x-forwarded-proto', 'host' => 'x-forwarded-host', 'port' => 'x-forwarded-port', ], ]);
The accepted values are:
TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC
string constant. Parse all data from singleForwarded
header according to RFC 7239.- Array. Parse data from separate forwarded headers with "X" prefix. Unlike with RFC variation, each header stores only
one data unit (for example, IP). Headers with "X" prefix are quite common despite being non-standard:
- X-Forwarded-For - IP.
- X-Forwarded-Proto - protocol.
- X-Forwarded-Host - host.
X-Forwarded-Port
- port.
The header groups are processed in the order they are defined. If the header containing IP is present and is non-empty, this group will be selected and further ones will be ignored.
You can add support for custom headers and/or change priority:
use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; /** @var TrustedHostsNetworkResolver $middleware */ $middleware = $middleware->withForwardedHeaderGroups([ [ 'ip' => 'y-forwarded-for', 'protocol' => 'y-forwarded-proto', 'host' => 'y-forwarded-host', 'port' => 'y-forwarded-port', ], TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_X_PREFIX, TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC, ]);
For protocol, it's also possible to resolve non-standard values via mapping:
use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; /** @var TrustedHostsNetworkResolver $middleware */ $middleware = $middleware->withForwardedHeaderGroups([ TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC, [ 'ip' => 'y-forwarded-for', 'protocol' => [ 'front-end-https', ['on' => 'https'], ], 'host' => 'y-forwarded-host', 'port' => 'y-forwarded-port', ], TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_X_PREFIX, ]);
or via callable:
use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; /** @var TrustedHostsNetworkResolver $middleware */ $middleware = $middleware->withForwardedHeaderGroups([ TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC, [ 'ip' => 'y-forwarded-for', 'protocol' => [ 'front-end-https', static fn (string $protocol): ?string => $protocol === 'On' ? 'https': 'http',, ], 'host' => 'y-forwarded-host', 'port' => 'y-forwarded-port', ], TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_X_PREFIX, ]);
It's also a good idea to limit default header groups to the only guaranteed sources of data:
use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; /** @var TrustedHostsNetworkResolver $middleware */ $middleware = $middleware->withForwardedHeaderGroups([ TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC, ]);
Typical forwarded headers
List of headers that are considered related to forwarding.
The default is:
use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; /** @var TrustedHostsNetworkResolver $middleware */ $middleware = $middleware->withTypicalForwardedHeaders([ // RFC 'forwarded', // "X" prefix 'x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-forwarded-port', // Microsoft 'front-end-https', ]);
The headers that are present in this list but missing in a matching forwarded header group will be deleted from request because they are potentially not secure and likely were not passed by a proxy server.
For example, with default forwarded header groups' setup used as well:
use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; /** @var TrustedHostsNetworkResolver $middleware */ $middleware = $middleware->withForwardedHeaderGroups([ TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC, TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_X_PREFIX, ]);
and with the following request headers passed:
[ 'Forwarded' => [ 'for="9.9.9.9:8013";proto=http;host=example13.com', 'for="8.8.8.8:8012";proto=http;host=example12.com', 'for="2.2.2.2:8011";proto=http;host=example11.com', ], 'X-Forwarded-For' => 'not-secure', 'X-Forwarded-Host' => 'not-secure', 'X-Forwarded-Proto' => 'not-secure', 'X-Forwarded-Port' => 'not-secure', 'Front-End-Https' => 'not-secure', 'Non-Forwarded' => 'not-typical', ];
middleware will remove these headers from request:
x-forwarded-for
.x-forwarded-host
.x-forwarded-proto
.x-forwarded-port
.front-end-https
.
because RFC group is matching and the rest can't be trusted. The headers that are not declared as typical forwarded
headers will be left as is (Non-Forwarded
in the example above).
Accessing resolved data
Resolved IP is saved to a special request's attribute:
use Psr\Http\Message\ServerRequestInterface; /** @var ServerRequestInterface $request */ $ip = $request->getAttribute(TrustedHostsNetworkResolver::ATTRIBUTE_REQUEST_CLIENT_IP);
There is an additional attribute allowing to retrieve all previous validated and trusted connection chain items. It needs explicit configuration:
use Psr\Http\Message\ServerRequestInterface; use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; /** @var TrustedHostsNetworkResolver $middleware */ $middleware = $middleware->withConnectionChainItemsAttribute('connectionChainItems'); // ... /** @var ServerRequestInterface $request */ $connectionChainItems = $request->getAttribute('connectionChainItems');
An example of contents:
[ [ 'ip' => '18.18.18.18', 'protocol' => null, 'host' => null, 'port' => null, 'ipIdentifier' => null, ], [ 'ip' => '2.2.2.2', 'protocol' => 'http', 'host' => 'example1.com', 'port' => null, 'ipIdentifier' => '_obfuscated1', ] ],
Reverse-obfuscating IP identifier
You may extend middleware class and provide reverse-obfuscating logic for obfuscated IP identifiers:
use Yiisoft\ProxyMiddleware\TrustedHostsNetworkResolver; class MyTrustedHostsNetworkResolver extends TrustedHostsNetworkResolver { protected function reverseObfuscateIpIdentifier( string $ipIdentifier, array $validatedConnectionChainItems, array $remainingConnectionChainItems, RequestInterface $request, ): ?array { return match ($ipIdentifier) { '_obfuscated1' => ['2.2.2.2', null], // Without port '_obfuscated2' => ['5.5.5.5', '8082'], // With port default => null, // Unable to resolve (default) }; } }
Documentation
If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.
License
The Yii Proxy Middleware is free software. It is released under the terms of the BSD License.
Please see LICENSE
for more information.
Maintained by Yii Software.