This is a plugin for OpenResty Nginx that 2FA with a YubiKey OTP. The plugin is designed to run within an Nginx block from a single call, providing a seamless and efficient authentication process.
- YubiKey
- An existing Nginx deployment which is running from a docker compose
- Setup a custom
Dockerfile
to build your Docker environment into Lua ENV variables- Check my
entrypoint.sh
as an example to creating the environment directives on OpenResty startup
- Check my
This process will guide you through installing the plugin into the OpenResty Lua Path.
- Clone or download the repository.
- Add
lua_package_path
to the core Nginx configuration.
- Make sure that persistent volume in Nginx is configured to a location like
./lua:/usr/local/openresty/nginx/lua:ro
. - In
nginx.conf
setuplua_package_path '/usr/local/openresty/nginx/lua/plugins/?.lua;;';
.
- Place the
plugins/
folder for this repo into thatlua/
directory for the docker compose.
Once installed, you can use the access_by_lua_file
in your Nginx configuration. Here's an example:
server {
listen 443 ssl;
server_name example.com;
error_log /usr/local/openresty/nginx/logs/error.log;
access_log /usr/local/openresty/nginx/logs/otp-access.log main;
# Configure OTP auth
access_by_lua_file /usr/local/openresty/nginx/lua/plugins/resty-yubikey-auth/main.lua;
location / {
proxy_pass http://localhost:8080$request_uri;
}
}
The plugin stores the the environment in code within env.lua
. You can set the following environment variables:
Environment Variable | Default | Description |
---|---|---|
YUBIKEY_REQUEST_ID |
REQUIRED | A unique ID which identifies you the requestor |
YUBIKEY_AUTHORIZED_KEYS |
REQUIRED | Accepts a CSV of authorized YubiKey IDs |
YUBIKEY_COOKIE_SECRET |
REQUIRED | A secret used to encrypt the cookie |
YUBIKEY_COOKIE_NAME |
OTP |
The name of the cookie |
YUBIKEY_COOKIE_SAMESITE |
Strict |
Mozilla Cookie SameSite |
YUBIKEY_COOKIE_SECURITY |
Secure |
Set env to "" to disable Mozilla Cookie Secure |
YUBIKEY_COOKIE_TTL |
1800 |
The time to live for the cookie in seconds |
This plugin utilizes the Yubico WSAPI to verify the OTP.
After verification from Yubico the YUBIKEY_AUTHORIZED_KEYS
from the environment is used to authorize the "user".
The plugin features an OTP input form that is displayed when authentication is required. The form is customizable to fit your application's look and feel. Checkout login_page.lua
to review this feature.