> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
gitea admin auth list
```

Customize the output format:

```bash theme={null}
gitea admin auth list --vertical-bars --min-width 10 --tab-width 8
```

### Delete Authentication Source

Remove an authentication source by ID:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

<ParamField path="name" type="string" required>
  Authentication source name
</ParamField>

<ParamField path="security-protocol" type="string" required>
  Security protocol: `unencrypted`, `ldaps`, or `starttls`
</ParamField>

<ParamField path="host" type="string" required>
  LDAP server hostname or IP address
</ParamField>

<ParamField path="port" type="number" required>
  LDAP server port (typically 389 for LDAP, 636 for LDAPS)
</ParamField>

<ParamField path="bind-dn" type="string">
  DN to bind to the LDAP server (Bind DN mode only)
</ParamField>

<ParamField path="bind-password" type="string">
  Password for the bind DN (Bind DN mode only)
</ParamField>

<ParamField path="user-search-base" type="string" required>
  LDAP base DN where user accounts are searched
</ParamField>

<ParamField path="user-filter" type="string" required>
  LDAP filter to find user records. Use `%s` as placeholder for username.
  Example: `(&(objectClass=inetOrgPerson)(uid=%s))`
</ParamField>

<ParamField path="username-attribute" type="string">
  LDAP attribute containing the username (e.g., `uid`, `sAMAccountName`)
</ParamField>

<ParamField path="firstname-attribute" type="string">
  LDAP attribute for first name (e.g., `givenName`)
</ParamField>

<ParamField path="surname-attribute" type="string">
  LDAP attribute for surname (e.g., `sn`)
</ParamField>

<ParamField path="email-attribute" type="string" required>
  LDAP attribute for email address (e.g., `mail`)
</ParamField>

<ParamField path="public-ssh-key-attribute" type="string">
  LDAP attribute containing SSH public keys
</ParamField>

<ParamField path="avatar-attribute" type="string">
  LDAP attribute containing user avatar image
</ParamField>

<ParamField path="admin-filter" type="string">
  LDAP filter to identify admin users
</ParamField>

<ParamField path="restricted-filter" type="string">
  LDAP filter to identify restricted users
</ParamField>

<ParamField path="skip-tls-verify" type="boolean" default="false">
  Skip TLS certificate verification (not recommended for production)
</ParamField>

<ParamField path="synchronize-users" type="boolean" default="false">
  Enable periodic user synchronization
</ParamField>

<ParamField path="page-size" type="number">
  LDAP search page size for pagination
</ParamField>

#### Group Mapping

Map LDAP groups to Gitea organization teams:

```bash theme={null}
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:

```bash theme={null}
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

<CodeGroup>
  ```bash GitHub theme={null}
  gitea admin auth add-oauth \
    --name "GitHub" \
    --provider github \
    --key "your-client-id" \
    --secret "your-client-secret"
  ```

  ```bash GitLab theme={null}
  gitea admin auth add-oauth \
    --name "GitLab" \
    --provider gitlab \
    --key "your-application-id" \
    --secret "your-secret"
  ```

  ```bash Google theme={null}
  gitea admin auth add-oauth \
    --name "Google" \
    --provider google \
    --key "your-client-id.apps.googleusercontent.com" \
    --secret "your-client-secret"
  ```

  ```bash OpenID Connect theme={null}
  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"
  ```
</CodeGroup>

### OAuth2 Configuration Options

<ParamField path="name" type="string" required>
  Authentication source display name
</ParamField>

<ParamField path="provider" type="string" required>
  OAuth2 provider: `github`, `gitlab`, `google`, `azure`, `bitbucket`, `discord`, `gitea`, `openidConnect`, etc.
</ParamField>

<ParamField path="key" type="string" required>
  OAuth2 client ID
</ParamField>

<ParamField path="secret" type="string" required>
  OAuth2 client secret
</ParamField>

<ParamField path="auto-discover-url" type="string">
  OpenID Connect auto-discovery URL (required for `openidConnect` provider)
</ParamField>

<ParamField path="scopes" type="string">
  Comma-separated OAuth2 scopes to request
</ParamField>

<ParamField path="icon-url" type="string">
  Custom icon URL for the login button
</ParamField>

<ParamField path="skip-local-2fa" type="boolean" default="false">
  Skip Gitea's 2FA for users authenticated via this source
</ParamField>

### Custom OAuth2 Endpoints

For self-hosted OAuth2 providers:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

<ParamField path="name" type="string" required>
  Authentication source name
</ParamField>

<ParamField path="auth-type" type="string" default="PLAIN">
  SMTP authentication type: `PLAIN`, `LOGIN`, or `CRAM-MD5`
</ParamField>

<ParamField path="host" type="string" required>
  SMTP server hostname
</ParamField>

<ParamField path="port" type="number" required>
  SMTP server port (typically 25, 465, or 587)
</ParamField>

<ParamField path="force-smtps" type="boolean" default="false">
  Force SMTPS on all ports (normally only port 465)
</ParamField>

<ParamField path="skip-verify" type="boolean" default="false">
  Skip TLS certificate verification
</ParamField>

<ParamField path="helo-hostname" type="string">
  Hostname sent with HELO command (defaults to current hostname)
</ParamField>

<ParamField path="disable-helo" type="boolean" default="false">
  Disable SMTP HELO command
</ParamField>

<ParamField path="allowed-domains" type="string">
  Comma-separated list of allowed email domains. Leave empty to allow all.
</ParamField>

### Update SMTP Source

```bash theme={null}
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`:

```ini theme={null}
[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:

```ini theme={null}
[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:

<Steps>
  <Step title="Verify Source is Active">
    ```bash theme={null}
    gitea admin auth list
    ```

    Ensure the "Enabled" column shows `true`
  </Step>

  <Step title="Test Login">
    Attempt to log in via the web interface using credentials from the authentication source
  </Step>

  <Step title="Check Logs">
    Monitor logs for authentication errors:

    ```bash theme={null}
    tail -f /var/log/gitea/gitea.log
    ```
  </Step>
</Steps>

## 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](/admin/configuration)
* [Command-Line Tools](/admin/command-line)
* [Database Setup](/admin/database)