dkam/clinch
1
0
Fork 0
Code Issues 2 Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Dan Milne
2025-10-29 16:08:49 +11:00
parent ddcb297c74
commit 81871426e9
1 changed files with 11 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/forward-auth.md
View File

@@ -104,17 +104,17 @@ end
- Secure random generation - Secure random generation
- Session validation before token acceptance - Session validation before token acceptance
## Authelia Analysis ## Implementation Overview
### Implementation Comparison ### Forward Auth Pattern
**Authelia Approach (from analysis of `tmp/authelia/`):** **Standard Forward Auth Approach:**
- Returns `302 Found` or `303 See Other` with `Location` header - Returns `302 Found` or `303 See Other` with `Location` header
- Direct browser redirects (bypasses some proxy logic) - Direct browser redirects to authentication service
- Uses StatusFound (302) or StatusSeeOther (303) - Uses HTTP status codes to communicate authentication state
**Clinch Current Implementation:** **Clinch Current Implementation:**
- Returns `302 Found` directly to login URL (matching Authelia) - Returns `302 Found` directly to login URL
- Includes `rd` (redirect destination) and `rm` (request method) parameters - Includes `rd` (redirect destination) and `rm` (request method) parameters
- Uses root domain cookies for cross-subdomain authentication - Uses root domain cookies for cross-subdomain authentication
@@ -123,7 +123,7 @@ end
### Authentication Flow ### Authentication Flow
1. **User visits** `https://metube.example.com/` 1. **User visits** `https://metube.example.com/`
2. **Caddy forwards** to `http://clinch:9000/api/verify?rd=https://clinch.example.com` 2. **Caddy forwards** to `http://clinch:3000/api/verify?rd=https://clinch.example.com`
3. **Clinch checks session**: 3. **Clinch checks session**:
- **If authenticated**: Returns `200 OK` with user headers - **If authenticated**: Returns `200 OK` with user headers
- **If not authenticated**: Returns `302 Found` to login URL with redirect parameters - **If not authenticated**: Returns `302 Found` to login URL with redirect parameters
@@ -157,12 +157,12 @@ Location: https://clinch.example.com/signin?rd=https://metube.example.com/&rm=GE
```caddyfile ```caddyfile
# Clinch SSO (main authentication server) # Clinch SSO (main authentication server)
clinch.example.com { clinch.example.com {
reverse_proxy clinch:9000 reverse_proxy clinch:3000
} }
# MEtube (protected by Clinch) # MEtube (protected by Clinch)
metube.example.com { metube.example.com {
forward_auth clinch:9000 { forward_auth clinch:3000 {
uri /api/verify?rd=https://clinch.example.com uri /api/verify?rd=https://clinch.example.com
copy_headers Remote-User Remote-Email Remote-Groups Remote-Admin copy_headers Remote-User Remote-Email Remote-Groups Remote-Admin
} }
@@ -181,13 +181,13 @@ metube.example.com {
- **Forward Auth Controller**: `app/controllers/api/forward_auth_controller.rb` - **Forward Auth Controller**: `app/controllers/api/forward_auth_controller.rb`
- **Authentication Logic**: `app/controllers/concerns/authentication.rb` - **Authentication Logic**: `app/controllers/concerns/authentication.rb`
- **Caddy Examples**: `docs/caddy-example.md` - **Caddy Examples**: `docs/caddy-example.md`
- **Authelia Analysis**: `docs/authelia-forward-auth.md` - **Implementation Details**: See technical documentation below
## Testing ## Testing
```bash ```bash
# Test forward auth endpoint directly # Test forward auth endpoint directly
curl -v http://localhost:9000/api/verify?rd=https://clinch.example.com curl -v http://localhost:3000/api/verify?rd=https://clinch.example.com
# Should return 302 redirect to login page # Should return 302 redirect to login page
# Or 200 OK if you have a valid session cookie # Or 200 OK if you have a valid session cookie