Wstęp

Dokument opisuje konfigurację HTTPS dla aplikacji Comarch APS.

Generowanie certyfikatu

Należy pobrać mkcert (https://github.com/FiloSottile/mkcert/releases/download/v1.4.3/mkcert-v1.4.3-windows-amd64.exe). W folderze, w którym znajduje się mkcert należy wykonać następujące polecenia:

Jako <host> można użyć również adresu IP zamiast nazwy domenowej serwera.

Certyfikat wraz z kluczem należy przenieść do folderu instalacyjnego \Comarch APS <numer_wersji>\nginx\SSL. Jeśli końcowy folder nie istnieje należy go utworzyć.

Szyfrowanie komunikacji przeglądarka – serwer

W lokalizacji \Comarch APS <numer_wersji>\nginx\SSL powinien znajdować się certyfikat wraz z kluczem. Jeśli końcowy folder nie istnieje należy go utworzyć.

W pliku \Comarch APS <numer_wersji>\nginx\conf\app.conf, w sekcji server należy dodać wpis:

listen <nr_portu> ssl;

ssl_certificate ~/../ssl/<nazwa_certyfikatu>;

ssl_certificate_key ~/../ssl/<nazwa_klucza_certyfikatu>;

server_name <nazwa_serwera>;

Poniżej przykładowa konfiguracja:

Szyfrowanie komunikacji serwer – API

Przed modyfikacją plików konfiguracyjnych API należy zatrzymać ich działanie.

W folderze instalacyjnym Comarch APS należy przejść do folderu API. Powinno tam się znajdować 6 folderów. Interesują nas 4 z nich:

Dla każdego z nich należy wykonać następujące czynności:

Po wejściu do danego folderu należy odnaleźć plik appsettings.json. Po otwarciu w dowolnym edytorze tekstu należy wyszukać w nim sekcję Kestrel. Powinna wyglądać w następujący sposób:

„Kestrel”: {

„Endpoints”: {

„Http”: {

„Url”: „http://*:0”

}

}

},

Należy ją zmodyfikować tak, aby wyglądała następująco:

„Kestrel”: {

„Endpoints”: {

„Https”: {

„Url”: „https://*:0”,

„Certificate”: {

„Path”: „<ścieżka_do_certyfikatu>”,

„KeyPath”: „<ścieżka_do_klucza_certyfikatu>”

}

}

}

},

Aby uzyskać zamierzony efekt należy:

– zmodyfikować nagłówek sekcji „Http” na „Https”

– podmienić adres aplikacji przypisany do klucza „Url”. Tutaj należy zmodyfikować „http” na „https”

– dodać nową sekcję z nagłówkiem „Certificate”. Powinna ona zawierać dwa klucze – „Path”, do którego przypisujemy ścieżkę do certyfikatu oraz „KeyPath” do którego przypisujemy ścieżkę do klucza certyfikatu. Należy użyć tego samego certyfikatu, który został wykorzystany przy szyfrowaniu komunikacji pomiędzy przeglądarką i serwerem. Uzupełniając ścieżkę należy stosować podwójne znaki „/” oddzielające fragmenty ścieżki. Jeśli certyfikat i klucz znajdują się w folderze nginx/SSL, ścieżka będzie wyglądać następująco:

.//..//..//nginx//SSL//<nazwa_certyfikatu>

.//..//..//nginx//SSL//<nazwa_klucza_certyfikatu>

Poniżej przykładowa sekcja Kestrel w pliku konfiguracyjnym:

Po wykonaniu tych czynności we wszystkich folderach wymienionych na początku tego punktu wracamy do pliku konfiguracyjnego serwera nginx (\Comarch APS <wersja_produktu>\nginx\conf\app.conf).

Wyszukujemy w nim wszystkie wystąpienia klucza o nazwie ‘proxy_pass’ i zamieniamy w url „http” na „https”.

Po wykonaniu powyższych czynności uruchamiamy ponownie serwisy oraz restartujemy serwer nginx/przeładowujemy jego konfigurację.

Najczęściej pojawiające się problemy

W przypadku jakichkolwiek problemów z ponownym uruchomieniem serwisów lub z uruchomieniem Comarch APS w pierwszej kolejności należy sprawdzić logi znajdujące się folderze (\Comarch APS <wersja_produktu>\api\logs). Jeśli wskazówki z logów okażą się niewystarczające do zidentyfikowania problemu, w dalszej kolejności należy sprawdzić zawartość Podglądu zdarzeń:

1) Jeśli po zmianie konfiguracji serwisy nie chcą się ponownie uruchomić, należy przejść do Podglądu Zdarzeń (wyszukać w wyszukiwarce Windows Podgląd Zdarzeń), rozwinąć sekcję Dzienniki systemu Windows i otworzyć zakładkę [Aplikacja]. W liście na środku ekranu należy znaleźć wpis dotyczący serwisu. Powinien wyglądać w następujący sposób:

Następnie należy sprawdzić linijkę zaczynającą się od Exception Info:

Wpisany URL w konfiguracji nie jest poprawny. Należy upewnić się, że wpisane adresy są poprawne, zaczynają się od http lub https (odpowiednio do sekcji).

W pliku konfiguracyjnym znajdują się błędy. Przyczyną mogą być brakujące lub nadmiarowe nawiasy/przecinki/średniki.

2) W przypadku gdy po zmianach w pliku konfiguracyjnym serwer nginx nie uruchamia się, a w poglądzie zdarzeń znajduje się:

lub brak jest jakiegokolwiek błędu, to przyczyną może być literówka lub nadmiarowy/brakujący znak w pliku app.conf.

3) W przypadku gdy podczas logowania do Comarch APS wprowadzimy poprawne dane, a zostanie wyświetlony komunikat:

przyczyną może być brak podmiany „http” na „https” w kluczu ‘proxy_pass’ w pliku app.conf.

Dodatkowe informacje

Więcej na temat konfigurowania ustawień SSL dla Nginx można poczytać w dokumentacji:

http://nginx.org/en/docs/http/configuring_https_servers.html

Więcej na temat konfiguracji punktów końcowych dla serwera Kestrel można poczytać w dokumentacji:

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel/endpoints?view=aspnetcore-6.0