Skip to content

Commit 4f708fa

Browse files
Youssef-HarbyYoussef-Harby
committed
update README.md
1 parent ee9354e commit 4f708fa

4 files changed

+203
-44
lines changed

‎README.md

+203-44
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,241 @@
1-
# pygeoapi-auth
1+
# pygeoapi-auth 🌍🔒
22

3-
<p align="center" style="margin:50px">
4-
<img src="docs/images/pygeoapi-auth.png"/>
3+
<p align="center">
4+
<img src="docs/images/pygeoapi-auth.png" alt="pygeoapi-auth logo"/>
55
</p>
66

7-
### Providing authentication and authorization for the vanilla pygeoapi. It does this by placing the `pygeoapi` behind a `Caddy` reverse proxy, which handles forward authentication and authorization with `Authelia`.
7+
> Secure your pygeoapi deployment with enterprise-grade authentication and authorization
88
9-
This project is a Dockerized application, and Docker Compose is used for the orchestration of the multiple services. The application's configuration is found in the `docker-compose.yml` and `Caddyfile` files.
9+
This project provides a complete authentication and authorization solution for pygeoapi, supporting multiple deployment scenarios with Caddy or Nginx as reverse proxies, and flexible authentication backends including file-based and LDAP.
1010

11-
## Pre-requisites
11+
## 🌟 Features
1212

13-
- Docker and Docker Compose installed on your machine.
14-
- Permission to edit `/etc/hosts` file.
13+
- 🔐 Enterprise-grade authentication and authorization with Authelia
14+
- 🚀 Multiple reverse proxy options (Caddy/Nginx)
15+
- 📁 File-based or LDAP user management
16+
- 🔄 Hot-reload configuration support
17+
- 🎯 Granular access control based on user groups
18+
- 🌐 OpenAPI specification with security schemes
19+
- 🗺️ QGIS integration support
1520

16-
## Steps for Deployment
21+
## 🛠️ Prerequisites
1722

18-
1. **Edit `/etc/hosts` File:**
19-
Add the following entries to your `/etc/hosts` file:
23+
- Docker and Docker Compose
24+
- Permission to edit `/etc/hosts` file (for local development)
25+
- Domain with DNS A records (for production)
26+
- SSL certificates (self-signed for development, Let's Encrypt for production)
2027

28+
## 🚀 Deployment Guide
29+
30+
### Local Development Setup
31+
32+
#### 1. Configure Local DNS
33+
Add the following entries to your `/etc/hosts` file:
2134
```bash
2235
127.0.0.1 pygeoapi.local
2336
127.0.0.1 app.pygeoapi.local
37+
127.0.0.1 lldap.pygeoapi.local # Required for LLDAP scenarios
38+
```
39+
40+
#### 2. Choose Your Development Stack
41+
42+
##### A. Caddy with File-based Authentication
43+
```bash
44+
docker compose -f docker-compose-caddy.yml up -d
45+
```
46+
- Access the API at: https://app.pygeoapi.local/api
47+
- Default users:
48+
- yharby/cartologic (cartologic group)
49+
- francbartoli/francbartoli (geobeyond group)
50+
51+
##### B. Caddy with LLDAP Integration
52+
```bash
53+
docker compose -f docker-compose-caddy-lldap.yml up -d
54+
```
55+
1. Access LLDAP admin interface: https://lldap.pygeoapi.local
56+
2. Login with default credentials:
57+
- Username: admin
58+
- Password: super_strong_ldap_password
59+
3. Create required groups:
60+
- Create group: cartologic
61+
- Create group: geobeyond
62+
4. Create a test user and assign to either group
63+
5. Access the API at: https://app.pygeoapi.local/api
64+
65+
##### C. Nginx with File-based Authentication
66+
1. Generate development SSL certificates:
67+
```bash
68+
cd nginx/certs
69+
openssl genpkey -algorithm RSA -out pygeoapi.key
70+
openssl req -new -key pygeoapi.key -out pygeoapi.csr -subj "/C=EG/ST=Cairo/L=Cairo/O=Pygeoapi/OU=IT Department/CN=*.pygeoapi.local"
71+
openssl x509 -req -days 365 -in pygeoapi.csr -signkey pygeoapi.key -out pygeoapi.crt
72+
cd ../..
73+
```
74+
2. Start services:
75+
```bash
76+
docker compose -f docker-compose-nginx.yml up -d
77+
```
78+
79+
##### D. Nginx with LLDAP Integration
80+
1. Generate SSL certificates (if not done in step C)
81+
2. Start services:
82+
```bash
83+
docker compose -f docker-compose-nginx-lldap.yml up -d
84+
```
85+
3. Follow LLDAP setup steps from section B
86+
87+
### Production Deployment
88+
89+
#### 1. Domain and DNS Setup
90+
1. Register a domain (e.g., pygeoapi-example.com)
91+
2. Create A records for your subdomains:
92+
- app.pygeoapi-example.com
93+
- auth.pygeoapi-example.com
94+
- lldap.pygeoapi-example.com (if using LLDAP)
95+
96+
> **Important**: After setting up your domain, you'll need to modify the domain names in the configuration files of your chosen stack:
97+
> - For Caddy: Update domains in `caddy/Caddyfile` or `caddy/lldap.Caddyfile`
98+
> - For Nginx: Update server names in `nginx/site-confs/default.conf` or `nginx/site-confs-lldap/default.conf`
99+
> - Update domain in Authelia configuration: `authelia-*/configuration.yml`
100+
> - If using LLDAP, update LLDAP environment variables and base DN in the docker-compose file
101+
102+
#### 2. SSL Certificates
103+
Choose one option:
104+
105+
##### Option A: Let's Encrypt (Recommended)
106+
1. Install certbot:
107+
```bash
108+
sudo apt install certbot
109+
```
110+
2. Obtain certificates:
111+
```bash
112+
sudo certbot certonly --standalone -d app.pygeoapi-example.com -d auth.pygeoapi-example.com -d lldap.pygeoapi-example.com
113+
```
114+
115+
##### Option B: Custom SSL Certificate
116+
Use your organization's SSL certificates and place them in the appropriate directory:
117+
- For Nginx: `nginx/certs/`
118+
- For Caddy: Automatic HTTPS is handled by Caddy
119+
120+
#### 3. Choose Production Stack
121+
122+
##### A. Caddy (Recommended for Simplicity)
123+
```bash
124+
docker compose -f docker-compose-caddy.yml up -d # File-based auth
125+
# or
126+
docker compose -f docker-compose-caddy-lldap.yml up -d # LLDAP
24127
```
25128

26-
This step is necessary to resolve the local domains used in the Caddyfile or Nginx.
129+
##### B. Nginx (More Configuration Control)
130+
```bash
131+
docker compose -f docker-compose-nginx.yml up -d # File-based auth
132+
# or
133+
docker compose -f docker-compose-nginx-lldap.yml up -d # LLDAP
134+
```
135+
136+
#### 4. Security Recommendations
137+
- Use strong passwords for all services
138+
- Enable firewall rules
139+
- Set up monitoring and logging
140+
- Regular security updates
141+
- Configure rate limiting
142+
- Use secure headers
143+
144+
## 🔒 Access Control
145+
146+
### Protected Endpoints
147+
- `/api/collections/obs`: Requires cartologic group membership
148+
- `/api/collections/lakes`: Requires geobeyond group membership
149+
- `/api`: Accessible to all authenticated users
150+
151+
### OpenAPI Security
152+
The OpenAPI specification is automatically injected with security schemes using [pygeoapi-auth](https://github.com/geopython/pygeoapi-auth/), which enables:
153+
- Automatic security scheme injection into OpenAPI specification
154+
- Swagger UI authentication support with Basic Auth
155+
- API documentation with security requirements
156+
157+
The authentication injection is handled automatically by the entrypoint script using pygeoapi-auth's CLI:
158+
```bash
159+
pygeoapi-auth openapi inject-auth ${PYGEOAPI_OPENAPI} authelia ${PYGEOAPI_HOME}/authelia-config/configuration.yml --api-prefix api --output-file ${PYGEOAPI_OPENAPI}
160+
```
161+
![Swagger Page With Authentication of pygeoapi](docs/images/pygeoapi-openapi-auth-swagger.png)
27162

28-
2. **Start the Services :**
163+
This ensures that all API endpoints are properly documented with their security requirements and the OpenAPI specification reflects the actual authentication setup.
29164

30-
- ### Using Caddy
165+
## 📋 Project Roadmap
31166

32-
1. **Run the Services with Docker**:
33-
From the root directory of the project, start all the services using Docker Compose with the following command:
167+
### Current Features
168+
- ✅ Basic Authentication support
169+
- ✅ Authelia integration
170+
- ✅ Multiple reverse proxy options (Caddy/Nginx)
171+
- ✅ LLDAP integration
172+
- ✅ OpenAPI specification injection
173+
- ✅ Group-based authorization
34174

35-
```bash
36-
docker-compose up -d
37-
```
175+
### Planned Features
176+
1. Authentication Enhancements
177+
- 🔄 OAuth2 support
178+
- 🔄 OpenID Connect support
179+
- 🔄 Multi-factor authentication (MFA)
38180

39-
- ### Using Nginx
181+
2. Integration Expansions
182+
- 🔄 Additional identity providers
183+
- 🔄 More reverse proxy options (eg. traefik)
184+
- 🔄 Enhanced QGIS authentication methods
185+
- 🔄 ArcGIS Pro authentication methods
186+
- 🔄 Kubernetes deployment
40187

41-
1. **Generate Self-Signed Certificates**:
188+
3. Developer Experience
189+
- 🔄 Cookiecutter CLI tool
190+
- 🔄 Better documentation
191+
- 🔄 Example implementations
192+
- 🔄 Testing utilities
42193

43-
> [!IMPORTANT]
44-
> You must generate self-signed certificates for the local domains before starting the services.
194+
Want to contribute? Check our [issues](https://github.com/cartologic/pygeoapi-auth-deployment/issues) or submit a pull request!
45195

46-
Follow the provided instructions in [README.md](nginx/README.md) to generate self-signed certificates for the local domains or use your own certificates.
196+
## 🗺️ QGIS Integration
47197

48-
2. **Run the Services with Docker**:
49-
From the root directory of the project, start all the services using Docker Compose with the following command:
198+
### Basic Authentication Setup
199+
1. Open QGIS
50200

51-
```bash
52-
docker compose -f "docker-compose-nginx.yml" up -d
53-
```
201+
2. Add new WFS / OGC API - Features connection:
202+
- URL: https://app.your-domain.com/api (or https://app.pygeoapi.local/api for local)
203+
- Authentication: Basic (or create an authentication configuration)
204+
- Username: (your username)
205+
- Password: (your password)
206+
207+
![QGIS WFS Connection Setup](docs/images/qgis-integration-pygeoapi-auth-1.png)
54208

55-
This command pulls the necessary Docker images and starts the services defined in docker-compose.yml (for Caddy) or docker-compose-nginx.yml (for Nginx).
209+
3. Enable "Save Username" and "Save Password" if desired
210+
211+
![QGIS Authentication Configuration](docs/images/qgis-integration-pygeoapi-auth-2.png)
56212

57-
## Testing Scenarios
213+
4. Test connection
58214

59-
For testing the deployment, you can use the following users and endpoints.
215+
### Troubleshooting QGIS Connection
216+
- For local development: Add SSL certificate exception in QGIS
217+
- For production: Ensure valid SSL certificate
218+
- Verify user has access to desired collections
219+
- Check network connectivity to pygeoapi server
60220

61-
Users:
221+
## 🤝 Contributing
62222

63-
- User 1: yharby, Password: cartologic
64-
- User 2: francbartoli, Password: francbartoli
223+
Contributions are welcome! Please feel free to submit a Pull Request.
65224

66-
Endpoints:
225+
## 💡 Credits
67226

68-
- Endpoint 1: https://app.pygeoapi.local/api/collections/obs
227+
This project is inspired by [fastgeoapi](https://github.com/geobeyond/fastgeoapi) and builds upon the excellent work of the pygeoapi community.
69228

70-
Accessible by: yharby
229+
## Bugs and Issues
71230

72-
- Endpoint 2: https://app.pygeoapi.local/api/collections/lakes
231+
All bugs, enhancements and issues are managed on [GitHub](https://github.com/cartologic/pygeoapi-auth-deployment/issues).
73232

74-
Accessible by: francbartoli
233+
## Contact
75234

76-
- Endpoint 3: https://app.pygeoapi.local/api
235+
* [Tom Kralidis](https://github.com/tomkralidis)
236+
* [Youssef Harby](https://github.com/Youssef-Harby)
77237

78-
Accessible by: yharby and francbartoli
79238

80-
Please note that the password and user groups have been hashed for security reasons. The hashed passwords provided in the users_database.yml file are `cartologic` for `yharby` and `francbartoli` for `francbartoli`.
239+
## 📝 License
81240

82-
This project is inspired by the [fastgeoapi](https://github.com/geobeyond/fastgeoapi)
241+
This project is licensed under the MIT License - see the LICENSE file for details.

‎docs/images/pygeoapi-openapi-auth-swagger.png

131 KB
Loading

‎docs/images/qgis-integration-pygeoapi-auth-1.png

306 KB
Loading

‎docs/images/qgis-integration-pygeoapi-auth-2.png

349 KB
Loading

0 commit comments

Comments
 (0)