> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/on-premises/zh-tw/she-ding/overleaf-toolkit/authentication/oidc-authentication.md).

# OIDC 驗證

此功能由 [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep)。這裡提供一些文件供您的設定參考。

### 設定

在內部，Overleaf OIDC 模組使用 [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect) 函式庫。如果你在設定 OpenID Connect 時遇到問題，值得閱讀 `passport-openidconnect` 了解它預期的設定方式。

環境變數 `EXTERNAL_AUTH` 是啟用 OIDC 驗證模組所必須的。這個環境變數指定已啟用哪些外部驗證方法。此變數的值是一個列表。若該列表包含 `oidc` 則會啟用 OIDC 驗證。

例如： `EXTERNAL_AUTH=ldap oidc`

使用 OIDC 驗證方法時，使用者會被重新導向至身分提供者（IdP）驗證網站。若 IdP 成功驗證使用者，系統會在 Overleaf 使用者資料庫中查找包含 `thirdPartyIdentifiers` 欄位，其結構如下：

```
thirdPartyIdentifiers: [
  {
    externalUserId: "...",
    externalData: null,
    providerId: "..."
  }
]
```

此 `externalUserId` 必須與 IdP 伺服器回傳的設定檔中的使用者 ID 相符（請參閱 `OVERLEAF_OIDC_USER_ID_FIELD` 環境變數），並且 `providerId` 必須與 OIDC 提供者的 ID 相符（請參閱 `OVERLEAF_OIDC_PROVIDER_ID`).

如果找不到相符的記錄，系統會在資料庫中搜尋其主要電子郵件地址與 IdP 使用者設定檔中的電子郵件相符的使用者：

* 如果找到這樣的使用者，則 `thirdPartyIdentifiers` 欄位會更新。
* 如果找不到相符的使用者，且未停用 JIT 帳號建立，系統會使用該電子郵件地址與 `thirdPartyIdentifiers` 來自 IdP 設定檔的資料建立新使用者。

在這兩種情況下，該使用者都被視為已與外部 OIDC 使用者「連結」。使用者可在 `/user/settings` 頁面。

#### 環境變數

以下五個必要變數的值可透過 `.well-known/openid-configuration` 你的 OpenID 提供者（OP）端點找到。

* `OVERLEAF_OIDC_ISSUER` **（必填）**
* `OVERLEAF_OIDC_AUTHORIZATION_URL` **（必填）**
* `OVERLEAF_OIDC_TOKEN_URL` **（必填）**
* `OVERLEAF_OIDC_USER_INFO_URL` **（必填）**
* `OVERLEAF_OIDC_LOGOUT_URL` **（必填）**

以下兩個必要變數的值將由你的 OP 管理員提供

* `OVERLEAF_OIDC_CLIENT_ID` **（必填）**
* `OVERLEAF_OIDC_CLIENT_SECRET` **（必填）**
* `OVERLEAF_OIDC_SCOPE`
  * 預設： `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * OP 的任意 ID，預設為 `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * OP 的名稱，用於 `已連結帳號` 中的 `/user/settings` 頁面，預設為 `OIDC 提供者`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * 身分服務的顯示名稱，用於登入頁面（預設： `使用 $OVERLEAF_OIDC_PROVIDER_NAME 登入`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * OP 的描述，用於 `已連結帳號` 區段（預設： `使用 $OVERLEAF_OIDC_PROVIDER_NAME 登入`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * `了解更多` OP 描述中的 URL，預設：無 `了解更多` 描述中不顯示連結。
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * 如果使用者的帳號未與 OP 連結，則不要在 `/user/settings` 頁面上顯示 OP，預設 `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * 此屬性的值將由 Overleaf 用作外部使用者 ID，預設為 `id`。其他可能合理的值包括 `email` 以及 `使用者名稱` （對應於 `preferred_username` OIDC 聲明）。
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * 限制透過 OIDC 驗證的使用者的即時（JIT）帳號建立。若設定為以逗號分隔的網域名稱清單，只有當使用者電子郵件地址的網域與清單中的某個網域相符時，才會建立新帳號。若網域不相符，管理員必須使用 OIDC 使用者的電子郵件地址手動建立使用者帳號，並搭配強隨機密碼，或更理想地，不使用 `hashedPassword` 欄位。網域名稱可以包含前導 `*.` 萬用字元以比對子網域。
    * 範例：若要允許電子郵件地址如下的使用者建立 JIT 帳號，例如 `name@example.com` 以及 `name@math.example.com`:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * 範例：若要完全停用 JIT 帳號建立：\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * 若設為 `true`，登入時會更新使用者的 `first_name` 以及 `last_name` 欄位，並停用使用者詳細資料表單於 `/user/settings` 頁面。
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` 以及 `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * 當這兩個環境變數都設定時，登入程序會更新 `user.isAdmin = true` 如果 OP 回傳的設定檔包含由 `OVERLEAF_OIDC_IS_ADMIN_FIELD` 指定的屬性，且其值符合 `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`，否則 `user.isAdmin` 會設為 `false`。如果 `OVERLEAF_OIDC_IS_ADMIN_FIELD` 是 `email` 則該屬性的值 `emails[0].value` 會用於比對檢查。

你的 OpenID 提供者重新導向 URL 為 `https://my-overleaf-instance.com/oidc/login/callback`.

<details>

<summary>範例 variables.env 檔案</summary>

{% code title="variables.env" overflow="wrap" %}

```dotenv
OVERLEAF_APP_NAME="Our Overleaf Instance"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# 啟用使用 ImageMagick 生成縮圖
ENABLE_CONVERSIONS=true

# 停用電子郵件確認需求
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## 透過 nginx-proxy 設定 TLS
# 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": "聯絡您的支援團隊", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"哈囉，我在右側", "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=此系統由 x 部門營運

OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true

#################
## CE 的 OIDC ##
#################

EXTERNAL_AUTH=oidc

OVERLEAF_OIDC_PROVIDER_ID=oidc
OVERLEAF_OIDC_ISSUER=https://keycloak.provider.com/realms/example
OVERLEAF_OIDC_AUTHORIZATION_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/auth
OVERLEAF_OIDC_TOKEN_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/token
OVERLEAF_OIDC_USER_INFO_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/userinfo
OVERLEAF_OIDC_LOGOUT_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/logout
OVERLEAF_OIDC_CLIENT_ID=Overleaf-OIDC
OVERLEAF_OIDC_CLIENT_SECRET=DoNotUseThisATGgaAcTgCcATgGATTACAagGtTCaGcGTAG
OVERLEAF_OIDC_IDENTITY_SERVICE_NAME='使用 Keycloak OIDC 提供者登入'
OVERLEAF_OIDC_PROVIDER_NAME=OIDC Keycloak 提供者
OVERLEAF_OIDC_PROVIDER_INFO_LINK=https://openid.net
OVERLEAF_OIDC_IS_ADMIN_FIELD=email
OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=overleaf.admin@example.com
OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=false
```

{% endcode %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/on-premises/zh-tw/she-ding/overleaf-toolkit/authentication/oidc-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.