> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# LDAP 驗證
此功能由 [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep) 開發。我們在此提供一些文件，供你進行設定時參考。
Overleaf 使用 **passport-ldapauth** 函式庫，該函式庫相對老舊，因此無法完全保證 LDAP 的相容性。使用某些 LDAP 身分提供者（例如 [https://goauthentik.io/](https://goauthentik.io/)）時，可能會發生登入失敗的情況。因此，如果可行，建議優先使用 OAuth/SAML 方式。若使用 goauthentik，請依照下方已經過測試的[逐步教學：goauthentik](/zh-TW/on-premises/configuration/overleaf-toolkit/authentication/ldap-authentication)進行設定。
### 什麼是 LDAP
LDAP 是一種用於外部身分驗證的驗證協定。Overleaf Server Pro 在網頁介面中提供了專用的 LDAP 登入表單，與標準驗證方式分開。當使用者送出其 LDAP 使用者名稱與密碼時，Overleaf 後端會向已設定的 LDAP 伺服器（例如 `ldap://ldap:10389`）驗證這些憑證。
### 設定
在內部，Overleaf LDAP 使用 [passport-ldapauth](https://github.com/vesse/passport-ldapauth) 函式庫。這些設定選項大多會傳遞給 `server` 設定物件，用於設定 `passport-ldapauth`。如果你在設定 LDAP 時遇到問題，建議閱讀 `passport-ldapauth` 的 README，以了解它所預期的設定方式。
啟用 LDAP 驗證模組需要設定環境變數 `EXTERNAL_AUTH`。此環境變數指定要啟用哪些外部驗證方式，其值為一個清單。若清單中包含 `ldap`，就會啟用 LDAP 驗證。
例如：`EXTERNAL_AUTH=ldap saml`
與 Overleaf CEP 不同，在我們的 ayaka-notes 版本中，LDAP 驗證被限制為純粹的驗證方式，可透過 `http://your-overleaf.com/ldap/login` 使用。
使用 LDAP 驗證方式時，使用者在登入表單中輸入 `username` 與 `password` 後，系統會嘗試：
1. 使用 `OVERLEAF_LDAP_SEARCH_FILTER` 所定義的篩選條件，在 LDAP 目錄中搜尋 LDAP 使用者並進行驗證。
2. 若驗證成功，系統會在 Overleaf 使用者資料庫中，尋找主要電子郵件地址與已驗證 LDAP 使用者電子郵件地址相符的使用者：
* 若找到相符的使用者，會刪除該使用者的 `hashedPassword` 欄位（若存在）。這可確保該使用者日後只能透過 LDAP 驗證登入。
* 若未找到相符的使用者，會使用從 LDAP 伺服器取得的電子郵件、名字與姓氏建立新的 Overleaf 使用者。
對於透過 LDAP 登入的使用者，我們不會在 Overleaf 的 mongo 資料庫中儲存雜湊密碼（且會移除既有的雜湊密碼）。
#### 環境變數
* `OVERLEAF_LDAP_URL` （必填）
* LDAP 伺服器的 URL。
* 範例：`ldaps://ldap.example.com:636`（LDAP over SSL）
* 範例：`ldap://ldap.example.com:389`（未加密，或在已設定的情況下使用 STARTTLS）。
* `OVERLEAF_LDAP_IDENTITY_SERVICE_NAME`
* LDAP 身分服務的顯示名稱，用於登入頁面。
* 預設為 `Log in with LDAP Provider`。
* `OVERLEAF_LDAP_EMAIL_ATT`
* LDAP 伺服器回傳的電子郵件屬性，預設為 `mail`。每個 LDAP 使用者都必須至少有一個電子郵件地址。若提供了多個地址，只會使用第一個。
* `OVERLEAF_LDAP_FIRST_NAME_ATT`
* 存放使用者名字（first name）的屬性名稱，供應用程式使用，通常為 `givenName`。
* `OVERLEAF_LDAP_LAST_NAME_ATT`
* 存放使用者姓氏的屬性名稱，供應用程式使用，通常為 `sn`。
* `OVERLEAF_LDAP_NAME_ATT`
* 存放使用者全名的屬性名稱，通常為 `cn`。若前兩個變數中任一個未定義，使用者的名字及/或姓氏會從此變數中擷取；否則不會使用此變數。
* `OVERLEAF_LDAP_PLACEHOLDER`
* 登入表單的預留位置文字，預設為 `Username`。
* `OVERLEAF_LDAP_UPDATE_USER_DETAILS_ON_LOGIN`
* 若設為 `true`，會在登入時更新 LDAP 使用者的 `first_name` 與 `last_name` 欄位，並為 LDAP 使用者關閉 `/user/settings` 頁面上的使用者詳細資料表單。否則，詳細資料只會在首次登入時取得。
* `OVERLEAF_LDAP_BIND_DN`
* 用於 LDAP 連線的 LDAP 使用者辨別名稱（distinguished name，此使用者應能在 LDAP 伺服器上搜尋/列出帳號），例如 `cn=ldap_reader,dc=example,dc=com`。若未定義，則使用匿名繫結。
* `OVERLEAF_LDAP_BIND_CREDENTIALS`
* `OVERLEAF_LDAP_BIND_DN` 的密碼。
* `OVERLEAF_LDAP_BIND_PROPERTY`
* 用於與用戶端繫結的使用者屬性，預設為 `dn`。
* `OVERLEAF_LDAP_SEARCH_BASE` （必填）
* 搜尋使用者時的基礎 DN，例如 `ou=people,dc=example,dc=com`。
* `OVERLEAF_LDAP_SEARCH_FILTER`
* 用於尋找使用者的 LDAP 搜尋篩選條件。使用字面值 '\{\{username}}'，即可在 LDAP 搜尋中代入使用者輸入的使用者名稱。
* 範例：`(|(uid={{username}})(mail={{username}}))`（使用者可使用電子郵件或登入名稱登入）。
* 範例：`(sAMAccountName={{username}})`（Active Directory）。
* `OVERLEAF_LDAP_SEARCH_SCOPE`
* 搜尋範圍，可以是 `base`、`one` 或 `sub`（預設）。
* `OVERLEAF_LDAP_SEARCH_ATTRIBUTES`
* 要從 LDAP 伺服器擷取的屬性 JSON 陣列，例如 `["uid", "mail", "givenName", "sn"]`。預設會擷取所有屬性。
* `OVERLEAF_LDAP_STARTTLS`
* 若為 `true`，則使用 LDAP over TLS。
* `OVERLEAF_LDAP_TLS_OPTS_CA_PATH`
* 用於驗證 LDAP 伺服器 SSL/TLS 憑證的 CA 憑證檔案路徑。若有多個憑證，可以是由憑證路徑組成的 JSON 陣列。這些檔案必須可供 Docker 容器存取。
* 範例（單一憑證）：`/var/lib/overleaf/certs/ldap_ca_cert.pem`
* 範例（多個憑證）：`["/var/lib/overleaf/certs/ldap_ca_cert1.pem", "/var/lib/overleaf/certs/ldap_ca_cert2.pem"]`
* `OVERLEAF_LDAP_TLS_OPTS_REJECT_UNAUTH`
* 若為 `true`，會根據所提供的 CA 清單驗證伺服器憑證。
* `OVERLEAF_LDAP_CACHE`
* 若為 `true`，則一次最多會快取 100 組憑證，快取時間為 5 分鐘。
* `OVERLEAF_LDAP_TIMEOUT`
* 用戶端在操作逾時前允許其持續的時間，單位為毫秒（預設：Infinity）。
* `OVERLEAF_LDAP_CONNECT_TIMEOUT`
* 用戶端在 TCP 連線逾時前應等待的時間，單位為毫秒（預設：作業系統預設值）。
* `OVERLEAF_LDAP_IS_ADMIN_ATT` 與 `OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE`
* 當這兩個環境變數都有設定時，若 LDAP 個人資料中包含 `OVERLEAF_LDAP_IS_ADMIN_ATT` 所指定的屬性，且其值與 `OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE` 相符，或為包含 `OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE` 的陣列，登入流程就會將 `user.isAdmin` 更新為 `true`；否則 `user.isAdmin` 會設為 `false`。若其中任一變數未設定，則管理員狀態只會在 Launchpad 建立管理員使用者時設為 `true`。
以下五個變數用於設定如何從 LDAP 伺服器擷取使用者聯絡人。
* `OVERLEAF_LDAP_CONTACTS_FILTER`
* 用於在 LDAP 伺服器中搜尋要載入至聯絡人的使用者的篩選條件。篩選條件中的預留位置 '\{\{userProperty}}' 會被替換為發起搜尋之 LDAP 使用者的 `OVERLEAF_LDAP_CONTACTS_PROPERTY` 所指定屬性的值。若未定義，則不會從 LDAP 伺服器擷取任何使用者至聯絡人。
* `OVERLEAF_LDAP_CONTACTS_SEARCH_BASE`
* 指定開始搜尋聯絡人的基礎 DN。預設為 `OVERLEAF_LDAP_SEARCH_BASE`。
* `OVERLEAF_LDAP_CONTACTS_SEARCH_SCOPE`
* 搜尋範圍，可以是 `base`、`one` 或 `sub`（預設）。
* `OVERLEAF_LDAP_CONTACTS_PROPERTY`
* 指定使用者物件中，用來替換 `OVERLEAF_LDAP_CONTACTS_FILTER` 裡 '\{\{userProperty}}' 預留位置的屬性。
* `OVERLEAF_LDAP_CONTACTS_NON_LDAP_VALUE`
* 指定當搜尋由非 LDAP 使用者發起時，`OVERLEAF_LDAP_CONTACTS_PROPERTY` 所使用的值。若未定義此變數，產生的篩選條件將不會符合任何項目。可使用 `*` 作為萬用字元。
```text theme={null}
OVERLEAF_LDAP_CONTACTS_FILTER=(gidNumber={{userProperty}})
OVERLEAF_LDAP_CONTACTS_PROPERTY=gidNumber
OVERLEAF_LDAP_CONTACTS_NON_LDAP_VALUE=1000
```
上述範例會將所有與目前 LDAP 使用者具有相同 UNIX `gid` 的 LDAP 使用者，載入至該使用者的聯絡人中。非 LDAP 使用者的聯絡人中則會包含所有 UNIX `gid=1000` 的 LDAP 使用者。
```text theme={null}
OVERLEAF_APP_NAME="Our Overleaf Instance"
ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url
# Enables Thumbnail generation using ImageMagick
ENABLE_CONVERSIONS=true
# Disables email confirmation requirement
EMAIL_CONFIRMATION_DISABLED=true
## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768
## Set for TLS via nginx-proxy
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true
OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=Our Overleaf Instance
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
OVERLEAF_ADMIN_EMAIL=support@example.com
OVERLEAF_LEFT_FOOTER=[{"text": "Contact your support team", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Hello, I am on the Right", "url":"https://github.com/yu-i-i/overleaf-cep"}]
OVERLEAF_EMAIL_FROM_ADDRESS=team@example.com
OVERLEAF_EMAIL_SMTP_HOST=smtp.example.com
OVERLEAF_EMAIL_SMTP_PORT=587
OVERLEAF_EMAIL_SMTP_SECURE=false
# OVERLEAF_EMAIL_SMTP_USER=
# OVERLEAF_EMAIL_SMTP_PASS=
# OVERLEAF_EMAIL_SMTP_NAME=
OVERLEAF_EMAIL_SMTP_LOGGER=false
OVERLEAF_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
OVERLEAF_EMAIL_SMTP_IGNORE_TLS=false
OVERLEAF_CUSTOM_EMAIL_FOOTER=This system is run by department x
OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true
#################
## LDAP for CE ##
#################
EXTERNAL_AUTH=ldap
OVERLEAF_LDAP_URL=ldap://ldap.example.com:389
OVERLEAF_LDAP_STARTTLS=true
OVERLEAF_LDAP_TLS_OPTS_CA_PATH=/var/lib/overleaf/certs/ldap_ca_cert.pem
OVERLEAF_LDAP_SEARCH_BASE=ou=people,dc=example,dc=com
OVERLEAF_LDAP_SEARCH_FILTER=(|(uid={{username}})(mail={{username}}))
OVERLEAF_LDAP_BIND_DN=cn=ldap_reader,dc=example,dc=com
OVERLEAF_LDAP_BIND_CREDENTIALS=GoodNewsEveryone
OVERLEAF_LDAP_EMAIL_ATT=mail
OVERLEAF_LDAP_FIRST_NAME_ATT=givenName
OVERLEAF_LDAP_LAST_NAME_ATT=sn
# OVERLEAF_LDAP_NAME_ATT=cn
OVERLEAF_LDAP_SEARCH_ATTRIBUTES=["uid", "sn", "givenName", "mail"]
OVERLEAF_LDAP_UPDATE_USER_DETAILS_ON_LOGIN=true
OVERLEAF_LDAP_PLACEHOLDER='Username or email address'
OVERLEAF_LDAP_IS_ADMIN_ATT=mail
OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE=admin@example.com
OVERLEAF_LDAP_CONTACTS_FILTER=(gidNumber={{userProperty}})
OVERLEAF_LDAP_CONTACTS_PROPERTY=gidNumber
OVERLEAF_LDAP_CONTACTS_NON_LDAP_VALUE='*'
```
## 逐步教學：goauthentik
本節將逐步說明一套已在 [goauthentik](https://goauthentik.io/) 上測試過的設定。範例使用的 Base DN 為 `dc=example,dc=com`，請替換為你自己的值。
Overleaf 會先使用一個專屬帳號登入目錄，以尋找使用者。在 Authentik 中，開啟 **Directory > Users**，點選 **New User**，選擇 **Internal User** 後點選 **Next**。輸入使用者名稱，例如 `ldapservice`，然後點選 **Create**：
開啟新建立的使用者，點選 **Set password**。這組密碼要填入 `OVERLEAF_LDAP_BIND_CREDENTIALS`：
記下網址列中該使用者的編號，例如 `…/#/identity/users/19` 中的 `19`。第 3 步會用到它。
開啟 **Applications > Applications**，點選 **New Application**。精靈會同時建立應用程式及其提供者。
1\. 為應用程式指定名稱與 slug，例如 `overleaf-ldap`，然後點選 **Next**：
2\. 選擇 **LDAP Provider**，然後點選 **Next**：
3\. 將 **Bind Mode** 設為 **Direct binding**，**Search Mode** 設為 **Direct querying**：
4\. 往下捲動，將 **Bind Flow** 設為 `default-authentication-flow`，並將 **Base DN** 設為你的 Base DN，例如 `dc=example,dc=com`：
5\. 持續點選 **Next** 直到最後一頁，然後送出應用程式。
若沒有這項權限，綁定帳號只能看到自己，搜尋時找不到任何使用者，所有 LDAP 登入都會失敗。
開啟提供者，前往 **Permissions**，點選 **Assign Role Object Permission**。在 **Role** 中輸入第 1 步記下的編號，並選擇 `ak-managed-role--user-`，然後開啟 **Search full LDAP directory**：
之後該角色在 **Search full LDAP directory** 下方會顯示勾選標記：
Authentik 透過 outpost（一個獨立的容器）回應 LDAP 請求。開啟 **Applications > Outposts**，使用你的提供者建立一個類型為 **LDAP** 的 outpost，並依照 Authentik 的說明進行部署。它會監聽所在主機的 389 連接埠。連線成功後，會顯示綠色勾選標記：
```dotenv theme={null}
OVERLEAF_LDAP_URL=ldap://ldap.example.com:389
```
提供者頁面的 **How to connect** 下方會顯示 Base DN 與範例：
請勿直接照抄範例值：
* **Bind DN** 顯示的是你目前登入的帳號。請改用第 1 步建立的綁定帳號：`cn=ldapservice,ou=users,`。
* **Search base** 顯示的是 Base DN。請改用 `ou=users,`。
```dotenv theme={null}
OVERLEAF_LDAP_BIND_DN=cn=ldapservice,ou=users,dc=example,dc=com
OVERLEAF_LDAP_BIND_CREDENTIALS=
OVERLEAF_LDAP_SEARCH_BASE=ou=users,dc=example,dc=com
OVERLEAF_LDAP_SEARCH_FILTER=(cn={{username}})
```
Authentik 會在 `ou=virtual-groups` 下為每位使用者保留一個同名的群組。若在整個 Base DN 中搜尋 `(cn=alice)`，會同時找到 `cn=alice,ou=users,…` 與 `cn=alice,ou=virtual-groups,…`，而 Overleaf 會拒絕符合多筆項目的登入。請將搜尋基準保持為 `ou=users,`。
在啟動 Overleaf 之前，先執行它將要進行的搜尋。輸出中必須恰好只有一個 `dn:`：
```shell theme={null}
ldapsearch -x -H ldap://ldap.example.com:389 \
-D cn=ldapservice,ou=users,dc=example,dc=com -w '' \
-b ou=users,dc=example,dc=com '(cn=alice)' dn
```
如果完全沒有 `dn:`，通常表示缺少第 3 步的權限。
使用者所屬的群組位於 `memberOf` 中，以 `ou=groups` 下的 DN 表示。若要讓 Authentik 群組 `Admins` 的成員成為 Overleaf 的管理員：
```dotenv theme={null}
OVERLEAF_LDAP_IS_ADMIN_ATT=memberOf
OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE=cn=Admins,ou=groups,dc=example,dc=com
```
每次透過 LDAP 登入時都會更新管理員旗標。若屬性或值設定錯誤，所有透過 LDAP 登入的管理員都會失去管理員權限。請先使用第二個管理員帳號測試此對應設定。
```dotenv title="variables.env" wrap theme={null}
EXTERNAL_AUTH=ldap
OVERLEAF_LDAP_IDENTITY_SERVICE_NAME=Log in with Authentik
OVERLEAF_LDAP_URL=ldap://ldap.example.com:389
OVERLEAF_LDAP_BIND_DN=cn=ldapservice,ou=users,dc=example,dc=com
OVERLEAF_LDAP_BIND_CREDENTIALS=
OVERLEAF_LDAP_SEARCH_BASE=ou=users,dc=example,dc=com
OVERLEAF_LDAP_SEARCH_FILTER=(cn={{username}})
OVERLEAF_LDAP_EMAIL_ATT=mail
OVERLEAF_LDAP_NAME_ATT=name
OVERLEAF_LDAP_IS_ADMIN_ATT=memberOf
OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE=cn=Admins,ou=groups,dc=example,dc=com
OVERLEAF_LDAP_UPDATE_USER_DETAILS_ON_LOGIN=true
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.