Authentication

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:

Bind DN - Search for users using a service account
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:

Verify Source is Active

gitea admin auth list

Ensure the “Enabled” column shows true

Test Login

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

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

Documentation Index

​Overview

​Managing Authentication Sources

​List Authentication Sources

​Delete Authentication Source

​LDAP Authentication

​LDAP via Bind DN

​Add LDAP Source

​Update LDAP Source

​LDAP Configuration Options

​Group Mapping

​LDAP Simple Auth

​OAuth2 Authentication

​Add OAuth2 Source

​OAuth2 Configuration Options

​Custom OAuth2 Endpoints

​OAuth2 Claims and Groups

​Update OAuth2 Source

​SMTP Authentication

​Add SMTP Source

​SMTP Configuration Options

​Update SMTP Source

​Configuration via app.ini

​Two-Factor Authentication

​Testing Authentication

​Best Practices

​Related Resources

Overview

Managing Authentication Sources

List Authentication Sources

Delete Authentication Source

LDAP Authentication

LDAP via Bind DN

Add LDAP Source

Update LDAP Source

LDAP Configuration Options

Group Mapping

LDAP Simple Auth

OAuth2 Authentication

Add OAuth2 Source

OAuth2 Configuration Options

Custom OAuth2 Endpoints

OAuth2 Claims and Groups

Update OAuth2 Source

SMTP Authentication

Add SMTP Source

SMTP Configuration Options

Update SMTP Source

Configuration via app.ini

Two-Factor Authentication

Testing Authentication

Best Practices

Related Resources