What Authentication Methods Are Available in Gitea: A Complete Technical Guide

Gitea supports nine distinct authentication methods including local username/password, LDAP (simple and bind variations), SMTP, PAM, OAuth2/OpenID Connect, Windows SSPI, WebAuthn passkeys, and API token authentication, all orchestrated through a pluggable login source architecture centered on models/auth/source.go.

Gitea is a self-hosted Git service that provides a flexible, extensible authentication framework designed to integrate with enterprise identity providers and modern security standards. According to the go-gitea/gitea source code, the platform organizes authentication around login sources—configurable backends defined in models/auth/source.go that determine how user credentials are verified and mapped to local user accounts.

Login Source Architecture

The foundation of Gitea's authentication system is the Source struct defined in models/auth/source.go. Each authentication backend is represented as a row in the login_source table with a numeric Type field that determines the specific implementation used during credential verification.

The architecture uses a pluggable configuration pattern where each authentication method implements the Config interface with Convert and SetAuthSource methods. This design, utilizing the registeredConfigs registry, allows new authentication mechanisms to be added without modifying the core login flow in services/auth/signin.go.

When a login attempt occurs, Gitea iterates over enabled login sources and invokes the source-specific Authenticate method. Upon successful authentication, the system creates or updates a local User record with the LoginType field set to the corresponding source type.

Local and Directory-Based Authentication

Username and Password (Plain)

The simplest authentication method uses local accounts stored directly in the Gitea database. This Plain type requires no external configuration and serves as the default when no external login sources are defined. Credentials are verified against Gitea's internal password hashing mechanism in the user table.

LDAP and Direct LDAP (DLDAP)

Gitea provides comprehensive LDAP integration through two distinct modes implemented in services/auth/source/ldap/source_authenticate.go:

• LDAP (BindDN): Connects to an LDAP directory using a service account to search for users before authenticating with the user's credentials
• DLDAP (Direct LDAP): Performs a simple bind directly with the user's distinguished name and password without requiring a service account

Both modes are handled in the same source file, with the authentication logic checking source.AuthSource.Type == auth.DLDAP to determine which bind strategy to execute. Configuration options include attribute mappings for username, email, and display name.

SMTP Authentication

The SMTP authentication method, implemented in services/auth/source/smtp/source_authenticate.go, validates credentials against an external mail server. This is useful for organizations that use their email infrastructure as the primary identity provider. Gitea attempts to authenticate against the configured SMTP host using the provided username and password, treating successful mail server authentication as valid application login.

PAM (Pluggable Authentication Modules)

For Linux and Unix deployments, Gitea supports PAM authentication via services/auth/source/pam/source_authenticate.go. This method delegates credential verification to the underlying operating system's authentication stack, allowing Gitea to leverage existing system accounts, Kerberos tickets, or any other PAM-configured authentication mechanism.

External Identity Providers

OAuth2 and OpenID Connect

Gitea supports OAuth2 and OpenID Connect through a provider-based architecture. Provider registration occurs in services/auth/source/oauth2/providers.go, while source registration is handled in services/auth/source/oauth2/source_register.go.

This implementation supports major providers including GitHub, GitLab, Google, Microsoft, and generic OIDC servers. The Source struct implements the Config interface to store client credentials, scopes, and discovery URLs. When configured, Gitea redirects unauthenticated users to the external provider and creates local accounts based on the returned identity claims.

// Register a new OAuth2 source
authSource := &models.AuthSource{
    Type:     auth.OAuth2,
    Name:     "GitHub",
    IsActive: true,
    Cfg: &oauth2.Source{
        Provider: "github",
        ClientID: "YOUR_CLIENT_ID",
        Secret:   "YOUR_CLIENT_SECRET",
    },
}

Windows SSPI

For Windows environments, Gitea implements SSPI (Security Support Provider Interface) in services/auth/source/sspiauth_windows.go (with a POSIX no-op variant in sspiauth_posix.go). This enables Integrated Windows Authentication, allowing domain-joined clients to authenticate seamlessly using their Windows credentials without manually entering usernames and passwords.

Multi-Factor and Passwordless Authentication

WebAuthn Passkeys

Gitea supports WebAuthn (FIDO2) for passwordless and second-factor authentication through modules/auth/webauthn/webauthn.go. The system initializes a WebAuthn singleton from settings and manages user credentials via modules/auth/webauthn/user.go.

When a user registers a passkey, Gitea stores the credential using auth.InsertWebAuthnCredential. During subsequent authentication attempts, the system retrieves stored credentials via auth.GetWebAuthnCredentialsByUID and challenges the authenticator to verify possession of the private key.

API and Git Access Authentication

Token and HTTP Basic Authentication

For programmatic access and Git operations over HTTP, Gitea implements API token and HTTP Basic authentication in modules/auth/httpauth/httpauth.go. The parser extracts credentials from Authorization headers in the format Authorization: token <TOKEN> or standard Basic Auth.

Personal access tokens are treated as passwords in Git clone operations:

git clone https://git.example.com/user/repo.git

# Username: your-username

# Password: <personal-access-token>

Internally, httpauth.ParseAuthorizationHeader maps the token to the internal user session, enabling seamless integration with existing Git tooling while maintaining security through token revocation.

Configuration Examples

Adding an LDAP Source

{
  "type": "ldap",
  "name": "Corporate LDAP",
  "host": "ldap.example.com:636",
  "security_protocol": "LDAPS",
  "bind_dn": "cn=admin,dc=example,dc=com",
  "bind_password": "********",
  "attribute_username": "uid",
  "attribute_name": "cn",
  "attribute_surname": "sn",
  "attribute_mail": "mail"
}

This JSON configuration is stored in login_source.Cfg and processed by services/auth/source/ldap/source_authenticate.go when users attempt to log in.

Summary

Gitea provides a comprehensive authentication framework that balances flexibility with security:

• Nine authentication methods are available: Plain, LDAP, DLDAP, SMTP, PAM, OAuth2, SSPI, WebAuthn, and API tokens
• Pluggable architecture centered on models/auth/source.go allows new methods without core code changes
• Enterprise integration through LDAP, OAuth2, and Windows SSPI support
• Modern security standards including WebAuthn passkeys for passwordless authentication in modules/auth/webauthn/webauthn.go
• Unified API access via HTTP Basic Auth and personal access tokens parsed in modules/auth/httpauth/httpauth.go

Frequently Asked Questions

How does Gitea determine which authentication source to use?

Gitea iterates through all enabled login sources as implemented in services/auth/signin.go. For each source, it calls the type-specific Authenticate method until one succeeds. The order of sources can be configured in the administration panel, and each source has an IsActive flag to enable or disable it without deleting the configuration.

Can multiple LDAP servers be configured simultaneously?

Yes. Gitea's authentication architecture supports multiple concurrent login sources of the same type. You can configure multiple LDAP sources (such as BindDN and Direct LDAP) or multiple OAuth2 providers. Each source is evaluated independently during the login process, and users are associated with the specific source that authenticated them through the LoginType field in the user model.

What is the difference between DLDAP and standard LDAP in Gitea?

Standard LDAP (type LDAP) uses a service account (BindDN) to connect to the directory, search for the user, then authenticate with the user's credentials. Direct LDAP (type DLDAP) skips the service account and performs a simple bind directly using the user's distinguished name and password. DLDAP is suitable for directories that allow anonymous searches or when the user DN follows a predictable pattern, while standard LDAP is preferred for complex directory structures requiring administrative search privileges.

How are WebAuthn credentials stored and verified?

WebAuthn credentials are stored in the database via auth.GetWebAuthnCredentialsByUID and auth.InsertWebAuthnCredential, as implemented in the modules/auth/webauthn package. During authentication, Gitea retrieves the user's stored credentials from webauthn.Credential records and challenges the authenticator to prove possession of the private key. The verification logic resides in modules/auth/webauthn/webauthn.go and validates the cryptographic signature against the stored public key credential.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}