Configuration
Contents
Setup layout
Gateryx is designed to serve a group of web applications. For basic configuration it is important to have all web applications hosted as APP.domain where APP is the name of the application and domain is the domain of the group. The applications may have aliases.
Different layouts are possible but may require additional complicated setups and certain functionality is not available in such cases (e.g. Passkey authentication).
Initial setup
After the server is installed, it is important to change the following:
/etc/gateryx/config.toml - change auth/tokens/domain to the domain of the application group.
/etc/gateryx/config.toml - obtain and replace the certificate and key files in tls section of the HTTPS listener. As there is only one certificate used for the whole application group, it should either cover all hosted application subdomains or be a wildcard (both kinds can be obtained e.g. from LetsEncrypt or an internal company certificate can be used).
/etc/gateryx/app.d/system.toml - change hosts to the desired system application host name.
/etc/gateryx/app.d - create configuration files for each web application to be served, see included example.toml for reference.
There is no users created by default, use the gateryx CLI command to create:
gateryx user create USERNAME
In case if an external IDF will be used, no local users are needed.
Server
Main configuration
The main server configuration file is located by default at /etc/gateryx/config.toml
# The notation used for
#
# * Large numbers - k = 1_000, m = 1_000_000, g = 1_000_000_000
# * Time durations - s = seconds (default if not specified), m = minutes,
# h = hours, d = days, w = weeks, M = months, y = years
#
[auth]
# Authenticator configuration
# Note: there can be only one authenticator configured at a time
# Basic authenticator using htpasswd file
# use htpasswd -B to create bcrypt hashed passwords
#authenticator = { kind = "htpasswd", params = { path = "htpasswd" } }
# Database authenticator (uses server database to store user accounts)
# uses server database to store user accounts
# WARNING: it is recommended to raise the minimum password length and complexity
# requirements when running in production
authenticator = { kind = "db", params = { policy = { min_length = 6, require_uppercase = false, require_lowercase = false, require_digit = false, require_special = false } } }
# LDAP authenticator
#
# * path - LDAP search base DN for user accounts (e.g. "ou=users,dc=domain,dc=com")
# * service_user - LDAP service account username (e.g. "service" or "cn=service,dc=domain,dc=com")
# * service_password - LDAP service account password
# * url - LDAP server URL (e.g. "ldap://somehost:389" or "ldaps://somehost:636")
# * provider - LDAP server provider
# * starttls - optional boolean parameter to enable STARTTLS for ldap:// URLs (default: false)
# * no_tls_verify - optional boolean parameter to disable TLS certificate verification (default: false)
# * timeout - optional connection timeout in seconds (default: 5)
# * pool_size - optional connection pool size (default: 1)
# * auth_pool_size - optional authentication connection pool size (default: 1)
#
#
# supported providers:
# * "msad" - Microsoft Active Directory
# * "authentik" - Authentik LDAP server
#
# other providers are treated as generic LDAP (RFC 4510), specify as "generic" or omit the provider parameter
# warning: for generic LDAP servers the authenticator does not check if the user account is disabled or locked
#authenticator = { kind = "ldap", params = { path = "ou=users,dc=domain,dc=com", service_user = "service", service_password = "secret", url = "ldap://somehost:389", provider = "msad" } }
# EVA ICS authenticator (requires [eapi] section)
#
# * auth_svcs - list of authentication services to use, required
# * timeout - optional; overrides [eapi] timeout for this authenticator
#
#authenticator = { kind = "eva", params = { auth_svcs = ["eva.aaa.localauth"], timeout = 5 } }
# EAPI (EVA ICS bus) connection
#
# * id - bus client ID (default: gateryx)
# * timeout - default timeout for bus operations
# * bus/path - bus socket path (default: /opt/eva4/var/bus.ipc)
#[eapi]
#id = "gateryx"
#timeout = 5
#bus = { path = "/opt/eva4/var/bus.ipc" }
# Breakin protection configuration
#
# * max_records - maximum number of remote clients to track
# * window - time window
# * ip_score - score to add for each failed attempt from the same IP address
# * user_score - score to add for each failed attempt for the same username
# * captcha_threshold - score threshold to require captcha verification
breakin_protection = { max_records = "10k", window = "10m", ip_score = 1, user_score = 1, captcha_threshold = 3 }
# Passkeys
#
# * max_auth_challenges - maximum number of allowed authentication challenges per time
# * max_reg_challenges - maximum number of allowed registration challenges per time
# * timeout - challenge validity time in seconds
# * max_auth_callenges_per_ip - maximum number of allowed authentication challenges per IP address
# * check_login_present - require the selected authenticator to confirm that the user exists (default: true)
passkeys = { max_auth_challenges = "1k", max_reg_challenges = 10, timeout = 60 }
# key_file: PKCS#8 private key in PEM format, eg. openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:prime256v1 -out tokens.pem. Auto-generated if not present
# expire: token expiration time since the token was issued
# max_bearer_expire: maximum allowed expiration time for per-app tokens
# domain: token validation for subdomains of the specified domain, also used as rp_id for passkeys
# cookie: name of the cookie to store the token (gateryx_auth_<cookie>), default is "token"
# stick_to_ip: when true, JWTs include client IP and are only accepted when the request IP matches (default: false)
tokens = { key_file = "tokens.pem", expire = "7d", domain = "domain.local", cookie = "token" }
# authentication form web
www_root = "/var/gateryx/www/auth"
# The following user agents will always get 401 Unauthorized response with
# Basic authentication challenge, unless text/html is requested
#reply_401_to_user_agents = ["git/*", "curl/*", "Wget/*"]
[[listener]]
bind = "0.0.0.0:80"
max_clients = "1k"
max_workers = "5k"
app = "plain"
[[listener]]
bind = "0.0.0.0:443"
max_clients = "1k"
max_workers = "5k"
tls = { cert = "selfsigned.crt", key = "selfsigned.pem", protocols = ["tls1.2", "tls1.3"] }
# allows HTTP/2
protocol = "http2"
# allowed hosts/networks (ip addresses only), allowed all by default
#allow = ["127.0.0.1/32"]
[server]
http_log = "/var/gateryx/log/access.log"
# when set, use this HTTP header value as the client IP instead of the
# connection IP (e.g. "X-Forwarded-For" or "X-Real-IP"); for comma-separated
# values the first element is used
#remote_real_ip = "X-Forwarded-For"
# number of master threads (responsible for logging and IDP)
master_threads = 1
# number of worker threads (responsible for processing web requests)
worker_threads = 1
max_body_size = "20m"
timeout = 5
user = "gateryx"
#[websocket_default]
#read_buffer = "16k"
#write_buffer = "16k"
#max_message_size = "40m"
#max_frame_size = "40m"
# SQLite / PostgreSQL
[db]
uri = "sqlite:///var/gateryx/db/gateryx.db"
#uri = "postgres://gateryx:xxx@192.168.1.1/gateryx"
pool_size = 10
timeout = 5
# Override default HTTP header names
#[headers]
#jwt_assertion = "X-JWT-Assertion" # JWT assertion header
#user = "X-Gateryx-User" # Current authenticated user
#real_ip = "X-Real-IP" # Real client IP address
#authorization = "X-Gateryx-Authorization" # Additional authorization header
#via = "X-Via" # Via header (returned to client)
[admin]
# key_file: PKCS#8 private key in PEM format, eg. openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:prime256v1 -out admin.pem. Auto-generated if not present
key_file = "admin.pem"
# allowed hosts/networks (ip addresses only), no admin access by default
allow = ["127.0.0.1/32"]
# max time difference in seconds between server and client for admin requests
#max_time_diff = "5m"
# Web applications can be defined directly in the main configuration file or in
# "app.d" directory as separate files with ".toml" extension
#[[app]]
#url = "gateryx://system"
#hosts = [ "gate.domain.local" ]
#remote = "/var/gateryx/www/system"
It is possible to validate the configuration file with:
gateryx-server --check
After the configuration file is modified, the Gateryx server can be started with:
systemctl start gateryx
Web Applications
Web application configurations are located in /etc/gateryx/app.d/.toml* by default. In case if a different configuration path is used, the app.d folder must be located in the same folder as the main configuration file.
Example:
# Application name
name = "Example App"
# External application URL, for non-standard layouts
#url = "https://example.domain.local/"
# HTTP hosts to reply
hosts = ["example.domain.local"]
# Remote target to connect to
remote = "http://192.168.1.10:8080/"
# Compress target responses (brotli)
# The compression is applied automatically to all data > 1KB
# Exceptions:
# - image/* (except image/svg, image/svg+xml)
# - video/*
# - audio/*
# - application/zip
# - application/gzip
# - application/x-gzip
# - application/x-7z-compressed
# - application/x-rar-compressed
compress = true
# Client protocol to use, http1.0 for HTTP/1.0, http1 for HTTP/1.1 (default),
# http2 for HTTP/2
#
# - when http1.0 client is used:
# - no extra headers are inserted (including JWT assertion)
# - Accept-Encoding and Connection headers are removed
# - the cookie "gateryx_auth_token" is forcibly removed from Cookie header.
# - recomended for embedded appliances that do not support HTTP/1.1 properly
#
# - when http2 client is used, the request is not downgraded and sent as-is
# (the listener must be configured to support HTTP/2)
#
#client = "http1"
# Path to application icon (relative to the primary configuration file)
#icon = "icons/generic.png"
# Target timeout (default: 10 seconds)
#timeout = 10
# Application visibility in the list (default: false)
#hidden = false
# Use authentication (default: true)
#use_auth = true
# For remote HTTPS targets, skip TLS verification (default: false)
#skip_remote_tls_verify = false
# Allow access to Gateryx API endpoints (/.gateryx/*) for this app (default: false)
# When enabled, the proxied app can access authentication, RPC, and other Gateryx APIs
#gateryx_api = false
# allowed hosts/networks (ip addresses only), allowed all by default
#allow = ["127.0.0.1/32"]
# allow per-application tokens (default: true)
#allow_tokens = true
# allowed user groups (by name), allow all if the list is empty or not present
#allow_groups = ["group1", "group2"]
#[websocket]
# Send only required headers, do not send the token in cookies
#strict = true
An application can also include specific WebSocket options in websocket section. The parameters are identical to the ones in the main configuration file.
System application
The system application is a built-in web application that provides a general interface for users. There should be only one system application configured.
# System application
url = "gateryx://system"
hosts = [ "gate.domain.local" ]
# System applcation web
remote = "/var/gateryx/www/system"
The system application is also responsible for OIDC token flow and other system tasks.
Plain application
The plain application is a web application which does several important tasks:
Serves static files from .well-known folder which must be located in the configured web root (remote parameter).
For other requests - redirects requests to secure HTTPS URLs.
The application has no host names to configure and is connected directly to a listener in the main configuration file (usually plain HTTP listener on port 80).
# Used to redirect plain HTTP traffic to HTTPS ports
url = "gateryx://plain"
# A folder to host files via plain HTTP (usually .well-known folder only for
# ACME challenges)
remote = "/var/gateryx/www/plain"
# Override redirection port
#[settings]
#target_port = 8443
Administration client
The Gateryx client is a command line tool to perform the administration tasks.
The configuration file is located by default at /etc/gateryx/client.toml. In case the configuration file is missing, the client will use server defaults if installed on the same machine.
key_file = "admin.pem"
url = "http://127.0.0.1"
timeout = 5
In case if the client is used on a different machine, it is important to copy admin.pem key file from the server and ensure the client.toml file points to it.
Configuring 3rd party apps for OIDC
Third-party applications can be configured to use Gateryx as an OIDC provider with the following URLs exposed:
https://gate.domain/.well-known/openid-configuration - OIDC configuration URL
https://gate.domain/.well-known/jwks.json - public keys URL
https://gate.domain/.well-known/public.pem - public key URL in PEM format
Where gate.domain is the host name of the system application configured.
The current token can be obtained by the third party application either from gateryx_auth_token cookie or X-JWT-Assertion HTTP header.
If an application wants to logout the user, it can erase the mentioned cookie. This works either for a single application if a custom domain is used or for all application group of the domain. For the last case, the domain=.yourdomain must be used when the cookie is erased.
If a third-party application can fully trust the Gateryx server (e.g. using IP filtering or having no external access), it can use X-Gateryx-User HTTP header which contains the username of the authenticated user.
Configuring 3rd party apps for Gateryx API
Third-party applications can be configured to use the exposed Gateryx API (./gateryx/rpc) having gateryx_api: true in the application configuration.
As the API can directly manipulate sensitive authentication data, it is strongly recommended to enable API for trusted applications only.