Initialisation depot
This commit is contained in:
Serge NOEL
285
arti-api/auth-service/README.md
Normal file
285
arti-api/auth-service/README.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# Authentication Service with Active Directory Integration
|
||||
|
||||
This authentication service provides JWT-based authentication with Active Directory integration and Traefik ForwardAuth support for Kubernetes environments.
|
||||
|
||||
## Features
|
||||
|
||||
- 🔐 **Active Directory Authentication**: Validates credentials against your AD server
|
||||
- 🎫 **JWT Tokens**: Secure token-based authentication with configurable expiration
|
||||
- 🍪 **Cookie & Local Storage**: Tokens stored securely in HTTP-only cookies and locally
|
||||
- 🚀 **Traefik Integration**: ForwardAuth middleware for seamless Kubernetes access control
|
||||
- 📱 **Responsive UI**: Clean, modern login interface
|
||||
- 🔒 **Security Headers**: Proper CORS, security headers, and token validation
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ User Browser │───▶│ Auth Service │───▶│ Active Directory│
|
||||
│ │ │ │ │ │
|
||||
│ 1. Login Form │ │ 2. Validate AD │ │ 3. LDAP Auth │
|
||||
│ 4. Store Token │◀───│ Create JWT │ │ │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
│ │
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌──────────────────┐
|
||||
│ Protected API │◀───│ Traefik Forward │
|
||||
│ │ │ Auth Middleware │
|
||||
│ 5. Access with │ │ 6. Validate JWT │
|
||||
│ JWT Token │ │ │
|
||||
└─────────────────┘ └──────────────────┘
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
To build image, let's drone io work! As we use drone.io simply push git repository
|
||||
|
||||
### 1. Configure Active Directory
|
||||
|
||||
Update the `values.yaml` file with your AD configuration:
|
||||
|
||||
```yaml
|
||||
authService:
|
||||
activeDirectory:
|
||||
server: "ldap://your-ad-server.yourdomain.com"
|
||||
baseDN: "DC=yourdomain,DC=com"
|
||||
userSearchBase: "CN=Users,DC=yourdomain,DC=com"
|
||||
bindUser: "CN=ServiceAccount,CN=Users,DC=yourdomain,DC=com"
|
||||
bindPassword: "your-service-account-password"
|
||||
```
|
||||
|
||||
### 3. Configure Traefik ForwardAuth
|
||||
|
||||
The service automatically creates a ForwardAuth middleware that:
|
||||
|
||||
```yaml
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: auth-forward
|
||||
spec:
|
||||
forwardAuth:
|
||||
address: http://auth-service:8080/auth/verify
|
||||
authResponseHeaders:
|
||||
- "X-Auth-User"
|
||||
- "X-Auth-Email"
|
||||
- "X-Auth-Groups"
|
||||
- "X-Auth-Display-Name"
|
||||
```
|
||||
|
||||
### 4. Protect Your Services
|
||||
|
||||
Add the ForwardAuth middleware to any IngressRoute:
|
||||
|
||||
```yaml
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: IngressRoute
|
||||
metadata:
|
||||
name: protected-service
|
||||
spec:
|
||||
routes:
|
||||
- match: Host(`api.yourdomain.com`)
|
||||
kind: Rule
|
||||
services:
|
||||
- name: your-api-service
|
||||
port: 8000
|
||||
middlewares:
|
||||
- name: auth-forward # This protects the entire service
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
1. **User visits protected resource** → Traefik ForwardAuth redirects to login
|
||||
2. **User enters AD credentials** → Service validates against Active Directory
|
||||
3. **JWT token created** → Stored in HTTP-only cookie + localStorage
|
||||
4. **Subsequent requests** → Traefik validates JWT via ForwardAuth
|
||||
5. **Access granted** → User headers passed to backend service
|
||||
|
||||
### Token Storage
|
||||
|
||||
The system uses a dual-storage approach:
|
||||
|
||||
- **HTTP-only Cookie**: Secure, automatic transmission, protected from XSS
|
||||
- **localStorage**: Available to JavaScript for SPA applications
|
||||
|
||||
### Security Features
|
||||
|
||||
- ✅ **LDAP over TLS** support for secure AD communication
|
||||
- ✅ **JWT token expiration** with configurable timeouts
|
||||
- ✅ **HTTP-only cookies** prevent XSS token theft
|
||||
- ✅ **Secure headers** for production deployment
|
||||
- ✅ **CORS protection** with configurable origins
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Authentication Endpoints
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/` | GET | Login page (HTML) |
|
||||
| `/dashboard` | GET | Dashboard page (HTML) |
|
||||
| `/auth/login` | POST | Authenticate user |
|
||||
| `/auth/verify` | POST | Verify JWT token (ForwardAuth) |
|
||||
| `/auth/logout` | GET | Logout user |
|
||||
| `/auth/user` | GET | Get current user info |
|
||||
| `/health` | GET | Health check |
|
||||
|
||||
### ForwardAuth Integration
|
||||
|
||||
When Traefik calls `/auth/verify`, the service:
|
||||
|
||||
1. **Checks for token** in Authorization header or cookies
|
||||
2. **Validates JWT** signature and expiration
|
||||
3. **Returns user headers** for backend services:
|
||||
- `X-Auth-User`: Username
|
||||
- `X-Auth-Email`: User email
|
||||
- `X-Auth-Groups`: AD group memberships
|
||||
- `X-Auth-Display-Name`: User's display name
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `JWT_SECRET` | Secret key for JWT signing | (required) |
|
||||
| `TOKEN_EXPIRE_HOURS` | Token expiration in hours | 8 |
|
||||
| `AD_SERVER` | LDAP server URL | (required) |
|
||||
| `AD_BASE_DN` | Base DN for AD | (required) |
|
||||
| `AD_USER_SEARCH_BASE` | User search base | (required) |
|
||||
| `AD_BIND_USER` | Service account for LDAP | (optional) |
|
||||
| `AD_BIND_PASSWORD` | Service account password | (optional) |
|
||||
|
||||
### Kubernetes Secrets
|
||||
|
||||
Create the required secrets:
|
||||
|
||||
```bash
|
||||
kubectl create secret generic auth-secrets \
|
||||
--from-literal=jwt-secret="your-super-secret-key" \
|
||||
--from-literal=ad-bind-user="CN=ServiceAccount,CN=Users,DC=yourdomain,DC=com" \
|
||||
--from-literal=ad-bind-password="your-service-password"
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Custom Group-Based Access
|
||||
|
||||
The service passes AD group memberships in the `X-Auth-Groups` header. You can use this in your backend services:
|
||||
|
||||
```python
|
||||
# In your FastAPI backend
|
||||
from fastapi import Header
|
||||
|
||||
def check_admin_access(x_auth_groups: str = Header(None)):
|
||||
groups = x_auth_groups.split(',') if x_auth_groups else []
|
||||
if 'CN=Admins,CN=Groups,DC=yourdomain,DC=com' not in groups:
|
||||
raise HTTPException(status_code=403, detail="Admin access required")
|
||||
```
|
||||
|
||||
### Multiple Protection Levels
|
||||
|
||||
You can create different ForwardAuth middlewares for different access levels:
|
||||
|
||||
```yaml
|
||||
# Admin-only middleware
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: admin-auth
|
||||
spec:
|
||||
forwardAuth:
|
||||
address: http://auth-service:8080/auth/verify-admin
|
||||
authResponseHeaders:
|
||||
- "X-Auth-User"
|
||||
- "X-Auth-Groups"
|
||||
```
|
||||
|
||||
### Token Refresh
|
||||
|
||||
The service automatically handles token refresh. Configure shorter expiration times and implement refresh logic in your frontend:
|
||||
|
||||
```javascript
|
||||
// Check token expiration
|
||||
const token = localStorage.getItem('auth_token');
|
||||
const payload = JSON.parse(atob(token.split('.')[1]));
|
||||
const expiry = new Date(payload.exp * 1000);
|
||||
|
||||
if (expiry < new Date()) {
|
||||
// Redirect to login for refresh
|
||||
window.location.href = '/auth/login';
|
||||
}
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Health Checks
|
||||
|
||||
The service includes health check endpoints:
|
||||
|
||||
```bash
|
||||
curl http://auth-service:8080/health
|
||||
```
|
||||
|
||||
### Logging
|
||||
|
||||
The service logs authentication attempts and failures:
|
||||
|
||||
```
|
||||
INFO: Successfully authenticated user: john.doe
|
||||
ERROR: Authentication failed for user: invalid.user
|
||||
ERROR: LDAP connection failed: timeout
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Use HTTPS**: Always deploy with TLS certificates
|
||||
2. **Secure JWT Secret**: Use a strong, unique JWT secret
|
||||
3. **Network Security**: Restrict access to AD servers
|
||||
4. **Token Expiration**: Use reasonable token expiration times
|
||||
5. **Service Account**: Use a dedicated AD service account with minimal permissions
|
||||
6. **Audit Logs**: Monitor authentication logs for suspicious activity
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **LDAP Connection Failed**
|
||||
- Check AD server connectivity
|
||||
- Verify LDAP URL format
|
||||
- Check firewall rules
|
||||
|
||||
2. **Authentication Failed**
|
||||
- Verify AD credentials
|
||||
- Check user search base DN
|
||||
- Confirm user exists in specified OU
|
||||
|
||||
3. **ForwardAuth Not Working**
|
||||
- Verify Traefik middleware configuration
|
||||
- Check service connectivity
|
||||
- Review Traefik logs
|
||||
|
||||
4. **Token Issues**
|
||||
- Verify JWT secret consistency
|
||||
- Check token expiration
|
||||
- Validate cookie settings
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging by setting log level:
|
||||
|
||||
```yaml
|
||||
env:
|
||||
- name: LOG_LEVEL
|
||||
value: "DEBUG"
|
||||
```
|
||||
|
||||
This will provide detailed authentication flow logs.
|
||||
|
||||
# Trigger build with Jsonnet
|
||||
# Webhook test mer. 01 oct. 2025 17:11:01 CEST
|
||||
# DNS fix test mer. 01 oct. 2025 17:25:00 CEST
|
||||
# RBAC fix test jeu. 02 oct. 2025 09:06:56 CEST
|
||||
Reference in New Issue
Block a user