{"id":15064662,"url":"https://github.com/sctg-development/nginx-ad-auth","last_synced_at":"2025-04-10T12:41:13.705Z","repository":{"id":257343474,"uuid":"850008447","full_name":"sctg-development/nginx-ad-auth","owner":"sctg-development","description":"A lightweight authentication server for Nginx mail proxy, enabling seamless user authentication against Active Directory via LDAP. Easily integrates with Nginx to secure email services by leveraging your existing AD infrastructure.","archived":false,"fork":false,"pushed_at":"2024-09-01T16:45:58.000Z","size":71,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T11:21:34.826Z","etag":null,"topics":["active-directory","nginx","nginx-mail-auth"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sctg-development.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2024-08-30T17:30:55.000Z","updated_at":"2025-03-06T10:25:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"2beb6b7a-3cc1-4748-a5b9-edadbcd79a24","html_url":"https://github.com/sctg-development/nginx-ad-auth","commit_stats":null,"previous_names":["sctg-development/nginx-ad-auth"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sctg-development%2Fnginx-ad-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sctg-development%2Fnginx-ad-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sctg-development%2Fnginx-ad-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sctg-development%2Fnginx-ad-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sctg-development","download_url":"https://codeload.github.com/sctg-development/nginx-ad-auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248217156,"owners_count":21066634,"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":["active-directory","nginx","nginx-mail-auth"],"created_at":"2024-09-25T00:24:01.594Z","updated_at":"2025-04-10T12:41:13.689Z","avatar_url":"https://github.com/sctg-development.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nginx-ad-auth\n\n`nginx-ad-auth` is a Go-based authentication service for the NGINX email proxy, allowing seamless authentication of users against Active Directory using LDAP. It integrates easily with NGINX to secure email services (IMAP, SMTP, POP3), leveraging existing AD infrastructures.\n\n## Features\n\n- **Easy Integration:** Connects with NGINX mail proxy for seamless user authentication.\n- **Supports Multiple Protocols:** IMAP, POP3, and SMTP protocols supported for full compatibility.\n- **Active Directory Authentication:** Authenticate users against AD using LDAP.\n- **Flexible Configuration:** Configure through command-line flags or environment variables.\n- **Lightweight:** Minimal dependencies, runs as a standalone service.\n\n## Table of Contents\n\n- [nginx-ad-auth](#nginx-ad-auth)\n  - [Features](#features)\n  - [Table of Contents](#table-of-contents)\n  - [TD;DR](#tddr)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n    - [Test](#test)\n  - [Usage](#usage)\n    - [Flags](#flags)\n    - [Environment Variables](#environment-variables)\n  - [Docker](#docker)\n  - [Kubernetes](#kubernetes)\n  - [Using the Helm Chart](#using-the-helm-chart)\n  - [Configuring NGINX as an Email Proxy](#configuring-nginx-as-an-email-proxy)\n  - [License](#license)\n    - [Key points of the AGPLv3](#key-points-of-the-agplv3)\n  - [Contributing](#contributing)\n  - [Support](#support)\n\n## TD;DR\n\nYou can run `nginx-ad-auth` using Docker in just a few steps:\n\n```bash\ndocker run -p 8080:8080 \\\n   -e NGINX_AUTH_LDAP_URI=\"ldap://your-ad-server\" \\\n   -e NGINX_AUTH_LDAP_BASE=\"dc=your,dc=domain\" \\\n   -e NGINX_AUTH_AD_DOMAIN=\"your-domain\" \\\n   -e NGINX_AUTH_MAIL_SERVER=\"your-mail-server\" \\\n   -e NGINX_AUTH_MAIL_SERVER_PORT=143 \\\n   sctg/nginx-ad-auth\n```\n\n## Prerequisites\n\n- Go 1.21 or later [(Go installation guide)](https://golang.org/doc/install)\n- Access to an Active Directory server\n- Docker installed for the Docker setup (optional).\n\n## Installation\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/yourusername/nginx-ad-auth.git\n   ```\n\n2. Change to the project directory:\n\n   ```bash\n   cd nginx-ad-auth\n   ```\n\n3. Build the program:\n\n   ```bash\n   go build -o nginx-ad-auth\n   ```\n\n### Test\n\nFor testing you can use the provided test file:\n\n```bash\n./nginx-ad-auth -ad-domain ADDOMAIN -ldap-base \"dc=ADDOMAIN,dc=WINDOWS\" -ldap-uri \"ldap://server.addomain.windows\" -mail-server 192.168.1.1 -mail-server-port 143 -port 8080\nVALIDUSER=\"myuser\" CORRECTPASSWORD=\"mypassword\" tests/test-nginx-ad-auth.sh\n```\n\n## Usage\n\nRun the program with the following command:\n\n```bash\n./nginx-ad-auth [flags]\n```\n\n### Flags\n\n- `--port`: Port to listen on (default: 8080)\n- `--ldap-uri`: LDAP URI\n- `--ldap-base`: LDAP base\n- `--ad-domain`: Active Directory domain\n- `--mail-server`: Mail server address\n- `--mail-server-port`: Mail server port\n- `--help`: Show help message\n\n### Environment Variables\n\nYou can also use environment variables instead of flags:\n\n- `NGINX_AUTH_PORT`\n- `NGINX_AUTH_LDAP_URI`\n- `NGINX_AUTH_LDAP_BASE`\n- `NGINX_AUTH_AD_DOMAIN`\n- `NGINX_AUTH_MAIL_SERVER`\n- `NGINX_AUTH_MAIL_SERVER_PORT`\n\n## Docker\n\nTo build and run the Docker image:\n\n1. (Optional) Build the image:\n\n   ```bash\n   docker build -t nginx-ad-auth .\n   ```\n\n2. Run the container:\n\n   ```bash\n   docker run -p 8080:8080 -e NGINX_AUTH_LDAP_URI=ldap://your-ad-server -e NGINX_AUTH_LDAP_BASE=\"dc=your,dc=domain\" -e NGINX_AUTH_AD_DOMAIN=your-domain -e NGINX_AUTH_MAIL_SERVER=\"your-mail-server\" -e NGINX_AUTH_MAIL_SERVER_PORT=143 sctg/nginx-ad-auth\n   ```\n\n## Kubernetes\n\nTo deploy on Kubernetes using Helm:\n\n## Using the Helm Chart\n\nTo deploy the `nginx-ad-auth` service using the provided Helm chart, follow these steps:\n\n1. First, ensure you have Helm installed on your local machine and configured to work with your Kubernetes cluster.\n\n2. Update the `values.yaml` file in the `helm/nginx-ad-auth` directory to match your environment. Pay special attention to the following fields:\n   - `image.repository`: Update this to your Docker registry if you've pushed a custom image.\n   - `env`: Update the environment variables to match your Active Directory and mail server configuration.\n\n3. From the root of the project, run:\n\n   ```bash\n   helm install nginx-ad-auth ./helm/nginx-ad-auth\n   ```\n\n4. To upgrade an existing deployment with new values:\n\n   ```bash\n   helm upgrade nginx-ad-auth ./helm/nginx-ad-auth\n   ```\n\n5. You can customize the installation by overriding values:\n\n   ```bash\n   helm install nginx-ad-auth ./helm/nginx-ad-auth --set replicaCount=3\n   ```\n\nRemember to configure your NGINX Ingress or other ingress controller to route traffic to the `nginx-ad-auth` service.\n\n## Configuring NGINX as an Email Proxy\n\nTo configure NGINX as an email proxy to a mail server hosted in a private network, you can use the following NGINX configuration:\n\n```nginx\nmail {\n    server_name mail.example.com;\n    auth_http localhost:8080/auth;\n\n    server {\n        listen 993 ssl;\n        protocol imap;\n        ssl_certificate /path/to/your/certificate.crt;\n        ssl_certificate_key /path/to/your/certificate.key;\n        imap_capabilities \"IMAP4rev1\" \"UIDPLUS\";\n    }\n}\n```\n\nThis configuration does the following:\n\n- Sets up NGINX to listen on port 993 for IMAPS connections.\n- Uses the `nginx-ad-auth` service running on `localhost:8080` for authentication.\n- Proxies authenticated connections to the internal mail server at 192.168.1.1:143.\n- Enables SSL for both the client connection and the proxy connection to the internal server.\n\nRemember to replace `/path/to/your/certificate.crt` and `/path/to/your/certificate.key` with the paths to your SSL certificate and key files. Also, ensure that the `auth_http` URL matches the location where your `nginx-ad-auth` service is running.\n\n## License\n\nThis project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).\n\n### Key points of the AGPLv3\n\n1. Source Code: You must make the complete source code available when you distribute the software.\n2. Modifications: If you modify the software, you must release your modifications under the AGPLv3 as well.\n3. Network Use: If you run a modified version of the software on a server and allow users to interact with it over a network, you must make the source code of your modified version available.\n4. No Additional Restrictions: You cannot impose any further restrictions on the recipients' exercise of the rights granted by the license.\n\nFor the full license text, see the [LICENSE](LICENSE.md) file in the project repository or visit [GNU AGPL v3.0](https://www.gnu.org/licenses/agpl-3.0.en.html).\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## Support\n\nIf you encounter any problems or have any questions, please open an issue in the GitHub repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsctg-development%2Fnginx-ad-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsctg-development%2Fnginx-ad-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsctg-development%2Fnginx-ad-auth/lists"}