Hermes Gateway — User Authentication with Lua Script

This guide walks through setting up Lua-based user authentication in Hermes Gateway. The Lua script authenticates users against a simple users.txt file — the same pattern used to integrate with any external user store, such as LDAP, Active Directory, or HashiCorp Vault-mounted secrets.

username:*ANENCRYPTEDPASSWORD*

Passwords are hashed using MySQL's PASSWORD() function.

Setting Up with Docker Compose

Make sure you've completed the steps in the Installation Guide.

Then, take the config-examples/config.example-demo.yaml as your starting point — see the Configuration Guide for a full breakdown of the options.

cd deployments
touch .env  # create an empty env file; config will be driven by config.json
cp config-examples/config.example-demo.json config.json
make start-demo  # may take a few minutes to pull images on first run

Connecting to Hermes Gateway

Once the demo stack is running, connect via your preferred SQL client on localhost:3307:

mysql -h localhost -P 3307 -u root -p

Enter 123456 when prompted (or whatever you set in config.json).

From there, you can explore Hermes Gateway console commands:

show cache help;

See the Console Guide for the full command reference.

Testing Authentication as Other Users

A key feature of this demo is the users.txt-based auth flow, which mirrors how you'd integrate any external user directory — LDAP, Azure AD, or a Vault-managed credential file.

mysql -h localhost -P 3307 -u someuser -p

Enter testpass when prompted, then:

show cache help;

Adding a New User

To add a user, first generate a hashed password using Hermes Gateway's MySQL-compatible interface:

mysql -h localhost -P 3307 -u root -p

Enter 123456 when prompted, then run:

SELECT PASSWORD('newpassword');

Copy the resulting hash and add a new entry to users.txt:

newuser:*ANENCRYPT3DP455W0RDH4SH*

The new user can authenticate immediately — no restart required.