Authentik mit Gitea verbinden — OAuth2 Single Sign-On für euren Git-Server

Gitea mit Authentik per OAuth2 verbinden: Single Sign-On für euren Self-Hosted Git-Server. OAuth2-Source einrichten, Auto-Registration und bestehende Accounts verknüpfen.

💡 Hinweis: Dieses Tutorial setzt voraus, dass du bereits Gitea und Authentik auf deinem Server laufen hast. Beide müssen über HTTPS erreichbar sein.

Einleitung — Warum SSO für Gitea?

Gitea bringt eine eigene User-Datenbank mit. Bei einem Solo-Setup ist das egal — bei mehreren Entwicklern wird es schnell unübersichtlich. Neue Mitarbeiter? Account in Gitea anlegen. Mitarbeiter geht? Account in Gitea löschen, Passwort in eurem Passwort-Manager invalidieren. Bei zehn Self-Hosted-Diensten habt ihr zehn Stellen, an denen ihr User pflegen müsst.

Mit Authentik als Identity Provider übernimmt Gitea einfach die User aus Authentik. Anlegen, deaktivieren, 2FA, Passwort-Policies — alles zentral. Gitea bekommt nur das Login-Token.

Was diese Integration bringt

Ein Login für Gitea, Vaultwarden, Nextcloud und alle anderen Self-Hosted-Dienste
Zentrale 2FA — In Authentik einmal konfiguriert, gilt für Gitea automatisch
Auto-Registration — Erste Anmeldung legt automatisch einen Gitea-User an
Gruppen-Sync — Authentik-Gruppen können Gitea-Berechtigungen steuern
Account-Lifecycle — User in Authentik deaktivieren = sofort kein Gitea-Zugriff

In diesem Guide bauen wir die Verbindung Schritt für Schritt auf.

Voraussetzungen

Authentik unter eigener Domain (z.B. auth.example.com)
Gitea unter eigener Domain (z.B. git.example.com)
Beide mit gültigem SSL-Zertifikat
Admin-Zugriff auf beide
Gitea Version 1.20+ (OAuth2-Source-Provider stabil ab 1.20)

Gitea-Version prüfen

# Wenn Gitea als systemd-Service läuft
gitea --version

# Wenn Gitea als Docker-Container läuft
docker exec gitea gitea --version

# Wenn Gitea als systemd-Service läuft
gitea --version

# Wenn Gitea als Docker-Container läuft
docker exec gitea gitea --version

Falls eure Version älter ist, vorher updaten — siehe Gitea-Tutorial.

Schritt 1: OAuth2-Provider in Authentik anlegen

Loggt euch ins Authentik Admin Interface unter https://auth.example.com ein.

Provider erstellen

Applications → Providers → Create
Wählt OAuth2/OpenID Provider
Konfiguration:
- Name: gitea-provider
- Authorization flow: default-provider-authorization-implicit-consent
- Client type: Confidential
- Client ID: Wird automatisch generiert — gleich kopieren
- Client Secret: Wird automatisch generiert — gleich kopieren
- Redirect URIs / Origins: https://git.example.com/user/oauth2/authentik/callback
- Signing Key: authentik Self-signed Certificate
Advanced Settings:
- Subject mode: Based on the User's username
- Include claims in id_token: aktiviert
Create

⚠️ Wichtig: Die Redirect-URI hat das Format https://EUER_GITEA/user/oauth2/EUER_PROVIDER_NAME/callback. Der EUER_PROVIDER_NAME-Teil muss später in Gitea exakt so heißen, wie ihr ihn hier in der URI angebt — wir nehmen authentik.

Application erstellen

Applications → Applications → Create
Konfiguration:
- Name: Gitea
- Slug: gitea
- Provider: gitea-provider
- Launch URL: https://git.example.com
Create

Verbindungsdaten merken

Klickt auf den Provider → Tab Overview. Notiert euch:

Client ID:                    [aus Provider-Übersicht]
Client Secret:                [aus Provider-Übersicht]
OpenID Configuration URL:     https://auth.example.com/application/o/gitea/.well-known/openid-configuration

Client ID:                    [aus Provider-Übersicht]
Client Secret:                [aus Provider-Übersicht]
OpenID Configuration URL:     https://auth.example.com/application/o/gitea/.well-known/openid-configuration

Schritt 2: OAuth2-Source in Gitea anlegen

Loggt euch in Gitea als Administrator ein.

Site Administration → Authentication Sources → Add Authentication Source
Konfiguration:
- Authentication Type: OAuth2
- Authentication Name: authentik (muss exakt mit der Redirect-URI übereinstimmen!)
- OAuth2 Provider: OpenID Connect
- Client ID (Key): Aus Authentik
- Client Secret: Aus Authentik
- OpenID Connect Auto Discovery URL: https://auth.example.com/application/o/gitea/.well-known/openid-configuration
- Icon URL (optional): https://goauthentik.io/img/icon.png
- Skip Local 2FA: aktivieren (2FA läuft jetzt über Authentik)
Add Authentication Source

💡 Hinweis: Skip Local 2FA ist wichtig — sonst fragt Gitea nach SSO trotzdem nochmal nach 2FA, was den ganzen Sinn von zentralem 2FA aushebelt.

Loggt euch in Gitea aus, dann öffnet https://git.example.com neu.

Auf der Login-Seite seht ihr jetzt einen zusätzlichen Button Sign in with authentik (mit Authentik-Icon).

Klick auf den Button
Weiterleitung zu auth.example.com
Login mit eurem Authentik-User
Authentik fragt einmalig nach Zustimmung → Ja
Zurück bei Gitea — eingeloggt

Bei der ersten Anmeldung

Wenn ihr einen neuen User per SSO anmeldet, fragt Gitea einmalig nach:

Username — Wird aus Authentik vorbelegt, kann angepasst werden
E-Mail — Wird aus Authentik übernommen

Bestätigen → der Gitea-Account wird automatisch angelegt und mit der Authentik-Identität verknüpft.

✅ Geschafft! Gitea authentifiziert über Authentik. User-Anlage, 2FA und Lifecycle laufen zentral.

Schritt 4: Bestehende Gitea-Accounts mit Authentik verknüpfen

Wenn ihr Gitea schon länger nutzt und bestehende User habt, müssen die ihre Accounts einmalig verknüpfen.

Per User selbst

User loggt sich klassisch in Gitea ein
Settings → Security → Manage OAuth2 (oder direkt: Account Linking)
Klickt auf Link with authentik
SSO-Flow läuft → User-Match per E-Mail

Ab jetzt funktioniert sowohl klassischer Login als auch SSO. Eine Anmeldung über den Sign in with authentik-Button reicht.

Per Admin (wenn User nicht mehr klassisch einloggen kann)

In Gitea als Admin:

Site Administration → User Accounts → [User] öffnen
Im Authentication Source auf authentik umstellen
Login Name auf den Authentik-Username setzen

Damit ist der bestehende Gitea-User direkt mit dem entsprechenden Authentik-User verknüpft.

Wenn alle User SSO nutzen, könnt ihr den klassischen Login komplett abschalten.

sudo nano /etc/gitea/app.ini

sudo nano /etc/gitea/app.ini

(Bei Docker-Setup: in das gemountete Config-Volume schauen.)

Im [service]-Block:

[service]
DISABLE_REGISTRATION = true
ALLOW_ONLY_EXTERNAL_REGISTRATION = true
SHOW_REGISTRATION_BUTTON = false

[openid]
ENABLE_OPENID_SIGNIN = true
ENABLE_OPENID_SIGNUP = true

[service]
DISABLE_REGISTRATION = true
ALLOW_ONLY_EXTERNAL_REGISTRATION = true
SHOW_REGISTRATION_BUTTON = false

[openid]
ENABLE_OPENID_SIGNIN = true
ENABLE_OPENID_SIGNUP = true

Gitea neu starten:

sudo systemctl restart gitea

sudo systemctl restart gitea

Oder bei Docker:

cd /opt/gitea && sudo docker compose restart

cd /opt/gitea && sudo docker compose restart

⚠️ Wichtig: Wenn ihr ALLOW_ONLY_EXTERNAL_REGISTRATION = true setzt und gleichzeitig kein Notfall-Admin-Account mehr klassisch funktioniert, sperrt ihr euch aus, falls Authentik mal ausfällt. Behaltet mindestens einen lokalen Admin-Account aktiv.

Schritt 6: Auto-Registration für neue User

Wenn ihr wollt, dass jeder neue Authentik-User automatisch einen Gitea-Account bekommt:

In app.ini:

[oauth2_client]
USERNAME = nickname
UPDATE_AVATAR = true
ACCOUNT_LINKING = auto

[oauth2_client]
USERNAME = nickname
UPDATE_AVATAR = true
ACCOUNT_LINKING = auto

USERNAME — woher der Gitea-Username kommt (nickname, preferred_username oder email)
UPDATE_AVATAR — Avatar aus Authentik übernehmen
ACCOUNT_LINKING = auto — Existierende Accounts automatisch per E-Mail verknüpfen

Ab jetzt: Erste Anmeldung eines neuen Authentik-Users → Gitea-Account wird ohne weitere Bestätigung erstellt.

Schritt 7: Gruppen-Sync (optional)

Authentik-Gruppen können Gitea-Berechtigungen steuern — z.B. „Authentik-Gruppe developers“ → „Gitea-Organization dev-team„.

Schritt 1: Authentik-Mapping konfigurieren

In Authentik:

Customisation → Property Mappings → Create
Scope Mapping
Konfiguration:
- Name: gitea-groups-mapping
- Scope name: groups
- Description: Authentik groups for Gitea
- Expression:

return {
    "groups": [group.name for group in user.ak_groups.all()],
}

return {
    "groups": [group.name for group in user.ak_groups.all()],
}

Save

Schritt 2: Mapping in Provider aktivieren

Applications → Providers → gitea-provider öffnen
Edit → Advanced Settings
Bei Scopes das gitea-groups-mapping hinzufügen
Update

Schritt 3: Gitea-Source updaten

In Gitea Site Administration → Authentication Sources → authentik öffnen → Required Claim Name und Group Claim Name auf groups setzen.

Damit landen Authentik-Gruppen als Claim im Token, und Gitea kann sie auswerten.

💡 Tipp: Gruppen-Sync wird interessant, wenn ihr ein Team mit klaren Rollen habt. Bei Solo-Setups oder kleinen Setups (< 5 User) ist der manuelle Weg meist einfacher.

Schritt 8: 2FA über Authentik

Wenn in Authentik MFA-Stages konfiguriert sind (siehe Authentik-Tutorial), greift 2FA automatisch beim SSO-Login.

Gitea-eigene 2FA deaktivieren

Pro User:

User Settings → Security → Two-Factor Authentication → Disable

Bei Admin-Übersicht: Site Administration → User Accounts → User-2FA-Status sichtbar.

⚠️ Best Practice: 2FA in Gitea erst deaktivieren, nachdem ihr mehrfach erfolgreich per SSO mit Authentik-2FA eingeloggt habt. Sonst Lock-out-Risiko.

Troubleshooting

„Cannot find authentication source“

Der Authentication Name in Gitea muss exakt dem Pfad in der Redirect-URI entsprechen. Wenn die Redirect-URI /user/oauth2/authentik/callback ist, muss der Name authentik sein — case-sensitive.

„Invalid redirect_uri“

In Authentik die Redirect-URI auf genau den Wert prüfen, den Gitea aufruft
Trailing-Slash beachten

„Failed to authenticate user“

# Gitea-Logs
sudo journalctl -u gitea -f

# Bei Docker
sudo docker compose logs -f gitea

# Gitea-Logs
sudo journalctl -u gitea -f

# Bei Docker
sudo docker compose logs -f gitea

Häufige Ursachen:

OpenID Discovery URL nicht erreichbar von Gitea aus
Falsches Client Secret eingetragen
Authentik Worker-Container nicht erreichbar

Im Authentik Subject mode auf Based on the User's username setzen. In Gitea app.ini: USERNAME = preferred_username testen.

„Account already exists with this email“

Existierender Gitea-User mit gleicher E-Mail. Lösungen:

ACCOUNT_LINKING = auto setzen → automatisches Matching
Oder manuell verknüpfen (siehe Schritt 4)

Avatare werden nicht synchronisiert

UPDATE_AVATAR = true in app.ini? Plus: User in Authentik hat einen Avatar hinterlegt?

Zusammenfassung & Checkliste

Schritt	Status
Authentik läuft unter eigener Domain	☐
Gitea läuft unter eigener Domain	☐
OAuth2-Provider in Authentik angelegt	☐
Application in Authentik erstellt	☐
Client ID & Secret kopiert	☐
OAuth2-Source in Gitea angelegt	☐
Skip Local 2FA in Gitea aktiviert	☐
Erster SSO-Login erfolgreich	☐
Bestehende User-Accounts verknüpft	☐
Auto-Registration konfiguriert	☐
2FA über Authentik getestet	☐
Lokaler Login deaktiviert (optional)	☐
Notfall-Admin-Account dokumentiert	☐

Nächste Schritte

Authentik mit Vaultwarden — Passwort-Manager mit SSO
Authentik mit Nextcloud — App per OIDC-App in Nextcloud
Federation — GitHub/Google als Authentik-Login-Quelle
Gitea Actions — CI/CD für eure Repos

Habt ihr Fragen oder Probleme? Schreibt es in die Kommentare — ich helfe gerne!