{"id":13975498,"url":"https://github.com/61131/nginx-http-auth-totp","last_synced_at":"2026-05-04T05:04:35.069Z","repository":{"id":250966860,"uuid":"833960926","full_name":"61131/nginx-http-auth-totp","owner":"61131","description":"Time-based one-time password (TOTP) authentication for Nginx","archived":false,"fork":false,"pushed_at":"2025-12-09T20:30:48.000Z","size":78,"stargazers_count":18,"open_issues_count":2,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-06T07:41:48.530Z","etag":null,"topics":["c","nginx","totp"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/61131.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-26T06:08:09.000Z","updated_at":"2026-03-02T15:47:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"cdc0fe1e-6c67-49bd-90ee-0695f0e7917f","html_url":"https://github.com/61131/nginx-http-auth-totp","commit_stats":null,"previous_names":["61131/nginx-http-auth-totp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/61131/nginx-http-auth-totp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/61131%2Fnginx-http-auth-totp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/61131%2Fnginx-http-auth-totp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/61131%2Fnginx-http-auth-totp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/61131%2Fnginx-http-auth-totp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/61131","download_url":"https://codeload.github.com/61131/nginx-http-auth-totp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/61131%2Fnginx-http-auth-totp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32595208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","nginx","totp"],"created_at":"2024-08-09T01:01:03.612Z","updated_at":"2026-05-04T05:04:35.063Z","avatar_url":"https://github.com/61131.png","language":"C","funding_links":[],"categories":["Third Party Modules","Authentication"],"sub_categories":["C Modules"],"readme":"# nginx-http-auth-totp\n\nTime-based one-time password (TOTP) authentication for Nginx\n\nThe 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.\n\nThe nginx-http-auth-totp module provides TOTP authentication for a Nginx server.\n\n## Features\n\n* HTTP basic authentication using time-based one-time password (TOTP)\n* Cookie-based tracking of authenticated clients beyond TOTP validity window\n* Configurable secret, time reference, time step and truncation length for TOTP generation\n* Configurable time-skew for TOTP validation\n\n## Build\n\nTo build the nginx-http-auth-totp module from the Nginx source directory:\n\n```bash\n./configure --add-module=/path/to/nginx-http-auth-totp\nmake\nmake install\n```\n\n## Packages\n\nFor 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/):\n\n```bash\ndnf -y install https://extras.getpagespeed.com/release-latest.rpm \ndnf -y install nginx-module-auth-totp\n```\n\n## Configuration\n\n```nginx\nserver {\n    listen 80;\n\n    location /protected {\n        auth_totp_realm \"Protected\";\n        auth_totp_secret \"Secret\";\n        auth_totp_file /etc/nginx/totp.conf;\n        auth_totp_length 8;\n        auth_totp_reuse off;\n        auth_totp_skew 1;\n        auth_totp_step 1m;\n        auth_totp_cookie \"totp-session\";\n        auth_totp_expiry 1d;\n    }\n}\n```\n\nEnable the module by adding the following at the top of `/etc/nginx/nginx.conf`:\n\n```nginx\nload_module modules/ngx_http_auth_totp_module.so;\n```\n\n## Directives\n\n### auth_totp_cookie\n\n* **syntax:** `auth_totp_cookie \u003cname\u003e`\n* **default:** `totp`\n* **context:** `http`, `server`, `location`, `limit_except`\n\nSpecifies the name of the HTTP cookie to be used for tracking authenticated clients.\n\nAs 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. \n\n### auth_totp_expiry\n\n* **syntax:** `auth_totp_expiry \u003cinterval\u003e`\n* **default:** `0s`\n* **context:** `http`, `server`, `location`, `limit_except`\n\nSpecifies the expiry time for the HTTP cookie to be used for tracking authenticated clients.\n\nIf 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.\n\n### auth_totp_file\n\n* **syntax:** `auth_totp_file \u003cfilename\u003e`\n* **default:** -\n* **context:** `http`, `server`, `location`, `limit_except`\n\nSpecifies the file that contains usernames and shared secrets for Time-based One-Time Password (TOTP) authentication. \n\nThis configuration file has the format:\n\n    # comment\n    user1:secret1\n    user2:secret2\n    user3:secret3\n\n### auth_totp_length\n\n* **syntax:** `auth_totp_length \u003cnumber\u003e`\n* **default:** `6`\n* **context:** `http`, `server`, `location`, `limit_except`\n\nSpecifies the truncation length of the Time-based One-Time Password (TOTP) code. This truncation length may be between 1 and 8 digits inclusively.\n\nIf the supplied TOTP is of a different length to this value, the authentication request will fail.\n\n### auth_totp_realm\n\n* **syntax:** `auth_totp_realm \u003cstring\u003e|off`\n* **default:** `off`\n* **context:** `http`, `server`, `location`, `limit_except`\n\nEnables 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.\n\n### auth_totp_reuse\n\n* **syntax:** `auth_totp_reuse \u003con\u003e|\u003coff\u003e`\n* **default:** `off`\n* **context:**  `http`, `server`, `location`, `limit_except`\n\nEnables 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.\n\n### auth_totp_secret\n\n* **syntax:** `auth_totp_secret \u003cstring\u003e`\n* **default:** -\n* **context:** `http`, `server`, `location`, `limit_except`\n\nA server-side secret used when generating session cookies and then when validating session cookies. If an attacker knows this secret, they will be able to forge session cookies that grant access, so it is vital that it be difficult to guess.\n\n### auth_totp_skew\n\n* **syntax:** `auth_totp_skew \u003cnumber\u003e`\n* **default:** `1`\n* **context:** `http`, `server`, `location`, `limit_except`\n\nSpecifies the number of time steps by which the time base between the issuing and validating TOTP systems.\n\nDue 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.\n\nIt 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.\n\n### auth_totp_start\n\n* **syntax:** `auth_totp_start \u003ctime\u003e`\n* **default:** `0`\n* **context:** `http`, `server`, `location`, `limit_except`\n\nSpecifies the UNIX time from which to start counting time steps as part of Time-based One-Time Password (TOTP) algorithm operations.\n\nThe default value is 0, the UNIX epoch at 1970/01/01. \n\n### auth_totp_step\n\n* **syntax:** `auth_totp_step \u003cinterval\u003e`\n* **default:** `30s`\n* **context:** `http`, `server`, `location`, `limit_except`\n\nSpecifies the time step as part of Time-based One-Time Password (TOTP) algorithm operations.\n\n## References\n\n* [RFC 4226 HOTP: An HMAC-Based One-Time Password Algorithm](https://datatracker.ietf.org/doc/html/rfc4226)\n* [RFC 6238 TOTP: Time-Based One-Time Password Algorithm](https://datatracker.ietf.org/doc/html/rfc6238)\n* [RFC 7235 Hypertext Transfer Protocol (HTTP/1.1): Authentication](https://datatracker.ietf.org/doc/html/rfc7235)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F61131%2Fnginx-http-auth-totp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F61131%2Fnginx-http-auth-totp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F61131%2Fnginx-http-auth-totp/lists"}