Time-based one-time password (TOTP) authentication for Nginx
The Time-based One-Time Password (TOTP) algorithm, provides a secure mechanism for short-lived one-time password values, which are desirable for enhanced security. This algorithm can be used across a wide range of network applications ranging from remote Virtual Private Network (VPN) access, Wi-Fi network logon to transaction-orientated Web applications.
The nginx-http-auth-totp module provides TOTP authentication for a Nginx server.
- HTTP basic authentication using time-based one-time password (TOTP)
- Cookie-based tracking of authenticated clients beyond TOTP validity window
- Configurable secret, time reference, time step and truncation length for TOTP generation
- Configurable time-skew for TOTP validation
To build the nginx-http-auth-totp module from the Nginx source directory:
./configure --add-module=/path/to/nginx-http-auth-totp
make
make installFor users who prefer pre-built and optimized packages, the nginx-http-auth-totp module can be installed from the GetPageSpeed repository:
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-auth-totpserver {
listen 80;
location /protected {
auth_totp_realm "Protected";
auth_totp_file /etc/nginx/totp.conf;
auth_totp_length 8;
auth_totp_skew 1;
auth_totp_step 1m;
auth_totp_cookie "totp-session";
auth_totp_expiry 1d;
}
}Enable the module by adding the following at the top of /etc/nginx/nginx.conf:
load_module modules/ngx_http_auth_totp_module.so;- syntax:
auth_totp_cookie <name> - default:
totp - context:
http,server,location,limit_except
Specifies the name of the HTTP cookie to be used for tracking authenticated clients.
As the validity of the Time-based One-Time Password (TOTP) used for authentication expires (by design), a HTTP cookie is set following successful authentication in order to persist client authentication beyond the TOTP validity window. This configuration directives specifies the name to be used when setting this cookie while the expiry period for this cookie may be set using the auth_totp_expiry directive.
- syntax:
auth_totp_expiry <interval> - default:
0s - context:
http,server,location,limit_except
Specifies the expiry time for the HTTP cookie to be used for tracking authenticated clients.
If this expiry value is not specified (or set to zero), the HTTP cookie used for tracking authenticated clients will be set as a session cookie which will be deleted when the current HTTP client session ends. It is important to note that the browser defines when the "current session" ends, and some browsers use session restoration when restarting, which can cause session cookies to last indefinitely.
- syntax:
auth_totp_file <filename> - default: -
- context:
http,server,location,limit_except
Specifies the file that contains usernames and shared secrets for Time-based One-Time Password (TOTP) authentication.
This configuration file has the format:
# comment
user1:secret1
user2:secret2
user3:secret3
- syntax:
auth_totp_length <number> - default:
6 - context:
http,server,location,limit_except
Specifies the truncation length of the Time-based One-Time Password (TOTP) code. This truncation length may be between 1 and 8 digits inclusively.
If the supplied TOTP is of a different length to this value, the authentication request will fail.
- syntax:
auth_totp_realm <string>|off - default:
off - context:
http,server,location,limit_except
Enables validation of user name and Time-based One-Time Password (TOTP) using the "HTTP Basic Authentication" protocol. The specified parameter is used as the realm for this authentication. This parameter value can contain variables. The special value of off cancels the application of any auth_totp_realm directive inherited from a higher configuration level.
- syntax:
auth_totp_skew <number> - default:
1 - context:
http,server,location,limit_except
Specifies the number of time steps by which the time base between the issuing and validating TOTP systems.
Due to network latency, the gap between the time that a OTP was generated and the time that the OTP is received at the validating system may be large. Indeed, it is possible that the receiving time at the validating system and that when the OTP was generated by the issuing system may not fall within the same time-step window. Accordingly, the validating system should typically set a policy for an acceptable OTP transmission window for validation. In line with this, the validating system should compare OTPs not only with the receiving timestamp, but also the past timestamps that are within the transmission delay.
It is important to note that larger acceptable delay windows represent a larger window for attacks and a balance must be struck between the security and usability of OTPs.
- syntax:
auth_totp_start <time> - default:
0 - context:
http,server,location,limit_except
Specifies the UNIX time from which to start counting time steps as part of Time-based One-Time Password (TOTP) algorithm operations.
The default value is 0, the UNIX epoch at 1970/01/01.
- syntax:
auth_totp_step <interval> - default:
30s - context:
http,server,location,limit_except
Specifies the time step as part of Time-based One-Time Password (TOTP) algorithm operations.