GitLab LDAP 設定更新

修改 GitLab Omnibus 的 LDAP 認證設定並驗證連線的三步驟 SOP。

概述

GitLab 的 LDAP 設定集中在 /etc/gitlab/gitlab.rb 的 gitlab_rails['ldap_servers'] 區塊中，管理 AD（Active Directory）認證的相關參數，包括 LDAP Server 位址、Bind DN、Bind 密碼、Search Base 等。

常見需要更新 LDAP 設定的情境：

• 年度帳密輪替：Bind DN 帳號（如 assistant@wiwynn.com）的密碼異動
• LDAP Server 變更：AD Server IP 或 FQDN 異動
• 網段調整：LDAP Server 遷移到新網段後需更新連線位址

修改 gitlab.rb 後必須執行 gitlab-ctl reconfigure（而非只 restart），Omnibus 才會重新產生所有服務設定並套用 LDAP 變更。

核心內容

三步驟 SOP

步驟 1 — 修改設定檔：

sudo vi /etc/gitlab/gitlab.rb

找到 gitlab_rails['ldap_servers'] 區塊，修改對應的值（如 bind_dn、password、host）。

步驟 2 — 套用設定：

sudo gitlab-ctl reconfigure

reconfigure 會重新產生所有服務設定檔（包括 LDAP 設定），需要幾分鐘。

注意： 只執行 gitlab-ctl restart 不會套用 gitlab.rb 的變更，必須執行 reconfigure。

步驟 3 — 驗證 LDAP 連線：

sudo gitlab-rake gitlab:ldap:check[10]

此指令連線至 LDAP Server 並嘗試查詢前 10 筆使用者，確認設定正確且連線可用。

gitlab.rb LDAP 設定結構（參考）

gitlab_rails['ldap_enabled'] = true
gitlab_rails['prevent_ldap_sign_in'] = false

gitlab_rails['ldap_servers'] = {
  'main' => {
    'label' => 'LDAP',
    'host' =>  'wyhqadsrv01.wiwynn.corp',
    'port' => 389,
    'uid' => 'userPrincipalName',
    'bind_dn' => 'assistant@wiwynn.com',
    'password' => 'YOUR_LDAP_PASSWORD',
    'encryption' => 'plain',        # 'plain' / 'start_tls' / 'simple_tls'
    'verify_certificates' => true,
    'active_directory' => true,
    'base' => 'DC=wiwynn,DC=corp',
    'user_filter' => '',
    'attributes' => {
      'username' => ['userPrincipalName', 'uid', 'userid', 'sAMAccountName'],
      'email' => ['mail', 'email', 'userPrincipalName'],
      'name' => 'cn',
      'first_name' => 'givenName',
      'last_name' => 'sn',
    }
  }
}

關鍵要點

• 修改 gitlab.rb 後一律執行 gitlab-ctl reconfigure，不是 restart
• gitlab-rake gitlab:ldap:check[10] 是快速驗證 LDAP 連線的最佳工具
• 修改 Bind 密碼後，操作完成需清除 bash 歷史紀錄以防明文密碼殘留（history -c && rm ~/.bash_history）
• LDAP 設定更新是年度維運 SOP 的一部分，應與憑證輪替同步進行

實際應用

• 搭配 AAD / LDAP 查詢工具指南 先確認 LDAP bind 帳號有效再修改設定
• 年度 Bind 帳號密碼更換後，需同步更新此處與 PostgreSQL pg_hba.conf（詳見 維運 SOP：憑證與帳密更新）
• 若更新後 ldap:check 失敗，可先用 ldapsearch 手動測試 LDAP Server 連通性排查根因

部署設定參考

以下為實際部署時使用的完整指令，供日後查詢與複製使用。

環境參數

項目	值
GitLab 設定檔	/etc/gitlab/gitlab.rb
LDAP 設定區塊	gitlab_rails['ldap_servers']
GitLab Server IP	10.248.32.101
LDAP Server	wyhqadsrv01.wiwynn.corp（10.247.1.10）

操作指令

# 步驟 1：修改 LDAP 設定
sudo vi /etc/gitlab/gitlab.rb
# 修改 gitlab_rails['ldap_servers'] 區塊

# 步驟 2：套用設定（必須 reconfigure，不是 restart）
sudo gitlab-ctl reconfigure

# 步驟 3：驗證 LDAP 連線（回傳前 10 筆結果）
sudo gitlab-rake gitlab:ldap:check[10]

# 操作完成後清除含密碼的 bash 歷史
history -c && rm ~/.bash_history && exec bash

相關概念

• GitLab Omnibus (Docker) HTTPS 連線失敗排除 SOP — GitLab Server 的 SSL 設定與排錯，同樣需要 reconfigure
• AAD / LDAP 查詢工具指南 — 用 ldapsearch 直接測試 LDAP Server 連通性與帳號有效性
• 維運 SOP：憑證與帳密更新 — 涵蓋 GitLab LDAP 設定的年度維運完整 SOP

來源

• 原始素材：GitLab 更新 LDAP 設定