# 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