vps/docs/oidc-integration-guide.md

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:

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:

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