# Connection and security

> How to connect to the eKasa service from the same device, from the local network and from the internet via Expose, and how to set up CORS, login and HTTPS.

Source: https://ekasa.ninedigit.sk/en/docs/security

How you connect to eKasa depends on where your software runs. It is simplest on the same device and in the shop's
local network. From the internet, eKasa is reachable only over a secure connection.

This article applies to the HTTP API. The .NET library runs directly inside your application and uses no network
connection.

## Where your software runs

| Your software | eKasa address | Encryption |
|---|---|---|
| on the same device | `http://localhost:3010` | not needed, traffic never leaves the device |
| in the local network | `https://ekasa.local:4010` (from version 9.1.0) | HTTPS recommended ([below](#https-in-the-local-network)) |
| in the cloud or another network | the Expose address | always HTTPS |

In the local network, from version 9.1.0 we recommend communicating over **HTTPS** and connecting by the name
`ekasa.local`. The connection is encrypted, credentials cannot be intercepted and the name keeps working even if the
device's IP address changes.

Older versions support only HTTP on the device's IP address, for example `http://192.168.1.24:3010`. In that case,
give the device a fixed IP address (for example with a reservation in the router); otherwise it may change after a
restart and your software will not find it.

## Access from the internet

Local communication uses unencrypted HTTP, so from version 9.0.4 eKasa does not allow it from the internet.
It accepts requests only from:

- the same device (`127.0.0.1`, `::1`),
- the private networks `10.0.0.0/8`, `172.16.0.0/12` and `192.168.0.0/16` and local IPv6 addresses,
- the Expose service.

A request from a public IP address, for example through a port forwarded on the router, is rejected with status `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. …"
}
```

The wording of `detail` may change between versions. Recognise this situation by status `403` and code `-100`.

A public IP address, dynamic DNS or port forwarding is therefore not a suitable way of remote access.

If your software runs outside the shop's local network, you have three options:

1. **Expose** (recommended): built into eKasa, with nothing else to install, no ports to open and an encrypted
   connection. The Expose credentials are entered directly in the eKasa settings.
2. **VPN**: the remote server gets an address from the shop's private network and eKasa treats it as a local client.
   It suits customers who already use a VPN, who need to connect several devices or whole networks, or whose
   network is managed by an IT team. VPN configuration is not part of eKasa.
3. **Your own app in the shop's network** (a bridge): it runs on the same device or in the same network as eKasa,
   calls it locally and talks to your server in its own way. It is a custom solution that you design, secure and
   operate yourself. Nine Digit does not provide such an app.

You can also put **your own reverse proxy** in front of eKasa. Test it before going live, though: whether eKasa lets
the request through depends on the proxy configuration and on how headers such as `X-Forwarded-For` are handled.

### Expose

Expose gives eKasa a permanent web address with an encrypted HTTPS connection. eKasa opens the connection to the
Expose service itself, so the shop needs neither a public IP address nor router configuration. Requests and
responses are the same as with a local connection; only the address changes:

```text
local:       POST http://192.168.1.24:3010/api/v1/requests/receipts/cash_register
via Expose:  POST https://moja-kaviaren.expose.ninedigit.sk/v1/requests/receipts/cash_register
```

Only the API is available through Expose, not the web interface. If you are interested in Expose,
[contact us](https://ekasa.ninedigit.sk/?zaujem=expose#kontakt).

## Browser applications (CORS)

If JavaScript on a web page calls eKasa directly from the browser, the browser lets the request through only if
eKasa allows the page's origin. Set the allowed origins in the web interface in the **Systém → Nastavenia**
(System → Settings) menu, on the **Ostatné** (Other) tab, section **CORS**:

| Field | What to enter |
|---|---|
| **Povolené domény** (Allowed origins) | your page's origin without a path, for example `https://pos.example.com` |
| **Sprístupnené hlavičky** (Exposed headers) | response headers your JavaScript needs to read. `Content-Range` and `Content-Disposition` are always exposed. |
| **Prístup z privátnej siete** (Private network access) | **Povolený** (Allowed) if a page on a public address calls eKasa on a local address. eKasa then answers the Private Network Access preflight request sent by older versions of Chrome. |

Enter each origin separately. The `*` wildcard (all origins) is not allowed for security reasons.

### Chrome and local network access

From version 142, Chrome blocks pages from the internet from accessing the local network, including `localhost`,
by default. Until the user allows it, calls to eKasa fail with an error in the browser console, for example:

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

This is not a CORS configuration error in eKasa. On the first call, Chrome shows a prompt to allow local network
access. The cashier has to confirm it, or allow access later in Chrome's site settings. Plan for this step when
installing your software on cash registers.

A page loaded over HTTPS may call `http://localhost`, but not an HTTP address of another device in the network.
The browser blocks such a call as mixed content. In that case use HTTPS (from version 9.1.0) or Expose.

## Login

By default eKasa does not require login. If the service is reachable from the local network, we recommend turning it
on. In the web interface, in the **Systém → Nastavenia** menu, on the **Ostatné** tab, section **Prihlásenie**
(Login), turn on **Vyžadovať prihlásenie** (Require login) and add at least one user.

Then send the `Authorization` header with every request using the HTTP Basic scheme: the word `Basic`, a space and
the string `name:password` encoded in Base64. For the name `admin` and password `admin`:

```text
Authorization: Basic YWRtaW46YWRtaW4=
```

Without the header or with wrong credentials, eKasa returns status `401`.

You can also set up login through the API, in the settings `PUT /api/v1/settings`. You send the password in plain
text; eKasa stores it and no longer returns it in responses: they contain `"password": null` and
`"hasPassword": true` instead:

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

The request body contains the complete settings. Load them first with `GET /api/v1/settings`, change the
`authentication` part and send them back. How masked passwords and the `hasPassword` flags behave is described in
[Migration to version 8](https://ekasa.ninedigit.sk/en/docs/migration/v8#5-changes-in-apiv1settings).

Over HTTP, the name and password are sent unencrypted. In the local network, send them over HTTPS.

## HTTPS in the local network

From version 9.1.0, eKasa can serve HTTPS in addition to HTTP. The settings are in the web interface on the
**Ostatné** tab, section **Hosting**:

| Setting | Default | Description |
|---|---|---|
| **Port (HTTP)** | `3010` | unsecured connection |
| **HTTPS → Režim** (Mode) | Vypnuté (HTTP only) | Zapnuté (HTTP and HTTPS), Presmerovať HTTP na HTTPS (response `307`), Len HTTPS (HTTP off) |
| **Port (HTTPS)** | `4010` | secured connection |
| **Certifikát** (Certificate) | self-signed | or your own certificate in PFX format |

In the local network, eKasa is also available under the name `ekasa.local`, for example `https://ekasa.local:4010`.
If there are several eKasa devices in the network, give each its own instance name, for example
`pokladna2.ekasa.local`.

The self-signed certificate is issued for the names `ekasa.local`, `*.ekasa.local` and `localhost`. Clients do not
trust it by default. Download its public part in the settings with the download button or through the API, and
install it on the clients as a trusted certificate:

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

To connect by IP address, you need your own certificate that contains that address.

Recommended setup for operation in a network: mode **Presmerovať HTTP na HTTPS** (redirect) or **Len HTTPS**
(HTTPS only), and in the **Prihlásenie** section the option **Vyžadovať HTTPS pre prihlásenie** (Require HTTPS for
login). eKasa then rejects credentials sent over HTTP with status `401` before processing them.

## Where next

- [HTTP API](https://ekasa.ninedigit.sk/en/docs/rest-api): Installation, the first call and communication rules.
- [Receipt registration](https://ekasa.ninedigit.sk/en/docs/receipt-registration): Receipt types, items, payments and the result.
- [Error codes](https://ekasa.ninedigit.sk/en/docs/rest-api/error-codes): What the codes in error responses mean.
