身份验证

LDAP（轻型目录访问协议）

LDAP 通过 BindDN 和简单身份验证 LDAP 共享以下字段

• 授权名称 （必需）

  • 分配给新授权方法的名称。

• 主机 （必需）

  • 可以访问 LDAP 服务器的地址。
  • 示例：mydomain.com

• 端口 （必需）

  • 连接到服务器时使用的端口。
  • 示例：389 用于 LDAP 或 636 用于 LDAP SSL

• 启用 TLS 加密（可选）

  • 是否在连接到 LDAP 服务器时使用 TLS。

• 管理员过滤器（可选）

  • 指定用户是否应获得管理员权限的 LDAP 过滤器。如果用户帐户通过过滤器，该用户将被授予管理员权限。
  • 示例：(objectClass=adminAccount)
  • Microsoft Active Directory (AD) 的示例：(memberOf=CN=admin-group,OU=example,DC=example,DC=org)

• 用户名属性（可选）

  • 包含用户名的用户 LDAP 记录的属性。第一次成功登录后，给定的属性值将用于新的 Gitea 帐户用户名。保留为空以使用登录表单上提供的登录名。
  • 当提供的登录名与多个属性匹配时，这很有用，但应仅使用单个特定属性作为 Gitea 帐户名，请参阅“用户过滤器”。
  • 示例：uid
  • Microsoft Active Directory (AD) 的示例：sAMAccountName

• 名字属性（可选）

  • 包含用户姓名的用户 LDAP 记录的属性。这将用于填充其帐户信息。
  • 示例：givenName

• 姓氏属性（可选）

  • 包含用户姓氏的用户 LDAP 记录的属性。这将用于填充其帐户信息。
  • 示例：sn

• 电子邮件属性 （必需）

  • 包含用户电子邮件地址的用户 LDAP 记录的属性。这将用于填充其帐户信息。
  • 示例：mail

LDAP 通过 BindDN

添加以下字段

• Bind DN（可选）

  • 用于在搜索用户时与 LDAP 服务器绑定的 DN。可以留空以执行匿名搜索。
  • 示例：cn=Search,dc=mydomain,dc=com

• Bind 密码（可选）

  • 上面指定的 Bind DN 的密码（如果有）。注意：密码使用服务器上的 SECRET_KEY 进行加密存储。仍然建议确保 Bind DN 的权限尽可能少。

• 用户搜索基础 （必需）

  • 将在其中搜索用户帐户的 LDAP 基础。
  • 示例：ou=Users,dc=mydomain,dc=com

• 用户过滤器 （必需）

  • 声明如何找到尝试进行身份验证的用户记录的 LDAP 过滤器。%[1]s 匹配参数将被登录表单上提供的登录名替换。
  • 示例：(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))
  • Microsoft Active Directory (AD) 的示例：(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))
  • 要替换多次，应使用 %[1]s，例如，当匹配提供的登录名与多个属性（例如用户标识符、电子邮件甚至电话号码）时。
  • 示例：(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))

• 启用用户同步

  • 此选项启用定期任务，该任务将 Gitea 用户与 LDAP 服务器同步。默认周期为每 24 小时，但可以在 app.ini 文件中更改。有关该部分的详细说明，请参阅 示例 app.ini 中的cron.sync_external_users 部分。上面描述的用户搜索基础和用户过滤器设置将限制哪些用户可以使用 Gitea 以及哪些用户将被同步。首次运行时，该任务将创建与给定设置匹配的所有 LDAP 用户，因此在使用大型企业 LDAP 目录时要小心。

使用简单身份验证的 LDAP

添加以下字段

• 用户 DN （必需）

  • 用作用户 DN 的模板。%s 匹配参数将被登录表单上提供的登录名替换。
  • 示例：cn=%s,ou=Users,dc=mydomain,dc=com
  • 示例：uid=%s,ou=Users,dc=mydomain,dc=com

• 用户搜索基础（可选）

  • 将在其中搜索用户帐户的 LDAP 基础。
  • 示例：ou=Users,dc=mydomain,dc=com

• 用户过滤器 （必需）

  • 声明何时允许用户登录的 LDAP 过滤器。%[1]s 匹配参数将被登录表单上提供的登录名替换。
  • 示例：(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))
  • 示例：(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))

验证 LDAP 中的组成员身份

使用以下字段

• 组搜索基础 DN（可选）

  • 用于组的 LDAP DN。
  • 示例：ou=group,dc=mydomain,dc=com

• 包含用户列表的组属性（可选）

  • 列出/包含组成员的组对象的属性。
  • 示例：memberUid 或 member

• 在组中列出的用户属性（可选）

  • 用于在组对象中引用用户的用户属性。
  • 示例：如果组对象包含 member: bender 且用户对象包含 uid: bender，则为 uid。
  • 示例：如果组对象包含 member: uid=bender,ou=users,dc=planetexpress,dc=com，则为 dn。

• 验证 LDAP 中的组成员身份（可选）

  • 声明如何找到上述 DN 中的有效组的 LDAP 过滤器。
  • 示例：(|(cn=gitea_users)(cn=admins))

PAM（可插拔身份验证模块）

此过程启用 PAM 身份验证。用户仍然可以通过用户管理手动添加到系统中。PAM 提供了一种机制，通过针对 PAM 身份验证测试用户来自动将用户添加到当前数据库。要使用正常的 Linux 密码，运行 Gitea 的用户还必须具有对 /etc/shadow 的读取权限，以便在使用公钥登录时检查帐户的有效性。

注意：如果用户已将 SSH 公钥添加到 Gitea，则使用这些密钥可能会绕过登录检查系统。因此，如果您希望禁用使用 PAM 进行身份验证的用户，您应该也使用内置用户管理器手动禁用 Gitea 中的帐户。

1. 配置和准备安装。
   • 建议您创建一个管理员用户。
   • 可能还需要取消选择自动注册。
2. 数据库初始化后，以新创建的管理员用户身份登录。
3. 导航到用户设置（右上角的图标），选择 站点管理 -> 身份验证源，然后选择 添加身份验证源。
4. 填写以下字段
   • 身份验证类型 : PAM
   • 名称 : 任何值在此处都应有效，如果您愿意，请使用“系统身份验证”。
   • PAM 服务名称 : 选择 /etc/pam.d/ 下列出的执行所需身份验证的适当文件。¹
   • PAM 电子邮件域 : 要附加到用户身份验证的电子邮件后缀。例如，如果登录系统期望一个名为 gituser 的用户，并且此字段设置为 mail.com，那么 Gitea 将期望已验证的 GIT 实例的 用户电子邮件 字段为 [email protected]。²

注意：PAM 支持通过 构建时标志 添加，提供的官方二进制文件未启用此功能。PAM 要求必要的 libpam 动态库可用，并且编译器可以访问必要的 PAM 开发头文件。

SMTP（简单邮件传输协议）

此选项允许 Gitea 以 Gitea 用户身份登录 SMTP 主机。要配置此选项，请设置以下字段

• 身份验证名称 （必需）

  • 分配给新授权方法的名称。

• SMTP 身份验证类型 （必需）

  • 用于连接到 SMTP 主机的身份验证类型，PLAIN 或 LOGIN。

• 主机 （必需）

  • SMTP 主机可达的地址。
  • 例如：smtp.mydomain.com

• 端口 （必需）

  • 连接到服务器时使用的端口。
  • 例如：587

• 允许的域名

  • 如果使用公共 SMTP 主机或具有多个域的 SMTP 主机，则限制哪些域名可以登录。
  • 例如：gitea.com,mydomain.com,mydomain2.com

• 强制使用 SMTPS

  • 如果要使用 SMTPS 连接到其他端口，则默认情况下将对端口 465 的连接使用 SMTPS。设置此值。
  • 否则，如果服务器提供 STARTTLS 扩展，则将使用此扩展。

• 跳过 TLS 验证

  • 在身份验证时禁用 TLS 验证。

• 此身份验证来源已激活

  • 启用或禁用此身份验证来源。

FreeIPA

• 为了使用 FreeIPA 凭据登录 Gitea，需要为 Gitea 创建一个绑定帐户。

• 在 FreeIPA 服务器上，创建一个 gitea.ldif 文件，将 dc=example,dc=com 替换为您的 DN，并提供一个足够安全的密码。

  dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
  changetype: add
  objectclass: account
  objectclass: simplesecurityobject
  uid: gitea
  userPassword: secure password
  passwordExpirationTime: 20380119031407Z
  nsIdleTimeout: 0

• 导入 LDIF（如果需要，将 localhost 更改为 IPA 服务器）。将提示输入目录管理器密码。

  ldapmodify -h localhost -p 389 -x -D \
  "cn=Directory Manager" -W -f gitea.ldif

• 为 gitea_users 添加一个 IPA 组。

  ipa group-add --desc="Gitea Users" gitea_users

• 注意：对于有关 IPA 凭据的错误，请运行 kinit admin 并提供域管理员帐户密码。

• 以管理员身份登录 Gitea，然后在“管理面板”下单击“身份验证”。然后单击 添加新的来源 并填写详细信息，并在适当的地方更改所有内容。

带有 SSPI 的 SPNEGO（Kerberos/NTLM，仅限 Windows）

Gitea 通过 Windows 中内置的安全支持提供程序接口 (SSPI) 支持 SPNEGO 单点登录身份验证（RFC4559 定义的方案），用于服务器的 Web 部分。SSPI 仅在 Windows 环境中有效 - 当服务器和客户端都在运行 Windows 时。

在激活 SSPI 单点登录身份验证 (SSO) 之前，您需要准备环境。

• 在活动目录中创建一个单独的用户帐户，gitea.exe 进程将在该帐户下运行（例如，user 在域 domain.local 下）。

• 为运行 gitea.exe 的主机创建一个服务主体名称，类为 HTTP。

  • 以特权域用户 (例如，域管理员) 身份启动 命令提示符 或 PowerShell。
  • 运行以下命令，将 host.domain.local 替换为运行 Web 应用程序的服务器的完全限定域名 (FQDN)，将 domain\user 替换为在上一步中创建的帐户的名称。

  setspn -A HTTP/host.domain.local domain\user

• 使用创建的用户登录（如果您已登录，请注销）。

• 确保 custom/conf/app.ini 中的 [server] 部分中的 ROOT_URL 是运行 Web 应用程序的服务器的完全限定域名 - 与创建服务主体名称时使用的域名相同（例如，host.domain.local）。

• 启动 Web 服务器 (gitea.exe web)。

• 在 站点管理 -> 身份验证来源 中添加 带有 SSPI 的 SPNEGO 身份验证来源，以启用 SSPI 身份验证。

• 使用任何域用户登录到同一域中的客户端计算机（客户端计算机，与运行 gitea.exe 的服务器不同）。

• 如果您使用的是 Chrome 或 Edge，请将 Web 应用程序的 URL 添加到本地 Intranet 站点（Internet 选项 -> 安全 -> 本地 Intranet -> 站点）。

• 启动 Chrome 或 Edge，然后导航到 Gitea 的 FQDN URL（例如，http://host.domain.local:3000）。

• 单击仪表板上的 登录 按钮，然后选择 SSPI，以便使用当前登录到计算机的相同用户自动登录。

• 如果它不起作用，请确保

  • 您没有在运行 Gitea 的同一服务器上运行 Web 浏览器。您应该在与服务器不同的域加入计算机（客户端）上运行 Web 浏览器。如果客户端和服务器都在同一台计算机上运行，则 NTLM 将优先于 Kerberos。
  • 主机只有一个 HTTP/... SPN。
  • SPN 仅包含主机名，不包含端口。
  • 您已将 Web 应用程序的 URL 添加到 本地 Intranet 区域。
  • 服务器和客户端的时钟差异不应超过 5 分钟（取决于组策略）。
  • Internet Explorer 中应启用 集成 Windows 身份验证（在 高级设置 下）。

反向代理

Gitea 支持反向代理标头身份验证，它将读取标头作为受信任的登录用户名或用户电子邮件地址。默认情况下，此功能未启用，您可以使用以下方法启用它。

[service]
ENABLE_REVERSE_PROXY_AUTHENTICATION = true

默认登录用户名位于 X-WEBAUTH-USER 标头中，您可以通过更改 app.ini 中的 REVERSE_PROXY_AUTHENTICATION_USER 来更改它。如果用户不存在，您可以使用 ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true 启用自动注册。

默认登录用户电子邮件为 X-WEBAUTH-EMAIL，您可以通过更改 app.ini 中的 REVERSE_PROXY_AUTHENTICATION_EMAIL 来更改它，也可以使用 ENABLE_REVERSE_PROXY_EMAIL 禁用它。

如果设置 ENABLE_REVERSE_PROXY_FULL_NAME=true，则自动创建用户时，将为用户分配 X-WEBAUTH-FULLNAME 中预期用户的全名。您也可以使用 REVERSE_PROXY_AUTHENTICATION_FULL_NAME 更改标头名称。

您也可以使用 REVERSE_PROXY_TRUSTED_PROXIES 限制反向代理的 IP 地址范围，其默认值为 127.0.0.0/8,::1/128。通过 REVERSE_PROXY_LIMIT，您可以限制受信任的代理级别。

注意

反向代理身份验证不支持 API。您仍然需要访问令牌或基本身份验证才能进行 API 请求。

脚注

1. 例如，在 Debian “Bullseye” 上使用标准 Linux 登录，请使用 common-session-noninteractive - 此值可能对 Debian 的其他版本（包括 Ubuntu 和 Mint）有效，请参阅您发行版的文档。↩

2. 这是 PAM 的必填字段。请注意：在上面的示例中，用户将以 gituser 而不是 [email protected] 的身份登录 Gitea Web 界面。↩