├── config ├── LICENSE ├── ngx_http_auth_totp.h ├── README.md └── ngx_http_auth_totp.c /config: -------------------------------------------------------------------------------- 1 | ngx_addon_name=ngx_http_auth_totp_module 2 | 3 | DEPS="$ngx_addon_dir/ngx_http_auth_totp.h" 4 | SRCS="$ngx_addon_dir/ngx_http_auth_totp.c" 5 | 6 | LIBS="-lcrypto" 7 | 8 | if test -n "$ngx_module_link"; then 9 | ngx_module_type=HTTP 10 | ngx_module_name=$ngx_addon_name 11 | ngx_module_deps=$DEPS 12 | ngx_module_srcs=$SRCS 13 | ngx_module_libs=$LIBS 14 | . auto/module 15 | else 16 | HTTP_MODULES="$HTTP_MODULES $ngx_addon_name" 17 | NGX_ADDON_DEPS="$NGX_ADDON_DEPS $DEPS" 18 | NGX_ADDON_SRCS="$NGX_ADDON_SRCS $SRCS" 19 | NGX_ADDON_LIBS="$NGX_ADDON_LIBS $LIBS" 20 | fi 21 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 Rob Casey 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /ngx_http_auth_totp.h: -------------------------------------------------------------------------------- 1 | #ifndef _NGX_HTTP_AUTH_TOTP_H_INCLUDED_ 2 | #define _NGX_HTTP_AUTH_TOTP_H_INCLUDED_ 3 | 4 | #include 5 | #include 6 | #include 7 | 8 | 9 | #define MODULE_NAME ("totp") 10 | 11 | #define NGX_HTTP_AUTH_TOTP_BUF_SIZE (2048) 12 | 13 | 14 | /* 15 | The following enumeration is intended to contain the processing states 16 | employed by the configuration file parser. 17 | */ 18 | 19 | typedef enum { 20 | STATE_USER = 0, 21 | STATE_SECRET, 22 | STATE_START, 23 | STATE_STEP, 24 | STATE_LENGTH, 25 | STATE_SKIP 26 | } 27 | ngx_http_auth_totp_state_e; 28 | 29 | typedef struct { 30 | ngx_rbtree_t tree; 31 | ngx_rbtree_node_t sentinel; 32 | ngx_slab_pool_t *shpool; 33 | } 34 | ngx_http_auth_totp_shm_t; 35 | 36 | typedef struct { 37 | ngx_http_complex_value_t *realm; 38 | ngx_http_complex_value_t *totp_file; 39 | ngx_int_t length; 40 | ngx_int_t skew; 41 | time_t start; 42 | time_t step; 43 | ngx_str_t cookie; 44 | time_t expiry; 45 | ngx_flag_t reuse; 46 | ngx_shm_zone_t *shm; 47 | } 48 | ngx_http_auth_totp_loc_conf_t; 49 | 50 | 51 | #endif /* _NGX_HTTP_AUTH_TOTP_H_INCLUDED_ */ 52 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # nginx-http-auth-totp 2 | 3 | Time-based one-time password (TOTP) authentication for Nginx 4 | 5 | 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. 6 | 7 | The nginx-http-auth-totp module provides TOTP authentication for a Nginx server. 8 | 9 | ## Features 10 | 11 | * HTTP basic authentication using time-based one-time password (TOTP) 12 | * Cookie-based tracking of authenticated clients beyond TOTP validity window 13 | * Configurable secret, time reference, time step and truncation length for TOTP generation 14 | * Configurable time-skew for TOTP validation 15 | 16 | ## Build 17 | 18 | To build the nginx-http-auth-totp module from the Nginx source directory: 19 | 20 | ```bash 21 | ./configure --add-module=/path/to/nginx-http-auth-totp 22 | make 23 | make install 24 | ``` 25 | 26 | ## Packages 27 | 28 | For users who prefer pre-built and optimized packages, the nginx-http-auth-totp module can be installed from the [GetPageSpeed repository](https://nginx-extras.getpagespeed.com/modules/auth-totp/): 29 | 30 | ```bash 31 | dnf -y install https://extras.getpagespeed.com/release-latest.rpm 32 | dnf -y install nginx-module-auth-totp 33 | ``` 34 | 35 | ## Configuration 36 | 37 | ```nginx 38 | server { 39 | listen 80; 40 | 41 | location /protected { 42 | auth_totp_realm "Protected"; 43 | auth_totp_file /etc/nginx/totp.conf; 44 | auth_totp_length 8; 45 | auth_totp_reuse off; 46 | auth_totp_skew 1; 47 | auth_totp_step 1m; 48 | auth_totp_cookie "totp-session"; 49 | auth_totp_expiry 1d; 50 | } 51 | } 52 | ``` 53 | 54 | Enable the module by adding the following at the top of `/etc/nginx/nginx.conf`: 55 | 56 | ```nginx 57 | load_module modules/ngx_http_auth_totp_module.so; 58 | ``` 59 | 60 | ## Directives 61 | 62 | ### auth_totp_cookie 63 | 64 | * **syntax:** `auth_totp_cookie ` 65 | * **default:** `totp` 66 | * **context:** `http`, `server`, `location`, `limit_except` 67 | 68 | Specifies the name of the HTTP cookie to be used for tracking authenticated clients. 69 | 70 | 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. 71 | 72 | ### auth_totp_expiry 73 | 74 | * **syntax:** `auth_totp_expiry ` 75 | * **default:** `0s` 76 | * **context:** `http`, `server`, `location`, `limit_except` 77 | 78 | Specifies the expiry time for the HTTP cookie to be used for tracking authenticated clients. 79 | 80 | 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. 81 | 82 | ### auth_totp_file 83 | 84 | * **syntax:** `auth_totp_file ` 85 | * **default:** - 86 | * **context:** `http`, `server`, `location`, `limit_except` 87 | 88 | Specifies the file that contains usernames and shared secrets for Time-based One-Time Password (TOTP) authentication. 89 | 90 | This configuration file has the format: 91 | 92 | # comment 93 | user1:secret1 94 | user2:secret2 95 | user3:secret3 96 | 97 | ### auth_totp_length 98 | 99 | * **syntax:** `auth_totp_length ` 100 | * **default:** `6` 101 | * **context:** `http`, `server`, `location`, `limit_except` 102 | 103 | Specifies the truncation length of the Time-based One-Time Password (TOTP) code. This truncation length may be between 1 and 8 digits inclusively. 104 | 105 | If the supplied TOTP is of a different length to this value, the authentication request will fail. 106 | 107 | ### auth_totp_realm 108 | 109 | * **syntax:** `auth_totp_realm |off` 110 | * **default:** `off` 111 | * **context:** `http`, `server`, `location`, `limit_except` 112 | 113 | 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. 114 | 115 | ### auth_totp_reuse 116 | 117 | * **syntax:** `auth_totp_reuse |` 118 | * **default:** `off` 119 | * **context:** `http`, `server`, `location`, `limit_except` 120 | 121 | Enables the reuse of a Time-based One-Time Password (TOTP) within a validity window. While this is non-standard behaviour per [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238), it provides a convenient manner to ensure a minimum window of validity for generated TOTP codes, even if the TOTP has already been presented to the validating system. 122 | 123 | ### auth_totp_skew 124 | 125 | * **syntax:** `auth_totp_skew ` 126 | * **default:** `1` 127 | * **context:** `http`, `server`, `location`, `limit_except` 128 | 129 | Specifies the number of time steps by which the time base between the issuing and validating TOTP systems. 130 | 131 | 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. 132 | 133 | 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. 134 | 135 | ### auth_totp_start 136 | 137 | * **syntax:** `auth_totp_start