{"id":28396139,"url":"https://github.com/orange-cyberdefense/reverse-proxy-auth","last_synced_at":"2025-10-30T07:01:52.539Z","repository":{"id":107085276,"uuid":"345711588","full_name":"Orange-Cyberdefense/reverse-proxy-auth","owner":"Orange-Cyberdefense","description":"A Nginx reverse proxy that authenticates users using their personal certificates. Includes everything to create and revoke those certificates, create the CA and even TLS certificates for websites.","archived":false,"fork":false,"pushed_at":"2021-03-08T18:18:45.000Z","size":87,"stargazers_count":28,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-31T10:24:59.923Z","etag":null,"topics":["authentication","docker","nginx","reverseproxy"],"latest_commit_sha":null,"homepage":"https://orangecyberdefense.com/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Orange-Cyberdefense.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}},"created_at":"2021-03-08T15:59:03.000Z","updated_at":"2025-05-16T14:06:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"9458a687-788b-435d-ac4d-4240a662ff8f","html_url":"https://github.com/Orange-Cyberdefense/reverse-proxy-auth","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Orange-Cyberdefense/reverse-proxy-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-Cyberdefense%2Freverse-proxy-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-Cyberdefense%2Freverse-proxy-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-Cyberdefense%2Freverse-proxy-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-Cyberdefense%2Freverse-proxy-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Orange-Cyberdefense","download_url":"https://codeload.github.com/Orange-Cyberdefense/reverse-proxy-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-Cyberdefense%2Freverse-proxy-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271746776,"owners_count":24813583,"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","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"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":["authentication","docker","nginx","reverseproxy"],"created_at":"2025-05-31T21:36:59.908Z","updated_at":"2025-10-30T07:01:47.272Z","avatar_url":"https://github.com/Orange-Cyberdefense.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Authenticating reverse proxy on docker using client certificate authentication\n\n## What is Reverse Proxy Auth\n**Nginx** can easily be configured to act as a **reverse proxy** in order to externaly expose on the same point different web services hosted internaly.\n\nTo restrict the access to the content hosted behind the proxy, it is possible to require the users to provide a **personal certificate**. Using this mechanism, you ensure only **trusted users are allowed** to access protected services.\n\nThis project provides all the tools needed to easily setup and configure the reverse proxy and the client certificates.\n\n\n\n## 1. Preparation\nThis project requires Docker and Docker-compose to be installed.   \nThe docker-compose.yml file describes the architecture of the project.\nAlternatively, you can use the provided files on a regular Nginx server to use the same mechanism without Docker.\n\n**Files:**\nThe `nginx/nginx.conf` file is configured to run Nginx using default configuration.\n\nThe `nginx/fastcgi.conf` file is the default configuration for FastCGI.\n\nThe `nginx/proxy.conf` file contains the parameters to optimize the proxy role of Nginx.\n\nThe `nginx/ssl.conf` file is configured to use strong encryption protocols and ciphers. It also add security mechanisms through headers.\n\nThe `nginx/conf.d/site.example.conf` is configured to listen on ports **80** and **443** and requires clients to use a certificate to authenticate themself. If a client is successfully authenticated, it is redirected to the webapp docker machine.\n\n\n#### Architecture:\nclient [certificate] -\u003e front [CA + proxy] -\u003e webapp [website]\n\n\n### 1.1 Server initialization\n- Go to `nginx/ssl` : `$ cd nginx/ssl`\n- Edit the `ca/ca.cnf` file to reflect your organization values in the `[ ca_dn ]` part.\n  - Create the certificate authority (CA): `$ ./create_ca.sh`. The file `create_ca.sh` should then by set to mode 000 in order to avoid erasing the issued CA.\n- Edit the `tls/tls.tpl` file to reflect your organization subdomain values in the `[ default ]` part.\n  - Create a certificate for the front website `$ ./create_tls.sh site.example`. The DNS name of the website can differ but you have to edit the file generated in `nginx/conf.d` to match the actual name.\n Alternatively, you can buy a certificate from a recognized issuer or get one for free using Let's Encrypt.\n- Edit the `client/client.tpl` file to reflect organization values in the `[ client_dn ]` part. You don't need to change the email address, this will be done by the script.\n  - Create a client `$ ./create_client.sh firstname lastname client@site.example`\nThe newly created certificate is located in `clients/p12` and protected by a password added to the `clients/passwords.txt` file.   \n\n\n- Go to `nginx/conf.d` : `$ cd ../conf.d`\n- Open the `site.example.conf` to adjust the following parameters :\n  - Change the `site.example` value after `server_name` to match your website's URL (2 times).\n  - Change the values after `ssl_certificate` and `ssl_certificate_key` to match your website's certificate.\n  - Change the `http://protectedapp;` value after `proxy_pass` to match your docker application's name or its address (domain name or IP).\n  - **Optional**: change the log's name after `access_log`.\n- **Optional**: change the file's name, as long as its extension is \".conf\".\n\n### 1.2 Client side initialization\nIn your browser, to go the *settings* -\u003e *certificate* part. It can have different names, such as \"manage certificates\" or \"view certificates\".   \n\nThis part has 4 sections: \"Your certificates\", \"People\", \"Servers\" and \"Authorities\".   \n\nIn the \"Your certificates\", click \"import\" and select the .p12 file issued for you. The browser asks for a password which has been assigned during the certificate creation.\n\n**Optional**: In the \"Authorities\", import the \"ca.crt\" certificate. Check \"Trust this CA to identify websites\". You don't have to do this if your website certificate has been issued by a recognized issuer.\n\nThen, validate/exit the certificate manager part.\n\n![alt text](browser_certs.png)\n\n### 1.3 Testing the service\n- In the root directory, where the \"docker-compose.yml\" is located, run `$ docker-compose up`.   \n- Edit the `/etc/hosts` file using sudo `$ sudo nano /etc/root`. Add the following new line: `127.0.0.1\tsite.example` or whatever name you chose for your website.\n- Open you browser, go to https://site.example. The browser should ask for permissions to use your user certificate. Validate the request.\n\n![alt text](browser_asks.png)\n\nIf your browser raises a TLS warning, ignore it and \"accept the risk\".\n\nIf everything went well, you should see a page displaying \"NGINX\" and various info such as \"Server address\" and \"Server name\".\n\n![alt text](site_accessed.png)\n\n\n### 1.4 Revocation\nTo revoke a client, run `$ ./revoke_client firstname lastname` and check the certificate has been moved to `clients/revoked`.\n\nRevoked files are visible by possessing a `200122103242Z,cessationOfOperation` string in the 3rd column of `nginx/ssl/ca/ca.db`.\n\nUsers possessing revoked certificated can not authenticate themself anymore on the proxy.\n\n\n## 3. Troubleshoot\n### 3.1 Firefox does not ask for the certificate\nGo to `about:config` and set `security.osclientcerts.autoload` to `true`.\n\n### 3.2 The browser does not accept the password\nThe password may be wrong. Check the associated password in `passwords.txt` or regenerate a certificate.\n\n### 3.3 I get an error 400 \"No required SSL certificate was sent\"\nYou have not imported your certificate in your browser or the domain linked to the certificate is wrong.\n\n### 3.4 I can no longer access the website using my certificate\nYour certificate may be revoked. Check the `revoked` folder.\n\n### 3.5 That does not work\nHave you tried rebooting ?\n\nCredits:\n- Docker: [https://www.docker.com/](https://www.docker.com/)\n- Docker-compose: [https://docs.docker.com/compose/](https://docs.docker.com/compose/)\n- Nginx: [https://www.nginx.com/](https://www.nginx.com/)\n- OpenSSL [https://www.openssl.org/](https://www.openssl.org/)\n\nComing later:\n- LDAP based Two Factors Authentication\n- Web interface to manage the PKI\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forange-cyberdefense%2Freverse-proxy-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forange-cyberdefense%2Freverse-proxy-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forange-cyberdefense%2Freverse-proxy-auth/lists"}