# Pripojenie a zabezpečenie

> Ako sa k službe eKasa pripojiť z toho istého zariadenia, z lokálnej siete a z internetu cez Expose, a ako nastaviť CORS, prihlásenie a HTTPS.

Zdroj: https://ekasa.ninedigit.sk/docs/security

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](#https-v-lokálnej-sieti)) |
| 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`:

```json
{
  "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:

```text
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](https://ekasa.ninedigit.sk/?zaujem=expose#kontakt).

## 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:

```text
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`:

```text
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`:

```json
{
  "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](https://ekasa.ninedigit.sk/docs/migration/v8#5-zmeny-v-apiv1settings).

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:

```http
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

- [HTTP API](https://ekasa.ninedigit.sk/docs/rest-api): Inštalácia, prvé volanie a pravidlá komunikácie.
- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Typy dokladov, položky, platby a výsledok.
- [Chybové kódy](https://ekasa.ninedigit.sk/docs/rest-api/error-codes): Význam kódov v chybových odpovediach.
