Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yiisoft/proxy-middleware
Middleware to set request parameters based on headers provided by proxy
https://github.com/yiisoft/proxy-middleware
forwarded load-balancer middleware proxy psr-15 yii3
Last synced: 4 months ago
JSON representation
Middleware to set request parameters based on headers provided by proxy
- Host: GitHub
- URL: https://github.com/yiisoft/proxy-middleware
- Owner: yiisoft
- License: bsd-3-clause
- Created: 2023-05-14T12:30:17.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-04-03T20:34:07.000Z (10 months ago)
- Last Synced: 2024-04-13T21:57:20.138Z (10 months ago)
- Topics: forwarded, load-balancer, middleware, proxy, psr-15, yii3
- Language: PHP
- Homepage: https://www.yiiframework.com
- Size: 85 KB
- Stars: 7
- Watchers: 15
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
Yii Proxy Middleware
[](https://packagist.org/packages/yiisoft/proxy-middleware)
[](https://packagist.org/packages/yiisoft/proxy-middleware)
[](https://github.com/yiisoft/proxy-middleware/actions/workflows/build.yml)
[](https://codecov.io/gh/yiisoft/proxy-middleware)
[](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/proxy-middleware/master)
[](https://github.com/yiisoft/proxy-middleware/actions?query=workflow%3A%22static+analysis%22)
[](https://shepherd.dev/github/yiisoft/proxy-middleware)
[](https://shepherd.dev/github/yiisoft/proxy-middleware)
The package provides proxy related middleware classes that implement
[PSR-15](https://www.php-fig.org/psr/psr-15/#12-middleware):
- [`TrustedHeaderProtocolResolver`](#trustedheaderprotocolresolver).
- [`TrustedHostsNetworkResolver`](#trustedhostsnetworkresolver).
For other miscellaneous middleware, there is a separate package -
[Yii Middleware](https://github.com/yiisoft/yii-middleware).
For more information on how to use middleware in the [Yii Framework](https://www.yiiframework.com/), see the
[Yii middleware guide](https://github.com/yiisoft/docs/blob/master/guide/en/structure/middleware.md).
## Requirements
- PHP 8.0 or higher.
## Installation
The package could be installed with [Composer](https://getcomposer.org):
```shell
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.
```php
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](https://datatracker.ietf.org/doc/html/rfc7239#section-6.2) or
[obfuscated](https://datatracker.ietf.org/doc/html/rfc7239#section-6.3). 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:
```php
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:
```php
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:
```php
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 single `Forwarded`
header according to [RFC 7239](https://datatracker.ietf.org/doc/html/rfc7239).
- 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) - IP.
- [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) - protocol.
- [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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:
```php
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:
```php
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:
```php
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:
```php
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:
```php
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:
```php
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:
```php
[
'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:
```php
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:
```php
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:
```php
[
[
'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](https://datatracker.ietf.org/doc/html/rfc7239#section-6.3) IP identifiers:
```php
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
- [Internals](docs/internals.md)
If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
## License
The Yii Proxy Middleware is free software. It is released under the terms of the BSD License.
Please see [`LICENSE`](./LICENSE.md) for more information.
Maintained by [Yii Software](https://www.yiiframework.com/).
## Support the project
[](https://opencollective.com/yiisoft)
## Follow updates
[](https://www.yiiframework.com/)
[](https://twitter.com/yiiframework)
[](https://t.me/yii3en)
[](https://www.facebook.com/groups/yiitalk)
[](https://yiiframework.com/go/slack)