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:
- mkcert-v1.4.3-windows-amd64.exe -install
- mkcert-v1.4.3-windows-amd64.exe <nazwa_pliku_certyfikatu> <host> localhost 127.0.0.1 ::<numer portu>
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:
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ę. 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). Wybrany port jest już zajęty przez inną aplikację. Należy sprawdzić które porty na serwerze są wolne i wpisać w url wolny port. 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. 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: Szyfrowanie komunikacji serwer – API
Najczęściej pojawiające się problemy
Dodatkowe informacje
Czy ten artykuł był pomocny?