Initial commit: VPS setup documentation
Add comprehensive documentation for VPS setup and configuration including: - Project instructions - VPS1 starting point configuration - VPS1 current state documentation - VPS1 todo list Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
145
docs/oidc-integration-guide.md
Normal file
145
docs/oidc-integration-guide.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Netbird OIDC Integration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide explains how to integrate your applications (Gitea, Immich, Nextcloud) with Netbird's Zitadel identity provider for single sign-on (SSO) authentication.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Netbird is running and accessible at `nb.phiiiil.de`
|
||||
2. You have admin access to the Netbird dashboard
|
||||
3. DNS records are configured for your applications
|
||||
|
||||
## Zitadel (Netbird Identity Provider)
|
||||
|
||||
Zitadel is running as part of Netbird and is accessible via Caddy reverse proxy.
|
||||
|
||||
**Management Console:** `https://nb.phiiiil.de/ui`
|
||||
|
||||
## Step 1: Access Zitadel Console
|
||||
|
||||
1. Go to `https://nb.phiiiil.de`
|
||||
2. Login with your Netbird admin credentials
|
||||
3. Click on "Zitadel" or access via `https://nb.phiiiil.de/ui`
|
||||
|
||||
## Step 2: Create OIDC Application for Gitea
|
||||
|
||||
### In Zitadel Console:
|
||||
|
||||
1. Navigate to **Projects** → **New Project**
|
||||
- Name: `Gitea`
|
||||
- Project role: Click "Create"
|
||||
|
||||
2. Go to the new Project → **Settings** → Note the **Project ID**
|
||||
|
||||
3. Create Application:
|
||||
- Go to **Applications** → **New**
|
||||
- Application Name: `gitea`
|
||||
- Application Type: **Web**
|
||||
- Redirect URIs:
|
||||
- `https://git.phiiiil.de/user/oauth2/zitadel/callback`
|
||||
- Post Logout URIs:
|
||||
- `https://git.phiiiil.de/
|
||||
- Auth Method: **PKCE**
|
||||
- Click **Continue**
|
||||
|
||||
4. Note the following:
|
||||
- **Client ID**
|
||||
- **Client Secret** (click to reveal)
|
||||
|
||||
## Step 3: Configure Gitea
|
||||
|
||||
### Via Gitea Web UI (Initial Setup):
|
||||
|
||||
1. Access Gitea at `https://git.phiiiil.de` (after DNS is configured)
|
||||
2. Create initial admin account
|
||||
3. Go to **Administration** → **Authentication Sources**
|
||||
|
||||
4. Add OAuth2 Authentication:
|
||||
- **Authentication Name**: Netbird Zitadel
|
||||
- **OAuth2 Provider**: OpenID Connect
|
||||
- **Client ID**: [From Zitadel]
|
||||
- **Client Secret**: [From Zitadel]
|
||||
- **OpenID Connect Discovery Endpoint**: `https://nb.phiiiil.de/.well-known/openid-configuration`
|
||||
- **Auto-discover Email Address**: Enabled
|
||||
- **Scopes**: `openid profile email`
|
||||
- **Email Authentication Field**: Email
|
||||
- **Update Avatar**: Enabled
|
||||
|
||||
5. Click **Create Authentication Source**
|
||||
|
||||
### Via Gitea Configuration (Alternative):
|
||||
|
||||
Edit `/home/phil/docker/gitea/.env` or add to `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- GITEA__oauth2__ENABLE=true
|
||||
- GITEA__oauth2__OPENID_CONNECT_SCOPES=openid,email,profile,groups
|
||||
```
|
||||
|
||||
Then configure via web UI as above.
|
||||
|
||||
## Step 4: Test SSO
|
||||
|
||||
1. Logout of Gitea
|
||||
2. Login page should now show "Sign in with Netbird Zitadel"
|
||||
3. Click to authenticate via Netbird
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Redirect URI mismatch
|
||||
**Solution**: Ensure the redirect URI in Zitadel exactly matches: `https://git.phiiiil.de/user/oauth2/zitadel/callback`
|
||||
|
||||
### Issue: Discovery endpoint fails
|
||||
**Solution**: Check that Caddy is properly proxying OIDC requests:
|
||||
```bash
|
||||
docker logs netbird-caddy-1 | grep -i openid
|
||||
```
|
||||
|
||||
### Issue: User not created automatically
|
||||
**Solution**: In Gitea admin settings, enable "Auto-create users for OAuth2"
|
||||
|
||||
## Additional Applications
|
||||
|
||||
### Immich
|
||||
- Redirect URI: `https://immich.phiiiil.de/auth/login`
|
||||
- Similar process via Immich Admin → Settings → Authentication
|
||||
|
||||
### Nextcloud
|
||||
- Redirect URI: `https://nc.phiiiil.de/index.php/apps/user_oidc/code*
|
||||
- Requires Nextcloud OIDC app
|
||||
- Configure in Nextcloud → Settings → Administration → Security
|
||||
|
||||
## Security Notes
|
||||
|
||||
1. **Store credentials securely**: Keep `.env` files with proper permissions (600)
|
||||
2. **Use HTTPS only**: All OAuth2 communication requires HTTPS
|
||||
3. **Enable PKCE**: Uses Proof Key for Code Exchange for security
|
||||
4. **Limit scopes**: Only request necessary user information
|
||||
|
||||
## Netbird OIDC Endpoints
|
||||
|
||||
The OIDC discovery endpoint is: `https://nb.phiiiil.de/.well-known/openid-configuration`
|
||||
|
||||
This endpoint provides:
|
||||
- Authorization endpoint
|
||||
- Token endpoint
|
||||
- JWKS URI
|
||||
- Supported scopes
|
||||
|
||||
## Current Status
|
||||
|
||||
- ✅ Zitadel running as part of Netbird
|
||||
- ✅ Caddy configured to proxy OIDC requests
|
||||
- ⏳ DNS records needed for git.phiiiil.de and immich.phiiiil.de
|
||||
- ⏳ Manual OIDC configuration required in Gitea
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Update DNS records for `git.phiiiil.de` → `152.53.119.222`
|
||||
2. Wait for DNS propagation (usually 1-24 hours)
|
||||
3. Access Gitea and complete initial setup
|
||||
4. Create OIDC application in Zitadel
|
||||
5. Configure Gitea with OIDC credentials
|
||||
6. Test SSO login
|
||||
Reference in New Issue
Block a user