Authentication

Configure external authentication sources for Gitea

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

GitHub

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

gitea admin auth add-oauth \
  --name "GitLab" \
  --provider gitlab \
  --key "your-application-id" \
  --secret "your-secret"

gitea admin auth add-oauth \
  --name "Google" \
  --provider google \
  --key "your-client-id.apps.googleusercontent.com" \
  --secret "your-client-secret"

gitea admin auth add-oauth \
  --name "Custom OIDC" \
  --provider openidConnect \
  --key "client-id" \
  --secret "client-secret" \
  --auto-discover-url "https://auth.example.com/.well-known/openid-configuration"

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

Related Resources

• Configuration
• Command-Line Tools
• Database Setup