auth_totp_file
The `auth_totp_file` directive specifies the path to the TOTP configuration file for use in TOTP authentication within NGINX.
Description
The auth_totp_file directive is a crucial configuration option for enabling Time-based One-Time Password (TOTP) authentication in NGINX. This directive accepts a file path as its argument and is typically used to direct NGINX to a specific configuration file that contains the necessary keys and configurations for generating and validating TOTP tokens. The TOTP mechanism enhances security by generating passwords that are valid for a limited time, thus requiring users to regenerate codes regularly for authentication.
When a request is made to a protected location, NGINX checks the provided TOTP against the secrets defined in the specified file. If the TOTP is valid and corresponds with the expected authentication time frame, the request is allowed to proceed. This step is essential for protecting sensitive resources from unauthorized access. The files referenced through auth_totp_file are expected to be structured according to specific configurations, detailing key-value pairs where keys may represent user identifiers and values hold the corresponding secret keys used for TOTP generation.
This directive can be included in various contexts—namely, http, server, location, and limit_except—allowing flexibility in its application across different levels of NGINX configurations. To effectively use this directive, it's imperative that the file path provided is accessible by the NGINX process, and that proper permissions are set to avoid unauthorized access to sensitive keys.
Config Example
location /protected {
auth_totp_realm "Protected Area";
auth_totp_file /etc/nginx/totp.conf;
auth_totp_length 8;
auth_totp_reuse off;
auth_totp_skew 1;
auth_totp_step 1m;
auth_totp_cookie "totp-session";
auth_totp_expiry 1d;
}Ensure the file path specified has the correct permissions for the NGINX user to read it.
If the specified file does not exist, TOTP authentication will fail for all requests.
The keys in the totp configuration file must be correctly formatted to avoid parsing errors.