Skip to main content

​
Overview

Gitea supports multiple authentication methods including LDAP, OAuth2, SMTP, and PAM. Authentication sources can be managed through the web interface or command-line.

​
Managing Authentication Sources

​
List Authentication Sources

View all configured authentication sources: 
gitea admin auth list
Customize the output format: 
gitea admin auth list --vertical-bars --min-width 10 --tab-width 8

​
Delete Authentication Source

Remove an authentication source by ID: 
gitea admin auth delete --id 1

​
LDAP Authentication

Gitea supports two LDAP authentication modes:
  1. Bind DN - Search for users using a service account
  2. Simple Auth - Authenticate directly with user credentials

​
LDAP via Bind DN

​
Add LDAP Source

gitea admin auth add-ldap \
  --name "Corporate LDAP" \
  --security-protocol ldaps \
  --host ldap.example.com \
  --port 636 \
  --bind-dn "cn=gitea,ou=service,dc=example,dc=com" \
  --bind-password "service-password" \
  --user-search-base "ou=users,dc=example,dc=com" \
  --user-filter "(&(objectClass=inetOrgPerson)(memberOf=cn=gitea-users,ou=groups,dc=example,dc=com))" \
  --username-attribute uid \
  --firstname-attribute givenName \
  --surname-attribute sn \
  --email-attribute mail

​
Update LDAP Source

gitea admin auth update-ldap \
  --id 1 \
  --security-protocol ldaps \
  --user-filter "(&(objectClass=inetOrgPerson)(memberOf=cn=developers,ou=groups,dc=example,dc=com))"

​
LDAP Configuration Options

​
name
string
required
Authentication source name
​
security-protocol
string
required
Security protocol: unencrypted, ldaps, or starttls
​
host
string
required
LDAP server hostname or IP address
​
port
number
required
LDAP server port (typically 389 for LDAP, 636 for LDAPS)
​
bind-dn
string
DN to bind to the LDAP server (Bind DN mode only)
​
bind-password
string
Password for the bind DN (Bind DN mode only)
​
user-search-base
string
required
LDAP base DN where user accounts are searched
​
user-filter
string
required
LDAP filter to find user records. Use %s as placeholder for username. Example: (&(objectClass=inetOrgPerson)(uid=%s))
​
username-attribute
string
LDAP attribute containing the username (e.g., uid, sAMAccountName)
​
firstname-attribute
string
LDAP attribute for first name (e.g., givenName)
​
surname-attribute
string
LDAP attribute for surname (e.g., sn)
​
email-attribute
string
required
LDAP attribute for email address (e.g., mail)
​
public-ssh-key-attribute
string
LDAP attribute containing SSH public keys
​
avatar-attribute
string
LDAP attribute containing user avatar image
​
admin-filter
string
LDAP filter to identify admin users
​
restricted-filter
string
LDAP filter to identify restricted users
​
skip-tls-verify
boolean
default:"false"
Skip TLS certificate verification (not recommended for production)
​
synchronize-users
boolean
default:"false"
Enable periodic user synchronization
​
page-size
number
LDAP search page size for pagination

​
Group Mapping

Map LDAP groups to Gitea organization teams: 
gitea admin auth add-ldap \
  --name "LDAP with Groups" \
  --enable-groups \
  --group-search-base-dn "ou=groups,dc=example,dc=com" \
  --group-member-attribute member \
  --group-user-attribute dn \
  --group-filter "(objectClass=groupOfNames)" \
  --group-team-map '{"cn=developers,ou=groups,dc=example,dc=com": {"myorg": ["developers"]}}' \
  --group-team-map-removal
  # ... other LDAP options

​
LDAP Simple Auth

For LDAP servers where you can construct the user DN directly: 
gitea admin auth add-ldap-simple \
  --name "Simple LDAP" \
  --security-protocol ldaps \
  --host ldap.example.com \
  --port 636 \
  --user-dn "uid=%s,ou=users,dc=example,dc=com" \
  --user-filter "(uid=%s)" \
  --email-attribute mail

​
OAuth2 Authentication

Configure OAuth2 providers like GitHub, GitLab, Google, or custom OpenID Connect providers.

​
Add OAuth2 Source

gitea admin auth add-oauth \
  --name "GitHub" \
  --provider github \
  --key "your-client-id" \
  --secret "your-client-secret"

​
OAuth2 Configuration Options

​
name
string
required
Authentication source display name
​
provider
string
required
OAuth2 provider: github, gitlab, google, azure, bitbucket, discord, gitea, openidConnect, etc.
​
key
string
required
OAuth2 client ID
​
secret
string
required
OAuth2 client secret
​
auto-discover-url
string
OpenID Connect auto-discovery URL (required for openidConnect provider)
​
scopes
string
Comma-separated OAuth2 scopes to request
​
icon-url
string
Custom icon URL for the login button
​
skip-local-2fa
boolean
default:"false"
Skip Gitea’s 2FA for users authenticated via this source

​
Custom OAuth2 Endpoints

For self-hosted OAuth2 providers: 
gitea admin auth add-oauth \
  --name "Self-hosted GitLab" \
  --provider gitlab \
  --key "client-id" \
  --secret "client-secret" \
  --use-custom-urls true \
  --custom-auth-url "https://gitlab.example.com/oauth/authorize" \
  --custom-token-url "https://gitlab.example.com/oauth/token" \
  --custom-profile-url "https://gitlab.example.com/api/v4/user"

​
OAuth2 Claims and Groups

gitea admin auth add-oauth \
  --name "OIDC with Claims" \
  --provider openidConnect \
  --key "client-id" \
  --secret "client-secret" \
  --auto-discover-url "https://auth.example.com/.well-known/openid-configuration" \
  --required-claim-name "groups" \
  --required-claim-value "gitea-users" \
  --group-claim-name "groups" \
  --admin-group "gitea-admins" \
  --restricted-group "gitea-restricted" \
  --group-team-map '{"developers": {"myorg": ["dev-team"]}}'

​
Update OAuth2 Source

gitea admin auth update-oauth \
  --id 2 \
  --name "Updated GitHub" \
  --key "new-client-id" \
  --secret "new-client-secret"

​
SMTP Authentication

Allow users to authenticate using their email credentials via SMTP.

​
Add SMTP Source

gitea admin auth add-smtp \
  --name "Corporate Email" \
  --auth-type PLAIN \
  --host mail.example.com \
  --port 587 \
  --allowed-domains "example.com,example.org"

​
SMTP Configuration Options

​
name
string
required
Authentication source name
​
auth-type
string
default:"PLAIN"
SMTP authentication type: PLAIN, LOGIN, or CRAM-MD5
​
host
string
required
SMTP server hostname
​
port
number
required
SMTP server port (typically 25, 465, or 587)
​
force-smtps
boolean
default:"false"
Force SMTPS on all ports (normally only port 465)
​
skip-verify
boolean
default:"false"
Skip TLS certificate verification
​
helo-hostname
string
Hostname sent with HELO command (defaults to current hostname)
​
disable-helo
boolean
default:"false"
Disable SMTP HELO command
​
allowed-domains
string
Comma-separated list of allowed email domains. Leave empty to allow all.

​
Update SMTP Source

gitea admin auth update-smtp \
  --id 3 \
  --port 465 \
  --force-smtps

​
Configuration via app.ini

While the CLI is recommended, you can also configure authentication in app.ini: 
[service]
; Disable registration after creating users via authentication sources
DISABLE_REGISTRATION = false

; Require email confirmation for registration
REGISTER_EMAIL_CONFIRM = true

; Require manual admin approval for new registrations
REGISTER_MANUAL_CONFIRM = false

​
Two-Factor Authentication

Configure 2FA policies: 
[service]
; Require 2FA for all users
REQUIRE_SIGNIN_VIEW = false

[security]
; Disable non-admin users from adding 2FA
DISABLE_2FA = false

​
Testing Authentication

After configuring an authentication source:
1

Verify Source is Active

gitea admin auth list
Ensure the “Enabled” column shows true
2

Test Login

Attempt to log in via the web interface using credentials from the authentication source
3

Check Logs

Monitor logs for authentication errors:
tail -f /var/log/gitea/gitea.log

​
Best Practices

  • Use LDAPS/StartTLS: Always encrypt LDAP connections in production
  • Restrict Filters: Use LDAP filters to limit which users can authenticate
  • Test Separately: Test authentication sources in a non-production environment first
  • Group Mapping: Use group mapping to automatically assign team memberships
  • Monitor Sync: Enable user synchronization to keep LDAP users up-to-date
  • Backup Sources: Export authentication configuration before making changes

Build docs developers (and LLMs) love

Get started for freeTalk to us