Pripojenie a zabezpečenie

Integrujem cez

Spôsob pripojenia k eKase závisí od toho, kde beží váš softvér. Najjednoduchšie je to na tom istom zariadení a v lokálnej sieti predajne. Z internetu sa k eKase dostanete len cez zabezpečené spojenie.

Článok sa týka HTTP API. .NET knižnica beží priamo vo vašej aplikácii a sieťové spojenie nepoužíva.

Kde beží váš softvér

Váš softvér Adresa eKasy Šifrovanie
na tom istom zariadení http://localhost:3010 netreba, komunikácia neopustí zariadenie
v lokálnej sieti https://ekasa.local:4010 (od verzie 9.1.0) odporúčame HTTPS (nižšie)
v cloude alebo inej sieti adresa Expose vždy HTTPS

V lokálnej sieti odporúčame od verzie 9.1.0 komunikovať cez HTTPS a pripájať sa podľa mena ekasa.local. Spojenie je šifrované, prihlasovacie údaje sa nedajú odpočúvať a meno platí, aj keď sa IP adresa zariadenia zmení.

Staršie verzie podporujú len HTTP na IP adrese zariadenia, napríklad http://192.168.1.24:3010. Zariadeniu vtedy nastavte pevnú IP adresu (napríklad rezerváciou v routri), inak sa môže po reštarte zmeniť a váš softvér ho nenájde.

Prístup z internetu

Lokálna komunikácia beží cez HTTP bez šifrovania, preto ju eKasa od verzie 9.0.4 nepovolí z internetu. Požiadavky prijme len z týchto adries:

  • z toho istého zariadenia (127.0.0.1, ::1),
  • z privátnych sietí 10.0.0.0/8, 172.16.0.0/12 a 192.168.0.0/16 a z lokálnych adries IPv6,
  • cez službu Expose.

Požiadavku z verejnej IP adresy, napríklad cez presmerovaný port na routri, eKasa odmietne so stavom 403:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-100-generalerror",
  "title": "Prístup bol odmietnutý",
  "status": 403,
  "code": -100,
  "detail": "Prístup zo siete internet (volanie z IP adresy inej ako 127.0.0.1 (localhost) alebo privátnych adries …) je z bezpečnostných dôvodov povolené iba cez zabezpečené spojenie medzi koncovými bodmi. …"
}

Znenie poľa detail sa môže medzi verziami meniť. Rozpoznajte túto situáciu podľa stavu 403 a kódu -100.

Verejná IP adresa, dynamický DNS ani presmerovanie portu preto nie sú vhodným spôsobom vzdialeného prístupu.

Ak váš softvér beží mimo lokálnej siete predajne, máte tri možnosti:

  1. Expose (odporúčame): je zabudované v eKase, netreba inštalovať nič ďalšie ani otvárať porty a spojenie je šifrované. Prihlasovacie údaje k Expose sa zadávajú priamo v nastaveniach eKasy.
  2. VPN: vzdialený server dostane adresu z privátnej siete predajne a eKasa ho berie ako lokálneho klienta. Hodí sa, ak zákazník VPN už používa, treba prepojiť viac zariadení či celé siete alebo sieť spravuje IT tím. Nastavenie VPN nie je súčasťou eKasy.
  3. Vlastná aplikácia v sieti predajne (bridge): beží na tom istom zariadení alebo v tej istej sieti ako eKasa, volá ju lokálne a s vaším serverom komunikuje vlastným spôsobom. Je to individuálne riešenie, ktoré si navrhujete, zabezpečujete a prevádzkujete sami. Nine Digit takú aplikáciu neposkytuje.

Použiť môžete aj vlastnú reverse proxy pred eKasou. Pred nasadením ju však overte: či eKasa požiadavku pustí, závisí od konfigurácie proxy a spracovania hlavičiek ako X-Forwarded-For.

Expose

Expose pridelí eKase stálu webovú adresu so šifrovaným spojením HTTPS. eKasa si k službe Expose sama otvorí spojenie, takže na predajni netreba verejnú IP adresu ani nastavovať router. Požiadavky a odpovede sú rovnaké ako pri lokálnom spojení, mení sa len adresa:

lokálne:    POST http://192.168.1.24:3010/api/v1/requests/receipts/cash_register
cez Expose: POST https://moja-kaviaren.expose.ninedigit.sk/v1/requests/receipts/cash_register

Cez Expose je dostupné len API, webové rozhranie nie. Ak máte o Expose záujem, napíšte nám.

Aplikácia v prehliadači (CORS)

Ak eKasu volá JavaScript priamo z webovej stránky v prehliadači, prehliadač požiadavku pustí, len ak eKasa povolí doménu stránky. Povolené domény nastavíte vo webovom rozhraní v menu Systém → Nastavenia, záložka Ostatné, časť CORS:

Pole Čo zadať
Povolené domény adresa vašej stránky bez cesty, napríklad https://pokladna.example.sk
Sprístupnené hlavičky hlavičky odpovede, ktoré má váš JavaScript čítať. Content-Range a Content-Disposition sú sprístupnené vždy.
Prístup z privátnej siete Povolený, ak stránka z verejnej adresy volá eKasu na lokálnej adrese. eKasa tak odpovie na predbežnú požiadavku Private Network Access, ktorú posielajú staršie verzie prehliadača Chrome.

Každú doménu zadajte zvlášť. Zástupný znak * (všetky domény) nie je z bezpečnostných dôvodov povolený.

Chrome a prístup k lokálnej sieti

Od verzie 142 prehliadač Chrome predvolene blokuje stránkam z internetu prístup k lokálnej sieti vrátane localhost. Kým ho používateľ nepovolí, volanie eKasy zlyhá s chybou v konzole prehliadača, napríklad:

Access to XMLHttpRequest at 'http://localhost:3010' from origin 'https://www.example.com' has been blocked
by CORS policy: Permission was denied for this request to access the 'unknown' address space.

Nejde o chybu nastavenia CORS v eKase. Pri prvom volaní Chrome zobrazí výzvu na povolenie prístupu k lokálnej sieti. Pokladník ju musí potvrdiť, prípadne prístup povolí neskôr v nastaveniach stránky v Chrome. Na pokladniciach s vaším softvérom preto s týmto krokom počítajte pri inštalácii.

Stránka načítaná cez HTTPS môže volať http://localhost, nie však HTTP adresu iného zariadenia v sieti. Prehliadač také volanie zablokuje ako nezabezpečený obsah. V tom prípade použite HTTPS (od verzie 9.1.0) alebo Expose.

Prihlásenie

Predvolene eKasa prihlásenie nevyžaduje. Ak je služba dostupná z lokálnej siete, odporúčame ho zapnúť. Vo webovom rozhraní v menu Systém → Nastavenia, záložka Ostatné, časť Prihlásenie, zapnite Vyžadovať prihlásenie a pridajte aspoň jedného používateľa.

Potom posielajte v každej požiadavke hlavičku Authorization podľa schémy HTTP Basic: slovo Basic, medzera a reťazec meno:heslo zakódovaný v Base64. Pre meno admin a heslo admin:

Authorization: Basic YWRtaW46YWRtaW4=

Bez hlavičky alebo s nesprávnymi údajmi vráti eKasa stav 401.

Prihlásenie môžete nastaviť aj cez API, v nastaveniach PUT /api/v1/settings. Heslo posielate v čitateľnej podobe. eKasa ho uloží a v odpovediach ho už nevráti: namiesto neho je "password": null a "hasPassword": true:

{
  "authentication": {
    "enabled": true,
    "users": [
      { "userName": "admin", "password": "admin" }
    ]
  }
}

Telo požiadavky obsahuje celé nastavenia. Najprv ich načítajte cez GET /api/v1/settings, zmeňte časť authentication a pošlite späť. Ako sa pri tom správajú maskované heslá a príznaky hasPassword, popisuje Migrácia na verziu 8.

Pri HTTP sa meno a heslo posielajú nešifrovane. V lokálnej sieti ich preto posielajte cez HTTPS.

HTTPS v lokálnej sieti

Od verzie 9.1.0 vie eKasa okrem HTTP obsluhovať aj HTTPS. Nastavenie je vo webovom rozhraní v záložke Ostatné, časť Hosting:

Nastavenie Predvolená hodnota Popis
Port (HTTP) 3010 nezabezpečené spojenie
HTTPS → Režim Vypnuté (len HTTP) Zapnuté (HTTP aj HTTPS), Presmerovať HTTP na HTTPS (odpoveď 307), Len HTTPS (vypnúť HTTP)
Port (HTTPS) 4010 zabezpečené spojenie
Certifikát samopodpísaný alebo vlastný certifikát vo formáte PFX

V lokálnej sieti je eKasa dostupná aj pod menom ekasa.local, napríklad https://ekasa.local:4010. Ak je v sieti viac zariadení s eKasou, každému nastavte vlastný názov inštancie, napríklad pokladna2.ekasa.local.

Samopodpísaný certifikát je vystavený na mená ekasa.local, *.ekasa.local a localhost. Klienti mu predvolene nedôverujú. Stiahnite si jeho verejnú časť v nastaveniach tlačidlom na stiahnutie alebo cez API a nainštalujte ju na klientoch medzi dôveryhodné certifikáty:

GET https://ekasa.local:4010/api/v1/settings/hosting/https/certificates/pfx?format=pem

Pre spojenie cez IP adresu potrebujete vlastný certifikát, ktorý túto adresu obsahuje.

Odporúčané nastavenie pre prevádzku v sieti: režim Presmerovať HTTP na HTTPS alebo Len HTTPS a v časti Prihlásenie voľba Vyžadovať HTTPS pre prihlásenie. eKasa potom odmietne prihlasovacie údaje poslané cez HTTP so stavom 401 ešte predtým, ako ich spracuje.

Kam ďalej

Esc

↑↓ výberEnter otvoriťEsc zavrieť

Chýba vám niečo v dokumentácii?

Napíšte nám, s čím potrebujete pomôcť. Ozveme sa do pár hodín.

Údaje použijeme len na odpoveď. Viac v ochrane osobných údajov.