Docs / Configure

Authentication

Define users in the configuration, give each slot a list of users and permissions, and have clients log in with u and p.

The password travels in cleartext

No Ghoti listener implements TLS, so the p command, and the HTTP Basic Auth header on the http transport, carry the password in the clear. Anyone who can observe the traffic can read it. Terminate TLS in a reverse proxy or load balancer in front of the server, or keep the traffic on loopback or an equivalent trusted network. See SECURITY.md for the full security model.

Users#

Define users and passwords in a top-level users map:

users:
  my_service: "my_password"
  other_service: "another_password"
  upstream: "123456"

Usernames and passwords follow the login rules below. A user that breaks them stops the server at startup.

The users block is read as a map, and map entries can't be injected from GHOTI_ environment variables, so user passwords have to come from the configuration file. Keep that file outside the repository, owned by the service user and readable only by it. See SECURITY.md.

Slot permissions#

Each slot can have its own users map, giving each user one of three permissions:

ValuePermission
rRead only
wWrite only
aAll: read and write
slot_001:
  kind: simple_memory
  users:
    my_service: "r"
    other_service: "w"
    upstream: "a"

slot_002:
  kind: simple_memory
  users:
    my_service: "a"

slot_003:
  kind: simple_memory

With this configuration my_service can read slots 001 and 002 but only write slot 002.

A slot without a users map is open to everyone

Slot 003 above has no users, so anyone can read and write it, logged in or not. As soon as a slot has a users map, anonymous connections and unlisted users can't use it.

Logging in#

On standard and telnet, a client logs in with u followed by the username, then p followed by the password. Both answer v and the username:

> umy_service
< vmy_service
> pmy_password
< vmy_service
> w000secret
< v000secret

Every later command on that connection runs as the logged-in user. On the http transport there is no login exchange: send the credentials as an HTTP Basic Auth header on every request. A request without the header is anonymous, and a request with wrong credentials gets 401.

Login rules#

A client has to follow these rules exactly:

Captured failures, each on a new connection:

> umy_service
< vmy_service
> pwrong_pass
< exxx004
# connection closed

> u1bad
< exxx002
# connection closed

Found something out of date? Open an issue or edit this page.