Konfiguracja CORS (Cross-Origin Resource Sharing) dla strony w ServBay

We współczesnym rozwoju aplikacji webowych frontend (zwykle działający pod jedną domeną) często wymaga dostępu do backendowych API lub innych usług (które mogą działać pod inną domeną lub portem). Ze względów bezpieczeństwa domyślna polityka przeglądarek – polityka tego samego pochodzenia – blokuje takie żądania międzydomenowe. CORS (Cross-Origin Resource Sharing) to standardowy mechanizm, który pozwala serwerowi deklarować, które źródła (origin) mogą uzyskiwać dostęp do jego zasobów, umożliwiając w bezpieczny sposób komunikację międzydomenową.

W tym przewodniku dowiesz się, jak skonfigurować i włączyć CORS dla swojej strony lokalnie w środowisku ServBay przy użyciu graficznego interfejsu użytkownika.

Czym jest CORS?

CORS (Cross-Origin Resource Sharing) to mechanizm oparty na nagłówkach HTTP, umożliwiający serwerowi wskazanie, które źródła (domeny, protokoły lub porty) – inne niż własny – mają prawo ładować dane/zasoby. Gdy strona próbuje pobrać zasób z innego pochodzenia, przeglądarka traktuje to jako „żądanie międzydomenowe HTTP”. Polityka tego samego pochodzenia domyślnie blokuje takie zapytania. CORS jest formą komunikacji między serwerem i przeglądarką, pozwalającą ustalić, czy dane żądanie jest akceptowane.

Dlaczego programiści muszą skonfigurować CORS?

Jeśli tworzysz aplikację z podziałem na frontend i backend (np. frontend: app.servbay.demo, backend API: api.servbay.demo) albo Twój frontend korzysta z API zewnętrznych, przeglądarka zablokuje takie żądania z powodu polityki tego samego pochodzenia. Konfigurując CORS na serwerze, informujesz przeglądarkę, że żądania z wybranego źródła są dozwolone i mogą uzyskać dostęp do danych – dzięki temu unikasz błędów wynikających z blokady zabezpieczeń.

Kluczowe nagłówki HTTP dla CORS

Gdy serwer odpowiada na żądanie międzydomenowe, przesyła kilka nagłówków HTTP Access-Control-*. Przeglądarka analizuje ich wartości, by zdecydować, czy umożliwić dostęp do zasobu. W ServBay można skonfigurować poniższe podstawowe parametry CORS (odpowiadające tym nagłówkom):

1. Access-Control-Allow-Origin

   • Opis: Najważniejszy nagłówek CORS wskazujący, z jakich dokładnie domen (źródeł) dozwolony jest dostęp do zasobu.
   • Możliwe wartości:
     • *: pozwala na dostęp ze wszystkich domen. Ważne: mimo wygody, nie zaleca się stosowania tej opcji w środowisku produkcyjnym, bo umożliwia dostęp dowolnej stronie (ryzyko bezpieczeństwa).
     • https://servbay.demo: tylko ta konkretna domena może uzyskać dostęp.
     • https://servbay.demo https://api.servbay.demo: wiele domen – rozdzielone spacją.
   • Uwaga: Jeżeli żądanie międzydomenowe będzie zawierać ciasteczka lub dane uwierzytelniające (Access-Control-Allow-Credentials: true), wartość Access-Control-Allow-Origin nie może być ustawiona na * – musisz podać dokładny adres źródła.

2. Access-Control-Allow-Methods

   • Opis: Określa, jakie metody HTTP są dozwolone w żądaniu międzydomenowym (np. GET, POST, PUT, DELETE, OPTIONS itd.).
   • Możliwe wartości: Np. GET, POST, PUT, DELETE, OPTIONS – rozdzielone przecinkiem.
   • Uwaga: Dla tzw. „nieprostych żądań” (np. użycie metod PUT lub DELETE, nagłówków niestandardowych), przeglądarka wysyła najpierw zapytanie wstępne (OPTIONS, tzw. preflight). W odpowiedzi serwer musi uwzględnić Access-Control-Allow-Methods – stąd obecność metody OPTIONS w konfiguracji jest zwykle konieczna.

3. Access-Control-Allow-Headers

   • Opis: Określa, które nagłówki HTTP mogą być przesyłane w żądaniu międzydomenowym.
   • Możliwe wartości: Np. Content-Type, Authorization, X-Requested-With – rozdzielone przecinkiem.
   • Uwaga: Jeśli frontend używa nagłówków innych, niż domyślne „proste” (Accept, Accept-Language, Content-Language, Content-Type o wartościach: application/x-www-form-urlencoded, multipart/form-data, text/plain), przeglądarka wyśle preflight, a Ty musisz wyraźnie podać tu każdy dozwolony nagłówek.

4. Access-Control-Allow-Credentials

   • Opis: Wskazuje, czy żądania międzydomenowe mogą przekazywać dane uwierzytelniające, np. ciasteczka (Cookies), certyfikaty SSL klienta, dane HTTP Auth.
   • Możliwe wartości: true lub false
   • Uwaga: Jeśli ustawisz wartość na true, jak wcześniej wspomniano, nie możesz ustawić Access-Control-Allow-Origin na *. Po stronie klienta (kod JS w przeglądarce) musisz ustawić odpowiednią opcję: xhr.withCredentials = true lub fetch(url, { credentials: 'include' }).

Włączanie i konfiguracja CORS w ServBay

ServBay oferuje wygodny graficzny interfejs, dzięki któremu możesz osobno skonfigurować ustawienia CORS dla każdej strony. Poniżej znajdziesz instrukcję krok po kroku:

1. Uruchom ServBay i przejdź do listy stron: Włącz aplikację ServBay. W głównym oknie po lewej stronie wybierz zakładkę „Strony”. Zobaczysz listę wszystkich lokalnych stron skonfigurowanych w ServBay.

2. Wybierz stronę do konfiguracji CORS: Wybierz stronę, dla której chcesz włączyć i ustawić CORS. Kliknij jej nazwę, aby przejść do szczegółowych ustawień.

3. Znajdź i włącz ustawienia CORS: W konfiguracji strony przewiń do sekcji „CORS”. Domyślnie CORS jest wyłączony. Przełącz widoczny obok przełącznik ze stanu „wyłączone” na „włączone”. Po aktywacji pola do konfiguracji staną się edytowalne.

4. Ustaw Access-Control-Allow-Origin: W oknie „Access-Control-Allow-Origin” podaj adres (lub adresy) źródeł, które mają mieć dostęp do danych tej strony. Kilka źródeł oddziel spacją. Przykład: https://frontend.servbay.demo https://anotherapp.servbay.demo. W środowisku produkcyjnym unikaj znaku *.

5. Ustaw Access-Control-Allow-Methods: W polu „Access-Control-Allow-Methods” wpisz listę akceptowanych metod HTTP – rozdzielonych przecinkiem, np.: GET, POST, PUT, DELETE, OPTIONS. Pamiętaj, by uwzględnić potrzebne metody i zwykle OPTIONS do obsługi preflight.

6. Ustaw Access-Control-Allow-Headers: W polu „Access-Control-Allow-Headers” wpisz akceptowane niestandardowe nagłówki HTTP, rozdzielone przecinkiem, np.: Content-Type, Authorization, X-Custom-Header. Podaj tylko te nagłówki, których rzeczywiście wymaga Twoja aplikacja.

7. Ustawienie Access-Control-Allow-Credentials (opcjonalnie): Jeśli Twój frontend ma przesyłać ciasteczka lub dane uwierzytelniające HTTP, przełącz przełącznik „Allow-Credentials” w stan „włączone”. Pamiętaj: w tym wypadku w kroku 4 nie możesz użyć *!

8. Zapisz ustawienia: Po skonfigurowaniu wszystkich parametrów CORS kliknij przycisk "Zapisz" w prawym dolnym rogu okna. ServBay automatycznie zaktualizuje konfigurację serwera WWW (Caddy lub Nginx); nie musisz ręcznie restartować usług.

Przykład konfiguracji

Poniżej znajduje się przykładowy zrzut ekranu ustawień CORS dla witryny „ServBay Demo Website” w ServBay:

Zgodnie z powyższą konfiguracją:

• Access-Control-Allow-Origin: https://frontend.servbay.demo https://api.servbay.demo
• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization
• Allow-Credentials: włączone (true)

Oznacza to, że żądania z https://frontend.servbay.demo i https://api.servbay.demo mogą uzyskać dostęp do zasobów „ServBay Demo Website” przy użyciu metod GET, POST, PUT, DELETE, OPTIONS, z nagłówkami Content-Type i Authorization oraz z przesyłaniem ciasteczek i danych uwierzytelniających.

Wskazówki i najlepsze praktyki

• Bezpieczeństwo przede wszystkim: W środowisku testowym możesz ustawić Access-Control-Allow-Origin: *, ale po wdrożeniu strony na produkcji zawsze zawęź dozwolony origin tylko do rzeczywiście wykorzystywanych.
• Preflight (żądanie wstępne): Zrozumienie mechaniki żądań preflight (OPTIONS) jest kluczowe podczas debugowania CORS. Upewnij się, że serwer konfigurowany przez ServBay poprawnie na nie odpowiada.
• Pamięć podręczna przeglądarki: Przeglądarki mogą cachować politykę CORS. Jeśli po zmianie ustawień w ServBay nadal masz problemy, opróżnij cache przeglądarki lub przetestuj w trybie incognito.
• CORS po stronie aplikacji: Niektóre frameworki lub biblioteki webowe (np. Laravel, Express.js, Spring Boot) umożliwiają konfigurację CORS w kodzie aplikacji. Ustawienia z ServBay działają na poziomie serwera WWW (Caddy/Nginx), zwykle mają pierwszeństwo przed ustawieniami aplikacji. W złożonych scenariuszach warto sprawdzić oba poziomy regulacji CORS.
• Narzędzia do debugowania: Korzystaj z narzędzi developerskich przeglądarki (zwykle F12 → zakładka „Sieć/Network”), by podglądać nagłówki żądań i odpowiedzi. Ułatwi to wykrycie, czy CORS jest właściwie skonfigurowany i zdiagnozowanie powodów ewentualnych błędów.

Najczęstsze pytania (FAQ)

P: Skonfigurowałem CORS zgodnie z instrukcją, a mimo to żądania międzydomenowe nadal nie działają. Dlaczego?

Odp: Sprawdź następujące kwestie:

1. Konsola przeglądarki i zakładka „Sieć”: Przeglądarki wyświetlają błędy CORS w konsoli i pokazują pełną zawartość nagłówków w zakładce „Sieć/Network”. Sprawdź, czy odpowiedź zawiera poprawne nagłówki Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers i czy ich wartości zgadzają się z konfiguracją klienta.
2. Dokładność adresu źródła: Sprawdź, czy adres (protokół, domena, port) w polu Access-Control-Allow-Origin zgadza się dokładnie z tym, z którego pochodzi żądanie.
3. Metody i nagłówki: Upewnij się, że Access-Control-Allow-Methods zawiera metodę żądania HTTP, a Access-Control-Allow-Headers wymienia wszystkie niestandardowe nagłówki występujące w żądaniu.
4. Przesyłanie danych uwierzytelniających: Jeśli używasz ciasteczek lub innych danych uwierzytelniających, sprawdź, czy w ServBay jest włączony Allow-Credentials i czy Access-Control-Allow-Origin nie jest *. Po stronie klienta pamiętaj o ustawieniu flagi wysyłania danych uwierzytelniających (np. withCredentials = true).
5. Preflight: W przypadku nieprostych żądań zatwierdź, czy przeglądarka wysyła zapytanie OPTIONS i czy serwer odpowiada wymaganymi nagłówkami.
6. Zapisz konfigurację: Upewnij się, że po zmianie ustawień w ServBay kliknąłeś przycisk „Zapisz”.

P: Czy mogę ustawić globalną politykę CORS dla wszystkich stron?

Odp: Konfiguracja CORS w ServBay jest niezależna dla każdej strony – taki model zapewnia elastyczność i bezpieczeństwo. Obecnie interfejs ServBay nie oferuje globalnych ustawień CORS. Jeśli kilka stron wymaga podobnej polityki, należy skonfigurować każdą z nich osobno.

P: Jak ServBay realizuje ustawienia CORS?

Odp: ServBay korzysta z serwerów WWW Caddy lub Nginx. Konfiguracja CORS w interfejsie ServBay jest automatycznie tłumaczona na instrukcje w pliku Caddyfile albo w konfiguracji Nginx. Zarządzaniem tymi plikami i przeładowaniem serwera zajmuje się ServBay, nie musisz edytować ich ręcznie.

Podsumowanie

Dzięki przejrzystemu interfejsowi użytkownika w ServBay łatwo włączysz i poprawnie skonfigurujesz CORS dla stron w lokalnym środowisku developerskim, eliminując problemy z żądaniami międzydomenowymi. Poprawne rozumienie i ustawienie nagłówków Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Allow-Credentials to podstawa bezpiecznej i sprawnej komunikacji frontendu z backendem. Stosując się do powyższego przewodnika oraz zaleceń z sekcji „Najlepsze praktyki”, zwiększysz efektywność i bezpieczeństwo swojej pracy.