Dotyczy wersji 2026.1 i powyżej, autor: Tadeusz Baum, Lily Adamowicz
Wprowadzenie
Publikacja aplikacji .NET za reverse proxy jest jednym z częściej spotykanych scenariuszy wdrożeniowych. W takim modelu użytkownik końcowy komunikuje się wyłącznie z publicznym adresem HTTPS, natomiast ruch jest następnie przekazywany do warstwy aplikacyjnej działającej wewnątrz infrastruktury. Taki sposób publikacji pozwala oddzielić warstwę wejściową od samej aplikacji, ułatwia zarządzanie certyfikatami i ogranicza bezpośrednią ekspozycję serwera IIS do Internetu.
W opisywanym scenariuszu serwer reverse proxy przyjmuje ruch zewnętrzny, obsługuje połączenie HTTPS i przekazuje żądania do IIS, a następnie do aplikacji .NET czyli w tym wypadku WEBCON. Kluczowe jest przy tym nie tylko poprawne przekazanie ruchu, ale również zachowanie informacji o oryginalnym żądaniu klienta. Microsoft wskazuje wprost, że aplikacje działające za proxy lub load balancerem muszą otrzymać informacje o pierwotnym schemacie, hoście i adresie klienta, ponieważ w przeciwnym razie mogą niepoprawnie generować adresy URL, przekierowania lub dane wykorzystywane w logowaniu.
WAŻNE: Od wersji 2026 ustawienie ForceHttpsOnProxy nie jest wspierane. Jeżeli środowisko w wersji 2025 korzystało z tego mechanizmu, po aktualizacji należy skonfigurować reverse proxy oraz obsługę forwarded headers zgodnie z poniższą instrukcją. W przeciwnym razie aplikacja może rozpoznawać ruch jako HTTP zamiast HTTPS, co prowadzi m.in. do niepoprawnych przekierowań, błędów logowania zewnętrznego oraz generowania nieprawidłowych adresów URL.
Założenia
Artykuł opisuje referencyjny model publikacji, w którym ścieżka komunikacji wygląda następująco:
Klient → HTTPS → reverse proxy → HTTP/HTTPS → IIS → WEBCON
W takim układzie użytkownik korzysta z jednego publicznego adresu HTTPS, natomiast serwer IIS i sama aplikacja nie muszą być wystawione bezpośrednio do Internetu. To właśnie warstwa reverse proxy pełni rolę publicznego punktu wejścia. Podobny model publikacji i SSL offloadingu jest opisany w innym artykule.
Aktualizacja środowiska z wersji 2025 do 2026
W środowiskach, które wcześniej wykorzystywały ustawienie ForceHttpsOnProxy, sama aktualizacja platformy do wersji 2026 nie zapewnia zachowania dotychczasowego działania. Po aktualizacji należy upewnić się, że reverse proxy przekazuje nagłówki X-Forwarded-*, a aplikacja poprawnie je przetwarza.
Brak tej konfiguracji może powodować, że Portal będzie rozpoznawał żądanie jako HTTP zamiast HTTPS. W praktyce najczęściej objawia się to błędnymi przekierowaniami oraz problemami z logowaniem zewnętrznym, na przykład przez ADFS lub Microsoft Entra ID, gdy generowany adres redirect_uri nie odpowiada publicznemu adresowi HTTPS.
Jeżeli środowisko przed aktualizacją działało poprawnie z użyciem ForceHttpsOnProxy, po przejściu na wersję 2026 należy zweryfikować konfigurację reverse proxy, sposób przekazywania nagłówków oraz obsługę forwarded headers po stronie aplikacji.
Dlaczego konfiguracja reverse proxy jest istotna
Najczęstszy problem w tego typu środowiskach nie polega na samym przekazaniu żądania do backendu, ale na tym, że aplikacja zaczyna „widzieć” ruch wewnętrzny zamiast oryginalnego żądania użytkownika. Jeżeli publiczne połączenie HTTPS kończy się na reverse proxy, a dalej żądanie jest przekazywane do IIS po HTTP, aplikacja może błędnie uznać, że klient połączył się właśnie po HTTP. Taki stan zwykle prowadzi do problemów z przekierowaniami, błędnie generowanymi linkami i trudnościami z logowaniem zewnętrznym. Microsoft zaleca w takich przypadkach stosowanie nagłówków przekazywanych przez proxy oraz przetwarzanie ich po stronie aplikacji.
W praktyce oznacza to, że serwer reverse proxy powinien przekazać do aplikacji co najmniej informację o:
- publicznym hoście,
- oryginalnym schemacie żądania, czyli HTTP lub HTTPS,
- adresie źródłowym klienta.
To właśnie te dane są zwykle przesyłane przy użyciu nagłówków X-Forwarded-Host, X-Forwarded-Proto oraz X-Forwarded-For. Jednocześnie publiczny host nie powinien być akceptowany bezwarunkowo. Po stronie reverse proxy i aplikacji warto ograniczyć akceptowane nazwy hostów do znanych, poprawnych wartości, aby uniknąć problemów wynikających z przekazywania nieoczekiwanego nagłówka Host.
Przygotowanie środowiska
Przed rozpoczęciem konfiguracji warto ustalić docelową nazwę publiczną usługi, na przykład app.przyklad.pl, oraz sposób terminacji TLS. W prezentowanym modelu certyfikat jest instalowany na serwerze reverse proxy i to on obsługuje połączenie HTTPS od strony użytkownika. Po stronie infrastruktury należy również zaplanować reguły komunikacji sieciowej w taki sposób, aby ruch z Internetu trafiał wyłącznie do warstwy reverse proxy, a dostęp do IIS był ograniczony do sieci wewnętrznej lub wyłącznie do serwera reverse proxy.
Z perspektywy sieciowej oznacza to zwykle:
- udostępnienie portu 443 do serwera reverse proxy,
- ewentualne pozostawienie portu 80 wyłącznie na potrzeby przekierowania do HTTPS,
- dopuszczenie komunikacji z reverse proxy do IIS tylko po wewnętrznie ustalonym porcie,
- zachowanie informacji o adresie IP lub zakresie adresów serwera reverse proxy, które będą potrzebne przy konfiguracji zaufanych proxy po stronie aplikacji.
Konfiguracja zaufanych proxy
Aby aplikacja działająca za reverse proxy mogła poprawnie interpretować przekazywane nagłówki, serwer proxy musi być oznaczony jako zaufany.
Jeżeli reverse proxy działa na tym samym serwerze co aplikacja i przekazuje ruch na adres localhost, dodatkowa konfiguracja zwykle nie jest potrzebna. Adres localhost jest domyślnie traktowany jako zaufany.
Jeżeli reverse proxy działa na innym serwerze, jego adres IP lub zakres adresów należy dodać do listy zaufanych. Aplikacja udostępnia w tym celu konfigurację w węźle Security:ForwardedHeaders, którą można ustawić standardowo w plikach konfiguracyjnych albo za pomocą zmiennych środowiskowych.
Dostępne opcje:
- ForwardedHeaders – lista nagłówków, które mają być przekazywane; domyślnie: X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host,
- KnownProxies – lista adresów zaufanych serwerów proxy; domyślnie zawiera tylko localhost,
- KnownIpNetworks – lista zaufanych sieci; przydatna wtedy, gdy proxy ma dynamicznie przydzielany adres IP; domyślnie pusta.
Przykładowa konfiguracja:
"Security": {
"ForwardedHeaders": {
"ForwardedHeaders": [
"XForwardedFor",
"XForwardedProto",
"XForwardedHost"
],
"KnownProxies": [
],
"KnownIpNetworks": [
"10.0.0.0/8"
]
}
}
W szczególnych przypadkach możliwe jest również włączenie przekazywania nagłówków bez weryfikacji zaufanych proxy. Rozwiązanie to nie jest jednak zalecane przez Microsoft, ponieważ może prowadzić do powstania luki bezpieczeństwa. Aby je włączyć, należy ustawić zmienną środowiskową ASPNETCORE_FORWARDEDHEADERS_ENABLED na true.
Szczegółowe informacje dotyczące działania mechanizmu oraz konfiguracji dla konkretnych serwerów reverse proxy można znaleźć w dokumentacji Microsoft.
Testy po wdrożeniu
Po zakończeniu konfiguracji warto przeprowadzić kilka podstawowych testów, które potwierdzą poprawność całej ścieżki komunikacji.
Najpierw należy sprawdzić, czy wejście po HTTP jest przekierowywane do HTTPS i czy użytkownik zawsze trafia na publiczny adres z ważnym certyfikatem. Następnie warto zweryfikować, czy aplikacja otwiera się poprawnie pod publiczną nazwą i czy nie generuje błędnych linków absolutnych. W przypadku logowania zewnętrznego należy potwierdzić, że w parametrze redirect_uri widoczny jest adres https://…, a nie http://…. Ostatnim krokiem powinno być upewnienie się, że serwer IIS nie jest osiągalny bezpośrednio z Internetu i że ruch do backendu jest ograniczony do serwera Nginx lub sieci administracyjnej.
Najczęstsze problemy
Jeżeli aplikacja przekierowuje użytkownika na HTTP zamiast HTTPS, zwykle oznacza to brak poprawnej obsługi X-Forwarded-Proto albo brak zaufania do proxy. Jeżeli podczas logowania zewnętrznego pojawia się błąd typu redirect_uri mismatch, najczęstszą przyczyną jest niezgodność między publicznym adresem aplikacji a tym, co backend rozpoznaje jako scheme i host. Z kolei brak prawidłowego adresu IP klienta w logach wskazuje najczęściej na problem z przekazywaniem lub obsługą X-Forwarded-For. Te scenariusze są zgodne z typowymi problemami opisywanymi w dokumentacji ASP.NET Core dla aplikacji pracujących za proxy.