security rework and memory optimilizations.
This commit is contained in:
@@ -0,0 +1,259 @@
|
||||
# Authentik Forward Authentication Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
All NPM-managed domains now use Authentik for centralized Single Sign-On (SSO) authentication. When users access any protected site, they are automatically redirected to Authentik for login, then returned to their original destination.
|
||||
|
||||
## Authentication Flow
|
||||
|
||||
1. **User accesses protected site** (e.g., https://portainer.schweitz.net)
|
||||
2. **NPM checks authentication** via Authentik forward auth
|
||||
3. **If not authenticated**: Redirect to https://auth.schweitz.net/outpost.goauthentik.io/start
|
||||
4. **User logs in** with Google (via Authentik)
|
||||
5. **Authentik sets session cookie** (8-hour validity)
|
||||
6. **Redirect back** to originally requested URL
|
||||
7. **Subsequent requests**: Automatically authenticated (no login required)
|
||||
|
||||
## Token & Session Configuration
|
||||
|
||||
### Token Validity
|
||||
- **Initial validity**: 8 hours (480 minutes)
|
||||
- **Activity-based extension**: Token stays active on use (rolling expiration)
|
||||
- **Idle timeout**: 8 hours after last activity
|
||||
- **Explicit logout**: Token invalidated immediately
|
||||
|
||||
### Session Behavior
|
||||
- **Single login** protects all domains under `*.schweitz.net`
|
||||
- **Cookie domain**: Shared across all sites
|
||||
- **Persistent**: Survives browser restarts (until expiration/logout)
|
||||
- **Secure**: HTTPS-only, HttpOnly flag set
|
||||
|
||||
## Protected Domains
|
||||
|
||||
The following domains are protected with Authentik forward auth:
|
||||
|
||||
1. **192.168.86.149** - Direct IP access
|
||||
2. **amp.schweitz.net** - AMP Server
|
||||
3. **cloud.schweitz.net** - Nextcloud
|
||||
4. **code.schweitz.net** - VS Code Server
|
||||
5. **git.schweitz.net** - Gitea
|
||||
6. **home.schweitz.net** - Home Assistant/Dashboard
|
||||
7. **media.schweitz.net** - Media Server
|
||||
8. **tatlock.schweitz.net** - Tatlock Services
|
||||
9. **tower-of-joy** - Tower of Joy Services
|
||||
|
||||
### Unprotected Domains
|
||||
|
||||
- **auth.schweitz.net** - Authentik itself (cannot protect the auth provider)
|
||||
|
||||
## User Management
|
||||
|
||||
### Adding Users
|
||||
|
||||
1. Go to https://auth.schweitz.net/if/admin/
|
||||
2. Navigate to **Directory** → **Users**
|
||||
3. Click **Create** → **Create and enroll user**
|
||||
4. Enter user details
|
||||
5. Send enrollment invite (they'll set up Google OAuth)
|
||||
|
||||
### User Access Control
|
||||
|
||||
Currently, **all authenticated users** can access protected sites. To restrict access:
|
||||
|
||||
1. Go to https://auth.schweitz.net/if/admin/#/core/applications
|
||||
2. Select **NPM Forward Auth** application
|
||||
3. Go to **Policy / Group / User Bindings**
|
||||
4. Add specific users or groups
|
||||
|
||||
### Group-Based Access (Future)
|
||||
|
||||
You can create groups and assign different access levels:
|
||||
- `admin` - Full access to all sites
|
||||
- `family` - Access to media, home
|
||||
- `developers` - Access to code, git
|
||||
|
||||
## Logout
|
||||
|
||||
Users can log out at: https://auth.schweitz.net/if/user/#/settings
|
||||
|
||||
Click **Sign Out** to invalidate the session across all protected sites.
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Authentik Components
|
||||
|
||||
1. **Proxy Provider** (`npm-forward-auth-provider`)
|
||||
- Mode: `forward_single`
|
||||
- External Host: `https://auth.schweitz.net`
|
||||
- Token Validity: 480 minutes
|
||||
|
||||
2. **Application** (`NPM Forward Auth`)
|
||||
- Links provider to user interface
|
||||
- Accessible at: https://auth.schweitz.net
|
||||
|
||||
3. **Outpost** (`authentik Embedded Outpost`)
|
||||
- Handles authentication requests from NPM
|
||||
- Endpoint: `http://authentik-server:9000/outpost.goauthentik.io`
|
||||
|
||||
### NPM Configuration
|
||||
|
||||
Each proxy host has advanced nginx configuration:
|
||||
|
||||
```nginx
|
||||
# Forward auth to Authentik
|
||||
auth_request /outpost.goauthentik.io/auth/nginx;
|
||||
|
||||
# Preserve cookies
|
||||
auth_request_set $auth_cookie $upstream_http_set_cookie;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
|
||||
# Extract user info
|
||||
auth_request_set $authentik_username $upstream_http_x_authentik_username;
|
||||
auth_request_set $authentik_groups $upstream_http_x_authentik_groups;
|
||||
auth_request_set $authentik_email $upstream_http_x_authentik_email;
|
||||
|
||||
# Pass to backend
|
||||
proxy_set_header X-authentik-username $authentik_username;
|
||||
proxy_set_header X-authentik-email $authentik_email;
|
||||
|
||||
# Redirect on auth failure
|
||||
error_page 401 = @authentik_proxy_signin;
|
||||
|
||||
location @authentik_proxy_signin {
|
||||
return 302 /outpost.goauthentik.io/start?rd=$scheme://$http_host$request_uri;
|
||||
}
|
||||
|
||||
# Auth endpoint
|
||||
location /outpost.goauthentik.io {
|
||||
proxy_pass http://authentik-server:9000/outpost.goauthentik.io;
|
||||
proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
|
||||
proxy_pass_request_body off;
|
||||
}
|
||||
```
|
||||
|
||||
## Backend Application Integration
|
||||
|
||||
Protected applications receive user information via headers:
|
||||
|
||||
- `X-authentik-username` - Username
|
||||
- `X-authentik-email` - Email address
|
||||
- `X-authentik-groups` - Comma-separated groups
|
||||
- `X-authentik-name` - Full name
|
||||
- `X-authentik-uid` - Unique user ID
|
||||
|
||||
Applications can use these headers for:
|
||||
- Displaying user info
|
||||
- Audit logging
|
||||
- Role-based access control
|
||||
- Personalization
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### User Can't Log In
|
||||
|
||||
1. **Check Authentik status**: `docker ps | grep authentik`
|
||||
2. **Check Authentik logs**: `docker logs authentik-server`
|
||||
3. **Verify Google OAuth**:
|
||||
- Go to https://auth.schweitz.net/if/admin/#/core/sources
|
||||
- Ensure Google source is enabled
|
||||
4. **Check user exists**:
|
||||
- Go to https://auth.schweitz.net/if/admin/#/identity/users
|
||||
- Verify user account is active
|
||||
|
||||
### Redirect Loop
|
||||
|
||||
If users get stuck in a redirect loop:
|
||||
|
||||
1. **Clear browser cookies** for `*.schweitz.net`
|
||||
2. **Check NPM config**: Ensure `/outpost.goauthentik.io` location exists
|
||||
3. **Restart NPM**: `docker restart npm`
|
||||
4. **Check outpost**: Verify provider is assigned to outpost
|
||||
|
||||
### 502 Bad Gateway
|
||||
|
||||
If auth requests fail:
|
||||
|
||||
1. **Check Authentik container**: `docker ps | grep authentik`
|
||||
2. **Verify network**: Ensure NPM can reach `authentik-server:9000`
|
||||
3. **Check NPM logs**: `docker logs npm`
|
||||
|
||||
### Session Expires Too Quickly
|
||||
|
||||
If users are logged out unexpectedly:
|
||||
|
||||
1. **Check token validity**: Should be 480 minutes (8 hours)
|
||||
2. **Verify rolling expiration**: Active use should extend session
|
||||
3. **Check system time**: Ensure Docker host time is correct
|
||||
|
||||
## Automation
|
||||
|
||||
### Adding Forward Auth to New Sites
|
||||
|
||||
When creating new proxy hosts via core-api:
|
||||
|
||||
```python
|
||||
from src.clients.npm_client import get_npm_client
|
||||
|
||||
npm = get_npm_client()
|
||||
|
||||
# Create proxy host
|
||||
proxy = await npm.create_proxy_host(
|
||||
domain_names=["newsite.schweitz.net"],
|
||||
forward_host="backend-container",
|
||||
forward_port=8080,
|
||||
ssl_enabled=True
|
||||
)
|
||||
|
||||
# Enable forward auth
|
||||
await npm.enable_authentik_forward_auth(proxy["id"])
|
||||
```
|
||||
|
||||
### Bulk Enable/Disable
|
||||
|
||||
To enable on all hosts:
|
||||
```bash
|
||||
docker exec core-api /venv/bin/python /app/enable_npm_forward_auth.py
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **HTTPS Required**: Forward auth should only be used with HTTPS
|
||||
2. **Secure Cookies**: HttpOnly and Secure flags prevent XSS/MITM
|
||||
3. **Token Rotation**: Tokens are rotated on activity for security
|
||||
4. **Audit Logging**: Authentik logs all authentication events
|
||||
5. **MFA Support**: Can be enabled in Authentik for additional security
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Check Authentication Status
|
||||
|
||||
```bash
|
||||
# Check Authentik health
|
||||
curl http://authentik-server:9000/-/health/live/
|
||||
|
||||
# Check active sessions (in Authentik admin)
|
||||
# https://auth.schweitz.net/if/admin/#/events/log
|
||||
```
|
||||
|
||||
### Monitor Failed Attempts
|
||||
|
||||
Go to **System** → **Events** in Authentik admin to see:
|
||||
- Failed login attempts
|
||||
- Successful authentications
|
||||
- Token expirations
|
||||
- Policy violations
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Per-Site Access Control**: Different user groups for different domains
|
||||
2. **Multi-Factor Authentication**: SMS/TOTP for high-security sites
|
||||
3. **Rate Limiting**: Prevent brute force attacks
|
||||
4. **IP Whitelisting**: Allow certain IPs without auth
|
||||
5. **API Key Support**: Service-to-service authentication
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Security Implementation Plan**: `security-implementation-plan.md`
|
||||
- **SSO Progress**: `SSO_IMPLEMENTATION_PROGRESS.md`
|
||||
- **OIDC Configuration**: `OIDC_CONFIGURATION.md`
|
||||
- **Authentik Docs**: https://docs.goauthentik.io/docs/providers/proxy/
|
||||
Reference in New Issue
Block a user