service
1e1a528a5e
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>
146 lines
4.2 KiB
Markdown
146 lines
4.2 KiB
Markdown
# 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
|