-
-
-
-
-
-
-
-
+
+ {isLoadingMethods ? (
+
+
+
-
-
-
-
-
+
+ ) : (
+ <>
+ {/* Show tabs only if multiple auth methods are available */}
+ {authMethods.sso.enabled && authMethods.emailPassword ? (
+
+
+
+
+ Email
+
+
+
+ SSO
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {authMethods.sso.providers.length > 0 && (
+ <>
+
+
+ Sign in with your organization account
+
+ {authMethods.sso.providers.map(provider => (
+
+ ))}
+
+
+
+
+ )}
+
+
+
+
setSsoEmail(e.target.value)}
+ className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+ placeholder="Enter your work email"
+ disabled={isLoading}
+ />
+
+ We'll redirect you to your organization's SSO provider
+
+
+
+ ) : (
+ // Single auth method - show email/password only
+ <>
+
+
+
+
+
+
+
+ )}
+
+ )}
+
Don't have an account? Contact your administrator.
diff --git a/src/components/auth/LoginPage.tsx b/src/components/auth/LoginPage.tsx
new file mode 100644
index 0000000..abd8937
--- /dev/null
+++ b/src/components/auth/LoginPage.tsx
@@ -0,0 +1,10 @@
+import { LoginForm } from './LoginForm';
+import Providers from '@/components/layout/Providers';
+
+export function LoginPage() {
+ return (
+
+
+
+ );
+}
\ No newline at end of file
diff --git a/src/components/auth/SignupForm.tsx b/src/components/auth/SignupForm.tsx
index 53f52f1..77ee885 100644
--- a/src/components/auth/SignupForm.tsx
+++ b/src/components/auth/SignupForm.tsx
@@ -5,21 +5,22 @@ import { Button } from '@/components/ui/button';
import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@/components/ui/card';
import { toast, Toaster } from 'sonner';
import { showErrorToast } from '@/lib/utils';
+import { useAuth } from '@/hooks/useAuth';
export function SignupForm() {
const [isLoading, setIsLoading] = useState(false);
+ const { register } = useAuth();
async function handleSignup(e: React.FormEvent) {
e.preventDefault();
setIsLoading(true);
const form = e.currentTarget;
const formData = new FormData(form);
- const username = formData.get('username') as string | null;
const email = formData.get('email') as string | null;
const password = formData.get('password') as string | null;
const confirmPassword = formData.get('confirmPassword') as string | null;
- if (!username || !email || !password || !confirmPassword) {
+ if (!email || !password || !confirmPassword) {
toast.error('Please fill in all fields');
setIsLoading(false);
return;
@@ -31,28 +32,15 @@ export function SignupForm() {
return;
}
- const signupData = { username, email, password };
-
try {
- const response = await fetch('/api/auth/register', {
- method: 'POST',
- headers: {
- 'Content-Type': 'application/json',
- },
- body: JSON.stringify(signupData),
- });
-
- const data = await response.json();
-
- if (response.ok) {
- toast.success('Account created successfully! Redirecting to dashboard...');
- // Small delay before redirecting to see the success message
- setTimeout(() => {
- window.location.href = '/';
- }, 1500);
- } else {
- showErrorToast(data.error || 'Failed to create account. Please try again.', toast);
- }
+ // Derive username from email (part before @)
+ const username = email.split('@')[0];
+ await register(username, email, password);
+ toast.success('Account created successfully! Redirecting to dashboard...');
+ // Small delay before redirecting to see the success message
+ setTimeout(() => {
+ window.location.href = '/';
+ }, 1500);
} catch (error) {
showErrorToast(error, toast);
} finally {
@@ -84,20 +72,6 @@ export function SignupForm() {
);
}
diff --git a/src/components/config/SSOSettings.tsx b/src/components/config/SSOSettings.tsx
new file mode 100644
index 0000000..0d3b072
--- /dev/null
+++ b/src/components/config/SSOSettings.tsx
@@ -0,0 +1,426 @@
+import { useState, useEffect } from 'react';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Switch } from '@/components/ui/switch';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
+import { apiRequest, showErrorToast } from '@/lib/utils';
+import { toast } from 'sonner';
+import { Plus, Trash2, ExternalLink, Loader2, AlertCircle, Copy, Shield, Info } from 'lucide-react';
+import { Separator } from '@/components/ui/separator';
+import { Skeleton } from '../ui/skeleton';
+import { Badge } from '../ui/badge';
+
+interface SSOProvider {
+ id: string;
+ issuer: string;
+ domain: string;
+ providerId: string;
+ organizationId?: string;
+ oidcConfig: {
+ clientId: string;
+ clientSecret: string;
+ authorizationEndpoint: string;
+ tokenEndpoint: string;
+ jwksEndpoint: string;
+ userInfoEndpoint: string;
+ mapping: {
+ id: string;
+ email: string;
+ emailVerified: string;
+ name: string;
+ image: string;
+ };
+ };
+ createdAt: string;
+ updatedAt: string;
+}
+
+export function SSOSettings() {
+ const [providers, setProviders] = useState
([]);
+ const [isLoading, setIsLoading] = useState(true);
+ const [showProviderDialog, setShowProviderDialog] = useState(false);
+ const [isDiscovering, setIsDiscovering] = useState(false);
+ const [headerAuthEnabled, setHeaderAuthEnabled] = useState(false);
+
+ // Form states for new provider
+ const [providerForm, setProviderForm] = useState({
+ issuer: '',
+ domain: '',
+ providerId: '',
+ clientId: '',
+ clientSecret: '',
+ authorizationEndpoint: '',
+ tokenEndpoint: '',
+ jwksEndpoint: '',
+ userInfoEndpoint: '',
+ });
+
+
+
+ useEffect(() => {
+ loadData();
+ }, []);
+
+ const loadData = async () => {
+ setIsLoading(true);
+ try {
+ const [providersRes, headerAuthStatus] = await Promise.all([
+ apiRequest('/sso/providers'),
+ apiRequest<{ enabled: boolean }>('/auth/header-status').catch(() => ({ enabled: false }))
+ ]);
+
+ setProviders(providersRes);
+ setHeaderAuthEnabled(headerAuthStatus.enabled);
+ } catch (error) {
+ showErrorToast(error, toast);
+ } finally {
+ setIsLoading(false);
+ }
+ };
+
+ const discoverOIDC = async () => {
+ if (!providerForm.issuer) {
+ toast.error('Please enter an issuer URL');
+ return;
+ }
+
+ setIsDiscovering(true);
+ try {
+ const discovered = await apiRequest('/sso/discover', {
+ method: 'POST',
+ data: { issuer: providerForm.issuer },
+ });
+
+ setProviderForm(prev => ({
+ ...prev,
+ authorizationEndpoint: discovered.authorizationEndpoint || '',
+ tokenEndpoint: discovered.tokenEndpoint || '',
+ jwksEndpoint: discovered.jwksEndpoint || '',
+ userInfoEndpoint: discovered.userInfoEndpoint || '',
+ domain: discovered.suggestedDomain || prev.domain,
+ }));
+
+ toast.success('OIDC configuration discovered successfully');
+ } catch (error) {
+ showErrorToast(error, toast);
+ } finally {
+ setIsDiscovering(false);
+ }
+ };
+
+ const createProvider = async () => {
+ try {
+ const newProvider = await apiRequest('/sso/providers', {
+ method: 'POST',
+ data: {
+ ...providerForm,
+ mapping: {
+ id: 'sub',
+ email: 'email',
+ emailVerified: 'email_verified',
+ name: 'name',
+ image: 'picture',
+ },
+ },
+ });
+
+ setProviders([...providers, newProvider]);
+ setShowProviderDialog(false);
+ setProviderForm({
+ issuer: '',
+ domain: '',
+ providerId: '',
+ clientId: '',
+ clientSecret: '',
+ authorizationEndpoint: '',
+ tokenEndpoint: '',
+ jwksEndpoint: '',
+ userInfoEndpoint: '',
+ });
+ toast.success('SSO provider created successfully');
+ } catch (error) {
+ showErrorToast(error, toast);
+ }
+ };
+
+ const deleteProvider = async (id: string) => {
+ try {
+ await apiRequest(`/sso/providers?id=${id}`, { method: 'DELETE' });
+ setProviders(providers.filter(p => p.id !== id));
+ toast.success('Provider deleted successfully');
+ } catch (error) {
+ showErrorToast(error, toast);
+ }
+ };
+
+
+ const copyToClipboard = (text: string) => {
+ navigator.clipboard.writeText(text);
+ toast.success('Copied to clipboard');
+ };
+
+ if (isLoading) {
+ return (
+
+
+
+
+ );
+ }
+
+ return (
+
+ {/* Header with status indicators */}
+
+
+
Authentication & SSO
+
+ Configure how users authenticate with your application
+
+
+
+
0 ? 'bg-green-500' : 'bg-muted'}`} />
+
+ {providers.length} Provider{providers.length !== 1 ? 's' : ''} configured
+
+
+
+
+ {/* Authentication Methods Overview */}
+
+
+ Active Authentication Methods
+
+
+
+ {/* Email & Password - Always enabled */}
+
+
+
+
Email & Password
+
Default
+
+
Always enabled
+
+
+ {/* Header Authentication Status */}
+ {headerAuthEnabled && (
+
+
+
+
Header Authentication
+
Auto-login
+
+
Via reverse proxy
+
+ )}
+
+ {/* SSO Providers Status */}
+
+
+
0 ? 'bg-green-500' : 'bg-muted'}`} />
+ SSO/OIDC Providers
+
+
+ {providers.length > 0 ? `${providers.length} provider${providers.length !== 1 ? 's' : ''} configured` : 'Not configured'}
+
+
+
+
+ {/* Header Auth Info */}
+ {headerAuthEnabled && (
+
+
+
+ Header authentication is enabled. Users authenticated by your reverse proxy will be automatically logged in.
+
+
+ )}
+
+
+
+ {/* SSO Providers */}
+
+
+
+
+ External Identity Providers
+
+ Connect external OIDC/OAuth providers (Google, Azure AD, etc.) to allow users to sign in with their existing accounts
+
+
+
+
+
+
No SSO providers configured
+
+ Enable Single Sign-On by adding an external identity provider like Google, Azure AD, or any OIDC-compliant service.
+
+
+
+
+
+ {providers.map(provider => (
+
+
+
+
+
{provider.providerId}
+
{provider.domain}
+
+
+
+
+
Issuer
+
{provider.issuer}
+
+
+
Client ID
+
{provider.oidcConfig.clientId}
+
+
+ ))}
+
+
+
+
+
+
+ Support Development
+
+
+ Help us improve Gitea Mirror
+
+
+
+
+ Gitea Mirror is open source and free. Your sponsorship helps us maintain and improve it.
+
+
+
+
+
+
+
+ Pro features available in hosted version
+
+
+
+
+
+ );
+ }
+
+ if (error) {
+ return (
+
+
+
+
+ Authorization Error
+
+
+
+ {error}
+
+
+
+
+
+
+
+
+
+
+
+
+ Authorize {application?.name}
+
+ This application is requesting access to your account
+
+
+
+
+
+
Requested permissions:
+
+ {scopes.map(scope => {
+ const scopeInfo = getScopeDescription(scope);
+ const Icon = scopeInfo.icon;
+ const isRequired = scope === 'openid';
+
+ return (
+
+
toggleScope(scope)}
+ disabled={isRequired || isSubmitting}
+ />
+
+
+
+ {scopeInfo.description}
+
+
+ );
+ })}
+
+
+
+
+ You'll be redirected to {application?.type === 'web' ? 'the website' : 'the application'}
+
+
+
+ You can revoke access at any time in your account settings
+
+
+
+ Gitea Mirror is open source and free to use. If you find it helpful,
+ consider supporting the project!
+
+
+
+
+
+
+
+ Your support helps maintain and improve the project
+
+
+
+
Advanced Topics
+
+ Advanced configuration options, deployment strategies, troubleshooting, and performance optimization for Gitea Mirror.
+
+
Environment Variables
+
+
+ Gitea Mirror can be configured using environment variables. These are particularly useful for containerized deployments.
+
+
+
+
+
+
+ | Variable |
+ Description |
+ Default |
+
+
+
+ {[
+ { var: 'NODE_ENV', desc: 'Application environment', default: 'production' },
+ { var: 'PORT', desc: 'Server port', default: '4321' },
+ { var: 'HOST', desc: 'Server host', default: '0.0.0.0' },
+ { var: 'BETTER_AUTH_SECRET', desc: 'Authentication secret key', default: 'Auto-generated' },
+ { var: 'BETTER_AUTH_URL', desc: 'Authentication base URL', default: 'http://localhost:4321' },
+ { var: 'NODE_EXTRA_CA_CERTS', desc: 'Path to CA certificate file', default: 'None' },
+ { var: 'DATABASE_URL', desc: 'SQLite database path', default: './data/gitea-mirror.db' },
+ ].map((item, i) => (
+
+ | {item.var} |
+ {item.desc} |
+ {item.default} |
+
+ ))}
+
+
+
Database Management
+
+
+ Gitea Mirror uses SQLite for data storage. The database is automatically created on first run.
+
+
+ Database Commands
+
+
+
+
Initialize Database
+
+ bun run init-db
+
+
Creates or recreates the database schema
+
+
+
+
Check Database
+
+ bun run check-db
+
+
Verifies database integrity and displays statistics
+
+
+
+
Fix Database
+
+ bun run fix-db
+
+
Attempts to repair common database issues
+
+
+
+
Backup Database
+
+ cp data/gitea-mirror.db data/gitea-mirror.db.backup
+
+
Always backup before major changes
+
+
Database Schema Management
+
+
+
+
+
+
Drizzle Kit
+
Database schema is managed with Drizzle ORM. Use these commands for schema changes:
+
+ bun run drizzle-kit generate - Generate migration filesbun run drizzle-kit push - Apply schema changes directlybun run drizzle-kit studio - Open database browser
+
+
+
Performance Optimization
+
+ Mirroring Performance
+
+
+ {[
+ {
+ title: 'Batch Operations',
+ tips: [
+ 'Mirror multiple repositories at once',
+ 'Use organization-level mirroring',
+ 'Schedule mirroring during off-peak hours'
+ ]
+ },
+ {
+ title: 'Network Optimization',
+ tips: [
+ 'Use SSH URLs when possible',
+ 'Enable Git LFS only when needed',
+ 'Consider repository size limits'
+ ]
+ }
+ ].map(section => (
+
+
{section.title}
+
+ {section.tips.map(tip => (
+ -
+ โข
+ {tip}
+
+ ))}
+
+
+ ))}
+
Database Performance
+
+
+
Regular Maintenance
+
+ -
+ โข
+ Enable automatic cleanup in Configuration โ Automation
+
+ -
+ โข
+ Periodically vacuum the SQLite database:
sqlite3 data/gitea-mirror.db "VACUUM;"
+
+ -
+ โข
+ Monitor database size and clean old events regularly
+
+
+
Reverse Proxy Configuration
+
+
+ For production deployments, it's recommended to use a reverse proxy like Nginx or Caddy.
+
+
+ Nginx Example
+
+
+
{`server {
+ listen 80;
+ server_name gitea-mirror.example.com;
+ return 301 https://$server_name$request_uri;
+}
+
+server {
+ listen 443 ssl http2;
+ server_name gitea-mirror.example.com;
+
+ ssl_certificate /path/to/cert.pem;
+ ssl_certificate_key /path/to/key.pem;
+
+ location / {
+ proxy_pass http://localhost:4321;
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection 'upgrade';
+ proxy_set_header Host $host;
+ proxy_cache_bypass $http_upgrade;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ }
+
+ # SSE endpoint needs special handling
+ location /api/sse {
+ proxy_pass http://localhost:4321;
+ proxy_http_version 1.1;
+ proxy_set_header Connection '';
+ proxy_set_header Cache-Control 'no-cache';
+ proxy_set_header X-Accel-Buffering 'no';
+ proxy_read_timeout 86400;
+ }
+}`}
+
Caddy Example
+
+
+
{`gitea-mirror.example.com {
+ reverse_proxy localhost:4321
+}`}
+
Monitoring and Health Checks
+
+ Health Check Endpoint
+
+
+
Monitor application health using the built-in endpoint:
+
+
+ GET /api/health
+
+
+
Response:
+
+
{`{
+ "status": "ok",
+ "timestamp": "2024-01-15T10:30:00Z",
+ "database": "connected",
+ "version": "1.0.0"
+}`}
+
+
Monitoring with Prometheus
+
+
+ While Gitea Mirror doesn't have built-in Prometheus metrics, you can monitor it using:
+
+
+
+ -
+ โข
+ Blackbox exporter for endpoint monitoring
+
+ -
+ โข
+ Node exporter for system metrics
+
+ -
+ โข
+ Custom scripts to check database metrics
+
+
+
+
+
+
+
+
+ Backup and Recovery
+
+ What to Backup
+
+
+
+
Essential Files
+
+ - โข data/gitea-mirror.db
+ - โข .env (if using)
+ - โข Custom CA certificates
+
+
+
+
+
Optional Files
+
+ - โข Docker volumes
+ - โข Custom configurations
+ - โข Logs for auditing
+
+
+
Backup Script Example
+
+
+
{`#!/bin/bash
+BACKUP_DIR="/backups/gitea-mirror"
+DATE=$(date +%Y%m%d_%H%M%S)
+
+# Create backup directory
+mkdir -p "$BACKUP_DIR/$DATE"
+
+# Backup database
+cp data/gitea-mirror.db "$BACKUP_DIR/$DATE/"
+
+# Backup environment
+cp .env "$BACKUP_DIR/$DATE/" 2>/dev/null || true
+
+# Create tarball
+tar -czf "$BACKUP_DIR/backup_$DATE.tar.gz" -C "$BACKUP_DIR" "$DATE"
+
+# Clean up
+rm -rf "$BACKUP_DIR/$DATE"
+
+# Keep only last 7 backups
+ls -t "$BACKUP_DIR"/backup_*.tar.gz | tail -n +8 | xargs rm -f`}
+
Troubleshooting Guide
+
+
+ {[
+ {
+ issue: 'Application won\'t start',
+ solutions: [
+ 'Check port availability: `lsof -i :4321`',
+ 'Verify environment variables are set correctly',
+ 'Check database file permissions',
+ 'Review logs for startup errors'
+ ]
+ },
+ {
+ issue: 'Authentication failures',
+ solutions: [
+ 'Ensure BETTER_AUTH_SECRET is set and consistent',
+ 'Check BETTER_AUTH_URL matches your deployment',
+ 'Clear browser cookies and try again',
+ 'Verify database contains user records'
+ ]
+ },
+ {
+ issue: 'Mirroring failures',
+ solutions: [
+ 'Test GitHub/Gitea connections individually',
+ 'Verify access tokens have correct permissions',
+ 'Check network connectivity and firewall rules',
+ 'Review Activity Log for detailed error messages'
+ ]
+ },
+ {
+ issue: 'Performance issues',
+ solutions: [
+ 'Check database size and run cleanup',
+ 'Monitor system resources (CPU, memory, disk)',
+ 'Reduce concurrent mirroring operations',
+ 'Consider upgrading deployment resources'
+ ]
+ }
+ ].map(item => (
+
+
{item.issue}
+
+ {item.solutions.map(solution => (
+ -
+ โ
+ {solution}
+
+ ))}
+
+
+ ))}
+
Migration Guide
+
+ Migrating from JWT to Better Auth
+
+
+
If you're upgrading from an older version using JWT authentication:
+
+
+ -
+ 1
+
+
Backup your database
+
Always create a backup before migration
+
+ -
+ 2
+
+
Update environment variables
+
Replace JWT_SECRET with BETTER_AUTH_SECRET
+
+ -
+ 3
+
+
Run database migrations
+
New auth tables will be created automatically
+
+ -
+ 4
+
+
Users will need to log in again
+
Previous sessions will be invalidated
+
+
+
@@ -184,7 +185,8 @@ import MainLayout from '../../layouts/main.astro';
{[
- 'Authentication and user management',
+ 'Authentication with Better Auth (email/password, SSO, OIDC)',
+ 'OAuth2/OIDC provider functionality',
'GitHub API integration',
'Gitea API integration',
'Mirroring operations and job queue',
@@ -213,11 +215,13 @@ import MainLayout from '../../layouts/main.astro';
{[
- 'User accounts and authentication data',
+ 'User accounts and authentication data (Better Auth)',
+ 'OAuth applications and SSO provider configurations',
'GitHub and Gitea configuration',
'Repository and organization information',
'Mirroring job history and status',
- 'Event notifications and their read status'
+ 'Event notifications and their read status',
+ 'OAuth tokens and consent records'
].map(item => (
โธ
@@ -238,7 +242,7 @@ import MainLayout from '../../layouts/main.astro';
{[
- { title: 'User Authentication', desc: 'Users authenticate through the frontend, which communicates with the backend to validate credentials.' },
+ { title: 'User Authentication', desc: 'Users authenticate via Better Auth using email/password, SSO providers, or as OIDC clients.' },
{ title: 'Configuration', desc: 'Users configure GitHub and Gitea settings through the UI, which are stored in the SQLite database.' },
{ title: 'Repository Discovery', desc: 'The backend queries the GitHub API to discover repositories based on user configuration.' },
{ title: 'Mirroring Process', desc: 'When triggered, the backend fetches repository data from GitHub and pushes it to Gitea.' },
diff --git a/src/pages/docs/authentication.astro b/src/pages/docs/authentication.astro
new file mode 100644
index 0000000..d87ef96
--- /dev/null
+++ b/src/pages/docs/authentication.astro
@@ -0,0 +1,535 @@
+---
+import MainLayout from '../../layouts/main.astro';
+---
+
+
+
+
+
+
+
+
+
+
Authentication & SSO Configuration
+
+ Configure authentication methods including email/password, Single Sign-On (SSO), and OIDC provider functionality for Gitea Mirror.
+
+
Authentication Overview
+
+
+
+ Gitea Mirror uses Better Auth, a modern authentication library that supports multiple authentication methods.
+ All authentication settings can be configured through the web UI without editing configuration files.
+
+
Supported Authentication Methods
+
+
+ {[
+ {
+ icon: 'โ๏ธ',
+ title: 'Email & Password',
+ desc: 'Traditional authentication with email and password. Always enabled by default.',
+ status: 'Always Enabled'
+ },
+ {
+ icon: '๐',
+ title: 'Single Sign-On (SSO)',
+ desc: 'Allow users to sign in using external OIDC providers like Google, Okta, or Azure AD.',
+ status: 'Optional'
+ },
+ {
+ icon: '๐',
+ title: 'OIDC Provider',
+ desc: 'Act as an OIDC provider, allowing other applications to authenticate through Gitea Mirror.',
+ status: 'Optional'
+ }
+ ].map(method => (
+
+
{method.icon}
+
{method.title}
+
{method.desc}
+
+ {method.status}
+
+
+ ))}
+
Accessing Authentication Settings
+
+
+ -
+ 1
+ Navigate to the Configuration page
+
+ -
+ 2
+ Click on the Authentication tab
+
+ -
+ 3
+ Configure SSO providers or OAuth applications as needed
+
+
+
+
+
+
+
+
+ Single Sign-On (SSO) Configuration
+
+
+ SSO allows your users to authenticate using external identity providers. This is useful for organizations that already have centralized authentication systems.
+
+
+ Adding an SSO Provider
+
+
+
Required Information
+
+
+ {[
+ { name: 'Issuer URL', desc: 'The OIDC issuer URL of your provider', example: 'https://accounts.google.com' },
+ { name: 'Domain', desc: 'The email domain for this provider', example: 'example.com' },
+ { name: 'Provider ID', desc: 'A unique identifier for this provider', example: 'google-sso' },
+ { name: 'Client ID', desc: 'OAuth client ID from your provider', example: '123456789.apps.googleusercontent.com' },
+ { name: 'Client Secret', desc: 'OAuth client secret from your provider', example: 'GOCSPX-...' }
+ ].map(field => (
+
+
+ {field.name}
+ Required
+
+
{field.desc}
+
{field.example}
+
+ ))}
+
+
+
+
+
+
Auto-Discovery
+
Most OIDC providers support auto-discovery. Simply enter the Issuer URL and click "Discover" to automatically populate the endpoint URLs.
+
+
+
Redirect URL Configuration
+
+
+
When configuring your SSO provider, use this redirect URL:
+
https://your-domain.com/api/auth/sso/callback/{`{provider-id}`}
+
Replace {`{provider-id}`} with your chosen Provider ID (e.g., google-sso)
+
Example SSO Configurations
+
+
+
+
+ 
+ Google SSO
+
+
+
+
+ -
+ 1. Create OAuth Client in Google Cloud Console
+
+ - โข Go to Google Cloud Console
+ - โข Create a new OAuth 2.0 Client ID
+ - โข Add authorized redirect URI:
https://your-domain.com/api/auth/sso/callback/google-sso
+
+
+ -
+ 2. Configure in Gitea Mirror
+
+
+
Issuer URL: https://accounts.google.com
+
Domain: your-company.com
+
Provider ID: google-sso
+
Client ID: [Your Google Client ID]
+
Client Secret: [Your Google Client Secret]
+
+
+ -
+ 3. Use Auto-Discovery
+
Click "Discover" to automatically populate the endpoint URLs
+
+
+
+
+
+ O
+ Okta SSO
+
+
+
+
+ -
+ 1. Create OIDC Application in Okta
+
+ - โข In Okta Admin Console, create a new OIDC Web Application
+ - โข Set Sign-in redirect URI:
https://your-domain.com/api/auth/sso/callback/okta-sso
+ - โข Note the Client ID and Client Secret
+
+
+ -
+ 2. Configure in Gitea Mirror
+
+
+
Issuer URL: https://your-okta-domain.okta.com
+
Domain: your-company.com
+
Provider ID: okta-sso
+
Client ID: [Your Okta Client ID]
+
Client Secret: [Your Okta Client Secret]
+
+
+
+
+
+
+ M
+ Azure AD / Microsoft Entra ID
+
+
+
+
+ -
+ 1. Register Application in Azure Portal
+
+ - โข Go to Azure Portal โ Azure Active Directory โ App registrations
+ - โข Create a new registration
+ - โข Add redirect URI:
https://your-domain.com/api/auth/sso/callback/azure-sso
+
+
+ -
+ 2. Configure in Gitea Mirror
+
+
+
Issuer URL: https://login.microsoftonline.com/{`{tenant-id}`}/v2.0
+
Domain: your-company.com
+
Provider ID: azure-sso
+
Client ID: [Your Application ID]
+
Client Secret: [Your Client Secret]
+
+
+
+
+
OIDC Provider Configuration
+
+
+ The OIDC Provider feature allows Gitea Mirror to act as an authentication provider for other applications.
+ This is useful when you want to centralize authentication through Gitea Mirror.
+
+
+ Creating OAuth Applications
+
+
+
+ -
+ 1
+
+
Navigate to OAuth Applications
+
Go to Configuration โ Authentication โ OAuth Applications
+
+ -
+ 2
+
+
Create New Application
+
Click "Create Application" and provide:
+
+ - โข Application Name
+ - โข Application Type (Web, Mobile, or Desktop)
+ - โข Redirect URLs (one per line)
+
+
+ -
+ 3
+
+
Save Credentials
+
You'll receive a Client ID and Client Secret. Store these securely!
+
+
+
OIDC Endpoints
+
+
+
Applications can use these standard OIDC endpoints:
+
+
+ Discovery:
+ https://your-domain.com/.well-known/openid-configuration
+
+
+ Authorization:
+ https://your-domain.com/api/auth/oauth2/authorize
+
+
+ Token:
+ https://your-domain.com/api/auth/oauth2/token
+
+
+ UserInfo:
+ https://your-domain.com/api/auth/oauth2/userinfo
+
+
+ JWKS:
+ https://your-domain.com/api/auth/jwks
+
+
+
Supported Scopes
+
+
+ {[
+ { scope: 'openid', desc: 'Required - provides user ID', claims: 'sub' },
+ { scope: 'profile', desc: 'User profile information', claims: 'name, username, picture' },
+ { scope: 'email', desc: 'Email address', claims: 'email, email_verified' }
+ ].map(item => (
+
+
{item.scope}
+
{item.desc}
+
Claims: {item.claims}
+
+ ))}
+
User Experience
+
+ Login Flow with SSO
+
+
+
When SSO is configured, users will see authentication options on the login page:
+
+ - 1. Email & Password tab for traditional login
+ - 2. SSO tab with provider buttons or email input
+ - 3. Automatic redirect to the appropriate provider
+ - 4. Return to Gitea Mirror after successful authentication
+
+
OAuth Consent Flow
+
+
+
When an application requests authentication through Gitea Mirror:
+
+ - 1. User is redirected to Gitea Mirror
+ - 2. Login prompt if not already authenticated
+ - 3. Consent screen showing requested permissions
+ - 4. User approves or denies the request
+ - 5. Redirect back to the application with auth code
+
+
Security Considerations
+
+
+ {[
+ {
+ icon: '๐',
+ title: 'Client Secrets',
+ items: [
+ 'Store OAuth client secrets securely',
+ 'Never commit secrets to version control',
+ 'Rotate secrets regularly'
+ ]
+ },
+ {
+ icon: '๐',
+ title: 'Redirect URLs',
+ items: [
+ 'Only add trusted redirect URLs',
+ 'Use HTTPS in production',
+ 'Validate exact URL matches'
+ ]
+ },
+ {
+ icon: '๐ก๏ธ',
+ title: 'Scopes & Permissions',
+ items: [
+ 'Grant minimum required scopes',
+ 'Review requested permissions',
+ 'Users can revoke access anytime'
+ ]
+ },
+ {
+ icon: 'โฑ๏ธ',
+ title: 'Token Security',
+ items: [
+ 'Access tokens have expiration',
+ 'Refresh tokens for long-lived access',
+ 'Tokens can be revoked'
+ ]
+ }
+ ].map(section => (
+
+
+ {section.icon}
+
{section.title}
+
+
+ {section.items.map(item => (
+ -
+ โข
+ {item}
+
+ ))}
+
+
+ ))}
+
Troubleshooting
+
+
+
+
SSO Login Issues
+
+ -
+ โข
+
+ "Invalid origin" error: Check that your Gitea Mirror URL matches the configured redirect URI
+
+
+ -
+ โข
+
+ "Provider not found" error: Ensure the provider is properly configured and saved
+
+
+ -
+ โข
+
+ Redirect loop: Verify the redirect URI in both Gitea Mirror and the SSO provider match exactly
+
+
+
+
+
+
+
OIDC Provider Issues
+
+ -
+ โข
+
+ Application not found: Ensure the client ID is correct and the app is not disabled
+
+
+ -
+ โข
+
+ Invalid redirect URI: The redirect URI must match exactly what's configured
+
+
+ -
+ โข
+
+ Consent not working: Check browser cookies are enabled and not blocked
+
+
+
+
+
Migration from JWT Authentication
+
+
+
+
+
+
For Existing Users
+
+ - โข Email/password authentication continues to work
+ - โข No action required from existing users
+ - โข SSO can be added as an additional option
+ - โข JWT_SECRET is no longer required in environment variables
+
+
+
+
+
+
CA Certificates Configuration
+
+ Configure custom Certificate Authority (CA) certificates for connecting to self-signed or privately signed Gitea instances.
+
+
Overview
+
+
+
+ When your Gitea instance uses a self-signed certificate or a certificate signed by a private Certificate Authority (CA),
+ you need to configure Gitea Mirror to trust these certificates. This guide explains how to add custom CA certificates
+ for different deployment methods.
+
+
+
+
+
+
Important
+
Without proper CA certificate configuration, you'll encounter SSL/TLS errors when connecting to Gitea instances with custom certificates.
+
+
+
Common SSL/TLS Errors
+
+ If you see any of these errors, you likely need to configure CA certificates:
+
+
+ {[
+ 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+ 'SELF_SIGNED_CERT_IN_CHAIN',
+ 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+ 'CERT_UNTRUSTED',
+ 'unable to verify the first certificate'
+ ].map(error => (
+
+ {error}
+
+ ))}
+
Docker Configuration
+
+ For Docker deployments, you have several options to add custom CA certificates:
+
+ Method 1: Volume Mount (Recommended)
+
+
+
+ -
+ 1. Create a certificates directory
+
+
+ -
+ 2. Copy your CA certificate(s)
+
+
cp /path/to/your-ca-cert.crt ./certs/
+
+ -
+ 3. Update docker-compose.yml
+
+
{`version: '3.8'
+services:
+ gitea-mirror:
+ image: raylabs/gitea-mirror:latest
+ volumes:
+ - ./data:/app/data
+ - ./certs:/usr/local/share/ca-certificates:ro
+ environment:
+ - NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/your-ca-cert.crt`}
+
+ -
+ 4. Restart the container
+
+
docker-compose down && docker-compose up -d
+
+
+
Method 2: Custom Docker Image
+
+
+
For permanent certificate inclusion, create a custom Docker image:
+
+
+
{`FROM raylabs/gitea-mirror:latest
+
+# Copy CA certificates
+COPY ./certs/*.crt /usr/local/share/ca-certificates/
+
+# Update CA certificates
+RUN update-ca-certificates
+
+# Set environment variable
+ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/your-ca-cert.crt`}
+
+
+
Build and use your custom image:
+
+
docker build -t my-gitea-mirror .
+
+
Native/Bun Configuration
+
+ For native Bun deployments, configure CA certificates using environment variables:
+
+ Method 1: Environment Variable
+
+
+
+ -
+ 1. Export the certificate path
+
+
export NODE_EXTRA_CA_CERTS=/path/to/your-ca-cert.crt
+
+ -
+ 2. Run Gitea Mirror
+
+
+
+
Method 2: .env File
+
+
+
Add to your .env file:
+
+
NODE_EXTRA_CA_CERTS=/path/to/your-ca-cert.crt
+
+
Method 3: System-wide CA Store
+
+
+
Add certificates to your system's CA store:
+
+
+
+
Ubuntu/Debian:
+
+
{`sudo cp your-ca-cert.crt /usr/local/share/ca-certificates/
+sudo update-ca-certificates`}
+
+
+
+
+
RHEL/CentOS/Fedora:
+
+
{`sudo cp your-ca-cert.crt /etc/pki/ca-trust/source/anchors/
+sudo update-ca-trust`}
+
+
+
+
+
macOS:
+
+
{`sudo security add-trusted-cert -d -r trustRoot \\
+ -k /Library/Keychains/System.keychain your-ca-cert.crt`}
+
+
+
+
LXC Container Configuration
+
+ For LXC deployments on Proxmox VE:
+
+
+
+ -
+ 1. Enter the container
+
+
pct enter <container-id>
+
+ -
+ 2. Create certificates directory
+
+
mkdir -p /usr/local/share/ca-certificates
+
+ -
+ 3. Copy your CA certificate
+
+
cat > /usr/local/share/ca-certificates/your-ca.crt
+
Paste your certificate content and press Ctrl+D
+
+ -
+ 4. Update the systemd service
+
+
{`cat >> /etc/systemd/system/gitea-mirror.service << EOF
+Environment="NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/your-ca.crt"
+EOF`}
+
+ -
+ 5. Reload and restart
+
+
{`systemctl daemon-reload
+systemctl restart gitea-mirror`}
+
+
+
Multiple CA Certificates
+
+ If you need to trust multiple CA certificates:
+
+ Option 1: Bundle Certificates
+
+
+
Combine multiple certificates into one file:
+
+
{`cat ca-cert1.crt ca-cert2.crt ca-cert3.crt > ca-bundle.crt
+export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt`}
+
+
Option 2: System CA Store
+
+
+
Add all certificates to the system CA store (recommended for production):
+
+
{`# Copy all certificates
+cp *.crt /usr/local/share/ca-certificates/
+update-ca-certificates`}
+
+
Verifying Certificate Configuration
+
+ Test your certificate configuration:
+
+
+
1. Test Gitea Connection
+
Use the "Test Connection" button in the Gitea configuration section
+
+
2. Check Logs
+
Look for SSL/TLS errors in the application logs:
+
+
+
+
Docker:
+
+ docker logs gitea-mirror
+
+
+
+
Native:
+
+ Check terminal output
+
+
+
+
LXC:
+
+ journalctl -u gitea-mirror -f
+
+
+
+
+
3. Manual Certificate Test
+
Test SSL connection directly:
+
+
openssl s_client -connect your-gitea-domain.com:443 -CAfile /path/to/ca-cert.crt
+
+
Best Practices
+
+
+ {[
+ {
+ icon: '๐',
+ title: 'Certificate Security',
+ items: [
+ 'Keep CA certificates secure',
+ 'Use read-only mounts in Docker',
+ 'Limit certificate file permissions',
+ 'Regularly update certificates'
+ ]
+ },
+ {
+ icon: '๐',
+ title: 'Certificate Management',
+ items: [
+ 'Use descriptive certificate filenames',
+ 'Document certificate purposes',
+ 'Track certificate expiration dates',
+ 'Maintain certificate backups'
+ ]
+ },
+ {
+ icon: '๐ข',
+ title: 'Production Deployment',
+ items: [
+ 'Use proper SSL certificates when possible',
+ 'Consider Let\'s Encrypt for public instances',
+ 'Implement certificate rotation procedures',
+ 'Monitor certificate expiration'
+ ]
+ },
+ {
+ icon: '๐',
+ title: 'Troubleshooting',
+ items: [
+ 'Verify certificate format (PEM)',
+ 'Check certificate chain completeness',
+ 'Ensure proper file permissions',
+ 'Test with openssl commands'
+ ]
+ }
+ ].map(section => (
+
+
+ {section.icon}
+
{section.title}
+
+
+ {section.items.map(item => (
+ -
+ โข
+ {item}
+
+ ))}
+
+
+ ))}
+
Common Issues and Solutions
+
+
+
+
Certificate not being recognized
+
+ -
+ โข
+ Ensure the certificate is in PEM format
+
+ -
+ โข
+ Check that NODE_EXTRA_CA_CERTS points to the correct file
+
+ -
+ โข
+ Restart the application after adding certificates
+
+
+
+
+
+
Still getting SSL errors
+
+ -
+ โข
+ Verify the complete certificate chain is included
+
+ -
+ โข
+ Check if intermediate certificates are needed
+
+ -
+ โข
+ Ensure the certificate matches the server hostname
+
+
+
+
+
+
Certificate expired
+
+ -
+ โข
+ Check certificate validity:
openssl x509 -in cert.crt -noout -dates
+
+ -
+ โข
+ Update with new certificate from your CA
+
+ -
+ โข
+ Restart Gitea Mirror after updating
+
+
+
+
-
+