starred/gitea-mirror

Fork 0

mirror of https://github.com/RayLabsHQ/gitea-mirror.git synced 2026-04-25 07:15:57 +03:00

[PR #31] [MERGED] Add Multi-Method Authentication Support (OIDC, Forward Auth, Local) #105

New issue

Closed

opened 2026-02-27 15:55:09 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 15:55:09 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/RayLabsHQ/gitea-mirror/pull/31
Author: @arunavo4
Created: 6/24/2025
Status: ✅ Merged
Merged: 6/24/2025
Merged by: @arunavo4

Base: main ← Head: oidc-experiment

📝 Commits (7)

6f9b524 feat(auth): Implement multi-method authentication with JWT, OIDC, and forward auth
7e0dcdf feat(auth): Add comprehensive authentication guide and implement JWKS utilities for JWT validation
3f2d15e feat(auth): Add OIDC and Forward Authentication configurations to docker-compose files
0b665d0 Add comprehensive documentation for Gitea Mirror
a95619f feat(auth): implement dynamic OIDC configuration and setup
a19c83b test(auth): enhance forward authentication tests with async validation
b819e1f feat(auth): introduce UI-based authentication configuration and migration guide

📊 Changes

54 files changed (+6675 additions, -1502 deletions)

View changed files

📝 .env.example (+77 -36)
➕ .env.local (+50 -0)
📝 CHANGELOG.md (+22 -0)
➕ CONTRIBUTING.md (+360 -0)
➕ OIDC_TESTING_GUIDE.md (+313 -0)
📝 README.md (+70 -550)
➖ data/README.md (+0 -32)
➕ docker-compose.forward-auth.yml (+61 -0)
➕ docker-compose.oidc.yml (+60 -0)
📝 docker-compose.yml (+22 -0)
➕ docs/DEVELOPER_GUIDE.md (+408 -0)
➖ docs/GRACEFUL_SHUTDOWN.md (+0 -249)
➕ docs/README.md (+58 -0)
➖ docs/RECOVERY_IMPROVEMENTS.md (+0 -170)
➖ docs/SHUTDOWN_PROCESS.md (+0 -236)
➕ docs/SYSTEM_INTERNALS.md (+582 -0)
➕ docs/USER_GUIDE.md (+314 -0)
➕ docs/auth-migration-guide.md (+109 -0)
➕ docs/authentication-guide.md (+367 -0)
➖ docs/testing.md (+0 -127)

...and 34 more files

📄 Description

Closes #29

Summary

This PR implements a comprehensive authentication system for Gitea Mirror, adding support for enterprise SSO while maintaining the simplicity of local authentication. Users can now choose between three authentication methods based on their infrastructure needs.

Major Features

🔐 Three Authentication Methods

Local Authentication (default)
- Simple username/password with JWT tokens
- No configuration required
- Perfect for personal use or small teams
OIDC/SSO Authentication
- Full OpenID Connect implementation
- Supports Authentik, Keycloak, Auth0, Google, Azure AD, GitHub
- Automatic user provisioning
- JWKS-based token validation
Forward Authentication
- Header-based auth for reverse proxy setups
- Works with Authentik, Authelia, Traefik
- Trusted proxy validation
- Zero-config for users

🛡️ Security Enhancements

JWT signature validation using JWKS
OIDC state parameter for CSRF protection
Trusted proxy IP validation
Secure cookie flags in production
Prevention of auth method bypass attempts
Comprehensive error handling without information leakage

📚 Documentation Overhaul

Created 4 focused documentation guides (was 10+ scattered files)
Added step-by-step OIDC testing guide
Simplified README from 648 to 155 lines
Documentation now organized by audience (users, developers, operators)

🔧 Technical Improvements

Automatic database migrations system
Enhanced configuration with validation
Comprehensive test coverage
Docker compose configs for each auth method
Backward compatible with existing deployments

Breaking Changes

None. Existing installations will continue working with local authentication by default.

Configuration

Basic OIDC Setup

AUTH_METHOD=oidc
AUTH_OIDC_ISSUER_URL=https://authentik.example.com/application/o/gitea-mirror/
AUTH_OIDC_CLIENT_ID=gitea-mirror
AUTH_OIDC_CLIENT_SECRET=your-secret

Forward Auth Setup

AUTH_METHOD=forward
AUTH_FORWARD_USER_HEADER=X-Remote-User
AUTH_FORWARD_EMAIL_HEADER=X-Remote-Email
AUTH_FORWARD_TRUSTED_PROXIES=10.0.0.1

Testing

Comprehensive test suite added:

Unit tests for all auth methods
JWKS validation tests
Integration test guide with Docker
Manual testing checklist included

Migration Guide

No action required for existing users (local auth continues working)
To enable SSO: Set environment variables and restart
Database migrations run automatically
See /docs/authentication-guide.md for detailed setup

Files Changed

Core Implementation

/src/lib/auth/ - Complete auth system implementation
/src/lib/db/migrations.ts - Database migration system
/src/pages/api/auth/ - New auth endpoints
/src/middleware.ts - Auth enforcement middleware

Documentation

/docs/authentication-guide.md - Complete auth setup guide
/docs/USER_GUIDE.md - User installation guide
/docs/DEVELOPER_GUIDE.md - Developer documentation
/docs/SYSTEM_INTERNALS.md - Architecture deep dive
/README.md - Simplified and focused

Configuration

/docker-compose.yml - Added auth environment variables
/docker-compose.oidc.yml - OIDC-specific compose file
/docker-compose.forward-auth.yml - Forward auth compose file
/.env.example - Complete with all auth options

Checklist

Code follows project conventions
Tests added and passing
Documentation updated
Backward compatibility maintained
Security review completed
Docker images build successfully

Screenshots

Not applicable - backend authentication changes.

Additional Notes

This implementation was security-reviewed and includes fixes for:

Missing JWT signature validation (now uses JWKS)
Incorrect proxy validation in forward auth
Missing auth method checks in login endpoint
Missing secure cookie flags in production

All authentication methods have been tested with real providers (Authentik, Keycloak, Google).

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/RayLabsHQ/gitea-mirror/pull/31 **Author:** [@arunavo4](https://github.com/arunavo4) **Created:** 6/24/2025 **Status:** ✅ Merged **Merged:** 6/24/2025 **Merged by:** [@arunavo4](https://github.com/arunavo4) **Base:** `main` ← **Head:** `oidc-experiment` --- ### 📝 Commits (7) - [`6f9b524`](https://github.com/RayLabsHQ/gitea-mirror/commit/6f9b524339291e472021c01a1e516ae9a056ead1) feat(auth): Implement multi-method authentication with JWT, OIDC, and forward auth - [`7e0dcdf`](https://github.com/RayLabsHQ/gitea-mirror/commit/7e0dcdf8e114da08c0180bf3f1dc1320ffa1b01f) feat(auth): Add comprehensive authentication guide and implement JWKS utilities for JWT validation - [`3f2d15e`](https://github.com/RayLabsHQ/gitea-mirror/commit/3f2d15ebc19d36a732ef974b7ac8e855ea51c759) feat(auth): Add OIDC and Forward Authentication configurations to docker-compose files - [`0b665d0`](https://github.com/RayLabsHQ/gitea-mirror/commit/0b665d0f13a0d9e8e5237b1fddfc8f7cbf78b9b5) Add comprehensive documentation for Gitea Mirror - [`a95619f`](https://github.com/RayLabsHQ/gitea-mirror/commit/a95619f7156dee3b18ae130cc3f30f4a5df38f9d) feat(auth): implement dynamic OIDC configuration and setup - [`a19c83b`](https://github.com/RayLabsHQ/gitea-mirror/commit/a19c83b018b312fb22e89a26e4cd936772ee5d6c) test(auth): enhance forward authentication tests with async validation - [`b819e1f`](https://github.com/RayLabsHQ/gitea-mirror/commit/b819e1f7e282504269425aa1b00f057ddd673c2d) feat(auth): introduce UI-based authentication configuration and migration guide ### 📊 Changes **54 files changed** (+6675 additions, -1502 deletions) <details> <summary>View changed files</summary> 📝 `.env.example` (+77 -36) ➕ `.env.local` (+50 -0) 📝 `CHANGELOG.md` (+22 -0) ➕ `CONTRIBUTING.md` (+360 -0) ➕ `OIDC_TESTING_GUIDE.md` (+313 -0) 📝 `README.md` (+70 -550) ➖ `data/README.md` (+0 -32) ➕ `docker-compose.forward-auth.yml` (+61 -0) ➕ `docker-compose.oidc.yml` (+60 -0) 📝 `docker-compose.yml` (+22 -0) ➕ `docs/DEVELOPER_GUIDE.md` (+408 -0) ➖ `docs/GRACEFUL_SHUTDOWN.md` (+0 -249) ➕ `docs/README.md` (+58 -0) ➖ `docs/RECOVERY_IMPROVEMENTS.md` (+0 -170) ➖ `docs/SHUTDOWN_PROCESS.md` (+0 -236) ➕ `docs/SYSTEM_INTERNALS.md` (+582 -0) ➕ `docs/USER_GUIDE.md` (+314 -0) ➕ `docs/auth-migration-guide.md` (+109 -0) ➕ `docs/authentication-guide.md` (+367 -0) ➖ `docs/testing.md` (+0 -127) _...and 34 more files_ </details> ### 📄 Description Closes #29 ## Summary This PR implements a comprehensive authentication system for Gitea Mirror, adding support for enterprise SSO while maintaining the simplicity of local authentication. Users can now choose between three authentication methods based on their infrastructure needs. ## Major Features ### 🔐 Three Authentication Methods 1. **Local Authentication** (default) - Simple username/password with JWT tokens - No configuration required - Perfect for personal use or small teams 2. **OIDC/SSO Authentication** - Full OpenID Connect implementation - Supports Authentik, Keycloak, Auth0, Google, Azure AD, GitHub - Automatic user provisioning - JWKS-based token validation 3. **Forward Authentication** - Header-based auth for reverse proxy setups - Works with Authentik, Authelia, Traefik - Trusted proxy validation - Zero-config for users ### 🛡️ Security Enhancements - JWT signature validation using JWKS - OIDC state parameter for CSRF protection - Trusted proxy IP validation - Secure cookie flags in production - Prevention of auth method bypass attempts - Comprehensive error handling without information leakage ### 📚 Documentation Overhaul - Created 4 focused documentation guides (was 10+ scattered files) - Added step-by-step OIDC testing guide - Simplified README from 648 to 155 lines - Documentation now organized by audience (users, developers, operators) ### 🔧 Technical Improvements - Automatic database migrations system - Enhanced configuration with validation - Comprehensive test coverage - Docker compose configs for each auth method - Backward compatible with existing deployments ## Breaking Changes None. Existing installations will continue working with local authentication by default. ## Configuration ### Basic OIDC Setup ```bash AUTH_METHOD=oidc AUTH_OIDC_ISSUER_URL=https://authentik.example.com/application/o/gitea-mirror/ AUTH_OIDC_CLIENT_ID=gitea-mirror AUTH_OIDC_CLIENT_SECRET=your-secret ``` ### Forward Auth Setup ```bash AUTH_METHOD=forward AUTH_FORWARD_USER_HEADER=X-Remote-User AUTH_FORWARD_EMAIL_HEADER=X-Remote-Email AUTH_FORWARD_TRUSTED_PROXIES=10.0.0.1 ``` ## Testing Comprehensive test suite added: - Unit tests for all auth methods - JWKS validation tests - Integration test guide with Docker - Manual testing checklist included ## Migration Guide 1. No action required for existing users (local auth continues working) 2. To enable SSO: Set environment variables and restart 3. Database migrations run automatically 4. See `/docs/authentication-guide.md` for detailed setup ## Files Changed ### Core Implementation - `/src/lib/auth/` - Complete auth system implementation - `/src/lib/db/migrations.ts` - Database migration system - `/src/pages/api/auth/` - New auth endpoints - `/src/middleware.ts` - Auth enforcement middleware ### Documentation - `/docs/authentication-guide.md` - Complete auth setup guide - `/docs/USER_GUIDE.md` - User installation guide - `/docs/DEVELOPER_GUIDE.md` - Developer documentation - `/docs/SYSTEM_INTERNALS.md` - Architecture deep dive - `/README.md` - Simplified and focused ### Configuration - `/docker-compose.yml` - Added auth environment variables - `/docker-compose.oidc.yml` - OIDC-specific compose file - `/docker-compose.forward-auth.yml` - Forward auth compose file - `/.env.example` - Complete with all auth options ## Checklist - [x] Code follows project conventions - [x] Tests added and passing - [x] Documentation updated - [x] Backward compatibility maintained - [x] Security review completed - [x] Docker images build successfully ## Screenshots Not applicable - backend authentication changes. ## Additional Notes This implementation was security-reviewed and includes fixes for: - Missing JWT signature validation (now uses JWKS) - Incorrect proxy validation in forward auth - Missing auth method checks in login endpoint - Missing secure cookie flags in production All authentication methods have been tested with real providers (Authentik, Keycloak, Google). --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>