{"id":13639580,"url":"https://github.com/ViRb3/authelia-basic-2fa","last_synced_at":"2025-04-19T22:33:06.383Z","repository":{"id":38451900,"uuid":"236207493","full_name":"ViRb3/authelia-basic-2fa","owner":"ViRb3","description":"🗝 Use Authelia 2FA through only standard basic auth","archived":true,"fork":false,"pushed_at":"2024-06-13T18:19:19.000Z","size":270,"stargazers_count":25,"open_issues_count":13,"forks_count":4,"subscribers_count":3,"default_branch":"v2","last_synced_at":"2024-08-03T01:15:04.133Z","etag":null,"topics":["2fa","auth","authelia","authentication","basic","nginx","proxy","reverse-proxy","totp","two-factor-authentication"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ViRb3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2020-01-25T17:56:31.000Z","updated_at":"2024-06-16T13:05:34.000Z","dependencies_parsed_at":"2024-05-05T03:31:42.769Z","dependency_job_id":null,"html_url":"https://github.com/ViRb3/authelia-basic-2fa","commit_stats":null,"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViRb3%2Fauthelia-basic-2fa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViRb3%2Fauthelia-basic-2fa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViRb3%2Fauthelia-basic-2fa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViRb3%2Fauthelia-basic-2fa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ViRb3","download_url":"https://codeload.github.com/ViRb3/authelia-basic-2fa/tar.gz/refs/heads/v2","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223810553,"owners_count":17206787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["2fa","auth","authelia","authentication","basic","nginx","proxy","reverse-proxy","totp","two-factor-authentication"],"created_at":"2024-08-02T01:01:02.293Z","updated_at":"2024-11-09T09:31:13.858Z","avatar_url":"https://github.com/ViRb3.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Authelia Basic Auth 2FA\n\n\u003e Use Authelia 2-factor authentication through only standard basic auth\n\n## Introduction\n\nThis project allows you to use [Authelia](https://github.com/authelia/authelia)'s 2FA through only [basic auth](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) and a\ncustom credentials format described [below](#format). This allows you to use 2FA on clients and scenarios\nthat demand basic auth, e.g. [webdav](https://en.wikipedia.org/wiki/WebDAV) network streaming.\n\n## Technical details\n\n2FA is achieved through basic auth by placing a reverse proxy (this project) before every authentication attempt with Authelia. Your requests will look like this:\n\n```\nYou ---\u003e nginx (or other reverse proxy) ---\u003e this reverse proxy --\u003e Authelia\n```\n\nThis proxy will clone the client's request headers and cookies based on a whitelist, and use them to negotiate authentication with Authelia on the client's behalf.\n\nThe proxy will first execute a sub-request to Authelia's `verify` endpoint to check if the client has a valid session cookie or authorization (e.g. basic auth). If that succeeds, code `2xx` is returned to the client directly.\n\nIf that fails, the proxy will attempt to detect if the special credentials format is being used. If yes, it will decode the credentials (which include the TOTP) and execute standard Authelia 2FA TOTP authentication. The proxy will then verify the newly obtained session, and, if valid, return the session cookie to the client through a `Set-Cookie` header, along with a status code `2xx`.\n\nIn all other cases, including when the client does not use the special credentials format or the format is invalid, this proxy will return a `non-2xx` code.\n\n## Format\n\nThe custom format combines the password and TOTP into the basic auth password field. Example:\n\n### Original credentials\n\n- Username: `john`\n- Password: `secret`\n- TOTP: `123456`\n\n### New credentials\n\n- Username: `john`\n- Password: `secret123456`\n\n## Requirements\n\n- [Nginx](https://www.nginx.com/) (or any other reverse proxy)\n- [Authelia](https://github.com/authelia/authelia)\n\n## Installation\n\nCheck out the [Docker guide](docker). If you do not use Docker, you can still extract the configuration and use it directly.\n\nNote that the endpoint for `authelia-basic-2fa` is just the root `/`, not `/api/verify` like Authelia itself.\n\n## Usage\n\nRun with argument `-help`:\n\n```bash\n-debug\n    Debug logging\n-ip string\n    Listening ip (default \"0.0.0.0\")\n-port int\n    Listening port (default 8081)\n-url string\n    Authelia URL to use for authentication (default \"http://authelia:9091\")\n```\n\n## :warning: Security notes\n\n- Make sure you are setting all reverse proxy headers from [whitelists.go](util/whitelists.go) in your nginx configuration, as shown in [authelia-proxy.conf](docker/nginx/data/authelia-proxy.conf). This project will pass all the headers listed above from the client to Authelia, allowing an attacker to spoof them if nginx is not present.\n\n## Other notes\n\n- Make sure `Set-Cookie` headers can reach the client through `auth_request` or the client will always create a new session and lose access after the TOTP expires. Check `auth_request_set` in [auth.conf](docker/nginx/data/auth.conf)\n- Make sure Authelia is aware of the real client IP or you may lock out your server on bruteforce attempts. Check `set_real_ip_from` in [authelia-proxy.conf](docker/nginx/data/authelia-proxy.conf)\n- Your client (e.g. [VLC Player](https://www.videolan.org/vlc/)) must support cookies and use the session cookie on subsequent requests, since the basic auth password will become invalid after the TOTP expires\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FViRb3%2Fauthelia-basic-2fa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FViRb3%2Fauthelia-basic-2fa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FViRb3%2Fauthelia-basic-2fa/lists"}